# Packmind

> A second brain for Claude Code: project memory, real token & cost accounting, local semantic recall, and active guardrails.

- **Type:** MCP server
- **Install:** `agentstack add mcp-mchl-schrdng-packmind`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mchl-schrdng](https://agentstack.voostack.com/s/mchl-schrdng)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [mchl-schrdng](https://github.com/mchl-schrdng)
- **Source:** https://github.com/mchl-schrdng/packmind

## Install

```sh
agentstack add mcp-mchl-schrdng-packmind
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

```bash
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.
2. **MCP server** - registered in `.mcp.json`, it exposes the brain as tools
   Claude can call directly (`recall`, `remember`, `record_solution`, and more).
3. **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](https://github.com/mchl-schrdng)
- **Source:** [mchl-schrdng/packmind](https://github.com/mchl-schrdng/packmind)
- **License:** Apache-2.0

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-mchl-schrdng-packmind
- Seller: https://agentstack.voostack.com/s/mchl-schrdng
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.