projectmem

<!-- mcp-name: io.github.riponcm/projectmem --> <div align="center"> <img src="https://raw.githubusercontent.com/projectmem/projectmemdoc/main/logo/projectmem-wordmark-800.png" alt="projectmem" width="420" /> <p> <a href="https://github.com/riponcm/projectmem/blob/main/CHANGELOG.md"><b>🎉 v0.3.3 is out</b></a> — `pjm precheck` no longer slows down as your project grows, and Windows works end to end. <a href="https://github.com/riponcm/projectmem/blob/main/CHANGELOG.md">See what changed →</a> </p> <p><b>We don't make AI smarter. We make it experienced.</b></p> <p><i><b>Coding agent memory</b> — the local-first memory + judgment layer for AI coding agents. One MCP server for every project. Save up to 50%+ of AI tokens. Stop repeating yesterday's bug.</i></p> <p> <a href="https://pypi.org/project/projectmem/"><img src="https://img.shields.io/pypi/v/projectmem.svg?color=4c1d95&label=pypi" alt="PyPI version"></a> <a href="https://pypi.org/project/projectmem/"><img src="https://img.shields.io/pypi/pyversions/projectmem.svg?color=3b82f6" alt="Python Versions"></a> <a href="https://pepy.tech/project/projectmem"><img src="https://static.pepy.tech/personalized-badge/projectmem?period=month&units=abbreviation&left_color=grey&right_color=brightgreen&left_text=downloads%2Fmonth" alt="PyPI downloads per month"></a> <a href="https://github.com/riponcm/projectmem/stargazers"><img src="https://img.shields.io/github/stars/riponcm/projectmem?style=flat&color=f59e0b&label=stars" alt="GitHub stars"></a> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-3b82f6.svg" alt="License: MIT"></a> <a href="https://arxiv.org/abs/2606.12329"><img src="https://img.shields.io/badge/arXiv-2606.12329-b31b1b.svg" alt="arXiv paper"></a> </p> <p> <a href="https://ossdrop.com/tool/projectmem"><img src="https://ossdrop.com/badge/projectmem" width="250" height="56" alt="projectmem on OSSDrop" /></a> </p> <p> <a href="https://projectmem.dev"><b>Website</b></a> • <a href="https://projectmem.dev/guide"><b>Guide</b></a> • <a href="https://projectmem.dev/demo"><b>Demo</b></a> • <a href="https://projectmem.dev/changelog"><b>Changelog</b></a> • <a href="https://arxiv.org/abs/2606.12329"><b>Paper</b></a> </p> <br /> <img src="https://raw.githubusercontent.com/projectmem/projectmemdoc/main/demo/precheck-warning.gif" alt="projectmem pre-commit warning demo" width="720" />

<br /><br />

<img src="https://raw.githubusercontent.com/projectmem/projectmemdoc/main/screenshots/dashboard-overview-0.3.0.png" alt="projectmem dashboard — coding agent memory for one project: memory card, failure heatmap, ROI and case files" width="860" /> <p>_{<code>pjm visualize</code> — every case your project solved, what failed on the way, and what it saved. Generated locally from <code>.projectmem/events.jsonl</code>.}</p> </div>

---

🚀 Start here — five minutes, once

Five minutes if you follow along here. Want to be shown instead — every command, the exact output it prints back, and the dashboards at the end? Take the complete setup guide.

New to projectmem, or upgrading from 0.1.x / 0.2.x? Since 0.3.0 one MCP server serves every project, so this is the last time you configure anything.

1. Install or update

pip install -U projectmem

2. Find the projects you already have

pjm doctor

It looks where code lives — ~/Developer, ~/code, ~/projects, your cloud folders, and every drive on Windows — and lists projects with memory that aren't registered yet. Anything it missed, add by hand:

pjm project register "/Users/you/Developer/repos/ossdrop"

3. Register them

pjm doctor --fix

4. Point your AI at all of them with one config

"mcpServers": {
  "projectmem": {
    "command": "/absolute/path/to/python",
    "args": ["-m", "projectmem.mcp_server"]
  }
}

No --root, no cwd — that's what makes it serve everything. Per-client instructions (Claude Desktop, Claude Code, Cursor, Antigravity, Codex) are in MCP Integration; pjm init prints this block with your own Python path filled in. Then fully restart the client — MCP servers only load on a cold start.

5. Check your work

pjm doctor

Add --online if you also want it to tell you when a newer projectmem is out — projectmem makes no network calls otherwise, and --auto turns that into a once-a-day check if you prefer.

Run it again after editing the config. It flags any client still pinned to a single repo — the most common reason a new project is invisible to your agent.

All green? You're done. From here on it is one command per repo:

pjm init

Your agent reads what the project already learned instead of rediscovering it, and writes down what it finds. Fewer tokens, no repeated dead ends, memory that outlives the session.

---

What is coding agent memory?

Coding agent memory is a persistent record of what happened while building a project — the issues hit, the approaches attempted, the fixes that worked and the decisions made — stored so an AI coding agent can read it at the start of a new session. Without it every session begins from zero.

