memory

name	memory
description	Use this skill as the default memory system for non-trivial work when task continuity or durable repo knowledge matters.

Memory

Use this skill for non-trivial coding work when task continuity or durable repo knowledge matters.

Use this practical distinction:

• trivial: one-shot work, low risk, no meaningful continuity needed, and no likely durable memory outcome
• non-trivial: repo state matters, prior context may matter, the task spans multiple steps or turns, or durable knowledge may emerge

As a rule of thumb, most implementation, debugging, review, refactor, migration, CI, deployment, storage, auth, schema, or architecture work in an existing repo is non-trivial.

Read First

• scripts/agent-memory.sh
• references/examples.md

What This Skill Adds

This skill is not a generic memory tutorial. It adds a portable local workflow that works identically across agents:

• one wrapper command that finds neo4j-agent-memory
• automatic .env loading when the tool repo provides one (OPENAI_API_KEY + OPENAI_BASE_URL)
• a mandatory preflight that detects sandbox network issues once per session
• a simple cadence: startup, milestone, finish
• clear, non-looping behavior when Neo4j is blocked by the sandbox

Wrapper First

The wrapper is exposed as agent-memory on PATH. Install once:

mkdir -p ~/.local/bin
ln -sf ~/.pi/agent/skills/memory/scripts/agent-memory.sh ~/.local/bin/agent-memory
# Ensure ~/.local/bin is on PATH

All commands in this skill use the bare agent-memory name. Do not hardcode absolute paths; they break across agents.

The wrapper resolves the binary in this order:

1. AGENT_MEMORY_BIN
2. AGENT_MEMORY_HOME/.venv/bin/neo4j-agent-memory
3. neo4j-agent-memory on PATH
4. common repo locations under ~/code, ~/src, and ~/projects

If a tool home is found, the wrapper loads its .env file automatically (which provides OPENAI_API_KEY and OPENAI_BASE_URL for the embedding provider).

Timeouts

Embeddings are generated via API (text-embedding-3-large via LiteLLM proxy). No local model cold-start.

Mandatory timeout rules:

Command	Minimum timeout
agent-memory doctor	10s (default)
agent-memory memory ... (any subcommand)	30s

Always pass an explicit timeout when running agent-memory memory commands:

agent-memory memory get-context --query "..." --include-long-term  # timeout 30s
agent-memory memory recall --repo X --task "..."                   # timeout 30s
agent-memory memory search --kind fact --query "..."               # timeout 30s

If a memory command times out, treat memory as degraded for the rest of the session. Do not retry in a loop.

Step 0 — Preflight (once per session)

Before the first memory ... call in a session, always ensure Neo4j is running, then run doctor:

# Auto-start Neo4j if not running (silent, no user prompt)
docker ps --filter "name=neo4j-agent-memory-test" --format '{{.Status}}' | grep -q "Up" || \
  (cd ~/code/led8/ai/spark/agent-memory && docker compose up -d && sleep 5)

agent-memory doctor

This is not optional — run the auto-start silently every time, don't ask the user.

Parse the output and act on it:

• binary: missing → memory is unavailable for this session. Continue the task without it and mention the unavailable state only if the final response needs that context. Do not retry.
• env_file: missing → the tool repo .env cannot be located. Continue, but be aware that NEO4J_URI, credentials, or embedder config may be wrong. Report once.
• memory_cli: failed → the binary exists but cannot run. Treat as unavailable for the session. Report once.
• neo4j_socket_127.0.0.1_7687: unreachable → the agent sandbox is blocking localhost. See Availability And Sandbox Policy below. Do not retry in a loop.
• All green → proceed with the normal workflow.

The preflight state is sticky for the session. If it fails, do not rerun doctor repeatedly and do not retry memory ... commands hoping for a different result. Report once, continue the task without memory.

Core Rules

