v0.2.0 — The Workspace Release

The Workspace Release

projectmem lifts memory from one project to your whole machine — and closes the gap between what happened (memory) and what your code is (structure). No new required dependencies, and the six core event types (issue, hypothesis, attempt, fix, decision, note) are unchanged — your existing events.jsonl just gains new ways to be seen.

pip install -U projectmem

🌐 Cross-project global dashboard — pjm dashboard

One page over every repo 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. A tiny registry at ~/.projectmem/projects.json only records where your projects are.

• Serverless by default — writes a self-contained static snapshot and opens it; the page honestly labels itself a snapshot, so it never overclaims.
• --serve for live — a tiny, ephemeral local server where the Refresh button re-reads your files and each card renders on demand. No background daemon; Ctrl+C stops it cleanly.

🧬 Code structure & relations — pjm map --build

Memory knew your history; now projectmem also reads your structure. pjm map --build (run automatically at pjm init) walks the codebase and, for Python, resolves imports into a real dependency graph — written to a derived, gitignored structure.json cache (code is only ever read, never modified). The Project Map's Graph and Flow views now render your actual files and the import edges between them.

🔥 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 — intent, kept separate from memory

pjm init now scaffolds a .projectmem/plan.md: your 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 via the new get_plan() MCP tool and edits it directly, like PROJECT_MAP.md; a plan never becomes an event. pjm plan prints it, pjm plan "idea" appends one. Committed, so intent is shared with your team.

Also

• 15 MCP tools now (get_plan added) — 10 read, 5 write.
• No schema changes, no new required dependencies.
• New tests cover the registry, the global dashboard (static + --serve), the structure extractor, and plan.md — 135 total.

---

Full changelog: https://github.com/riponcm/projectmem/blob/main/CHANGELOG.md · Docs: https://projectmem.dev/guide · Verified end-to-end on Claude Desktop, Cursor, Antigravity, and Codex.

v0.1.6 — The Visualization Release

Your project's memory is now something you can watch — and share. The dashboard grows from four tabs to six, every new view is rendered from the same real event log, and nothing new is required: zero new dependencies, no schema changes, no CLI changes.

🎬 Showoff — animated story scenes + built-in recorder

A new dashboard tab with three animated scenes, all driven by your real events:

• Story Replay — watch your project's history build itself, node by node; auto-loops, scrubber, live captions
• Orbit — files orbit the project, events orbit their file
• Universe — your project as a rotating galaxy; every bright star is a real issue, attempt, fix, or decision

Click any node for its real details — the field dims, a halo pulses, its connections light up. And hit REC (10–60 s) to download a .webm clip rendered 100% locally, with a toggleable "made with projectmem" badge baked in.

🗺️ Flow — the Project Map's new default view

A layered flowchart of the project story: PROJECT → DIRECTORIES → FILES → WHAT HAPPENED → MEMORY. Files with repeated failures glow red along their path, every file shows outcome chips, and everything flows into the events.jsonl cylinder — the append-only memory, drawn as what it is. Zoom, pan, auto-fit, and a new Hide details toggle. Tree and Graph remain one click away.

🧵 Time Spine — the Timeline's new default view

A real-time axis you scroll: day pills, "quiet gap" markers, problems branching left (issues, failed attempts) and knowledge branching right (fixes, decisions, notes). Hover any card and its whole issue thread stays lit. The classic list remains as Details.

🤝 Community: Story Map readability controls

This release includes #7 by @hanley-development (which also folds in #6 — thank you!): collapse dense files into draggable bubbles, collapse directories with drill-down, expand all, reset focus, reduced label noise, and correct linking for file-only locations.

Also

• README gains a "New in 0.1.6" showcase with dashboard screenshots
• 8 new tests pin the new template surface (115 total)
• Includes v0.1.5's reliability fixes for anyone upgrading straight from 0.1.4

Upgrade

pip install -U projectmem

v0.1.5 — Reliability Release

Same features, fewer ways to break. Three community-contributed fixes make projectmem safer to run everywhere — especially on Windows. No new dependencies, no schema changes.

Fixes

