projectmem MCP server

https://github.com/user-attachments/assets/e055988e-7253-4ba9-92fc-95d3d4bcd763

---

🚀 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 its signature feature possible: a pre-commit warning that fires before you repeat an approach that already failed in this project.

pip install projectmem
cd your-project && pjm init

---

🎬 Watch the demo

📚 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.5 — precheck matches every spelling of a path, and long entries no longer bloat the summary.
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.5 — warnings for every spelling, and a summary that stays small

Precheck recognises a file however its path is spelled. Events store project-relative paths, so asking about ./src/auth.py, an absolute path, a path through a symlinked folder or a Windows C:\ path matched nothing, and precheck called a file with known failures "Safe to modify". Every spelling now gets the same warnings, and checking is faster on large logs. get_issue("1") and get_issue("#1") find issue 0001. (#26)

Long entries no longer bloat the summary. 0.3.4 capped how many entries the summary shows, not how long each one is. Records are now clipped at 300 characters, and a fixed issue takes one line. On a real 238-event project the summary went from 8,974 tokens to 3,458. (#29, #30)

Upgrading? Run pjm init once in each project. The instructions now ask agents for shorter records, and pjm init refreshes AI_INSTRUCTIONS.md, keeping your previous copy as AI_INSTRUCTIONS.md.bak.

The #26 fixes were contributed by @vishalhabib99, and #29 was reported and fixed by @bigfree.

✨ New in 0.3.4 — memory that stays small, and warnings you can trust

The summary no longer grows forever. Notes were capped, but Recent issues and Decisions listed everything ever logged, so on an aged project reading the memory cost more than reading the code. Every open issue is still shown — the newest 20 in full, older ones by id — while fixed issues are capped at the newest 10 and decisions at the newest 15, each with a line saying what was left out and where to find it. On a test project with 25 issues and 60 decisions the summary went from about 2,900 tokens to about 1,100. (#19)

Commits are filed under the code they change. Auto-capture used the first changed path in git's sort order, which was usually the regenerated .projectmem/summary.md — so valid memories were flagged stale and the real file lost its history. The location is now the source file the commit is about, with deletions, renames, merges and a repository's first commit handled. (#20)

Stale warnings no longer depend on your time zone. A 0.3.3 speed-up compared git's local-time commit dates with UTC event times as text: west of UTC, recent stale memories were never flagged; east of UTC, fresh ones were flagged at once. Both sides are compared in UTC now, and events already filed under .projectmem/ stop warning without your log being rewritten.

The guidance names the tools' real arguments. It gave precheck_file and get_issue the wrong argument names (path and id, where the tools take file_path and issue_id) and showed search_events without its required query, so an agent copying the call got a validation error. A test now checks every call shown to an agent against the tool's actual signature. (#18)

Upgrading? Run pjm init once in each project. Older projects kept the AI_INSTRUCTIONS.md and git hooks of the release that created them, so fixes to either never arrived. pjm init now refreshes both — your previous instructions are kept as AI_INSTRUCTIONS.md.bak, and anything of yours outside projectmem's block in a hook is left untouched.

Also: a mistyped issue id no longer breaks every later command, pjm precheck stops warning about projectmem's own files, and Python 3.13 and 3.14 are supported.

Fixes for #18 and #20 were contributed by Rohan Tiwari, and the first cap for #19 by hylin. #18 and #19 were reported by @medium-effort, #20 by @bigfree.

✨ 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 matched a reimplementation of the old algorithm, including across merge commits — except for a time-zone bug this change introduced, which 0.3.4 fixes.

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 three MCP clients (Antigravity, Claude, and Codex) — 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 stopped there, and each pjm watch --daemon leaked another process. Both are fixed.

Windows daemon support was contributed by @medium-effort (#13).

pjm doctor also got two things. It now tells you to quit your AI client before editing its config — those files hold the app's own preferences too, so a running client can rewrite the whole thing on exit and restore the --root you just removed. And it remembers what it saw last time, so a config that was clean and is pinned again gets named as a revert rather than looking like doctor being flaky. Local files only; nothing leaves your machine.

✨ New in 0.3.1 — know when to upgrade

Both dashboards now show which version generated the page, with a check for updates link beside it. The page makes no request until you click — PyPI's public JSON is fetched straight from your browser and nothing about your machine is sent. On the command line, pjm doctor --online checks once and pjm doctor --auto remembers to check daily; both are off unless you ask.

✨ New in 0.3.0 — one server, many projects

Until now an MCP config was tied to one repository: eleven projects meant eleven server entries and eleven restarts. 0.3.0 serves every registered project from a single server. Paste the config once; every repo you pjm init afterwards is reachable from it.

pjm project list          # what this server can reach
pjm project use ossdrop   # the default when a call names no project

log_issue(summary="stars come back empty", project="ossdrop")
→ Logged issue #0019 → ossdrop: stars come back empty

Every write names the project it landed in — in a shared server, the dangerous failure is not "nothing works", it is a write that succeeds against the wrong repo. Existing --root configs keep working untouched, and a pinned server now refuses to write anywhere else even when asked.

Also in 0.3.0:

• Fixed: the MCP server was broken on fresh installs. mcp 2.0 renamed FastMCP and left the old import path raising — since 2026-07-28 every new pip install projectmem got a server that died at import. Caught and fixed by @VIVAAN-DHAWAN.
• Security: stored XSS in pjm visualize. Event summaries reached the DOM unescaped, and git commit messages become event summaries — so a crafted commit in a branch you pulled could run script in your dashboard. Every sink is escaped now.
• A rebuilt dashboard — a shareable Memory Card, case files with the full issue → attempt → fix chain, an effort treemap, per-file dossiers, and a global view that opens with where you left off.

Registry migration is automatic: the 0.2.x list of paths is converted on first read, with a .bak kept beside it.

✨ New in 0.2.0 — the workspace release

0.1.6 made one project's memory something you could watch. 0.2.0 lifts that to your whole workspace — and closes the gap between what happened (memory) and what your code is (structure).

• 🌐 Global dashboard — pjm dashboard is one page over every project you've pjm init-ed: total issues captured, fixes confirmed, dead-ends prevented, tokens saved, a grade per project, and a "needs attention" list. Click any card to open that repo's own dashboard, generated fresh. It's a global view, not a global store — each repo's .projectmem/ is aggregated at read time and never leaves its folder. Default is serverless (a static snapshot); add --serve for a tiny, ephemeral live server where the Refresh button re-reads your files — no background daemon, Ctrl+C stops it.
• 🧬 Structure & relations — pjm map --build (run automatically at pjm init) walks your codebase and, for Python, resolves imports into a real dependency graph. The Project Map's Graph and Flow views now render actual files and the import edges between them. The cache (structure.json) is derived from code, gitignored, and never committed — code is only ever read.
• 🔥 Failure heat on structure (the combo) — the one view a pure code-grapher can't draw and a pure memory tool can't either: files with repeated failed attempts glow red, laid directly over the real import graph. Structure comes from the code, heat comes from your memory, and they meet only in the renderer.
• 🗂️ plan.md — a new editable intent file: ideas and plans, what you mean to do — deliberately not the event log. events.jsonl → summary.md records what happened; plan.md records what you intend. The AI reads it at session start and edits it directly; a plan never becomes an event. pjm plan / pjm plan "idea" / MCP get_plan().

Everything stays 100% local — the global dashboard is a read-time aggregate, never a central honeypot of your code's history.

The visualization suite (shipped in 0.1.6)

Your project's memory is also something you can watch — and share.

• 🎬 Showoff — a dashboard tab with three animated story scenes, all rendered from your real event log: Story Replay (watch your project's history build itself, node by node), Orbit (files orbit the project, events orbit their file), and Universe (your project as a rotating galaxy — every bright star is a real issue, attempt, fix, or decision; click one for its full details).
• ⏺ Built-in recorder — hit REC (10–60 s) and Showoff downloads a .webm clip of the animation, rendered 100% locally with a "made with projectmem" badge. Your debugging story, ready for a tweet or a standup.
• 🗺️ Flow — the Project Map's default view: a layered flowchart reading PROJECT → DIRECTORIES → FILES → WHAT HAPPENED → MEMORY. Files with repeated failures glow red along their path, every file shows its outcome chips, and everything flows into the events.jsonl cylinder. Tree and Graph views are one click away.
• 🧵 Time Spine — the Timeline's default view: a real-time axis you scroll, with problems branching left (issues, failed attempts) and knowledge branching right (fixes, decisions, notes). Hover any card and its whole issue thread lights up. The classic list remains as "Details".

---