Metadata-Version: 2.4
Name: cherry-docs
Version: 0.2.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

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

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

Then add to your `.mcp.json`:

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

## Minimal AI Rule

```md
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](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

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

For PR hardening:

```bash
bash scripts/local_pr_gate.sh fast
```

## Documentation

- [Product Brief](docs/PRODUCT_BRIEF.md)
- [System Deep Dive](docs/SYSTEM_DEEP_DIVE.md)

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