• pjm fix --issue / record_fix(issue_id=…) — close the issue you mean. Previously fix always closed the "current" issue, so fixing an older one could silently close the wrong issue. You can now target a specific issue by ID (pjm fix --issue 0001; IDs normalize 1/001/0001). Closes #3. (#2)
• MCP git helpers no longer hang stdio sessions — git subprocesses now run with detached stdin (DEVNULL) and bounded timeouts, fixing a class of Windows MCP hangs. (#4)
• Console output is encoding-safe — pjm brief and pjm precheck no longer crash on non-UTF-8 (cp1252) Windows consoles and git hooks. (#5)

🙏 Thanks

All three fixes contributed by @hanley-development — thank you!

Install

```
pip install -U projectmem
```

Full Changelog: v0.1.4...v0.1.5

v0.1.4 — The Accountable-Judgment Release

The accountable-judgment release — memory that flags its own staleness instead of silently trusting (or deleting) it. Six features, ~330 lines, no new dependencies, the same 14-tool MCP surface.

📦 pip install -U projectmem · 📰 Release post · 🎓 Research paper (arXiv:2606.12329) · 🎬 Tutorial video

✨ New

• Stale-memory detection — flag, never delete. Every decision/fix/note that cites a file is cross-checked against that file's git history. When the file moved on (3+ commits, or it no longer exists), pjm precheck and the MCP precheck_file tool flag the memory — "predates 7 commits to auth.py — confirm or supersede." Nothing is deleted; a human decides. Deterministic git log counts, no embeddings, no daemon.
• Superseded-decision marking. pjm decision "switch to argon2" --supersedes <event-id> (also on MCP add_decision) retires an old decision without rewriting history: it leaves summary.md, stays in the append-only log, and shows in pjm search tagged (superseded). Search now prints event ids.
• pjm brief — one-screen session-start briefing: active warnings, possibly-stale memories, open issues, recent decisions, stack gotchas, and your prevention score with a weekly delta.
• Precheck snooze. pjm precheck --snooze 2h pauses warnings for a bounded window instead of pushing you to --no-verify. The snooze is itself logged — even the silence is audited. --unsnooze restores early.
• Failed approaches listed in the warning. Precheck now shows the dead ends themselves ("✗ tried CSS contain:layout"), and pjm search --failed-only lists a project's full catalogue of dead ends.
• pjm export --claude-md (and --cursor) — compiles live decisions (stale ones flagged), gotchas, and a "Do NOT retry — these already failed" list into a marked block in CLAUDE.md / .cursorrules. Agents without MCP inherit the project's judgment.
• Dashboard Overview tab — pjm visualize opens on an all-at-a-glance view (failure heatmap, A+→F prevention gauge, project graph with failure rings, typed-event timeline), re-themed light.

🐛 Fixed

• Walk-up discovery no longer mistakes ~/.projectmem (the machine-wide global store) for a project — found by dogfooding 0.1.4 on this very repo.
• pjm precheck payment.py auth.py — named files now work directly from the CLI.
• pjm search payment.py matches the location field, so per-file lookups behave like precheck.

📋 Compatibility

One new optional event field (supersedes); existing logs parse unchanged; MCP surface unchanged (14 tools). After upgrading run pjm hooks install once per project. 23 new tests — 81 passing.

Full changelog: https://projectmem.dev/changelog

v0.1.3 — quality + privacy + conda/venv hook fix + init UX

Six focused improvements:

• Schema enrichment — all 14 MCP tools now have parameter descriptions + schema constraints. Projected Glama score 75% → ~90%.
• Secret redaction on write — API keys, tokens, PEM blocks scrubbed from event text before they touch disk. Default-on, PROJECTMEM_NO_REDACT=1 to skip.
• L-047: conda/venv hook fix — pre-commit warning now works under conda/pyenv/venv. The killer feature had been silently no-op for most Python users.
• L-048: stack auto-detect — pjm init pre-populates PROJECT_MAP.md from your manifests (pyproject / package.json / Cargo / go.mod). Setup Mode becomes refinement, not greenfield.
• L-049: MCP config printed at init — copy-pasteable JSON block with paths for Claude Desktop / Cursor / Antigravity / Codex.
• L-050: silent post-commit auto-capture — no more output printing over your shell prompt after git commit.

Plus TUTORIAL.md — 15-minute step-by-step walkthrough linked from the README.

Install: pip install -U projectmem
Tutorial: TUTORIAL.md
Full changelog: CHANGELOG.md

v0.1.1 — First Stable Release · Cross-Project Memory Verified

projectmem v0.1.1 — First Stable Release

The local-first memory layer for AI coding agents. projectmem captures what your AI learned (and what didn't work) so the next session — and the next project — starts experienced instead of from zero. 100% local. No cloud. No telemetry. No account.

After months of dogfooding, 46 documented lessons, a 22-item polish-pass, four MCP clients verified end-to-end, and three language ecosystems put through a real cross-project memory test cycle — v0.1.1 is the version we're comfortable putting on PyPI as a stable release.

pip install projectmem
cd your-project
pjm init

Two commands and your AI is no longer amnesiac.

---

What projectmem does, in one sentence

It gives your AI persistent memory — about your bugs, your decisions, the approaches you've already tried, and the libraries that have bitten you before — accessible through 14 native MCP tools that work with Claude Desktop, Cursor, Antigravity, and Codex out of the box.

What's in this release

The intelligence layer

• Pre-commit warnings — fires before a commit if you're about to repeat a failed approach, touch a high-churn file, or revisit an unresolved issue. The only AI memory tool that prevents mistakes instead of just remembering them.
• Real-time file watcher — auto-starts on pjm init. Detects rapid edits to the same file (debugging sessions) and logs churn events automatically. Battery-aware, gitignore-aware.
• Smart context injection (pjm wrap) — wraps your AI agent with a token-budgeted memory block before the session starts. Inject into CLAUDE.md, .cursorrules, or clipboard.
• Prevention Score (pjm score) — quantifiable A+ → F letter grade backed by debugging hours saved, tokens prevented, and dollars protected. CTO-readable ROI.

Cross-project memory — verified across 3 languages

A library gotcha learned in one project surfaces automatically in any other project on the same stack, with source-project attribution. Three wiring gaps closed in this release:

• Auto-promote wiring restored. Failed attempts and gotcha-prefixed decisions now consistently propagate to the machine-wide store. Wired through storage.append_event so every write surface — MCP, CLI, git hooks — promotes uniformly.
• Language parity. Self-curating library cache at ~/.projectmem/global/.promotable.json means Go, Rust, Java, Ruby, and mobile projects accumulate cross-project knowledge the same way JavaScript and Python ones did. A Go user's gin lessons now propagate exactly like a React user's vite ones.
• Signal filter. Project-setup decisions stay local. Only deliberate lessons — failed attempts, or decisions/notes opening with gotcha: / lesson: / warning: / caution: / pitfall: / avoid: / don't / do not / never / bug: — reach the global store. Signal-to-noise went from 14% to 100% in the real test cycle.

End-to-end verification across proj-react → proj-next (JS inheritance with attribution), proj-python (negative — vite gotcha correctly bounded by stack), and proj-go (gin promotion under the new library cache + signal filter).

Cross-client compatibility

Four MCP clients tested end-to-end. 124 of 124 cells green.

Client	Status	Setup
Antigravity	✅ All checks pass	Native — cwd honored, no workaround
Claude Desktop	✅ All checks pass	Use Auto mode (not Plan); pass root via --root in args
Cursor	✅ All checks pass	Same --root workaround for cwd-ignored bug
Codex	✅ All checks pass	TOML config at ~/.codex/config.toml; medium reasoning required

Each client ships with a documented setup block, captured during real verification.

Operational hardening

• MCP stdio integrity — write tools no longer corrupt the JSON-RPC stream. Five consecutive log_issue / record_attempt / record_fix / add_decision / add_note calls survive cleanly in every client.
• MCP project-root discovery — server walks up the tree to find .projectmem/ (like git does for .git/). Plus --root flag and PROJECTMEM_ROOT env var for explicit pinning.
• No silent issue misattribution — record_attempt after record_fix never latches onto a stale open issue. Marker file + 5-minute time-fence + explicit --issue flag.
• AI workflow alignment — three surfaces (MCP instructions=, CLAUDE.md, AI_INSTRUCTIONS.md) now mirror each other. No drift between what each client tells the AI.
• Setup → Maintenance state machine — AI detects placeholder vs real content via concrete signals, populates memory through MCP write tools (not direct file edits).

100% local. No exceptions.

• Memory lives at <your-project>/.projectmem/ (local to each project) and ~/.projectmem/global/ (machine-wide).
• Nothing uploads anywhere. No accounts. No telemetry. No "anonymous usage data."
• Team sharing is explicit: pjm global export > team-gotchas.json → commit → teammate runs pjm global import. You choose what to share and when.

Install

pip install projectmem

Requires Python 3.10+. MIT licensed.

Quick start

cd your-project
pjm init                           # creates .projectmem/, installs git hooks, starts watcher
# Open your AI client (Claude Desktop / Cursor / Antigravity / Codex)
# Ask anything about the project — memory is now wired

For the multi-project / monorepo setup, AI client configuration per tool, and the full feature tour, see the User Guide.

Upgrade notes

This is your first chance to install projectmem from real PyPI — there's nothing to upgrade from. If you previously installed from TestPyPI or from source, pip install --upgrade projectmem replaces it cleanly. Memory files (.projectmem/events.jsonl and global store) load without migration.

Acknowledgements

Built in the open, on a single MacBook, over six months of dogfooding. Every bug in the launch matrix was a real bug found by real use — not synthetic test data. Special thanks to the four MCP client teams whose work made this possible: Anthropic (Claude Desktop), Anysphere (Cursor), Google (Antigravity), and OpenAI (Codex).

The 46 lessons logged during this release are publicly tracked in report/LESSONS_AND_FIXES.md. Read them if you want to see how the sausage actually gets made.

---

Star the repo · Try it now · Read the guide · Report a bug