projectmem is an open-source agent memory layer built for that job. It is local-first: memory lives in a plain .projectmem/ directory inside your repository, with no cloud, no account and no telemetry — the only network call it can make is an update check you turn on yourself. A native MCP server exposes 17 tools to Claude Code, Claude Desktop, Cursor, Antigravity and Codex, so your agent reads memory and logs its work on its own.

Unlike chat-history memory tools, projectmem stores typed events — issues, attempts, fixes, decisions, notes — which is what makes the one thing no other tool does possible: a pre-commit warning that fires before you repeat an approach that already failed.

pip install projectmem
cd your-project && pjm init

---

🎬 Watch the demo

<p align="center"> <a href="https://youtu.be/pELGdXHj_Ls"> <img src="https://img.youtube.com/vi/pELGdXHj_Ls/maxresdefault.jpg" alt="projectmem — 60-second demo" width="720" /> </a> <br /> <em>Full screen-recorded tutorial- watch on YouTube</em> </p>

📚 Docs

| Doc | What's in it | |---|---| | Complete setup guide | The full walkthrough on the web — install, MCP setup per client, pjm doctor, your first logged issue, and both dashboards. Every terminal output is captured from a real run. | | TUTORIAL.md | 15-minute step-by-step walkthrough — set up projectmem on your own project, watch the lifecycle, see the pre-commit warning fire. | | CHANGELOG.md | Release history. Latest: v0.3.3 — pjm precheck is flat rather than linear in project age, and six Windows reports are closed. | | Research paper (arXiv:2606.12329) | PROJECTMEM: A Local-First, Event-Sourced Memory and Judgment Layer for AI Coding Agents — the peer-readable version: design, Memory-as-Governance framing, capability comparison, and the 207-event dogfooding study. | | LICENSE | MIT |

---

The Problem

Every new AI session starts from zero. Claude, Cursor, Aider — they all forget yesterday's decisions, repeat failed debugging attempts, and burn millions of tokens reconstructing context from raw source files.

The model isn't the problem. The architecture is. Stateless models need a memory cortex.

The Solution

projectmem is the local-first memory + judgment layer that sits above your AI tools. It captures every failed attempt, decision, and gotcha — then injects that experience back into future AI sessions. Git tracks what changed. projectmem tracks why it changed, what was tried, and what failed.

Install

First time here? → The complete setup guide walks the whole path end to end: install, connecting Claude Desktop, Claude Code, Cursor, Codex or Antigravity, checking it with pjm doctor, and reading your memory back through the dashboards — with the real terminal output at every step.

Three commands to a project that remembers:

pip install projectmem
cd your-project
pjm init

That's it. pjm init installs three git hooks (pre-commit warnings, post-commit classification, post-merge tracking), auto-starts a real-time file watcher, inherits cross-project memory if available, and creates .projectmem/. Capture is active from minute one.

The canonical command is projectmem. A pjm alias is installed for speed.

---

✨ New in 0.3.3 — precheck stops getting slower, and Windows works end to end

pjm precheck runs before every edit — the instructions tell agents to call it first — so its cost is paid constantly. It was taking 26 seconds on a 1,200-event project, and getting worse every week, because it ran one git log per event to answer a question about a single file. It now makes one call per distinct file, bounded by the oldest event citing it.

| events | before | after | |---|---|---| | 100 | 2,210 ms | 48 ms | | 400 | 8,905 ms | 51 ms | | 1,500 | ~33 s, 1,501 git processes | 82 ms, 2 processes |

Latency is now flat rather than linear in project age. Results are unchanged — verified against a reimplementation of the old algorithm, including across merge commits.

A retired decision no longer resurfaces. supersedes has existed since 0.1.4, but the two surfaces an agent actually reads during work — get_context and precheck_file — were not filtering it. You could retire a decision and still be told about it. Both filter now, and AI_INSTRUCTIONS.md finally documents how to retire one, which is why models never called it.

Your project is named in the bridge file, and AGENTS.md is written too. One server serves every project, so a call naming none is refused rather than guessed at — but nothing told the agent the name, so it learned it from the error and retried, every session. The name is in the bridge now. It goes into AGENTS.md as well as CLAUDE.md, because Antigravity and Codex never read the latter.

Six Windows reports are closed. Git hooks shipped a bash shebang that Git for Windows often cannot resolve — and an unresolvable shebang does not skip the hook, it aborts your commit. The baked binary path lost its backslashes to shell escaping. The venv fallback looked in bin/, which cannot exist there. pjm watch --daemon could not be seen or stopped. And a box-drawing character in the output killed pjm init outright on a cp1252 console — after it had already created everything, so the command both did its work and reported failure.

Every one was fixed by running projectmem on the machines that reported it — Windows 11, and the four MCP clients — not by reading the code. Reported by @medium-effort, who also contributed the 0.3.2 Windows daemon support.

✨ New in 0.3.2 — Windows, properly

pjm watch --daemon crashed on Windows with AttributeError: module 'os' has no attribute 'fork'. It now spawns a detached worker instead of forking, so background watching works on every platform.

Fixing that uncovered a second bug hiding behind it. Liveness was checked with os.kill(pid, 0) — a POSIX idiom that does not port, because on Windows os.kill routes to TerminateProcess and signal 0 is not a check at all. The watcher could not be seen or s