agentmemory — Workflow

Phase Overview

agentmemory's workflow is event-driven rather than task-phase-driven. The system operates as a background capture-and-recall loop, not a sequential planning pipeline.

Session Start
    ↓
[SessionStart hook] → register session, optionally inject prior context
    ↓
Active Work Loop:
  [UserPromptSubmit hook] → pre-process prompt
  [PreToolUse hook] → capture intent (Edit|Write|Read|Glob|Grep)
  [PostToolUse hook] → observe tool output → mem::observe
  [PostToolUseFailure hook] → record errors for pattern detection
    ↓
[SubagentStart/Stop] → track sub-agent spawning in session graph
[TaskCompleted hook] → record task milestones
[Notification hook] → handle async agent notifications
    ↓
Pre-Compaction Gate:
  [PreCompact hook] → claude-bridge sync + inject compressed context
    ↓
Session End:
  [Stop hook] → trigger compression + summarization
  [SessionEnd hook] → final state flush

Observation Pipeline

Raw events from hooks flow into mem::observe (registered via registerObserveFunction):

1. Hook fires → sends HookPayload to REST API at POST /agentmemory/observe
2. Privacy stripping (stripPrivateData) removes credentials/secrets
3. Dedup check via DedupMap — Jaccard similarity prevents near-duplicate observations
4. Observation stored in mem:obs:{sessionId} (iii-engine KV)
5. If AUTO_COMPRESS_ENABLED: async LLM compression → creates CompressedObservation
6. BM25 index + vector embedding computed and stored
7. Graph extraction (if GRAPH_EXTRACTION_ENABLED=true): entity/relation extraction via LLM

Context Injection

Two paths for injecting past context:

SessionStart injection (opt-in): set AGENTMEMORY_INJECT_CONTEXT=true. The session-start hook POSTs to /agentmemory/session/start and writes the returned context string to stdout — Claude Code reads it as the first system message of the session.

PreCompact injection: Before Claude Code compacts the context window, the hook POSTs to /agentmemory/context, which returns a compressed summary of the session's observations. This survives context window resets.

Recall Flow

When the /recall skill is invoked or the agent calls memory_smart_search:

1. Query → hybrid search: BM25 (token overlap) + vector similarity (all-MiniLM-L6-v2 embeddings) + graph traversal (entity expansion)
2. Results ranked by combined score
3. Filtered by project cwd (unless AGENT_SCOPE_ISOLATED=false)
4. Returned as observations grouped by session with importance scores
5. Agent presents results; high-importance (≥7) observations highlighted

Compression / Crystallization Pipeline

Long-term memory consolidation:

• Auto-compress: LLM-driven observation compression (background)
• Consolidate (memory_consolidate): merge related observations
• Crystallize (memory_crystallize): promote patterns into permanent mem:crystals entries
• Sketch → Promote (memory_sketch_create / memory_sketch_promote): scratch-pad patterns promoted to crystals after validation

Handoff Protocol

Using the /handoff skill at session start:

1. memory_sessions called → returns sessions with cwd metadata
2. Directory-boundary matching: session.cwd equals projectPath OR one is prefix of the other with a separator boundary (prevents false positives like /repo-a matching /repo-a-staging)
3. Most recent completed session preferred over abandoned
4. Unanswered user-facing questions (observations with type conversation ending in ?) surfaced first
5. Key files, decisions, errors summarized; memory_recall called for supporting observations

Team Memory Sharing

memory_team_share posts to mem:team:{teamId}:shared. memory_team_feed pulls the shared pool. All team members' observations merge into the team namespace — cross-agent recall without file sharing.

Configuration Flags

Key environment variables affecting workflow:

agentmemory — Memory and Context

Storage Architecture

All state is stored in SQLite via iii-engine's StateModule at ./data/state_store.db. There are no external database dependencies — the README badge reads "0 external DBs."

iii-engine wraps the SQLite as a KV store accessed through typed keys defined in src/state/schema.ts. The KV object has 45+ named keys.

Memory Layers

Observations (mem:obs:{sessionId}): Raw per-session records. Each observation has:

• sessionId: session it belongs to
• hookType: which hook captured it (PreToolUse, PostToolUse, etc.)
• timestamp
• narrative: LLM-compressed summary (if auto-compress enabled) or raw content
• type: conversation | file_read | file_write | bash | error | task | pattern
• importance: 1–10 score (higher = more likely to be recalled)
• files: file paths involved
• concepts: semantic tags

Long-term memories (mem:memories): Explicitly saved insights via memory_save or promoted from observations.

Crystals (mem:crystals): Permanently crystallized patterns. Created via memory_crystallize — the highest permanence tier; never evicted by lifecycle.

Semantic (mem:semantic) and Procedural (mem:procedural): Typed memory categories.

