projectmem

🎉 v0.3.2 is out — Windows support for the file watcher, and a doctor that notices when a fix gets undone. See what changed →

---

🚀 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

📚 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.2 — the file watcher works on Windows, and pjm doctor spots a config fix that got reverted.
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.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".

---

Why You'll Love It

• Pre-Commit Warnings — pjm precheck warns you before you commit if you're about to repeat a failed approach, modify a high-churn file, or touch an unresolved issue. No other AI tool does this — it requires the memory layer underneath. The warning now lists the dead ends themselves ("What already failed here: ✗ tried CSS contain:layout"), and pjm precheck --snooze 2h silences it politely — the snooze is itself logged, so even the silence is audited.
• Stale-Memory Detection (new in 0.1.4) — other memory tools silently decay or delete old memories; projectmem never deletes. Every decision that cites a file is cross-checked against that file's git history — when the file has moved on, the memory is flagged ("predates 7 commits to auth.py — confirm or supersede") and a human decides. Retire it cleanly with pjm decision "new way" --supersedes <id>: the old event stays in the log, tagged, forever.
• Session-Start Briefing (new in 0.1.4) — pjm brief answers "where was I?" in one screen: active warnings, possibly-stale memories, open issues, recent decisions, stack gotchas, and your prevention score with a week-over-week delta.
• Memory for agents without MCP (new in 0.1.4) — pjm export --claude-md compiles live decisions, gotchas, and a "Do NOT retry — these already failed" list into a marked block in CLAUDE.md (or .cursorrules). Copilot, plain Claude, any agent that reads the file inherits your project's judgment.
• Smart Context Injection — pjm wrap claude (or cursor/aider) injects a token-budgeted memory block into your AI before the session opens. Your AI starts experienced, not blank.
• Provable ROI Score — pjm score outputs a letter grade (A+ → F) backed by concrete numbers — debugging hours saved, tokens prevented, dollars protected. CI-friendly JSON output and shields.io badge for your README.
• Cross-Project Memory — Lessons learned in one repo follow you forever. Library gotchas, decisions, and patterns live in ~/.projectmem/global/ and auto-inherit into every new project that matches your stack.
• Real-time File Watcher — Background daemon detects rapid edits to the same file (debugging sessions) between commits. Battery-aware, gitignore-aware, auto-started by pjm init.
• Native MCP Server — Plugs into Claude Desktop, Cursor, Antigravity, Codex, and any MCP-compatible tool. 15 native tools force the AI to read context, check files for known failures, read your plan.md, and log work automatically. Verified end-to-end against all four clients.
• Interactive Dashboard (expanded in 0.1.6) — pjm visualize opens a six-tab local dashboard: Overview, Story Map (failure heatmap with collapse/focus controls), ROI Dashboard, Project Map (Flow / Tree / Graph, now over your real code structure), Timeline (Time Spine / Details), and Showoff — animated story scenes with a built-in video recorder.
• One MCP server for every project (new in 0.3.0) — configure your client once instead of once per repository. Calls name their project (project="ossdrop"), or fall back to the active one; every write reports which repo it landed in, and a pinned --root server refuses to write outside its own. Existing single-project setups are untouched.
• Global Dashboard (new in 0.2.0) — pjm dashboard is one cross-project view over every repo you've pjm init-ed: grades, issues, savings, and per-project drill-in. A global view, never a global store — each repo's memory is aggregated at read time and never leaves its folder. Serverless by default; --serve for an ephemeral live server (Ctrl+C to stop).
• Code Structure + Judgment (new in 0.2.0) — pjm map --build reads your codebase into a real import graph, and the Project Map overlays failure heat from your event log on top: the files that keep breaking, glowing red over the structure that actually connects them. The structure cache is derived from code and gitignored — never committed.
• Intent, separate from memory (new in 0.2.0) — plan.md holds ideas and plans (what you mean to do), kept deliberately apart from the append-only event log (what happened). pjm plan, or the MCP get_plan(); the AI edits it directly and a plan never becomes an event.
• 100% Local — No cloud, no telemetry, no accounts. Your code, your memory, your machine.

How It Compares

Capability	projectmem	claude-mem	agentmemory	mem0	Letta (MemGPT)
Core focus	Memory + Judgment	Session capture	Memory engine	Chat memory	Agent framework
Pre-commit failure warnings	✅ unique	❌	❌	❌	❌
Stale memory: flag, never delete	✅ new in 0.1.4	❌	❌ silent decay	❌	❌
Supersede without losing history	✅ new in 0.1.4	❌	❌	❌	❌
Captures development history	✅ typed events	🟡	🟡	🟡	🟡
Records architectural decisions	✅	❌	🟡	❌	❌
Memory for agents without MCP	✅ CLAUDE.md export	❌	❌	❌	🟡
Cross-project memory	✅ library-scoped	🟡	🟡	🟡	🟡
Provable ROI score	✅ A+ → F + $	❌	❌	❌	❌
Plain-text, greppable store	✅ events.jsonl	❌	❌	❌	🟡
No persistent server or DB	✅ stdio + files †	❌	❌	❌	❌ server + DB
No telemetry, no accounts	✅	❌ default-on	✅	❌	🟡
Native MCP server	✅ 15 focused tools	✅	🟡 53 tools	🟡	🟡
Global dashboard (all repos)	✅ read-time, local	❌	🟡 central store	❌	❌
Editable intent (plan ≠ memory)	✅ plan.md	❌	❌	❌	🟡
Price	✅ Free · MIT	Free + paid tier	Free	Freemium	Free + cloud

✅ yes · 🟡 partial · ❌ no — snapshot June 2026; design capabilities, not benchmark results. claude-mem runs a background worker (port 37777) and enables telemetry by default (v13.5+); agentmemory down-ranks and prunes old memories via decay, mem0 rewrites facts on update, Letta's memory blocks self-edit in place — projectmem never deletes: it flags staleness and lets you decide. Letta requires a running server (Postgres or cloud).

† There is no database and nothing you have to keep running: the MCP server is a stdio subprocess your AI client spawns, and everything else is plain files. The only server anywhere is the optional pjm dashboard --serve, an ephemeral local viewer you start and stop with Ctrl+C — never a background service.

🚧 Upcoming

• Import your existing memory — pjm import (planned for 0.3.3) will migrate history from mem0, agentmemory, Letta, and Claude session logs into projectmem. It maps only to the core event vocabulary — issues, attempts, fixes, decisions, notes — so signal comes in and another tool's clutter stays out. Your judgment history moves with you.

Want a source supported? Open an issue and tell us what you're migrating from.