memcrumbs

Project memory for Claude Code and other coding agents: a small markdown wiki your agent reads before it reads your code, and a local index that answers in a few hundred tokens.

Every new session, a coding agent starts from zero. It greps, it reads whole files, it rediscovers the same facts, and it repeats mistakes your team already made. Notes kept by hand drift until they contradict the system, and sometimes they leak a secret.

memcrumbs gives each project a memory that stays small, current and safe.

What it does for you

• Your agent starts every session knowing the rules. A short header (under 1,000 tokens) brings your standing rules, the project map, the top gotchas and recent journal lines, so "never deploy on Friday" is read before anything else.
• Answers instead of file dumps. memcrumbs find "how do I roll back a bad deploy" returns a few ranked hits with path:line, how old each one is and whether it is still current. The agent then opens one section or one function, not a 4,000-line file.
• It remembers what happened and why. Decisions (including the ones you rejected), incidents with the symptom someone will see next time, runbooks, and a dated journal. Asking "did we ever try Postgres?" finds the rejected decision instead of a fresh attempt.
• It knows when it may be wrong. Every hit says how long ago it was verified, flags STALE pages, and says SRC-CHANGED when the code a page describes changed after the page was checked.
• It tells the agent what the wiki says about a file before it edits it. memcrumbs about deploy.ps1 lists the decisions, incidents and gotchas that mention it.
• It keeps one current value per fact. Versions, ports and hosts live in one table, optionally read straight from the source file, and check flags pages that still state an old value.
• It notices things for you, and asks first. memcrumbs suggest offers near-duplicate pages to merge, questions the wiki could not answer, gotchas that can become permission prompts, repeated command sequences that could become a skill, and auto-memory notes the wiki already holds. Nothing changes until you say yes, and every change can be undone byte for byte.
• Your secrets stay out. Everything indexed, printed or written is redacted; .env files and keys are never indexed; memcrumbs scan checks a folder or a package before you publish it.
• You stay in control of token spend. Re-indexing is free and local. Rewriting stale pages is agent work, so memcrumbs plan and the dashboard let you pick the pages and the budget.

Standard library only: no model calls, no background service, no per-tool-call hooks, and no network use except memcrumbs update, when you run it. Your wiki is plain markdown in your own folder.

What it looks like

$ memcrumbs find "how do I roll back a bad deploy" -n 3
[run ] Roll back booking app — wiki/runbooks/rollback-booking.md:1 · v8d
       …booking [release] in under two minutes by repointing the current junction [Roll back] booking…
[run ] Deploy booking app — wiki/runbooks/deploy-booking.md:1 · v8d
       Numbered steps to [ship] a new booking app [release] to web-srv, with the…
[wiki] Booking web app › Behaviour notes — wiki/components/booking-app.md:23 · v8d
       …[Deploy] with [[deploy-booking]]; [undo] with [[rollback-booking]].
read: memcrumbs page rollback-booking · more: -n 6

$ memcrumbs about repo/ops/EmberOps.psm1
EmberOps.psm1 — cited by 1 decision (ACCEPTED), 2 incidents, 1 runbook
[dec ] Unlimited execution time for daemon tasks — wiki/decisions/2026-08-12-execution-time-limit-zero.md:1 · ACCEPTED
[inc ] BOM in a PowerShell script silently broke a scheduled task — wiki/incidents/2026-07-29-bom-breaks-scheduled-task.md:1
…

(From the invented sample project in bench/kiln.)

Install

pip install memcrumbs            # Python 3.11+; puts `memcrumbs` on PATH (pipx and uv tool work too)

To upgrade later, run memcrumbs update: it installs the newest release the same way memcrumbs was installed, re-indexes your projects and refreshes the agent setup in your repos. After an upgrade by hand (pip install --upgrade memcrumbs), run memcrumbs update once to finish it. Add [update] notify = true to a project's config to get a one-line notice in the session header when a new release is out.

Your wikis live outside the package, in ~/.memcrumbs/projects by default. To keep them somewhere else (for example a private git repo), set projects_dir in ~/.memcrumbs/config.toml or the MEMCRUMBS_PROJECTS environment variable.

Quick start

pip install memcrumbs
cd /code/myapp && memcrumbs init

init names the project after the repo, writes a starter wiki with a map drafted from the repo (README, languages, folders, tests, CI), indexes the code and the repo's markdown, and checks the result. It asks once before it wires Claude Code (a CLAUDE.md block, a session-start hook, read-only allow rules and a skill). Running it again repairs and upgrades; memcrumbs init --remove takes the wiring out again, byte for byte.

From then on, every Claude Code session in that repo starts with the header, and the agent looks things up with memcrumbs find. In the first session the agent drafts your rules and gotchas from CLAUDE.md, the README and the code; they reach the header once you approve them with memcrumbs review. Inside the repo (or the project folder) -p can be left out. Write the wiki as you go:

memcrumbs log "rotated the API key" --tag ops                        # a dated journal line
memcrumbs decision "Move bookings to Postgres" --status rejected --why "too much to run for our size"
memcrumbs incident "Nightly task died after 72 h" --symptom "no reports since Tuesday" --cause "task time limit"
memcrumbs check                                                      # lint: secrets, links, stale pages, …

To do each step yourself (or have your agent follow them), see the step-by-step setup in docs/adopting.md.

Everyday commands

Every command takes --json. Full reference: docs/cli.md.

Documentation

• Setting up a project, step by step
• Writing good crumbs: pages, rules, gotchas, decisions, incidents, facts
• Configuration · Command reference
• Plugins and packs: add a source, a check, a header section or a language
• Security: what redaction promises and what it does not

Contributing and reporting bugs

• Found a bug? Open an issue with the bug template. Paste the output of memcrumbs doctor --share: it holds versions, counts and timings only, never your paths, page text or secrets.
• An idea or a missing feature? Use the feature request template. Say what you were trying to do.
• A security problem? Please report it privately, as described in SECURITY.md, not in a public issue.
• Want to contribute code or docs? See CONTRIBUTING.md: how to run the tests, the few rules the code follows, and what a good pull request looks like.

Status

Alpha: usable day to day, with the command line and config still allowed to change before 1.0. Changes are listed in CHANGELOG.md. License: Apache-2.0.