projectmind

projectmind

Persistent, compact project memory for AI coding agents. Your agent reads one small digest instead of re-scanning the codebase every session — and a local ledger shows you exactly how many tokens (and dollars) that saved.

-success)

Every AI coding session starts the same way: the agent has no memory of your project, so it re-reads files, re-derives your architecture, or asks you to re-explain decisions you made months ago. You pay for that in tokens, time, and wrong guesses — every single session, on every machine, for every teammate.

projectmind fixes this with a structured, persistent project map (.projectmind/map.json): your modules, their dependencies, your architectural decisions, your conventions, your domain glossary. The agent reads a ~400-token digest first, drills into single nodes only when needed, and writes back what it learns — so the *next* session (yours, a teammate's, or a different AI tool's) starts already knowing the project.

The digest scales with your project's *conceptual* size (modules, decisions), not its *byte* size — so the savings grow with the repo.

Quick start — one command

npm install -g @nodemint/projectmind

cd your-repo projectmind init

That single init does everything: scaffolds the map, seeds it from your repo layout, detects which AI agents are installed on your machine and wires each one (MCP server + a rules file carrying the live map), adds .projectmind/ to your .gitignore (the map stays local — nothing to push), and installs the git hook that keeps the map fresh on every commit.

Then the one step no tool can do for you: restart your agent (or start a new chat session). AI agents load their config and rules files at session start — a chat that was already open keeps its old context, and every session after that has the map automatically. Using the VS Code savings extension? Cmd+Shift+P → *"Developer: Reload Window"* once.

Want it available in every future project without even running `init`?

projectmind setup --global        # registers the MCP server once, user-wide

(projectmind init --bare scaffolds only, and projectmind setup re-wires agents on demand, if you prefer the pieces separately.)

See what it saves you — measured, not promised

The MCP server keeps a local savings ledger: every time your agent reads the map instead of scanning files, it records the tokens actually served vs. the estimated tokens of the files the agent would have read instead.

Check it anytime:

$ projectmind savings

projectmind savings (estimated — local ledger, never leaves this machine)

Total saved: ~20.5k tokens across 22 map read(s) ≈ $0.0614 at sonnet-tier input pricing ($3/MTok, as of 2026-06) Today: ~20.5k tokens (22 read(s))

By tool: mind_digest 12 reads ~18.5k saved mind_query 6 reads ~1210 saved mind_context 4 reads ~712 saved

Methodology: tokens ≈ ceil(bytes/4); baseline = files the agent would have read instead.

The dollar figure needs zero configuration: it defaults to Sonnet-tier input pricing from a built-in table of published rates (Haiku $1 / Sonnet $3 / Opus $5 / Fable $10 per MTok input, as of June 2026), and says exactly which assumption it used. If you run a different model, set savings.model (or an exact savings.inputPricePerMTok) in .projectmind/config.json — but nobody has to.

*(Real output from a scripted day of agent work on the sample project in test/fixtures/ — 12 session starts, 6 module drill-ins, 4 task-context reads. Reproduce the per-session number with npm run benchmark.)*

VS Code status bar: the integrations/vscode extension shows a live ✦ ~20.5k tokens saved counter that reads the same local ledger. Zero dependencies, zero network.

The ledger is honest by design: every number is labelled an estimate (ceil(bytes ÷ 4), the rough English+code average), savings are floored at zero, and the file is gitignored — it's your private data, on your machine, deletable at any time.

One deliberate gap, stated plainly: the ledger only counts *tool calls* (mind_digest, mind_query, mind_context). The embedded digest described below never requires a tool call — that's the whole point — so its savings don't show up as a number here. projectmind savings names which rules files carry it instead of inventing a token count we can't actually observe.

Session handoff — pick up exactly where you left off

The thing every agent session loses is *working state*: what you were in the middle of, what's next, the gotcha you just discovered. Code graphs can't capture it; chat history dies with the session. projectmind carries it over:

$ projectmind digest

shopflow-api — project map

Order-management HTTP API with JWT auth, backed by PostgreSQL. Stack: node, express, postgres

⏪ Handoff from last session (2026-07-02)

Adding refund support to orders-route; next: write the refund tests

