kaeru gives Claude Code and Codex long-term graph memory via MCP

Anyone who has worked with AI agents for more than a week knows this scene. You open a project, and the agent asks something you already answered yesterday. Half an hour later it proposes fixing something you decided to leave alone, and it sounds convincing because it doesn't know the reason. And when the context overflows and the conversation is compressed into a summary, half the discussion shrinks to a couple of lines.

The Lamantin AI team proposes solving this with a separate memory layer. The tool is called kaeru, and the source code is on GitHub. Below is a breakdown of how it works and where it is weak. The author of the original text is the developer of the tool itself, so treat this as a view from the inside.

Why a rules file isn't enough

Everyone takes the same first step: CLAUDE.md, AGENTS.md, .cursorrules or a note in Obsidian. About a month in, problems start:

• the file gets updated whenever someone remembers it, meaning three days later and with details lost;
• it only grows: adding is easy, striking out is scary, and the agent trusts yesterday's rule and a rule cancelled a month ago equally;
• it has the "what" but not the "why": "don't touch the parser" with no reason can be neither verified nor revoked;
• every team member has their own file.

ADRs and task trackers like beads cover part of the problem, but not the working layer between commits: hypotheses, checks, quirks of test environments. Dragging all of that into the repository clutters the history, while not recording it means losing it. kaeru was built for this layer.

How it works

kaeru runs on your machine as an MCP server, and Claude Code, Codex, Cursor and other clients connect to it. Memory is stored as a graph: observations ("the client's files arrive in cp1251"), decisions, tasks with deadlines, hypotheses with the result of a check, and documents. Links are typed: "grew out of," "replaces," "refutes," "confirms," "blocks," "contradicts." The agent can save the whole chain from observation to decision as a line of reasoning.

An example from the article: an agent suspects that the nightly export fails because of file size. It tests with a 2 GB file and records the hypothesis immediately with the verdict "refuted." If the export fails again a week later, the next agent starts with a different theory. Without memory, a negative result is the first thing lost: successful solutions end up in the code, unsuccessful ones go nowhere.

Old entries can be replaced explicitly. The replace call marks the previous entry as superseded and shows which conclusions relied on it. The entry is not deleted; it keeps its history, and you can open its version at any point in time.

There are also reminders: an entry can be hidden until a given date. The author's example: a certificate on a test environment is renewed every six days. On day five you need that knowledge; on day one it only gets in the way. The reminder period is counted from the first time it is shown, so it won't expire while you're on vacation.

What the hooks do and what the server does

The server handles storage and the summary. When to request the summary and what to do when context is compressed is up to the client, through hooks in Claude Code and Codex. The author wrote some of the hooks for personal use, and they are not yet part of kaeru. The repository includes kaeru-first: before the agent asks a human a question, the hook searches memory for matches and suggests reading what it finds first.

There is also a useful observation. The agent was simply asked to read the saved reasoning, and over seven sessions it never once did. That is why the summary is fed in automatically at session start.

Limitations

• kaeru does not guarantee that entries are true. The agent can record nonsense just as it can in a rules file. The gain is that you can see which observations a conclusion grew out of, and that you can flag a mistake and redo the chain.
• The agent has to call the replacement of an old entry itself. On the author's project, two rules with different GitLab IDs for the same people lived side by side for two weeks: the new one was recorded, but the old one was not replaced.
• A word match does not mean the entry contains the answer.
• You deploy the team server, kaeru-cloud, yourself. It is designed for a trusted team, with one shared space divided by project, and there is no isolation between users and organizations yet. Projects are private by default, and entries are scanned for keys and tokens before being sent.

What to do with this

If your agents live on one project for more than a couple of days, it's worth splitting knowledge into two layers. Durable agreements stay in the repository (rules, ADRs) and go through review. Working findings, rejected hypotheses and the "why" need a separate store with history and explicit replacement of outdated entries. Even without kaeru, two practices are worth adopting: record hypotheses together with their verdict, and feed the agent a short summary automatically instead of hoping it will read it on its own.