Project memory for coding agents

memcrumbs is a command-line tool that keeps a project's working knowledge (standing rules, gotchas, runbooks, decisions, incidents and a dated journal) in short markdown pages, and indexes those pages, your docs and your code symbols in a local SQLite full-text index. A coding agent reads a header of rules once per session, then looks things up with memcrumbs find instead of grepping and reading whole files.

It sits between an agent's own scratch notes (Claude Code's auto-memory and CLAUDE.md) and a full documentation site, and it borrows from practices teams already use: architecture decision records, runbooks and post-incident reviews.

Start with three things. They work from the first session, before you write a single wiki page.

When you need more. Everything else is optional, and each part works on its own.

After memcrumbs init, every Claude Code session in the repo follows these five steps. The output below is real, from the invented sample project in the repository.

1. The session starts with the header

   A SessionStart hook prints the rules, the map, the top gotchas and recent journal lines. The agent reads them before it reads any code.

   memcrumbs · Emberline Ceramics (bench) — 43 pages · index 449 docs
   Project knowledge: memcrumbs find "<words>" · …; an exact name: grep for it

2. The agent asks the wiki

   Plain questions work: question words are dropped, a thesaurus bridges vocabulary and identifiers match by their parts.

   $ memcrumbs find "how do I roll back a bad deploy"
   [run ] Roll back booking app — …rollback-booking.md:1 · v8d

3. It opens only what it needs

   One section of a page, or one function by its line range. Every cut output names the command that goes deeper.

   $ memcrumbs page rollback-booking
   $ memcrumbs sym start_firing --body

4. It writes down what happened

   Decisions keep the options considered and the evidence. Incidents are keyed on the symptom the next person will see.

   $ memcrumbs decision "Move bookings to Postgres" \
       --status rejected --why "too much to run for our size"

5. You approve what it wrote

   A rule the agent adds waits outside the header until you approve it, in the same session. Claude Code asks you before the approval runs.

   > /memcrumbs-review
   [24109529bc] rules.md: - Ask the owner before moving a booked firing to another kiln
   $ memcrumbs review --approve 24109529bc
   # Claude Code asks you first; you say yes
   reviewed 1 item(s)

An agent should know how far to trust what it reads. Each hit says so in a few characters.

v12d

The page was last verified 12 days ago.

STALE

Older than the project's freshness limit (45 days by default).

SRC-CHANGED 3d

A file the page cites changed 3 days ago, after the page was verified.

SUPERSEDED→page

Replaced by a newer page, and ranked below current ones.

REJECTED

A decision that was tried or considered and turned down. Kept, so nobody tries it again.

UNREVIEWED

Written by an agent and not yet checked by a person.

Numbers from the repository's own benchmarks. You can run every one of them yourself.

httpx is a real public repository; its questions, results and the way to rerun them are in bench/httpx. The sample project is invented, so your numbers will differ. memcrumbs bench measures recall on your own questions; the setup guide shows how to write them.

Two commands from install to a wired repository. init names the project after the repo, drafts the map from it, indexes the code and the repo's markdown, asks once before it wires Claude Code, and runs a health check. Later, memcrumbs update keeps it current. The setup guide covers each step by hand.

$ pip install memcrumbs
$ cd /code/myapp && memcrumbs init
# CLAUDE.md block, session header hook, two skills, approval prompts; undo with init --remove