projectmem: a local memory layer that warns coding agents before they repeat a failed fix

The problem is not context length, it is that sessions start from zero

A coding agent that debugs a failing migration on Monday has no record of it on Tuesday. The README states the consequence plainly: without memory, every session begins from zero. That costs tokens, and it costs the same dead end twice. The project targets developers who already run an agent inside a real repository and keep coming back to it, not people trying an agent for the first time. The README frames the product as a memory plus judgment layer, and the distinction it draws is against tools that store chat history. projectmem stores typed events instead: issues, attempts, fixes, decisions, notes. The typing is what makes a pre-commit warning possible, because the system can tell an attempt that failed from a decision that was made. The tagline in the repository is direct about the scope: "We don't make AI smarter. We make it experienced."

How the memory is stored and how the agent gets at it

Memory lives in a plain .projectmem/ directory inside the repository, according to the README, with no cloud, no account and no telemetry. The dashboard screenshot caption states that pjm visualize is generated locally from .projectmem/events.jsonl, so an append-only JSONL file is the underlying record. A native MCP server exposes 17 tools to Claude Code, Claude Desktop, Cursor, Antigravity and Codex. The agent reads memory at the start of a session and logs its own work through those tools, which is the part that separates this from a file you maintain by hand. Since v0.3.0, one server serves every project: the README says the MCP config takes no --root and no cwd, and that this is what makes it serve everything. That is a real architectural change from the 0.1.x and 0.2.x line, and the README treats the migration as the last time you configure anything. The pre-commit warning is the differentiating mechanism: it fires before an approach that already failed is repeated. Whether it fires depends on that approach having been logged as a failed attempt in the first place.

Install, register, wire up MCP, verify

The README gives a five-step sequence. Install or update with pip install -U projectmem. Then run pjm doctor, which searches where code lives (the README names ~/Developer, ~/code, ~/projects, cloud folders, and every drive on Windows) and lists projects that have memory but are not registered. Anything missed can be added with pjm project register "/Users/you/Developer/repos/ossdrop". Registration is applied in bulk with pjm doctor --fix. The MCP block is a standard entry with the absolute Python path and args ["-m", "projectmem.mcp_server"]; pjm init prints that block with your own Python path filled in. The README is explicit that the client must be fully restarted, because MCP servers only load on a cold start. Then pjm doctor runs again and flags any client still pinned to a single repo, which the README calls the most common reason a new project is invisible to your agent. Per-repo work from then on is pjm init. Two flags matter for privacy: --online adds a newer-version check, --auto turns it into a once-a-day check, and the README states projectmem makes no network calls otherwise.

Where it breaks: empty memory, stale memory, and the doctor

The warning can only fire on what was recorded. A project where the agent never logged its failed attempts has nothing to warn about, so the value of the tool tracks how consistently your agent writes events, not how long you have had it installed. The v0.3.2 release notes describe a doctor that notices when a fix gets undone, which implies the project has already run into memory that drifts out of sync with the code. That is a maintenance surface, not a one-time setup. The .projectmem/ directory sits inside the repository, and the README does not describe how that interacts with .gitignore, branching or merge conflicts on events.jsonl. If your team cannot commit that directory, or you work in ephemeral containers where the working tree is discarded, the local-first design works against you. The README also does not state a retention or compaction policy for events.jsonl, so long-lived repositories will accumulate events with no documented pruning mechanism. Treat the token-saving figure in the README as a project claim, not a measured result.

How it differs from chat-history memory and from mem0

The README positions projectmem against chat-history memory tools and lists mem0-alternative as a repository topic. The difference in approach is what gets stored. A chat-history tool keeps conversational context and retrieves passages that look similar to the current prompt. projectmem keeps typed events scoped to a project and uses them for a specific decision: has this attempt already failed here. The output is a warning before an action rather than a passage injected into a prompt. That design also means projectmem is not a general knowledge store. It will not help an agent reason about an unfamiliar library, and it has nothing to say about a codebase it has not worked in. Scope is the trade-off: project memory for repositories you return to, not broad retrieval across everything you have ever read.

Licence, upgrades and what the release cadence implies

The repository is MIT licensed, which permits commercial use and modification. That is a statement about the licence text, not legal advice; if you redistribute projectmem inside a product, read the licence yourself. The release history shows v0.3.0, v0.3.1 and v0.3.2 within a week of each other in early September 2026, with v0.3.0 changing the server model so that one server serves many projects and v0.3.1 adding opt-in update checks. Two of the three releases in that window touch configuration or network behaviour, which is the kind of change that can invalidate a working setup. The README anticipates this by treating the 0.3.0 migration as the last configuration step, but the practical cost is that pjm doctor has to be re-run after any config edit. Budget for that check after each upgrade rather than assuming the previous config still holds.

Who should install it and what to confirm first

The fit is narrow and specific. You run Claude Code, Cursor, Antigravity or Codex against repositories you return to over weeks, you can commit a .projectmem/ directory, and you want the project history in a file you can read and diff. The wrong fit is equally specific: short-lived containers, repos where the working tree is thrown away, or workflows where the agent is not expected to log its own work. If the agent does not write events, projectmem has nothing to warn about. Verify in this order: run pjm doctor after wiring MCP and confirm no client is pinned to a single repo, run pjm init in one project, and then check that .projectmem/events.jsonl grows while your agent works. If that file stays empty, the memory layer is inert regardless of what the dashboard shows.

Editorial conclusion

Adopt projectmem if you run Claude Code, Cursor, Antigravity or Codex on repositories you return to across many sessions and you want that history in a file you can read, diff and commit. Do not adopt it if you work in ephemeral containers, cannot commit a .projectmem/ directory, or expect the warning to catch anything your agent never logged. Before trusting it, run pjm doctor after editing the MCP config and confirm no client is still pinned to a single repo, then run pjm init in one real project and check that .projectmem/events.jsonl actually grows when your agent works.

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. riponcm/projectmem on GitHub