# projectmem — full text > Everything on projectmem.dev as plain markdown: the complete FAQ and all 23 articles. Last updated 2026-07-07 · covers v0.2.0 · https://projectmem.dev # Frequently Asked Questions ## About projectmem ### What is projectmem? projectmem is a free, open-source (MIT), local-first memory and judgment layer for AI coding agents such as Claude Code, Claude Desktop, Cursor, Antigravity, and Codex. It records your project's development history — issues, fix attempts, decisions, and gotchas — as typed events in a plain-text log, then feeds that memory back to your AI so it starts every session experienced instead of amnesiac. It also acts on the memory: a git pre-commit hook warns you before you repeat an approach that already failed. Install with pip install projectmem, then run pjm init in your repo. It is published by Matily, a nonprofit open-source studio, and described in a peer-readable research paper (arXiv:2606.12329). ### Is projectmem free? What is the license? Yes — projectmem is completely free, forever, for individuals, teams, and commercial use. It is open source under the MIT license with no paid tiers, no feature gates, no license keys, and no accounts. It is published by Matily (matily.org), a nonprofit software studio whose motto is "no trackers, no lock-in, no cost." ### Does projectmem send my code or data anywhere? No. projectmem is 100% local: all memory lives in a plain-text .projectmem/ folder inside your own repository, there is no cloud component, no telemetry, and no account. The only network use in the tool is the optional visualization dashboard loading its charting library from a CDN. As a guardrail, secret redaction is on by default: known key patterns (OpenAI, GitHub, AWS, Google, Slack, Stripe, JWTs, private keys) are scrubbed from event text before anything touches disk. ### Which AI coding tools does projectmem work with? projectmem works with any MCP-compatible AI tool and has been verified end-to-end on Claude Desktop, Cursor, Antigravity, and Codex; Claude Code connects the same way. Its MCP server exposes 17 tools (12 read, 5 write) over stdio. For agents without MCP — GitHub Copilot, plain chat models — pjm export --claude-md compiles the live memory into a marked block inside CLAUDE.md or .cursorrules, so any tool that reads a file inherits the project's judgment. ### Who built projectmem? projectmem was created by Ripon Chandra Malo, a PhD researcher at the University of Utah, and is published through Matily, his nonprofit open-source studio. The design is documented in a research paper (arXiv:2606.12329). It is community-open: recent releases shipped fixes and features contributed by outside developers, credited in the changelog and on the contact page. ## Agentic memory, explained ### What is AI agent memory? AI agent memory is any mechanism that lets an AI system retain information between sessions instead of starting from zero each time. Large language models are stateless: when a chat ends, everything the agent learned — the bug it chased, the fixes that failed, the decisions made — is gone unless an external memory layer stores it. Approaches range from static instruction files (CLAUDE.md), to cloud chat-memory services, to event-sourced local memory like projectmem, which records the development process itself as typed, replayable events. ### Why do AI coding assistants forget everything between sessions? Because the model's only working state is its context window, which is discarded when the session ends. Nothing about your project persists inside the model itself. The practical cost is real: every new session burns thousands of tokens re-reading source files to reconstruct context that existed yesterday, and the assistant will happily re-propose a fix that already failed last week. The model isn't the problem — the architecture around it is. A persistent, project-scoped memory layer closes that gap. ### What is the difference between episodic and semantic memory for AI agents? Episodic memory stores specific events in time order — "what happened" — while semantic memory stores distilled facts — "what is true now." projectmem deliberately mirrors this: events.jsonl is the episodic log (every issue, attempt, fix, decision, note, append-only and immutable), and summary.md is the semantic layer, automatically re-distilled from the log after every event. A third layer, AI_INSTRUCTIONS.md, plays the role of procedural memory: the workflow rules the agent must follow. ### What is MCP (Model Context Protocol)? MCP is an open protocol, introduced by Anthropic in 2024, that lets AI applications call external tools and data sources in a standard way. An MCP server exposes typed tools; the AI client (Claude Desktop, Cursor, Codex, and others) can discover and invoke them mid-conversation. projectmem ships a native MCP server (pjm-mcp) over stdio with 17 tools, so the AI can read the project's memory (typically a few hundred to ~1,500 tokens) instead of re-scanning source files, and log new events as it works. ### Is a memory layer better than a bigger context window? They solve different problems. A bigger context window lets one session hold more, but it still evaporates when the session ends, and re-filling it costs tokens every time. A memory layer persists across sessions, tools, and machines, and can be distilled so the AI reads a ~500-token summary instead of megabytes of source. Memory also enables judgment: because projectmem knows which fixes failed before, it can warn at commit time — something no context window, however large, can do after the session is gone. ### What is a 'judgment layer' for AI coding? A judgment layer doesn't just remember history — it acts on it at the moment a mistake is about to repeat. projectmem installs a git pre-commit hook: when you commit, it checks the staged files against the memory and warns if you are repeating a previously failed approach, touching a file with unresolved issues, or committing to a high-churn file. The warning lists the dead ends themselves ("What already failed here: tried CSS contain:layout"). To our knowledge this memory-plus-pre-commit-judgment combination is unique to projectmem. ## How-to ### How do I give Claude Code persistent memory? Install projectmem (pip install projectmem), run pjm init in your repository, and connect the MCP server — pjm init prints the exact config block for your client. From then on Claude reads the project's distilled memory at session start and logs issues, attempts, fixes, and decisions as it works. Claude Code also picks up the CLAUDE.md bridge that pjm init writes automatically, so the memory workflow is honored even before MCP is configured. ### How do I give Cursor persistent project memory? The same two commands: pip install projectmem, then pjm init in the repo. Add the printed MCP server entry to Cursor's MCP settings (use the --root flag form that pjm init prints — Cursor launches MCP servers from its own directory, and projectmem works around that known quirk automatically). Alternatively pjm export --cursor writes the live memory into .cursorrules, no MCP required. ### How do I stop my AI from repeating the same failed fix? Record the failure once, and let the tooling replay it. With projectmem, each fix attempt is logged with an outcome (pjm attempt "tried X" --failed, or the AI calls the record_attempt MCP tool). From then on two mechanisms stop the repeat: the pre-commit hook warns when staged changes match a known failed approach, and the AI reads the failure list at session start — including a "Do NOT retry — these already failed" section if you export to CLAUDE.md. ### Can I share one project memory across Claude, Cursor, and Codex? Yes — that's a core design goal. The memory is a plain-text folder inside the repository, not tied to any vendor, and the same MCP server serves all clients. Start a task in Claude Code, continue it in Cursor or Codex, and each tool reads the same events, summary, and warnings. Switching AI tools no longer means losing your project's history. ### How do I get AI memory without MCP? Run pjm export --claude-md. It compiles the live memory — current decisions (with staleness flags), known gotchas, and failed approaches from the last 90 days — into a clearly marked, auto-regenerated block inside CLAUDE.md (or .cursorrules with --cursor). Any agent that reads the file inherits the project's judgment with zero setup. Re-run it any time; it replaces its own block and never touches the rest of the file. ### How do I see the memory for all my projects in one place? Run pjm dashboard from any repo. It opens a single local dashboard over every project you've run pjm init in — with total issues captured, fixes confirmed, dead-ends prevented, tokens saved, and a letter grade per project. Click any card to open that repo's own dashboard. It's a global view, not a global store: each project's memory is aggregated at read time and never leaves its folder. The default is a static snapshot; add --serve for a live, ephemeral local server where the Refresh button re-reads your files (Ctrl+C stops it). ### How do I keep ideas and plans separate from my project's memory? Use plan.md. pjm init scaffolds a .projectmem/plan.md for your ideas and plans — what you mean to do — kept deliberately separate from the append-only event log, which records what actually happened. Your AI reads it at session start via the get_plan() MCP tool and edits it directly, like PROJECT_MAP.md; a plan never becomes a logged event. Print it with pjm plan, or append an idea with pjm plan "...". ## Comparisons ### What is the best open-source coding agent memory? It depends on which memory your agent is missing. Graphify maps code structure, OpenMemory stores user preferences, MemRL keeps scored episodes of past sessions, and projectmem records engineering history — issues, attempts, fixes and decisions — and is the only one that warns before your agent repeats an approach that already failed. All run locally. The blog has a full comparison. ### projectmem vs mem0 — what's the difference? mem0 is a memory platform focused on chat and user memory, typically consumed through a managed cloud service and vector retrieval. projectmem is a local-first developer tool that records the development process itself — issues, failed attempts, fixes, decisions — as typed events in plain text inside your repo, with no accounts and no cloud. The sharpest differences: projectmem adds pre-commit judgment (warnings before repeating failures), its store is git-auditable plain text rather than a database, and it never rewrites or decays memories — stale ones are flagged for a human to retire. ### projectmem vs claude-mem — what's the difference? claude-mem captures Claude Code session transcripts and summarizes them; it is Claude-centric and, as of mid-2026, runs a background worker and enables telemetry by default. projectmem is tool-agnostic (verified on four MCP clients), stores typed events rather than session logs, adds the pre-commit failure warning, and runs with no daemon, no server, and no telemetry. If you live entirely inside Claude Code, claude-mem's automatic capture is convenient; if you want structured, auditable memory that follows the project across tools, that is projectmem's territory. ### projectmem vs Letta (MemGPT) — what's the difference? Letta is an agent framework: you build and host agents whose memory blocks self-edit, backed by a server and database. projectmem is not a framework — it is a thin memory layer that attaches to the AI tools you already use, with no server or database; the store is append-only plain text. Philosophically they differ on mutation: Letta's memory rewrites itself in place, while projectmem never deletes — history is immutable, staleness is flagged, and decisions are retired by superseding, so you can always audit what the project knew and when. ### Is projectmem just a fancy CLAUDE.md file? No — they are complementary. CLAUDE.md holds static rules you write once: style, conventions, project context. projectmem captures the dynamic history that no one writes by hand — every issue, failed attempt, fix, and decision, timestamped and typed — and computes things from it: summaries, staleness flags, pre-commit warnings, a prevention score. It even meets CLAUDE.md halfway: pjm export --claude-md writes the distilled judgment into the file for agents that read nothing else. ### Do I need a vector database for AI memory? Not for development memory. projectmem deliberately uses a small typed vocabulary — six event types — instead of embeddings, which makes queries precise ("how many failed attempts on this file?"), results deterministic, and the whole store human-readable and git-diffable. That precision is what makes the pre-commit judgment trustworthy. Vector search shines for fuzzy recall over large unstructured corpora; optional local embeddings are on projectmem's roadmap for exactly that, as a complement rather than a replacement. ## Technical ### What is stored inside the .projectmem folder? Plain text, nothing else: events.jsonl (the append-only episodic log, one JSON object per line), summary.md (the distilled memory, auto-regenerated from events), PROJECT_MAP.md (structure and entry points), AI_INSTRUCTIONS.md (the workflow rules agents follow), config.toml, per-issue files under issues/, and a small .current_issue marker. You can cat, grep, and git-diff every one of them. There is no database. ### Is events.jsonl safe to commit to a public repository? It is designed to be committed — plain text, git-auditable, and protected by default-on secret redaction that scrubs known key patterns (OpenAI, GitHub, AWS, Google, Slack, Stripe, JWTs, private keys) before any event is written. Committing it is what gives teammates and future sessions shared memory. That said, event summaries are written by you and your AI: if your debugging notes themselves are sensitive, treat the folder like any other internal documentation and review before publishing the repo. ### Does projectmem work on Windows? Yes. Windows support was hardened in v0.1.5 with three targeted fixes: MCP git subprocesses can no longer hang a stdio session, and console output is encoding-safe on cp1252 terminals and git hooks (no more UnicodeEncodeError from emoji or box-drawing characters). projectmem requires Python 3.10+ and runs on Windows, macOS, and Linux with three lightweight runtime dependencies. ### How does the pre-commit warning actually work? pjm init installs a standard git pre-commit hook. On every commit, projectmem replays the event log for the staged files and prints a warning block if it finds previously failed approaches (listed verbatim), unresolved issues, or high churn. Nothing is blocked by default — you stay in control, and pjm precheck --snooze 2h silences it politely for a bounded window, with the snooze itself logged so even the silence is audited. ### Can I visualize — and record — my project's memory? Yes. pjm visualize opens a six-tab local dashboard generated entirely from your event log: Overview, Story Map (failure heatmap), ROI Dashboard with an A+ to F prevention grade, Project Map (Flow, Tree, or Graph layouts), Timeline (Time Spine or list), and Showoff — three animated story scenes with a built-in recorder that downloads a 10–60 second .webm of your project's history, rendered 100% locally in the browser (added in v0.1.6). ### How many tokens does projectmem save? Reading the distilled memory costs a few hundred to about 1,500 tokens — measured at about 250 on a young project and about 1,100 on one with 25 issues and 60 decisions — versus several times that to re-derive the same context by re-scanning source files. Across whole sessions the project estimates savings of 50% or more; treat that figure as the tool's own estimate rather than an independent benchmark. The pjm score and pjm stats commands show your project's own numbers, computed from your actual event log. ### Does projectmem run a background server or a database? No. There is no database and nothing you have to keep running. The MCP server is a stdio subprocess that your AI client (Claude Desktop, Cursor, Antigravity, Codex) spawns on demand, and everything else is plain files under .projectmem/. The only server anywhere is the optional pjm dashboard --serve, an ephemeral local viewer you start and stop with Ctrl+C — never a persistent service. ### Does projectmem read my source code? Only to build the structure map. pjm map --build (run automatically at pjm init) walks your codebase and, for Python, resolves imports into a dependency graph cached in a derived, gitignored structure.json. Code is only ever read, never modified, and nothing is uploaded — it all stays on your machine. The Project Map's Graph and Flow views then show your real files with a failure-heat overlay drawn from your event log. # Articles ## The Complete projectmem Guide: Give Your AI Coding Agent a Real Memory > Install projectmem, connect it to Claude, Cursor or Codex, verify it with pjm doctor, and read your project's memory back through the dashboards — a complete walkthrough with real captured terminal output at every step. Published 2026-09-01 · https://projectmem.dev/blog/projectmem-complete-guide-ai-coding-agent-memory/ Your AI coding assistant has no memory. Not a short one — none. Every session starts from an empty room, and the only way it learns anything about your project is to read your files again, from scratch, and guess. That produces two costs. The obvious one is tokens: several thousand per session spent rebuilding context that existed yesterday. The expensive one is judgment. An agent that cannot remember Tuesday will cheerfully propose, on Thursday, the exact fix that failed on Tuesday — and you will not recognise it either, because you have forgotten too. projectmem is a local-first memory and judgment layer that closes that loop. This guide is the complete path: install, connect, verify, use, and read the memory back. Every terminal block below is captured from a real run — nothing is illustrative. ### What you get, concretely ### Where the time actually goes Before the setup, it is worth being precise about the claim, because "saves tokens" is easy to say and rarely quantified. projectmem's own pjm score estimates savings from fixed, published constants — you can read them in commands/score.py and disagree with them: > Be sceptical of any memory tool's savings figure, including this one. What you can verify directly is the input side: get_summary() returns a bounded document you can read and count. Everything else is an estimate built on top of it. ### Step 1 — Install projectmem One command, and it is the same command whether this is your first install or an upgrade from 0.1.x or 0.2.x. ### Step 2 — Initialise your first project Change into a real repository and run pjm init. It creates .projectmem/, installs three git hooks, builds a structure map of your code, and prints the MCP configuration you need for the next step. Here is everything it created, and what each file is for: > Commit .projectmem/ if you want the project's history shared with your team; the events are plain JSON lines and diff cleanly. structure.json is gitignored for you because it is derived. Nothing forces this choice — it is a normal directory in your repo. ### Step 3 — Connect your AI client This is the step that matters most, and the one people get wrong. You are telling your AI client to start one projectmem server. That single server reaches every project you have registered — you do not configure it per repository, and you do not point it at a path. > Replace /opt/homebrew/bin/python3 with **your** Python — the absolute path which pjm reported in Step 1. MCP clients do not inherit your shell's PATH, so a bare python3 fails with nothing in the logs. This is the number one cause of "projectmem isn't showing up". Pick your client. Every configuration below is machine-validated — the JSON parses, the TOML parses, and none of them is pinned to a single repository. #### Why there is no path in that config Before 0.3.0, one server served one repository, so the config had to name it. That meant a config file per project, and switching projects meant editing JSON and restarting your client. Since 0.3.0 the server resolves the project per call. It checks, in order: a project named explicitly on the tool call, the folders your client says it has open, the active project you set with pjm project use, then the working directory — walking up like git does. If it cannot tell, it refuses and names the projects it knows rather than guessing. A write into the wrong repository's audit trail is worse than an error message. ### Step 4 — Check it with pjm doctor Do not go looking in your client's UI yet. The terminal answers faster and tells you what to fix. This is the check that catches the mistake people actually make. Upgrading from an older version usually looks more like this — and both of these warnings are worth understanding rather than just clearing: > --fix registers missing projects and drops stale entries. It will **not** edit your client config, even though it knows exactly which line is wrong. projectmem prints configuration and never rewrites your tooling behind your back, so a pinned client stays listed until you edit that file yourself and re-run. That is a deliberate limit, not an unfinished feature. Once every line is green, confirm the registry sees what you expect: ### Step 5 — Talk to your AI and confirm it worked Open a new chat in your client and ask a question that a stateless assistant could only answer by reading your source: ```text What is this project about, and what have we already tried that didn't work? Use your projectmem tools. ``` A correctly connected client calls get_instructions(), then get_summary(), and answers from those. Three things tell you it worked: #### What your agent actually receives This is the part worth seeing, because it is the whole mechanism. When your agent calls get_summary() on the project we just built, this is the document it gets back — roughly 500 tokens, in place of reading src/ and inferring: ```markdown # projectmem - checkout-api _Last updated: 2026-09-01_ ## Project purpose Replace this placeholder with a concise description of what this project does, who it serves, and the main technologies or runtime assumptions. ## Recent issues - [OPEN] #0004 Idempotency middleware rejects legitimate retries after a 500 [src/api/routes.py:1] (open) - Failed attempt: Cleared the key on any 5xx — reopens the duplicate-charge hole we just closed [src/api/routes.py:1] - [DONE] #0003 Connection pool exhausted during the nightly settlement run [src/db/pool.py:3] -> External calls moved outside the transaction. Pool stays under 30% at settlement. [src/db/pool.py:3] (fixed) - Failed attempt: Raised pool size from 10 to 40 — moved the wall, did not remove it [src/db/pool.py:3] - [DONE] #0002 Payment intent amount off by a factor of 100 for JPY [src/payments/stripe.py:6] -> Amounts converted using the currency's own minor-unit exponent, not an assumed 2. [src/payments/stripe.py:6] (fixed) - Failed attempt: Divided by 100 at the API boundary — correct for JPY, broke every 2-decimal currency [src/payments/stripe.py:6] - [DONE] #0001 Webhook retries create duplicate charges [src/payments/webhook.py:12] -> Idempotency key on the payment intent, written before the charge. Duplicates impossible. [src/payments/webhook.py:18] - Failed attempt: Deduplicated on the Stripe event id — Stripe reuses ids across retries [src/payments/webhook.py:14] - Failed attempt: Added a 5s lock around mark_paid — narrowed the window, did not close it [src/payments/webhook.py:22] ## Decisions - Webhook handlers are idempotent by construction, never by locking. A lock narrows a race; it does not remove one. [src/payments/webhook.py:1] - Amounts cross our boundary in minor units only. A float amount is rejected at the type level. [src/payments/stripe.py:4] - No external network call inside a database transaction, ever. [src/db/pool.py:1] ## Notes - Stripe reuses event ids across retries of the same event. Never dedupe on event id alone. [src/payments/webhook.py:14] - JPY has 0 decimal places. Any test that assumes 2 passes until someone pays in yen. [src/payments/stripe.py:6] - The settlement run starts at 02:00 UTC and is the only thing that touches the pool that hard. [src/db/pool.py:3] ``` > Read the failed attempts again. "Deduplicated on the Stripe event id" and "Added a 5s lock" are exactly the two fixes a competent assistant proposes for duplicate charges — and both are recorded as already tried and failed, with the reason. That is the difference between memory and judgment: the agent is not just better informed, it is specifically prevented from wasting your afternoon. Notice the placeholder under **Project purpose**. That is deliberate. pjm init cannot know what your project does, so it writes a placeholder — and the agent's instructions tell it to detect that phrase, read the source once, and replace it with a real description. After that first session it never re-scans; it trusts the summary. Two modes, and the switch is a literal phrase in the file. #### If nothing happens ### Step 6 — Log your first issue from the terminal Your agent writes memory through the MCP tools. You write it through the CLI, and it is the same log. A real debugging session looks like this — an issue, the things you tried, and how it ended: > A line number is worth adding — --at src/foo.py:14 points a reader at the exact spot, and pjm precheck quotes it back to you. It is no longer required for scoring: in 0.3.1 and earlier a location without a colon counted for nothing toward file coverage, which cost up to 20 points in silence. [0.3.2](/changelog) fixed that, and fixed the matching case where a Windows path like C:\src\foo.py was read as a file called C. The other two event types are not tied to an issue. Use them for the things that are true regardless of what broke: ```bash pjm decision "Webhook handlers are idempotent by construction, never by locking." \ --at src/payments/webhook.py:1 pjm note "Stripe reuses event ids across retries. Never dedupe on event id alone." \ --at src/payments/webhook.py:14 # A decision that replaces an earlier one — the old event stays in the log, # tagged (superseded), and drops out of summary.md pjm decision "Idempotency keys now live in Redis, not Postgres." --supersedes evt_a1b2c3 ``` You do not have to log everything by hand. pjm init installed a post-commit hook, so commits, reverts and merges are captured automatically — and the events are tagged as auto-captured so you can tell them apart from what a human deliberately wrote down. ### Seeing the memory: one project Everything so far has been text. pjm visualize renders the same event log as a single self-contained HTML file and opens it — no server, no build step, no network. It is one file you can email to someone. The Overview opens on a Memory Card — a shareable summary of what this project has learned — with the story of the codebase beside it. (image: projectmem Memory Card: a shareable summary of one project's memory showing 49K tokens saved, 19 hours saved, 12 cases closed and an A+ prevention grade, with buttons to download the card, copy a README badge and share it) Six workspaces sit in the left sidebar. Each answers a different question: Below the Memory Card, Case files turns the event log into one card per problem — what broke, what was tried, and how it ended: (image: projectmem Case files panel: each closed issue as a card showing what broke, how many attempts it took and the fix that ended it) #### Story Map — where the effort went A treemap where area is effort and colour is failure intensity. The large red rectangles are the files that fought back. Click one and you get its dossier: every issue, attempt, fix, decision and note that ever touched it, in order. (image: projectmem Story Map treemap: every file in the project sized by how many events it accumulated and shaded by failure intensity, from solid red on the files that fought back to pale grey on the quiet ones) This is the view that changes how a project feels. A file you thought was fine turns out to be the reddest rectangle on the page, and the reason is right there in its dossier. #### Project Map — structure with failure on top pjm map --build reads your code and, for Python, resolves imports into a real dependency graph. The Project Map draws that structure and then colours it with your memory. Structure comes from the code, heat comes from the event log, and they meet only in the renderer. (image: projectmem Project Map: the project's file tree coloured by the events recorded against each file, with directory filters and clickable nodes) This is the one view a pure code-grapher cannot draw and a pure memory tool cannot either. Neither half is interesting alone. #### Timeline — what happened, in order (image: projectmem Timeline: the project's issues, attempts, fixes, decisions and notes laid out in order, with clickable markers that open the full case) Click any red dot and the full case opens — the issue, every attempt with its outcome, and the fix that ended it. Read it a month later and you can reconstruct the afternoon. ### Seeing the memory: every project at once pjm dashboard aggregates every registered project into one page. Run it from anywhere — it does not care which directory you are in. The page opens on the question you actually have after a weekend away — not "how are my metrics" but **where was I?** (image: projectmem global dashboard session card: names the last project worked on, the length and event count of that session, that it finished on a fix, the files it touched, and what was left open) That top card is reconstructed from timestamps alone — a session is just a run of events less than three hours apart. It tells you which project you were last in, how long you were there, what you finished on, and what you left open. No prompt to copy, no summary to write. It is the signal that lets you remember the rest yourself. Below it, the attention band shows which projects have been getting your time over the trailing 32 weeks, and which have gone quiet. (image: projectmem attention band: a heatmap of weekly activity per project across 32 weeks, showing which projects have had attention and which have gone quiet) Each card carries a state badge, and those are the honest ones: **Wrapped up** means every issue has a fix after it, **Capturing** means work is in progress, **Mid-problem** means you left with issues open and no fix recorded. A project sitting at Mid-problem for three weeks is telling you something. (image: projectmem global dashboard project cards: one card per project with a letter grade, event and fix counts, open issues, an activity sparkline and a state badge reading Wrapped up, Capturing or Mid-problem) > This is a global **view**, never a global **store**. The dashboard reads each repository's own .projectmem/ at the moment you run it and renders one local page. Nothing is copied out, there is no central database, and ~/.projectmem/projects.json records only where your projects are. Delete a repo and its memory goes with it. The default is a static snapshot, and the page labels itself as one so it never pretends to be live. If you want a Refresh button that actually re-reads your files: ```bash pjm dashboard --serve # ephemeral local server, Ctrl+C to stop pjm dashboard --serve --port 9000 # if 8787 is taken ``` There is no background daemon and nothing survives Ctrl+C. ### The three commands you will actually use Most of projectmem's surface is for your agent. Three commands are for you, and they map onto the three moments where memory pays: starting, committing, and reviewing. #### pjm brief — start here Run it when you sit down. It is the human counterpart to get_summary(): what is on fire, what is open, what you decided, and where the score is heading. #### pjm precheck — the one that prevents things This runs automatically before every commit, because pjm init installed the hook. It looks at the files you are about to commit and tells you what already failed in them. This is the feature with no equivalent elsewhere. Every other memory tool answers questions when asked. This one interrupts you, unprompted, at the moment you are about to repeat yourself — and it is the reason projectmem calls itself a judgment layer and not just a memory. > Genuinely need to push past it? pjm precheck --snooze 2h silences warnings for two hours — and logs the snooze as an event, so the silence is itself in the audit trail. Nothing about the record is quietly editable, including the decision to ignore it. #### pjm score — what it has been worth That is a **D**, and it is worth sitting with rather than explaining away. Twenty-one carefully written events over a few days is a genuinely well-logged young project — and it still scores 27/100, because the score measures accumulated knowledge, not diligence. Every component caps at 20 points and fills slowly. So the grade is not a verdict on you. It answers one question: **how much does this project already know?** A repo at A+ has hundreds of events, dozens of recorded dead ends and file coverage across the codebase. A new repo starts at F and climbs, and the only way up is time and honest logging. The same numbers have a rendered form. pjm visualize has an ROI Dashboard workspace that is the score as a page — the grade as a dial, and the token, hour and dollar estimates broken out: (image: projectmem ROI Dashboard: tokens saved, estimated USD saved and hours saved for the project, beside a prevention grade dial reading A+ at 90 out of 100) That one is a mature project from the [demo dashboard](/demo), not the three-week-old example above — which is the difference the grade is measuring. For a README badge: ```bash pjm score --format badge # shields.io endpoint JSON pjm score --format json # full breakdown, for CI ``` ### How the memory actually works Worth understanding, because it explains what projectmem will and will not do for you. #### One append-only log, one derived summary Everything is events.jsonl — one JSON object per line, appended, never rewritten. summary.md is regenerated from it. That direction is the whole design: ```text you / your agent │ ▼ events.jsonl ──regenerate──▶ summary.md ──▶ your AI reads this (append-only) (derived) │ ├──▶ pjm score (grade, estimated value) ├──▶ pjm precheck (what failed in these files) ├──▶ pjm visualize (one project, as HTML) └──▶ pjm dashboard (every project, as HTML) ``` Because history is never mutated, a correction is a new event rather than an edit. pjm decision --supersedes retires an earlier decision: the old event stays in the log tagged (superseded) and drops out of the summary. You can always replay how the project's understanding changed — which is the only reason an audit trail is worth keeping. > Never edit .projectmem/summary.md by hand. It is regenerated from the log, so your edit disappears on the next write and the log never learns what you meant. Write through the CLI or the MCP tools and the summary follows. #### Memory that knows it might be wrong Stored knowledge goes stale, and a memory tool that does not admit that is worse than none — it makes confident claims about a file that has since been rewritten. projectmem counts commits to the files a memory cites and flags the ones that have fallen behind. You already saw it fire in the precheck above, and pjm brief reports it too: ```text ⏳ Possibly stale decision [evt_49cf18c48b06] Webhook handlers are idempotent by construction, never — src/payments/webhook.py changed 8x since confirm, or retire: pjm decision "..." --supersedes ``` It says **possibly** stale, and it never deletes anything. Eight commits to a file is evidence that a decision about that file might not hold any more — it is not proof that it does not. Whether it still holds is a judgment only you can make, which is why the tool's entire response is to raise its hand. #### Lessons that outlive the project Some things you learn are not about this repository at all — they are about a library. When you record an attempt, decision or note that mentions one, projectmem promotes it to a machine-wide store at ~/.projectmem/global/, filtered by your detected stack. Start a new project using the same library and your agent inherits the gotcha through get_global_gotchas(). ```bash pjm gotchas stripe # what this machine has learned about stripe ``` Still entirely local. "Global" means your machine, not a server. ### What it costs you Stated plainly, because the honest answer includes the parts that are not free. The privacy position is simple enough to state in one line: everything is a file on your disk. .projectmem/ is in your repo, ~/.projectmem/ holds the registry and the global gotchas, and the only network call in the entire tool is the version check you ask for with pjm doctor --online. No accounts, no telemetry, no phone-home on install. ### Frequently asked questions ### The whole thing, in six commands ```bash pip install projectmem # 1. install cd ~/code/your-project pjm init # 2. scaffold memory + git hooks # 3. paste the MCP block into your client, # then fully restart it pjm doctor # 4. confirm nothing is pinned or unregistered # 5. ask your AI a question about the project pjm brief # 6. and this is how each session starts ``` After that, the loop is short: your agent reads memory at the start of a session and writes to it as things happen, the pre-commit hook catches you repeating yourself, and pjm dashboard tells you where you left off when you come back a week later. projectmem is free and MIT-licensed. The [setup guide](/guide) covers the same ground as a reference, the [changelog](/changelog) tracks what each release changed, and the [live demo](/demo) is a real dashboard you can click through. If it saves you an afternoon, a [GitHub star](https://github.com/riponcm/projectmem) helps other people find it — and issues and pull requests are genuinely welcome. ## AI Memory for Coding Agents in 2026: projectmem, OpenMemory, Graphify and MemRL Compared > Four open-source tools now give AI coding agents memory — and they remember completely different things. A structural map, a preference store, an RL-scored episode log, and a typed record of what failed. Here is what each actually stores, and which one fits which problem. Published 2026-08-12 · https://projectmem.dev/blog/ai-memory-for-coding-agents-compared/ "AI memory" became a category in 2026, but the label hides a real split. Two tools can both claim to give Claude Code memory and share almost no functionality. One remembers your codebase's structure. Another remembers that you prefer pytest. A third remembers the transcript of last Tuesday. These solve different problems, and picking by star count gets you the wrong one. This compares the four most active open-source options by what they actually store. We build one of them ([projectmem](/guide)), so every capability below is stated as a documented design capability, with the trade-offs named in both directions. ### The four tools ### What each tool actually remembers This is the distinction that matters, and it is the one most comparison posts skip. Put plainly: Graphify gives your agent a **map**. OpenMemory gives it a **profile**. MemRL gives it a **diary with a highlighter**. projectmem gives it a **lab notebook** — including the experiments that failed. ### Capability comparison ### Why token savings claims are hard to compare Every tool in this category advertises token reduction, and the numbers are not comparable because the baselines differ. A structural tool measures against an agent reading whole files. A memory layer measures against an agent rebuilding conversational context. Same unit, different denominators. > A note on benchmarks: LoCoMo, LongMemEval and BEAM are the standard AI-memory benchmarks, and none of them measure coding work. They test recall over multi-session conversations. No public benchmark yet asks whether an agent avoided repeating a failed fix — which is why every claim in this category, including ours, should be read as a design capability rather than a measured result. ### Where projectmem is weaker Graphify understands code structure far more deeply than projectmem's pjm map does — it parses many languages deterministically and explains every edge. If structural navigation is your bottleneck, use Graphify. OpenMemory has broader client integration and a much larger community behind it. MemRL is doing something genuinely novel with utility scoring that projectmem does not attempt. And projectmem has no conversational recall at all: it will not remember what you said, only what you did. ### Frequently asked questions ### The short version The category is young and the tools are converging in name only. Ask what kind of memory your agent is missing — a map, a profile, a diary, or a lab notebook — and pick accordingly. If your agent keeps walking into walls it has already hit, that is the gap [projectmem](/guide) was built for. ## projectmem v0.2.0: The Workspace Release — a Cross-Project Global Dashboard, Code Structure & Relations, and plan.md > projectmem v0.2.0 lifts memory from one project to your whole machine. pjm dashboard puts every repo you've init-ed in a single local view, pjm map --build reads your code into a real structure graph with failure heat laid on top, and a new plan.md keeps intent separate from the event log. 15 MCP tools, no schema changes, still 100% local. Published 2026-07-07 · https://projectmem.dev/blog/projectmem-v020-workspace-release-global-dashboard-code-structure-plan/ projectmem v0.2.0 is the workspace release. Until now, the local-first memory + judgment layer for AI coding agents lived inside one project at a time. v0.2.0 lifts that to your whole machine — and closes the gap between what happened (memory) and what your code actually is (structure). No new required dependencies, and the six core event types are unchanged: your existing events.jsonl just gains new ways to be seen. Install or upgrade in one command: ```bash pip install -U projectmem ``` ### The global dashboard: every project in one view (image: projectmem v0.2.0 global dashboard: every pjm init-ed project in one view with grades, issues captured, dead-ends prevented, tokens saved, and a grade-per-project card grid) The new pjm dashboard is a single page over every repo you've run [pjm init](/guide) in: total issues captured, fixes confirmed, dead-ends prevented, tokens and dollars saved, a letter grade per project, and a 'needs attention' list. Click any card and it opens that repo's own dashboard, generated fresh from its current files. ```bash pjm dashboard # writes a static snapshot and opens it pjm dashboard --serve # live: Refresh re-reads your files (Ctrl+C to stop) pjm dashboard --serve --port 9000 ``` Crucially, this is a global view, not a global store. Nothing is centralized: the dashboard aggregates each repo's own .projectmem/ at read time and never copies memory out of its folder. A tiny registry at ~/.projectmem/projects.json only records where your projects live. The default is serverless — it writes a self-contained snapshot and the page honestly labels itself a snapshot, so it never pretends to be live. Add --serve and a tiny, ephemeral local server renders everything fresh on each load; there's no background daemon, and Ctrl+C ends it cleanly. ### Code structure & relations: memory meets the code Memory knew your history; now projectmem also reads your structure. pjm map --build walks the codebase and, for Python, resolves imports into a real dependency graph. It writes a derived, gitignored structure.json cache — code is only ever read, never modified — and it runs automatically right after [pjm init](/guide), so the map is populated from day one. ```bash pjm init # scaffolds .projectmem AND builds the structure map pjm map --build # rebuild the structure + import graph any time pjm map # print the current Project Map ``` The Project Map's Graph and Flow views now render your actual files and the import edges between them — not just the files that happen to appear in the event log. ### Failure heat on structure — the combo This is the one view a pure code-grapher can't draw and a pure memory tool can't either: real structure with real judgment on top. Files with repeated failed attempts in your event log glow red — with a dashed ring past a threshold — laid directly over the import graph, and hovering shows the failed attempts. 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, in plain Markdown (Ideas, Active plans, Next, Someday, Shipped). It is deliberately NOT the event log: events.jsonl → summary.md records what happened; plan.md records what you intend. Your AI reads it at session start via the new get_plan() MCP tool and edits it directly, the way it edits PROJECT_MAP.md — a plan never becomes an event, so intent stays out of your memory's audit trail. ```bash pjm plan # print the plan (intent) file pjm plan "add a migration adapter" # append an idea under Ideas ``` On the MCP side, get_plan() is the fifteenth projectmem tool. Your agent now has a read for intent (get_plan) alongside its reads for memory (get_summary, get_project_map) and its writes for events (log_issue, record_attempt, record_fix, add_decision, add_note). Everything else in the schema is unchanged. > Everything above is 100% local. The global dashboard is a read-time aggregate of each repo's .projectmem/ — never a central copy of your code's history — and the only server anywhere is the optional pjm dashboard --serve, an ephemeral viewer you start and stop with Ctrl+C. No cloud, no telemetry, no accounts. ### Frequently asked questions ### Try it ```bash pip install -U projectmem cd your-project pjm init # if you haven't already — also builds the structure map pjm dashboard # then, from any repo, see them all in one view ``` projectmem is free and open source (MIT). If the workspace view makes your projects click together, a GitHub star helps others find it — and issues and PRs are very welcome. Next up (v0.2.1): pjm import, to migrate your history from mem0, agentmemory, Letta, and Claude session logs into projectmem. ## projectmem v0.1.6: Watch Your Project's Memory — Showoff Scenes, a Built-In Recorder, Flow Maps and the Time Spine > projectmem v0.1.6 is the visualization release: a new Showoff tab plays your project's history as animated scenes (and records a shareable video, 100% locally), the Project Map gains a Flow layout that reads like a story, and the Timeline becomes a Time Spine — problems branching left, knowledge branching right. Published 2026-07-01 · https://projectmem.dev/blog/projectmem-v016-visualization-release-showoff-flow-time-spine/ projectmem v0.1.6 is the visualization release. The local-first memory + judgment layer for AI coding agents already remembered every issue, failed attempt, fix, and decision in your project — now it can show you that story, animate it, and even record it as a video you can share. Zero new dependencies, no schema changes, no CLI changes: every new view is rendered from the same append-only events.jsonl you already have. Install or upgrade in one command: ```bash pip install -U projectmem ``` ### Showoff: your project as a living galaxy (image: projectmem v0.1.6 Showoff tab: the Universe scene — the project as a rotating galaxy where every bright star is a real logged event) Open [pjm visualize](/demo) and there is a new tab in the sidebar: Showoff. It plays three animated scenes, all driven by your real event log. Story Replay rebuilds your project's history node by node on a force canvas — issues appear, failed attempts flash, fixes bloom — with a scrubber, live captions, and an auto-loop. Orbit turns your codebase into a solar system: files orbit the project, events orbit their file. And Universe renders the whole project as a rotating spiral galaxy where every bright, blinking star is a real issue, attempt, fix, or decision. None of it is decorative fakery: click any node and the field dims, a halo pulses around it, its real connections light up, and a card shows the actual event — summary, file, issue number, date. Click again to release. It is the same data as the Story Map, staged like a planetarium. ### Hit REC: a shareable video, rendered 100% locally The Showoff bar has a REC button with a 10–60 second picker. It records the animation using your browser's own MediaRecorder — nothing leaves your machine — and downloads a .webm clip with a small, toggleable 'made with projectmem' badge baked in. A debugging month compressed into a fifteen-second galaxy flyover is the kind of thing you can actually post. ### Flow: the project map that reads like a story (image: projectmem v0.1.6 Flow layout: PROJECT to DIRECTORIES to FILES to WHAT HAPPENED to MEMORY, with a red path marking the file with repeated failures) The Project Map gains a third layout — Flow — and it is now the default. It reads left to right like a flowchart: PROJECT → DIRECTORIES → FILES → WHAT HAPPENED → MEMORY. Files with three or more failures are outlined red, with red flow lines tracing the hot path. Every file carries chips summarizing its story — 4 failed, 1 decision, 3 notes — and every line converges into a cylinder labeled events.jsonl, because that is what projectmem actually is: an append-only memory everything flows into. Zoom, pan, auto-fit; a new 'Hide details' toggle gives any view the full width. Tree and Graph are still one click away. ### Time Spine: problems left, knowledge right (image: projectmem v0.1.6 Time Spine: a central real-time axis with issue and attempt cards branching left, fixes, decisions and notes branching right) The Timeline's new default view is a Time Spine: a central real-time axis you scroll, with day pills and 'quiet gap' markers where nothing happened. The story branches into two meaningful sides — problems on the left (issues; failed, partial and worked attempts), knowledge on the right (fixes, decisions, notes). A glance tells you the shape of any day: heavy left means struggling, heavy right means learning. Hover any card and its entire issue thread stays lit while everything else dims — you can watch one bug's story thread down through time. The classic list view is still there as Details. ### Community: this release has a second author v0.1.6 also ships the Story Map readability controls contributed by Mike Hanley (@hanley-development): collapse dense files into draggable bubbles, collapse directories with click-to-drill-down, expand all, reset focus, and correct linking for file-only locations. After his three reliability fixes in v0.1.5, this is his second release in a row — exactly the kind of contribution an open, plain-text, MIT-licensed tool is built to attract. Thank you, Mike. > Everything above is generated from your local .projectmem/events.jsonl — 100% local, no telemetry, no accounts. The recorder runs in your browser; the video never touches a server. ### Frequently asked questions ### Try it ```bash pip install -U projectmem cd your-project pjm init # if you haven't already pjm visualize # then click Showoff ``` projectmem is free and open source (MIT). If the new views make your project's story click for you, a GitHub star helps others find it — and issues and PRs are very welcome; as this release proves, they ship. ## projectmem v0.1.4: Stale-Memory Detection for AI Coding Agents — Flag, Never Delete > projectmem v0.1.4 is the accountable-judgment release: stale-memory detection that flags outdated decisions instead of deleting them, supersede without losing history, a polite pre-commit snooze, the pjm brief session briefing, and CLAUDE.md export so even agents without MCP inherit your project's judgment. Published 2026-06-12 · https://projectmem.dev/blog/projectmem-v014-stale-memory-detection-ai-coding-agents/ projectmem v0.1.4 is the accountable-judgment release. The local-first memory layer for AI coding agents now flags its own staleness instead of silently trusting — or silently deleting — old memories. Six new features, about 330 lines of code, zero new dependencies, and the same 14-tool MCP surface that works across Claude Desktop, Claude Code, Cursor, Antigravity, and Codex. (image: projectmem v0.1.4 dashboard overview: failure heatmap, A-to-F prevention grade gauge, project map with failure rings, and a typed-event timeline — generated locally from .projectmem/events.jsonl) Install or upgrade in one command: ```bash pip install -U projectmem ``` ### What is stale-memory detection? Stale-memory detection is a deterministic check that cross-references every recorded decision, fix, and note against the git history of the file it cites. If you logged "auth uses session cookies with a 30-minute timeout" against auth.py, and auth.py has since changed in three or more commits — or no longer exists — projectmem flags the memory as possibly stale, right inside the [pre-commit warnings](/#features) and the MCP precheck_file tool. ```text $ pjm precheck auth.py auth.py 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 ``` The important word is flag. Most AI memory systems handle aging memories with decay: old entries get down-ranked, pruned, or rewritten automatically — and users discover that memories they still wanted have quietly vanished. projectmem takes the opposite position: memory is never deleted, never down-ranked, never rewritten. It is flagged, and a human decides. No embeddings, no daemon, no model call — just a git log count. > Design principle: detect staleness, let the human supersede, never lose history. Judgment belongs in the loop; deletion does not. ### Supersede a decision without rewriting history When a flagged decision really is outdated, you retire it explicitly: ```bash pjm decision "auth migrated to JWT, 15min expiry" --supersedes evt_9db5a3f8 ``` Three guarantees follow. The old decision disappears from summary.md, so your AI only steers by the current one. It stays physically in events.jsonl — the log is append-only, always. And pjm search still finds it, tagged (superseded), with event ids now printed so the reference is one copy-paste away. The same option exists on the MCP add_decision tool, so your AI agent can retire stale decisions itself when you confirm. ### pjm brief: the session-start briefing One command answers "where was I?" — active failure warnings by file, possibly-stale memories, open issues, the latest live decisions, stack-relevant gotchas inherited from your other projects, and your prevention score with a week-over-week delta. It runs in milliseconds and composes data projectmem already tracks. Nothing leaves your machine. ```text $ pjm brief projectmem brief — acme-web ────────────────────────────────────────── ⚠ Active warnings payment.py — 2 failed attempts ⏳ Possibly stale decision [evt_9db5...] auth uses session cookies 📋 Open issues #0001 payment form jumps on submit 🕑 Recent decisions auth migrated to JWT, 15min expiry 📈 Score B (72/100) ▲ +9 this week ``` ### Pre-commit warnings now list what already failed The killer feature got sharper. Instead of telling you "3 failed attempts on this file," the warning now lists the dead ends themselves — "tried CSS contain:layout", "debounced the submit handler" — so neither you nor your AI re-tries them. The data was always in the event log; v0.1.4 puts it at the decision point. pjm search --failed-only lists a project's full catalogue of dead ends, and search now matches file paths logged with --at. ### A snooze that is itself audited Every warning system faces the same failure mode: when it fires at the wrong moment, users reach for git commit --no-verify — which silences everything, forever, invisibly. v0.1.4 adds the polite alternative: pjm precheck --snooze 2h pauses warnings for a bounded window. The snooze itself is logged to memory, so even the silence is on the audit trail, and while it is active every commit prints one dim line so a silenced warning is never mistaken for a clean check. ### CLAUDE.md export: memory for agents without MCP MCP-connected agents read projectmem through 14 native tools. But what about GitHub Copilot, a plain Claude chat, or any tool that never loads an [MCP server](/guide)? pjm export --claude-md compiles the live memory — current decisions with stale flags, known gotchas, and a "Do NOT retry — these already failed" list — into a marked, auto-regenerated block inside CLAUDE.md (add --cursor for .cursorrules). Any agent that reads the file inherits the project's judgment with zero setup. Superseded decisions are excluded; possibly-stale ones are flagged, not hidden. ### Also in 0.1.4 ### Why flag-never-delete matters Memory that silently changes is memory you cannot trust. Decay-based systems optimize for retrieval relevance, and the cost is auditability: you cannot ask "what did my project know last month?" if last month's knowledge was pruned. projectmem's event log is append-only plain text — you can cat it, grep it, and diff it — and v0.1.4 extends that accountability to aging: staleness is detected deterministically from git history and surfaced for a human decision. This is the same philosophy as the rest of the tool: 100% local, no daemon, no telemetry, no cloud account, secrets redacted before they ever touch disk. ### The research behind it projectmem's design — including the Memory-as-Governance framing, the deterministic pre-commit judgment gate, and a two-month dogfooding study across 10 real projects and 207 logged events — is described in our research paper: "PROJECTMEM: A Local-First, Event-Sourced Memory and Judgment Layer for AI Coding Agents" (arXiv:2606.12329). If projectmem is useful in your research, the paper page has a ready BibTeX entry. ### FAQ ### Get started ```bash pip install projectmem cd your-project pjm init pjm brief ``` Full release notes are on the changelog at projectmem.dev/changelog, the complete setup guide for every MCP client is at projectmem.dev/guide, and the source is MIT-licensed at github.com/riponcm/projectmem. If projectmem saves you a re-debugging session this week, a GitHub star helps more developers find it. ## projectmem v0.1.3: Schema-Enriched MCP Tools, Secret Redaction, and the Conda/Venv Hook Fix > projectmem v0.1.3 lands six focused improvements: every MCP tool now exposes rich parameter descriptions and schema-level constraints (record_attempt.outcome is enforced at the schema), API keys and tokens are scrubbed from event text before they touch disk, the pre-commit warning now actually fires under conda/pyenv/venv where it had been silently broken for most Python users, pjm init pre-populates PROJECT_MAP from your manifests, and it prints a copy-pasteable MCP client config block at the end. Six improvements, one release. Published 2026-05-20 · https://projectmem.dev/blog/projectmem-v013-schema-redaction-hook-fix/ Today we're releasing projectmem v0.1.3 — six carefully scoped improvements that together close the biggest first-run friction points and add a real privacy guardrail on top of the local-first memory layer. The headline fix (L-047) restores the [pre-commit warnings](/#features) for the majority of Python users; the headline feature (secret redaction) puts a default-on scrubber between your AI sessions and your event log. The other four improvements polish the parts of the product people touch first. Install or upgrade in one command: ```bash pip install -U projectmem ``` ### 1 — Schema enrichment on every MCP tool All 14 projectmem MCP tools now expose Pydantic Field descriptions on every parameter, plus schema-level constraints. Before v0.1.3 a tool's parameters showed up in AI clients as bare names and types — summary: string, outcome: string, limit: integer — and the agent had to guess at semantics. Glama's automated tool-quality evaluator flagged this across the entire surface (Parameters scored 1-2/5 on every tool with arguments). Now search_events.limit clamps to 1..100 at the schema layer. record_attempt.outcome enforces ^(worked|failed|partial)$ — an agent that tries to pass outcome="maybe" is rejected by the JSON-RPC schema validation before the tool body runs. Every parameter has a real description that surfaces on hover in Claude Desktop / Cursor / Antigravity / Codex. Projected Glama tool-quality score lifts from 75% with one B-grade tool to roughly 90% all-A. ### 2 — Secret redaction on write (the privacy guardrail) projectmem's value proposition is local-first: every event lives in .projectmem/events.jsonl in your repo, in plain text you can git diff. The flip side: a careless paste in an AI chat — "the bug repros when I set OPENAI_API_KEY=sk-..." — used to land that key on disk verbatim, often in a file that subsequently got committed to git. v0.1.3 closes that hole. storage.append_event now runs a conservative pattern scrubber across the event's user-supplied text fields (summary, notes, command, git_message, location) BEFORE anything touches disk. Matches are replaced with [REDACTED:] and a one-line stderr notice fires so you know redaction happened. Patterns covered: OpenAI / Anthropic / OpenRouter sk-... keys, GitHub classic tokens (ghp_..., gho_..., ghu_..., ghs_..., ghr_...) and fine-grained PATs (github_pat_...), AWS access key IDs (AKIA...), Google API keys (AIza...), Slack tokens (xox[abprs]-...), Stripe live/test keys, JWTs (eyJ...), Bearer tokens, and PEM private-key block headers. The patterns are intentionally narrow — anchored to recognisable prefixes with minimum-length requirements — so ordinary debugging prose like tried contain: layout or forgot password reset flow is never touched. 29 new tests pin both the true-positive and false-positive behavior. Default on. Escape hatch: PROJECTMEM_NO_REDACT=1 skips scrubbing entirely (for debugging the redactor itself or for trusted offline contexts). The whole thing is wrapped in a defensive try/except so a scrubber bug never blocks the primary write path — better a logged secret than a lost event in a tool whose job is logging. ### 3 — L-047: the pre-commit warning silently no-op under conda / venv This one stings. projectmem's killer feature is the [pre-commit warnings](/#features) — the moment where memory becomes judgment, where the system tells you "you tried this approach a month ago, it didn't work." From v0.1.1 through v0.1.2 that feature was silently broken for the majority of Python users. Here's why. pjm init installs git hooks under .git/hooks/. The pre-commit snippet looked like this: ```bash if [ -d ".projectmem" ]; then if command -v pjm &> /dev/null; then pjm precheck --level warn || true fi fi ``` It relied on command -v pjm to find the binary at commit time. Git invokes hooks via a non-interactive bash — which does NOT run .zshrc or .bashrc — so conda's PATH modifications were absent. command -v pjm returned nothing, the if block skipped silently, and git commit proceeded with no output. The user saw a normal commit and assumed projectmem had no warning to give. In fact the warning was sitting right there in memory, ready to fire, with no way to deliver it. The fix: install_hooks now resolves the absolute path to pjm (via shutil.which, falling back to sys.prefix/bin/pjm) at install time and bakes it into the hook as a literal PJM_BIN="/abs/path/to/pjm". A runtime command -v fallback remains for the rare case where the install-time binary was later moved. The hook's if [ -d ".projectmem" ] && [ -n "$PJM_BIN" ] guard means a stale path degrades gracefully instead of erroring at commit time. Verified end-to-end with a regression test that simulates git's hook environment (stripped PATH, no shell init), and with a real git commit in a conda-installed setup — the warning now appears reliably. Users who installed projectmem before v0.1.3 need to run pjm hooks install once after upgrading to refresh the baked path. ### 4 — L-048: pjm init pre-populates PROJECT_MAP.md from your stack Before v0.1.3, PROJECT_MAP.md started life as a Status: not created yet placeholder that an AI session had to fill in by re-reading every manifest and folder — exactly the kind of token burn projectmem is supposed to prevent. pjm init now reads pyproject.toml / package.json / Cargo.toml / go.mod directly and writes an actual map: project description, stack tags + frameworks + key libraries, main folders, and entry points. Setup Mode becomes refinement, not greenfield. The agent's first prompt against a fresh .projectmem/ finds an already-useful PROJECT_MAP and adds the architectural decisions it learns on top — instead of having to rebuild the whole stack tour from scratch every time. Skip with --no-stack-detect. Safety: the auto-populate only overwrites when the current map still contains the placeholder marker; a human- or AI-edited map is never clobbered. ### 5 — L-049: pjm init prints the MCP client config block Every new user asked the same question right after pjm init: "OK, what JSON do I paste, and where?" The answer was in the README, but six clicks deep. v0.1.3's pjm init ends with a copy-pasteable config block right in the terminal: ```json { "mcpServers": { "projectmem": { "command": "/opt/anaconda3/bin/python", "args": [ "-m", "projectmem.mcp_server", "--root", "/Users/you/repo" ] } } } ``` The absolute sys.executable is baked in to dodge the Claude-Desktop / Cursor PATH-inheritance gotcha (those clients spawn the MCP server without your shell's PATH). The block is followed by the on-disk config-file paths for Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json), Cursor (~/.cursor/mcp.json), Antigravity legacy IDE (~/.gemini/antigravity/mcp_config.json), and Codex (~/.codex/config.toml — TOML, not JSON). Skip with --no-mcp-config. ### 6 — L-050: silent post-commit auto-capture Smaller paper-cut, real annoyance. The post-commit / post-merge hooks run pjm _auto-capture in the background (&). Before v0.1.3 the snippet redirected only stderr (2>/dev/null), so the success line — [projectmem] Auto-captured: … — printed to stdout AFTER git commit had already returned the prompt. Visually it looked like the terminal was hung waiting for input; users would press Ctrl-C to recover when their keystrokes were already being captured by the shell. Now both streams are redirected (>/dev/null 2>&1 &) — capture stays silent. Verify it ran via pjm show. ### Plus: TUTORIAL.md and a tighter PyPI tagline v0.1.3 also ships a new TUTORIAL.md at the repo root — a 15-minute step-by-step walkthrough that covers install, init, Setup Mode, the issue → attempt → fix lifecycle, the pre-commit warning, Maintenance Mode, and pjm score. It's linked from the README and is the canonical written companion to the upcoming screen-recorded video tutorial. The PyPI and official MCP Registry tagline both tightened to: "Local-first memory + judgment layer for AI coding agents — warns before repeating failed fixes." Same wording across surfaces. ### Upgrading ```bash pip install -U projectmem # refresh the git hook so the baked path picks up your current install pjm hooks install ``` That second command is important if you were on v0.1.1 or v0.1.2 — without re-installing the hooks, you keep the old command -v pjm snippet and the L-047 fix doesn't take effect. After re-install, run head .git/hooks/pre-commit and confirm the file contains a PJM_BIN="..." line with the absolute path to your pjm binary. ### Frequently asked questions ### What's next Two tracks. Short term: a full screen-recorded tutorial replaces the 60-second promo on the demo page; Product Hunt launch with the assets that are now stable; the warm-up plan for the HN Show post. Medium term: a 0.2.0 alpha with the next batch of competitive features — stale-memory detection (flag, never delete), explicit supersedes-marking for decisions, and a citation-provenance flag on get_summary / get_context output so the agent can trace any retrieved claim back to its originating event. All of v0.1.3 — 58 passing tests, end-to-end verified across Claude Desktop / Cursor / Antigravity / Codex, conda / pyenv / venv. Get it with pip install -U projectmem. Full release notes on the changelog page, full walkthrough in TUTORIAL.md on GitHub. ## projectmem v0.1.1: The First Local-First Cross-Project Memory Layer for AI Coding Agents > projectmem v0.1.1 ships the first open-source local-first cross-project memory layer for AI coding agents — verified end-to-end across Claude Desktop, Cursor, Antigravity, and Codex, and across JavaScript, Python, and Go. Library gotchas learned in one project surface automatically in every other. 100% local, MIT, install in two commands. Published 2026-05-15 · https://projectmem.dev/blog/projectmem-v011-cross-project-memory-launch/ Today we're releasing projectmem v0.1.1 — the first stable public release, and the first open-source local-first memory layer that gives AI coding agents persistent knowledge across every project on your machine. Library gotchas learned while debugging one repository automatically surface in every future repository on a shared stack — with source-project attribution, stack-aware filtering, and zero cloud sync. Verified end-to-end across four major MCP clients (Claude Desktop, Cursor, Antigravity, Codex) and three language ecosystems (JavaScript, Python, Go). 100% local. No telemetry. No accounts. MIT licensed. If you've ever caught your AI agent re-suggesting the same broken fix you rejected last week — or worse, suggesting it in a different project, completely unaware you've fought this battle before — that's the gap projectmem closes. ### The Problem Every AI Coding Session Has Modern AI coding agents are brilliant for a single session and amnesiac across them. Claude Code, Cursor, Antigravity, and Codex all reset to zero context every time you start a fresh chat. They don't remember the architectural decision you made on Tuesday, the regex they tried that failed on Wednesday, or the library gotcha you discovered three projects ago. Every conversation starts from scratch, which means you start from scratch — re-explaining context, re-watching the AI propose approaches you've already disproven, re-discovering lessons your past self learned the hard way. The industry's first answer to this was vector databases full of conversation transcripts. The result: AI that quotes itself badly. The second answer was static rule files like CLAUDE.md and .cursorrules. The result: stale rules that drift the moment the project changes. Neither solves the real problem, which is that meaningful AI memory needs structure — issues, attempts, decisions, fixes — and it needs to travel across both sessions AND projects. ### What projectmem Does projectmem captures structured project memory in a local .projectmem/ directory inside every repository, with a shared cross-project store at ~/.projectmem/global/ on your machine. Events are append-only JSONL — human-readable, git-friendly, AI-readable. A native Model Context Protocol (MCP) server exposes 15 tools that any MCP-compatible AI client can call directly, with no API keys, no cloud account, no paid plan. Two commands installs the whole thing: ```bash pip install projectmem cd your-project pjm init ``` That's it. Git hooks are installed. The real-time file watcher starts in the background. Cross-project gotchas from your other repositories are inherited automatically based on the stack this project declares. Your AI client picks up the [MCP server](/guide) on its next launch. ### What's New in v0.1.1 v0.0.6 introduced the intelligence layer — [pre-commit warnings](/#features), the prevention score, smart context injection, the real-time watcher. v0.1.0 stayed internal as the polish + cross-client tag. v0.1.1 is the first stable PyPI release and closes three concrete wiring gaps that were preventing cross-project memory from actually working in earlier builds. All three fixes ship with end-to-end verification across real projects in real MCP clients. #### 1. Cross-Project Memory, Wired End-to-End (L-043) The 'Cross-Project Knowledge' diagram on the landing page promised library gotchas to propagate machine-wide. Verification revealed it shipped half-built: the auto_promote_event function existed in global_memory.py but no write path actually called it. Every record_attempt, add_decision, and add_note silently skipped the global promotion step. The cross-project store stayed empty forever; nothing had anything to inherit. v0.1.1 wires auto-promotion into storage.append_event — the single chokepoint every write tool routes through. Whether you're using the MCP server, the CLI, or a git hook, library-mentioning events now promote consistently. Plus two precision fixes that came out of the same investigation: whole-word library matching (so 'gin' doesn't false-match inside 'imagineering') and stack-filtering (so a vite project mentioning 'next' in plain English doesn't create a fake Next.js gotcha for actual Next.js projects). #### 2. Language Parity for Every Ecosystem (L-045) Earlier builds hardcoded a 28-entry PROMOTABLE_LIBRARIES set — every entry was JavaScript or Python. Go, Rust, Java, Ruby, .NET, Swift, Kotlin, Flutter — all silently dropped at promotion time. A Go developer using projectmem v0.0.6 would never accumulate cross-project knowledge for gin, chi, fiber, cobra, gorm, or any other Go library. The system gave every appearance of supporting these languages on the read side, then quietly did nothing on the write side. v0.1.1 replaces the hardcoded set with a self-curating cache at ~/.projectmem/global/.promotable.json. Every library that detect_stack ever observes in a manifest file on this machine — package.json, pyproject.toml, Cargo.toml, go.mod, Gemfile, pom.xml, build.gradle — becomes eligible for promotion. A Go user's gin lessons now propagate exactly like a React user's vite ones. The system curates itself to the languages you actually use, with no PRs needed to add 'fiber' or 'axum' to a list. #### 3. Signal Filter: Only Lessons, Not Setup Noise (L-046) Earlier builds promoted any library-mentioning decision to the global store. The result, in real testing across four scaffold projects: seven entries in the global store, of which only one was actually a cross-project lesson. The other six were project-local setup choices — 'Use FastAPI as the core web framework', 'Styling: Tailwind CSS 3.4.0', 'Use Uvicorn as the ASGI server'. Signal-to-noise sat at 14%. v0.1.1 introduces an explicit signal filter. Failed and partial attempts always promote — the outcome itself is the signal. Decisions and notes only promote if their summary opens with one of ten gotcha-signal prefixes (case-insensitive): A bare 'we use redis for caching' decision stays project-local. 'gotcha: redis pipeline batches over 1MB silently truncate' propagates machine-wide. The user opts in to global promotion by tagging the text — self-documenting, no hidden magic. Signal-to-noise in the post-fix verification cycle: 100%. ### Verified Across 4 MCP Clients and 3 Languages Cross-project memory is the kind of feature that's easy to claim and hard to actually prove. We built a dedicated test scaffold under /globaltest/ with four real subprojects — proj-react (React + Vite), proj-next (Next.js + Tailwind), proj-python (FastAPI + Pydantic + SQLAlchemy), and proj-go (Gin) — and walked the full auto-promote → stack-detect → inherit chain end-to-end. Results: 124 of 124 test cells green. 31 tests × 4 MCP clients = the full matrix. A vite gotcha logged in proj-react surfaces correctly in proj-next with proj-react attributed as the source. The same gotcha stays out of proj-python and proj-go responses because their declared stacks don't include vite. A gin decision in proj-go promotes correctly under the new library cache + signal filter. Negative cases (cross-project gotchas explicitly bounded by stack) pass. AI clients consistently call get_global_gotchas before proposing approaches, surface the source project transparently, and bridge stack differences in their reasoning. The promotion mechanism is server-side, so the guarantee inherits uniformly across all four MCP clients once any one client demonstrates the chain end-to-end. Antigravity served as the verification driver; Claude Desktop, Cursor, and Codex inherit the same behavior because they all flow through the same Python server. Each client ships with its own documented setup block, captured during real verification — including the workarounds for Claude Desktop's silently-ignored cwd field, Codex's TOML config quirks, and Cursor's matching --root requirement. ### How Cross-Project Memory Actually Works Conceptually there are three tiers of memory, each in its own location: There's no 'parent folder' magic. The shared store lives in your home folder, not in any project parent — which means it works regardless of whether your projects sit in a monorepo, in flat sibling directories, or scattered across your filesystem. Moving a project from one folder to another preserves both its local memory and its access to global knowledge. ### 100% Local. No Cloud. No Telemetry. Every memory file is human-readable on your disk. There is no cloud sync, no analytics, no anonymous usage data, no opt-in collection of any kind. The MCP server runs as a subprocess of your AI client and dies when you close the chat. The CLI runs only when you invoke it. There is no daemon making outbound network connections — projectmem cannot phone home because there is no home for it to phone. Team sharing of the global store is explicit and user-controlled: pjm global export writes a JSON file you can review, edit, redact, then commit to git or share via any channel you control. Your teammates run pjm global import to merge it into their local store. There is never an automatic sync, never a hidden upload, never a 'projectmem connect' command. Privacy is a structural property of how the system is built, not a setting you can flip off. ### Install in 60 Seconds ```bash pip install projectmem cd your-project pjm init ``` Requires Python 3.10 or later. Three small direct dependencies (typer, mcp, watchdog) get installed alongside. Total disk footprint under 5 MB. After pjm init, open your AI client and ask it any question about the project — memory is now wired. If you have multiple projects under one parent folder (a monorepo, or a Developer/ directory with several repos), run pjm init inside each one. v0.2.0 will add 'pjm init all' to scan and initialize a folder of projects in a single command. ### Frequently Asked Questions ### What's Next: v0.2.0 Roadmap Three features queued for the next minor release, all responses to user feedback during v0.1.1 verification: v0.3.0 introduces 'pjm switch' and an MCP --multi-project server mode so one MCP registration handles every project on your machine. End the per-project config-and-restart dance. ### Try It and Star the Repo projectmem v0.1.1 is on PyPI now. The fastest way to evaluate it is two commands and a fresh AI chat: ```bash pip install projectmem cd a-project-you-care-about pjm init ``` If you find it useful, the single most helpful thing you can do is star the GitHub repository and share it with one other developer. Cross-project memory works better the more developers use it — every library gotcha logged is a future hour someone else doesn't lose. Open source AI tools live or die on word of mouth; projectmem is free, MIT, no funding round, no growth team. Adoption is the only signal that this is worth keeping alive. Welcome to v0.1.1. Welcome to AI sessions that remember. Welcome to the first day your AI agent stops repeating yesterday's bugs. ## How to Give Claude Code Persistent Memory in 2026 (Step-by-Step Guide) > Claude Code forgets everything between sessions. This step-by-step tutorial shows you exactly how to give it persistent memory using projectmem and the Model Context Protocol — in under 60 seconds. Free, local, MIT-licensed. Published 2026-05-12 · https://projectmem.dev/blog/how-to-give-claude-code-persistent-memory/ Claude Code is one of the best AI coding assistants available in 2026 — but like every LLM-based assistant, it has a fundamental limitation: it forgets everything between sessions. Every new conversation starts with zero memory of your project's history, your past decisions, or the approaches that already failed. This tutorial walks you through giving Claude Code persistent project memory in three commands. You'll set up a local memory engine called projectmem, configure the Model Context Protocol (MCP) integration, and verify that Claude is reading and writing your project memory automatically. Total time: under 60 seconds. No cloud accounts. No API keys. No paid subscriptions. ### Why Claude Code Needs External Memory Claude Code has CLAUDE.md, which it reads at the start of each session. That handles static project rules — your coding style, your tooling preferences. But CLAUDE.md cannot capture dynamic memory: failed debugging attempts, architectural decisions made last week, library gotchas you discovered three projects ago. For that, you need a separate memory layer that captures events over time and surfaces them back to Claude on demand. projectmem is that layer. It's an open-source CLI tool that creates a .projectmem/ directory in your repo, captures events from git commits and AI sessions, and exposes them to Claude Code through a native [MCP server](/guide). The result: Claude starts every session already aware of your project's full history. ### Step 1: Install projectmem ```bash pip install projectmem ``` Requires Python 3.10 or later. Installs typer, mcp, and watchdog as dependencies (~70KB total). ### Step 2: Initialize Memory in Your Project ```bash cd your-project pjm init ``` This single command does everything: creates the .projectmem/ directory with structured memory files (summary.md, PROJECT_MAP.md, AI_INSTRUCTIONS.md), installs three git hooks ([pre-commit warnings](/#features), post-commit classification, post-merge tracking), auto-starts the real-time file watcher, inherits any cross-project memory from past projects with matching stacks, and backfills the last 20 git commits as classified events. ### Step 3: Connect Claude Code via MCP Open your Claude Desktop config file. On macOS, it lives at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows, it's at %APPDATA%/Claude/claude_desktop_config.json. Add a new MCP server entry pointing at projectmem: ```json { "mcpServers": { "projectmem": { "command": "python", "args": ["-m", "projectmem.mcp_server"] } } } ``` Save the file, then completely quit and restart Claude Desktop. The MCP server connection only initializes on app startup — a config reload won't pick it up. ### Step 4: Verify the Integration Open a new chat in Claude Desktop while inside your project's folder. Ask: 'What projectmem tools do you have access to?' Claude should list 15 tools, including get_instructions, get_summary, get_project_map, log_issue, record_attempt, record_fix, add_decision, add_note, precheck_file, get_issue, search_events, get_score, get_context, and get_global_gotchas. If you see this list, Claude is now wired to your project memory. ### Step 5: Test the Workflow Ask Claude to do something realistic that exercises the memory loop: If Claude is calling these tools automatically without you prompting it, you've successfully given Claude Code persistent memory. From this point forward, every session inherits everything your AI has ever learned about this project. ### Optional: Use the Same Memory in Cursor or Antigravity projectmem's MCP server is tool-agnostic. The same memory works in Cursor and in Antigravity (Google's AI IDE — config lives at ~/.gemini/antigravity/mcp_config.json). Add an MCP server entry pointing at python -m projectmem.mcp_server, set cwd to your project root (or rely on the parent-walk auto-discovery), restart the tool. Same 15 tools. Same memory. Same prevention score. Switching between Claude Code, Cursor, and Antigravity no longer means starting from scratch. Heads-up: on first run every MCP client (Claude Desktop, Cursor, Antigravity) asks permission before each new tool call. That's standard MCP security — not a bug, not a projectmem issue. Approve each tool once per session and the prompt stops appearing. ### What Happens Without MCP (Universal Mode) If you use an AI tool that doesn't support MCP — ChatGPT, Gemini, plain Claude.ai — you can still use projectmem. Paste this single line into your AI's Custom Instructions or System Prompt: ```text Read .projectmem/AI_INSTRUCTIONS.md, .projectmem/PROJECT_MAP.md, and .projectmem/summary.md before working. This project uses mandatory memory tracking. You MUST run `projectmem log` when you find a bug, `projectmem attempt` after each fix attempt, `projectmem fix` when confirmed. ``` The AI will read your memory files at the start of every session and suggest pjm commands for you to run. Less elegant than MCP, but works with any AI that can read files. ### Common Issues and Fixes ### Frequently asked questions ### What's Next You've given Claude Code persistent memory in three commands. The real value compounds over time. After a week, your AI starts noticing patterns. After a month, it warns you about repeated failures before you commit. After six months, your global memory across all your projects starts inheriting useful library gotchas into every new repo. If you want to push further, learn how to use pjm watch for real-time file churn detection, pjm wrap for token-budgeted context injection, and pjm score for measurable ROI. Full documentation is in the projectmem guide. ## How to Cut Your Claude and Cursor AI Token Costs by 50%+ Without Switching Models > AI coding bills are eating engineering budgets in 2026. Most of the cost is waste — the same context rebuilt across sessions, the same bugs debugged twice, the same prompts repeated. Here are five proven techniques to cut your Claude and Cursor token costs in half, ranked by impact. Published 2026-05-11 · https://projectmem.dev/blog/reduce-claude-cursor-ai-token-costs/ AI coding tools have moved from novelty to infrastructure in 2026. Claude, Cursor, Aider, and GitHub Copilot are now line items on engineering budgets — and for many teams, growing line items. The good news: most of that spending is recoverable waste. Studies of typical AI coding workflows show that 50%+ of tokens are spent on context rebuilding and repeated work that smarter tooling can eliminate. This guide ranks five proven techniques to cut Claude and Cursor token costs, in order of ROI. You can implement most of them in under an hour. Together, they reliably deliver a 30–50%+ reduction without sacrificing AI quality. ### 1. Stop Re-Loading Source Files Every Session (~40% savings) The single biggest token waste is your AI re-reading the same source files every chat session. A typical Claude or Cursor session burns 5,000 to 20,000 tokens just rebuilding context — file by file — that you already have in your head. The fix is to give your AI a distilled summary file it reads once per session, instead of letting it scan raw source. Tools like projectmem auto-generate a 2,000-token summary.md that captures the current state, recent decisions, and known failures. AI agents can call MCP tools like get_summary or get_issue to load only the slice they need. Setup: pip install projectmem followed by [pjm init](/guide) in your project. Wire the MCP server into Claude Desktop or Cursor config. Time: 60 seconds. Estimated savings: 70–90% of context-loading tokens. ### 2. Prevent Repeated Debugging Rounds (~25% savings) The second-biggest waste is paying for the same debugging session twice. When your AI suggests an approach you already tried and rejected, you don't just lose the suggestion tokens — you lose the implementation tokens, the broken-build debugging cycle, and the explanation of why it failed all over again. A single repeat-failure round costs roughly 3,000 tokens and 30 minutes. The fix is [pre-commit warnings](/#features) that check your project's failure history before you commit. projectmem installs a git pre-commit hook that runs pjm precheck on every commit. If you're modifying a file with previously failed approaches, you get a warning before the commit lands. ```bash $ git commit -m "switch auth to JWT" projectmem: Pre-Commit Check ──────────────────────────────────── WARN 3 failed attempts on this file Last: "JWT middleware broke session handling" (2 days ago) WARN HIGH CHURN: 5 changes in 7 commits ──────────────────────────────────── ~30 min re-debugging just saved. ``` Estimated savings: 2–5 prevented repeat-failures per developer per month = 15,000–30,000 tokens saved, plus the avoided debugging time. ### 3. Use Token-Budgeted Context Injection (~15% savings) Most AI tools load a fixed amount of context — whatever fits in CLAUDE.md, whatever the codebase indexer returns. This is inefficient when the relevant context is small. A typical bug fix only needs the failure history of one or two files, not your entire summary. The fix is dynamic, token-budgeted context that loads exactly what's relevant for the current task. projectmem's pjm wrap command pre-generates a memory block under a token cap you specify and injects it into CLAUDE.md or .cursorrules before your AI session opens. ```bash # Inject 1,500 tokens of context focused on the auth module pjm wrap claude --tokens 1500 --focus src/auth/ ``` You decide how many tokens to spend on context. Estimated savings: 50–70% reduction in context overhead on focused tasks, with no quality drop. ### 4. Use Cross-Project Memory to Skip Library Re-Learning (~10% savings) Library-specific knowledge is repeated across every project you work on. Every time you start a new FastAPI project, your AI re-learns SQLAlchemy async patterns. Every new React project, the same useEffect cleanup gotchas. This is pure waste — the lesson is the same, the cost is paid every time. The fix is cross-project memory. projectmem maintains ~/.projectmem/global/ on your machine, storing library gotchas and patterns from every project you've worked on. When you run pjm init on a new project, it detects the stack and auto-injects matching gotchas into AI_INSTRUCTIONS.md. Your AI starts every new project already aware of the library lessons from past work. ```bash # Add a library gotcha learned in your current project pjm global add-gotcha --library sqlalchemy \ "Async sessions must use 'async with' — pool leaks otherwise" # Next time you pjm init a SQLAlchemy project, # this gotcha is auto-inherited. ``` Estimated savings: 5,000–15,000 tokens per new project starting from inherited knowledge. ### 5. Switch to MCP Mode for All Tooling (~5% additional savings) The Model Context Protocol is the most token-efficient way to give AI tools memory access. Instead of loading entire markdown files at session start, MCP lets your AI call specific tools — get_summary, get_issue, precheck_file, search_events — on demand, loading only the data needed for the current question. Claude Desktop, Cursor, and Antigravity all support MCP natively in 2026. Configure once, and your AI silently uses targeted tools instead of bulk file loading. The savings compound across every session. ### How to Measure Your Own Savings If you implement all five techniques via projectmem, you can run pjm score at any time to see your actual savings — debugging hours saved, tokens prevented, estimated dollar value. The output is a letter grade from A+ to F backed by concrete numbers from your real workflow. ```text $ pjm score projectmem Prevention Score ─────────────────────────────── ==== A ==== Score: 84 / 100 ─────────────────────────────── Debugging hours saved: ~18.5h Tokens saved: 847,000 Estimated USD saved: $42.35 ``` Available as terminal output, JSON for CI dashboards, or a shields.io badge for your README. The first AI memory tool with audit-able ROI numbers. ### Frequently asked questions ### The Honest Total Combined across all five techniques, typical results land between 30% and 50%+ total token reduction depending on your workflow. Power users with heavy debugging cycles see higher savings. Light users with mostly new code see lower. The math is provable, not marketing fluff — every claim is backed by what pjm score actually measures on your project. If you spend $200/month on Claude or Cursor today, expect to spend $100–$140 after implementing these techniques. Free, MIT-licensed, runs entirely on your machine. Install in two commands and check your own savings within a week. ## What Is MCP (Model Context Protocol)? A Developer's Guide to Anthropic's Open Standard > MCP is the open protocol that lets AI tools call local servers in 2026 — and it's quietly becoming as important as HTTP for AI development. Here's what MCP is, why it matters, how it works, and how to build your first MCP server in under 30 minutes. Published 2026-05-10 · https://projectmem.dev/blog/what-is-mcp-model-context-protocol-developer-guide/ The Model Context Protocol — or MCP — has gone from a niche Anthropic announcement in late 2024 to a category-defining standard by 2026. If you build AI tools, integrate with Claude Code or Cursor, or maintain developer infrastructure that needs to talk to LLMs, you'll encounter MCP. This guide explains what MCP is, why it matters, and how to build your first [MCP server](/guide). ### What MCP Solves Before MCP, every AI tool had its own way of integrating with external data and capabilities. Claude Desktop had one mechanism. Cursor had another. ChatGPT had Custom GPTs. Aider had its own config. Integrating a single capability — say, querying a database — meant writing the same wrapper four different ways. MCP standardizes this. It defines a single protocol for how AI clients (Claude Desktop, Cursor, etc.) talk to external servers that provide tools, resources, and prompts. Build one [MCP server](/guide), expose it once, and every MCP-compatible AI tool can use it. Think of MCP as the Language Server Protocol — but for AI capabilities instead of code intelligence. ### The Three Primitives An MCP server exposes three kinds of things to AI clients: Most MCP servers focus on tools, because tools are how AI agents take action in the world. A weather MCP server exposes a get_weather tool. A database MCP server exposes query and write tools. A project memory MCP server (like projectmem's) exposes log_issue, get_summary, precheck_file, and 11 other tools. ### How MCP Communication Works MCP servers communicate with AI clients over stdio (standard input/output streams). When you launch an MCP-aware AI client, it spawns each configured MCP server as a subprocess and exchanges JSON-RPC messages with it. This is intentional: it keeps everything local, requires zero network configuration, and lets the OS handle process lifecycle and security. ```text [AI client] ──spawn──> [MCP server subprocess] ▲ ▲ │ JSON-RPC over stdio │ ▼ ▼ [Conversation] [Your code] ``` When the AI decides it needs to use a tool, it sends a tools/call message to the server. The server executes the tool and returns the result. The AI incorporates the result into its response. All of this is transparent to the user — they just see Claude or Cursor giving a better answer. ### Why MCP Matters in 2026 ### Building Your First MCP Server in Python The official Anthropic MCP SDK makes building a server trivial. Here's a minimal MCP server that exposes one tool — a 'hello' function — and runs over stdio: ```python # my_mcp_server.py from mcp.server.fastmcp import FastMCP mcp = FastMCP("my-server") @mcp.tool() def hello(name: str) -> str: """Say hello to someone.""" return f"Hello, {name}!" if __name__ == "__main__": mcp.run() ``` Install the SDK with pip install mcp. Save the script, then add it to your Claude Desktop config: ```json { "mcpServers": { "my-server": { "command": "python", "args": ["/absolute/path/to/my_mcp_server.py"] } } } ``` Restart Claude Desktop. Ask: 'Can you call my hello tool with the name Alice?' Claude will call hello(name='Alice'), receive 'Hello, Alice!', and respond accordingly. ### Real-World MCP Servers Worth Knowing By 2026, the MCP ecosystem includes dozens of production-grade servers for common developer needs: Most are open-source on GitHub. The MCP project maintains a directory of community servers at modelcontextprotocol.io. ### Common MCP Pitfalls to Avoid ### The Strategic Picture MCP is doing for AI what HTTP did for web — turning a fragmented set of vendor-specific integrations into an open standard that anyone can build on. The companies that get this early are building moats now. The developer tools that ship MCP support today are positioned to be infrastructure for the next decade. If you're building anything that touches AI workflows in 2026 — internal tools, dev tools, automation, knowledge bases — adding an MCP server should be on your roadmap. The friction is tiny. The strategic upside is significant. ### Frequently asked questions ### Where to Go Next MCP isn't just an Anthropic protocol anymore. It's the substrate the next generation of AI development is being built on. Worth learning now. ## Why Your AI Coding Assistant Keeps Suggesting Fixes That Already Failed > Claude Code, Cursor, and Aider all share the same blind spot: they don't remember the approaches you already tried that didn't work. Here's why stateless AI keeps walking into the same wall — and how a memory + judgment layer makes your AI experienced instead of just smarter. Published 2026-05-12 · https://projectmem.dev/blog/stop-ai-repeating-same-bugs/ It's 11pm. You're debugging an auth flow with Claude Code. The AI confidently suggests switching to JWT middleware. You implement it. The build breaks. You revert. Tomorrow morning, fresh session, fresh AI — and within 20 minutes it suggests the exact same JWT middleware approach that broke production yesterday. This isn't a bug in the model. It's the architecture. AI coding assistants like Claude Code, Cursor, Aider, and GitHub Copilot are stateless — each new chat session starts with zero memory of the past. They cannot remember what you already tried. They cannot warn you before re-introducing a failed approach. And they will keep paying the same debugging cost, over and over, until something tells them otherwise. ### The Real Cost of AI Amnesia Most developers underestimate how expensive stateless AI actually is. Each new session burns 5,000 to 20,000 tokens just rebuilding context that you already have in your head. Multiply that by ten sessions a day, by a team of five engineers, by twenty work days a month, and the number gets uncomfortable fast. ```text Average context rebuild per AI session: ~15,000 tokens Sessions per developer per day: ~8 Waste per developer per month: ~2.4M tokens At ~$10/M tokens (Claude Opus pricing): ~$24/month per dev For a team of 5: ~$120/month, just on amnesia. ``` And that's only the loading cost. The compounding cost is worse. Every time an AI suggests a fix you already tried, you pay for the suggestion tokens, the implementation tokens, the debugging cycle, and the explanation of why it failed. A single repeated-failure round costs roughly 3,000 tokens and 30 minutes of developer time. ### Why CLAUDE.md and .cursorrules Aren't Enough Both Claude Code and Cursor have native memory features. Claude reads CLAUDE.md at the start of every session. Cursor reads .cursorrules. These are useful for static project rules — coding style, conventions, tooling preferences. But they were never designed to capture the dynamic memory a project accumulates over time. A static rules file cannot tell your AI which three approaches to authentication already failed. It cannot warn you about the database migration that broke staging two weeks ago. It cannot carry the lesson you learned about Pydantic v2's parse_obj-to-model_validate migration across to your next FastAPI project. CLAUDE.md is the rule book. What's missing is the history book. ### The Memory + Judgment Layer projectmem is a local-first, open-source memory layer that sits above your AI coding tools. It captures every failed attempt, architectural decision, and debugging breakthrough into a structured event log. Then — and this is the killer feature — it warns you before every commit if you're about to repeat a known failure. ```bash $ git commit -m "switch auth to JWT" projectmem: Pre-Commit Check ──────────────────────────────────── src/auth/middleware.py WARN 3 failed attempts on this file Last: "JWT middleware broke session handling" (2 days ago) WARN HIGH CHURN: 5 changes in 7 commits ──────────────────────────────────── ~30 min re-debugging just saved. ``` This is what experience looks like. Not a smarter model — an experienced one. The same Claude, the same Cursor, the same Aider you already use, with one piece of infrastructure added that gives it institutional memory of your project. ### Four Layers of Auto-Capture projectmem captures meaningful project events without asking you to remember to log things. Four independent mechanisms feed the memory log: You don't need to use all four. Any one of them is enough to start building project memory. Combine them and you cover roughly 90% of meaningful events with zero conscious effort. ### Token Efficiency: Where the Savings Come From AI coding tools that read raw source files for context burn between 5,000 and 20,000 tokens per session. projectmem distills your project's memory into compact summary files — typically under 2,500 tokens total. Via the native [MCP server](/guide), your AI can call individual tools like get_summary or precheck_file to load just the slice it needs, dropping per-session cost to 800–1,500 tokens. Compounded over a month, this typically translates to 30–50%+ total AI token savings. The exact number depends on how many repeat-failure rounds projectmem prevents in your workflow. Run pjm score on your own project to see real numbers — debugging hours saved, tokens prevented, dollars protected. ### Cross-Project Memory: Lessons That Follow You Most AI memory tools scope memory to a single repo. projectmem also maintains a global memory at ~/.projectmem/global/ that follows you across every project on your machine. A library gotcha you discover in one project gets auto-injected into your next project's AI instructions when the stack matches. Library-specific knowledge — SQLAlchemy async session leaks, Pydantic v2 migration changes, React useEffect cleanup patterns — compounds across years of work. ### Frequently asked questions ### Getting Started Install in 30 seconds. Two commands. Zero configuration. ```bash pip install projectmem cd your-project pjm init ``` [pjm init](/guide) installs three git hooks, auto-starts the real-time file watcher, inherits any cross-project memory, and creates .projectmem/. Capture is active from minute one. Wire up the MCP server in Claude Desktop or Cursor and your AI starts calling tools automatically — including precheck_file, which lets the AI ask 'is this file safe to modify?' before proposing changes. 100% local. Free under MIT. No cloud, no telemetry, no accounts. Your code, your memory, your machine. Stop paying for AI to relearn what you already know. ## Comparing the Top 5 AI Memory Tools for Developers in 2026: projectmem, claude-mem, Graphify, mem0, and Cursor > AI memory tools exploded in 2026. Five projects now compete to give Claude Code, Cursor, and Aider persistent project context. We built one of them — and we'll show you honestly which tool wins on which dimension, with no marketing fluff. Published 2026-05-08 · https://projectmem.dev/blog/best-ai-memory-tools-comparison-2026/ Twelve months ago, 'AI memory for coding' was a niche idea. In 2026, it's a category. Five serious tools now compete to give Claude Code, Cursor, Aider, and the rest of your AI coding stack persistent project context. We built one of them — projectmem — and this post is the honest, no-fluff comparison we wish existed when we started. We'll cover each tool's core focus, what it does well, what it doesn't do, and which kind of developer should pick which. No competitor will be portrayed as bad. They're all open-source projects (or open-core) doing genuinely interesting work. ### The Five Tools ### Feature Comparison Matrix ### projectmem — Memory + Judgment Best for: developers who want [pre-commit warnings](/#features) that prevent repeated failures, plus cross-project memory that compounds across years of work. projectmem is the only tool in this list that combines memory with predictive judgment. It captures every failed approach, decision, and gotcha into an append-only event log. Then it warns you before every commit if you're about to re-introduce a known bad change. A real-time file watcher detects debugging churn. A native [MCP server](/guide) with 15 tools lets Claude Desktop, Cursor, and Aider call get_summary, precheck_file, get_score, and 11 other capabilities directly. The pjm score command outputs a letter grade with debugging hours saved, tokens prevented, and dollars protected — the only AI memory tool with quantifiable, audit-able ROI. Limitations: projectmem doesn't build a deep graph of your code structure (Graphify wins on that). It doesn't do output token compression (Caveman wins on that). It's only as smart as the events it captures. ### claude-mem — Session Capture + Compression Best for: developers who want every Claude Code session preserved as searchable history without manual logging. claude-mem records what happens during AI coding sessions, AI-compresses the result, and injects relevant context back into future sessions. It's a clean, focused implementation with a working local server, semantic search via Chroma vector DB, and a friendly web viewer. It works across Claude Code, Codex, Gemini, Hermes, and Copilot. Limitations: claude-mem captures raw session transcripts. It doesn't classify events into structured types (failures vs. decisions vs. fixes). It doesn't warn you before commits. It doesn't have cross-project memory beyond filtering. It's storage, not judgment. ### Graphify — Code Structure as a Graph Best for: developers working on large codebases who need their AI to understand structural relationships between files, modules, and dependencies. Graphify uses tree-sitter to parse 29 languages and builds a queryable knowledge graph of your code. Files, functions, classes, and their relationships become nodes and edges. AI agents can query the graph instead of reading raw source. The project claims roughly 70x token reduction on large codebases. Open-source under MIT, with a commercial enterprise layer called Penpax in development. Limitations: Graphify maps what exists, not what happened. It doesn't track failed attempts, decisions, or debugging history. The graph is regenerated periodically — it's a static snapshot, not a temporal log. ### mem0 — Cloud Agent Memory Best for: teams building AI agent applications where memory needs to be shared across users, devices, and services. mem0 is the most mature platform on this list, with a well-funded team and clean SDK across multiple languages. It scopes broader than coding — agent memory in general, for chatbots, support agents, and personalization. The vector-database-backed retrieval is solid. Limitations: mem0 is cloud-first. Your project's memory leaves your machine. There's a paid SaaS tier above the open-source baseline. For developers who care deeply about local-first principles or have privacy/compliance constraints, this is a non-starter. For coding-specific features like pre-commit warnings or git auto-capture, it's not the design intent. ### Cursor — AI-First IDE with Built-In Memory Best for: developers who want a complete AI-first editor experience and don't want to assemble tools themselves. Cursor is the dominant paid AI editor. It has built-in memory features, .cursorrules support, codebase indexing, and tight integration between editor and AI. If you're already paying for Cursor, you have some level of memory included. Limitations: Cursor is closed-source, paid ($20/mo), and vendor-locked. Its memory features are tied to the Cursor editor — you can't use them in Aider, Claude Desktop, or any other tool. Its memory is also bounded by what Cursor's product roadmap prioritizes. It cannot do pre-commit warnings the way projectmem can because it doesn't operate at the git layer. ### Which Should You Choose? ### Frequently asked questions ### Honest Take: They're Complementary These tools mostly don't compete head-on. Graphify gives your AI a spatial map (what exists). projectmem gives it a temporal log (what happened). claude-mem captures raw session content. mem0 handles cross-service agent memory. Cursor wraps everything in a paid IDE. The smart developer probably uses two or three of them — Graphify for structural understanding, projectmem for failure prevention, claude-mem for session replay. The category is young. None of these tools is perfect. All of them are improving rapidly. If you're evaluating AI memory tools in 2026, install two and pick the one that gives you the bigger weekly 'aha' moment. For us, that moment is when projectmem warns you, before you commit, that you've already tried this exact approach twice and it failed both times. Once you experience that, it's hard to imagine working without it. ## projectmem v0.0.6 Released: Adding Judgment to AI Memory > Today we shipped v0.0.6 — the biggest release since projectmem launched. Pre-commit failure warnings, real-time file watcher, prevention score, cross-project memory inheritance, smart context injection, and 14 native MCP tools. Save up to 50%+ of AI tokens with zero configuration. Published 2026-05-12 · https://projectmem.dev/blog/projectmem-v006-intelligence-layer-release/ Today we're releasing projectmem v0.0.6 — the largest update since the project launched. This release transforms projectmem from a passive memory logger into an active intelligence layer that captures events automatically, warns developers before they repeat known failures, injects token-budgeted context into AI sessions, and proves its own ROI with a quantifiable letter grade. Everything still runs entirely on your machine. No cloud. No telemetry. No accounts. MIT licensed and free forever. Two commands to install: pip install projectmem followed by [pjm init](/guide). ### What's New in v0.0.6 The headline of this release is the intelligence layer — six new capabilities that turn raw memory storage into proactive judgment. Each one is opt-in or auto-enabled depending on what makes sense for your workflow. #### 1. Pre-Commit Failure Warnings (pjm precheck) This is the feature we're most excited about. Run [pjm init](/guide) and a pre-commit hook is automatically installed. From that moment on, every git commit triggers a check against your project's memory. If you're modifying a file with a known failed approach, an unresolved issue, or high churn, projectmem warns you before the commit lands. ```bash $ git commit -m "switch auth to JWT" projectmem: Pre-Commit Check ──────────────────────────────────── src/auth/middleware.py WARN 3 failed attempts on this file Last: "JWT middleware broke session handling" (2 days ago) WARN HIGH CHURN: 5 changes in 7 commits ──────────────────────────────────── ~30 min re-debugging just saved. ``` No other AI memory tool does this because it requires the memory layer underneath. You can also run pjm precheck manually at any time, or set the strictness with --level info, --level warn (default), or --level block. #### 2. Real-Time File Watcher (pjm watch) A new background daemon detects rapid edits to the same file — 4+ changes within a 10-minute window — and auto-logs them as churn events. This catches debugging sessions that never make it to commit. Battery-aware, gitignore-aware, and auto-started by pjm init on interactive terminals. Skip it in CI/CD automatically. Stop anytime with pjm watch --stop. ```bash $ pjm watch --status ● running · PID 23489 · uptime 1h 23m Logs: .projectmem/watch.log Stop: pjm watch --stop ``` #### 3. Smart Context Injection (pjm wrap) pjm wrap launches your AI agent through projectmem. Before the session opens, it injects a token-budgeted context block containing the most relevant warnings, recent decisions, and file gotchas. Works with Claude Code, Cursor (writes to .cursorrules), Aider, and clipboard-paste for everything else. Your AI starts experienced, not blank. ```bash $ pjm wrap claude --tokens 2000 ## projectmem context (2000 tokens) ### WARNINGS — Do Not Repeat - FAILED: JWT middleware broke sessions - FAILED: SameSite cookie redirect loop ### Recent Decisions - Cookie-based auth until v2 migration ### File Gotchas - auth/middleware.py: HIGH CHURN ✓ Injected into CLAUDE.md. Launching agent... ``` #### 4. Prevention Score (pjm score) Every AI tool claims to save you time. projectmem proves it. pjm score outputs a letter grade from A+ to F with concrete numbers — failed approaches on record, decisions documented, debugging hours saved, tokens prevented, dollars protected. Available as terminal output, JSON for CI dashboards, or a shields.io badge for your README. ```text $ pjm score projectmem Prevention Score ─────────────────────────────── ==== A ==== Score: 84 / 100 ─────────────────────────────── Failed approaches on record: 23 Decisions documented: 41 Debugging hours saved: ~18.5h Tokens saved: 847,000 Estimated USD saved: $42.35 ``` #### 5. Cross-Project Memory (pjm global) Knowledge that follows you across every project. ~/.projectmem/global/ stores patterns, library-specific gotchas, and stack preferences. When you run pjm init on a new project, projectmem detects the stack (Python, TypeScript, Rust, Go, Java) and auto-inherits any matching gotchas into AI_INSTRUCTIONS.md. Library lessons from one project apply to every future project that uses the same library. #### 6. MCP Server Expansion (8 → 15 tools) The native Model Context Protocol server now exposes 15 tools to AI agents — up from 8. The six new tools turn memory into proactive judgment: Configure once in claude_desktop_config.json or Cursor settings and your AI calls these tools automatically. The most valuable is precheck_file — your AI can ask 'is this file safe to modify?' before suggesting a change, and decide on its own to avoid the known failed approach. ### Zero-Touch Setup The biggest UX change is that pjm init now does everything in a single command. Git hooks installed automatically. Real-time watcher auto-started. Global memory inherited based on detected stack. Last 20 git commits auto-backfilled as classified events. From pip install to active memory in two commands. ```bash pip install projectmem cd your-project pjm init # Done. Capture is active. Watcher is running. # Pre-commit warnings will fire on your next git commit. ``` Opt-out flags exist for every automation: --no-hooks, --no-watch, --no-global, --no-backfill. Use them on sensitive repos or in CI environments. ### Token Efficiency v0.0.6 is where the marketed token savings actually land. Combined across the four access modes, typical AI sessions drop from 5,000–20,000 tokens (baseline) to 800–1,500 tokens (MCP mode). Plus the compounding savings from prevented repeat-failures. Empirically: up to 50%+ savings on power-user workflows. ### Visualization Dashboard Refresh pjm visualize now opens a four-tab D3.js dashboard with: a Story Map showing failure heatmaps, an ROI Dashboard with animated counters and capture-source breakdown, a Project Map with toggleable Tree (dendrogram) and Graph (force-directed) views, and an enhanced Timeline that distinguishes auto-captured from manually-logged events. All running locally in your browser, no cloud calls. ### Privacy and Security We added SECURITY.md with the full threat model, plus a Privacy & Security section in the user guide that explains the team-memory-via-git pattern, prompt-injection considerations, and the uninstall path. By default, projectmem commits the distilled summary files (so teammates inherit memory via git clone) and gitignores the raw event log. For sensitive repos, add .projectmem/ to your .gitignore for total privacy. ### Upgrade Path v0.0.6 is fully backward compatible. Existing events.jsonl files work without modification. The new auto_captured fields are optional additions. The watchdog dependency is now required (added ~70KB to install size — small price for the real-time watcher). ```bash pip install --upgrade projectmem # Reinstall git hooks to get the new pre-commit warning hook cd your-project pjm hooks install # Verify pjm watch --status ``` ### Frequently asked questions ### What's Next v0.0.7 will focus on three things: semantic search across the event log using local embeddings (sentence-transformers + sqlite-vec), a VS Code extension that surfaces warnings inline as you code, and diff-aware pre-commit checks that compare staged changes against the content of known-failed approaches, not just the file path. If you try projectmem v0.0.6 and find it useful, the single most helpful thing you can do is star the GitHub repo and share it with one other developer. We don't need money. We need adoption. Every star helps the project survive and grow. Install in 30 seconds. Save up to 50%+ of AI tokens. Stop repeating yesterday's bug. Free, MIT, on your machine. Welcome to projectmem v0.0.6. ## Coding Agent Memory for Claude Code: Setup Guide (2026) > How to give Claude Code persistent coding agent memory with projectmem: install, initialise, connect — then every issue, attempt, fix and decision is remembered across sessions, 100% locally. Published 2026-08-26 · https://projectmem.dev/blog/coding-agent-memory-for-claude-code/ ### Does Claude Code have persistent memory? Yes. As of 2026, [Claude Code](https://github.com/anthropics/claude-code) ships two native memory systems, documented in the [official memory docs](https://code.claude.com/docs/en/memory). **CLAUDE.md files** are instructions you write, loaded at the start of every session, at four scopes: managed policy (organization-wide), user (~/.claude/CLAUDE.md), project (./CLAUDE.md or ./.claude/CLAUDE.md, shared via version control), and personal-per-project (CLAUDE.local.md). They support @path imports and path-scoped rules in .claude/rules/. **Auto memory**, on by default, is notes Claude writes for itself: each git repository gets a directory at ~/.claude/projects//memory/ with a MEMORY.md index (the first 200 lines or 25KB load into every session) plus topic files read on demand. That is genuinely the strongest native memory of any terminal coding agent — and it still leaves a specific gap. The gap is *engineering history*. Anthropic's docs say auto memory deliberately skips things like debugging fixes, and it is machine-local — your desktop's accumulated notes do not exist on your laptop, and nothing in it is typed or queryable. CLAUDE.md is prose you maintain by hand, with no structured record of which fix attempts failed, which decisions were superseded, or which library gotchas bit you in another repo. That is the layer projectmem adds: an append-only events.jsonl of typed events (issue, attempt with worked/failed/partial outcomes, fix, decision, note) living in .projectmem/ inside the repo itself, so it travels with git clone. The design is described in the [Memory-as-Governance paper](https://arxiv.org/abs/2606.12329). ### What Claude Code remembers natively vs. with projectmem Be clear about when you do *not* need projectmem: if you are one developer, on one machine, using only Claude Code, its native CLAUDE.md-plus-auto-memory combination covers most of what a memory layer is for, and adding another tool is overhead. projectmem earns its place when memory has to be typed and queryable, committed to the repo, shared with teammates, or portable to a second agent — the [full comparison of open-source options](/blog/ai-memory-for-coding-agents-compared) walks through the alternatives honestly. ### Set up coding agent memory for Claude Code Three steps, roughly five minutes. This is the condensed version of our [longer walkthrough on giving Claude Code persistent memory](/blog/how-to-give-claude-code-persistent-memory). Requirements: Python 3.10+, a git repository. #### Step 1: Install projectmem and initialize the repo ```bash pip install projectmem cd /path/to/your-repo pjm init ``` pjm init creates .projectmem/, installs git hooks (a pre-commit warning plus post-commit auto-capture), writes the CLAUDE.md bridge block automatically so Claude Code knows the memory tools exist, backfills the last 20 commits, and — this is the part that saves you the most fiddling — prints a ready MCP config with the absolute python path and --root already filled in. To confirm the install, run pip show projectmem (there is no pjm --version). #### Step 2: Register the MCP server with Claude Code projectmem's MCP server is a local stdio subprocess — if MCP is new to you, our [developer guide to the Model Context Protocol](/blog/what-is-mcp-model-context-protocol-developer-guide) covers the model. Claude Code offers two equivalent registration routes. The one-liner uses claude mcp add with --scope project, which writes a .mcp.json at the project root you can commit for your team: ```bash claude mcp add projectmem --scope project -- \ /opt/anaconda3/bin/python -m projectmem.mcp_server --root /path/to/your-repo ``` Or paste the block that pjm init printed into .mcp.json at the repo root yourself: ```json { "mcpServers": { "projectmem": { "command": "/opt/anaconda3/bin/python", "args": [ "-m", "projectmem.mcp_server", "--root", "/path/to/your-repo" ] } } } ``` Two details matter. Use the **absolute path to python** (run which python to find yours) — MCP host subprocesses do not reliably inherit your shell PATH. And pass the project root via **--root, not the cwd field**: some MCP hosts, including Claude Desktop and Cursor, silently ignore cwd, and the --root flag works everywhere. After any config change, restart cold — quit the app fully (Cmd+Q on macOS), don't just reload. #### Step 3: Verify the loop end-to-end ```bash pjm brief # what the agent will see pjm score # memory health, graded A+ through F ``` Then start a Claude Code session and ask it to call get_summary. From here the loop runs itself: Claude Code reads context through tools like get_context, search_events, and precheck_file, and logs its own work with log_issue, record_attempt, record_fix, add_decision, and add_note — 15 tools in total. The post-commit hook captures commits automatically, and pjm precheck (snoozable with --snooze 2h) warns before you re-attempt something that already failed. No cloud, no account, no telemetry. On cost: selective loading over MCP means the agent pulls only the events it needs instead of a monolithic context dump — the same principle behind our guide to [reducing Claude and Cursor token costs](/blog/reduce-claude-cursor-ai-token-costs). > **Claude Code gotchas.** (1) There is no pjm --version — verify the install with pip show projectmem. (2) MCP servers only initialize on a cold start; after editing .mcp.json, fully quit and reopen. (3) Keep --root in the config even though Claude Code launches in your repo — the server subprocess's working directory is not guaranteed, and the flag is honored everywhere. (4) Don't hand-edit .projectmem/summary.md or PROJECT_MAP.md; they are regenerated from events.jsonl, so write through the MCP tools or pjm commands. (5) Native auto memory stays on and coexists fine — Claude Code keeps its personal notes in ~/.claude/projects//memory/ while projectmem holds the shared, typed record in the repo. ### Frequently asked questions Claude Code is the coding agent where a memory layer has the least to prove — Anthropic's native CLAUDE.md and auto memory already carry real context between sessions. What projectmem adds is the part no prose file captures: a typed, append-only record of what was tried, what failed, and what was decided, committed to the repo and served identically to every agent you use. The [source is on GitHub](https://github.com/riponcm/projectmem) under MIT, the [research behind it is on arXiv](https://arxiv.org/abs/2606.12329), and the [guide](/guide) covers everything this page compressed. If it doesn't fit your workflow, the native features documented above will still take you a long way. ## Coding Agent Memory for Cursor: Setup Guide (2026) > How to give Cursor persistent coding agent memory with projectmem: install, initialise, connect — then every issue, attempt, fix and decision is remembered across sessions, 100% locally. Published 2026-08-26 · https://projectmem.dev/blog/coding-agent-memory-for-cursor/ ### Does Cursor have persistent memory? Partially. As of 2026 Cursor ships two native persistence mechanisms. **Rules** are instruction files the agent loads into context: project rules live as .mdc files in .cursor/rules/ and are version-controlled, and Cursor also reads a plain-markdown AGENTS.md (including nested ones per subdirectory) as a simpler alternative — both documented in the [official Rules docs](https://cursor.com/docs/context/rules). The old single .cursorrules file in the project root still works but is legacy. **Memories** are sentence-sized facts ("this repo uses pnpm") that a background model proposes during chats and you approve; they are per-project, stored in your Cursor settings rather than the repo, and invisible to teammates. What neither mechanism gives you is a *record of work*. Rules and Memories hold instructions and preferences; they do not capture that yesterday's agent tried three fixes for a flaky test, two failed, one worked, and the second failure was for a subtle reason. Each new Cursor chat starts from the same static instructions, so agents happily re-attempt approaches that already failed. That gap — episodic, structured, queryable memory — is what a dedicated memory layer adds, and it is the axis on which the [full comparison of open-source options](/blog/ai-memory-for-coding-agents-compared) evaluates tools. ### What Cursor remembers natively vs. with projectmem To be plain about where projectmem is *not* the answer: if your pain is style conventions or "always use our lint config," Cursor Rules alone solve that, versioned and reviewable, with zero extra moving parts. projectmem earns its place when the same repository is worked on across many sessions (or many teammates' agents) and repeated debugging, forgotten decisions, or re-explained architecture are costing you real time and tokens. ### Set up coding agent memory for Cursor #### Step 1: Install projectmem and initialize the repo ```bash pip install projectmem # Python 3.10+ cd /path/to/your/repo pjm init ``` pjm init creates .projectmem/ inside the repo, installs git hooks (a pre-commit warning plus post-commit auto-capture), backfills memory from your last 20 commits, and — most usefully here — prints a ready-to-paste MCP config with the absolute Python path and --root already filled in. Note there is no pjm --version; verify the install with pip show projectmem. #### Step 2: Add the server to .cursor/mcp.json Cursor reads project-level MCP servers from /.cursor/mcp.json (and global ones from ~/.cursor/mcp.json), per the [official MCP docs](https://cursor.com/docs/context/mcp). Paste the block pjm init printed; it looks like this: ```json { "mcpServers": { "projectmem": { "command": "/opt/anaconda3/bin/python", "args": [ "-m", "projectmem.mcp_server", "--root", "/absolute/path/to/your/project" ] } } } ``` The --root flag is **mandatory on Cursor**: in our testing Cursor ignores the cwd field entirely, so a server that relies on its working directory will read the wrong project or none at all. The server is a plain stdio subprocess — no port, no cloud, no account. If MCP itself is new to you, the [developer guide to Model Context Protocol](/blog/what-is-mcp-model-context-protocol-developer-guide) covers what actually happens on that stdio pipe. #### Step 3: Fully quit Cursor, reopen, and verify ```bash # after Cmd+Q and reopening Cursor: pjm brief # what the agent will see pjm score # memory health, A+ through F ``` Cursor only initializes MCP servers on a cold start — a window reload is not enough, so fully quit (Cmd+Q on macOS) and reopen. You should then see projectmem's 15 tools (get_summary, precheck_file, record_attempt, search_events, and the rest) under the server in Cursor's MCP settings. Ask the agent to "call get_summary" as a smoke test. Optionally run pjm export --cursor to also mirror the distilled summary into a rules file, so the very first prompt of every chat carries context even before a tool call — the [step-by-step guide](/guide) covers this and the wrap mode (pjm wrap cursor) for terminal use. On token cost: selective MCP loading means the agent pulls only the slice of memory it needs instead of re-reading the repo each session. These are projectmem's own measurements on a mid-sized repository, not an independent benchmark — the methodology is in the [token-cost writeup](/blog/reduce-claude-cursor-ai-token-costs): > **Cursor-specific gotchas.** (1) Cursor ignores the cwd field in mcp.json — always pass --root with an absolute path, or the server silently points at the wrong directory. (2) Config changes need a full quit (Cmd+Q), not a window reload. (3) A root-level .cursorrules file is legacy; put generated rules in .cursor/rules/ or AGENTS.md. (4) Cursor Memories are per-machine and unversioned — never rely on them for anything a teammate's agent needs to know. (5) There is no pjm --version; use pip show projectmem. ### Frequently asked questions The same event log travels with the repo, so a teammate on a different agent gets identical memory — the [Claude Code setup](/blog/coding-agent-memory-for-claude-code) uses the very same .projectmem/ directory with a different config file. The design is described in the [Memory-as-Governance paper](https://arxiv.org/abs/2606.12329); the code, issues, and 0.2.0 release notes are on [GitHub](https://github.com/riponcm/projectmem), and you can watch the precheck-warning flow end-to-end in the [two-minute demo](/demo). ## Coding Agent Memory for Codex: Setup Guide (2026) > How to give Codex persistent coding agent memory with projectmem: install, initialise, connect — then every issue, attempt, fix and decision is remembered across sessions, 100% locally. Published 2026-08-26 · https://projectmem.dev/blog/coding-agent-memory-for-codex/ ### Does Codex have persistent memory? Yes — partially, and in two distinct layers. [Codex](https://github.com/openai/codex), OpenAI's open-source coding agent for the terminal, reads **AGENTS.md** files before doing any work: it merges a global file in ~/.codex/ with files from your git root down to the current directory, concatenated in order so the closest file wins, capped at 32 KiB combined by default (project_doc_max_bytes). Separately, an opt-in **Memories** feature — off by default, enabled with [features] memories = true in config.toml or via the desktop app's Personalization settings — summarizes eligible past sessions into markdown files under ~/.codex/memories/. Both are documented in the [official Codex docs](https://developers.openai.com/codex). What neither layer gives you is a *structured, per-repository engineering record*. AGENTS.md is prose you maintain by hand. Memories are auto-generated summaries, global to your machine rather than scoped to a repo, and the docs note they may not update right away when a chat ends and can pause when you're near your rate limit. Neither distinguishes a failed fix attempt from a successful one, and neither travels with the repo to a teammate's machine (Memories are local; AGENTS.md does travel if you commit it, but only as unstructured text). That gap — the agent re-attempting a fix it already tried last Tuesday — is what a dedicated memory layer addresses, for Codex and for [Claude Code](/blog/coding-agent-memory-for-claude-code), [Cursor](/blog/coding-agent-memory-for-cursor), and the rest. ### What Codex remembers natively vs. with projectmem The two systems are complementary, not competing. AGENTS.md remains the right place for standing instructions; [projectmem](https://github.com/riponcm/projectmem) adds the event history underneath it, following the append-only, governance-first design described in the [Memory-as-Governance paper](https://arxiv.org/abs/2606.12329). To be clear about when you *don't* need this: if you work solo, the repo is small, and what you want remembered is preferences and conventions, Codex's own AGENTS.md plus Memories may be entirely sufficient — enable Memories and stop there. projectmem earns its keep when debugging history matters, when several people (or several agents) touch the same repo, or when you want one memory store shared across Codex and other tools. The [full comparison of open-source memory options](/blog/ai-memory-for-coding-agents-compared) covers the alternatives honestly. ### Set up coding agent memory for Codex projectmem connects to Codex over MCP — if you're new to the protocol, here's [what MCP is and how it works](/blog/what-is-mcp-model-context-protocol-developer-guide). Codex has first-class MCP support via [mcp_servers] tables in its config file. Total setup time is a few minutes. #### Step 1: Install and initialize projectmem projectmem needs Python 3.10+. Install it, then run pjm init from the repository you want Codex to remember. ```bash pip install projectmem # requires Python 3.10+ cd /path/to/your/repo pjm init ``` pjm init creates the .projectmem/ directory, installs git hooks (a pre-commit warning plus post-commit auto-capture), backfills memory from your last 20 commits, and — the part that matters here — **prints a ready-to-paste MCP server config** with the absolute Python path and --root already filled in. Keep that output on screen for Step 2. To confirm the install, use pip show projectmem; there is no pjm --version command. #### Step 2: Register the server in ~/.codex/config.toml Codex configures MCP servers in **TOML**, not the JSON format most MCP clients use — so translate the config pjm init printed rather than pasting it verbatim. Add an [mcp_servers.projectmem] table to ~/.codex/config.toml (or a project-scoped .codex/config.toml in the repo). In our testing, set **both** --root in the args and the cwd key to the repo's absolute path — belt and suspenders that keeps the server pointed at the right repo regardless of where Codex is launched. ```toml # ~/.codex/config.toml — TOML, not JSON. # Copy the command and args from the block `pjm init` printed. [mcp_servers.projectmem] command = "/absolute/path/to/your/python" args = ["", "--root", "/absolute/path/to/your/repo"] cwd = "/absolute/path/to/your/repo" ``` If you prefer not to edit the file by hand, Codex also accepts codex mcp add projectmem -- , and codex mcp list shows what's registered. Either way, this is a config-file workflow — don't go hunting for a settings UI panel; editing the file *is* the supported path. #### Step 3: Verify the memory loop end-to-end Start a Codex session and ask it to call get_instructions, then get_summary. Codex spawns MCP servers lazily — on the first tool call, not at startup — so a clean launch does not prove the config is right; the first successful tool call does. One behavioral note from our own testing: at low reasoning effort, Codex tends to skip the get_instructions bootstrap call, so keep reasoning effort at medium or higher for memory-dependent work. Then check the loop from the CLI side: ```bash # confirm the install (no `pjm --version` exists) pip show projectmem # what the agent sees at session start pjm brief # health of the memory itself, graded A+ through F pjm score ``` From here, Codex logs issues, attempts, fixes, and decisions as it works, and pjm precheck warns before it touches a file with known history. The [quickstart guide](/guide) covers the full command set, including pjm dashboard and pjm export. ### What this costs in tokens These are projectmem's own measurements on a mid-sized repository, not an independent benchmark — the [token-cost breakdown](/blog/reduce-claude-cursor-ai-token-costs) explains the methodology and its limits. > **Codex-specific gotchas.** (1) The config is **TOML, not JSON** — pasting a JSON MCP block into config.toml fails. (2) Set both --root and cwd; relying on either alone is fragile. (3) Servers spawn **lazily** — a broken path won't error until the first tool call, mid-session. (4) Low reasoning effort tends to skip the get_instructions bootstrap; use medium or higher. (5) Codex Memories and projectmem are independent stores — enabling one does not populate the other. (6) Verify installs with pip show projectmem; pjm --version does not exist. ### Frequently asked questions Codex already has better native memory than most coding agents — layered AGENTS.md plus opt-in Memories is a genuinely useful baseline. What projectmem adds is the part neither layer attempts: a governed, typed history of what actually happened in the repo. If you run more than one agent, the same .projectmem/ store serves them all — see the [Claude Code setup](/blog/coding-agent-memory-for-claude-code), skim the [FAQ](/faq), or start with the [guide](/guide) and pjm init. ## Coding Agent Memory for GLM: Setup Guide (2026) > How to give GLM persistent coding agent memory with projectmem: install, initialise, connect — then every issue, attempt, fix and decision is remembered across sessions, 100% locally. Published 2026-08-26 · https://projectmem.dev/blog/coding-agent-memory-for-glm/ ### Does GLM have persistent memory? No. GLM — Zhipu AI / Z.AI's model family, whose current coding models are documented at [docs.z.ai](https://docs.z.ai/devpack/tool/claude) — is a stateless model like every other LLM: once a session ends, everything the model learned about your repository is gone. Memory, when it exists, lives in the *client* around the model, not in GLM itself. And that is exactly why GLM is an interesting case. Z.AI's GLM Coding Plan exposes an Anthropic-compatible API endpoint (https://api.z.ai/api/anthropic), so the most common way to run GLM for coding is inside Claude Code with two environment variables changed. Whatever memory machinery the client supports — CLAUDE.md files, MCP servers — keeps working when GLM is the model answering. A memory layer built for Claude Code therefore works for GLM without modification. That client-side memory is still thin out of the box. Claude Code reads CLAUDE.md at session start, but nothing writes back what happened: which bug you found, which fix failed twice, which architectural decision you made and later reversed. An agent without that record happily re-attempts last week's failed approach. This is the gap [projectmem](https://github.com/riponcm/projectmem) fills — a local, append-only event log with typed events (issue, attempt with worked/failed/partial outcomes, fix, decision, note) stored in .projectmem/ inside your repo, distilled into a summary the agent actually reads. The design is described in the [Memory-as-Governance paper](https://arxiv.org/abs/2606.12329). ### What GLM remembers natively vs. with projectmem To be clear about scope: projectmem is repo-level *project* memory. If what you want is conversational memory ("remember I prefer tabs"), a hosted team knowledge base, or memory for one-off API scripts that never touch a git repo, projectmem is not the right tool — the [comparison of open-source memory options](/blog/ai-memory-for-coding-agents-compared) covers alternatives honestly. ### Set up coding agent memory for GLM The setup below assumes the most common GLM coding configuration: Claude Code pointed at Z.AI's Anthropic-compatible endpoint, as documented in [Z.AI's own guide](https://docs.z.ai/devpack/tool/claude). If you use GLM through another client, skip to the universal-mode note at the end of Step 3. #### Step 1: Point Claude Code at the GLM endpoint Z.AI's docs configure Claude Code with an auth token and a base URL override (plus optional model-mapping variables such as ANTHROPIC_DEFAULT_SONNET_MODEL). With your Z.AI API key: ```bash export ANTHROPIC_AUTH_TOKEN="your-z-ai-api-key" export ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic" claude # Claude Code now runs against GLM ``` Everything client-side is unchanged: slash commands, CLAUDE.md loading, and MCP servers all still work, because those are handled by Claude Code, not by the model. This is the whole trick — the memory layer never needs to know GLM is on the other end. #### Step 2: Install projectmem and initialize the repo ```bash pip install projectmem # Python 3.10+ cd your-repo pjm init ``` pjm init creates .projectmem/, installs the git hooks, backfills memory from your last 20 commits, and writes a bridge block into CLAUDE.md — which Claude Code loads at every session start, GLM or not. It also prints a ready-to-paste MCP config with the absolute Python path and --root already filled in. Note there is no pjm --version; verify the install with pip show projectmem. #### Step 3: Wire up the MCP server and verify Add the config that pjm init printed to your client. It is a local stdio subprocess exposing 15 tools (get_summary, search_events, precheck_file, record_attempt, add_decision, and so on — see the [MCP primer](/blog/what-is-mcp-model-context-protocol-developer-guide) if MCP is new to you). The shape looks like: ```json { "mcpServers": { "projectmem": { "command": "/absolute/path/to/python", "args": ["-m", "projectmem.mcp", "--root", "/absolute/path/to/your-repo"] } } } ``` Use the exact block pjm init printed rather than retyping this — the --root flag matters because some clients (Claude Desktop, Cursor) ignore the config's cwd field. Then start a session and ask the agent what it knows about the project; it should answer from get_summary rather than re-scanning files. Outside sessions, pjm brief shows what the agent will see, pjm score grades memory health from A+ to F, and pjm dashboard gives an overview. If you run GLM through a client with no MCP support at all, use universal mode instead: pjm export --claude-md (or --cursor) writes memory into the file your client reads, pjm wrap generic pre-injects context into a command, and pjm context --tokens N emits a budget-capped context block you can paste anywhere. The [Claude Code memory guide](/blog/how-to-give-claude-code-persistent-memory) walks through the same flow in more depth, and the general [setup guide](/guide) covers other clients. These are projectmem's own measurements, not an independent benchmark — but the shape matters more than the exact numbers, especially on a metered plan; the [token-cost breakdown](/blog/reduce-claude-cursor-ai-token-costs) explains where the savings come from. > GLM-specific gotchas: (1) MCP tool *calls* are made by the model, so how eagerly memory tools get used depends on the GLM model you mapped in — if it under-calls them, pjm export --claude-md guarantees the summary is in context regardless. (2) After changing MCP config in Claude Desktop, a cold restart (Cmd+Q, not just closing the window) is required. (3) Z.AI's model-mapping env vars decide which GLM model answers each tier; a mapping typo fails at the API, not in projectmem. (4) Stale memories are flagged against git history, never auto-deleted — retire one explicitly with pjm decision "..." --supersedes . ### Frequently asked questions GLM's endpoint-swap story makes it one of the easiest models to give real memory to: the client does the remembering, and projectmem does the recording. Start with pjm init, check the [guide](/guide) for client-specific details, browse the [live demo](/demo), or compare this setup against the field in the [open-source memory comparison](/blog/ai-memory-for-coding-agents-compared). The code is MIT-licensed at [github.com/riponcm/projectmem](https://github.com/riponcm/projectmem), and the design rationale is in the [Memory-as-Governance paper](https://arxiv.org/abs/2606.12329). ## Coding Agent Memory for Grok Build: Setup Guide (2026) > How to give Grok Build — xAI's terminal coding agent — persistent coding agent memory with projectmem: install, initialise, connect. Every issue, attempt, fix and decision remembered across sessions, 100% locally. Published 2026-08-26 · https://projectmem.dev/blog/coding-agent-memory-for-grok-build/ ### Does Grok Build have persistent memory? Yes — with an asterisk. Grok Build, SpaceXAI's open-source terminal coding agent ([xai-org/grok-build](https://github.com/xai-org/grok-build), Apache-2.0), includes a native cross-session memory feature, but its [own documentation](https://docs.x.ai/build/overview) marks it experimental and it ships disabled. Enable it with GROK_MEMORY=1 or a [memory] section in ~/.grok/config.toml, and Grok stores a global MEMORY.md, a per-workspace MEMORY.md, and per-session logs under ~/.grok/memory/, indexed by SQLite full-text search with optional vector search when an embedding model is configured. The automatic part of that memory is deliberately thin. When a session ends, Grok saves a metadata summary — message counts, the first few substantive prompts as topics, a timestamp — built without an LLM call. The docs are explicit that it does *not* record tool usage, file paths, or shell commands. Richer capture of decisions, debugging workflows, and API discoveries requires you to remember to run /flush before compaction discards the conversation. The structural gaps matter more than the thinness. Everything lives in your home directory, so nothing reaches teammates or CI, and nothing is versioned with the code. The files are freeform Markdown, so a failed migration attempt and a settled architectural decision look identical to search. And nothing ties a memory to git history, so notes go quietly stale. Those are exactly the gaps a dedicated memory layer covers — the [comparison of open-source memory options](/blog/ai-memory-for-coding-agents-compared) walks through how different tools handle each one. ### What Grok Build remembers natively vs with projectmem Both columns below describe documented behavior: the left from Grok Build's in-repo user guide (August 2026), the right from projectmem 0.2.0. projectmem ([MIT, on GitHub](https://github.com/riponcm/projectmem)) treats memory as an append-only event log with types — issues, attempts marked worked/failed/partial, fixes, supersedable decisions, notes — distilled into summary.md, PROJECT_MAP.md, and plan.md. A cross-project store in ~/.projectmem/global/ holds stack-tagged library gotchas. The design rationale is written up in the [Memory-as-Governance paper](https://arxiv.org/abs/2606.12329). ### Set up coding agent memory for Grok Build Grok Build's MCP support is standard stdio: it spawns the server as a local subprocess and speaks JSON-RPC over stdin/stdout — the [same protocol every other MCP client uses](/blog/what-is-mcp-model-context-protocol-developer-guide). projectmem's server is verified end-to-end on Claude Desktop, Cursor, Antigravity, and Codex, and the identical config applies here. Budget about five minutes. You need Python 3.10 or newer. #### Step 1: Install projectmem and initialize the repo ```bash pip install projectmem cd /path/to/your/repo pjm init pip show projectmem # verify the install — there is no `pjm --version` ``` pjm init creates .projectmem/, installs two git hooks (a pre-commit warning and post-commit auto-capture), backfills memory from your last 20 commits, and writes a bridge block into CLAUDE.md. That last part is a happy accident for Grok users: Grok Build's project-rules loader reads CLAUDE.md and AGENTS.md natively at every directory level, so the instructions telling the agent to consult memory load automatically at session start with zero extra configuration. pjm init also prints a ready-to-use MCP config with the absolute Python path and the --root flag already filled in — keep that output for Step 2. #### Step 2: Register the MCP server with Grok Build Grok Build configures MCP servers in TOML, not the JSON that Claude-style clients use, so either register through the CLI or translate the printed config by hand. The CLI route — everything after -- is passed to the server command: ```bash # Substitute the Python path and args exactly as `pjm init` printed them grok mcp add projectmem -- # By default this writes to ~/.grok/config.toml (user scope). # Add --scope project to write a committable .grok/config.toml instead. ``` ```toml # Equivalent hand-written entry in ~/.grok/config.toml [mcp_servers.projectmem] command = "/abs/path/to/python" # the interpreter path pjm init printed args = ["", "--root", "/abs/path/to/your/repo"] ``` Keep every path absolute, including --root. Claude Desktop and Cursor ignore the config's cwd field, which is why projectmem requires the flag in the first place — and since the Grok TUI can be launched from any directory, the same discipline applies here. #### Step 3: Verify the wiring and start a session ```bash grok mcp list # projectmem should appear grok mcp doctor projectmem # config + connectivity check grok # start a session ``` grok mcp doctor is Grok Build's built-in diagnostic and will catch a wrong interpreter path before you waste a session on it. Then open a session and ask the agent to call get_summary — thanks to the bridge block it should already know to run get_instructions, get_summary, and get_project_map at session start. Outside the TUI, pjm brief prints the same briefing for humans, pjm score grades memory health from A+ to F, and pjm dashboard shows the event stream; the [setup guide](/guide) covers the full command surface. One number worth being clear-eyed about: selective loading over MCP is what keeps a memory layer cheaper than pasting a full summary into every prompt. The figures below are projectmem's own measurements on a mid-sized repository, not an independent benchmark — the [token-cost breakdown](/blog/reduce-claude-cursor-ai-token-costs) explains the methodology. > Grok Build gotchas: **(1)** Grok's config is TOML — pjm init prints a JSON snippet for Claude-style clients, so use grok mcp add rather than pasting it verbatim. **(2)** In compatibility mode Grok Build also discovers MCP servers from .mcp.json, Claude, and Cursor configs, so if you already wired projectmem for another agent it may appear twice in grok mcp list — disable one copy. **(3)** Grok's native memory directory is shared across clones and worktrees of the same origin remote, while .projectmem/ is per-checkout and branch-versioned; with parallel sub-agents working in separate worktrees, events logged on a branch reach the shared store when that branch merges. **(4)** projectmem never deletes stale entries — it flags them against git history; retire one deliberately with pjm decision "..." --supersedes . ### Frequently asked questions Grok Build is one of the better-positioned agents for external memory: MCP is first-class, CLAUDE.md loads natively, and the experimental built-in layer shows the team takes the problem seriously. If its personal Markdown store covers your needs, use it — it is zero-install. When you want memory that is typed, git-anchored, and shared across your team and your other agents, projectmem is [MIT-licensed on GitHub](https://github.com/riponcm/projectmem); watch the [two-minute demo](/demo) or start with pip install projectmem. ## Coding Agent Memory for Qwen: Setup Guide (2026) > How to give Qwen persistent coding agent memory with projectmem: install, initialise, connect — then every issue, attempt, fix and decision is remembered across sessions, 100% locally. Published 2026-08-26 · https://projectmem.dev/blog/coding-agent-memory-for-qwen/ ### Does Qwen have persistent memory? Partially — and more than most coding agents. [Qwen Code](https://github.com/QwenLM/qwen-code), the terminal agent from the Qwen team (27k+ GitHub stars, built for the [Qwen3-Coder](https://github.com/QwenLM/Qwen3-Coder) model line), ships two memory mechanisms. First, **QWEN.md**: instruction files it loads every session, at three scopes — ~/.qwen/QWEN.md for you globally, QWEN.md in the project root for your team, and .qwen/QWEN.local.md for personal per-project notes. It also reads AGENTS.md if your repo already has one, and a /init command can generate a starter file from your codebase. Second, **auto-memory**: after conversations, Qwen Code quietly saves preferences and context it learned about you, without you writing anything. What neither mechanism gives you is a durable, structured history of the *project*. Qwen Code's own docs are direct about the constraint: every session starts with a fresh context window. QWEN.md holds what you remembered to write down; auto-memory holds what the agent inferred about your preferences. Neither records that the retry-logic fix from three weeks ago failed twice before the third approach worked, or that a decision about the database layer was superseded last month. That project-level, typed history is the gap projectmem fills — the same gap covered for every agent in our [comparison of open-source memory options](/blog/ai-memory-for-coding-agents-compared). ### What Qwen Code remembers natively vs. with projectmem These are complements, not competitors. QWEN.md is the right place for standing instructions ("always use pnpm"); projectmem is the right place for accumulated evidence about the codebase. Everything in the native column below comes from Qwen Code's [official documentation](https://qwenlm.github.io/qwen-code-docs/en/users/overview). ### Set up coding agent memory for Qwen There are two routes, and Qwen makes both realistic. Qwen Code has first-class MCP support, so the full 15-tool interface works in the CLI. And because Qwen3-Coder is genuinely runnable locally — the qwen3-coder tags on Ollama are among the most-pulled local coding models — projectmem's plain-text mode covers setups where no MCP client is in the loop at all. #### Step 1: Install projectmem and initialize your repo ```bash pip install projectmem # Python 3.10+, current version 0.2.0 cd /path/to/your-repo pjm init ``` pjm init creates .projectmem/, installs the git hooks, backfills memory from your last 20 commits, and — the part that matters here — **prints a ready-to-paste MCP config** with the absolute Python path and --root already filled in. Copy that output; you need it in Step 2. To confirm the install, use pip show projectmem (there is no pjm --version). #### Step 2: Register the MCP server in Qwen Code Qwen Code loads MCP servers from the mcpServers block in its settings.json (project scope: .qwen/settings.json), or via the qwen mcp add command with the default stdio transport. Paste the exact command and args that pjm init printed — projectmem's server is a stdio subprocess, and the --root flag matters because several clients ignore the config's working-directory field. If MCP is new to you, our [developer guide to the Model Context Protocol](/blog/what-is-mcp-model-context-protocol-developer-guide) covers how these stdio servers work. ```json { "mcpServers": { "projectmem": { "command": "", "args": ["", "--root", "/absolute/path/to/your-repo"] } } } ``` Restart Qwen Code in the same project after editing the config, then run /mcp inside the CLI to confirm the server is connected and its tools are listed. One honesty note: projectmem's MCP server is verified end-to-end on Claude Desktop, Cursor, Antigravity, and Codex. Qwen Code speaks the same stdio MCP protocol and documents this exact configuration path, but it is not yet on our formally verified list — if you hit an edge case, the [GitHub issues](https://github.com/riponcm/projectmem) are open. #### Step 3: Wire the plain-text route for local Qwen models If you run Qwen3-Coder locally through Ollama behind a client with no MCP support, use universal mode instead. The simplest wiring uses a documented Qwen Code feature: QWEN.md can import other files with @path references, and projectmem maintains a distilled summary.md that is regenerated from the event log. ```bash # Option A — reference the living summary from QWEN.md (add this line to QWEN.md): # Project memory: @.projectmem/summary.md # Option B — print a budgeted brief and paste it into any prompt or rules file: pjm brief pjm context --tokens 1500 # Option C — wrap a CLI that has no rules-file convention: pjm wrap generic -- ``` Option A means every Qwen Code session loads current project memory with zero extra tooling — useful when you want memory but not the MCP subprocess. For other local setups around Ollama, the same universal-mode pattern applies; the [OpenCode guide](/blog/coding-agent-memory-for-opencode) walks through a popular Qwen3-Coder-on-Ollama pairing in detail. These are our own measurements, not an independent benchmark — but the shape holds for local models too, where a smaller context spend means more room for actual code; the [token-cost breakdown](/blog/reduce-claude-cursor-ai-token-costs) explains the methodology. > **Qwen-specific gotchas.** (1) Qwen Code's npm install requires Node.js 22+. (2) Ollama's default context window is small — raise it, or a pasted memory brief plus your code may get truncated silently. (3) .qwen/QWEN.local.md is *not* auto-gitignored; add it to .gitignore yourself, and note some projects deliberately commit .qwen/settings.json — keep absolute paths out of the committed copy. (4) After any mcpServers change, fully restart Qwen Code in the same project. (5) Qwen Code's auto-memory and projectmem both write memory — that's fine, they don't conflict, but retire stale projectmem decisions explicitly with pjm decision "..." --supersedes rather than expecting either system to delete them. ### Frequently asked questions If your projects are small and your conventions fit in a page, Qwen Code's native QWEN.md plus auto-memory may honestly be enough — start there. When the history outgrows what you can curate by hand, projectmem adds the typed, git-aware layer: the [setup guide](/guide) covers every client in one place, the [live demo](/demo) shows the event log in action, and the design rationale is in the [Memory-as-Governance paper](https://arxiv.org/abs/2606.12329). The code is MIT-licensed at [github.com/riponcm/projectmem](https://github.com/riponcm/projectmem). ## Coding Agent Memory for OpenCode: Setup Guide (2026) > How to give OpenCode persistent coding agent memory with projectmem: install, initialise, connect — then every issue, attempt, fix and decision is remembered across sessions, 100% locally. Published 2026-08-26 · https://projectmem.dev/blog/coding-agent-memory-for-opencode/ ### Does OpenCode have persistent memory? Partially — and the distinction matters. [OpenCode](https://github.com/anomalyco/opencode), the open-source terminal coding agent (formerly sst/opencode, now under anomalyco/opencode, with over 200,000 GitHub stars at the time of writing), persists **session transcripts** locally. You can resume the last session with opencode --continue, jump to a specific one with --session , fork with --fork, list and delete sessions with opencode session list and opencode session delete, and export a session as JSON or share it as a public link. That is better session persistence than most coding agents ship. What OpenCode does *not* have is persistent **knowledge**: a structured record of what was tried, what failed, what was fixed, and what was decided — queryable across sessions without replaying an entire conversation. A transcript is a recording; memory is what you learned from it. If yesterday's session spent forty minutes discovering that a migration breaks under SQLite but not Postgres, today's fresh session knows none of that unless you resume that exact session — dragging its full token weight along — or rediscover it. This gap applies to every agent in this class; the [full comparison of open-source memory options](/blog/ai-memory-for-coding-agents-compared) covers how different tools attack it. projectmem's approach, described in the [Memory-as-Governance paper](https://arxiv.org/abs/2606.12329), is typed events rather than transcripts: issue, attempt (worked/failed/partial), fix, decision, and note records appended to events.jsonl inside .projectmem/ in your repo, distilled into a summary.md, PROJECT_MAP.md, and plan.md the agent can load selectively. ### What OpenCode remembers natively vs. with projectmem OpenCode also loads instruction files: it reads AGENTS.md at the project root (or globally at ~/.config/opencode/AGENTS.md), falls back to CLAUDE.md when no AGENTS.md exists, and accepts extra files via the instructions field in opencode.json. That is static, hand-maintained context — useful, but it does not update itself when a fix lands. Here is how the pieces line up, based on OpenCode's documented behavior: To be fair about where each tool wins: if your need is picking up this afternoon exactly where you left off this morning, OpenCode's built-in --continue is the right tool and projectmem adds nothing. projectmem earns its keep across *many* sessions on the same codebase — when the question is not "what were we just saying?" but "has anyone hit this before, and what actually worked?" On a throwaway script, skip both. ### Set up coding agent memory for OpenCode OpenCode supports local (stdio) MCP servers configured in opencode.json — the same protocol projectmem speaks, verified end-to-end on Claude Desktop, Cursor, Antigravity, and Codex. (New to the protocol? See the [MCP developer guide](/blog/what-is-mcp-model-context-protocol-developer-guide).) You need Python 3.10+ and OpenCode installed. #### Step 1: Install projectmem and initialize your repo ```bash pip install projectmem cd /path/to/your/repo pjm init ``` pjm init creates .projectmem/, installs git hooks (a pre-commit warning and post-commit auto-capture), backfills memory from your last 20 commits, writes a CLAUDE.md bridge block, and prints a ready-to-paste MCP config with the absolute Python path and --root already filled in. To confirm the install, use pip show projectmem — there is no pjm --version command. #### Step 2: Add projectmem to opencode.json The snippet pjm init prints uses the mcpServers format that Claude Desktop and Cursor expect. OpenCode's format is different: an mcp key with the command as a **single array**, not separate command and args fields. Translate it like this, in your project's opencode.json (or the global config): ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "projectmem": { "type": "local", "command": [ "/absolute/path/to/python", "-m", "projectmem.mcp_server", "--root", "/absolute/path/to/your/repo" ], "enabled": true } } } ``` Copy the Python path and --root value verbatim from what pjm init printed — the absolute interpreter path avoids the PATH issues stdio subprocesses commonly hit, and --root pins the server to your repo regardless of the working directory the client launches it from. #### Step 3: Restart OpenCode and verify the tools ```bash opencode # then ask the agent: # "Call get_summary from projectmem and tell me what this project remembers." ``` Restart OpenCode after editing the config so it re-reads opencode.json and spawns the server. If get_summary returns your project's distilled memory, the 15 tools — get_context, precheck_file, search_events, log_issue, record_fix, add_decision, and the rest — are live. From the terminal, pjm brief, pjm score, and pjm dashboard give you the human view of the same data; the [guide](/guide) walks through the full command set. These are projectmem's own measurements, not an independent benchmark — but the shape holds for OpenCode specifically, because OpenCode's own documentation warns that MCP servers "add to your context" and can consume tokens quickly. Selective loading is the answer: the agent calls get_context or precheck_file for the task at hand instead of front-loading everything. There is more on this trade-off in [reducing AI token costs](/blog/reduce-claude-cursor-ai-token-costs). > **OpenCode-specific gotchas.** (1) Config shape: OpenCode wants "mcp" with a single command array — pasting the mcpServers block from pjm init unmodified will not work. (2) Rules precedence: OpenCode reads CLAUDE.md only as a *fallback* when no AGENTS.md exists. If your repo has an AGENTS.md, the bridge block pjm init wrote into CLAUDE.md is ignored — copy it into AGENTS.md, or point OpenCode at it via the instructions field in opencode.json. (3) Sessions are not memory: --continue reloads an entire transcript's context; on long sessions that is far more expensive than a get_summary call in a fresh session. (4) If you disable the server temporarily, use "enabled": false rather than deleting the entry. One more design note worth knowing before you rely on any memory tool: projectmem never deletes. Stale memories are flagged against git history, and outdated decisions are retired with pjm decision "..." --supersedes , leaving the audit trail intact. Everything lives in your repo and ~/.projectmem/global/ — no cloud, no account, no telemetry — so git log and cat .projectmem/events.jsonl will always show you exactly what your agent knows. ### Frequently asked questions OpenCode already solved the part most agents get wrong — sessions that survive a restart. What it leaves open is the part transcripts cannot solve: turning forty minutes of debugging into three lines any future session can query in one tool call. That is what [projectmem](https://github.com/riponcm/projectmem) adds, in about five minutes of setup. Questions the article did not cover are probably in the [FAQ](/faq); the [demo](/demo) shows the whole loop end to end. ## Coding Agent Memory for Hermes: Setup Guide (2026) > How to give Hermes persistent coding agent memory with projectmem: install, initialise, connect — then every issue, attempt, fix and decision is remembered across sessions, 100% locally. Published 2026-08-26 · https://projectmem.dev/blog/coding-agent-memory-for-hermes/ ### Does Hermes have persistent memory? Yes — and that makes Hermes unusual. [Hermes Agent](https://github.com/NousResearch/hermes-agent), the open-source agent from Nous Research (MIT-licensed, Python, over 230,000 GitHub stars as of August 2026), runs as a persistent daemon and ships persistent memory as a headline feature: FTS5 full-text recall over past conversations enhanced by LLM summarization, agent-curated memory with periodic nudges, Honcho-based user modeling that deepens across sessions, and skills — procedural memory the agent creates itself and improves during use. So the question for Hermes is not *whether* it remembers, but *what* it remembers and *where* that memory lives. Hermes' native memory is agent-scoped and user-scoped: it lives under ~/.hermes/ (the session store is state.db), it models *you*, and it recalls *conversations*. It is not repo-scoped: there is no structured record inside the repository of which fix attempts failed, which architectural decisions were made and later superseded, or which files have a history of regressions. That memory evaporates the moment the work moves to another machine, another teammate, or another agent — a colleague opening the same repo in Claude Code or Cursor sees none of it. That repo-scoped layer is what projectmem adds, and because it attaches at the [MCP](/blog/what-is-mcp-model-context-protocol-developer-guide) client layer, the same .projectmem/ directory serves Hermes, [Claude Code](/blog/coding-agent-memory-for-claude-code), Cursor, and Codex interchangeably. ### What Hermes remembers natively vs. with projectmem To be clear about where projectmem is *not* the answer: if you are a solo developer who lives entirely inside Hermes, its native memory plus skills may already cover you — Hermes genuinely is the strongest native-memory agent in the [open-source comparison](/blog/ai-memory-for-coding-agents-compared). projectmem earns its place when the unit of memory should be the *project* rather than the *user*: multiple agents on one repo, multiple people on one repo, or engineering history you want reviewable and versioned in git rather than curated inside an agent's private database. ### Set up coding agent memory for Hermes projectmem's MCP server is a plain stdio subprocess, and Hermes has first-class stdio MCP support via the mcp_servers block in ~/.hermes/config.yaml. One honesty note: projectmem is verified end-to-end on Claude Desktop, Cursor, Antigravity, and Codex; Hermes is not yet on that formally verified list, but it speaks the same standard stdio transport, so the wiring below is the documented path on both sides. #### Step 1: Install projectmem and initialize your repo ```bash pip install projectmem # Python 3.10+ cd /path/to/your/repo pjm init # verify the install (there is no `pjm --version`) pip show projectmem ``` pjm init creates .projectmem/, installs git hooks (a pre-commit warning plus post-commit auto-capture), writes the CLAUDE.md bridge block, backfills memory from your last 20 commits, and — the part you need next — prints a ready-to-paste MCP config with the absolute Python path and --root already filled in. #### Step 2: Add the server to ~/.hermes/config.yaml pjm init prints its config in the JSON mcpServers shape used by Claude Desktop and Cursor: ```json { "mcpServers": { "projectmem": { "command": "/usr/local/bin/python3", "args": [ "-m", "projectmem.mcp_server", "--root", "/absolute/path/to/your/repo" ] } } } ``` Hermes reads the equivalent YAML from ~/.hermes/config.yaml under mcp_servers — the Hermes docs note that mcpServers snippets map over directly. The translation (this block is YAML): ```bash # ~/.hermes/config.yaml mcp_servers: projectmem: command: "/usr/local/bin/python3" # use the absolute path pjm init printed args: - "-m" - "projectmem.mcp_server" - "--root" - "/absolute/path/to/your/repo" ``` Keep --root absolute. Hermes does interpolate a documented ${workspaceFolder} variable, but it resolves to the session's terminal cwd — the same ambiguity that makes --root mandatory for Claude Desktop and Cursor in the first place. An explicit path fails loudly instead of silently pointing memory at the wrong directory. #### Step 3: Reload and verify Unlike Claude Desktop, Hermes does not need a cold restart: it auto-reloads MCP connections when ~/.hermes/config.yaml changes (with a 30-second timeout). Then confirm the loop works end to end: ```bash # ask Hermes in a session: # "Call projectmem's get_summary and tell me what this project's state is." # then check from the CLI that memory is accumulating: pjm brief pjm score # grades your memory hygiene A+ through F ``` Hermes now has all 15 projectmem tools — reads like get_summary, get_plan, precheck_file, and search_events, and writes like log_issue, record_attempt, record_fix, and add_decision. If 15 tools is more surface than you want in Hermes' tool roster, its per-server tools.include filter (a documented Hermes config key) can whitelist just the ones you use. These are projectmem's own measurements, not an independent benchmark — the same caveat applies as in our [token-cost breakdown](/blog/reduce-claude-cursor-ai-token-costs) — but the MCP mode's selective loading is why bolting memory on does not have to mean stuffing the context window. > **Hermes-specific gotchas.** (1) Editing ~/.hermes/config.yaml from *inside* a running Hermes session triggers auto-reload with only a 30s window — edit from a separate terminal if the reload seems flaky. (2) You now have two memory layers; they do not conflict (projectmem's store is just files in the repo), but tell Hermes in its instructions to prefer projectmem tools for *repo* facts so engineering history lands in the shared, typed log instead of only its private state.db. (3) Stale projectmem entries are flagged against git history, never auto-deleted — retire an outdated decision explicitly with pjm decision "..." --supersedes . (4) There is no pjm --version; use pip show projectmem. ### Frequently asked questions Hermes already answered the question most agents fail: it remembers. projectmem answers the follow-up: it makes the *project's* memory a first-class, versioned artifact that survives a switch of agent, machine, or teammate. The code is MIT-licensed on [GitHub](https://github.com/riponcm/projectmem), the design is written up in the [Memory-as-Governance paper](https://arxiv.org/abs/2606.12329), there's a [live demo](/demo), and the [FAQ](/faq) covers the edge cases — no cloud, no account, no telemetry involved. ## Coding Agent Memory for DeepSeek: Setup Guide (2026) > How to give DeepSeek persistent coding agent memory with projectmem: install, initialise, connect — then every issue, attempt, fix and decision is remembered across sessions, 100% locally. Published 2026-08-26 · https://projectmem.dev/blog/coding-agent-memory-for-deepseek/ ### Does DeepSeek have persistent memory? No. DeepSeek is a model provider, not an agent, so the memory question splits in two — and both halves come up empty. The [DeepSeek API](https://api-docs.deepseek.com/quick_start/pricing/) is stateless like every LLM API: it sees exactly the tokens you send in each request and retains nothing between calls. And the harnesses people run DeepSeek models in — Aider, Cline, and other OpenAI-compatible CLIs — keep context only for the duration of a session. Close the terminal and the agent forgets the bug it just spent an hour on, the fix that finally worked, and the two approaches that didn't. DeepSeek does offer one thing that looks memory-adjacent: context caching, with a discounted cache-hit input price for repeated prompt prefixes. That is a cost optimization, not memory — the cached prefix still has to be assembled and sent by your harness, and nothing about it survives a model's forgetting. It pairs well with a memory layer (a stable project brief is exactly the kind of prefix that caches), but it cannot substitute for one. The economics make this sting less than it should. DeepSeek's appeal has always been price — it is the default budget pick in Aider and Cline, the same niche [Qwen's coder models](/blog/coding-agent-memory-for-qwen) compete in — so re-explaining your architecture every morning feels almost free. But cheap tokens do not make repetition cheap. When the agent re-attempts a workaround it already tried and failed last Tuesday, the tokens cost cents; the debugging round costs you the afternoon. The expensive resource was never the API bill. ### What DeepSeek agents remember natively vs. with projectmem The design behind the right-hand column — append-only typed events (issue, attempt, fix, decision, note) in .projectmem/events.jsonl, distilled into summary.md, PROJECT_MAP.md, and plan.md — is described in the [Memory-as-Governance paper](https://arxiv.org/abs/2606.12329). The append-only part matters more than it sounds: a memory system that silently edits or deletes its own past is a memory system you cannot audit. ### Set up coding agent memory for DeepSeek #### Step 1: Install projectmem and initialize your repo projectmem needs Python 3.10+. Initialize inside the repository your DeepSeek agent works on — the memory lives in the repo, version-controllable alongside the code. ```bash pip install projectmem cd your-repo pjm init # verify the install — note: there is no `pjm --version` pip show projectmem ``` pjm init creates .projectmem/, installs git hooks (a pre-commit warning plus post-commit auto-capture), writes a CLAUDE.md bridge block, backfills memory from your last 20 commits, and prints a ready-to-paste MCP config with the absolute Python path and --root already filled in. The [guide](/guide) walks through each piece if you want to know what landed where. #### Step 2: Launch your DeepSeek agent with memory pre-injected For Aider — the most common DeepSeek harness — projectmem has a first-class path: pjm wrap aider launches Aider with the project's memory brief pre-injected, so the model starts every session already knowing the codebase's history. Your existing DeepSeek configuration (API key, model selection) is untouched; the wrapper only changes what context Aider starts with. ```bash export DEEPSEEK_API_KEY=your-key # configure Aider for DeepSeek as you already do pjm wrap aider # Aider, with memory pre-injected pjm context --tokens 1500 # optionally cap the injected brief's token budget ``` Pre-injection is the right mode here because most DeepSeek harnesses speak plain OpenAI-compatible chat, not [MCP](/blog/what-is-mcp-model-context-protocol-developer-guide). If you also use an MCP-capable client on the same repo — projectmem's 15 MCP tools are verified end-to-end on Claude Desktop, Cursor, Antigravity, and Codex — paste the config that pjm init printed. Two sharp edges: --root is required because Claude Desktop and Cursor ignore the cwd field, and config changes need a cold restart (Cmd+Q), not a window reload. #### Step 3: Close the loop as you work Memory only compounds if outcomes get recorded. The git hooks capture commits automatically; the commands below cover the rest of the loop. ```bash pjm brief # what the agent will be told at session start pjm precheck src/api.py # known issues in a file before the agent touches it pjm score # A+..F health grade for the memory itself pjm search "timeout" # find past events pjm decision "use httpx, not requests" --supersedes a1b2c3 # retire a stale decision ``` Stale entries are flagged against git history rather than deleted — when memory and code disagree, you see the conflict instead of silently losing one side. Superseded decisions stay in the log with their replacement linked. On cost: the figures below are projectmem's own measurements on a mid-sized repository, not an independent benchmark, and the [token-cost breakdown](/blog/reduce-claude-cursor-ai-token-costs) explains the methodology. > **DeepSeek-specific gotchas.** The model lineup moves fast: V3.1 (Aug 2025), V3.2 (Dec 2025), and the V4 line (deepseek-v4-pro, deepseek-v4-flash, GA Aug 2026) shipped within a year, and older API aliases have been retired along the way — pin the exact model name in your harness config and record the choice with pjm decision, so a silent model swap is a visible event rather than a mystery regression. Also resist letting cheap cache-hit pricing justify resending your whole history every turn: cached tokens still bill and still fill the context window. A distilled brief beats a raw transcript at any price. ### Frequently asked questions If DeepSeek's economics are why you are here, be honest about where a memory layer is *not* the answer: one-off scripts, throwaway repos, and greenfield prototypes have no history worth remembering, and projectmem adds nothing there. It earns its keep on codebases you return to — where the model that costs the least per token is also the one you can least afford to have relearning your project daily. For how this approach compares to conventions files, vector stores, and other tools, see the [full comparison of open-source options](/blog/ai-memory-for-coding-agents-compared), watch the [two-minute demo](/demo), or start from the [source on GitHub](https://github.com/riponcm/projectmem). ## Coding Agent Memory for Kimi: Setup Guide (2026) > How to give Kimi persistent coding agent memory with projectmem: install, initialise, connect — then every issue, attempt, fix and decision is remembered across sessions, 100% locally. Published 2026-08-26 · https://projectmem.dev/blog/coding-agent-memory-for-kimi/ ### Does Kimi have persistent memory? No — Kimi has no persistent project memory. Within a session, the K2 models hold context like any modern coding agent, and [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) injects your repo's AGENTS.md into the system prompt at startup, so static instructions do carry over. But that is configuration, not memory: when a session ends, the debugging you did — the three approaches that failed before the fourth worked, the reason you pinned a dependency — is gone. Kimi CLI stores sessions locally (they even migrate automatically to its successor, Kimi Code CLI), but a saved transcript is not structured knowledge; the next session starts from zero unless you re-explain. There is a second wrinkle that makes Kimi's memory situation unusual: Moonshot ships an **Anthropic-compatible API** at api.moonshot.ai/anthropic, so many people run K2 inside Claude-Code-style clients by pointing ANTHROPIC_BASE_URL at it — a documented, widely used setup. That means "memory for Kimi" often really means "memory for whatever client is hosting K2 today," and next month that client may be hosting a different model. A memory layer bolted to one vendor's account breaks the moment you switch. projectmem sidesteps this by keeping memory in .projectmem/ **inside the repo** — plain files, committed to git, readable by any MCP-capable agent. Swap K2 for Claude mid-project (our [Claude Code setup guide](/blog/coding-agent-memory-for-claude-code) covers that side) and the new model inherits every logged issue and decision. To be clear about where projectmem is *not* the answer: it needs an agent with tool access or at least a file it reads, so it does nothing for Kimi's plain web chat. And for a throwaway script or a repo you touch once, a hand-written AGENTS.md is simpler and enough. The [full comparison of open-source options](/blog/ai-memory-for-coding-agents-compared) is honest about the alternatives if you want to weigh them first. ### What Kimi remembers natively vs. with projectmem Everything in the left columns below is documented Kimi CLI behavior; the right column is what the memory layer adds via its 15 MCP tools (if MCP itself is new to you, start with [what MCP actually is](/blog/what-is-mcp-model-context-protocol-developer-guide)). ### Set up coding agent memory for Kimi Three steps, five minutes, entirely local. Python 3.10+ is the only requirement. #### Step 1: Install projectmem and initialize the repo ```bash pip install projectmem cd /path/to/your/repo pjm init ``` pjm init creates .projectmem/, installs git hooks (a pre-commit warning plus post-commit auto-capture), backfills memory from your last 20 commits, and — the part you need next — **prints a ready-to-paste MCP config** with the absolute Python path and the --root flag already filled in. Note there is no pjm --version; confirm the install with pip show projectmem. #### Step 2: Register the MCP server with Kimi CLI Kimi CLI manages MCP servers through the kimi mcp sub-command group and supports stdio servers, which is exactly what projectmem is. Take the command and arguments exactly as pjm init printed them and register them: ```bash # Substitute the command and args exactly as `pjm init` printed them, # including --root /absolute/path/to/your/repo kimi mcp add --transport stdio projectmem -- kimi mcp list # confirm "projectmem" appears ``` Kimi CLI also accepts an ad-hoc config file in the standard mcpServers JSON format via kimi --mcp-config-file /path/to/mcp.json, so the block pjm init prints drops in unmodified. If you instead run K2 **inside Claude Code** through the Anthropic-compatible endpoint, register that same printed block in the client's own MCP config — --root is still required there, because Claude-Code-style clients ignore the cwd field — and fully restart the client (Cmd+Q) after any config change. #### Step 3: Bridge the instructions into AGENTS.md and verify pjm init writes its bridge block for CLAUDE.md, but Kimi reads AGENTS.md. The block is plain markdown, so export it and paste it there — that is what tells the agent to consult memory before working: ```bash pjm export --claude-md # prints the bridge block — paste it into AGENTS.md pjm brief # preview exactly what the agent will see pjm score # memory health, graded A+ through F ``` Then start a session and ask Kimi to call get_summary. If it returns your project's distilled state instead of an error, the loop is closed: from now on the agent can call log_issue, record_attempt, record_fix, and add_decision as it works, and precheck_file before editing files with known history. The token effect is measurable, though the numbers below are projectmem's own — treat them as a vendor's measurement, not a benchmark, and see the [token-cost breakdown](/blog/reduce-claude-cursor-ai-token-costs) for how they were taken. > **Kimi-specific gotchas.** (1) Kimi CLI is being succeeded by **Kimi Code CLI** — Moonshot says installing it migrates your configuration and sessions automatically, but run kimi mcp list afterwards to confirm the projectmem registration survived. (2) Kimi's built-in subagents (explore, plan, coder) run in fully independent context windows and cannot see the main conversation — knowledge that only lives in the chat is invisible to them, which is precisely why persisting it to .projectmem/ matters. (3) When K2 runs behind ANTHROPIC_BASE_URL in a Claude-Code-style client, MCP config edits need a cold restart, not a reload. ### Frequently asked questions Kimi's strongest trait — running the same K2 models through whichever client fits, thanks to the Anthropic-compatible API — is exactly the trait that punishes vendor-locked memory. Keeping project knowledge in the repo makes it as portable as the code. The [step-by-step guide](/guide) covers every client in more depth, the [live demo](/demo) shows the event log in action, and the source, MIT-licensed, is at [github.com/riponcm/projectmem](https://github.com/riponcm/projectmem) — the design rationale is written up in the [Memory-as-Governance paper](https://arxiv.org/abs/2606.12329).