Coding Agent Memory: How It Works, and Where projectmem Fits

projectmem takes a narrower view of memory than most tools in this space. Instead of storing conversations or embedding documents for retrieval, it records typed events: an issue you hit, an attempt you made and whether it worked, a fix that resolved it, a decision you took, a note worth keeping. Those five types are the whole vocabulary, and the constraint is the point — structure is what lets software reason about the record rather than merely search it.

Everything lives in a plain .projectmem/ directory inside the repository. The raw log is an append-only events.jsonl; the distilled files (summary.md, PROJECT_MAP.md, issue files) are generated from it. There is no database and no persistent server. The MCP server is a stdio subprocess your editor spawns and kills with the session, exposing 15 tools to Claude Code, Claude Desktop, Cursor, Antigravity and Codex. The only thing that ever listens on a port is the optional dashboard you start yourself and stop with Ctrl+C.

That architecture has a consequence worth spelling out, because it is the practical difference from cloud memory services: memory travels with the repository. Clone the repo and you have the team's history — including the failed approaches — without provisioning anything. Add .projectmem/ to .gitignore and nothing leaves your machine at all. There is no account, no telemetry and no network call in the core tool.

The part that has no equivalent in the other tools is what happens at commit time, covered in its own section below. Everything else here — event capture, distilled summaries, MCP access — exists in some form elsewhere. The pre-commit gate does not.

The term covers at least three different things, which is why comparisons in this space so often talk past each other.

1. Context retrieval. Making a large corpus — your codebase, your docs — searchable so the agent can pull relevant chunks on demand. This is what vector stores and knowledge graphs do, and it is what most "AI memory" products mean. cognee and mem0 are strongest here.

2. Conversation persistence. Remembering what you and the agent said, so you do not re-explain your preferences every session. basic-memory and much of mem0's consumer framing address this.

3. Experience memory. Recording what was attempted and what happened — that this fix failed, that this decision was taken for that reason. This is the smallest category and the least served, because it needs structure that free-form notes do not have.

projectmem is squarely in the third. It will not find a function for you or semantically search your repo; that is not what it stores. What it holds is the thing your version-control history cannot tell you: git records what changed, not what was tried and abandoned. The failed branch you deleted, the approach you reverted, the reason you chose sessions over JWTs — none of that survives in the code, and all of it is exactly what an agent needs in order not to suggest it again.

If you are shopping in this space, work out which of the three you actually need first. Most frustration with agent memory tools comes from buying one category and expecting another.

Every tool here can store that something failed. projectmem is the only one that acts on it at a moment when acting still matters.

When you commit, a deterministic check runs against the files in the commit. Not a model call — a lookup. If a file you are touching has failed attempts recorded against it, or carries a decision that predates several commits and may no longer hold, it says so before the commit lands:

This is worth dwelling on, because it is the design decision the whole tool rests on.

The check is a lookup against typed events, not a model asking itself whether this looks like a repeat. That means it is fast, free, offline, and identical every time you run it. It cannot hallucinate a warning, and it cannot be talked out of one. An LLM-based reviewer would be more flexible and less trustworthy — and since the whole point is to be believed at the moment you are about to repeat a mistake, trustworthiness is the property that matters.

It also means the value is bounded by your logging discipline. The gate can only warn about attempts that were recorded. This is the honest limitation of the design: projectmem raises the value of a habit you have to keep. In MCP mode the agent logs its own work, which removes most of the friction — but if neither you nor your agent records the attempt, the gate has nothing to say about it.

The complementary rule is that memory is never silently deleted. Tools that decay or prune old memories optimise for a tidy store; projectmem flags a memory as possibly stale and asks you to confirm or supersede it, keeping the superseded version. For a record whose job is to explain past reasoning, losing history to make room is the wrong trade — you cannot audit a decision whose predecessor was pruned.

An append-only log of typed events turns out to be something you can render, and projectmem ships a local dashboard that does. This matters more than it sounds: the most common failure of any memory system is that nobody can tell whether it is working. Being able to look at what has accumulated is how you find out.

The Timeline puts real time down the middle, with problems branching left (issues, failed attempts) and knowledge branching right (fixes, decisions, notes). Hovering a card lights up its whole issue thread, so you can follow one bug from first symptom to eventual fix across weeks.

The dashboard also has a Showoff tab, which renders your real event log as animated scenes: Story Replay builds your project's history node by node, Orbit puts files in orbit around the project with their events orbiting them, and Universe renders the project as a rotating galaxy where every bright star is an actual issue, attempt, fix or decision — click one and you get its full record. A built-in recorder exports a 10–60 second .webm locally.

This is decorative and the documentation does not pretend otherwise. It is included here for two honest reasons. First, it is rendered entirely from the same real event log — nothing is simulated, so it doubles as a sanity check that the memory contains what you think it does. Second, a memory tool has an adoption problem before it has a technical one: the value only appears weeks later, when a warning fires. Something you can look at in week one helps a team stay with it long enough to reach that point.

If that argument does not move you, ignore the tab. Nothing else depends on it.

The economic argument for agent memory is that reading a distilled summary is cheaper than re-deriving context from source files every session. projectmem's documentation puts numbers on it:

Honest routing, including away from ours.

• You need semantic search over a large codebase or document set — cognee or mem0. This is retrieval, and they are built for it with vastly more users. projectmem does not do this and is not trying to.
• You are building stateful agents as a product — Letta. It is a framework for agents that learn over time, not a memory file for a repo.
• You want memory across every conversation, not per project — mem0 or basic-memory. Note basic-memory's AGPL-3.0 licence if you plan to embed it commercially.
• You want the largest community and most third-party testing — mem0, by a wide margin. 64k stars buys a lot of edge cases already found by other people.
• You want a record of what was tried and failed, living in the repo, with a check that fires before you repeat it — that specific case is what projectmem exists for.

These are not mutually exclusive. Retrieval memory and experience memory answer different questions, and running a retrieval tool alongside projectmem is a reasonable setup rather than a contradiction.

In the order likely to matter to you.

It is small. 766 stars against mem0's 64,210 and cognee's 30,299. That gap is not a detail — it is thousands of users who have not hit your edge case yet, integrations that do not exist, and far fewer people to ask when something breaks. If you need the safest choice by adoption, it is not this one.

The evaluation is a self-study. The arXiv paper reports a two-month study across 10 projects and 207 logged events, conducted by the authors on their own work. That is a legitimate design report and honestly labelled, but it is not independent evidence, and no one should treat it as a benchmark result.

It depends on logging discipline. Events that are never recorded cannot warn you later. MCP mode has the agent log its own work, which helps a great deal, but the tool's value is downstream of a habit.

It is not a retrieval engine. No semantic search, no embeddings over your code. If what you wanted was "find me the function that does X", this is the wrong category of tool entirely.

The gate is git-only. Warnings fire on commit. A workflow that does not commit through git gets nothing from the feature that most distinguishes it.

Setup is developer-grade. pip install, a CLI, and per-client MCP configuration. Compared with signing up for a hosted service, that is real friction, and it will lose users who would otherwise benefit.