projectmem

🚀 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

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.3 — precheck stops getting slower, and Windows works end to end

pjm precheck runs before every edit — the instructions tell agents to call it first — so its cost is paid constantly. It was taking 26 seconds on a 1,200-event project, and getting worse every week, because it ran one git log per event to answer a question about a single file. It now makes one call per distinct file, bounded by the oldest event citing it.

Latency is now flat rather than linear in project age. Results are unchanged — verified against a reimplementation of the old algorithm, including across merge commits.

A retired decision no longer resurfaces. supersedes has existed since 0.1.4, but the two surfac