Field note / agent state

Agents Do Not Need More Memory. They Need Better State.

The useful question is not whether an agent has memory. It is what state crosses the boundary between two runs, and why the next run should trust it.

agent memory =
  write policy
+ store
+ retrieval policy
+ validation loop

Split The Word

Most memory discussions mix context, compaction, durable memory, and learning. They are different mechanisms with different failure modes.

Mechanism	What it means	Examples	Common failure
Context	What the model sees now	prompt, files, tool output	too large or stale
Compaction	What survives context pressure	session summaries	lost intent
Durable memory	External state reused later	preferences, repo rules, skills	stale authority
Learning	Changed model or policy	weights, fine-tuning	usually not present

context pressure    = keep this run alive
session continuity  = keep this task coherent
durable memory      = change what a future run can know

Do not use long-term memory to solve context overflow. Use compaction for that. Durable memory starts when the harness decides state should cross a session boundary.

The Pipeline

A memory system is good only when a future action changes correctly, with source, scope, and deletion still intact. Each edge is policy.

event -> capture -> extract -> classify -> scope -> store
store -> retrieve -> inject/cite -> act -> validate -> merge/prune/delete -> store

Stage	Decision	Bad default
Capture	What is a candidate?	save everything
Extract	What stable signal exists?	summarize vaguely
Classify	rule, fact, preference, episode, skill?	flatten into notes
Scope	user, repo, project, org, tool?	global memory
Store	which data structure?	one vector index
Retrieve	what enters context now?	top-k similarity
Validate	is it still true?	trust old state
Delete	where must it disappear?	delete one visible note

memory enters context only through retrieval policy
memory changes action only after validation policy

Authority

A memory is not authoritative just because it is in context. Required team behavior belongs in checked-in files: AGENTS.md, CLAUDE.md, runbooks, CI config, repo docs. Generated memory is useful recall. It is not policy.

Source	Authority	Treatment
Checked-in docs/code/config	High	source of truth
Cited current repo fact	High-medium	use with citation/branch validation
Human-authored memory	Medium	instruction or hint
Generated memory with source	Medium-low	validate before action
Generated memory without source	Low	hypothesis
Similar retrieved memory	Hint only	use to search, not decide

memory can suggest
source of truth decides

System Archetypes

Archetype	Always loaded	Retrieved on demand	Write path	Examples	Failure
File-first	summary/index	files, grep, daily notes	agent writes or consolidation	Claude Code, Codex, OpenClaw	index cliff
Frozen prompt + search	tiny profile	transcript search	add/replace/remove, async sync	Hermes	snapshot lag
Managed resource	mount metadata	filesystem/API	versioned writes, API edits	Anthropic Managed Agents, AgentCore	writable memory injection
Product memory	user/repo profile	product recall	saved/inferred facts	ChatGPT, Gemini, Copilot, Devin	weak provenance
External semantic/graph	little or none	semantic search, graph traversal	API/tool writes, ingestion	Mem0, Zep, GBrain, Letta	governance sprawl

RAG:          query -> top-k chunks -> answer
graph memory: query -> retrieve -> connect -> synthesize -> cite -> expose gaps

external memory output = claim + citation + freshness + missing information

System Details

System	Mechanism	Detail	Risk
Claude Code	file-first instructions + auto memory	CLAUDE.md is human-authored instruction memory. Auto memory uses repository-scoped Markdown with MEMORY.md as the startup index and topic files loaded on demand.	Index cliff: memory exists on disk but becomes undiscoverable.
Codex	file-first generated memory	Writes are model-heavy and async: extraction first, consolidation later. Reads are cheap: inject a bounded summary, then search MEMORY.md, rollout summaries, and skills only when useful.	Write/read asymmetry can hide stale paraphrases.
OpenClaw	workspace Markdown + live context inspection	Durable MEMORY.md, daily notes, optional DREAMS.md, hybrid memory_search, compaction, memory flush before compaction, and /context list/detail for live prompt inspection.	Confusing disk memory with live prompt context.
Hermes	tiny frozen prompt + search	MEMORY.md is limited to 2,200 characters; USER.md to 1,375. Both are frozen at session start. Detail moves to SQLite FTS session search or one active external provider.	Snapshot lag after writes.
Anthropic Managed Agents	mounted governed resource	Memory stores mount under /mnt/memory/, support read-only/read-write access, optimistic concurrency, immutable versions, redaction, 100 kB memories, 2,000 memories per store, and up to 8 stores per session.	Writable memory can persist prompt injection.
Anthropic Dreams	async consolidation job	Dreams read one memory store plus 1 to 100 sessions, then produce a separate output memory store for review, attach, archive, or delete. The input store is not silently mutated.	Unsafe consolidation if candidate state becomes live without review.
Mem0 v3	external scoped semantic memory	Async ADD-only extraction writes to scoped stores such as user_id, agent_id, app_id, or run_id. Entity linking and multi-signal retrieval move recall outside the harness.	Governance sprawl across stores and identities.
GBrain	hybrid graph retrieval	Combines vector search for paraphrase, BM25 for exact names, graph traversal for relationships, source ranking for authority, and reranking for false positives.	Graph edges can amplify stale or weakly sourced claims.
Copilot / Devin / Gemini	product memory	Product-mediated user or repo profile state: repository facts, saved preferences, knowledge items, generated wiki/search, and controls around viewing or disabling remembered data.	Weak provenance unless citations, expiry, and user controls are explicit.
AgentCore / Letta / Zep	managed or OS-style memory	These systems make the state layer explicit: namespaces, long-term strategies, tiered memory, archival recall, and temporal graph structure.	More structure means more deletion, privacy, and audit surfaces.

