# Agent Memory

*Notes you can read and edit are the truth. Indexes are a cache you can throw away.*

> **Agent Memory** = **notes you can read and edit** + **indexes you can throw away at any time**. Every note cites its sources; indexes (full-text, vector, graph, outline) are only derivatives of the notes; and background maintenance jobs only **propose** edits and never rewrite the raw journal.

**AN-07** · Conformance level: L2 Memory · Cluster: Knowledge

## The problem

Memory frameworks put memory in opaque databases: you cannot inspect, diff, migrate or correct it, deleting it reliably is hard, and the index and the embedding model are locked in. And memory itself is an attack surface: in one [2026 study](https://arxiv.org/abs/2606.04329) persistent-memory poisoning reached an average attack success rate of 50.46% across two agents, and [another study](https://arxiv.org/abs/2607.05189) used one carefully crafted email to succeed against both file-system and vector memory backends.

Meanwhile, “which memory architecture is best” is nowhere near settled: benchmarks contradict each other. A design that bets on no particular retrieval algorithm is the one that can survive three years of change.

## How it works

- **Notes are the truth.** Markdown with YAML frontmatter: `kind` (episodic, semantic, procedural, preference), `subject`, `sources`, `confidence`, `valid_from`, `valid_to`, `supersedes`, `origin`, `reviewed`.
- **Update, do not overwrite.** A new fact `supersedes` the old one; valid time and record time are kept apart, because facts change and common benchmarks barely test that.
- **Indexes are a cache.** BM25 (for example SQLite FTS5), vectors (several can coexist) and an optional graph; every derivative carries its **recipe** and **inputs**. Changing the embedding model is a background recomputation, and the old index is kept until the new one meets the golden recall tests.
- **Two kinds of derivation.** Deterministic ones (chunking, BM25, embeddings from a fixed model) are reproducible; generative ones (LLM summaries, extracted facts) can only be “regenerated and compared”, so they are marked `generated: true` and never serve as the only copy.
- **Write path.** `nas_remember` writes a note (with sources) to the current branch, and taint is inherited. A note from a session with `external` taint goes into **quarantine**, marked unreviewed: it can be recalled but is **not autoloaded** and does not enter `MEMORY.md`.
- **Read path.** `nas_recall` = search, candidates, a budgeted view plus evidence pointers, and it shows each note’s source and review state.
- **Maintenance jobs** (overnight or when idle): deduplicate, consolidate episodes into semantic facts, flag contradictions, retire outdated facts, rebuild indexes. Jobs produce proposals on a branch for a person or an agent to review; they **never delete the raw journal**; the “regret rate” (the share of proposals that get rolled back) is measured.
- **Golden recall tests.** For each Home, a set of “question, expected note” pairs that run automatically when the model or the indexer changes.

## Start small

- `memory/notes/*.md` with frontmatter, and SQLite FTS5 for search.
- Run ten golden questions in CI.
- Vector indexes and maintenance jobs can come later; get “provenance” and “only reviewed notes autoload” right first.

## Interface sketch

Illustrative only. Field names may change before specification v0.3.

*memory/notes/customer-acme.md*

```markdown
---
id: mem_4kq2
kind: semantic
subject: customer/acme
valid_from: 2026-10-02
valid_to: null
confidence: 0.8
origin: agent
reviewed: true
sources:
  - nas://home-box/agents/cleo/journal/2026-10-02.md@9f2c1de#L12-L18
supersedes: [mem_1xa9]
---
Acme renewed for 24 months; the champion moved from Dana to Luis.
```

## What the specification asks for

- Notes MUST be readable without the Memory layer (they are plain files in the Store).
- Every derivative MUST carry its recipe and inputs; an index MUST be disposable and rebuildable.
- Notes written by a tainted session MUST NOT be autoloaded before they are reviewed.
- A new fact MUST replace an old one with `supersedes` instead of overwriting.
- Maintenance jobs MUST work on a branch and only propose; they MUST NOT delete the raw journal.
- Every Home SHOULD carry golden recall tests and run them whenever the model or the indexer changes.

## Borrowed, and what is new

What follows is all established thinking, and OpenClaw’s memory architecture already does provenance labels, per-tier quarantine and taint propagation during consolidation. **What is new:** OpenClaw does it **inside one runtime**; we propose doing it **in shared storage** so any runtime benefits, and demoting the index to a disposable cache so the retrieval algorithm can change without losing memory.

- [Letta Context Repositories](https://www.letta.com/blog/context-repositories/)
- [Letta: is a filesystem all you need?](https://www.letta.com/blog/benchmarking-ai-agent-memory/)
- [OpenClaw memory architecture](https://docs.openclaw.ai/concepts/memory-architecture)
- [Long-term memory security survey](https://arxiv.org/abs/2604.16548)
- [Graphiti](https://github.com/getzep/graphiti)
- [MemGPT](https://arxiv.org/abs/2310.08560)

## Honest limits

- Generative derivatives can never be reproduced bit for bit.
- A maintenance job can “harden” a mistake into a fact, which is why it only proposes and never edits directly.
- Which memory architecture is best remains unsettled.

## Open questions

- When should an agent write memory itself, and when should a maintenance job?
- What is the regression standard across model versions?

## Questions

### Why files rather than a vector database?

Files are the truth you can read, edit, diff and take with you; a vector index is a derived cache that can coexist in several versions and be rebuilt at any time. Letta’s benchmark showed that an agent with just `grep` and file tools is competitive, but benchmarks contradict each other, so the design does not bet on one retrieval algorithm.

### How is memory poisoning prevented?

It cannot be guaranteed that nothing bad is ever written, but the consequences can be bounded: content from outside carries the `external` label; notes written by a tainted session go to quarantine and are not autoloaded; merges are reviewed; and when something goes wrong you can follow the provenance chain to the affected notes and roll back.

### Do I have to migrate memory when I change the embedding model?

No. The notes do not change; only the indexes are recomputed in the background with the new recipe, and the old index is kept until the new one meets the golden recall tests.

## Related concepts

- [Budgeted Reads](https://agentnas.com/concepts/budgeted-reads/): Read a file as an outline, a section, a line range or in full, degrading to fit the budget.
- [Cascade Forget](https://agentnas.com/concepts/cascade-forget/): Delete derivatives along lineage, handle history by retention class, and report what it could not do.
- [Trust Labels](https://agentnas.com/concepts/trust-labels/): Two small labels plus session taint enforce the Rule of Two.

---

Canonical URL: https://agentnas.com/concepts/agent-memory/
Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0