cherry-docs 0.3.0

Local-first AI memory for Claude Code — capture, distill, and retrieve project knowledge automatically.

CherryDocs

Memory for AI coding agents. The AI is the user.

AI agents forget everything when a session ends. CherryDocs gives them a local, persistent project memory: what was decided, what failed, what to avoid — captured automatically, distilled into durable memories, and retrievable in any future session.

You set it up once. Your AI uses it every session without being asked.

capture → distill → promote → retrieve

Setup (once, ~2 minutes)

pip install cherry-docs
cherry install            # wires Claude Code hooks + MCP server globally
export ANTHROPIC_API_KEY=sk-ant-...   # recommended for production distillation

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

Distillation provider (auto-detected):

• ANTHROPIC_API_KEY set → Claude Haiku (best quality, ~fractions of a cent per session)
• No key → local Ollama (ollama pull qwen2.5:7b-instruct) — good for offline/dev

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	Records a decision, fix, or insight that would otherwise be lost
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.

How a session flows

1. AI calls onboard() — gets project memory instantly
2. Work happens normally; hooks capture prompts, tool use, shell results
3. On stop/commit, the session is distilled into durable memories (decisions, warnings, procedures, facts — noise is rejected)
4. Any future session asks answer("why did we switch to X?") and gets the decision with its rationale and evidence

Memory quality, enforced

• Self-contained memories only — title-only labels ("Steps for X") are rejected at distillation; a memory must teach something actionable
• No transient noise — test counts, CI status, commit counts, session summaries never become permanent memories
• Self-healing store — cherry consolidate (also auto-run after promotion) 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 + provider health
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)
• Distillation: Anthropic Claude Haiku or local Ollama
• Privacy: secrets detected and redacted before anything persists

Project-scoped first, branch-aware second.

Development

pip install -e '.[dev,anthropic]'
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?