Agent Memory as Hint Surface
What it is
Agent memory should be treated as a hint surface, not an authority surface. A memory record says “this was true or useful at some point”; it should guide retrieval and action, but concrete claims about files, functions, flags, preferences, or workflows must be verified before being used as current truth.
Why it matters
Memory systems fail when old records silently become instructions. Claude Code’s strongest design lesson is not a storage format; it is verification discipline. Indexes can be always visible, bodies can be lazy-loaded, and every body read should remind the agent to verify stale claims before acting.
Evidence across sources
- Nic’s audit compared Hermes, Codex, and Claude Code memory systems and found that simple filesystem-based memory beat over-engineered vector/graph memory in practical agent workflows.
- Claude Code treats memory as files plus age-aware reminders, making stale records visible at use time.
- Codex separates live work from delayed memory consolidation and cites memory usage, while Hermes freezes memory snapshots for prefix-cache stability.
Design principles
- Index always visible, body lazy-loaded：agent can know what memories exist without loading every detail.
- Verify on read：file paths, functions, flags, and preferences are claims from a past moment.
- No dynamic memory in system prompt：changing system prompt bytes destroys prefix cache economics.
- Simple stack first：LLM + Markdown + filesystem tools is often easier to debug than vector DB + graph + background agent.
- Signal gate writes：default to no-op unless a memory is clearly worth keeping.
Open questions
- Should the vault adopt explicit age reminders for old
ai_draftpages and memory-like notes? - How should memory records be demoted or expired without losing useful searchability?
- Can wiki
knowledge_statusplay the same role as memory freshness reminders?