🚀 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 projectmem2. Find the projects you already have
pjm doctorIt 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 --fix4. Point your AI at all of them with one config
"mcpServers": { "projectmem": { "command": "/absolute/path/to/python", "args": ["-m", "projectmem.mcp_server"] } }No
--root, nocwd— that's what makes it serve everything. Per-client instructions (Claude Desktop, Claude Code, Cursor, Antigravity, Codex) are in MCP Integration;pjm initprints 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 doctorAdd
--onlineif you also want it to tell you when a newer projectmem is out — projectmem makes no network calls otherwise, and--autoturns 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 initYour 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 its signature feature possible: a pre-commit warning that fires before you repeat an approach that already failed in this project.
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. Apjmalias is installed for speed.
✨ New in 0.3.4 — memory that stays small, and warnings you can trust
The summary no longer grows forever. Notes were capped, but Recent issues and Decisions listed everything ever logged, so on an aged project reading the memory cost more than reading the code. Every open issue is still shown — the newest 20 in full, older ones by id — while fixed issues are capped at the newest 10 and decisions at the newest 15, each with a line saying what was left out and where to find it. On a test project with 25 issues and 60 decisions the summary went from about 2,900 tokens to about 1,100. (#19)
Commits are filed under the code they change. Auto-capture used the first
changed path in git's sort order, which was usually the regenerated
.projectmem/summary.md — so valid memories were flagged stale and the real
file lost its history. The location is now the source file the commit is about,
with deletions, renames, merges and a repository's first commit handled.
(#20)
Stale warnings no longer depend on your time zone. A 0.3.3 speed-up compared
git's local-time commit dates with UTC event times as text: west of UTC, recent
stale memories were never flagged; east of UTC, fresh ones were flagged at once.
Both sides are compared in UTC now, and events already filed under
.projectmem/ stop warning without your log being rewritten.
The guidance names the tools' real arguments. It gave precheck_file and
get_issue the wrong argument names (path and id, where the tools take
file_path and issue_id) and showed search_events without its required
query, so an agent copying the call got a validation error. A test
now checks every call shown to an agent against the tool's actual signature.
(#18)
Upgrading? Run pjm init once in each project. Older projects kept the
AI_INSTRUCTIONS.md and git hooks of the release that created them, so fixes to
either never arrived. pjm 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.
Also: a mistyped issue id no longer breaks every later command, pjm precheck
stops warning about projectmem's own files, and Python 3.13 and 3.14 are
supported.
Fixes for #18 and #20 were contributed by Rohan Tiwari, and the first cap for #19 by hylin. #18 and #19 were reported by @medium-effort, #20 by @bigfree.
✨ 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 matched a reimplementation of the old algorithm, including across merge commits — except for a time-zone bug this change introduced, which 0.3.4 fixes.
A retired decision no longer resurfaces. supersedes has existed since
0.1.4, but the two surfaces an agent actually reads during work — get_context
and precheck_file — were not filtering it. You could retire a decision and
still be told about it. Both filter now, and AI_INSTRUCTIONS.md finally
documents how to retire one, which is why models never called it.
Your project is named in the bridge file, and AGENTS.md is written too.
One server serves every project, so a call naming none is refused rather than
guessed at — but nothing told the agent the name, so it learned it from the
error and retried, every session. The name is in the bridge now. It goes into
AGENTS.md as well as CLAUDE.md, because Antigravity and Codex never read
the latter.
Six Windows reports are closed. Git hooks shipped a bash shebang that
Git for Windows often cannot resolve — and an unresolvable shebang does not
skip the hook, it aborts your commit. The baked binary path lost its
backslashes to shell escaping. The venv fallback looked in bin/, which
cannot exist there. pjm watch --daemon could not be seen or stopped. And a
box-drawing character in the output killed pjm init outright on a cp1252
console — after it had already created everything, so the command both did its
work and reported failure.
Every one was fixed by running projectmem on the machines that reported it — Windows 11, and three MCP clients (Antigravity, Claude, and Codex) — not by reading the code. Reported by @medium-effort, who also contributed the 0.3.2 Windows daemon support.
✨ New in 0.3.2 — Windows, properly
pjm watch --daemon crashed on Windows with AttributeError: module 'os' has no attribute 'fork'. It now spawns a detached worker instead of forking, so
background watching works on every platform.
Fixing that uncovered a second bug hiding behind it. Liveness was checked with
os.kill(pid, 0) — a POSIX idiom that does not port, because on Windows
os.kill routes to TerminateProcess and signal 0 is not a check at all. The
watcher could not be seen or stopped there, and each pjm watch --daemon leaked
another process. Both are fixed.
Windows daemon support was contributed by @medium-effort (#13).
pjm doctor also got two things. It now tells you to quit your AI client
before editing its config — those files hold the app's own preferences too, so
a running client can rewrite the whole thing on exit and restore the --root
you just removed. And it remembers what it saw last time, so a config that was
clean and is pinned again gets named as a revert rather than looking like doctor
being flaky. Local files only; nothing leaves your machine.
✨ New in 0.3.1 — know when to upgrade
Both dashboards now show which version generated the page, with a check for
updates link beside it. The page makes no request until you click — PyPI's
public JSON is fetched straight from your browser and nothing about your machine
is sent. On the command line, pjm doctor --online checks once and
pjm doctor --auto remembers to check daily; both are off unless you ask.
✨ New in 0.3.0 — one server, many projects
Until now an MCP config was tied to one repository: eleven projects meant eleven
server entries and eleven restarts. 0.3.0 serves every registered project from
a single server. Paste the config once; every repo you pjm init afterwards is
reachable from it.
pjm project list # what this server can reach
pjm project use ossdrop # the default when a call names no project
log_issue(summary="stars come back empty", project="ossdrop")
→ Logged issue #0019 → ossdrop: stars come back empty
Every write names the project it landed in — in a shared server, the dangerous
failure is not "nothing works", it is a write that succeeds against the wrong
repo. Existing --root configs keep working untouched, and a pinned server now
refuses to write anywhere else even when asked.
Also in 0.3.0:
- Fixed: the MCP server was broken on fresh installs. mcp 2.0 renamed
FastMCPand left the old import path raising — since 2026-07-28 every newpip install projectmemgot a server that died at import. Caught and fixed by @VIVAAN-DHAWAN. - Security: stored XSS in
pjm visualize. Event summaries reached the DOM unescaped, and git commit messages become event summaries — so a crafted commit in a branch you pulled could run script in your dashboard. Every sink is escaped now. - A rebuilt dashboard — a shareable Memory Card, case files with the full issue → attempt → fix chain, an effort treemap, per-file dossiers, and a global view that opens with where you left off.
Registry migration is automatic: the 0.2.x list of paths is converted on first
read, with a .bak kept beside it.
✨ New in 0.2.0 — the workspace release
0.1.6 made one project's memory something you could watch. 0.2.0 lifts that to your whole workspace — and closes the gap between what happened (memory) and what your code is (structure).
- 🌐 Global dashboard —
pjm dashboardis one page over every project 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 global view, 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+C stops 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's Graph and Flow views 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 ever read. - 🔥 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 you mean to do — deliberately not the 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.
The visualization suite (shipped in 0.1.6)
Your project's memory is also something you can watch — 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), and Universe (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 reading
PROJECT → 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, with problems branching left (issues, failed attempts) and knowledge branching right (fixes, decisions, notes). Hover any card and its whole issue thread lights up. The classic list remains as "Details".
Why You'll Love It
- Pre-Commit Warnings —
pjm precheckwarns you before you commit if you're about to repeat a failed approach, modify a high-churn file, or touch an unresolved issue. It works from this project's own recorded failures, which is why it needs 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) — projectmem never deletes a memory. 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 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. - Estimated ROI Score —
pjm scoreoutputs a letter grade (A+ → F) with the tool's own estimates of debugging hours saved, tokens avoided, and dollars saved. 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 are inherited by new projects. A project with a manifest (pyproject.toml,requirements.txt,package.json,Cargo.toml,go.mod) is offered only the lessons for its 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.
How It Compares
✅ yes · 🟡 partial · ❌ not found in the project's own docs · ? not documented. Snapshot taken 2026-10-02 from each project's README, docs and changelog; design capabilities, not benchmark results. Corrections welcome — open an issue.
There is no database and nothing 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 the optional pjm dashboard --serve, an ephemeral local viewer you start and stop with Ctrl+C.
🚧 Upcoming
- Import your existing memory —
pjm import(planned for 0.4.0) will migrate history from mem0, 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.
Want a source supported? Open an issue and tell us what you're migrating from.
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.
Estimates, not benchmarks. Measured on the 0.3.4 summary itself: about 250 tokens for a young project and about 1,100 for one with 25 issues and 60 decisions; more when many issues are open.
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.
One server, many projects
Since 0.3.0 a single MCP server serves every project you have registered. Paste
the config once and every repo you pjm init afterwards is reachable from it —
no second entry, no restart.
pjm project list # what this server can reach
pjm project use ossdrop # the default when a call names no project
pjm project alias ossdrop od
Your agent picks the project per call:
log_issue(summary="stars come back empty", project="ossdrop")
→ Logged issue #0019 → ossdrop: stars come back empty
Every write says where it landed. That echo is the point: in a one-project setup a misconfigured server simply fails, but a shared server can succeed against the wrong repository, which corrupts two audit trails at once. If the name in the reply is not the project you meant, stop.
How a call is routed, highest first:
Once client roots are wired in, they will outrank the active project on purpose: the root is where you are now, the active project is a mode you set days ago. When they disagree, the stale one is the wrong answer.
Single-repo setups are untouched — pjm init --mcp-config-single still prints
the pinned config, and an existing --root entry keeps working exactly as before.
MCP Integration (Recommended)
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.
Since 0.3.0 you configure this once, not once per repository. The block below has no --root: the server serves every project you have registered, and each call resolves its own. Paste it, and every repo you pjm init from then on is reachable — no second entry, no restart.
"mcpServers": {
"projectmem": {
"command": "/opt/anaconda3/bin/python",
"args": ["-m", "projectmem.mcp_server"]
}
}
Upgrading with projects you already have? The registry only ever recorded
projects you ran pjm init on since it existed (0.2.0), so anything older is
missing — and global mode routes through the registry. One command sorts it out:
pjm doctor # what's unregistered, what's stale, what's still pinned
pjm doctor --fix # register what it found
It looks in the places code actually lives — ~/Developer, ~/code, ~/src,
~/projects and friends, plus every fixed drive on Windows, where projects sit
on D:\ and E:\ as often as under your home folder. To point it somewhere
specific:
pjm doctor --path ~/work --path /Volumes/ssd --fix
pjm project scan D:\ E:\ --depth 3 # the same walk, without the other checks
Nothing is scanned until you run it, and nothing is written without --fix.
After an upgrade the CLI mentions pjm doctor once — a wheel install can't run
code, so the first command you type is the only place to say it.
With one project registered, that is the whole setup — there is only one place a call can go. With several, your AI passes project="<name>", or you set a default with pjm project use <name>. pjm init prints this block with your own Python path already filled in.
Upgrading from 0.2.x? Your existing --root entry keeps working exactly as before, and a pinned server now refuses to write outside its own repo even if asked. Replace it with the block above when you want one server for everything.
The 3-minute workflow (let your AI do the setup)
- Install + init.
pip install projectmem, thencdinto your project and runpjm init— or simply ask your AI to run it. - Ask your AI to set up the projectmem MCP server for you — it can edit the client's config file itself. (It needs permission to do that: use Auto / accept-edits mode, or approve the file edit when asked. The exact config per client is in the sections below if you'd rather paste it by hand.)
- Restart the AI tool so the MCP server loads, then start your session with this prompt:
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(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.
Claude Desktop
Easiest — open the config from the UI:
- 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.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows, ~/.config/Claude/claude_desktop_config.json on Linux (or $XDG_CONFIG_HOME/Claude/ if you have moved it). pjm init prints the right one for the machine you run it on.
Paste this block:
"mcpServers": {
"projectmem": {
"command": "/opt/anaconda3/bin/python",
"args": ["-m", "projectmem.mcp_server"]
}
}
Two things to know about this block:
- Use the absolute path to
python(e.g./opt/anaconda3/bin/python, or runwhich pythonto find yours). Claude Desktop subprocesses don't inherit your shellPATH, so bare"python"often fails. - You no longer need the
cwdfield, and you never could rely on it. Claude Desktop's current build (with the Epitaxy / Cowork workspace system) silently ignorescwd— the server ends up running withcwd=/and can't find.projectmem/. That is why older releases needed--root. The registry replaces it: the server finds projects by name, not by where it happens to be running.
"mcpServers": {
"projectmem": {
"command": "/opt/anaconda3/bin/python",
"args": [
"-m", "projectmem.mcp_server",
"--root", "/absolute/path/to/your/project"
]
}
}
A pinned server serves exactly that repository and refuses to write anywhere else, even when asked — the stricter choice if you want a hard boundary. pjm init --mcp-config-single prints this form.
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:
- Global (recommended): Cursor menu →
Settings…→ left sidebar Tools & MCPs → Installed MCP Servers → Add Custom MCP. Paste the JSON below. - 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"]
}
}
}
Two things to know about this block (same gotchas as Claude Desktop):
- Use the absolute path to
python(runwhich pythonto find yours). Cursor subprocesses don't reliably inherit your shellPATH. - Don't bother with the
cwdfield. Cursor — like Claude Desktop — silently ignores it: the server ends up running withcwd=~. Since 0.3.0 that no longer matters, because projects are found by name in the registry rather than by where the server runs.
Registered globally, one entry covers every project. Per-project .cursor/mcp.json still works if you prefer the server to exist only when that repo is open — add "--root", "/absolute/path/to/your/project" to args there to pin it.
Then fully quit Cursor (Cmd+Q on Mac) and reopen. projectmem also auto-discovers .projectmem/ by walking up from CWD (like git does for .git/), and honors PROJECTMEM_ROOT and a --root <path> CLI argument.
Antigravity
Antigravity (Google's AI IDE) speaks standard MCP.
Easiest — open the config from the UI:
- Open the Agent window (the chat panel on the right).
- Click the ⋯ Additional Options button in the panel header.
- Choose MCP Servers → Manage MCP Servers → Add new (or Edit Config).
The raw file is at ~/.gemini/antigravity/mcp_config.json if you prefer editing it directly.
Paste this block:
{
"mcpServers": {
"projectmem": {
"command": "python",
"args": ["-m", "projectmem.mcp_server"]
}
}
}
Antigravity does honor the cwd field, so adding "cwd": "/absolute/path/to/your/project" works — but it ties the server to that one repo. Leave it out and the same entry serves every registered project.
Then fully quit Antigravity (Cmd+Q on Mac) and reopen — MCP servers only initialize on cold start. All 17 projectmem tools register identically to Claude Desktop / Cursor.
Codex
Codex stores MCP config as TOML (not JSON) in ~/.codex/config.toml. There's a UI form at Settings → MCP Servers → Add MCP Server, but during cross-client verification the form's Save button didn't reliably persist — the file-edit path is faster and more reliable.
Easiest — edit ~/.codex/config.toml directly:
Append this block (preserves any existing config):
[mcp_servers.projectmem]
command = "/opt/anaconda3/bin/python"
args = ["-m", "projectmem.mcp_server"]
Three things to know about this block:
- Use the absolute path to
python(runwhich pythonto find yours). Codex subprocesses don't reliably inherit your shellPATH. - You no longer need
--rootorcwd. Earlier releases passed--rootas defense in depth (thecwdfield does appear to work in Codex, unlike Claude Desktop and Cursor). Since 0.3.0 the registry makes both unnecessary — add"--root", "/absolute/path/to/your/project"toargsonly if you want this server locked to a single repo. - Set your reasoning effort to
mediumor higher. On low-reasoning Codex skipsget_instructionsfrom the session-start trio, which can cause the AI to miss the Setup Mode workflow rules. Medium+ honors the full trio automatically.
Validate the TOML:
python -c "import tomllib; tomllib.load(open('/Users/<you>/.codex/config.toml','rb')); print('OK')"
Should print OK. If not, the parser tells you the offending line.
Then fully quit Codex (Cmd+Q on Mac) and reopen. Same cold-start rule as every other MCP client. Codex MCP servers spawn lazily on the first tool call in a chat session — if you don't see the process in ps aux right after reopening, send any message to a Codex chat and check again.
Reasoning-effort note: Codex's mode selector is at the bottom of the chat input. Set it to medium (not low) for the full session-start trio behavior. Once set, it persists per-session.
First-run permission prompts
On first use in any MCP-capable client (Claude Desktop, Cursor, Antigravity, Codex), your AI will ask permission before each projectmem tool call. This is expected security behavior — MCP clients require explicit consent for every new tool. Approve each tool once and the prompt won't reappear for that session.
Other MCP Tools
Any MCP-compatible client works — point your tool at
python -m projectmem.mcp_server and either set cwd to your project
root or rely on the parent-walk auto-discovery.
MCP Tools Exposed
All 17 tools your AI can call. Every repo tool takes an optional
project argument — see One server, many projects:
Read-side (12 tools):
Write-side (5 tools):
CLI Reference
Core memory
Intelligence layer
Projects (global MCP)
Visualization & utility
Use
--at "file.py:42"with any logging command to attach precise location metadata.
plan.md — intent, kept separate from memory
pjm init scaffolds a .projectmem/plan.md: your ideas and plans — what you mean to do, in plain Markdown (Ideas · Active plans · Next · Someday · Shipped). It's the one file that is deliberately not the event log:
events.jsonl → summary.mdrecords what happened (append-only, never rewritten).plan.mdrecords what you intend — and you (or the AI) edit it directly, likePROJECT_MAP.md.
Your AI reads it at session start via get_plan() and updates it in place: adding ideas, checking items off, moving finished work down to Shipped. A plan is never logged as an event, so intent stays cleanly out of your memory's audit trail. pjm plan prints it; pjm plan "auto-batch the exporter" appends an idea. It's committed (not gitignored) so intent is shared with your team.
Example: Pre-Commit Warnings in Action
$ git commit -m "switch auth to JWT"
projectmem: Pre-Commit Check
─────────────────────────────────────────────
src/auth/middleware.py
WARN What already failed here (2 attempts):
✗ tried switching to JWT middleware (2d ago)
✗ patched session timeout to 60min (5d ago)
WARN HIGH CHURN: 5 changes in last 30 days
WARN 1 possibly-stale memory cites this file
decision [evt_9db5a3f8…] "auth uses session
cookies, 30min timeout" — predates 7 commits
Confirm it still holds, or retire it:
pjm decision "..." --supersedes <id>
─────────────────────────────────────────────
3 warning(s). Review before committing.
Need it quiet for a refactor sprint? pjm precheck --snooze 2h — warnings pause, the pause itself is logged, and every commit shows one dim line so silence is never mistaken for a clean check.
Privacy & Security
By default, projectmem commits the distilled files (summary.md, PROJECT_MAP.md, AI_INSTRUCTIONS.md, issues/) and gitignores the raw log + runtime files (events.jsonl, watch.pid, watch.log). This means your teammate's AI inherits your team's knowledge automatically — just git clone and the AI already knows what your team learned.
Want total privacy? Add a single line .projectmem/ to your .gitignore. Nothing leaves your machine.
Full security policy and threat model: SECURITY.md · Privacy & Security guide
Design Principles
- Local-first — No cloud, no telemetry, and no network calls unless you turn on the update check. 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.
Built With
projectmem stands on the shoulders of these excellent open-source projects:
- Typer — the CLI framework that makes
pjmfeel ergonomic - Model Context Protocol — Anthropic's open spec that lets AI agents talk to local tools
- watchdog — cross-platform filesystem event monitoring (the heart of
pjm watch) - D3.js — the interactive visualizations in
pjm visualize
Research & Citation
projectmem is described in a peer-readable research paper:
PROJECTMEM: A Local-First, Event-Sourced Memory and Judgment Layer for AI Coding Agents Ripon Chandra Malo, Tong Qiu — University of Utah arXiv:2606.12329 · cs.AI
The paper introduces the Memory-as-Governance framing — memory that doesn't merely answer the agent but acts on its next action — and reports the design, the deterministic pre-commit judgment gate, a capability comparison against 12 contemporary memory systems, and a two-month, 207-event dogfooding study across 10 real projects.
If projectmem is useful in your research or writing, please cite:
@misc{malo2026projectmem,
title = {PROJECTMEM: A Local-First, Event-Sourced Memory and
Judgment Layer for AI Coding Agents},
author = {Malo, Ripon Chandra and Qiu, Tong},
year = {2026},
eprint = {2606.12329},
archivePrefix = {arXiv},
primaryClass = {cs.AI},
url = {https://arxiv.org/abs/2606.12329}
}
License
MIT — free for personal, commercial, and enterprise use forever.
Help Us Reach More Developers
We don't need money. We need you.
projectmem was started by one developer and is now shaped by contributors from the open-source community. Every star, every share, and every contribution helps the project survive and grow.
- Star the repo — takes one click, helps massively with discovery
- Share on X / LinkedIn — tell other devs they don't have to keep paying AI to relearn their codebase
- Open an issue — bug, feature request, or just feedback
- Contribute code — PRs welcome; for anything large, open an issue first
- Using
projectmemat work or in a commercial product? Reach out to [email protected] so we know who's shipping with us. It's free — we just love hearing about it.
Stars and shares matter more than money — but if you really want to: sponsor on GitHub →
