Skip to content
Back to search

projectmem

Open-source coding agents memory. Records issues, attempts, fixes and decisions, then warns your agent before it repeats an approach that already failed. Native MCP server for Claude Code, Cursor, Antigravity and Codex. 100% local, no cloud, no telemetry. MIT.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/riponcm--projectmem/badge.svg)](/listings/riponcm--projectmem)

HTML

<a href="/listings/riponcm--projectmem"><img src="/api/listings/riponcm--projectmem/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

> **First time here?** → **[The complete setup guide](https://projectmem.dev/blog/projectmem-complete-guide-ai-coding-agent-memory)** > 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.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 937 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <!-- mcp-name: io.github.riponcm/projectmem -->
  2. <div align="center">
  3. <img src="https://raw.githubusercontent.com/projectmem/projectmemdoc/main/logo/projectmem-wordmark-800.png" alt="projectmem" width="420" />
  4. <p>
  5. <a href="https://github.com/riponcm/projectmem/blob/main/CHANGELOG.md"><b>🎉 v0.3.5 is out</b></a> —
  6. precheck recognises a file however its path is spelled, and the summary stays small even when entries are long.
  7. <a href="https://github.com/riponcm/projectmem/blob/main/CHANGELOG.md">See what changed →</a>
  8. </p>
  9. <p><b>We don't make AI smarter. We make it experienced.</b></p>
  10. <p><i><b>Coding agent memory</b> — the local-first memory + judgment layer for AI coding agents. One MCP server for every project. Stop re-reading your project every session. Stop repeating yesterday's bug.</i></p>
  11. <p>
  12. <a href="https://pypi.org/project/projectmem/"><img src="https://img.shields.io/pypi/v/projectmem.svg?color=4c1d95&label=pypi" alt="PyPI version"></a>
  13. <a href="https://pypi.org/project/projectmem/"><img src="https://img.shields.io/pypi/pyversions/projectmem.svg?color=3b82f6" alt="Python Versions"></a>
  14. <a href="https://pepy.tech/project/projectmem"><img src="https://static.pepy.tech/personalized-badge/projectmem?period=month&units=abbreviation&left_color=grey&right_color=brightgreen&left_text=downloads%2Fmonth" alt="PyPI downloads per month"></a>
  15. <a href="https://github.com/riponcm/projectmem/stargazers"><img src="https://img.shields.io/github/stars/riponcm/projectmem?style=flat&color=f59e0b&label=stars" alt="GitHub stars"></a>
  16. <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-3b82f6.svg" alt="License: MIT"></a>
  17. <a href="https://arxiv.org/abs/2606.12329"><img src="https://img.shields.io/badge/arXiv-2606.12329-b31b1b.svg" alt="arXiv paper"></a>
  18. </p>
  19. <p>
  20. <a href="https://ossdrop.com/tool/projectmem"><img src="https://ossdrop.com/badge/projectmem" width="250" height="56" alt="projectmem on OSSDrop" /></a>
  21. </p>
  22. <p>
  23. <a href="https://projectmem.dev"><b>Website</b></a> •
  24. <a href="https://projectmem.dev/guide"><b>Guide</b></a> •
  25. <a href="https://projectmem.dev/demo"><b>Demo</b></a> •
  26. <a href="https://projectmem.dev/changelog"><b>Changelog</b></a> •
  27. <a href="https://arxiv.org/abs/2606.12329"><b>Paper</b></a>
  28. </p>
  29. <br />
  30. https://github.com/user-attachments/assets/e055988e-7253-4ba9-92fc-95d3d4bcd763
  31. <br /><br />
  32. <img src="https://raw.githubusercontent.com/projectmem/projectmemdoc/main/screenshots/dashboard-overview-0.3.0.png" alt="projectmem dashboard — coding agent memory for one project: memory card, failure heatmap, ROI and case files" width="860" />
  33. <p><sub><code>pjm visualize</code> — every case your project solved, what failed on the way, and what it saved. Generated locally from <code>.projectmem/events.jsonl</code>.</sub></p>
  34. </div>
  35. ---
  36. > ## 🚀 Start here — five minutes, once
  37. >
  38. > *Five minutes if you follow along here. Want to be shown instead — every
  39. > command, the exact output it prints back, and the dashboards at the end?
  40. > Take **[the complete setup guide](https://projectmem.dev/blog/projectmem-complete-guide-ai-coding-agent-memory)**.*
  41. >
  42. > **New to projectmem, or upgrading from 0.1.x / 0.2.x?** Since 0.3.0 one MCP
  43. > server serves every project, so this is the last time you configure anything.
  44. >
  45. > **1. Install or update**
  46. >
  47. > ```bash
  48. > pip install -U projectmem
  49. > ```
  50. >
  51. > **2. Find the projects you already have**
  52. >
  53. > ```bash
  54. > pjm doctor
  55. > ```
  56. >
  57. > It looks where code lives — `~/Developer`, `~/code`, `~/projects`, your cloud
  58. > folders, and every drive on Windows — and lists projects with memory that
  59. > aren't registered yet. Anything it missed, add by hand:
  60. >
  61. > ```bash
  62. > pjm project register "/Users/you/Developer/repos/ossdrop"
  63. > ```
  64. >
  65. > **3. Register them**
  66. >
  67. > ```bash
  68. > pjm doctor --fix
  69. > ```
  70. >
  71. > **4. Point your AI at all of them with one config**
  72. >
  73. > ```json
  74. > "mcpServers": {
  75. > "projectmem": {
  76. > "command": "/absolute/path/to/python",
  77. > "args": ["-m", "projectmem.mcp_server"]
  78. > }
  79. > }
  80. > ```
  81. >
  82. > No `--root`, no `cwd` — that's what makes it serve everything. Per-client
  83. > instructions (Claude Desktop, Claude Code, Cursor, Antigravity, Codex) are in
  84. > [MCP Integration](#mcp-integration-recommended); `pjm init` prints this block
  85. > with your own Python path filled in. **Then fully restart the client** — MCP
  86. > servers only load on a cold start.
  87. >
  88. > **5. Check your work**
  89. >
  90. > ```bash
  91. > pjm doctor
  92. > ```
  93. >
  94. > Add `--online` if you also want it to tell you when a newer projectmem is out
  95. > — projectmem makes no network calls otherwise, and `--auto` turns that into a
  96. > once-a-day check if you prefer.
  97. >
  98. > Run it again after editing the config. It flags any client still pinned to a
  99. > single repo — the most common reason a new project is invisible to your agent.
  100. >
  101. > **All green? You're done.** From here on it is one command per repo:
  102. >
  103. > ```bash
  104. > pjm init
  105. > ```
  106. >
  107. > Your agent reads what the project already learned instead of rediscovering it,
  108. > and writes down what it finds. Fewer tokens, no repeated dead ends, memory that
  109. > outlives the session.
  110. ---
  111. ## What is coding agent memory?
  112. **Coding agent memory is a persistent record of what happened while building a
  113. project** — the issues hit, the approaches attempted, the fixes that worked and
  114. the decisions made — stored so an AI coding agent can read it at the start of a
  115. new session. Without it every session begins from zero.
  116. projectmem is an open-source **agent memory** layer built for that job. It is
  117. **local-first**: memory lives in a plain `.projectmem/` directory inside your
  118. repository, with no cloud, no account and no telemetry — the only network call
  119. it can make is an update check you turn on yourself. A native **MCP server**
  120. exposes 17 tools to Claude Code, Claude Desktop, Cursor, Antigravity and Codex,
  121. so your agent reads memory and logs its work on its own.
  122. Unlike chat-history memory tools, projectmem stores **typed events** — issues,
  123. attempts, fixes, decisions, notes — which is what makes its signature feature possible: a **pre-commit warning**
  124. that fires *before* you repeat an approach that already failed in this project.
  125. ```bash
  126. pip install projectmem
  127. cd your-project && pjm init
  128. ```
  129. ---
  130. ## 🎬 Watch the demo
  131. <p align="center">
  132. <a href="https://youtu.be/pELGdXHj_Ls">
  133. <img src="https://img.youtube.com/vi/pELGdXHj_Ls/maxresdefault.jpg" alt="projectmem — 60-second demo" width="720" />
  134. </a>
  135. <br />
  136. <em>Full screen-recorded tutorial- watch on YouTube</em>
  137. </p>
  138. ## 📚 Docs
  139. | Doc | What's in it |
  140. |---|---|
  141. | **[Complete setup guide](https://projectmem.dev/blog/projectmem-complete-guide-ai-coding-agent-memory)** | The full walkthrough on the web — install, MCP setup per client, `pjm doctor`, your first logged issue, and both dashboards. Every terminal output is captured from a real run. |
  142. | **[TUTORIAL.md](https://github.com/riponcm/projectmem/blob/main/TUTORIAL.md)** | 15-minute step-by-step walkthrough — set up projectmem on your own project, watch the lifecycle, see the pre-commit warning fire. |
  143. | **[CHANGELOG.md](https://github.com/riponcm/projectmem/blob/main/CHANGELOG.md)** | Release history. Latest: v0.3.5 — precheck matches every spelling of a path, and long entries no longer bloat the summary. |
  144. | **[Research paper (arXiv:2606.12329)](https://arxiv.org/abs/2606.12329)** | *PROJECTMEM: A Local-First, Event-Sourced Memory and Judgment Layer for AI Coding Agents* — the peer-readable version: design, Memory-as-Governance framing, capability comparison, and the 207-event dogfooding study. |
  145. | **[LICENSE](https://github.com/riponcm/projectmem/blob/main/LICENSE)** | MIT |
  146. ---
  147. ## The Problem
  148. 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.
  149. The model isn't the problem. **The architecture is.** Stateless models need a memory cortex.
  150. ## The Solution
  151. `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.
  152. ## Install
  153. > **First time here?** → **[The complete setup guide](https://projectmem.dev/blog/projectmem-complete-guide-ai-coding-agent-memory)**
  154. > walks the whole path end to end: install, connecting Claude Desktop, Claude Code,
  155. > Cursor, Codex or Antigravity, checking it with `pjm doctor`, and reading your
  156. > memory back through the dashboards — with the real terminal output at every step.
  157. Three commands to a project that remembers:
  158. ```bash
  159. pip install projectmem
  160. cd your-project
  161. pjm init
  162. ```
  163. 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.
  164. > The canonical command is `projectmem`. A `pjm` alias is installed for speed.
  165. ---
  166. ## ✨ New in 0.3.5 — warnings for every spelling, and a summary that stays small
  167. **Precheck recognises a file however its path is spelled.** Events store
  168. project-relative paths, so asking about `./src/auth.py`, an absolute path, a
  169. path through a symlinked folder or a Windows `C:\` path matched nothing, and
  170. precheck called a file with known failures "Safe to modify". Every spelling now
  171. gets the same warnings, and checking is faster on large logs.
  172. `get_issue("1")` and `get_issue("#1")` find issue 0001.
  173. ([#26](https://github.com/riponcm/projectmem/pull/26))
  174. **Long entries no longer bloat the summary.** 0.3.4 capped how many entries
  175. the summary shows, not how long each one is. Records are now clipped at 300
  176. characters, and a fixed issue takes one line. On a real 238-event project the
  177. summary went from 8,974 tokens to 3,458.
  178. ([#29](https://github.com/riponcm/projectmem/issues/29),
  179. [#30](https://github.com/riponcm/projectmem/pull/30))
  180. **Upgrading? Run `pjm init` once in each project.** The instructions now ask
  181. agents for shorter records, and `pjm init` refreshes `AI_INSTRUCTIONS.md`,
  182. keeping your previous copy as `AI_INSTRUCTIONS.md.bak`.
  183. The #26 fixes were contributed by [@vishalhabib99](https://github.com/vishalhabib99),
  184. and #29 was reported and fixed by [@bigfree](https://github.com/bigfree).
  185. ## ✨ New in 0.3.4 — memory that stays small, and warnings you can trust
  186. **The summary no longer grows forever.** Notes were capped, but Recent issues
  187. and Decisions listed everything ever logged, so on an aged project reading the
  188. memory cost more than reading the code. Every **open** issue is still shown —
  189. the newest 20 in full, older ones by id — while fixed issues are capped at the
  190. newest 10 and decisions at the newest 15, each with a line saying what was left
  191. out and where to find it. On a test project with 25 issues and 60 decisions the
  192. summary went from about 2,900 tokens to about 1,100.
  193. ([#19](https://github.com/riponcm/projectmem/issues/19))
  194. **Commits are filed under the code they change.** Auto-capture used the first
  195. changed path in git's sort order, which was usually the regenerated
  196. `.projectmem/summary.md` — so valid memories were flagged stale and the real
  197. file lost its history. The location is now the source file the commit is about,
  198. with deletions, renames, merges and a repository's first commit handled.
  199. ([#20](https://github.com/riponcm/projectmem/issues/20))
  200. **Stale warnings no longer depend on your time zone.** A 0.3.3 speed-up compared
  201. git's local-time commit dates with UTC event times as text: west of UTC, recent
  202. stale memories were never flagged; east of UTC, fresh ones were flagged at once.
  203. Both sides are compared in UTC now, and events already filed under
  204. `.projectmem/` stop warning without your log being rewritten.
  205. **The guidance names the tools' real arguments.** It gave `precheck_file` and
  206. `get_issue` the wrong argument names (`path` and `id`, where the tools take
  207. `file_path` and `issue_id`) and showed `search_events` without its required
  208. `query`, so an agent copying the call got a validation error. A test
  209. now checks every call shown to an agent against the tool's actual signature.
  210. ([#18](https://github.com/riponcm/projectmem/issues/18))
  211. **Upgrading? Run `pjm init` once in each project.** Older projects kept the
  212. `AI_INSTRUCTIONS.md` and git hooks of the release that created them, so fixes to
  213. either never arrived. `pjm init` now refreshes both — your previous instructions
  214. are kept as `AI_INSTRUCTIONS.md.bak`, and anything of yours outside
  215. projectmem's block in a hook is left untouched.
  216. Also: a mistyped issue id no longer breaks every later command, `pjm precheck`
  217. stops warning about projectmem's own files, and Python 3.13 and 3.14 are
  218. supported.
  219. Fixes for #18 and #20 were contributed by [Rohan Tiwari](https://github.com/RTE404),
  220. and the first cap for #19 by [hylin](https://github.com/linhongyu510). #18 and #19
  221. were reported by [@medium-effort](https://github.com/medium-effort), #20 by
  222. [@bigfree](https://github.com/bigfree).
  223. ## ✨ New in 0.3.3 — precheck stops getting slower, and Windows works end to end
  224. `pjm precheck` runs before every edit — the instructions tell agents to call it
  225. first — so its cost is paid constantly. It was taking **26 seconds on a
  226. 1,200-event project**, and getting worse every week, because it ran one
  227. `git log` per event to answer a question about a single file. It now makes one
  228. call per distinct *file*, bounded by the oldest event citing it.
  229. | events | before | after |
  230. |---|---|---|
  231. | 100 | 2,210 ms | 48 ms |
  232. | 400 | 8,905 ms | 51 ms |
  233. | 1,500 | ~33 s, 1,501 git processes | **82 ms, 2 processes** |
  234. Latency is now flat rather than linear in project age. Results matched a
  235. reimplementation of the old algorithm, including across merge commits — except
  236. for a time-zone bug this change introduced, which 0.3.4 fixes.
  237. **A retired decision no longer resurfaces.** `supersedes` has existed since
  238. 0.1.4, but the two surfaces an agent actually reads during work — `get_context`
  239. and `precheck_file` — were not filtering it. You could retire a decision and
  240. still be told about it. Both filter now, and `AI_INSTRUCTIONS.md` finally
  241. documents how to retire one, which is why models never called it.
  242. **Your project is named in the bridge file, and `AGENTS.md` is written too.**
  243. One server serves every project, so a call naming none is refused rather than
  244. guessed at — but nothing told the agent the name, so it learned it from the
  245. error and retried, every session. The name is in the bridge now. It goes into
  246. `AGENTS.md` as well as `CLAUDE.md`, because Antigravity and Codex never read
  247. the latter.
  248. **Six Windows reports are closed.** Git hooks shipped a `bash` shebang that
  249. Git for Windows often cannot resolve — and an unresolvable shebang does not
  250. skip the hook, it aborts your commit. The baked binary path lost its
  251. backslashes to shell escaping. The venv fallback looked in `bin/`, which
  252. cannot exist there. `pjm watch --daemon` could not be seen or stopped. And a
  253. box-drawing character in the output killed `pjm init` outright on a cp1252
  254. console — after it had already created everything, so the command both did its
  255. work and reported failure.
  256. Every one was fixed by running projectmem on the machines that reported it —
  257. Windows 11, and three MCP clients (Antigravity, Claude, and Codex) — not by reading the code. Reported by
  258. [@medium-effort](https://github.com/riponcm/projectmem/issues), who also
  259. contributed the 0.3.2 Windows daemon support.
  260. ## ✨ New in 0.3.2 — Windows, properly
  261. `pjm watch --daemon` crashed on Windows with `AttributeError: module 'os' has no
  262. attribute 'fork'`. It now spawns a detached worker instead of forking, so
  263. background watching works on every platform.
  264. Fixing that uncovered a second bug hiding behind it. Liveness was checked with
  265. `os.kill(pid, 0)` — a POSIX idiom that does not port, because on Windows
  266. `os.kill` routes to `TerminateProcess` and signal 0 is not a check at all. The
  267. watcher could not be seen or stopped there, and each `pjm watch --daemon` leaked
  268. another process. Both are fixed.
  269. Windows daemon support was contributed by
  270. [@medium-effort](https://github.com/medium-effort) ([#13](https://github.com/riponcm/projectmem/pull/13)).
  271. `pjm doctor` also got two things. It now tells you to **quit your AI client
  272. before editing its config** — those files hold the app's own preferences too, so
  273. a running client can rewrite the whole thing on exit and restore the `--root`
  274. you just removed. And it remembers what it saw last time, so a config that was
  275. clean and is pinned again gets named as a revert rather than looking like doctor
  276. being flaky. Local files only; nothing leaves your machine.
  277. ## ✨ New in 0.3.1 — know when to upgrade
  278. Both dashboards now show which version generated the page, with a **check for
  279. updates** link beside it. The page makes no request until you click — PyPI's
  280. public JSON is fetched straight from your browser and nothing about your machine
  281. is sent. On the command line, `pjm doctor --online` checks once and
  282. `pjm doctor --auto` remembers to check daily; both are off unless you ask.
  283. ## ✨ New in 0.3.0 — one server, many projects
  284. Until now an MCP config was tied to one repository: eleven projects meant eleven
  285. server entries and eleven restarts. **0.3.0 serves every registered project from
  286. a single server.** Paste the config once; every repo you `pjm init` afterwards is
  287. reachable from it.
  288. ```bash
  289. pjm project list # what this server can reach
  290. pjm project use ossdrop # the default when a call names no project
  291. ```
  292. ```
  293. log_issue(summary="stars come back empty", project="ossdrop")
  294. → Logged issue #0019 → ossdrop: stars come back empty
  295. ```
  296. Every write names the project it landed in — in a shared server, the dangerous
  297. failure is not "nothing works", it is a write that succeeds against the wrong
  298. repo. Existing `--root` configs keep working untouched, and a pinned server now
  299. *refuses* to write anywhere else even when asked.
  300. Also in 0.3.0:
  301. - **Fixed: the MCP server was broken on fresh installs.** mcp 2.0 renamed
  302. `FastMCP` and left the old import path raising — since 2026-07-28 every new
  303. `pip install projectmem` got a server that died at import. Caught and fixed by
  304. [@VIVAAN-DHAWAN](https://github.com/riponcm/projectmem/pull/10).
  305. - **Security: stored XSS in `pjm visualize`.** Event summaries reached the DOM
  306. unescaped, and git commit messages become event summaries — so a crafted
  307. commit in a branch you pulled could run script in your dashboard. Every sink
  308. is escaped now.
  309. - **A rebuilt dashboard** — a shareable Memory Card, case files with the full
  310. issue → attempt → fix chain, an effort treemap, per-file dossiers, and a
  311. global view that opens with where you left off.
  312. Registry migration is automatic: the 0.2.x list of paths is converted on first
  313. read, with a `.bak` kept beside it.
  314. ## ✨ New in 0.2.0 — the workspace release
  315. 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).**
  316. - 🌐 **Global dashboard** — `pjm dashboard` is one page over *every* project you've `pjm 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 **`--serve`** for a tiny, ephemeral live server where the Refresh button re-reads your files — no background daemon, **Ctrl+C** stops it.
  317. - 🧬 **Structure & relations** — `pjm map --build` (run automatically at `pjm 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*.
  318. - 🔥 **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.
  319. - 🗂️ **`plan.md`** — a new editable intent file: **ideas and plans, what you *mean* to do** — deliberately *not* the event log. `events.jsonl → summary.md` records what happened; `plan.md` records 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"` / MCP `get_plan()`.
  320. Everything stays 100% local — the global dashboard is a read-time aggregate, never a central honeypot of your code's history.
  321. <p align="center">
  322. <img src="https://raw.githubusercontent.com/riponcm/projectmem/main/brand/dashboard-global.png" alt="projectmem global dashboard — every project in one read-time view" width="880" />
  323. <br /><em>Global Dashboard — every <code>pjm init</code>-ed project in one view: grades, issues, savings, and a "needs attention" list, aggregated at read time. Each card opens that repo's own dashboard.</em>
  324. </p>
  325. ### The visualization suite (shipped in 0.1.6)
  326. Your project's memory is also something you can *watch* — and share.
  327. - 🎬 **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).
  328. - ⏺ **Built-in recorder** — hit REC (10–60 s) and Showoff downloads a `.webm` clip of the animation, rendered 100% locally with a "made with projectmem" badge. Your debugging story, ready for a tweet or a standup.
  329. - 🗺️ **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 the `events.jsonl` cylinder. Tree and Graph views are one click away.
  330. - 🧵 **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".
  331. <p align="center">
  332. <img src="https://raw.githubusercontent.com/riponcm/projectmem/main/brand/dashboard-showoff-universe.png" alt="Showoff — your project as a rotating galaxy, every star a real event" width="800" />
  333. <br /><em>Showoff · Universe — every bright star is a real event from this project's memory</em>
  334. </p>
  335. <p align="center">
  336. <img src="https://raw.githubusercontent.com/riponcm/projectmem/main/brand/dashboard-projectmap-flow.png" alt="Flow — layered project map from project to memory" width="800" />
  337. <br /><em>Project Map · Flow — what happened, file by file, flowing into append-only memory</em>
  338. </p>
  339. <p align="center">
  340. <img src="https://raw.githubusercontent.com/riponcm/projectmem/main/brand/dashboard-timeline-spine.png" alt="Time Spine — problems branch left, knowledge branches right" width="800" />
  341. <br /><em>Timeline · Time Spine — problems on the left, knowledge on the right, real time down the middle</em>
  342. </p>
  343. ---
  344. ## Why You'll Love It
  345. - **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. 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"*), and `pjm precheck --snooze 2h` silences it politely — the snooze is itself logged, so even the silence is audited.
  346. - **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.
  347. - **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.
  348. - **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.
  349. - **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.
  350. - **Estimated ROI Score** — `pjm score` outputs 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.
  351. - **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.
  352. - **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`.
  353. - **Native MCP Server** — Plugs into Claude Desktop, Cursor, Antigravity, Codex, and any MCP-compatible tool. 17 native tools force the AI to read context, check files for known failures, read your `plan.md`, and log work automatically. Verified end-to-end in all four clients at first release; the 0.3.3 acceptance suite was re-run in Antigravity, Claude, and Codex.
  354. - **Interactive Dashboard** *(expanded in 0.1.6)* — `pjm visualize` opens a six-tab local dashboard: Overview, Story Map (failure heatmap with collapse/focus controls), ROI Dashboard, Project Map (**Flow** / Tree / Graph, now over your real code structure), Timeline (**Time Spine** / Details), and **Showoff** — animated story scenes with a built-in video recorder.
  355. - **One MCP server for every project** *(new in 0.3.0)* — configure your client once instead of once per repository. Calls name their project (`project="ossdrop"`), or fall back to the active one; every write reports which repo it landed in, and a pinned `--root` server refuses to write outside its own. Existing single-project setups are untouched.
  356. - **Global Dashboard** *(new in 0.2.0)* — `pjm dashboard` is one cross-project view over every repo you've `pjm init`-ed: grades, issues, savings, and per-project drill-in. A global *view*, never a global *store* — each repo's memory is aggregated at read time and never leaves its folder. Serverless by default; `--serve` for an ephemeral live server (Ctrl+C to stop).
  357. - **Code Structure + Judgment** *(new in 0.2.0)* — `pjm map --build` reads your codebase into a real import graph, and the Project Map overlays **failure heat** from your event log on top: the files that keep breaking, glowing red over the structure that actually connects them. The structure cache is derived from code and gitignored — never committed.
  358. - **Intent, separate from memory** *(new in 0.2.0)* — `plan.md` holds ideas and plans (what you *mean* to do), kept deliberately apart from the append-only event log (what *happened*). `pjm plan`, or the MCP `get_plan()`; the AI edits it directly and a plan never becomes an event.
  359. - **100% Local** — No cloud, no telemetry, no accounts. Your code, your memory, your machine.
  360. ## How It Compares
  361. | Capability | **projectmem** | claude-mem | agentmemory | mem0 | Letta |
  362. |---|:---:|:---:|:---:|:---:|:---:|
  363. | Core focus | **Memory + judgment** | Session capture | Memory engine | Chat / user memory | Agent harness |
  364. | Warns before a commit from a file's own failure history | ✅ | ❌ | ❌ | ❌ | ❌ |
  365. | Checks memory for staleness against git history | ✅ | ❌ | 🟡 links sessions to commits; time decay | ❌ | ❌ |
  366. | Failed attempts as typed events | ✅ worked / partial / failed | 🟡 bugfix type | 🟡 captures tool failures | ❌ | ❌ |
  367. | Keeps superseded memories (no deletion) | ✅ | ? | 🟡 versioned, but decay can evict | ✅ add-only since v3 | ✅ git-versioned memory |
  368. | Cross-project lessons | ✅ stack-scoped with a manifest | 🟡 opt-in flag | 🟡 cross-project search | 🟡 user-scoped | 🟡 per agent |
  369. | Runs locally with no LLM API key | ✅ | 🟡 local store, LLM compression | ✅ keyless mode | ❌ self-host needs a key | 🟡 local mode |
  370. | Native MCP server | ✅ 17 tools | ✅ | ✅ 54 tools | 🟡 hosted only | ❌ MCP client |
  371. | Price · licence | Free · MIT | Free · Apache-2.0, paid Pro | Free · Apache-2.0 | Free tier · Apache-2.0, paid cloud | Free tier · Apache-2.0, paid cloud |
  372. <sub>✅ 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](https://github.com/riponcm/projectmem/issues).</sub>
  373. <sub>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.</sub>
  374. ## 🚧 Upcoming
  375. - **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.
  376. Want a source supported? [Open an issue](https://github.com/riponcm/projectmem/issues) and tell us what you're migrating from.
  377. ## How AI Reads Your Memory (Token Efficiency)
  378. The architecture is built around one rule: **AI reads small, distilled files. Tools generate them from the big raw log.**
  379. *Measured on 0.3.5 with the `cl100k_base` tokenizer, on nine real projects of
  380. 9 to 238 events.* At session start an agent reads three files.
  381. `AI_INSTRUCTIONS.md` is about 3,300 tokens and costs the same in every project.
  382. `summary.md` ranged from about 400 to 3,500 tokens, and `PROJECT_MAP.md` from
  383. about 100 to 900. A synthetic worst case with 40 open issues and long entries in
  384. every record brings the summary to about 6,300. The baseline and `pjm wrap` rows
  385. are estimates.
  386. | Access mode | Tokens / session | How it works |
  387. |---|---|---|
  388. | No projectmem (baseline) | 5,000 – 20,000+ | AI re-reads source files every session |
  389. | Universal Mode (markdown) | ~3,700 – 7,600 | AI reads 3 distilled files once |
  390. | **MCP Mode** *(recommended)* | **~3,700 – 7,600** at session start | AI calls `get_instructions()`, `get_summary()` and `get_project_map()`, then `get_issue(issue_id)` or `precheck_file(file_path)` only when relevant |
  391. | `pjm wrap` (pre-injection) | 500 – 2,000 | Pre-generated, you set the budget |
  392. **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.
  393. ## One server, many projects
  394. Since 0.3.0 a single MCP server serves every project you have registered. Paste
  395. the config once and every repo you `pjm init` afterwards is reachable from it —
  396. no second entry, no restart.
  397. ```bash
  398. pjm project list # what this server can reach
  399. pjm project use ossdrop # the default when a call names no project
  400. pjm project alias ossdrop od
  401. ```
  402. Your agent picks the project per call:
  403. ```
  404. log_issue(summary="stars come back empty", project="ossdrop")
  405. → Logged issue #0019 → ossdrop: stars come back empty
  406. ```
  407. **Every write says where it landed.** That echo is the point: in a one-project
  408. setup a misconfigured server simply fails, but a shared server can succeed
  409. against the wrong repository, which corrupts two audit trails at once. If the
  410. name in the reply is not the project you meant, stop.
  411. How a call is routed, highest first:
  412. | | Source | Notes |
  413. |---|---|---|
  414. | 1 | `--root` at startup | A boundary, not a default. A pinned server refuses to write elsewhere, even when asked. |
  415. | 2 | `project="…"` on the call | id, alias or path. An unknown name is an error. |
  416. | 3 | The client's workspace root | *Planned for 0.4.0* — the resolver supports it, but MCP clients don't pass their roots to it yet. |
  417. | 4 | The active project | `pjm project use <name>`. |
  418. | 5 | The working directory | Walks up looking for `.projectmem/`, like git. |
  419. | 6 | — | Refuses, and lists what is registered. It never guesses. |
  420. Once client roots are wired in, they will outrank the active project on
  421. purpose: the root is where you are now, the active project is a mode you set
  422. days ago. When they disagree, the stale one is the wrong answer.
  423. Single-repo setups are untouched — `pjm init --mcp-config-single` still prints
  424. the pinned config, and an existing `--root` entry keeps working exactly as before.
  425. ## MCP Integration (Recommended)
  426. **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.
  427. **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.
  428. ```json
  429. "mcpServers": {
  430. "projectmem": {
  431. "command": "/opt/anaconda3/bin/python",
  432. "args": ["-m", "projectmem.mcp_server"]
  433. }
  434. }
  435. ```
  436. **Upgrading with projects you already have?** The registry only ever recorded
  437. projects you ran `pjm init` on since it existed (0.2.0), so anything older is
  438. missing — and global mode routes through the registry. One command sorts it out:
  439. ```bash
  440. pjm doctor # what's unregistered, what's stale, what's still pinned
  441. pjm doctor --fix # register what it found
  442. ```
  443. It looks in the places code actually lives — `~/Developer`, `~/code`, `~/src`,
  444. `~/projects` and friends, plus every fixed drive on Windows, where projects sit
  445. on `D:\` and `E:\` as often as under your home folder. To point it somewhere
  446. specific:
  447. ```bash
  448. pjm doctor --path ~/work --path /Volumes/ssd --fix
  449. pjm project scan D:\ E:\ --depth 3 # the same walk, without the other checks
  450. ```
  451. Nothing is scanned until you run it, and nothing is written without `--fix`.
  452. After an upgrade the CLI mentions `pjm doctor` once — a wheel install can't run
  453. code, so the first command you type is the only place to say it.
  454. 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.
  455. **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.
  456. ### The 3-minute workflow (let your AI do the setup)
  457. 1. **Install + init.** `pip install projectmem`, then `cd` into your project and run `pjm init` — or simply ask your AI to run it.
  458. 2. **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.)
  459. 3. **Restart the AI tool** so the MCP server loads, then start your session with this prompt:
  460. ```text
  461. Hi — I use projectmem as this project's memory. Before anything else,
  462. call get_instructions(), then get_summary(), then get_project_map() to
  463. load what we already know. As we work, log issues, attempts
  464. (failed/worked), fixes, decisions, and notes with the projectmem tools,
  465. and call precheck_file(file_path) before you edit a file. Ideas and plans go
  466. in plan.md via get_plan() — never as events.
  467. ```
  468. 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.
  469. - **Repeat for every project:** `pjm init` + the same kickoff prompt.
  470. - **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.
  471. > Prefer to wire it up by hand? The exact, verified config for each client follows.
  472. ### Claude Desktop
  473. **Easiest — open the config from the UI:**
  474. - **macOS:** Claude menu → `Settings…` → `Developer` tab → **Local MCP servers** → **Edit Config**.
  475. - **Windows / Linux:** same path expected (`Settings → Developer → Edit Config`) — open an issue if your platform differs and we'll update this.
  476. 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.
  477. Paste this block:
  478. ```json
  479. "mcpServers": {
  480. "projectmem": {
  481. "command": "/opt/anaconda3/bin/python",
  482. "args": ["-m", "projectmem.mcp_server"]
  483. }
  484. }
  485. ```
  486. **Two things to know about this block:**
  487. - **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.
  488. - **You no longer need the `cwd` field, and you never could rely on it.** Claude Desktop's current build (with the Epitaxy / Cowork workspace system) silently ignores `cwd` — the server ends up running with `cwd=/` 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.
  489. <details>
  490. <summary>Pin this server to a single repo instead</summary>
  491. ```json
  492. "mcpServers": {
  493. "projectmem": {
  494. "command": "/opt/anaconda3/bin/python",
  495. "args": [
  496. "-m", "projectmem.mcp_server",
  497. "--root", "/absolute/path/to/your/project"
  498. ]
  499. }
  500. }
  501. ```
  502. 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.
  503. </details>
  504. Then **fully quit Claude Desktop (Cmd+Q on Mac)** and reopen — MCP servers only initialize on cold start.
  505. ### Cursor
  506. Two ways to register the MCP server — pick whichever fits your workflow:
  507. 1. **Global (recommended):** Cursor menu → `Settings…` → left sidebar **Tools & MCPs** → **Installed MCP Servers** → **Add Custom MCP**. Paste the JSON below.
  508. 2. **Per-project:** drop the JSON into `<project-root>/.cursor/mcp.json` — only active when that project is open.
  509. ```json
  510. {
  511. "mcpServers": {
  512. "projectmem": {
  513. "command": "/opt/anaconda3/bin/python",
  514. "args": ["-m", "projectmem.mcp_server"]
  515. }
  516. }
  517. }
  518. ```
  519. **Two things to know about this block (same gotchas as Claude Desktop):**
  520. - **Use the absolute path to `python`** (run `which python` to find yours). Cursor subprocesses don't reliably inherit your shell `PATH`.
  521. - **Don't bother with the `cwd` field.** Cursor — like Claude Desktop — silently ignores it: the server ends up running with `cwd=~`. Since 0.3.0 that no longer matters, because projects are found by name in the registry rather than by where the server runs.
  522. 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.
  523. 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.
  524. ### Antigravity
  525. Antigravity (Google's AI IDE) speaks standard MCP.
  526. **Easiest — open the config from the UI:**
  527. 1. Open the **Agent** window (the chat panel on the right).
  528. 2. Click the **⋯ Additional Options** button in the panel header.
  529. 3. Choose **MCP Servers** → **Manage MCP Servers** → **Add new** (or **Edit Config**).
  530. The raw file is at `~/.gemini/antigravity/mcp_config.json` if you prefer editing it directly.
  531. Paste this block:
  532. ```json
  533. {
  534. "mcpServers": {
  535. "projectmem": {
  536. "command": "python",
  537. "args": ["-m", "projectmem.mcp_server"]
  538. }
  539. }
  540. }
  541. ```
  542. 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.
  543. 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.
  544. ### Codex
  545. 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.
  546. **Easiest — edit `~/.codex/config.toml` directly:**
  547. Append this block (preserves any existing config):
  548. ```toml
  549. [mcp_servers.projectmem]
  550. command = "/opt/anaconda3/bin/python"
  551. args = ["-m", "projectmem.mcp_server"]
  552. ```
  553. Three things to know about this block:
  554. - **Use the absolute path to `python`** (run `which python` to find yours). Codex subprocesses don't reliably inherit your shell `PATH`.
  555. - **You no longer need `--root` or `cwd`.** Earlier releases passed `--root` as defense in depth (the `cwd` field 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"` to `args` only if you want this server locked to a single repo.
  556. - **Set your reasoning effort to `medium` or higher.** On low-reasoning Codex skips `get_instructions` from the session-start trio, which can cause the AI to miss the Setup Mode workflow rules. Medium+ honors the full trio automatically.
  557. **Validate the TOML:**
  558. ```bash
  559. python -c "import tomllib; tomllib.load(open('/Users/<you>/.codex/config.toml','rb')); print('OK')"
  560. ```
  561. Should print `OK`. If not, the parser tells you the offending line.
  562. **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.
  563. **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.
  564. ### First-run permission prompts
  565. On first use in any MCP-capable client (Claude Desktop, Cursor, Antigravity, Codex),
  566. your AI will ask permission before each projectmem tool call. **This is
  567. expected security behavior** — MCP clients require explicit consent for
  568. every new tool. Approve each tool once and the prompt won't reappear for
  569. that session.
  570. ### Other MCP Tools
  571. Any MCP-compatible client works — point your tool at
  572. `python -m projectmem.mcp_server` and either set `cwd` to your project
  573. root or rely on the parent-walk auto-discovery.
  574. ### MCP Tools Exposed
  575. All 17 tools your AI can call. Every repo tool takes an optional
  576. `project` argument — see [One server, many projects](#one-server-many-projects):
  577. **Read-side (12 tools):**
  578. | Tool | When to use |
  579. |---|---|
  580. | `get_instructions()` | Start of every session — load workflow rules |
  581. | `get_summary()` | Start and end — distilled project memory |
  582. | `get_project_map()` | Start — understand repo structure |
  583. | `get_plan()` | Read `plan.md` — the ideas + plans (intent), separate from the event log |
  584. | `precheck_file(file_path)` | Before editing any file — surface failure history |
  585. | `get_issue(issue_id)` | Read one specific issue's full history by ID |
  586. | `search_events(query)` | Plain-text search across all logged events |
  587. | `get_context(tokens, focus)` | Token-budgeted memory block with optional focus filter |
  588. | `get_score()` | A+→F prevention score + ROI numbers |
  589. | `get_global_gotchas(library)` | Cross-project library lessons inherited from past repos |
  590. | `list_projects()` | See every registered project, and which one is active |
  591. | `current_project()` | Check which project a call would resolve to, without writing anything |
  592. **Write-side (5 tools):**
  593. | Tool | When to use |
  594. |---|---|
  595. | `log_issue(summary, location)` | Immediately when encountering a bug |
  596. | `record_attempt(summary, outcome)` | Immediately after each fix attempt (outcome: `failed`/`partial`/`worked`) |
  597. | `record_fix(summary)` | After confirming a fix resolves the issue |
  598. | `add_decision(summary, supersedes?)` | When making architectural / design decisions; pass `supersedes` to retire a stale decision without losing history |
  599. | `add_note(summary)` | When discovering gotchas, setup details, or constraints |
  600. ## CLI Reference
  601. ### Core memory
  602. | Command | Purpose |
  603. |---|---|
  604. | `pjm init` | Initialize memory + auto-install hooks + inherit global memory |
  605. | `pjm log <text>` | Start a new issue / debugging session |
  606. | `pjm attempt <text> [--failed\|--worked]` | Record a fix attempt outcome |
  607. | `pjm fix <text> [--issue <id>]` | Record the confirmed fix and close the issue — `--issue` targets a specific one *(new in 0.1.5)* |
  608. | `pjm decision <text> [--supersedes <id>]` | Record an architectural decision; optionally retire a prior one (old event stays in the log, tagged) |
  609. | `pjm note <text>` | Record durable context or a gotcha |
  610. | `pjm plan ["idea"]` | Print `plan.md` (ideas + plans); with text, append an idea. Intent, **not** an event *(new in 0.2.0)* |
  611. | `pjm show` | Print the current summary |
  612. | `pjm search <query> [--failed-only]` | Plain-text search across all events; `--failed-only` lists the project's dead ends |
  613. | `pjm brief` | One-screen session-start briefing: warnings, stale memories, open issues, decisions, score |
  614. | `pjm export [--claude-md\|--cursor]` | Compile live memory into CLAUDE.md / .cursorrules for agents without MCP |
  615. ### Intelligence layer
  616. | Command | Purpose |
  617. |---|---|
  618. | `pjm watch [--daemon\|--stop\|--status]` | Real-time file churn watcher |
  619. | `pjm precheck [--snooze 2h\|--unsnooze]` | Warn about repeating failed approaches before commit; snooze politely (audited) when needed |
  620. | `pjm wrap <agent>` | Inject token-budgeted memory into Claude/Cursor/Aider |
  621. | `pjm context [--tokens N]` | Generate token-budgeted project context |
  622. | `pjm score [--format text\|json\|badge]` | Letter-grade prevention score |
  623. | `pjm global <action>` | Manage cross-project memory |
  624. ### Projects (global MCP)
  625. | Command | Purpose |
  626. |---|---|
  627. | `pjm doctor [--fix] [--path P] [--online]` | Find unregistered projects, stale entries and pinned client configs. `--online` also asks PyPI for the newest release; `--auto` remembers to check daily *(new in 0.3.0)* |
  628. | `pjm project list` | Every project this server can reach, and which one is active *(new in 0.3.0)* |
  629. | `pjm project scan <dirs> [--depth N] [--dry-run]` | Walk for projects with memory and register them |
  630. | `pjm project register [path] [--alias a]` | Add a project that already has memory (`pjm init` registers automatically) |
  631. | `pjm project use [name]` | Set the default project for calls that name none; omit the name to clear it |
  632. | `pjm project alias <name> <alias>` | Give a project a shorter name |
  633. | `pjm project tag <name> <tag> [--remove]` | Tag a project |
  634. | `pjm project remove <name>` | Forget a project — its repo and `.projectmem/` are untouched |
  635. ### Visualization & utility
  636. | Command | Purpose |
  637. |---|---|
  638. | `pjm visualize` | Open the six-tab local dashboard (Overview, Story Map, ROI, Project Map, Timeline, Showoff) |
  639. | `pjm dashboard [--serve] [--port N]` | Cross-project **global** dashboard over every `pjm init`-ed repo; default writes a static snapshot, `--serve` runs an ephemeral live server (Ctrl+C to stop) *(new in 0.2.0)* |
  640. | `pjm map [--build]` | Print the Project Map; `--build` (re)builds the code structure + import graph into `structure.json` (a derived, gitignored cache) *(new in 0.2.0)* |
  641. | `pjm stats` | Token ROI summary in the terminal |
  642. | `pjm backfill` | Auto-populate memory from git history |
  643. | `pjm hooks install\|uninstall` | Manage git hooks manually |
  644. | `pjm regenerate` | Rebuild `summary.md` from `events.jsonl` |
  645. > Use `--at "file.py:42"` with any logging command to attach precise location metadata.
  646. ### `plan.md` — intent, kept separate from memory
  647. `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:
  648. - `events.jsonl → summary.md` records what *happened* (append-only, never rewritten).
  649. - `plan.md` records what you *intend* — and you (or the AI) edit it directly, like `PROJECT_MAP.md`.
  650. 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.
  651. ## Example: Pre-Commit Warnings in Action
  652. ```bash
  653. $ git commit -m "switch auth to JWT"
  654. projectmem: Pre-Commit Check
  655. ─────────────────────────────────────────────
  656. src/auth/middleware.py
  657. WARN What already failed here (2 attempts):
  658. ✗ tried switching to JWT middleware (2d ago)
  659. ✗ patched session timeout to 60min (5d ago)
  660. WARN HIGH CHURN: 5 changes in last 30 days
  661. WARN 1 possibly-stale memory cites this file
  662. decision [evt_9db5a3f8…] "auth uses session
  663. cookies, 30min timeout" — predates 7 commits
  664. Confirm it still holds, or retire it:
  665. pjm decision "..." --supersedes <id>
  666. ─────────────────────────────────────────────
  667. 3 warning(s). Review before committing.
  668. ```
  669. 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.
  670. ## Privacy & Security
  671. 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.
  672. **Want total privacy?** Add a single line `.projectmem/` to your `.gitignore`. Nothing leaves your machine.
  673. Full security policy and threat model: [SECURITY.md](https://github.com/riponcm/projectmem/blob/main/SECURITY.md) · [Privacy & Security guide](https://projectmem.dev/guide#privacy-security)
  674. ## Design Principles
  675. - **Local-first** — No cloud, no telemetry, and no network calls unless you turn on the update check. Your data never leaves your machine.
  676. - **Project-scoped** — Memory lives in the repo. When the code moves, the memory moves.
  677. - **AI-tool-agnostic** — Works natively via MCP, or universally via Markdown instructions. Any AI tool, any workflow.
  678. ## Built With
  679. `projectmem` stands on the shoulders of these excellent open-source projects:
  680. - [**Typer**](https://github.com/tiangolo/typer) — the CLI framework that makes `pjm` feel ergonomic
  681. - [**Model Context Protocol**](https://modelcontextprotocol.io) — Anthropic's open spec that lets AI agents talk to local tools
  682. - [**watchdog**](https://github.com/gorakhargosh/watchdog) — cross-platform filesystem event monitoring (the heart of `pjm watch`)
  683. - [**D3.js**](https://d3js.org) — the interactive visualizations in `pjm visualize`
  684. ## Research & Citation
  685. projectmem is described in a peer-readable research paper:
  686. > **PROJECTMEM: A Local-First, Event-Sourced Memory and Judgment Layer for AI Coding Agents**
  687. > Ripon Chandra Malo, Tong Qiu — University of Utah
  688. > [arXiv:2606.12329](https://arxiv.org/abs/2606.12329) · cs.AI
  689. 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.
  690. If projectmem is useful in your research or writing, please cite:
  691. ```bibtex
  692. @misc{malo2026projectmem,
  693. title = {PROJECTMEM: A Local-First, Event-Sourced Memory and
  694. Judgment Layer for AI Coding Agents},
  695. author = {Malo, Ripon Chandra and Qiu, Tong},
  696. year = {2026},
  697. eprint = {2606.12329},
  698. archivePrefix = {arXiv},
  699. primaryClass = {cs.AI},
  700. url = {https://arxiv.org/abs/2606.12329}
  701. }
  702. ```
  703. ## License
  704. MIT — free for personal, commercial, and enterprise use forever.
  705. ---
  706. ## Help Us Reach More Developers
  707. **We don't need money. We need you.**
  708. `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.
  709. - **[Star the repo](https://github.com/riponcm/projectmem)** — takes one click, helps massively with discovery
  710. - **Share on X / LinkedIn** — tell other devs they don't have to keep paying AI to relearn their codebase
  711. - **[Open an issue](https://github.com/riponcm/projectmem/issues)** — bug, feature request, or just feedback
  712. - **[Contribute code](https://github.com/riponcm/projectmem/pulls)** — PRs welcome; for anything large, open an issue first
  713. - **Using `projectmem` at work or in a commercial product?** Reach out to [support@projectmem.dev](mailto:support@projectmem.dev) so we know who's shipping with us. It's free — we just love hearing about it.
  714. *Stars and shares matter more than money — but if you really want to:* [sponsor on GitHub](https://github.com/sponsors/riponcm) →
  715. ---
  716. <div align="center">
  717. <sub>Built with care by the open-source community. Every contribution, no matter how small, makes a difference.</sub>
  718. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.