Memory Segmentation

Why Segmentation Matters

LLM agents are stateless between calls. If all memory is treated as one flat transcript, quality degrades as context grows.

Segmentation fixes this by giving each memory lane one clear job:

• Session memory: active working context
• Semantic memory: durable truths and preferences
• Episodic memory: chronological history and boundary snapshots
• Procedural memory: reusable workflows and playbooks

This model is agent-agnostic. It works whether you use CLI tools, MCP clients, SDK-based apps, or custom harnesses.

The Four Memory Lanes

1) Session Memory (working set)

Use for the current task: recent turns, active goals, and boundary checkpoints.

Properties:

• high read frequency during an active task
• bounded size (subject to compaction)
• explicitly checkpointed before destructive boundaries

2) Semantic Memory (durable truths)

Use for stable, re-usable truth: standards, constraints, architecture decisions, durable preferences.

Properties:

• concise and current
• overwrite/supersede when truth changes
• injected consistently in retrieval

3) Episodic Memory (timeline fidelity)

Use for history: what happened, when it happened, and task boundary snapshots.

Properties:

• append-oriented
• optimized for chronology and handoffs
• can preserve raw high-fidelity slices when needed

4) Procedural Memory (reusable workflows)

Use for repeatable execution patterns: checklists, runbooks, escalation flows, and successful routines.

Properties:

• intent-matched retrieval
• promoted from successful repeated episodes
• improves first-action quality on recurring work

Compaction and Lifecycle Triggers

Compaction compresses session context so work can continue inside finite context windows. Good compaction is checkpoint-first, not loss-first.

Reference flow:

1. Retrieve context with session hints (token/turn/inactivity state).
2. If compaction is required, write a checkpoint first.
3. Compact session context.
4. Continue with refreshed context.
5. On boundary events, persist a snapshot.

Routing Guide: What Goes Where

Update and Consolidation Rules

Segmentation only works if memory can evolve.

• Filter before writing: not every turn is memory-worthy.
• Consolidate duplicates: merge equivalent entries.
• Overwrite/supersede stale semantic truth: avoid stacking contradictions.
• Promote repeated successful patterns into procedural memory.

Agent-Agnostic Implementation Pattern

You can implement this model with many stacks (database-first, file-first, hybrid). The core contract is the same:

1. Define lane boundaries (session, semantic, episodic, procedural).
2. Define write triggers (count/time/event/explicit user intent).
3. Define retrieval policy (which lanes are always injected vs query-driven).
4. Define consolidation policy (merge, supersede, conflict handling).
5. Define observability (compaction rate, contradiction trend, retrieval quality).

Optional File-Mode Mapping

If you prefer human-readable files (for git workflows), map the same lanes to files:

# semantic
memory.md

# episodic daily timeline
memory/daily/YYYY-MM-DD.md

# boundary snapshots
memory/snapshots/YYYY-MM-DD/<slug>.md

Anti-patterns

• Storing full raw transcripts in semantic memory
• Treating all memory as one flat list
• Letting conflicting semantic entries stack without consolidation
• Skipping checkpoint writes before compaction
• Using only one trigger type (count/time/event) for all workloads

Next Steps

• Memory Types
• memories session
• memories compact
• openclaw memory (optional file-mode implementation)