It contains everything you need to start the working day: which rule applies, what is worth remembering, what is overdue, what needs review, and why a particular course of action was chosen over another. There is no need to explain any of it again.
I’ll say something separately about the top section. It contains established project rules. You can store rules discovered through work there and link to the entries from which they emerged. For example, since the summer I have had a rule that the interface of the visualizer built into kaeru (covered at the end) must be written only in English. I told the agent this once.
We tried simply suggesting that the agent read the saved reasoning. In seven sessions, it saw this prompt and never opened them even once. That is why I feed it a short summary immediately when opening the project.
During the day: entries you don’t have to dictate
Throughout the day, the agent writes to memory on its own and decides for itself what to record. An observation about the current work becomes an entry with a clear name. A specification or agreement that needs to be preserved verbatim becomes a document. Something to handle later becomes a task with a deadline.
Most of all, I’m glad when a rejected hypothesis remains in memory.Suppose the agent suspects that the nightly export is failing because of the file size. It checks—no. It immediately records the hypothesis along with the verdict: “disproven, tested on a 2 GB file.” If the export fails again in a week, the next agent will be able to find the check and start from a different version. Without memory, the negative result is lost first: successful solutions end up in the code, while unsuccessful ones go nowhere.
The first question we are asked is: doesn’t the agent write a stream of consciousness there? Here is what a typical entry looks like after such a check. There is no rigid field schema; the agent formats the “checked, cause, solution, lessons” blocks itself:
If you don’t like the wording, you can ask the agent to rewrite it: it will edit the entry itself, while the previous version will remain in the history.
Links are the “why”
When recording something new, the agent immediately specifies which entry it grew out of or what it is linked to—this is a single field in the same call. A link is not a generic “relates to”; it has a type: grew out of, replaces, disproves, confirms, blocks, is part of, contradicts.
When the agent has gone from an observation to a solution, it saves the entire chain as reasoning in a separate call, with a brief description:
A month later, the question “why do we normalize dates on input?” leads not only to the solution, but to the entire path leading to it.And if the reason has changed in the meantime—for example, the client specified the format in the contract—it is clear that the decision needs to be revisited.
The outdated entry can be explicitly replaced
The most annoying thing about the rules file is that the old and new entries sit side by side with equal rights. In kaeru, a new entry can explicitly replace an old one. The old entry is not deleted, but a marker appears next to it showing what replaced it.
In my setup, a hook fires after calls to record. It searches for similar entries and shows them to the agent. If the new entry refines the active one, it can be edited via revise. If the knowledge has changed, replace marks the old entry as replaced and shows which conclusions relied on it. The hook suggests candidates; the agent makes the decision.
But the agent is the one who should replace the old entry. If it recorded the new one without calling replace, the previous entry will remain active alongside the new one. For nearly two weeks, I had two rules with different IDs for the same people in GitLab: the team moved to a new server, the agent recorded the new rule, but did not replace the old one.
When the agent is about to ask you
There were times in the logs when the agent asked about things it had already recorded. To handle this, the kaeru repository has a separate hook for Claude Code and Codex called kaeru-first. Before handing the turn over to the human, the client lets the hook inspect the question. The hook takes into account whether the agent has read anything on the topic and may search using words from the question. If there are matches, it suggests reading the found entries once before asking.
A word match does not yet mean that the entry contains the answer.If there is no hook or the memory server is unavailable, the question goes to a human.
Long session: context compaction does not wipe out the work
When the context overflows, Claude Code compresses the conversation into a recap. Everything that does not make it into the recap is lost. If the agent discovers something and does not have time to write it down, that discovery disappears along with the context.
Entries in kaeru remain after compaction. To preserve even what has not yet been written down, hooks are triggered in my environment. In Claude Code, before compaction, a hook asks that a list of already saved entries and a separate list of what still needs to be written down be included in the summary. After compaction, a second hook saves the summary in the Cold layer, where it can be found through search.
In Codex, the hook before compaction saves a local snapshot of the end of the conversation. If a summary is available after compaction, it is the summary that goes into memory. If there is no summary, the snapshot itself can be saved. This preserves a point from which the investigation can continue.
Evening: tasks and reminders
Tasks in kaeru are regular entries with a deadline and status, and every project has a board:
There is nothing unusual about this, except for one thing: an overdue task comes up first in the summary, and the agent treats it as a debt (more about agent debts here).
Reminders are a separate story. The agent often learns things that will become important later. The certificate on the staging environment is renewed every six days, and if the renewal is missed, the client will fail the TLS check—with an error that resembles anything except an expired certificate.On the fifth day, this knowledge is invaluable; on the first day, it only gets in the way.
That is why kaeru has reminders: when creating an entry, the agent specifies the date from which it is important and how long to keep reminding. Before that date, the entry is not visible in the digest. Afterward, it appears in the reminders section, as in the digest screenshot above, and remains there until the period expires. The period is counted from the first display, not from the date: if you went on vacation for two weeks, the reminder will wait for the first session and only then start counting.
A week later and a month later: a time machine and cleanup
You can open an entry’s contents as they were saved in kaeru at a selected point in time. I need this when, a week later, the question arises of where a strange decision came from. I look at which version of the entry they might have relied on back then. This is the history of what was recorded, while the date of the event itself may be specified separately.
When there are many entries, the server itself changes the layers used to assemble the digest. For example, it may move old entries without links to Cold, while moving entries that are frequently linked to higher up. The content stays where it is, and the entry can still be found through search.
Several agents and a team
A single kaeru server runs on the machine. Several sessions can connect to it, including sessions belonging to different agents. Here is how it works for us: ideas are discussed with Claude and turned into tasks in memory, and Codex carries them out. All you have to tell it is “check the latest tasks and get them done”—it takes the context from memory, checks the result itself, and closes the task.
The team’s history began with a vacation. A colleague went on leave, and his work needed to be continued.We exported the project archive from kaeru, and the work continued almost seamlessly: the agent already knew the entire context; we were the ones who had to get up to speed. The colleague returned, and we uploaded the archive back. It became clear that this was a workaround, so we set up a shared team server with rules about what could be shared and with whom.
Another story. A colleague uses Claude to write lessons for an online course, experts edit them, and the writing guidelines gradually accumulate in memory. The first lessons had to be almost completely rewritten; by the eighth, there were almost no comments left. The agent had not become smarter—the edits had simply stopped getting lost between sessions.
For teamwork, there is kaeru-cloud—a separate server from the same repository that the team deploys in its own infrastructure. The documentation calls it a cloud, but it is not our service; it is your server. Everything is closed by default: every project starts out private, and nothing leaves the machine until you explicitly allow that project to share. Even then, only the records you select are sent to the shared server, and before sending, kaeru checks whether a record contains fragments resembling API keys, tokens, or private keys. The cloud is designed for a trusted team. At present, it has a single shared space with separation by project, while user and organization isolation is still planned. The agent accesses the shared memory separately. A regular local search does not traverse it.
Can you trust what the agent wrote?
This is the most common and most justified question. The short answer is: kaeru does not guarantee that what was recorded is true. An agent can write nonsense just as easily as it can write it into a rules file. kaeru is a work log; the experiment is the source of truth.A journal is needed so that the next experiment does not start from a blank slate or with groundless guesses.
But errors are easier to spot here:
for each conclusion, you can see which observations it grew from;
TAG158- TAG163@@the hypothesis is stored together with the verdict and what it was checked against;
- TAG167@@you can look at what the saved content of the entry was;
- TAG171@@when the agent replaces an erroneous entry, kaeru shows the conclusions that relied on it and may require revision.
when reading, you can see whether an entry is still current, what replaced it, and which contradictions have already been recorded in memory;
The worst-case scenario is an incorrect initial framing that is noticed too late. The agent diligently digs in the wrong direction, conclusions pile up, and when it turns out that the error was at the very beginning, the entire chain has to be redone. Within a single long context, models handle such cleanup poorly. Memory works differently: cleanup takes place not in the model’s attention, but in storage through explicit operations—replace, refute, flag a contradiction. The next session begins with the corrected state. But if neither the agent nor the human noticed the error, memory will not find it on its own—it only makes it visible.
If you use SDD and everything is already in the repository
If you work with SDD (spec-driven development), there is no need to migrate anywhere. Specifications in the repository are how things should be: they are written deliberately, reviewed, and versioned alongside the code.kaeru is what happens between specs while the agent is working: investigations, disproven hypotheses, reasons why a spec was changed, knowledge that does not belong to a single repository (test environments, setups, customer specifics), and reminders for the future.
Specs remain in the repository as they are. Two lines are added to the rules file stating that working memory lives in kaeru. If anything in memory has matured into a spec, it is exported to markdown and committed.
Honestly, about the benefit: if you have a disciplined SDD and all decisions already undergo review, the gain will be smaller. It is mainly in what lies between specs.
What else
The visualizer is built into the server itself: open http://127.0.0.1:9876/ui/ in your browser, and the storage will appear as a star map. Each project is a constellation, with bridges between projects visible, saved reasoning can be played back step by step, and the growth of knowledge can be viewed in fast-forward. The task board and the history of each record are there too. Password login is optional.
Data is not locked inside kaeru. Any project, several projects, or the entire storage can be exported to a ZIP with markdown pages that open in Obsidian, or to AMG (Agentic Memory Graph)—our binary knowledge-transfer format based on CBOR (a compact analogue of JSON), which preserves relationship types—so that it can be transferred to another kaeru storage.
For OpenCode, an open console agent, there is a kaeru connection script. The model and the way it is run are selected in OpenCode.And if you are writing your own agent in Rust, there is an adapter for the rig LLM framework.
Limitations
kaeru has 35 tools. Their argument schemas take up context space. Exactly how much depends on the client and model. When the client loads descriptions on demand, they do not occupy the context all at once. The server’s introductory instruction is shorter than the set of schemas.
Search is supplementary and has no vectors. The agent’s main route through memory is the graph: a summary, record links, and saved reasoning. Full-text search is needed when the exact name is forgotten. It is lexical, without vectors or morphology; for Russian endings, there is word-prefix search—“утечк” will find both “утечку” and “утечке”.
The agent may skip memory. Therefore, in the project’s rules file, I leave a short instruction on when to retrieve the summary, when to search for previous decisions, and what to record as work progresses.
We have not yet measured the overall effect. Our figures concern agent behavior: what they read, what they write, and which prompts they respond to. Honestly, we do not know how much time, money, or tokens memory saves per task. To evaluate responses based on accumulated history, you can use LongMemEval or MemoryAgentBench. For our workflow scenario, the first thing we examine in the call logs is whether the agent accesses memory, what it finds, and how that affects the next step.
Memory needs to be checked occasionally. Layered cleanup runs automatically, but it does not evaluate the content of entries.Every so often, it is worth opening the visualizer and seeing what the agent considers persistent.
Getting started
curl -fsSL https://raw.githubusercontent.com/LamantinAI/kaeru/main/contrib/install/install.sh | bashThe installer downloads the release and starts the server as a background service. Prebuilt binaries are available for Linux x86_64 (glibc 2.34 and later), macOS on Apple Silicon, and Windows x86_64. On Windows, download the ZIP from the releases page, unpack it, and run kaeru-mcp.exe. The macOS build is unsigned. Build instructions are available for other platforms. By default, the server listens on the loopback address.
Connecting to the local server in Claude Code:
claude mcp add --transport http kaeru http://127.0.0.1:9876/mcpFor Codex:
codex mcp add kaeru --url http://127.0.0.1:9876/mcpIf the client supports only stdio, specify the command kaeru-mcp --stdio. The bundled OpenCode example uses the /sse endpoint. The instructions include settings for different clients, including an option with authorization.
And the third step, which we ourselves reached too late: add a couple of lines about memory to the project rules file (CLAUDE.md, AGENTS.md), for example:
The project’s long-term memory is kaeru (MCP). At the start of the session, retrieve a summary via context for the current project. As you work, record decisions, checks, and tasks in kaeru.To get started, the line in the rules and one task you will return to in the next session are enough. Ask the agent to record a decision and the reason for it, then check whether it finds them when you log in again.The kaeru-first hook can be enabled separately.
What you get out of the box: the server, its tools, and the kaeru-first hook. The hooks I mentioned above—a session-start summary, finding similar entries after a write, and saving before context compression—are mine; they are not included in kaeru. Without them, the agent will receive a summary when it invokes `context` based on a line in the rules.
The source code is open: github.com/LamantinAI/kaeru. BSL 1.1 license: you can use kaeru in your work and embed it in your products, including paid ones. The restriction applies to providing kaeru itself to third parties as a hosting or managed service. For details and the timeline of the transition to Apache 2.0, see the license description.
Instead of a Conclusion
The main thing I learned from six months of working on memory for agents is that simply giving an agent somewhere to write is not enough. What has been written needs to reach the agent on its own, at the moment it is needed, and sound like a task that needs to be done. Graphs, layers, and the time machine work only on top of that.
The next thing we want to try is validating the memory itself. Right now, the agent or a human notices an error in an entry. The idea is to have a separate pass between sessions: it compares the entries with what actually happened during the work and suggests corrections, which a human accepts or rejects. Anthropic recently described a similar mechanism and called it dreaming.
Thank you for reading to the end. If you feel like trying it, the installation above takes a couple of minutes. And if kaeru proves useful to you, give it a star on GitHub: for a small project, it is the best way to say that what we are doing is useful and to help others find it. How do you remove outdated rules from your CLAUDE.md or AGENTS.md? Tell us in the comments.Send questions and bug reports to the community chat.
