Projectmem

AI coding 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-sourceagent memorylayer built for that job. It islocal-first: memory lives in a plain.projectmem/directory inside your repository, with no cloud, no account and no telemetry. A nativeMCP serverexposes 15 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 storestyped events— issues, attempts, fixes, decisions, notes — which is what makes the one thing no other tool does possible: apre-commit warningthat firesbeforeyou repeat an approach that already failed.

pip install projectmem cd your-project && pjm init

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.

projectmemis 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 trackswhatchanged.projectmemtrackswhyit changed, what was tried, and what failed.

pip install projectmem cd your-project pjm init

That's it.pjm initinstalls 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 isprojectmem. Apjmalias is installed for speed.

0.1.6 madeoneproject's memory something you could watch.0.2.0 lifts that to your whole workspace — and closes the gap between whathappened(memory) and what your codeis(structure).

- 🌐Global dashboard—pjm dashboardis one page overeveryproject you'vepjm 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 globalview, 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--servefor a tiny, ephemeral live server where the Refresh button re-reads your files — no background daemon,Ctrl+Cstops it.
- 🧬Structure & relations—pjm map --build(run automatically atpjm init) walks your codebase and, for Python, resolves imports into a real dependency graph. The Project Map'sGraphandFlowviews 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 everread.
- 🔥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 youmeanto do— deliberatelynotthe event log.events.jsonl → summary.mdrecords what happened;plan.mdrecords 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"/ MCPget_plan().

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

Global Dashboard — everypjm init-ed project in one view: grades, issues, savings, and a "needs attention" list, aggregated at read time. Each card opens that repo's own dashboard.

The visualization suite (shipped in 0.1.6)

Your project's memory is also something you canwatch— 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), andUniverse(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.webmclip 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 readingPROJECT → DIRECTORIES → FILES → WHAT HAPPENED → MEMORY. Files with repeated failures glow red along their path, every file shows its outcome chips, and everything flows into theevents.jsonlcylinder. Tree and Graph views are one click away.
- 🧵Time Spine— the Timeline's default view: a real-time axis you scroll, withproblems branching left(issues, failed attempts) andknowledge branching right(fixes, decisions, notes). Hover any card and its whole issue thread lights up. The classic list remains as "Details".

Showoff · Universe — every bright star is a real event from this project's memory

Project Map · Flow — what happened, file by file, flowing into append-only memory

Timeline · Time Spine — problems on the left, knowledge on the right, real time down the middle

- Pre-Commit Warnings—pjm precheckwarns youbeforeyou 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"), andpjm precheck --snooze 2hsilences 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; projectmemnever deletes. Every decision that cites a file is cross-checked against that file's git history — when the file has moved on, the memory isflagged("predates 7 commits to auth.py — confirm or supersede") and a human decides. Retire it cleanly withpjm decision "new way" --supersedes <id>: the old event stays in the log, tagged, forever.
- Session-Start Briefing(new in 0.1.4)—pjm briefanswers "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-mdcompiles 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 scoreoutputs 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 bypjm 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 yourplan.md, and log work automatically. Verified end-to-end against all four clients.
- Interactive Dashboard(expanded in 0.1.6)—pjm visualizeopens 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), andShowoff— animated story scenes with a built-in video recorder.
- Global Dashboard(new in 0.2.0)—pjm dashboardis one cross-project view over every repo you'vepjm init-ed: grades, issues, savings, and per-project drill-in. A globalview, never a globalstore— each repo's memory is aggregated at read time and never leaves its folder. Serverless by default;--servefor an ephemeral live server (Ctrl+C to stop).
- Code Structure + Judgment(new in 0.2.0)—pjm map --buildreads your codebase into a real import graph, and the Project Map overlaysfailure heatfrom 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.mdholds ideas and plans (what youmeanto do), kept deliberately apart from the append-only event log (whathappened).pjm plan, or the MCPget_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.

✅ 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 isno databaseandnothing 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 theoptionalpjm dashboard --serve, an ephemeral local viewer you start and stop with Ctrl+C — never a background service.

- Import your existing memory—pjm import(planned for 0.2.1)will migrate history frommem0,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.

How AI Reads Your Memory (Token Efficiency)

The architecture is built around one rule:AI reads small, distilled files. Tools generate them from the big raw log.

AI never readsevents.jsonldirectly.That file is for tools (pjm score,pjm context,pjm wrap). Tools distill the raw log into compact AI-readable summaries.

For:Claude Desktop, Cursor, Antigravity, Codex — and any tool with native MCP support. The MCP server forces the AI to read memory and log every action automatically.

The 3-minute workflow (let your AI do the setup)

Hi — I use projectmem as this project's memory. Before anything else, call get_instructions(), then get_summary(), then get_project_map() to load what we already know. As we work, log issues, attempts (failed/worked), fixes, decisions, and notes with the projectmem tools, and call precheck_file(path) before you edit a file. Ideas and plans go in plan.md via get_plan() — never as events.

Strictly speaking this prompt is optional — with the MCP server installed correctly the AI discovers the memory on its own. But saying it makes capture noticeably more consistent, so we recommend it.

- Repeat for every project:pjm init+ the same kickoff prompt.
- Coming back after closing the window?Open with a one-line reminder —"Reminder: we use projectmem as memory here."— and the whole setup carries on where you left off.

Prefer to wire it up by hand? The exact, verified config for each client follows.

- macOS:Claude menu →Settings…→Developertab →Local MCP servers→Edit Config.
- Windows / Linux:same path expected (Settings → Developer → Edit Config) — open an issue if your platform differs and we'll update this.

If you prefer the raw file path:~/Library/Application Support/Claude/claude_desktop_config.jsonon macOS,%APPDATA%\Claude\claude_desktop_config.jsonon Windows.

- Local-first— No network calls, no cloud, no telemetry. Your data never leaves your machine.
- Project-scoped— Memory lives in the repo. When the code moves, the memory moves.
- AI-tool-agnostic— Works natively via MCP, or universally via Markdown instructions. Any AI tool, any workflow.

projectmemstands on the shoulders of these excellent open-source projects: