cherry-docs 0.4.0

Decision records for AI coding agents — the AI logs decisions, attempts, and conclusions; the knowledge stays with the project.

CherryDocs

Decision records for AI coding agents. The AI writes them; the company keeps them.

When a developer leaves, the architecture decisions usually leave with them. CherryDocs fixes that: the AI agent records every decision, failed attempt, and conclusion at the moment it happens — first-person, with full provenance — and the knowledge stays with the project forever.

No API key. No cloud. No LLM middleman. The AI's own words are the record.

log → promote → retrieve → export

Setup (once, ~1 minute)

pip install cherry-docs
cherry install            # wires Claude Code hooks + MCP server globally

That's it. Open any project in Claude Code — CherryDocs is active. Verify anytime with cherry status.

What the AI gets

Tool	When the AI uses it
onboard	Session start — top memories + recent session state in one call
answer	"Why is this code here?" "What did we already try?" "What failed before?"
log_activity	A decision, pivot, fix, or refactor — promoted directly to durable memory
save_checkpoint	Structured handoff a blind AI can continue from

Every memory carries provenance: session, branch, commit, files, and the raw evidence events that support it.

What the company gets

cherry export --out docs/DECISIONS.md

An ADR-style markdown decision log — Decisions, Attempts & Pivots, Conclusions, Warnings — each with rationale, date, branch, commit, and files. Commit it to the repo and the knowledge belongs to the company, not to a tool, an account, or the developer who left.

How a session flows

1. AI calls onboard() — gets project memory instantly
2. Work happens normally; hooks capture prompts, tool use, and shell results as the raw evidence trail
3. When the AI logs a decision/pivot/fix/refactor, it lands in durable memory immediately — the AI's first-person testimony, no re-summarization
4. Any future session asks answer("why did we switch to X?") and gets the decision with its rationale and evidence

Memory quality, enforced

• First-person records — memories are written by the AI that made the decision, not inferred afterwards by another model
• No transient noise — test counts, CI status, commit counts, session summaries never become permanent memories
• Self-healing store — cherry consolidate merges near-duplicates and archives junk
• Relevance-first retrieval — token relevance dominates ranking; trust and past-retrieval utility can't carry an irrelevant memory to the top

Check store health: cherry eval --no-llm

CLI

cherry install      # wire into Claude Code globally
cherry status       # hooks + MCP health
cherry export       # write the decision log as markdown (--out FILE)
cherry consolidate  # merge duplicate memories, archive junk
cherry eval         # memory quality report (add --no-llm for heuristic only)
cherry why <file>   # memories anchored to commits touching <file>
cherry uninstall    # remove hooks + MCP entry

Architecture

• Store: local JSON at ~/.cherrydocs/promoted/{project_id}.json — no cloud, no DB
• Transport: MCP over stdio (FastMCP), 4 tools
• Capture: Claude Code hooks (UserPromptSubmit, PostToolUse, Stop) — raw evidence trail
• Privacy: secrets detected and redacted before anything persists

Project-scoped first, branch-aware second.

Development

pip install -e '.[dev]'
python -m pytest tests/ -q
python scripts/check_size_limits.py
bash scripts/local_pr_gate.sh fast     # before opening a PR

The canonical source for generated agent rules is docs/agent_protocol.toml. More: Product Brief · System Deep Dive

---

The test that matters: would another AI keep this turned on because it helps?