Slots (mem:slots, mem:slots:global): Scoped key-value storage for agents. Global slots persist across sessions; session slots are scoped.

Knowledge Graph

When GRAPH_EXTRACTION_ENABLED=true, an LLM extracts entities and relations from observations:

• Nodes: mem:graph:nodes
• Edges: mem:graph:edges
• Edge history: mem:graph:edge-history

Graph retrieval (graph-retrieval.ts) expands search results by traversing entity relationships — a file node may link to an architecture decision node, which links to other files involved.

Temporal graph (temporal-graph.ts) tracks entity validity windows — "used jose from session 3, switched to jsonwebtoken in session 7."

Search Mechanism

Three-layer hybrid search (from smart-search.ts):

1. BM25 (mem:index:bm25): token overlap over observation narratives
2. Vector (mem:emb:{obsId}): cosine similarity via all-MiniLM-L6-v2 local embeddings (no API key required, runs via @xenova/transformers)
3. Graph expansion: entity-linked observations pulled in by graph traversal

Benchmark: 95.2% R@5 on LongMemEval-S (500 questions); 96.7% R@5 on internal coding-agent-life-v1 corpus. BM25-only fallback achieves 86.2% R@5.

Vision Search

memory_vision_search and vision-search.ts / image-refs.ts / image-embeddings.ts: screenshots and image data captured in hook payloads are embedded and searchable. Image quota cleanup (image-quota-cleanup.ts) manages disk usage.

Context Injection Paths

SessionStart injection: AGENTMEMORY_INJECT_CONTEXT=true → hook writes compressed prior context to stdout → Claude Code prepends it to the first turn.

PreCompact injection: Before context window reset, hook fetches /agentmemory/context (which runs context.ts) → returns compressed observation summary → written to stdout → survives compaction.

Claude Bridge (mem:claude-bridge, claude-bridge.ts): When CLAUDE_MEMORY_BRIDGE=true, the PreCompact hook syncs CLAUDE.md contents into memory. /agentmemory/claude-bridge/sync endpoint.

Retention / Eviction

retention.ts + evict.ts + auto-forget.ts:

• Retention scores computed per observation (mem:retention-scores)
• Access frequency logged (mem:access)
• Old, low-importance observations evicted to keep database size bounded
• Disk size manager (disk-size-manager.ts) enforces a configurable size limit

Team Memory

mem:team:{teamId}:shared — team-scoped shared observations. mem:team:{teamId}:users:{userId} — per-user team profile. Multiple agents in a team share memory via memory_team_share / memory_team_feed.

Mesh / Multi-Agent

mem:mesh — distributed agent mesh topology. memory_mesh_sync — synchronizes memory state across mesh nodes. Used when multiple agentmemory instances run in a network.

Persistence Scope

Session observations: project-scoped by default (AGENT_SCOPE_ISOLATED=true). Long-term memories, crystals, lessons, and team memory: global (cross-project).

Obsidian export (memory_obsidian_export, obsidian-export.ts): export entire memory graph as Obsidian-compatible Markdown vault with bidirectional links.

agentmemory — Orchestration

Multi-Agent Pattern

agentmemory is not itself an orchestrator — it is the memory layer beneath any orchestrator. It supports multi-agent scenarios through three mechanisms:

1. SubagentStart/SubagentStop hooks: When Claude Code spawns a sub-agent, the SubagentStart hook registers the sub-agent in the parent session's observation graph. SubagentStop captures the sub-agent's completion. This creates a hierarchical session graph: parent session → sub-agent session → observations.

2. Shared memory namespace: All agents pointing at the same agentmemory server (via AGENTMEMORY_URL) share mem:memories, mem:crystals, mem:lessons, and mem:insights. Sub-agents can recall context from parent sessions and from other concurrent agents.

3. Mesh sync (memory_mesh_sync): For distributed setups where multiple agentmemory instances run on different machines, mem:mesh topology enables cross-instance memory synchronization.

Agent Scope Isolation

AGENT_SCOPE_ISOLATED=true (default): session observations are scoped to the project cwd — recall only returns results matching the current project path. Long-term memories (crystals, lessons) remain global.

AGENT_SCOPE_ISOLATED=false: all sessions share the same recall pool, useful in monorepo setups.

Signal Bus

mem:signals — cross-agent messaging. memory_signal_send / memory_signal_read allow agents to pass messages through the shared memory server without direct communication channels.

Lease Mechanism

mem:leases — distributed locking for concurrent agents. memory_lease acquires a named lease (TTL-based). Used internally by withKeyedLock to prevent concurrent writes to the same observation set.

Sentinel Watchers

memory_sentinel_create / memory_sentinel_trigger: agents can create watchers on memory conditions. When a condition is met (e.g., a specific pattern observed N times), the sentinel fires a trigger. Enables reactive multi-agent coordination: agent B watches for a signal from agent A before proceeding.

