memex/notes/comparative-memory.org

Comparative Memory & Persistence Study

• Purpose
• Findings Summary
• Claude Code — The Most Elaborate Memory System
• OpenCode — Anchored Summaries
• OpenClaw — Document-Centric Memory
• Hermes Agent — Full-Text Search + Pluggable Memory
• Passepartout Blindspot Assessment

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]