Amr Gharbeia
4e9431ec1d
passepartout v0.7.2 (Gate Trace + HITL + Search + 11 more features): - Gate trace visualization with Ctrl+G toggle - HITL inline panels with styled collapse on approve/deny - Agent identity file + /identity command - Safe-tool read-only allowlist - Message search mode with Up/Down nav and highlights - Context budget visibility with section breakdown - Session rewind /sessions /resume /rewind - Undo/redo per operation - Context debugging /context why /context dropped - Tool hardening (timeouts, write verify, read-only cache) - Tag stack severity tiers + trigger counts - Merkle provenance audit + audit-verify - Self-help /help <topic> reads USER_MANUAL.org - Live CONFIG section in system prompts - Pads: Page Up/Down scroll by 10 lines Core 92/92 TUI Main 104/104 TUI View 29/29 Neuro 13/13
86 lines
8.0 KiB
Org Mode
86 lines
8.0 KiB
Org Mode
#+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]
|