Team Memory Integration

memory_team_share: agent pushes an observation to mem:team:{teamId}:shared. memory_team_feed: agent pulls shared observations from other team members. The teamId can be a project identifier or a human-chosen team name. No explicit invitation/join protocol — any agent with the same teamId and AGENTMEMORY_SECRET can participate.

Cross-Platform Target

agentmemory positions as the universal memory layer for 16+ agent platforms simultaneously:

• Claude Code: 12 hooks + native plugin + MCP + 8 skills
• Codex CLI: 6 hooks + native plugin + MCP + 4 skills
• OpenClaw, Hermes, pi: native plugin + MCP
• OpenHuman: native Memory trait (Rust)
• Cursor, Gemini CLI, Claude Desktop, Windsurf, Cline, Kilo Code, Roo Code, Goose: MCP only
• OpenCode: 22 hooks + MCP + plugin
• Aider: REST API only (no hook/MCP support)

All platforms share the same agentmemory server process and the same SQLite database. "All agents share the same memory server."

Isolation Mechanism

None between platform clients — a Cursor session and a Claude Code session on the same project share observations. Isolation is only at the project-cwd level.

No sandboxing, no container boundaries, no separate databases per platform.

Concurrency

withKeyedLock provides per-session mutex on observation writes. The iii-engine WebSocket runtime handles concurrent requests via its Worker/Function/Trigger primitives. The SQLite StateModule serializes writes.

agentmemory — UI and CLI Surface

CLI Binary: agentmemory

Global npm binary (@agentmemory/agentmemory).

Subcommands

agentmemory                    # start memory server on :3111
agentmemory demo               # seed sample sessions + prove recall
agentmemory connect <agent>    # wire the specified agent (claude-code, codex, cursor, gemini-cli, kiro, ...)
agentmemory connect codex --with-hooks   # explicit hook wiring for Codex Desktop

agentmemory connect <agent> writes the mcpServers config block to the agent's config file and, for agents with native plugin support, registers the plugin.

Also available as npx @agentmemory/agentmemory (no install). From v0.9.16+, the first npx run prompts to install globally.

Real-Time Viewer (port 3113)

A live dashboard that shows memory as it accumulates.

• Served via src/viewer/server.ts on port 3113 (separate from the REST API on 3111)
• HTML document generated by src/viewer/document.ts (renderViewerDocument)
• CSP enforced: img-src 'self' — DNS rebinding protection via allowed-origins list
• Allowed origins: http://localhost:3111,http://localhost:3113,http://127.0.0.1:3111,http://127.0.0.1:3113
• Real-time updates via mem-live event stream (iii-engine stream)

The viewer shows observations flowing in as hooks fire, session timelines, and memory graph visualizations.

iii Console (database inspection)

The iii-engine console provides direct database inspection of all KV keys (mem:sessions, mem:obs:{sessionId}, mem:graph:nodes, etc.) without requiring SQL queries. Accessed via the iii-engine web interface.

REST API Surface (port 3111)

Used by hook scripts and fallback paths when MCP is unavailable:

• GET /agentmemory/health — server health, config flags, version
• POST /agentmemory/session/start — register session
• POST /agentmemory/context — compressed context for pre-compaction
• GET /agentmemory/sessions — list sessions
• POST /agentmemory/recall — search fallback
• POST /agentmemory/smart-search — hybrid search
• POST /agentmemory/observe — manual observation submission
• POST /agentmemory/claude-bridge/sync — CLAUDE.md sync

All endpoints require Authorization: Bearer {AGENTMEMORY_SECRET} when secret is configured (503 if required but missing).

MCP Server (stdio, @agentmemory/mcp)

Separate npm package @agentmemory/mcp — the stdio shim that proxies calls to the running agentmemory server. Added to mcpServers in agent config:

{
  "command": "npx",
  "args": ["-y", "@agentmemory/mcp"],
  "env": {
    "AGENTMEMORY_URL": "http://localhost:3111"
  }
}

Falls back to 7 local tools when no server is reachable; full 53 (or 51 per plugin.json v0.9.22) tools when server is up.

Claude Code Skills UI

8 skills accessible via /skill-name in Claude Code chat:

• /recall [query]
• /handoff [cwd]
• /remember
• /forget
• /recap
• /commit-context
• /commit-history
• /session-history

Issue Workaround for Hook Path Resolution

From README: wiring via ~/.claude.json directly instead of /plugin install causes hook scripts to embed the versioned install path (e.g., ~/.codex/plugins/cache/agentmemory/0.9.21/scripts/...). This breaks on upgrade. The plugin install path (${CLAUDE_PLUGIN_ROOT}) avoids this — tracked in issue #508.