feat(automem): Passive Memory Capture via Claude Code mcp_tool Hooks

[jack-arturo]

Migrated from AutoHub issue #528. AutoHub is the private automation-hub tracker; this work belongs in verygoodplugins/automem.

Claude Code hook-based passive memory capture is core AutoMem product/plugin work, not AutoHub runtime work.

Original source: https://github.com/verygoodplugins/autohub/issues/528

---

AutoMem Claude Code Plugin — Passive Memory Capture via mcp_tool Hooks

Type: fix_plan / Feature Issue
Lane: opportunity
Priority: High
Sources:

• https://code.claude.com/docs/en/hooks (official Anthropic docs, confirmed May 15 2026)
• https://code.claude.com/docs/en/hooks-guide (official Anthropic docs)
• https://modelcontextprotocol.io/docs/learn/server-concepts

---

Background

Claude Code's hook system now supports "type": "mcp_tool" hooks (officially documented). This allows any registered MCP server to receive lifecycle events from Claude Code deterministically — without relying on the agent to choose to call memory tools.

Current AutoMem integration requires agents to explicitly call store_memory. That is:

• Opt-in and agent-cooperative (the agent can skip it)
• Dependent on CLAUDE.md prompt instructions (subject to context compaction)
• Invisible at the tool-call level

Hooks are different. They fire regardless of model behavior, are deterministic, and cannot be bypassed (a PreToolUse hook returning deny blocks even --dangerously-skip-permissions).

---

Opportunity: Zero-Friction Passive Memory Capture

AutoMem could ship a Claude Code plugin / hook config that passively captures memory from four high-value lifecycle events:

Event	AutoMem Action	Why it Matters
PostToolUse	store_memory for significant tool results	Captures file edits, bash outputs, search results without any agent cooperation
Stop	consolidate_session — link session memories	Session summary + cross-memory graph edges at turn end
PostCompact	preserve_pre_compact_context	Rescues important context before compaction discards it
SubagentStop	Cross-agent memory transfer	Subagent findings become first-class memories for the orchestrator

Product gap confirmed: No memory MCP server (Mem0, Zep, engram, Hindsight) currently ships a Claude Code hook integration. The standard setup requires CLAUDE.md instructions which are prompt-cooperative, not deterministic.

---

Implementation Plan

1. New AutoMem MCP Tools (mcp-server additions)

// tool: capture_tool_use
// Called from PostToolUse hook
{
  name: "capture_tool_use",
  description: "Passively record a Claude Code tool call and result as a memory",
  inputSchema: {
    tool_name: string,       // e.g. "Bash", "Write", "Read"
    tool_input_summary: string,
    tool_output_summary: string,
    session_id: string,
    importance_hint?: number  // 0-1, optional override
  }
}

// tool: consolidate_session  
// Called from Stop hook
{
  name: "consolidate_session",
  description: "Create a session summary memory and link related tool-use memories",
  inputSchema: {
    session_id: string,
    workflow_name?: string
  }
}

// tool: preserve_pre_compact_context
// Called from PostCompact hook
{
  name: "preserve_pre_compact_context",
  description: "Store key context from a compacted session before it is lost",
  inputSchema: {
    compact_summary: string,  // Claude's own compaction summary
    session_id: string
  }
}

2. Claude Code Hook Configuration (.claude/settings.json snippet)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash|Write|Edit|MultiEdit|WebSearch|WebFetch",
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "automem",
            "tool": "capture_tool_use",
            "args": {
              "tool_name": "{{tool_name}}",
              "tool_input_summary": "{{input_summary}}",
              "tool_output_summary": "{{output_summary}}",
              "session_id": "{{session_id}}"
            }
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "automem",
            "tool": "consolidate_session",
            "args": {
              "session_id": "{{session_id}}",
              "workflow_name": "{{workflow_name}}"
            }
          }
        ]
      }
    ],
    "PostCompact": [
      {
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "automem",
            "tool": "preserve_pre_compact_context",
            "args": {
              "compact_summary": "{{summary}}",
              "session_id": "{{session_id}}"
            }
          }
        ]
      }
    ]
  }
}

3. Claude Code Plugin Manifest

Ship as a distributable plugin so any Claude Code user can claude plugin install automem:

automem-claude-plugin/
├── .claude-plugin/
│   └── plugin.json          # plugin manifest
├── skills/
│   └── automem-recall.md    # "before starting work, recall relevant memories"
├── hooks/
│   └── settings-fragment.json
└── README.md

4. Files to Create/Modify

File	Change
src/mcp-server/tools/capture-tool-use.ts	New tool
src/mcp-server/tools/consolidate-session.ts	New tool
src/mcp-server/tools/preserve-compact-context.ts	New tool
src/mcp-server/index.ts	Register 3 new tools
docs/claude-code-plugin.md	Installation guide
.claude-plugin/plugin.json	Plugin manifest
skills/automem-recall.md	Recall skill

---

Acceptance Criteria

1. PostToolUse hook fires on Bash, Write, Edit tool calls → AutoMem stores a memory with tool, input_hash, output_summary, timestamp, session_id
2. Stop hook fires → AutoMem creates a session summary memory linking all tool-use memories from that session via PART_OF edges
3. PostCompact hook fires → AutoMem stores the compaction summary as a Context memory with high importance
4. Plugin installable via claude plugin install or manual copy
5. Test: 5-turn Claude Code session → verify 5+ memories stored passively with correct graph edges
6. No agent instruction changes required — works with empty CLAUDE.md

---

Why This Matters for AutoMem's Graph Strategy

The key AutoMem graph insight: memories are more valuable as a graph than as isolated facts. The hook integration enables:

• LEADS_TO edges: Bash(run tests) → Edit(fix failing test) — causal chain from tool sequence
• PART_OF edges: all tool-use memories → session summary
• OCCURRED_BEFORE edges: automatic temporal ordering within sessions
• Cross-session RELATES_TO: same file edited in different sessions → link automatically

This closes the gap between AutoMem's graph model and the "passive recall" capability that Mem0 and Zep currently market as their differentiator. AutoMem's graph wins if the edges are written from real tool-call evidence, not just LLM-summarized text.

---

Competitive Differentiation

System	Claude Code Hook Integration
Mem0	❌ None (CLAUDE.md only)
Zep / Graphiti	❌ None
engram	❌ None
Hindsight	❌ None
AutoMem (proposed)	✅ Native mcp_tool hooks

---

Frontier Candidate

Add to frontier: opportunity:automem-claude-code-hook-integration

• Lane: opportunity
• Priority: 80 (higher than BEAM because zero external dependency, ships to production users)
• Status: open

---

Secondary Lead: LongMemEval-V2 (arXiv:2605.12493, May 12 2026)

Brand new (3 days old). Tests "knowledgeable colleague" memory — interface affordances, state dynamics, workflows, recurring failure modes. AutoMem's Pattern/Context types + LEADS_TO/OCCURRED_BEFORE edges map directly. No MCP memory system evaluated yet.

Action: Add frontier candidate research:longmemeval-v2-evaluation and outreach to Di Wu (UCLA) once code is released.

[caioribeiroclw-pixel]

One thing I’d add to this plan: make passive capture produce an auditable event record before it becomes a memory.

The hook part removes the “agent forgot to call store_memory” failure mode, but it introduces a different one: the memory system may now capture tool chatter deterministically even when the event is transient, sensitive, or not actually a durable learning.

A small invariant that would help:

{
  "capture_source": "claude_code.mcp_tool",
  "tool_name": "...",
  "tool_call_id": "...",
  "session_id": "...",
  "project_root_hash": "...",
  "trigger": "PostToolUse|Stop|SubagentStop",
  "raw_event_hash": "sha256:...",
  "raw_retention": "discarded|redacted|retained",
  "candidate_memory": "...",
  "classification": "fact|decision|preference|task_state|noise",
  "confidence": 0.0,
  "t_valid": "...",
  "t_invalid": null,
  "privacy_scope": "project|user|global",
  "why_durable": "..."
}

Then gate storage on a few rules:

• default to storing the derived candidate, not raw tool output;
• require why_durable / classification for passive captures, so logs don’t become memory by accident;
• reject or quarantine low-confidence captures instead of indexing them immediately;
• record a hash/source pointer so a later “why did AutoMem remember this?” question is answerable;
• make project/user/global scope explicit, because hook-captured memories can otherwise bleed between projects more easily than manually stored notes.

That keeps the deterministic hook benefit while preserving a review trail and a deletion/debug path for bad memories.

[ajdelaguila]

Full disclosure: I maintain Data Olympus, a governed project-knowledge MCP server for coding agents: https://github.com/knaisoma/data-olympus

The hook-based capture path is powerful because it removes reliance on the agent remembering to call a tool. The caution I would add is that deterministic capture should probably feed a review/promotion lane, not immediately become authoritative memory.

A useful split is:

• capture event: what happened, where it came from, privacy scope, hash/provenance;
• candidate memory: the distilled statement proposed from the event;
• governing knowledge: only promoted items that should influence future agent behavior.

Data Olympus focuses on that final governed layer: markdown in git, MCP retrieval, proposed writes, accepted/in-force filtering, validity windows, and supersession chains. In an AutoMem setup, it could be a downstream “promotion target” for durable project rules and decisions, while AutoMem continues to own passive event capture.

For this issue, I would consider an explicit classification or authority_state on captured memories. A passive PostToolUse event might be a good observation, but it should not automatically become a project rule without a promotion step.

[caioribeiroclw-pixel]

+1 to the capture → candidate → governed-knowledge split @ajdelaguila described.

For this issue, I’d make that boundary explicit in the captured record rather than hiding it inside later retrieval behavior. Something like:

{
  "capture_event_id": "evt_...",
  "candidate_memory_id": "mem_cand_...",
  "authority_state": "observed|candidate|proposed|in_force|rejected|superseded",
  "promotion_target": "automem|data_olympus|other",
  "promotion_decision_ref": null,
  "source_event_hash": "sha256:...",
  "derived_memory_hash": "sha256:...",
  "privacy_scope": "project|user|global",
  "stale_if": ["source_event_redacted", "project_root_changed", "superseded_by:..."]
}

Then AutoMem can stay excellent at deterministic capture, while downstream/governed systems can decide when a candidate becomes instruction-bearing knowledge.

The important invariant for passive hooks: a captured event is evidence, not authority. The default should be observed or candidate; only a promotion/review path should move it to in_force.

[ajdelaguila]

Agreed. Defaulting passive hook output to observed or candidate is the important guardrail. The promotion boundary can stay pluggable, but the captured record should make it impossible to confuse evidence with instruction-bearing knowledge.

[caioribeiroclw-pixel]

Exactly. I’d keep the interop contract deliberately small so AutoMem does not need to become a governance system itself.

Minimum useful handoff from passive capture:

{
  "capture_event_id": "evt_...",
  "candidate_memory_id": "mem_cand_...",
  "authority_state": "observed|candidate",
  "source_event_hash": "sha256:...",
  "derived_memory_hash": "sha256:...",
  "privacy_scope": "project|user|global",
  "promotion_target": "data_olympus|automem|other|null"
}

Then a downstream system can promote/accept/reject without AutoMem having to decide what is “truth”. The key is that retrieval should be able to filter differently: observations can help explain why a candidate exists, but only promoted/in-force knowledge should steer future agent behavior by default.