Why agent memory is startingto look like a set of files Agent 的记忆为什么越来越像一套文件

Soon after we started building seenzus, we ran into a question we could not dodge: how should an agent remember a place it may live in for years? People should not have to repeat “I run cold” or “leave the ceiling lights off when the projector is on” every time they start a conversation. But the obvious alternative is not much better. If we keep a running summary of everything the agent has learned and inject it into every turn, old conclusions linger, one resident’s information can leak into another resident’s context, and the summary can become a second interpretation of facts rather than a record of them. For a product that can turn on lights, change the temperature, and close blinds, a bad memory is more than an awkward answer.

At first, we treated knowledge-base RAG, vector retrieval, AGENTS.md, CLAUDE.md, and progressive disclosure as competing options. That framing did not survive contact with the implementations. They solve different parts of the problem. Vector retrieval is good at finding relevant fragments in a large body of material. Readable files are a better home for durable knowledge that needs to be summarized, corrected, or removed. The implementations we examined are splitting those jobs apart. Retrieval still matters for large corpora. It simply no longer needs to carry the full meaning of “memory.”

Claude Code, OpenAI Codex, and Nous Research’s Hermes Agent have all moved in this direction, though each brings memory into the current context differently. seenzus has another complication. A space belongs to more than one person, and memory can shape actions in the physical world. Some boundaries are too important to leave to model judgment alone.

The mechanisms described below come from official documentation or source code pinned to specific commits, checked on July 29 and July 31, 2026. The sources are listed at the end. We do not have reliable data on which approach was most popular at any point, so we treat that part of the story as our own observation rather than an industry fact.

Vector retrieval is still useful but it no longer owns the whole problem

RAG is now often used as shorthand for “chat with a knowledge base.” The original paper was narrower: combine model parameters with a vector index of Wikipedia to solve knowledge-intensive tasks such as open-domain question answering. “Memory” in that paper meant external world knowledge. It did not distinguish public knowledge from facts about one person, and it had no semantics for user-scoped writing, correction, or forgetting.¹

Early LLM applications quickly applied the same machinery to conversation. Many of them worked with context windows of only a few thousand tokens, and models struggled to maintain a coherent long-term record. A common pattern was to split previous conversations into chunks, store embeddings, retrieve chunks related to the new message, and place them back in the prompt.

LangChain’s route change is easy to see. It added vector-store memory in 2023, later deprecated it, and eventually removed the old memory module from the current codebase. Within LangChain, vector retrieval is no longer the recommended abstraction for conversational memory.² That does not prove vector memory disappeared from the industry.

Vector retrieval remains a sensible way to search a large body of material. Hermes still offers an external memory provider that performs vector recall on every turn. The storage design in seenzus also leaves room for vector retrieval. The change is in the division of labor. Retrieval can find related material, but it does not decide whether an old preference is still true. It also does not know that “you remembered that wrong” should revise a prior belief rather than sit beside it as one more chunk.

Two studies from 2023 were already working on that gap. Generative Agents combined stored experience with dynamic retrieval, then periodically reflected on and distilled what the agent had observed. MemGPT borrowed tiered storage from operating systems and moved information between a limited context window and external storage. Storage, maintenance, and context composition were becoming separate design problems.³

AGENTS.md and CLAUDE.md put memory back into files people can read

The next approach looked almost too simple: write what the agent should know in Markdown and let it read the file. CLAUDE.md became visible with the Claude Code research preview. Later that year, AGENTS.md described itself as “a README for agents” and was adopted by Codex, Jules, Cursor, Gemini CLI, and other tools.⁴

Files give facts about a project or a user a stable, readable home. Changes can live in version history. Compared with a collection of conversation fragments in a vector store, a team can inspect one file and point to the line that is wrong.

The cost is just as plain. At launch, Claude Code fully loads the CLAUDE.md files it finds from the working directory upward. Files in subdirectories enter context later. Anthropic recommends keeping each CLAUDE.md under 200 lines and moving multi-step procedures or local material into skills or path-scoped rules. A long startup file spends tokens and makes the important lines harder to notice.⁵

Progressive disclosure keeps the entry point resident and the details elsewhere

A file does not need to be resident in the current context simply because it is durable. The system can keep a small index, summary, or compact library within a hard budget, then read full details only when the current task calls for them.

The idea predates the current terminology around agents. MemGPT applied an operating-system paging analogy to context, while “progressive disclosure” came from interaction design. Anthropic later made it a design principle of Agent Skills: names and descriptions stay available, the body of SKILL.md is read after a skill is triggered, and supporting files sit another layer down.⁶

In a memory system, that entry point might be an index, a summary, or a small block of full text with a hard capacity limit. All three implementations we examined budget resident content, though they disagree on whether details should be fetched later. The more durable agreement is not a particular file layout. It is that long-term storage should not enter every context window unchanged.

Models are beginning to maintain the memory themselves

Then models started writing. Information that once depended on a person or a fixed pipeline can now be extracted, merged, and corrected by the model. The files are no longer static notes waiting for a human edit.

