Agent Memory#

Design and implement memory systems that let agents survive context window rotation and maintain continuity across sessions.

Core Problem#

LLM agents have finite context windows. Memory is lost when:

• Session ends or rotates
• Context is pruned or compacted under pressure
• Summaries replace detailed history (lossy compression)

Durable memory is not a nice-to-have — it is the agent's continuity substrate.

Architecture Patterns#

Three dominant architectures for persistent agent memory:

1. CMA — Continuous Memory Architecture#

Agent maintains flat/hierarchical markdown files, reads selectively at boot, writes on state change. Best for: operational state, ongoing projects, agent identity.

• ✅ Simple, no infrastructure, version-controlled
• ✅ Human-readable and auditable
• ✅ Works in any OpenClaw deployment
• ❌ No semantic search without an embedder
• ❌ No temporal reasoning (fact validity over time)

This is the default pattern for OpenClaw agents.

2. Semantic RAG Memory#

Agent embeds facts into a vector store; retrieval uses embedding similarity. OpenClaw's built-in memory uses node-llama-cpp with 768-dim embeddings (all-MiniLM-L6-v2 compatible).

• ✅ "What do I know about X?" queries across large fact sets
• ✅ Better recall than text search for paraphrased queries
• ❌ No temporal validity — stale facts pollute results
• ❌ Requires embedder infrastructure

3. Temporal KG Memory (Graphiti/Zep pattern)#

Agent builds a knowledge graph with valid_at/ invalid_at on every fact edge. Graphiti (open source, wraps Neo4j) is the leading implementation.

• ✅ Handles "what was true at time T?" queries correctly
• ✅ Supersedes stale facts without deleting them
• ✅ Entity deduplication across episodes
• ❌ Requires Neo4j + LLM for ingestion (high latency, not real-time)
• ❌ Best used as async batch-ingest, not inline tool

Recommendation: Use CMA + semantic RAG for all agents. Add temporal KG only for high-value long-horizon use cases (months of state).

See references/memory-architecture.md for detailed comparison and deployment notes.

Memory File Structure (CMA Pattern)#

text

workspace/
├── HEARTBEAT.md          # Current pulse state (keep SHORT — < 40 lines)
├── memory/
│   ├── CORE_MEMORY.md    # Identity and continuity anchors
│   ├── GOALS.md          # Long-horizon aims
│   ├── OPEN_LOOPS.md     # Unresolved tasks and promises
│   ├── WORLD_MODEL.md    # Verified facts about environment
│   ├── CAPABILITIES.md   # Verified tools, channels, limits
│   ├── RUNTIME_REALITY.md # Live channel/mutation/config state
│   └── research/         # Durable research artifacts
└── operator-outbox.jsonl # Async operator messages

What Goes Where#

Fact typeFileWho I am, values, drivesCORE_MEMORY.mdCurrent open workOPEN_LOOPS.mdInfrastructure/env factsWORLD_MODEL.mdWhat tools/channels workCAPABILITIES.mdLive config/channel stateRUNTIME_REALITY.mdResearch findingsmemory/research/*.mdCurrent pulse stateHEARTBEAT.md

Temporal Annotation Convention#

Add [YYYY-MM-DD] timestamps to facts in memory files. Mark superseded facts explicitly:

markdown

- [2026-03-27] Telegram: enabled, account "Morrow Operator Bot"
  ~~[2026-03-20] Telegram: disabled~~ SUPERSEDED 2026-03-27

This is lightweight temporal KG discipline without a full graph backend. See references/temporal-discipline.md.

Boot Routine#

At every session start, an agent should:

1. Read HEARTBEAT.md (injected or explicit)
2. Check operator inbox for new instructions
3. For infrastructure/channel questions: read RUNTIME_REALITY.md (not older prose)
4. For open work: read OPEN_LOOPS.md
5. For nontrivial tasks: read CORE_MEMORY.md, GOALS.md

Never trust session transcript alone for state that should be in memory. Transcripts get compacted.

Compression Defense#

OpenClaw's lossless-claw plugin (or similar LCM) compacts older session history. Defend against lossy compression:

1. Write before you forget. Externalize important facts immediately, not at the end of a session.
2. Keep HEARTBEAT.md short. Long heartbeats get truncated first.
3. Use lcm_grep and lcm_expand_query to retrieve compacted history before answering questions about prior work.
4. Separate observation from inference. Memory files should state facts with source and date, not just conclusions.

Semantic Memory (OpenClaw Built-In)#

If OpenClaw's local semantic memory is active:

• memory_search(query) — semantic search across all memory files
• memory_get(path, from, lines) — safe snippet read

Use memory_search before reading memory files directly. It's faster, scoped, and context-efficient.

To verify semantic memory is active: check for memory_search in your tool surface. If absent, memory files must be read explicitly.

Graphiti Quick Setup#

For temporal KG memory (advanced use):

bash

# 1. Install
pip install graphiti-core --user --break-system-packages

# 2. Neo4j (persistent)
docker run -d --name neo4j \
  --restart=unless-stopped \
  -p 7687:7687 -p 7474:7474 \
  -v neo4j-data:/data \
  -e NEO4J_AUTH=neo4j/yourpassword \
  neo4j:5.26

# 3. Configure to use OpenClaw /v1 as LLM + embedder backend
# See references/memory-architecture.md for OpenClawLLMClient patch

Important: Graphiti's add_episode requires 5-10 LLM calls per episode. Use it via cron/batch job, not inline during agent pulses.