Anthropic Dreams safety shape:
input memory store + 1..100 sessions
  -> async dream
  -> separate output memory store
  -> review / attach / archive / delete

The input store is not mutated. Consolidation produces candidate state, not silent live-state edits.

The Contract

Start with the contract, not the database. no_op should be common. Most events should not become memory. Retrieval and injection are also different decisions: retrieval says "this might matter"; injection says "show this to the model with this authority."

propose(event) -> candidate | null
write(candidate, scope, source) -> memory_id | no_op
retrieve(task, scope) -> ranked memories
validate(memory, task) -> trusted | stale | conflict | hint
inject(memory, mode) -> prompt text with source/authority
update(memory_id, source) -> new version
delete(memory_id) -> tombstone + derived cleanup
explain(memory_id) -> source, scope, versions, retrieval path

type: rule | fact | preference | episode | skill | hypothesis
scope: user | repo | project | org | tool
source: citation_or_event_id
content: "Deployments happen from main only after pnpm build passes."
confidence: high | medium | low
last_validated_at: timestamp
expires_at: timestamp | null
access: private | shared | read_only | read_write
valid_when: "task involves deploy/release/push"
contradicts: [...]

One Lifecycle

Raw event: "Remember, this repo deploys from main only after pnpm build passes." Bad memory: "User prefers pnpm build." That turns a repo deployment rule into a vague user preference.

Step	Decision	Result
Capture	durable operational constraint	candidate
Extract	deploy requires main + pnpm build	normalized rule
Classify	repo rule, not user preference	type: rule, scope: repo
Store	save source/confidence/validation path	memory record
Retrieve	task mentions release/deploy/push	load deploy rules
Validate	check package scripts, CI, docs	cite or downgrade
Act	block unsafe deploy, run build	changed behavior
Update	deploy process changes	stale old rule, add new rule
Delete	user asks to forget	remove record + derived summaries

if task involves deploy/release/push:
  retrieve repo deployment rules
  validate against checked-in source
  cite before acting

The point is not that the agent remembered the sentence. It preserved type, scope, source, validation path, and changed a future action correctly.

Failure Modes

Failure	Symptom	Root cause	Mitigation
Index cliff	memory exists but is never opened	capped/stale index	test lookup paths
Undiscoverability	search misses it	lexical mismatch, vague names, missing edge	hybrid retrieval, aliases
Loaded-state confusion	file exists, model did not see it	store is confused with context	context inspection
Snapshot lag	write persists but not this turn	frozen prompt	expose effective time
Stale authority	old rule wins	no validation	source-of-truth checks
Poisoned memory	attack persists	untrusted write access	read-only stores, scanners, quoting
Scope leak	memory crosses users/orgs	weak identity model	namespaces + leakage tests
Delete failure	deleted fact returns	derived summaries/indexes survive	delete across stores
Over-consolidation	nuance disappears	summaries merge contradictions	candidate store + review

wrong thing written
right thing not found
found thing trusted too much

Evaluation

Bad benchmark: did the agent remember the user's favorite color? Better benchmark: did yesterday's experience change today's decision correctly?

Session	Test
S1	Teach a repo rule with source
S2	Ask unrelated task; memory should not distract
S3	Ask task where rule matters; memory should change action
S4	Contradict/update rule
S5	Ask again; current rule should win
S6	Delete rule
S7	Ask again; deleted rule should not resurface

minimum passing bar:
memory improves relevant action
memory does not distract unrelated action
updated memory beats old memory
deleted memory does not reappear

score:
action correctness
citation validity
stale recall resistance
deletion correctness
false-positive rate
latency/token cost
cross-scope leakage tests

MemoryArena is useful because it couples memory with action. Stompy's coding-agent benchmark is useful because it reports a modest result: memory reduced exploration on harder tasks, did not materially improve code quality, and hurt trivial tasks. Memory helps when rediscovery is expensive.

What Should I Use

Need	Use	Avoid
Team rules, commands, security constraints	checked-in docs: AGENTS.md, CLAUDE.md, runbooks	generated memory
User preferences	product/user memory with controls	repo memory
Current task continuity	compaction/session summaries	long-term memory
Current codebase facts	cited repo facts or regenerated docs	uncited semantic notes
Long-lived research context	hybrid search or graph memory	one prompt-loaded file
Cross-tool recall	external provider/MCP with scopes	copied local folders
Enterprise audit/isolation	managed memory with namespaces/versions/delete APIs	informal files
Relationship/time-heavy facts	temporal graph	plain chunks

rules in repo docs
small summary in prompt
details retrieved on demand
sources attached to claims
writes scoped by identity/project
delete path tested

Checklist

What memory types exist?
Which events can create memory?
Which writes require approval?
What is always injected vs retrieved on demand?
What is the source of authority?
How are stale memories detected?
How are contradictions represented?
What is the delete path?
What eval proves memory improves action?
How can the operator inspect what loaded this turn?
Do writes affect the current prompt or the next snapshot?
Are memories scanned for prompt-injection/exfiltration before becoming prompt text?

If these answers are vague, the system has retrieval, not memory architecture.

References

Local pasted research notes were used during drafting: mem0 State of Memory in Agent Harness; Troy Hua Claude Code memory-source analysis; mem0 Codex CLI memory-source analysis; mem0 Hermes memory source/vendor notes.