The three products maintain memory at different times. Claude Code writes during normal work. Codex batches recent conversations in the background. Hermes lets the foreground agent write and also runs periodic background reviews.⁷

None of the vendors treats autonomous maintenance as a solved problem. When we checked, Codex local memories were still disabled by default.⁸ A model can write the wrong thing or fail to retain something that mattered. Capacity, triggers, and write boundaries still come from deterministic code around the model.

These layers still coexist: retrieval handles recall, files hold inspectable knowledge, progressive disclosure controls the current context, and models take on some of the editing work.

The files look similar but the context paths do not

All three products use files as the main carrier, let a model participate in maintenance, cap resident content, and give users some way to inspect or disable memory. Their real disagreement appears at read time: what is already present when the session starts, and what the agent must choose to fetch.

	Claude Code auto-memory	OpenAI Codex local memories	Hermes Agent
What it records	Build commands, debugging lessons, architecture notes, and style preferences selected by the agent	Durable knowledge extracted from rollout logs; reusable procedures move into skills	Declarative facts only, with preferences and corrections favored; procedures move into skills
How it is organized	Repository-level directory with a MEMORY.md index and topic files	State DB plus raw_memories.md, rollout summaries, a MEMORY.md registry, and memory_summary.md	Two files, MEMORY.md and USER.md, split into § entries
When it enters context	First 200 lines or 25 KB of the index at startup; topic files on demand	A summary of at most 2,500 tokens stays resident; registry and evidence are looked up as needed	Full text is frozen into the system prompt at session start, with default limits of 2,200 and 1,375 characters; an optional provider can recall each turn
How it is maintained	The main agent reads and writes during work	A two-phase background extraction and consolidation pipeline triggered at startup and while idle	A foreground memory tool plus a background review every ten user turns by default
What it may influence	Kept separate from CLAUDE.md instructions	Team constraints remain in AGENTS.md or other versioned documents; memory must be checked for staleness	Facts belong in memory, procedures in skills; writes can require approval

Mechanisms checked on July 29, 2026. Claude uses rolling documentation; Codex and Hermes are pinned to fixed versions. See note 7 for versions and sources. Future versions may behave differently.

The “when” row carries most of the architectural difference. Claude uses an index for progressive disclosure. Codex keeps a projection resident, then returns to the registry and evidence when necessary. Hermes skips the index. It freezes a very small complete store at session start, refuses further writes at capacity, and gives all entries back to the agent to reorganize. The three products all use files, but they implement three different forms of context engineering. Public material is enough to compare mechanics. It is not enough to compare recall quality under the same workload, because none of the vendors has published that evaluation.

The public mechanisms in all three systems also distinguish memory from instruction. Claude separates auto-memory from CLAUDE.md. Codex keeps strong team constraints in AGENTS.md or other versioned documents. In the Hermes version we checked, facts go into memory and reusable procedures into skills. Learning that something happened does not mean the agent must obey it forever. For a coding agent, that keeps information and rules from blurring together. For an agent that controls devices, the distinction is a safety boundary.

The default boundary for a coding agent breaks down in a physical space

The local memory in these systems is organized around a git repository, $CODEX_HOME, or a local profile. Each roughly describes “this person on this machine.” That is a good fit for a development tool. If the agent remembers the wrong build command, the user can usually fix it in a later session. We did not find a request-scoped Account × User × Site/Space authorization model in the public material. The products do not need to manage several residents, changing access to rooms, or device actions.⁹

A smart space has all of those problems at once. One keeper serves several members, but each person still has private information. An Account may contain several Sites, and each Site may contain several Spaces. Access can be granted or revoked at any time. The agent also does more than write a reply. It can turn on a light, change the temperature, or close a blind. A missed memory makes the product feel forgetful. A boundary failure can expose someone’s routine or let an old preference outweigh a clear instruction given today.

seenzus keeps file memory and moves its boundaries outside the model

seenzus also keeps durable memory in Markdown files. The agent maintains the prose, including uncertainty expressed in ordinary language rather than a precise-looking score field. A request keeps only the visible boundaries resident and reads the actual memory when a decision needs it. The difference is who enforces scope. Coding agents do not need the boundaries described below, so we implement as much of that work as possible in deterministic systems instead of asking the model to remember the rules every time.

First decide whether a fact belongs to a person or a place

Personal Memory belongs to a User and follows that person across Accounts. Environment Memory belongs to an Account and is scoped to a Site × Space. Our routing question is short: would this still be true in a different home, studio, or shop? “I prefer 26°C” follows the person, so it is personal. “Use warm light in this living room at night” loses its meaning elsewhere, so it belongs to the environment. When the answer is unclear, we keep the memory private.

Shared memory also has a content boundary. Inferences about a person’s body, health, mood, or whereabouts do not go into Environment Memory. A space has one keeper. It can read the preferences of several members and resolve conflicts, but we do not create a separate keeper for each person and leave them to disagree in isolation.

Rebuild the visible memory map for every request

Every request to the Conversation Agent receives a fresh Memory Index. The index lists only the boundaries visible at that moment. The personal axis has at most one entry. The environment axis contains each authorized Site · Space that has memory content. The index contains no facts, summaries, or filenames.