1. Use one session_id per active coding task.
2. Use short-term selectively for task continuity, not raw shell logs.
3. Open reasoning traces only for multi-step or uncertain work.
4. Treat long-term memory as review-first.
5. Search or inspect before durable writes.
6. Use replace-fact and replace-preference when durable entries change.
7. Use update-entity, alias-entity, and merge-entity for same-identity entity maintenance.
8. Never inline literal secrets in commands or examples.
9. Always persist memory content in English — regardless of the conversation language. Memory must be searchable and reusable across sessions.

At each use, explicitly decide whether to:

• recall
• search
• get-context
• write to short-term
• update reasoning
• review a durable memory candidate
• or skip

This is a mandatory decision point, not a mandatory memory write.

Memory use is required in these situations, conditional on the preflight being green:

• at the start of non-trivial work in an existing repo: run the preflight (agent-memory doctor), then run startup recall once for the active task if the preflight is green
• when the user references prior work, earlier sessions, preferences, previous decisions, or known constraints
• before any durable memory write
• after a verified outcome that may help future runs
• at a meaningful stopping point: evaluate whether to update reasoning or persist durable knowledge

Keep responsibilities separate:

• .spark_utils/backlog/ and .spark_utils/todo/ — local planning and execution tracking (see the planning section of this file for details)
• agent-memory short-term — selective task-local continuity
• agent-memory reasoning — concise multi-step trace updates
• agent-memory long-term — durable facts, preferences, and entities

Quality rules:

• do not store every turn by default
• do not store backlog items, todo items, raw shell output, or speculative notes
• search or inspect before durable writes
• use get-provenance to check evidence chains before overwriting existing facts
• treat long-term memory as review-first
• never claim memory was recalled, searched, or stored unless the tool actually succeeded
• if memory retrieval returns nothing, say so and continue

Three Memory Layers

Short-Term

Use short-term for the active task stream:

• current user requests
• current assistant replies
• session-local observations needed during the task
• a few key tool-facing observations when they help the next step

Operational commands:

• add-message
• delete-message

Do not dump every shell command, every raw output block, or noisy scratch notes into short-term.

Reasoning

Use reasoning for non-trivial tasks:

• concise reusable trace steps
• tool calls and outcomes
• final success or failure summaries

Operational commands:

• start-trace
• add-trace-step
• add-tool-call
• complete-trace

Do not store noisy intermediate thinking.

Long-Term

Use long-term only for durable knowledge that should survive the task:

• facts for stable repo truths, constraints, and decisions
• preferences for durable workflow or communication preferences
• entities for important nouns worth linking and retrieving later

Operational commands:

• add-fact
• add-preference
• add-entity
• update-entity
• alias-entity
• merge-entity
• replace-fact
• replace-preference
• inspect
• search
• get-provenance
• delete

V2 candidate commands (opt-in):

• list-candidates
• accept-candidate
• ignore-candidate
• get-candidate

This layer is curated. It is review-first, not automatic.

Standard Workflow

1. Startup

Run the preflight first (see Step 0), then for the active task:

agent-memory memory session-id --repo <repo> --task "<task>"
agent-memory memory recall --repo <repo> --task "<task>" --session-id "<session-id>"

Use --include-provenance when you want each fact/preference annotated with its evidence source:

agent-memory memory recall --repo <repo> --task "<task>" --session-id "<session-id>" --include-provenance

Use startup recall as the anchor for non-trivial repo work.

2. Milestone

During the task, choose the smallest useful action:

• search for one fact, preference, entity, or message thread
• search --expand to also get graph neighbors (1-hop traversal) alongside vector results
• get-context for a compact combined view (includes project context + graph expansion automatically)
• add-message only when the turn materially helps continuity
• start-trace and complete-trace only for multi-step work

3. Finish

At a meaningful stopping point:

• update reasoning if the trace gained a useful result
• review durable memory candidates
• persist only validated durable knowledge
• update project cartography (see Project Cartography section below)

Long-Term Candidate Review

Use this exact structure before any durable write:

