Metadata-Version: 2.4
Name: cherry-docs
Version: 0.3.0
Summary: Local-first AI memory for Claude Code — capture, distill, and retrieve project knowledge automatically.
License: MIT
Project-URL: Homepage, https://github.com/freebeiro/cherry-docs
Project-URL: Repository, https://github.com/freebeiro/cherry-docs
Keywords: ai,memory,claude,mcp,developer-tools
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.40; extra == "anthropic"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: coverage>=7.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.9; extra == "dev"

# 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)

```bash
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](https://ollama.com) (`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

```bash
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](docs/agent_protocol.toml).
More: [Product Brief](docs/PRODUCT_BRIEF.md) · [System Deep Dive](docs/SYSTEM_DEEP_DIVE.md)

---

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