Metadata-Version: 2.4
Name: cherry-docs
Version: 0.5.0
Summary: Decision records for AI coding agents — the AI logs decisions, attempts, and conclusions; the knowledge stays with the project.
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: 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

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

```bash
pip install cherry-docs
cherry install            # wires Claude Code + Cursor hooks and the MCP server globally
```

That's it. Open any project in Claude Code or Cursor — 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

```bash
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 + Cursor 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`) and Cursor hooks (`beforeSubmitPrompt`, `afterFileEdit`, `stop`) — raw evidence trail, vendor-neutral
- **Privacy**: secrets detected and redacted before anything persists

Project-scoped first, branch-aware second.

## Development

```bash
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](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?**
