A few months ago I started using OpenClaw and found that among the things it brought to the Agent industry, the most exciting one besides scheduled tasks was a seemingly ordinary file: MEMORY.md.
This curiosity drove me to look through my local ~/.claude/ directory. As it turns out, the projects I frequently run with Claude Code /loop each have their own corresponding memory files. They aren't logs, READMEs, or session histories:
Looking at the memory files of several projects together, a question naturally arises: what exactly are they recording? Some are 'must-dos for the future,' some are 'current project status,' some are 'pitfalls encountered last time, don't repeat,' some are 'why we believe this conclusion,' and others are 'where the next loop should pick up.'
Agent Memory has actually evolved from 'storing chat logs' into a complete architecture. Rules, profiles, history, evidence, reflection, and skill accumulation each have their own storage methods, loading timings, and governance challenges. What this article aims to clarify is exactly what this architecture looks like as of mid-2026.
Who this article is for:
- Developers using or building Coding Agents, Research Agents, Personal AI Agents, or any LLM application that needs to work continuously across sessions;
- Technical decision-makers interested in agent architecture but who haven't yet figured out how to layer memory;
- Power users already using tools like Claude Code / Codex / OpenClaw / Hermes who want to understand what those memory files in their projects are actually doing.
I. Long Context Solves Current Tasks, Memory Solves Cross-Task Compounding
First, let's clarify a point many people confuse: Agent Memory is not a replacement for long context.
Context windows of 250K, 1M, or even longer are already standard. Long context is certainly important—it allows the model to see more files, logs, and evidence in the current task, avoiding information loss from frequent summarization.
But long context always solves the problem of 'how much can fit in this round.'
Memory solves a different problem: When the agent wakes up for the next round, does it still remember why it did things that way last time?
Context window is the workbench, where all materials needed for the current task are spread out; RAG and search are external libraries called on demand; Memory is the persistent state layer that exists across sessions, projects, and agents. The three have clear divisions of labor.
A coding agent with only long context and no memory will hit the same test environment pitfalls when a session is restarted next week. A research agent with only RAG can find past data but won't know which piece has been debunked or which source is unreliable for a specific topic. A trading agent with only transcripts can look back at all logs but can't distinguish which have been elevated to invariants and which were just accidental.
The core value of Memory isn't 'storing more,' but layering the past: what should be resident, what should be searched, what should be archived, and what should become a reusable skill for the future.
II. Layer 1: Rule Memory — The Agent's Working Constitution
The earliest widely used agent memory actually landed before any automatic memory system. It's the rule file.
Claude Code calls it CLAUDE.md, Codex calls it AGENTS.md. It is essentially a 'working constitution': how the project is built and tested, which directories are strictly off-limits, which commands must run in specific subdirectories, which code styles and commit rules cannot be broken, and which business red lines are more important than completing the current task itself.
The advantages are obvious: readable, modifiable, auditable, and can be put into Git. Teams can review it, CI can check it, and the agent sees it every time it starts.
But it has clear boundaries. Rule files are suitable for 'long-term stable things that should be followed every time,' not for stuffing in every historical detail. Piling every bug, experiment, and log into CLAUDE.md will eventually turn the context into a mass of low-density noise.
Claude Code's official documentation also clearly separates CLAUDE.md from auto memory: the former is human-written instructions and rules, while the latter is learning accumulated by Claude based on corrections and preferences. Codex similarly emphasizes that rules the team must follow should be in AGENTS.md or repo docs, while memories are just a local recall layer.
The first design principle is thus established:
Rules that must be followed should not just be placed in automatic memory. They should enter versioned rule files.
Rule memory is the first layer of agent memory. It solves 'how to do things from now on.'
III. Layer 2: Resident Profiles — Things That Pay a Token Tax Every Round
After rules come something more subtle: profiles.
The design of Hermes Agent has a lot of character in this regard. It built-in two files: MEMORY.md stores the agent's own high-density notes—environmental facts, project conventions, lessons learned; USER.md stores user profiles—preferences, communication styles, long-term expectations. These two files are injected directly into the system prompt when a session starts, and they have strict length limits: exceeding the limit doesn't result in silent compression, but an error, forcing the agent to merge, replace, or delete content itself.
This design is very restrained. But it's effective precisely because it's restrained.
Resident memory isn't better if there's more of it. It pays a token tax every round, and the earlier its position, the more likely it is to influence the model's judgment. If you stuff a large amount of unorganized history into resident memory, the agent becomes expensive and confused—like repeating every conversation from ten years ago to someone and expecting them to extract useful information.
Resident memory should only contain three types of things: Identity—who this agent is and its long-term responsibilities; Preferences—what this user consistently likes or dislikes; Invariants—facts that hold true repeatedly in the environment and will definitely be useful next time.
My own garden memory is very much like this layer. It doesn't record the full process of every article I write, but only facts like 'use wquguru for public handles, not private accounts,' 'AGENTS.md and .agents/skills are symlinks,' and 'garden deploy goes through Cloudflare Pages + Access'—facts that will definitely be needed next time.
Second design principle:
Resident memory should be short, hard, and high-density. History should not be resident; only compressed identity, preferences, and invariants deserve to be resident.
Profile memory solves 'what identity and stable preferences the agent should continue working with.'
IV. Layer 3: Historical Recall — Most Memories Shouldn't Be Resident, But Must Be Findable
So if most history shouldn't be resident, where does it go?
The answer is on-demand recall. Search it out when needed, and let it sit quietly on the disk when not.
Hermes uses SQLite FTS5 to save all CLI and messaging sessions, providing session_search. It preserves original messages completely without information loss from summarization, and allows scrolling back and forth through the session for context.
OpenClaw designs the workspace more like a file system memory: MEMORY.md is the refined layer, memory/YYYY-MM-DD.md contains daily notes, and DREAMS.md stores offline thinking outputs. memory_search and memory_get are responsible for recall, and with an embedding provider, it can perform hybrid vector + keyword searches.
Codex's Memories follow this path as well—turning stable preferences, workflows, tech stacks, project conventions, and known pitfalls from old threads into local memory files to be brought in as needed for future tasks.
A consensus is forming: Separate 'resident memory' from 'historical recall.' Resident memory is like an index page—very short. Historical recall is like a library—very large. Search is responsible for precisely pulling out local fragments from the library when needed.
Returning to the carrywatch in the initial image—its MEMORY.md is an index page, about a dozen lines, each pointing to a topic file. binance-funding-interval-bug.md records the root cause, scope of impact, fix commit, verification method, and unresolved issues. clock-domain-and-health-freshness.md records a full analysis of a counter-intuitive bug where the macOS monotonic clock froze during sleep while the wall clock continued, leading to 'data stale for 6.6 hours but health status still green.'
Injecting these files into the prompt every time is a waste, but losing them entirely means the agent has to start from scratch next time. Thus, they are best suited as on-demand historical memory.
Third design principle:
Historical memory should be searchable, traceable, and partially readable, rather than entirely resident in context.
Historical recall solves 'what exactly happened in the past and why those judgments were made at the time.'
V. Layer 4: Evidence Chains and State Governance — Remembering Conclusions Isn't Enough; Remember the Basis
Truly difficult memory is remembering the source of a conclusion.
Agents too easily treat a summary as a fact, a guess as experience, and a temporary workaround as a long-term rule. Once memory becomes long-term, errors also become long-term—and they are the kind that get harder to find the longer they last and harder to correct the more confident the agent becomes.
This is why I care more and more about the structure of memory files.
A qualified bug memory shouldn't just say 'fixed'; it should be like a miniature postmortem: what was the problem, where is the evidence (the official field actually comes from fundingInfo rather than the premiumIndex response), what was the impact (4-hour symbol APR underestimated by 2x, 1-hour by 8x), how was it fixed, how was it verified, and what remains unresolved (last-settled and predicted funding semantics are still inconsistent).
Compared to ordinary notes, this is more like auditable engineering memory.
The memory of the trader project illustrates this even better. It doesn't just simply record 'Bitget demo connected,' but writes the boundary red lines between demo and real accounts, fee symbols, settlement invariants, deploy topology, Grafana panels, and authorization changes that are committed but not pushed—all into memory.
Why record these? Because they constitute state governance. If a long-running agent doesn't know 'which changes involving fund settlement require upgrade confirmation,' it will act on error boundaries no matter how strong its coding ability is. If an autonomous loop doesn't know 'only local commits are allowed, no pushing,' it might push a change that is technically correct but procedurally wrong to the remote.
Therefore, agent memory must include a category called governance memory: permission boundaries, risk red lines, environment topology, deployment processes, verification gates, current running state, and why the last decision held true.
This type of memory cannot rely solely on vector recall. It needs clear structure, explicit state, and human-auditable sources.
Fourth design principle:
Agent memory is also a governance system. It must manage sources, confidence, expiration, permissions, and deletability.
VI. Layer 5: From Recall to Reflection and Skill Accumulation — Where Memory's Compounding Interest Lies
What we've discussed so far is still mainly recall—remembering rules, profiles, history, and evidence.
But the true watershed for agent memory is the next layer: self-evolution.
Recall is just remembering what happened in the past. Reflection is summarizing why the past succeeded or failed. Skill extraction is turning repeatedly successful paths into reusable processes. Dreaming is organizing offline during idle time, rather than temporarily stuffing things into context during every online round.
OpenClaw's dreaming, Hermes' post-turn self-improvement review, Claude Code's auto memory, and EverOS's agent cases and skills are all essentially moving in this direction.
The 'backtesting framework and strategy economic conclusions' in the trader project are already close to experience accumulation. It organizes experimental conclusions from multiple time windows, multiple targets, and multiple sets of parameter grids into strategy judgments: high turnover with weak signals is structurally net negative, reducing turnover is the core lever, narrow samples easily lead to misjudging a strategy as failing, and only a wide enough pool and longer windows show stability; backtesting data sources must be closed-loop with real exchanges.
If these things only stay in chat logs, the agent will start from 'let's run it once and see' next time. Once settled into memory, the next round can start directly from a higher level—which parameters are worth scanning, which verifications can't be skipped, and which early conclusions have been corrected by subsequent samples.
This is the true compounding interest of memory.
Fifth design principle:
The endgame of agent memory is not 'remembering more,' but making fewer of the same mistakes and faster reuse of things done right.
VII. Comparison of Memory Architectures Across Four Applications
Looking at Claude Code, Codex, OpenClaw, and Hermes together, application-layer memory is clearly differentiating into four layers:
- Rule Layer: CLAUDE.md / AGENTS.md, suitable for project conventions that must be followed.
- Resident Layer: MEMORY.md / USER.md, suitable for high-density identity, preferences, and invariants.
- History Layer: session search, daily notes, topic files, suitable for large amounts of facts, evidence, and processes.
- Evolution Layer: dreaming, reflection, skills, responsible for turning historical experience into default capabilities for future actions.
True mature agent memory is a combination of these four layers. No single file or vector database can support it alone—just as you can't expect to manage the entire state of an operating system with only one data structure.
VIII. Why EverOS Hit the Mark on This Direction
EverOS designs memory as a developer-facing runtime—a structure that developers can directly read, write, debug, and version, rather than guessing what is stored in a black-box recall layer across an API.
Several of its designs align perfectly with the aforementioned layering:
- Markdown as source of truth: Memory is saved to disk as readable, modifiable, grep-able, and Git-versionable files.
- SQLite + LanceDB: Markdown is the true source, SQLite manages state, and LanceDB manages vectors, BM25, and scalar filters.
- Dual-track memory: User memory and agent memory are separated; episodes/profiles and cases/skills are not mixed.
- Multimodal ingestion: Text, images, audio, PDF, HTML, and email can all enter a unified memory layer.
- Self-evolution: Cases from real use can be settled into skills.
- Orthogonal retrieval: Retrieval by dimensions of user_id, agent_id, app_id, project_id, and session_id.
If memory is only in a remote black box, developers will never know what the agent remembered, why it recalled a certain piece, when it should be deleted, or what has expired. If memory is Markdown, the first step at least becomes simple: you can open it, read it, diff it, change it, put it in Git, and hand it to another agent.
This isn't the final answer. But it's the best engineering starting point currently available.
IX. New Problems Brought by Memory
Memory is not a silver bullet. Precisely because it exists long-term, it creates troubles more difficult than context hallucinations.
Permanentization of false memories: A misjudgment written into memory will be repeated more confidently by the agent next time, and because 'it's recorded in memory,' it's harder to self-correct than zero-shot reasoning.
Expired information continuing to influence decisions: Today's API limits, deployment topology, and account status might be completely different next month, but old snapshots in memory will still silently sway the agent's judgment.
Persistent pollution from prompt injection: A piece of web content saved as 'experience' by the agent will affect all subsequent sessions—this is much more serious than a single attack.
Irreversibility of privacy and deletion: Deleting chat logs doesn't mean the profiles, facts, and skills extracted from them also disappear. Extraction is an irreversible refinement of information, but forgetting requires the same systematic design.
Summaries turning evidence into second-hand conclusions: As second-hand conclusions are used more, the system finds it increasingly difficult to distinguish between 'facts that actually happened' and 'the model's interpretation at the time.' Once this boundary blurs, memory turns from an asset into a liability.
Therefore, a good memory system must have built-in governance: source, time, expiration, confidence (fact/inference/preference), scope (user/project/agent/organization), deletability, and traceability (ability to return to the original session, file, or commit).
This is also why I increasingly dislike simplifying agent memory to 'storing conversations in a vector database.' A vector database is just a means of recall. A true memory system needs to handle state, source, permissions, and evolution—things an embedding cannot solve.
X. Conclusion: Memory is the Agent's State Layer
Back to the beginning.
Those ~/.claude/projects/*/memory/MEMORY.md files on my machine convinced me: when an agent truly starts participating in long-term projects, it naturally needs a place outside of conversation to save state.
This state includes how the project runs, which bugs have been debunked, which verification methods are reliable, which risk red lines cannot be crossed, which experimental conclusions have been updated by subsequent data, which processes can be directly reused next time—and, this last point is most easily overlooked—what to do next, when to trigger it, and which promises haven't been fulfilled yet.
Memory doesn't just record the past. Task queues, scheduled triggers, and unfinished loop states are all future-oriented memories. The 'inspection-fix-deployment loop' and 'where to continue in the next round' in the trader project are essentially the agent's promises to itself. Lose them, and the agent will repeatedly start planning things it has already planned from scratch, like someone who wakes up every morning forgetting yesterday's progress.
Long context allows the agent to see more in the current task; Memory allows the agent to have a higher starting point in the next task.
This is why Agent Memory has evolved from a 'small feature' to an 'architectural layer.' It's not an optional enhancement, but the infrastructure for an agent to evolve from a single call to continuous operation. Without any one layer, the agent will degrade into a stateless API wrapper in some dimension.
If you are building a coding assistant, research agent, personal AI, browser agent, customer support agent, or any LLM app that needs to work continuously across sessions, you might want to try the EverOS repo: https://github.com/EverMind-AI/EverOS
