agent-memory

How an Agent persists and retrieves information across sessions. Per tw93 in 2026-04-27-agent-principles-architecture-engineering: Agents don’t have native temporal continuity — when a session ends, context is gone, and the next session won’t auto-restore prior state. Cross-session consistency has to be designed; it isn’t a bolt-on capability.

Four memory types — by the problem, not by the medium

The source slices memory by what problem each kind solves, not by where it’s stored:

Working memory is the only one inside the loop. The other three sit on disk and get pulled in selectively.

MEMORY.md is the load-bearing primitive

Two takeaways from the production examples in the source:

ChatGPT’s four-layer memory (per the source’s read of OpenAI’s implementation) — no vector DB, no RAG:

OpenClaw‘s hybrid approach:

• memory/YYYY-MM-DD.md — append-only daily log, raw detail preserved
• MEMORY.md — Agent-curated fact set, hand-shaped
• memory_search — 70% vector similarity + 30% keyword score

The shared insight: markdown + simple retrieval is enough at small/medium scale. Reach for vector retrieval only when memory grows past a few thousand items and semantic-similarity matching is genuinely needed. The cost of vector store + RAG infrastructure is non-trivial and is rarely the bottleneck at the start.

Consolidation, not deletion

The trigger pattern from the source (illustrated for OpenClaw):

tokenUsage / maxTokens >= 0.5  →  trigger consolidation

Success path:
  llmSummarize(toConsolidate) → append to MEMORY.md → advance lastConsolidatedIndex

Failure path:
  write toConsolidate to archive/  → preserve full history

Two emphases worth keeping:

1. Consolidation moves messages out of active context, doesn’t drop them. The archive path catches summarization failures so context isn’t lost on a bad LLM call.
2. The lastConsolidatedIndex pointer is what advances — not a destructive cut. Earlier messages remain on disk; the Agent can still query them.

This is the same instinct as using the file system as the context interface (context-engineering): instead of dropping content when the budget tightens, write it to disk and let later turns retrieve it.

What compaction loses if you don’t pin it

LLMs compressing context preferentially drop things that look re-fetchable — typically old tool output. But the architecture decisions and constraint rationale embedded around that tool output go with it. The fix is to declare priority order explicitly in CLAUDE.md (or equivalent), e.g.:

### Compact Instructions

保留优先级：
1. 架构决策，不得摘要
2. 已修改文件和关键变更
3. 验证状态，pass/fail
4. 未解决的 TODO 和回滚笔记
5. 工具输出，可删，只保留 pass/fail 结论

Don’t change identifiers during compaction. UUIDs, hashes, IPs, ports, URLs, filenames must survive byte-identical — one digit off in a PR number or commit hash breaks every downstream tool call.

Five session-management branches

Compression is a passive backstop. The source lists five active strategies (originally Claude Code team’s framing):

Source recommendation: when a path goes wrong, rewind and re-prompt from the last-good turn — don’t try to correct in place.

Anti-patterns

• Memory layer wired to a vector DB before the corpus is large enough to justify it.
• MEMORY.md left to the model to grow autonomously, with no human review path — drifts into junk.
• Compaction with no priority pins — architectural decisions silently lost.
• Treating “session length” as the only memory dimension; ignoring procedural (claude-skills) and semantic separation.

Lineage — the 2023 human-memory taxonomy

The four-types frame above didn’t appear from nowhere. Lilian Weng‘s 2023 survey (2026-06-04-llm-powered-autonomous-agents) already mapped agent memory onto the human memory taxonomy:

So the modern engineering frame is essentially Weng’s human taxonomy with sensory memory dropped, re-applied to file-backed storage instead of a vector store. The one place the two diverge is the default substrate: Weng’s 2023 equation was “long-term memory = external vector store + fast retrieval (MIPS)” — exactly the assumption the 2026 sources push back on (markdown + simple retrieval beats a vector DB at small/medium scale; ChatGPT’s production memory uses no RAG at all).

Why long-term memory benchmarks barely exist (Yao 2025)

Shunyu Yao’s The Second Half singles out long-term memory as the canonical example of real capability the field has no benchmark for. The reason isn’t that memory is hard to evaluate — it’s that the dominant evaluation frame (independent, identically-distributed tasks averaged into a single number) structurally cannot see memory’s contribution. A Google SWE accumulating familiarity with the google3 repo over weeks is invisible under that frame; a SWE-agent solving 500 issues in the same repo without gaining any such accumulation looks identical to one that does.

So the four-memory-types frame above (working / procedural / episodic / semantic) is engineering ahead of what current evals can reward. The implementation patterns (MEMORY.md, memory_search, daily logs, ChatGPT’s four-layer scheme, OpenClaw’s hybrid retrieval) all assume the i.i.d. eval frame is the wrong one and that real workflows are sequential. Per Yao, the missing piece is benchmarks where memory across tasks is the load-bearing variable — and his broader prescription applies: invent the eval setup, then solve it with the recipe. Cross-link agent-evaluation‘s utility problem section and long-running-agents‘s parallel framing of the same gap.