folded-memory-implementation

folded-memory-implementation

A developer guide for hierarchical memory: instead of replacing history with a single flat summary, maintain three memory layers at different levels of detail. Old content is compressed more aggressively — not discarded. Each layer is independently stored and selectively recalled.

Prerequisite: read compact-memory-implementation first. Folded memory builds on the same fork-agent and trigger concepts.

---

The core idea

L1 Working memory    [ turn 38..50 ] — raw turns, full detail, short window
L2 Episodic memory   [ turn 10..37 ] — compressed episodes, medium detail
L3 Semantic memory   [ turn 1..9  ] — abstract facts and decisions, sparse

When L1 fills up → fork an episode compactor → move oldest L1 turns into L2. When L2 fills up → fork a semantic extractor → distill L2 into L3.

At each agent turn, inject the right combination of layers into the system prompt.

---

Step 1 — Understand the setup

Same questions as compact-memory-implementation, plus:

• How long do sessions run? If sessions are short (<50 turns), flat compact is enough.
• What kind of information ages badly? Decisions and patterns age well (good for L3). Exact tool outputs age badly (keep only in L1 or summarize into L2).
• Does the agent need to cite past reasoning? If yes, L2/L3 must preserve decision rationale, not just conclusions.

---

Step 2 — Three-layer architecture

Layer 1 — Working memory

• Content: raw conversation turns, full fidelity
• Window: last N turns (e.g., 20 turns or ~30k tokens)
• Trigger to flush: when L1 exceeds its window, oldest turns move to L2
• Injected as: full message history in messages[]

Layer 2 — Episodic memory

• Content: compressed episode summaries — what happened, what was decided, what was tried
• Window: up to M episodes (e.g., 10 episodes, each covering ~20 turns)
• Trigger to flush: when episode count exceeds M, oldest episodes distill into L3
• Injected as: structured block in system prompt