projectmem
Local-first memory for coding agents: records issues, attempts, fixes and decisions, then warns before your agent repeats a failed approach.
Evidence shows a local-first design with no telemetry and the only network call being a user-opted update check; SECURITY.md tabulates where each file lives and lists six honest trade-offs (git hooks, background watcher, prompt-injection risk on memory files); full uninstall and hooks-uninstall paths exist; registry migration keeps a .bak. Deductions: pjm init auto-installs three git hooks and auto-starts a detached watcher process without per-action confirmation (opt-outs exist via --no-watch / hooks uninstall); dependencies are loosely pinned (>=) with no lockfile or audit evidence. No malware, covert exfiltration, or destructive defaults found.
Evidence shows tests covering path discovery, registry idempotency, and explicit reporting of unreadable configs ("unreadable" must not read as healthy); pjm doctor provides self-checks. Deductions: README contradicts itself on MCP tool count — 17 in one place, 15 twice, and SECURITY.md says 8 tools; pyproject declares 0.3.2 Production/Stable while still 0.x, and the changelog admits a fresh-install breakage (mcp 2.0 import failure) that shipped to all users for weeks, indicating weak release discipline.
Evidence shows support for Claude Desktop/Code, Cursor, Antigravity, Codex plus a no-MCP CLAUDE.md export path; 0.3.x fixes Windows-specific bugs (fork, os.kill, MSIX AppContainer config paths) with targeted tests. Deductions: boundary description mixes in marketing ("Save up to 50%+ of AI tokens" with no supporting experiment); precheck trigger precision is asserted descriptively only — no static evidence the warning rate is controlled, though the audited snooze is a good detail.
Evidence shows clear doc architecture (README/TUTORIAL/CHANGELOG/guide), install notes covering per-client differences and cold-start requirement; canonical command projectmem with pjm alias defined; a detailed per-version CHANGELOG crediting contributors; known limitations presented systematically as "Honest trade-offs" including prompt injection — rare among peers; complete MIT license file. Deductions: maintenance responsibility rests on one individual and one email with no governance or multi-maintainer evidence; examples lean on external links and there is no in-repo FAQ.
Evidence shows verifiable output design: dashboards marked snapshot vs live, tests proving the global view only reads and never mutates projects, precheck warnings naming the specific dead ends, JSON ROI output. Deductions: the core marginal-value claims (unique pre-commit warning, 50% token savings, provable ROI) are self-declarations with no benchmark data in the repo; the hidden maintenance cost of hooks + watcher + summary.md committed to git is not quantified.
Evidence shows the README explicitly separating "design capabilities, not benchmark results" in the comparison footnotes and a changelog citing PR numbers and contributors. Deductions: key quantitative claims (50% token savings, 207-event dogfooding study, arXiv paper 2606.12329) are not traceable within the provided sources and the arXiv identifier format is suspect; negative claims about competitors (claude-mem telemetry default-on, etc.) have no in-repo evidence and are unverifiable third-party facts.
- The README states MCP tool counts inconsistently (17, 15, and SECURITY.md says 8); verify against the actual running pjm-mcp before relying on it.
- pjm init installs git hooks and auto-starts a background watcher by default; for sensitive repos use --no-watch and inspect .git/hooks after init.
- summary.md and PROJECT_MAP.md are committed to git and read by AI agents — treat changes like code review for prompt-injection risk, and never log secrets into the event store.
- Quantitative claims (50% token savings, provable ROI, the arXiv paper) are independently unverified; do not base adoption decisions on them.
- Despite the Production/Stable classifier, this is a 0.x project with a past fresh-install breakage regression; pin your installed version.
- Cross-project global memory (~/.projectmem/global/) shares content across repos; use pjm init --no-global for sensitive repositories.
What does this agent do, and when should you use it?
projectmem is an open-source memory and judgment layer for AI coding agents. It records typed events — issues, attempts, fixes, decisions, notes — in an append-only log inside your repository's .projectmem/ directory (core store: events.l). A native MCP server, spawned as a stdio subprocess by your AI client, exposes 17 tools to Claude Desktop, Claude Code, Cursor, Antigravity and Codex so the agent reads memory and logs its own work. Since 0.3.0 a single server serves every registered project through a registry, replacing per-repo configuration. Its distinctive capability is the pre-commit warning, which blocks repeated failed approaches, high-churn files and possibly-stale decisions before you commit — and projectmem never deletes memory; it flags staleness and lets you supersede. The whole system runs 100% locally with no cloud, no accounts and no telemetry, requires Python and Git, and only touches the network for an update check you explicitly enable.
pjm init scaffolds .projectmem/, installs three git hooks (pre-commit warnings, post-commit classification, post-merge tracking), auto-starts a file watcher, and registers the project. Through MCP, agents read with get_summary(), get_project_map(), precheck_file(path), get_issue(id), search_events(query), get_context(), get_score(), get_plan() and write with log_issue(), record_attempt(), record_fix(), add_decision(), add_note(). At commit time pjm precheck cross-references the event log and warns about repeated dead ends ("✗ tried CSS contain:layout"), high-churn files, and decisions citing files that have since moved; stale decisions are retired with pjm decision --supersedes <id>, never deleted. pjm visualize and pjm dashboard render local dashboards (failure heatmaps, ROI grades, cross-project views); pjm export --claude-md compiles memory into CLAUDE.md for agents without MCP; pjm score outputs an A+→F prevention grade with concrete token/dollar savings.
- A Claude Code or Cursor user who wants new sessions to start with accumulated project knowledge instead of rediscovering yesterday's debugging dead ends
- A developer maintaining many repositories, using pjm doctor and the global dashboard for one-time configuration and a unified view of issues and failure hotspots
- An engineer repeatedly hitting failures in the same high-churn file who wants specific failure history warnings before each commit
- A Copilot or non-MCP agent user injecting the "Do NOT retry" list into CLAUDE.md via pjm export --claude-md
- A researcher studying agent memory, referencing the arXiv paper's Memory-as-Governance framing and its 207-event, 10-project dogfooding study
- A privacy-conscious solo developer wanting a fully local memory layer, keeping it private by adding .projectmem/ to .gitignore
What are this agent's strengths and limitations?
- Pre-commit failure warnings are a unique capability: it blocks repetition of known dead ends before committing — the README comparison marks no other tool as having this
- Memory is never deleted: stale decisions are flagged against git history and retired via --supersedes while staying in the log, avoiding silent decay
- One MCP server (0.3.0+) serves all registered projects; every write echoes which repo it landed in, and a pinned --root server refuses to write elsewhere
- 100% local: no cloud, no accounts, no telemetry; the only network call is an opt-in update check
- Verified integrations with per-client setup instructions for Claude Desktop, Claude Code, Cursor, Antigravity and Codex
- No database, no persistent service: the MCP server is a stdio subprocess and everything else is greppable plain files
- Requires a Python environment and Git, and client configs must use the absolute path to python (subprocesses don't inherit shell PATH) — a common misconfiguration point
- MCP clients must be fully cold-restarted after any config change, which adds friction
- Capture depends on the agent actively calling write tools; the README admits consistency drops without the kickoff prompt
- Codex setup requires hand-editing TOML (its UI save is unreliable) and a reasoning-effort setting of medium or higher for the full session-start behavior
- Distilled files (summary.md etc.) are committed to the repo by default; teams wanting private memory must edit .gitignore manually
- Most comparative claims are design capabilities, not benchmark results; headline benefits like 50% token savings come from project self-reporting, not independent validation
How do you install or deploy this agent?
- pip install -U projectmem
- cd into your project and run pjm init (installs git hooks, creates .projectmem/, registers the project)
- Run pjm doctor to find existing projects and pjm doctor --fix to register them
- Add the MCP config in your client (Claude Desktop/Cursor/Antigravity):
"mcpServers": { "projectmem": { "command": "/absolute/path/to/python", "args": ["-m", "projectmem.mcp_server"] } }
(Codex uses TOML: [mcp_servers.projectmem] in ~/.codex/config.toml, same absolute python path)
- Fully quit and restart the client (MCP servers load only on cold start), then run pjm doctor to verify.
How do you use this agent?
Daily flow: pjm brief for a session-start briefing; log manually with pjm log, pjm attempt --failed/--worked, pjm fix, pjm decision, pjm note — or let your agent log via MCP tools (log_issue, record_attempt, record_fix, add_decision, add_note). The agent calls precheck_file(path) before edits. Ideas and plans go in plan.md (pjm plan), deliberately separate from the event log. pjm precheck automatically warns at commit time; pjm precheck --snooze 2h pauses warnings (the snooze itself is logged). Visualize with pjm visualize (six-tab dashboard), pjm dashboard (cross-project view), and measure with pjm score.
How does this agent compare with similar options?
The README compares projectmem to claude-mem (session capture, background worker, telemetry default-on), agentmemory (memory engine with decay-based pruning), mem0 (chat memory that rewrites facts) and Letta/MemGPT (requires a running server with Postgres or cloud). Differentiators: pre-commit failure warnings (unique), flag-never-delete staleness handling, no database or persistent service, greppable events.l storage, provable ROI scoring, and plan.md separating intent from memory. A pjm import tool (planned for 0.3.3) will migrate history from mem0, agentmemory, Letta and Claude session logs.