projectmem Coding Memory

What does this agent do, and when should you use it?

projectmem is a local-first, event-sourced memory and judgment layer for AI coding agents, recording issues, attempts, fixes, decisions, and notes. Its components include a Python CLI, native MCP server, Git hooks, a file watcher, a project registry, and local project and workspace dashboards. Each repository keeps memory under .projectmem/: raw events go to events.jsonl, while tooling produces distilled summaries, issue files, and a project map for agents to read. Its pre-commit checks combine prior failures, file churn, unresolved issues, and potentially stale memories to warn before a mistake is repeated; older knowledge is flagged or superseded rather than silently erased. It fits developers who want the same project experience available to Claude Code, Claude Desktop, Cursor, Antigravity, Codex, or another MCP client without adopting a cloud account, telemetry service, or persistent database. Adoption still adds Python tooling, Git hooks, local memory artifacts, client configuration, and—in several clients—a full restart whenever the MCP setup changes.

After pjm init, projectmem creates .projectmem/, installs pre-commit warning, post-commit classification, and post-merge tracking hooks, builds the code structure, and starts its real-time watcher. Developers record typed events with pjm log, pjm attempt, pjm fix, pjm decision, and pjm note; pjm regenerate rebuilds summary.md from events.jsonl. MCP clients read context through operations such as get_instructions(), get_summary(), get_project_map(), get_plan(), get_issue(id), and search_events(query), then write experience back with log_issue, record_attempt, record_fix, add_decision, and add_note. Before an edit, an agent can call precheck_file(path); before a commit, pjm precheck surfaces known dead ends, high-churn files, unresolved issues, and file-linked decisions that may have become stale. pjm brief creates a session-opening briefing, pjm context and pjm wrap produce token-budgeted context, and pjm export --claude-md or --cursor serves assistants without MCP. pjm visualize produces a six-tab project dashboard, pjm dashboard aggregates registered repositories, and pjm map --build derives a code structure and Python import graph that can be overlaid with failure heat. Since version 0.3.0, one registry-backed MCP process can route calls across multiple projects, while --root provides a strict single-repository boundary.

1. A developer who frequently starts fresh coding-agent sessions can preserve yesterday's failed debugging paths, confirmed fixes, and architectural choices instead of reconstructing them from source.
2. An engineer maintaining many repositories can expose every registered project through one MCP configuration and select the destination with a project argument or active-project setting.
3. A team worried about risky or repeatedly broken files can run pjm precheck before commits to review previous failures, churn, unresolved work, and stale decisions.
4. A user of Copilot, plain Claude, or another assistant without MCP can export current decisions, gotchas, and a do-not-retry list into CLAUDE.md or .cursorrules.
5. A project lead reviewing engineering history can use the local dashboards, case files, timeline, failure heat, and pjm score to inspect what was learned and the tool's estimated savings.
6. A team that wants shared distilled knowledge but not a shared raw activity log can commit summaries, maps, instructions, and issue files while leaving events.jsonl ignored.

How do you install or deploy this agent?

Python, Git, and a shell are required. Install or upgrade the package:

pip install -U projectmem

Initialize it inside a repository:

cd your-project
pjm init

For older projects or upgrades from 0.1.x/0.2.x, scan for existing memory and register what is found:

pjm doctor
pjm doctor --fix

No account, cloud service, or API credential is required. Normal operation is documented as offline; network access occurs only when the user explicitly invokes pjm doctor --online, enables --auto, or clicks an update-check link in a dashboard.

How do you use this agent?

Begin by inspecting the session briefing and distilled memory:

pjm brief
pjm show

Record an issue, a failed attempt, and the confirmed fix:

pjm log "authentication callback returns an empty session"
pj m attempt "increase callback timeout" --failed

The second command above is not a valid source-documented alias because of the embedded space. Use the actual command:

pjm attempt "increase callback timeout" --failed
pjm fix "preserve the session cookie during callback"

Check historical risks before committing:

pjm precheck

Build structural data and open the local project dashboard:

pjm map --build
pjm visualize

To serve all registered repositories from one MCP process, add this to a supported client's configuration and replace the command with the absolute path to the machine's Python interpreter:

{
  "mcpServers": {
    "projectmem": {
      "command": "/absolute/path/to/python",
      "args": ["-m", "projectmem.mcp_server"]
    }
  }
}

Codex uses ~/.codex/config.toml instead:

[mcp_servers.projectmem]
command = "/absolute/path/to/python"
args = ["-m", "projectmem.mcp_server"]

Fully quit and reopen the client, then have the agent call get_instructions(), get_summary(), and get_project_map() at session start. It should call precheck_file(path) before editing and log issues, attempts, fixes, decisions, and notes as work proceeds. Add --root followed by an absolute repository path to the server arguments when a hard single-project boundary is preferred.

What are this agent's strengths and limitations?

How does this agent compare with similar options?

Key facts side by side with the most closely related agents.

How does FollowAgents rate this agent?

Recent releases

Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.

1. v0.3.4 v0.3.4 — memory that stays small, and warnings you can trust 2026-10-02
   Release notes excerpt

   Three community reports, three community fixes, and six more bugs found by checking them. Each report was reproduced end to end before it was fixed, and every fix was reviewed by someone other than its author. ```bash pip install -U projectmem ``` Then run pjm init once in each project. Older projects keep the AI_INSTRUCTIONS.md and git hooks of the release that created them; re-running 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. Fixed …

   View on GitHub ↗
2. v0.3.3 v0.3.3 — precheck stops getting slower, and Windows works end to end 2026-09-15
   Release notes excerpt

   Six field reports closed, and the check that runs before every edit no longer gets slower as your project ages. Every fix below was found by running projectmem on the machine that reported it — Windows 11, and all four MCP clients — not by reading the code. Two of them were found only because a client launched the server from a directory we did not expect. ```bash pip install -U projectmem ``` Faster pjm precheck was taking 26 seconds on a 1,200-event project, and getting worse every week. …

   View on GitHub ↗
3. v0.3.2 v0.3.2 — Windows watch support, and a doctor that tells the truth 2026-09-07
   Release notes excerpt

   Windows works properly now — and pjm doctor stops saying green when it cannot see. ```bash pip install -U projectmem ``` Every fix below was found by running the thing on Windows, not by reading the code. The watcher works on Windows pjm watch --daemon crashed there with AttributeError: module 'os' has no attribute 'fork'. Daemonisation used the POSIX-only os.fork() and os.setsid(); it now spawns a detached worker with subprocess.Popen — DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW on Windows, start_new_session=True elsewhere. …

   View on GitHub ↗

FAQ