#+TITLE: Comparative Memory & Persistence Study
#+FILETAGS: :notes:comparative-study:memory:persistence:context:

* Purpose

Compare memory/persistence architectures across Claude Code, OpenCode, OpenClaw, and Hermes Agent against Passepartout's Merkle tree memory. Audit the foveal-peripheral model against compaction pipelines. Inform session rewind (v0.7.2) and long-term memory features.

* Findings Summary

| Dimension | Claude Code | OpenCode | OpenClaw | Hermes | Passepartout |
|-----------+-------------+----------+----------+--------+--------------|
| Primary store | JSONL append-only | SQLite (Drizzle) | JSONL + trajectory JSONL | SQLite + WAL + FTS5 | Merkle-tree hash table + .snap |
| Compaction | 4 strategies (Full, Partial, SM, Micro) | Anchored summary + pruning | Pi SessionManager + snapshots | ContextCompressor + tool pruning | Foveal-peripheral pruning (single) |
| Trigger | Token threshold + API PTL | Token overflow detection | Threshold/overflow/timeout | Token threshold | Fixed depth + similarity cutoff |
| Cross-session memory | extractMemories (file-per-topic) + SessionMemory | Session-scoped only | SOUL.md/MEMORY.md/IDENTITY.md + oc:// | Builtin MEMORY.md + pluggable providers | None (all in Merkle tree) |
| Resume | UUID chain from JSONL tail | SQL query by session ID | JSONL replay | SQL query by session ID | Memory snapshots |
| Search | None | Frecency for files only | None | FTS5 full-text across all sessions | Embedding-based similarity |
| Subagent memory | Sidechain transcript + AgentSummary | Child sessions | Subagent sessions + trajectory | MemoryProvider.on_delegation | N/A (no subagents) |
| Auto-memory | extractMemories (LLM extraction) | None | SOUL.md manual edit | memory_write/read tools | Not implemented |

* Claude Code — The Most Elaborate Memory System

**Persistence**: Append-only JSONL, one file per session. parentUuid chain for graph reconstruction. Lite metadata reading (last 16KB tail) to avoid loading multi-GB files.

**4 Compaction Strategies:**
1. Full Compact: Forked agent summarizes entire conversation. 9-section template (Request, Concepts, Files, Errors, Problem Solving, Messages, Tasks, Current Work, Next Step). Post-compact: recently-read files re-attached, skills re-attached. Fork shares parent's prompt cache (~0.76% fleet savings).
2. Partial Compact: from (summarize after selected message) or up_to (summarize before selected message).
3. SessionMemory Compact: Pre-maintained markdown notes used as summary. No extra API call needed. Template: Session Title, Current State, Tasks, Files, Workflow, Errors, Learnings, Worklog.
4. Microcompact: Cache-editing to DELETE old tool results without invalidating cache. Time-based: clear old results when cache has expired.

**Auto-Memory**: extractMemories runs at end of query loop. Forked agent scans conversation, writes durable memories to ~/.claude/projects/<project>/memory/ as individual markdown files. Team memory support. Mutual exclusion with main agent. Trailing-run pattern for concurrent turns.

**CLAUDE.md Hierarchy**: Managed (/etc) → User (~/.claude) → Project (walking up from CWD) → Local (CLAUDE.local.md). Includes conditional rules with frontmatter (path:, when:). @include directives with circular prevention.

**Circuit breaker**: Stops auto-compacting after 3 consecutive failures.

**Unique**: Forked-agent cache sharing saves billions of tokens/month. Cache-editing microcompact surgically removes content without cache break.

* OpenCode — Anchored Summaries

**Persistence**: SQLite with session/message/part tables. Message decomposed into typed parts (text, tool, file, compaction, step-start, step-finish). Sync events for cross-process.

**Compaction**: Inline (not background). Overflow threshold: totalTokens >= model.limit.input - reserved. Two-turn tail protection. Anchored summaries: iterative updates to previous summary — preserve still-true details, remove stale ones, merge new facts. Dedicated compaction agent.

**Pruning**: Walks messages backwards, skips last 2 turns. Marks old tool outputs as compacted (excluded from context). Protected tools (skill) never pruned.

