RFC: compare Raven and Claude Code memory designs for Maka's durable memory architecture #771

Context

This is a follow-up to #544, especially the durable execution foundation / Memory track.

#544 defines the high-level requirement:

long-lived user, project, and task memory, not just context summarization; memory needs source attribution, freshness, confidence, scope, and expiry semantics.

Maka already has useful memory and context-management foundations, but it does not yet have a complete durable-memory lifecycle.

This RFC proposes a source-backed comparison of two mature design directions:

• Raven-native memory/context architecture;
• the file-based memory and session-compaction architecture exposed by the likun666661/claude-code source fork used in this research.

The Claude source reference is an open-source fork/reconstruction, not the complete current implementation of Anthropic's closed-source Claude Code product. Claims in this issue should therefore be phrased as source behavior in that repository, not as guarantees about every current Claude Code release.

The goal is to decide which concepts Maka should adopt, which existing Maka components should be preserved, and how the work should be split into independently mergeable issues and PRs.

Why this needs a dedicated RFC

Memory is currently mixed with several related but different concerns:

• prior conversation replay;
• context compaction;
• current task continuity;
• long-lived user/project facts;
• proactive attention and behavioral state;
• archive and retrieval;
• privacy, approval, scope, expiry, and correction.

Treating all of these as one growing MEMORY.md or one summary block would make correctness, cost, privacy, and recovery difficult to reason about.

We should first define explicit ownership and lifecycle boundaries, then implement them incrementally.

Current Maka baseline

Maka is not starting from zero.

Existing durable-memory controls

• user-visible memory/MEMORY.md;
• PENDING.md proposal queue;
• draft / review_required / active / archived / rejected states;
• proposal -> approve/reject flow;
• workspace/session scope fields;
• incognito read/write blocking;
• secret redaction;
• backup/restore and atomic writes;
• agent memory read disabled by default.

Existing context/compaction controls

• append-only RuntimeEvent ledger;
• history token/turn budgets;
• stale and active tool-result pruning;
• archive retrieval and history search;
• source-bearing history compact checkpoints;
• active full compact and semantic compact;
• compaction boundaries, coverage, hashes, and fail-open diagnostics.

Current gaps and correctness concerns

• active memory entries are concatenated and then truncated at 12,000 characters;
• recall is not query-aware or top-K;
• scope=session is stored but the current prompt builder does not receive a session id or enforce it;
• the memory prompt may be captured when the backend is created rather than refreshed every turn;
• there is no per-session message manifest;
• there is no independent working state for goals/open threads/decisions;
• there is no episode -> profile consolidation lifecycle;
• there is no structured stale/conflict/supersedes model;
• there is no attention/behaviors derived-state pipeline;
• there is no agent-facing MemoryPropose tool behind the host approval gate.

These correctness issues should be fixed before introducing an LLM Curator.

Raven design summary

Raven provides the stronger end-to-end memory lifecycle and should be considered the primary architectural reference.

Context ownership

• one ContextAssembler/ContextEngine owns the model-visible context;
• Fast Path passes history without an extra LLM call while pressure is low;
• Slow Path uses a smaller Curator model to select/archive/retrieve context;
• deterministic fallback remains available when Curator fails;
• the final trimmer enforces token budget and tool-call/result adjacency.

Durable and derived memory layers

• append-only session history remains the source of truth;
• lossless archive keeps old messages retrievable;
• working state tracks goals, open threads, and decisions;
• episodes record events and source references;
• profile updates occur after evidence accumulates;
• attention and behaviors support proactive planning;
• offsets prevent repeated processing of the same session data.

Evidence currently available

The Raven checkout contains extensive tests covering Curator paths, context invariants, session append/concurrency, locking/CAS, consolidation, attention/behaviors, offsets, and overflow recovery.

The reviewed 13 relevant test files contain 186 statically counted test_* functions. This is a source count, not an independently executed pass result.

Raven also provides benchmark/eval harnesses:

• PinchBench: 23 task cards;
• ClawBench Streaming: persistent-session task execution;
• Proactivity pbench: 120 help-or-skip records;
• Proactivity longrun: 6 personas x 30 days;
• Skill Evals: 50 retrieval queries.

Raven's first-party documentation reports:

These numbers are useful motivation, but the current repository does not include the complete raw artifacts needed to independently recompute them. Maka must run its own controlled A/B.

Claude Code design summary

Claude Code is the stronger reference for bounded file recall, session continuity, stale handling, and compact recovery.

Bounded file memory

• MEMORY.md is a small index rather than the full memory body;
• the index is capped at 200 lines and 25KB;
• at most 200 topic-file headers are scanned;
• a relevance side query selects at most 5 topic files;
• each selected topic is capped at 200 lines / 4KB;
• one turn injects at most about 20KB of relevant topic memory;
• session memory prefetch stops after 60KB of cumulative injected content;
• already-read or already-injected topic files are deduplicated.

Session Memory and compact

• Session Memory initializes after about 10,000 context tokens;
• it updates after about 5,000 additional tokens;
• the notes use fixed sections such as Current State, Task specification, Files and Functions, Workflow, Errors & Corrections, Learnings, Key results, and Worklog;
• total Session Memory is bounded to about 12,000 tokens;
• compact boundaries preserve continuation metadata;
• reactive compact handles prompt-too-long failures;
• resume reconnects the compact summary and preserved suffix.

Stale and correction behavior

• memories older than one day receive a stale warning;
• current code/resource state takes precedence over recalled memory;
• the extraction prompt asks the agent to update/remove outdated memories and avoid duplicates.

