Part of the Brigade fleet from Escoffier Labs
Keeps your agent memory healthy.
The Claude Code and OpenClaw memory system is a directory of markdown cards plus a MEMORY.md index. Over time the index outgrows its threshold, handoffs pile up unprocessed, and wiki-links rot. memory-doctor is one CLI that reports the state of memory, lints the dead links, ingests what is pending, and compacts the index back down.
The Tournant of the brigade: the swing chef who works every station and keeps it in order.
Look · what memory-doctor reads
- The memory dir of markdown cards plus the MEMORY.md index
- The handoffs dir where sessions drop pending handoff files
- [[wiki-link]] references threaded across every card
- Frontmatter and line counts, never the prose of a card body
- Optional git state, when the memory dir is a repo
Tend · what it keeps in order
- A MEMORY.md index that stays under its load threshold
- Pending handoffs promoted into the cards they describe
- Dead wiki-links surfaced before an agent trips on them
- Writes gated behind --apply, so nothing changes by surprise
- One reviewable git commit per write, when you opt in
status
Read-only$ memory-doctor status Prints the memory dir path, card count, MEMORY.md line and byte count, threshold status, dead-link count, handoffs dir path, pending and processed counts, and the oldest pending age. Always exits 0. Pass --json for a structured payload.
lint
Read-only$ memory-doctor lint Walks every .md in the memory dir, extracts [[wiki-link]] references, and checks whether each target exists. Dead links are grouped by source file with a closest-match suggestion. Exits 0 if there are none, 1 if any, so you can gate a pre-commit hook on it.
ingest
Dry-run by default$ memory-doctor ingest [--apply] Sweeps the handoffs dir for unprocessed handoff files. create-card writes a new card, update-card appends to an existing one, no-card just files the handoff. Processed handoffs move to processed/. Dry-run by default, --apply writes.
compact
Dry-run by default$ memory-doctor compact [--apply] Reads MEMORY.md and, if it is over the line threshold, flattens multi-line entries: the one-liner stays in the index and the detail moves to its topic file. Refuses if a target topic file is missing. Dry-run by default, --apply writes.
status and lint are read-only. ingest and compact default to dry-run; pass --apply to actually write. A one-time init-git turns the memory dir into a git repo so every --apply can be tied to a commit.
Dry-run is the default
Anything that writes (ingest, compact) prints exactly what it would change and stops. You pass --apply when you are ready. status and lint never write at all.
No LLM calls
Compaction is rule-based: flatten multi-line entries, move detail to topic files. No model-generated summaries, no semantic dedup, no surprise rewrites of your card bodies.
Local files only
memory-doctor operates on the memory and handoffs directories on disk. No remote sync, no upload, no daemon. Each invocation is a single shot you can wire into cron or a session hook.
Catches link rot
lint resolves every [[wiki-link]] across your cards and flags the dead ones with a closest-match suggestion, so a renamed or removed card does not silently break references.
Optional git integration
Run init-git once to make the memory dir a git repo, then add --commit to ingest --apply or compact --apply. Each write becomes one reviewable, revertable commit with a descriptive subject. Off by default.
Configurable paths and thresholds
Memory dir, handoffs dir, MEMORY.md line threshold, and commit behavior are all set via flags or environment variables. Defaults are tuned for the OpenClaw layout; override them for other setups.
Every path and threshold can be set with a flag or an environment variable. The defaults are tuned for the OpenClaw layout; override them for other setups. Requires Python 3.10+, with no runtime dependencies beyond the standard library.
| What | Flag | Env |
|---|---|---|
| --memory-dir | Memory dir | MEMORY_DOCTOR_MEMORY_DIR |
| --handoffs-dir | Handoffs dir | MEMORY_DOCTOR_HANDOFFS_DIR |
| --max-lines | MEMORY.md line threshold | MEMORY_DOCTOR_MAX_LINES |
| --commit / --no-commit | Commit verb output | MEMORY_DOCTOR_COMMIT |
| --commit-author | Commit author override | MEMORY_DOCTOR_COMMIT_AUTHOR |
memory-doctor is open source under the MIT license and ships as part of the Brigade fleet. Install it with pipx, read the full verb reference in the README, or browse the rest of the kitchen.