Your agent calls mind_handoff before the session ends (or before its context gets compacted); the note leads the very next digest, so the next session — tonight on your laptop, tomorrow on your desktop, or a different AI tool entirely — resumes in one read instead of re-deriving the task. Notes live in your gitignored local overlay: personal working state, never committed, cleared with mind_handoff({clear: true}) when done. Humans can use it too: projectmind handoff "note".

Works everywhere your team works

No language assumptions, no platform assumptions: the full test suite (85 tests, including the git-hook end-to-end and offline-guarantee tests) runs in CI on Linux, macOS, and Windows × Node 18/20/22. Paths, globs, atomic renames, and the installed git hook are exercised on all three. The map format is plain JSON — nothing OS-specific is ever written to your repo.

Verified against real open-source repos (fresh clone → projectmind init --seed, 2026-07-02):

That's the core scaling property in the wild: the digest tracks a project's *conceptual* size, staying ~100 tokens whether the repo is 150k or 500k tokens. (A freshly seeded digest is a starter skeleton — a curated map with decisions and conventions lands around 400 tokens, like the benchmark fixture. We quote the honest per-session savings number — 78.9% — from the benchmark, not from these whole-repo ratios.)

How it works

flowchart LR

subgraph agents["Your AI agents"] A1[Claude Code] A2[Cursor] A3[Gemini / Codex / Copilot] end subgraph pm["projectmind"] MCP["MCP server\n(stdio, 6 tools)"] CORE["core\n(atomic writes, schema-validated)"] HOOK["git post-commit hook\n+ watch mode"] end subgraph repo["Your repo"] MAP[".projectmind/map.json\nnodes · edges · decisions\nconventions · glossary"] DIG[".projectmind/digest.md\n+ embedded in CLAUDE.md etc."] end LEDGER[".projectmind/ledger.json\nlocal savings ledger (gitignored)"]

A1 <--> MCP A2 <--> MCP A3 <--> MCP MCP --> CORE HOOK --> CORE CORE <--> MAP CORE --> DIG MCP --> LEDGER

Two update paths keep the map current without burning tokens:

• Deterministic: the git hook (and optional projectmind watch) map changed files to modules via globs and bump freshness. Pure local computation, zero LLM.
• Agent-recorded: when the agent makes an architectural decision or learns a convention, it calls mind_update — a few tokens once, instead of re-discovery every session.

There is deliberately no background LLM summarization — that would burn the tokens this tool exists to save.

What the agent actually reads

# shopflow-api — project map

Order-management HTTP API with JWT auth, backed by PostgreSQL. Stack: node, express, postgres

Active

• auth: Issues/verifies JWT access tokens; exposes requireAuth Express middleware. [active]
• orders-route: Create and list orders for the authenticated user; totals in integer cents. [active]

Modules

• db: PostgreSQL pool wrapper: query() helper and withTransaction().

…

Key decisions

• Store money as integer cents, never floats. (2026-06-10)
• JWT for stateless auth instead of server sessions. (2026-06-15)

Conventions

• Never read process.env outside src/config.js.

…

~412 tokens for the whole thing. The long fields (notes, rationale, file lists) are excluded from the digest and only surface through mind_query — cheap by default, detail on demand.

MCP tools

One-command agent wiring — and it doesn't depend on the model choosing to read it

projectmind setup idempotently writes the MCP config and a workflow rules block for each agent — merging into existing configs, never clobbering (an unparseable config is backed up and skipped).

Here's the part that matters: MCP tools are a *nudge* — no server can force a model to call one, so an agent can (and sometimes will) skip mind_digest on a plain "explain this project" question, especially mid-task. But rules files (CLAUDE.md, .cursorrules, .windsurfrules, GEMINI.md, AGENTS.md, .github/copilot-instructions.md) are loaded into every agent's context unconditionally, with zero model choice involved — that's the actual mechanism, not a coincidence. So setup doesn't just write instructions to call mind_digest; it embeds the live digest itself between markers, and every subsequent mind_update, CLI edit, git-commit hook run, or watch save re-syncs it automatically. The project map is present in context from message one, on every agent, with no tool call required at all