Important limitations for Maka

Claude Code does not provide the full Raven lifecycle:

• no Raven-style per-message manifest;
• no explicit episode -> evidence threshold -> profile promotion;
• no attention/behaviors + offset pipeline;
• no Raven-style Curator message archive/retrieve tool loop;
• no Maka-style per-entry user approval requirement.

Comparison

Proposed direction

The current design hypothesis is:

Raven-first memory semantics
+ Maka-native context runtime
+ Maka approval/privacy/reversible storage
+ Claude-style bounded recall, stale handling, and compact recovery

In practical terms:

1. Keep RuntimeEvent as the append-only source of truth.
2. Introduce a narrow ContextEngine interface rather than rewriting Maka's compact internals.
3. Reuse existing Maka history compact, archive retrieval, history search, active compact, semantic compact, and boundary/checkpoint types as ContextEngine adapters.
4. Replace full active-memory concatenation with query/scope/freshness-aware bounded recall.
5. Add per-session manifest and working state.
6. Add lossless message archive/retrieve with verifiable source refs.
7. Add episode candidates and evidence-gated profile proposals.
8. Preserve proposal -> user approval before durable activation.
9. Add Claude-style reactive compact/resume as a final recovery path.
10. Add attention/behaviors only after durable memory correctness is stable.

This should not be a big-bang rewrite.

Proposed data ownership

This ownership is intended to prevent the same fact from being injected simultaneously through a compact summary, working state, durable profile, and attention state.

Questions for discussion

1. Should Raven-first be the main architecture, or should Maka use a simpler Claude-style topic-memory design first?
2. Should ContextEngine own all model-visible history shaping, while AiSdkBackend only consumes provider-safe messages?
3. Should the first recall implementation be deterministic, with an LLM selector only in shadow mode?
4. Should durable profile promotion always require user approval, even after repeated episode evidence?
5. Which memory scopes are required in v1: workspace and session only, or also user/project/team?
6. Should MEMORY.md remain the canonical store, or become a human-readable projection over structured entries?
7. What should be the initial memory-segment token budget and top-K?
8. How should corrections and deletion propagate through profile, episodes, archive indexes, and compact caches?
9. Which target models should be used to validate the claim that Raven-style bounded context is better for smaller or less stable tool-calling models?
10. Which Raven benchmark harnesses should be adapted, and which Maka-native memory datasets must be created?

Proposed implementation order

1. Fix correctness first:
   • enforce session scope on read;
   • refresh/invalidate memory prompt state per turn;
   • fail closed on invalid semantic compact summaries;
   • ensure every fallback still passes the hard context budget.
2. Add bounded MemorySegmentBuilder and recall trace.
3. Extract a narrow ContextEngine interface with real strategy switching.
4. Add session manifest, lossless archive, and working state.
5. Add LLM Curator in offline/shadow mode.
6. Add episode store and profile proposal consolidation.
7. Harden Claude-style reactive compact/resume.
8. Add attention/behaviors and proactivity evaluation.

Benchmark and acceptance requirements

At minimum, compare:

• full context;
• current Maka;
• deterministic Curator;
• LLM Curator;
• summary compact;
• hybrid Curator + reactive compact.

Report separately:

• task pass/verifier score;
• fact recall precision/recall/F1;
• final-call context tokens;
• task and session cumulative tokens;
• main-model and Curator tokens/cost;
• p50/p95 latency;
• Fast/Slow/Fallback counts;
• archive/retrieve use;
• provider overflow and emergency recovery;
• stale/conflict correctness;
• cross-session/workspace privacy leaks;
• false profile promotions.

The benchmark report must preserve commit, model/provider config, dataset hash, full transcript, model-visible selected source ids, token CSV, and verifier artifacts.

Non-goals

• adding EverOS, embeddings, a vector database, or an external memory backend in this RFC;
• rewriting all existing context/compact code;
• automatically converting all conversations into durable memory;
• enabling proactive attention before durable memory correctness is established;
• claiming Raven benchmark gains without reproducing them on Maka.

Expected outcome of this RFC

• agree on the target architecture and ownership boundaries;
• decide what is adopted from Raven, Claude Code, and current Maka;
• agree on v1 scope, storage, write/read/update/delete semantics;
• agree on benchmark variants, metrics, and promotion gates;
• split the work into small implementation issues/PRs.

Suggested follow-up issues

• Fix session-scope memory reads and per-turn memory refresh.
• Add deterministic bounded MemorySegmentBuilder and recall diagnostics.
• Extract ContextEngine strategy interface from AiSdkBackend.
• Add per-session context manifest and working state.
• Extend source-bearing archive/retrieve to message-level history.
• Add episode store and profile proposal consolidation.
• Add LLM Curator shadow mode and A/B runner.
• Add compact/resume recovery contract tests.
• Add attention/behaviors derived-state pipeline.
• Add Maka continuity and durable-memory lifecycle benchmark datasets.

Related

• roadmap: durable agent platform #544: roadmap: durable agent platform
• Add active-loop full compaction for long benchmark runs #327: active-loop full compaction for long benchmark runs
• feat(harness): add Maka-native AHE-style self-iteration loop #345: Maka-native AHE-style self-iteration loop
• Raven repository: https://github.com/EverMind-AI/Raven
• Claude Code source fork used for this research: https://github.com/likun666661/claude-code

Raven 作为 memory 生命周期与 ContextEngine 主架构
Maka 保留 RuntimeEvent、compact、审批、隐私和可回滚存储
Claude 补充按需读取、硬上限、stale、Session Memory 和 compact/resume