cherry-docs 0.2.0

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

CherryDocs

CherryDocs is a local-first memory layer for AI coding chats.

The intended flow is simple:

1. connect your AI client to CherryDocs via MCP
2. start with onboard() — get project context in one call
3. work normally in the repo
4. ask answer() when continuity matters

What It Does

CherryDocs helps an AI answer questions like:

• Why is this code here?
• What did we already try?
• What failed before?
• How do I continue this work without rereading everything?

The core product shape is:

• onboard() for the smallest useful startup view
• passive capture of work traces via Claude Code hooks
• local Ollama distillation of sessions into durable project memory
• answer() for retrieval when a new chat needs context

Current Architecture

• Durable memory store: local JSON at ~/.cherrydocs/promoted/{project_id}.json
• Transport: MCP via stdio (FastMCP) — 4 tools
• Distillation: local Ollama (qwen2.5:7b-instruct by default)
• Capture: Claude Code hooks + MCP log tools

CherryDocs is project-scoped first and branch-aware second.

MCP Tools

Tool	Purpose
onboard	Session start — loads top memories + recent sessions
log_activity	Record a decision, fix, or insight to the capture buffer
save_checkpoint	Structured handoff — blind AI must be able to continue
answer	Query promoted memory for project questions

Setup

pip install cherry-docs
cherry install   # installs Claude Code hooks

Then add to your .mcp.json:

{
  "mcpServers": {
    "cherry-docs": {
      "command": "cherry-docs-mcp"
    }
  }
}

Minimal AI Rule

Use CherryDocs.
- On start: call `onboard()`.
- Work normally.
- Use `answer()` when history could change the decision.
- Use `log_activity()` when something important would otherwise be lost.

The canonical source for generated agent rules is docs/agent_protocol.toml.

Workflow

In a new session:

1. Claude calls onboard() — gets top memories + recent session state
2. Work happens normally; hooks capture tool use and code changes
3. On git commit, auto-distillation fires via Ollama
4. Ask answer("Why did we change this?") in any future session

What Works Today

• Local file-backed promoted memory (no cloud, no graph DB)
• MCP stdio server with 4 tools
• Claude Code hook-based passive capture
• Ollama distillation pipeline (per-session + commit-triggered)
• cherry eval — heuristic + LLM judge for memory quality
• cherry why <file> — show memories anchored to commits touching a file

Development

pip install -e .
python -m pytest tests/ -q
python scripts/check_size_limits.py

For PR hardening:

bash scripts/local_pr_gate.sh fast

Documentation

• Product Brief
• System Deep Dive

Would another AI actually want to keep this on because it helps achieve the goal?