The system computes this map from current permissions, uses it for one request, and does not cache it. If either the personal or environment axis fails to resolve, that part of the map is omitted rather than replaced with a stale copy; the other axis remains available when it is still valid. When a member loses access to a Site, that Site disappears from the next request, including any hint that the Site exists. This boundary is applied on every request rather than left for the model to remember. The agent reads a full memory boundary only when the current decision needs it. The index itself is never a source of facts.

Start maintenance from evidence instead of a timer

A single device event does not wake a maintenance model. The system aggregates and deduplicates events, then compares the result with the evidence processed last time. Only when the Evidence Gate decides that the new batch might change existing knowledge does the model receive a bounded set to review.

Existing memory does not fade merely because time passed. A belief changes when new evidence conflicts with it. The wording of provenance also limits what the system may do. If a resident explicitly stated a preference, later behavior cannot silently replace it. The system may record the conflict, but it waits for another explicit statement before deleting or rewriting the original. Forgetting removes a current record. It does not prevent the system from learning the same fact again. If a resident says “do not remember my routine,” that instruction becomes a personal preference, and later maintenance must honor it.

Memory can inform an action but it can never authorize one

Memory may help the agent perform an already permitted action in a more suitable way. Permission itself comes only from the current request, a Policy, or an approval path. The system applies this boundary with the Memory Index on every request instead of relying on the model to remember it.

Some risks remain soft boundaries. Routing writes between the personal and environment axes still involves model judgment. A deterministic visibility boundary cannot prove that the model will always find, cite, or update the right memory. We still need evaluations for missed reads, bad citations, and boundary violations.

In daily use, memory should mean less explaining and less reason to worry

When someone says “make this room comfortable,” the keeper can combine Environment Memory for the current Space with the person’s preferences and interpret “comfortable” as roughly 26°C with warm light. It should not answer with a questionnaire.

If the same person says “set this room to 22°C,” the explicit instruction wins. A historical preference cannot override a complete current request. If permissions changed yesterday, the visible memory map must change today.

Correction should also sound like conversation. “You remembered that wrong. I do not run cold” is the strongest form of evidence. The keeper should say the memory is fixed only after the write has reached storage. Nobody should need to hunt through settings for a memory toggle just to correct one sentence.

These are design goals derived from the mechanism, not results from user research. We can verify that the request-scoped view changes with current permissions. We do not yet have evidence that people living with seenzus feel better understood. Answering that question requires the product to run in real spaces for long enough to accumulate useful mistakes and corrections.

Memory design should follow the agent’s lifespan and risk

Before choosing a memory architecture, ask how long the agent will live, whom it serves over that time, and what a wrong memory can cause.

A one-shot question-answering agent may not need durable memory at all. When it works over a large body of material, retrieval may be enough. A development agent that serves one person over time can combine files, a context budget, and model maintenance. Claude, Codex, and Hermes show three workable versions. When the user becomes a group and the agent can act in the physical world, the file substrate still works, but the system must say whose memory is visible in which place and how far that memory may influence action. The current seenzus design is our answer to that narrower problem.

Evaluation is the missing piece. The three context strategies have no comparable public recall data. seenzus can define scope but not prove semantic quality. Vector retrieval may eventually return inside one of our memory boundaries. Once we have those results, we expect parts of today’s design to change.

---

Notes and sources

1. Lewis et al., Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks, arXiv:2005.11401, May 22, 2020.↩
2. VectorStoreRetrieverMemory was introduced in PR #2804 on April 13, 2023. In langchain==0.3.27, it was marked deprecated since 0.3.1 with removal planned for 1.0.0. When checked on July 31, 2026, the master branch no longer contained the old langchain/memory/ directory.↩
3. Park et al., Generative Agents, April 7, 2023; Packer et al., MemGPT, October 12, 2023.↩
4. Claude Code launched as a research preview on February 24, 2025. The AGENTS.md specification repository received its first commit on August 19, 2025.↩
5. Anthropic, How Claude remembers your project, checked July 31, 2026. The documentation recommends fewer than 200 lines per CLAUDE.md and distinguishes startup loading, on-demand subdirectory loading, path-scoped rules, and skills.↩
6. Nielsen Norman Group, Progressive Disclosure, December 4, 2006; Anthropic, Equipping agents for the real world with Agent Skills and Introducing Agent Skills, October 16, 2025.↩
7. Claude Code is based on its rolling documentation. OpenAI Codex is based on the Memories documentation and source commit 406dc923…. Hermes Agent is based on the Persistent Memory documentation and source commit 5a23e3c5…. Mechanisms checked July 29, 2026.↩
8. OpenAI’s Memories documentation stated that Local Codex memories were off by default and had to be enabled by the user. Checked July 29, 2026.↩
9. The scope comparison comes from each product’s public storage documentation and pinned source, with versions listed in note 7: Claude by git repository, Codex under $CODEX_HOME, and built-in Hermes memory by local profile. The public material did not show a request-scoped Account × User × Site/Space authorization model. This describes the evidence we could inspect, not an assertion about undisclosed internals.↩