Projectmem

🎬 Watch the demo

📚 Docs

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

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.

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. 14 native tools force the AI to read context, check files for known failures, and log work automatically. Verified end-to-end against all four clients.
• Interactive Dashboard — pjm visualize opens a four-tab D3.js dashboard: Story Map (failure heatmap), ROI Dashboard, Project Map (tree or graph view), Timeline.
• 100% Local — No cloud, no telemetry, no accounts. Your code, your memory, your machine.

How It Compares

_{✅ 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).}

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 reads events.jsonl directly. That file is for tools (pjm score, pjm context, pjm wrap). Tools distill the raw log into compact AI-readable summaries.

MCP Integration (Recommended)

Claude Desktop

Easiest — open the config from the UI:

• macOS: Claude menu → Settings… → Developer tab → 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.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows.

Paste this block:

"mcpServers": {
  "projectmem": {
    "command": "/opt/anaconda3/bin/python",
    "args": [
      "-m", "projectmem.mcp_server",
      "--root", "/absolute/path/to/your/project"
    ]
  }
}

Two things to know about this block:

• Use the absolute path to python (e.g. /opt/anaconda3/bin/python, or run which python to find yours). Claude Desktop subprocesses don't inherit your shell PATH, so bare "python" often fails.
• We pass the project root via --root, not the cwd JSON field. Claude Desktop's current build (with the Epitaxy / Cowork workspace system) silently ignores the cwd field — the server ends up running with cwd=/ and can't find .projectmem/. The --root flag is honored by projectmem directly (read from sys.argv) and works regardless of how Claude Desktop spawns the subprocess.

Then fully quit Claude Desktop (Cmd+Q on Mac) and reopen — MCP servers only initialize on cold start.

Cursor

Two ways to register the MCP server — pick whichever fits your workflow:

1. Global (recommended): Cursor menu → Settings… → left sidebar Tools & MCPs → Installed MCP Servers → Add Custom MCP. Paste the JSON below.
2. Per-project: drop the JSON into <project-root>/.cursor/mcp.json — only active when that project is open.

{
  "mcpServers": {
    "projectmem": {
      "command": "/opt/anaconda3/bin/python",
      "args": [
        "-m", "projectmem.mcp_server",
        "--root", "/absolute/path/to/your/project"
      ]
    }
  }
}

Two things to know about this block (same gotchas as Claude Desktop):

• Use the absolute path to python (run which python to find yours). Cursor subprocesses don't reliably inherit your shell PATH.
• Pass the project root via --root, not the cwd JSON field. Cursor — like Claude Desktop — silently ignores cwd: the server ends up running with cwd=~ and can't find .projectmem/. The --root flag is honored by projectmem directly and works around the bug.

Then fully quit Cursor (Cmd+Q on Mac)

…