**Frecency**: File access tracking with scoring formula: frequency * (1 / (1 + daysSinceLastOpen)). Max 1000 entries, JSONL persisted. Used for autocomplete ranking.

**Undo/Redo**: Snapshot-based revert with file patch tracking per step.

* OpenClaw — Document-Centric Memory

**Memory files**: SOUL.md (persona), MEMORY.md (long-term knowledge), IDENTITY.md (avatar/name), AGENTS.md (instructions), TOOLS.md (tool config), USER.md (user context), BOOTSTRAP.md, HEARTBEAT.md.

**oc:// path system**: Structured addressing for memory file sections. Format: oc://SOUL.md/Boundaries/deny-rule-1/risk. Parser, AST, resolver, validation. Frontmatter-based scoping.

**Compaction checkpoints**: Pre-compaction transcript snapshots. Max 25 per session. Enable undo (restore to pre-compaction) and branch (fork new session from snapshot). Reasons: auto-threshold, overflow-retry, timeout-retry, manual.

**Pluggable context engine**: ContextEngine interface with assemble/compact/ingest/maintenance. Third-party context engine plugins.

**Trajectory sidecar**: Separate .trajectory.jsonl for structured runtime events. 256KB per event, 10MB runtime, 50MB file max.

* Hermes Agent — Full-Text Search + Pluggable Memory

**Persistence**: SQLite + WAL mode. FTS5 virtual table for full-text search across all sessions. Schema versioning with migrations. Jittered write retry (15 tries, 20-150ms random backoff) to break convoy effects.

**Context compressor**: Automatic on token threshold. Tool output pruning: 1-line semantic summaries (e.g., "[terminal] ran npm test -> exit 0, 47 lines"). Iterative summary updates. Scaled budget (20% of compressed tokens, capped at 12K). Active Task tracking so model knows what to resume. 10-min cooldown on failure.

**Trajectory compressor**: Separate offline batch processor for training data preparation. HuggingFace tokenizer for accurate counts. OpenRouter summarization (Gemini 3 Flash). Middle-only compression. Protected head/tail.

**Memory providers**: Pluggable architecture. BuiltinMemoryProvider uses MEMORY.md/USER.md files. External: Honcho, Hindsight, Mem0. One active at a time. Hooks: initialize, prefetch, sync_turn, on_pre_compress, on_delegation, on_session_end. Context fencing with <memory-context> markers.

* Passepartout Blindspot Assessment

1. **No CLAUDE.md equivalent** — Passepartout has Org-mode memory but no "always-loaded identity/instructions" mechanism. Claude Code's CLAUDE.md hierarchy is a lightweight, user-editable config that applies globally. Passepartout should add an equivalent in ~/memex/ (the IDENTITY.org analogue). [Action: minor addition to docs]

2. **No auto-memory** — Claude Code's extractMemories and Hermes's MemoryProvider.sync_turn both persist learnings automatically after each session. Passepartout records everything in the Merkle tree but doesn't extract durable cross-session learnings. [Action: post-v0.7.2 feature]

3. **Foveal-peripheral vs compaction** — Passepartout's model is more principled (semantic relevance, not token-count trimming), but lacks the battle-testing of Claude Code's 5-layer pipeline. Consider adding reactive compaction for PTL errors and tool output summarization. [Action: context study needed]

4. **No checkpoint/rewind** — Claude Code and OpenClaw both support session forking/rewinding. Passepartout's Merkle tree memory makes this possible with stronger guarantees (filesystem state rewind, not just transcript). [Action: v0.7.2 session rewind]

5. **No full-text search** — Hermes has FTS5. Passepartout relies on embedding similarity. For exact-match queries ("what did I say about the login form?") FTS is better than vector search. [Action: consider for v0.10.0+]

6. **Merkle tree advantage confirmed** — All competitors use linear transcripts (JSONL/SQL rows). Passepartout's Merkle tree provides content-addressed identity, copy-on-write snapshots, and cryptographic integrity. This is a permanent architectural advantage for rewind/undo/audit. [Architecture confirmed; no action]
