I set out to build persistent memory for AI coding agents.

The idea was straightforward: AI coding agents lose context every session. You spend the first twenty minutes of every conversation re-explaining your codebase, your conventions, what you already tried. agentmemory was supposed to fix that — a layer that maintains state across sessions so the agent always knows where you left off.

That was the plan.

What I actually built was something else. And I didn’t understand what it was until I watched someone use it wrong.

The thing you remember is the thing that shapes you

When an agent has persistent memory, it doesn’t just remember your code. It remembers its mistakes.

I watched a session where agentmemory surfaced a context note from three weeks prior: tried using recursive embeddings for the graph traversal, results were inconsistent, abandoned in favour of flat indexing. The agent had been about to suggest recursive embeddings again. The memory note stopped it.

That’s not a feature I planned. That’s a consequence I didn’t anticipate.

Agents — like humans — have a tendency to retry approaches that failed them, as if the failure was a fluke rather than a signal. Persistent memory turns failure into a documented fact. The agent can’t re-litigate the decision because the decision is recorded.

What I built, it turns out, is not primarily a memory system. It’s an honesty layer. It makes the agent’s history visible to the agent itself.

The hard part was not the architecture

I can tell you exactly how agentmemory works technically. It maintains a context store that gets updated at the end of every session. It chunks, embeds, and retrieves relevant context at the start of each new session. It handles token budget constraints by ranking memories by relevance and recency.

That was the hard part.

The harder part was deciding what counts as a memory worth keeping. Not every failed experiment deserves to be remembered — some failures are genuinely flukes. But some failures are patterns. The difference matters, and I had to build judgment into the system for deciding which is which.

I ended up with a simple heuristic: if the failure changed a decision, remember it. If it was just noise, discard it.

That distinction sounds obvious written down. Implementing it correctly took three iterations.

What I thought I was solving vs. what I actually solved

I thought I was solving the context window problem — giving agents more usable context by managing what’s in the window.

I was actually solving the epistemic continuity problem — giving agents a consistent sense of their own history so they don’t repeat mistakes they don’t remember making.

These sound similar. They’re not.

The context window problem is a technical constraint. You solve it with better retrieval, smarter chunking, lower token costs.

The epistemic continuity problem is a design problem. You solve it by deciding what the agent should know about itself, and what it should be allowed to forget.

agentmemory started as a retrieval system. It became a self-knowledge system.

That’s not what I planned. But it’s what the problem actually required.

The honest version

I use agentmemory every day now. It’s the first thing I reach for when I start a new session with a project I’ve been working on.

Does it work? Yes.

Is it the thing I imagined building? No. It’s better — but in a different direction than I expected.

The lesson I keep returning to: when you build something and it surprises you by being more useful than you planned, the surprise is usually a sign that you understood the problem better than you knew. You built the right thing for a reason you hadn’t articulated yet.

I thought I was solving a retrieval problem. I was actually solving an honesty problem.

agentmemory is on GitHub. MIT licensed. Runs entirely locally.