[Long-term candidate]
type: <fact|preference|entity>
scope: <repo|personal>
content: <durable memory candidate>
why: <why this is durable and reusable>
source: <user_explicit|code_verified|docs_verified|test_verified|run_observation>
confidence: <high|medium|low>
evidence: <short concrete evidence>
suggested_action: <remember_fact|remember_preference|remember_entity>
decision_needed: persist | ignore

A candidate is valid only when:

• the source is identifiable
• the information is likely durable beyond the current task
• the information is reusable by a future coding run
• the memory type is clear

confidence is a policy signal:

• high: durable, reusable, and backed by a strong source
• medium: promising but still mainly observation-driven
• low: too temporary or ambiguous to store

Use empirical discoveries when they are validated:

• a bug was reproduced, fixed, and verified
• repository behavior was confirmed by code or rerun
• a pattern worked better than the docs and the mismatch was confirmed
• an observation held across multiple runs

Practical rule:

• single observation: usually medium
• reproduced bug plus verified fix: often high
• doc mismatch: becomes high only after actual repo behavior is confirmed

Related Reference

• Use references/examples.md for short runnable command patterns.

Persistent Candidates (Optional)

When a candidate is worth persisting for later review (e.g., at the end of a long session with many candidates), use the persist_candidate pattern:

# Store a candidate in the graph for later review
# (This is opt-in — the default in-memory review-first workflow still works)
agent-memory memory list-candidates --status proposed
agent-memory memory accept-candidate <candidate-id>
agent-memory memory ignore-candidate <candidate-id>
agent-memory memory get-candidate <candidate-id>

Use persistent candidates when:

• a session produces multiple candidates that can't all be reviewed immediately
• you want to defer a review decision to the user
• the candidate confidence is medium and you want it visible in later sessions

Do not persist candidates by default. The in-memory review block remains the primary workflow.

Provenance Inspection

Before overwriting a high-value fact, inspect its evidence chain:

agent-memory memory get-provenance fact <fact-uuid>
agent-memory memory get-provenance preference <preference-uuid>

This returns the traces and messages that originally supported the entry. Use it when replace-fact might discard well-evidenced knowledge.

Project Cartography

The knowledge graph includes a Project Cartography Layer — structured nodes (Project, Module) representing local and external codebases. This enables cross-project knowledge navigation during recall.

How it works

• get-context automatically includes project context (vector search + 1-hop graph traversal of project relations)
• search --expand surfaces graph neighbors alongside primary vector results
• Project nodes store: name, purpose, stack, conventions, module map, and inter-project relations

When to update

Project cartography is updated at session end (/quit_session), just like other memory persistence:

# Scan the current project to update its index
agent-memory project scan <cwd>

This is fast (~2s) and keeps the project fresh for future sessions. Skip only if you did not modify or explore the project structure.

Batch operations (on-demand)

For full re-indexing or initial setup:

# Scan all known project trees
agent-memory project scan-all

# Scan all + LLM enrichment (purpose, roles, conventions)
agent-memory project scan-all --enrich

# Detect inter-project relations via LLM
agent-memory project relate

Operational commands

• project scan <path> — index a single project
• project scan-all — scan all configured trees, reconcile orphans
• project scan-all --enrich — scan + LLM enrichment
• project list — list all indexed projects
• project show <name> — show project details + modules + relations
• project add-external <name> --repo-url <url> — add an external project (e.g., from DeepWiki)
• project relate — detect and persist inter-project relations via LLM

Graph expansion

get-context and search --expand traverse these relationships:

Relation	What it surfaces
MENTIONS (Fact→Entity)	Extra facts that reference found entities
RELATED_TO (Entity→Entity)	Connected entities (when edges exist)
DISCOVERED_IN (Fact→Project)	Which project a fact came from
RELATES_TO (GraphLinker)	Semantically similar nodes across all types
SUPERSEDED_BY (Fact→Fact)	Filters out obsolete facts (shows only latest)
PROJECT_RELATES_TO	Related projects (DEPENDS_ON, CONSUMES_API, etc.)