Packmind

PackMind

A second brain for Claude Code. Project memory, estimated token & cost activity, local semantic recall, and active guardrails - through lifecycle hooks and an MCP server. Zero workflow changes.

---

---

Contents

• [What PackMind does](#what-packmind-does)
• [Install and quick start](#install-and-quick-start)
• [How it works](#how-it-works)
• [Lifecycle hooks](#lifecycle-hooks)
• [MCP tools](#mcp-tools)
• [CLI reference](#cli-reference)
• [What lives in .packmind/](#what-lives-in-packmind)
• [Configuration](#configuration)
• [Scheduled maintenance](#scheduled-maintenance-no-daemon)
• [Privacy](#privacy)
• [Security](#security)
• [Requirements](#requirements)
• [Contributing](#contributing)
• [License](#license)

What PackMind does

Claude Code works without persistent project context: it can't tell a 50-token config from a 2,000-token module before opening it, re-reads the same files, and forgets what it learned last session. PackMind fixes that with a small state directory (.packmind/) maintained by lifecycle hooks, plus an MCP server that exposes the project's memory as tools Claude can query directly.

• Project map - every file gets a one-line description, a token estimate, and

an estimated read cost, so Claude reads map.md instead of opening files blind.

• Estimated token & cost activity - fast local estimates always, priced per

model into a running dollar total. Exact reconciliation via Anthropic's count-tokens API is opt-in (packmind scan --exact), so nothing leaves your machine by default.

• Local semantic recall - an on-device embedding index (nothing leaves your

machine) lets Claude recall(...) past decisions, solutions, and code by meaning.

• Active guardrails - a policy engine warns (or hard-blocks, opt-in) before a

write touches a secret file or violates a project rule.

• Practice packs - installable sets of engineering reflexes (tests, CI, release

hygiene, security) that nudge at the right moment. Session-level checks like "src/** changed but no test written" can be satisfied with the record_evidence tool so they stay quiet once you've done the thing. Manage with packmind practice.

• Lean mode - a reuse-first decision ladder that nudges Claude to build less

(off / lite / full), with a packmind: shortcut convention you harvest via debt.

• Reversible compression - shelve a large non-source output (log, JSON, command dump)

with compress(...) and pull the exact original back with retrieve(hash), to keep the session's context lean.

• Session-aware - accounting and reminders are keyed to Claude's real session id, so

concurrent sessions and worktrees are tracked separately (no shared global file). Resume and compaction continue a session, /clear starts a fresh one, and each closes into its own usage-ledger row on SessionEnd.

• Live change intelligence - PackMind tracks the net set of files changed during a

session (add / modify / delete / rename) from ANY source - Write/Edit, Bash, generators, parallel tool batches, or external editors - and keeps the map, recall, and practice checks in sync with it. Inspect it with packmind changes or the changes MCP tool.

Install and quick start

npm install -g packmind          # or: pnpm add -g packmind
cd your-project
packmind init                    # sets up .packmind/, hooks, and the MCP server
packmind index                   # builds the local semantic index (first run fetches the embed model)

Then use claude as normal - the hooks and MCP server do their work in the background. To skip the optional local-recall dependency entirely (smaller, CVE-clean install), use npm install -g packmind --omit=optional and set recall.enabled: false.

Commit the durable brain files (map.md, knowledge.md, config.json, policy.json) so your whole team shares the same project memory. See [What lives in .packmind/](#what-lives-in-packmind) for the full commit guide.

How it works

PackMind has three moving parts, all local:

1. Lifecycle hooks - small, zero-dependency Node scripts copied into

.packmind/hooks/ and registered in .claude/settings.json (tagged _managedBy: packmind so they are preserved and removable cleanly). Claude Code runs them on its own events (session start/end, prompt submit, before and after each Read/Write, and turn stop). They maintain the map, journal, usage ledger, and session state, and feed short reminders back into the model.

1. MCP server - registered in .mcp.json, it exposes the brain as tools

Claude can call directly (recall, remember, record_solution, and more).

1. State directory - .packmind/, a set of plain files (Markdown + JSON) you

can read, diff, and commit.

Nothing runs as a daemon and nothing opens a network port except the opt-in packmind dashboard (loopback only). The CLI is how you inspect and maintain the brain from the terminal.

Change-tracking coverage

Live change intelligence is event-assisted and reconciliation-backed: hook events make updates appear quickly, and reconciliation establishes correctness.

• Git projects reconcile in-process at the end of each turn, so Bash, generator,

parallel-batch, and external-editor changes are reflected in the net change set, the map, recall, and practice checks - not just direct Write/Edit calls.

• Non-git projects capture a bounded file-fingerprint baseline at session start

and reconcile fully via that manifest when you run packmind reconcile or packmind maintain. (packmind changes is read-only - it displays the last reconciled set without recomputing.)

• Only eligible files are tracked - the same secret, binary, size, and

(in git projects) gitignore rules as the project map; non-git manifest walks are additionally bounded by map.maxFiles. Ignored, secret, binary, oversized, symlinked-out-of-root, and out-of-root files never enter the change set.

• External-edit watching (FileChanged) depends on the host emitting watch paths;

reconciliation, not file watching, is the completeness mechanism, so PackMind never claims to watch every possible future file or to prevent a change that a post-change hook only observes after it happened.

Lifecycle hooks

Installed into .packmind/hooks/ and wired into .claude/settings.json by packmind init. Each is standalone and fail-safe (an error never blocks your tool call).

| Event | Hook | What it does | |-------|------|--------------| | SessionStart | session-start.js | Opens or reattaches this session's record (keyed by the real session_id), injects the handoff note, a "check map.md first" reminder, and the session id into context. resume/compact continue the session; /clear folds the old one into the ledger and starts a fresh incarnation. | | UserPromptSubmit | prompt-submit.js | Lexically matches your prompt against recorded solutions and surfaces likely-relevant past fixes before Claude even calls a tool. | | PreToolUse: Read | pre-read.js | Before a read: warns if the file was already read unchanged this session (wasteful re-read), surfaces its map.md description + token estimate, and suggests compress() for large non-source files. | | PreToolUse: Write/Edit/MultiEdit | pre-write.js | Before a write: evaluates the guardrail policy (warn, or hard-block secrets/rules when enabled), surfaces relevant recorded solutions and knowledge.md never-do notes, and emits the lean-mode reuse nudge. | | PostToolUse: Read | post-read.js | After a read: reconciles the token and cost accounting for that file. | | PostToolUse: Write/Edit/MultiEdit | post-write.js | After a write: refreshes the file's map.md entry, appends to the journal, updates accounting, queues the file for recall re-embedding, and nudges after repeated edits to the same file. | | PostToolBatch | post-tool-batch.js | After a batch of (possibly parallel) tool calls: coalesces direct writes into change candidates and flags a reconcile when Bash, a file-writing MCP tool, or an unknown tool ran. Inspects tool names/inputs only, never the tool response. | | FileChanged | file-changed.js | A watched file changed on disk (add/change/unlink) outside the direct tools: records an eligible, in-root change candidate. Fires for the paths SessionStart emits via watchPaths. | | Stop | stop.js | End of each turn: reconciles the net change set (git), syncs map + recall, folds usage into the lifetime ledger, refreshes the handoff, and emits at-most-once reminders. | | SessionEnd | session-end.js | When a session ends: a final reconcile, folds into the ledger, then on a terminal end removes the live session file and refreshes the handoff; on resume it suspends and keeps the file. |

MCP tools

Registered automatically in .mcp.json. Claude can call:

| Tool | Purpose | |------|---------| | recall(query) | Semantic search across knowledge, journal, solutions, and source code (uses the local vector index). | | remember(note, kind) | Save a durable Preferences / Decisions / Never Do / Notes / Debt entry into knowledge.md. | | record_solution(error, cause, fix, tags, file?) | Log a bug and its fix so it is never rediscovered; recording the same error again bumps its occurrence count. | | record_evidence(check, detail?, session_id?) | Mark a practice check satisfied this session so its Stop-hook nudge stays quiet. Pass session_id (shown at SessionStart) when several sessions are active. | | project_map(filter?) | List mapped files with descriptions and token estimates, optionally filtered. | | usage_report() | Model, session count, reads/writes, tokens, and dollar cost for the project. | | insights() | Estimated savings, map coverage, heaviest files, upkeep flags, and the compression store. | | handoff(action, content?) | Read or update the session resume note (get / set). | | debt() | List packmind: deferred-shortcut markers left in the code. | | changes(session_id?) | The session's net change set (files different from session start, from any source) with per-file map and recall status. Read-only. | | review(base?) | Package the current git diff with the lean decision ladder for an over-engineering review. | | compress(content, kind?) | Shelve a large non-source output and get a compact, reversible preview plus a retrieval hash. | | retrieve(hash) | Return the full original a compress call stored. |

CLI reference

Run any command inside a project (a directory with .packmind/). packmind --help prints usage.

Setup and lifecycle

| Command | What it does | |---------|--------------| | packmind init | Create .packmind/ (config + seed brain files + hooks), register the lifecycle hooks in .claude/settings.json, register the MCP server in .mcp.json, wire a snippet into CLAUDE.md, resolve the effective guard set, and run an initial map scan. Idempotent - safe to re-run. | | packmind update [--dry-run] [--list] [--project ] | Update every registered project to the current PackMind version: snapshot first, re-copy the hooks, re-register, and refresh the effective guard set, all while preserving config.json. --dry-run shows what would change; --list lists registered projects; --project limits to one. | | packmind upgrade [--check] | Upgrade PackMind itself to the latest published version: detect the package manager (npm/pnpm/yarn), install packmind@latest, then refresh registered projects via packmind update. --check only reports whether a newer version exists and prints the command to run. (Note: update refreshes projects; upgrade bumps the installed package.) | | packmind doctor | Diagnose registered projects, hook installation, and MCP registration; report what is installed, stale, or missing. | | packmind mcp | Run the MCP server over stdio. Claude Code invokes this for you - you rarely run it by hand. |

Map and accounting

| Command | What it does | |---------|--------------| | packmind scan [--check] [--exact] | Rebuild map.md by walking the project (honoring .gitignore, secret globs, and size caps), describing each file with a token and cost estimate. --check exits 1 if the map is stale (for CI). --exact reconciles counts via Anthropic count-tokens (needs ANTHROPIC_API_KEY). | | packmind status | Print token usage, dollar cost, session count, and project health from the usage ledger. | | packmind insights | Show where tokens go and what PackMind saved: estimated savings, re-reads avoided, map coverage, heaviest files, upkeep flags, and the compression store. |

Memory and recall

| Command | What it does | |---------|--------------| | packmind index | Build the local semantic recall index. The first run downloads the embedding model (cached under ~/.packmind/models); everything after is offline. | | packmind recall | Semantic search across knowledge, journal, solutions, and source from the terminal. | | packmind solutions | Search recorded bug solutions by term. | | packmind debt | List packmind: deferred-shortcut markers (the lean-mode debt ledger). |

Change intelligence

| Command | What it does | |---------|--------------| | packmind changes [--session ] [--json] | Show the current session's net change set: files added, modified, deleted, or renamed since the session started, from any source, with per-file map and recall status. --session selects one when several are active; --json prints the raw ChangeSetV1. | | packmind reconcile [--session ] [--json] | Force a full reconciliation (git status, or a file-fingerprint manifest for non-git projects) and synchronize the map and recall queue. Succeeds even when there are no changes. |

Guardrails and practices

| Command | What it does | |---------|--------------| | packmind policy check | Lint policy.json guardrail rules and report any invalid entries. | | packmind practice list | List the bundled practice packs and which are active. | | packmind practice add | Activate a practice pack (adds its rules and session checks to the effective guard set). | | packmind practice remove | Deactivate a practice pack. | | packmind practice explain | Show which rules and checks apply to a given path. |

Backups and maintenance

| Command | What it does | |---------|--------------| | packmind backup [--list] | Snapshot .packmind/ to ~/.packmind/backups// (skipping the regenerable vector index). --list lists existing snapshots. | | packmind restore [timestamp] | Restore .packmind/ from a backup. Takes a pre-restore snapshot and swaps atomically so a failed restore can't lose your brain. Omit the timestamp to list available backups. | | packmind maintain [--quiet] [--keep-backups ] | One-shot upkeep: refresh the map, rebuild the recall index, archive an overgrown journal, and prune old backups and stale session files. --quiet for unattended runs; --keep-backups sets how many snapshots to keep (default 10). Cron-friendly. | | packmind dashboard [--port ] [--no-open] | Launch the local web dashboard (Overview, Insights, Project Map, Journal, Recall, Config). Binds to loopback only and is token-protected. --port sets a preferred port (default 7878); --no-open skips auto-opening the browser. |

What lives in .packmind/

| File | Role | Commit? | |------|------|---------| | map.md | File map with tokens & cost | yes | | knowledge.md | Preferences, decisions, never-do list | yes | | identity.md | Persistent project identity notes | yes | | config.json | Configuration | yes | | policy.json | Guardrail rules (your local overrides) | yes | | PACKMIND.md | Protocol Claude follows | yes | | guard.effective.json | Resolved guard set (default + packs + policy.json) | no (derived) | |

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mchl-schrdng
• Source: mchl-schrdng/packmind
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.