cherry-docs 0.2.0__tar.gz

cherry_docs-0.2.0/PKG-INFO

@@ -0,0 +1,143 @@
+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?

cherry_docs-0.2.0/README.md

@@ -0,0 +1,114 @@
+# 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?

cherry_docs-0.2.0/app/repo_scope.py

@@ -0,0 +1,24 @@
+from typing import Optional
+
+
+def normalize_project_id(project_id: Optional[str], default: str = "default-project") -> str:
+    """
+    Normalize repository/project identifiers to the internal dashed format.
+    Examples:
+    - github.com/owner/repo -> owner-repo
+    - https://github.com/owner/repo.git -> owner-repo
+    - git@github.com:owner/repo.git -> owner-repo
+    """
+    if not project_id:
+        return default
+
+    normalized = project_id.strip()
+    if not normalized:
+        return default
+
+    normalized = normalized.replace("https://", "").replace("http://", "")
+    normalized = normalized.replace("git@github.com:", "").replace("github.com/", "")
+    normalized = normalized.removesuffix(".git")
+    normalized = normalized.strip("/")
+    normalized = normalized.replace("/", "-")
+    return normalized.lower() or default

cherry_docs-0.2.0/app/services/agent_protocol.py

@@ -0,0 +1,59 @@
+"""Canonical agent protocol rendering for all supported client rule files."""
+from __future__ import annotations
+
+import tomllib
+from hashlib import sha256
+from pathlib import Path
+
+ROOT_DIR = Path(__file__).resolve().parents[2]
+PROTOCOL_PATH = ROOT_DIR / "docs" / "agent_protocol.toml"
+PROTOCOL_SOURCE = "docs/agent_protocol.toml"
+PROMPT_OUTPUTS = {
+    ".claude/CLAUDE.md": "claude",
+    "AGENTS.md": "agents",
+    "GEMINI.md": "gemini",
+    ".cursorrules": "cursorrules",
+    ".cursor/rules/cherrydocs.mdc": "cursor_mdc",
+}
+
+
+def _load_protocol() -> tuple[dict, str]:
+    raw = PROTOCOL_PATH.read_text(encoding="utf-8")
+    return tomllib.loads(raw), raw
+
+
+def _protocol_metadata(protocol: dict, raw: str) -> dict[str, str]:
+    return {
+        "source": PROTOCOL_SOURCE,
+        "version": str(protocol["meta"]["version"]),
+        "hash": sha256(raw.encode("utf-8")).hexdigest()[:12],
+    }
+
+
+def _generated_comment(version: str, protocol_hash: str) -> str:
+    return f"<!-- Generated from {PROTOCOL_SOURCE} version={version} hash={protocol_hash}; do not edit by hand. -->"
+
+
+def _render_body(protocol: dict, version: str, protocol_hash: str) -> str:
+    meta = protocol["meta"]
+    shared = protocol["shared"]
+    lines = [_generated_comment(version, protocol_hash), meta["title"], ""]
+    lines.extend(f"- {bullet}" for bullet in shared["bullets"])
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def render_platform_prompt(platform: str) -> str:
+    protocol, raw = _load_protocol()
+    meta = _protocol_metadata(protocol, raw)
+    body = _render_body(protocol, meta["version"], meta["hash"])
+    if platform == "claude":
+        return body
+    if platform in {"agents", "gemini", "cursorrules"}:
+        return f"# Project Rules\n\n{body}"
+    if platform == "cursor_mdc":
+        return "---\ndescription: CherryDocs project protocol\nalwaysApply: true\n---\n\n" + body
+    raise ValueError(f"Unsupported platform: {platform}")
+
+
+def build_prompt_file_map() -> dict[str, str]:
+    return {path: render_platform_prompt(platform) for path, platform in PROMPT_OUTPUTS.items()}

cherry_docs-0.2.0/app/services/auto_promote_sessions.py

@@ -0,0 +1,245 @@
+"""Background-friendly auto-promotion for captured AI sessions."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from app.repo_scope import normalize_project_id
+from app.services.capture_core import LocalCaptureBuffer
+from app.services.internal_memory_agent import MemoryModelProvider
+from app.services.memory_providers import resolve_provider
+from app.services.promoted_memory_pipeline import run_session_promotion
+from app.services.promoted_memory_store import DEFAULT_PROMOTED_ROOT, LocalPromotedMemoryStore
+
+
+class AutoPromotionPolicy(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    min_event_count: int = 3
+    min_candidate_confidence: float = 0.8
+    max_sessions: int = 10
+
+
+class AutoPromotionState(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    session_id: str
+    project_id: str
+    signature: str
+    event_count: int
+    last_event_timestamp: str | None = None
+    last_promoted_at: str = Field(default_factory=lambda: datetime.now(UTC).isoformat())
+
+
+class AutoPromotionSessionResult(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    session_id: str
+    action: str
+    reason: str = ""
+    promoted_count: int = 0
+    highlights: list[str] = Field(default_factory=list)
+    distillation_trace: dict[str, object] | None = None
+
+
+class AutoPromotionRunReport(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    project_id: str
+    processed: list[AutoPromotionSessionResult] = Field(default_factory=list)
+    skipped: list[AutoPromotionSessionResult] = Field(default_factory=list)
+
+
+def _state_dir(buffer_dir: str | Path) -> Path:
+    return Path(buffer_dir).expanduser().resolve() / ".promotion-state"
+
+
+def _state_path(buffer_dir: str | Path, session_id: str) -> Path:
+    safe = session_id.replace("/", "_").replace("\\", "_")
+    return _state_dir(buffer_dir) / f"{safe}.json"
+
+
+def _load_state(buffer_dir: str | Path, session_id: str) -> AutoPromotionState | None:
+    path = _state_path(buffer_dir, session_id)
+    if not path.exists():
+        return None
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        return AutoPromotionState.model_validate(payload)
+    except Exception:
+        return None
+
+
+def _save_state(buffer_dir: str | Path, state: AutoPromotionState) -> None:
+    path = _state_path(buffer_dir, state.session_id)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(state.model_dump(mode="json"), indent=2), encoding="utf-8")
+
+
+def list_capture_sessions(buffer_dir: str | Path) -> list[str]:
+    root = Path(buffer_dir).expanduser().resolve()
+    if not root.exists():
+        return []
+    return [
+        path.stem
+        for path in sorted(root.glob("*.jsonl"), key=lambda p: p.stat().st_mtime, reverse=True)
+    ]
+
+
+def _session_signature(events: list[dict]) -> str:
+    relevant = [
+        {
+            "event_type": event.get("event_type"),
+            "timestamp": event.get("timestamp"),
+            "text": str(event.get("text") or "")[:400],
+            "command": event.get("command"),
+            "exit_code": event.get("exit_code"),
+        }
+        for event in events
+    ]
+    payload = json.dumps(relevant, sort_keys=True, ensure_ascii=False)
+    return hashlib.sha1(payload.encode("utf-8"), usedforsecurity=False).hexdigest()
+
+
+def _new_state(project_id: str, session_id: str, events: list[dict]) -> AutoPromotionState:
+    timestamps = [
+        str(event.get("timestamp") or "").strip()
+        for event in events
+        if str(event.get("timestamp") or "").strip()
+    ]
+    return AutoPromotionState(
+        session_id=session_id,
+        project_id=project_id,
+        signature=_session_signature(events),
+        event_count=len(events),
+        last_event_timestamp=timestamps[-1] if timestamps else None,
+    )
+
+
+def _session_matches_scope(events: list[dict], *, project_id: str, branch: str | None) -> bool:
+    if not events:
+        return False
+    normalized_project_id = normalize_project_id(project_id)
+    repos = {
+        normalize_project_id(str(event.get("repo") or ""))
+        for event in events
+        if str(event.get("repo") or "").strip()
+    }
+    if repos:
+        if normalized_project_id not in repos:
+            return False
+    else:
+        # No repo field — fall back to cwd directory name match
+        cwds = {
+            normalize_project_id(Path(str(event.get("cwd") or "")).name)
+            for event in events
+            if str(event.get("cwd") or "").strip()
+        }
+        if cwds and normalized_project_id not in cwds:
+            return False
+    if branch:
+        branches = {
+            str(event.get("branch") or "").strip()
+            for event in events
+            if str(event.get("branch") or "").strip()
+        }
+        if branches and branch not in branches:
+            return False
+    return True
+
+
+def auto_promote_captured_sessions(
+    *,
+    project_id: str,
+    buffer_dir: str | Path = ".cherrydocs/capture",
+    promoted_root: str | Path = DEFAULT_PROMOTED_ROOT,
+    provider: MemoryModelProvider | None = None,
+    project_hint: str | None = None,
+    branch: str | None = None,
+    commit: str | None = None,
+    policy: AutoPromotionPolicy | None = None,
+    memory_profile: str | None = None,
+) -> AutoPromotionRunReport:
+    resolved_policy = policy or AutoPromotionPolicy()
+    resolved_provider = provider or resolve_provider()
+    buffer = LocalCaptureBuffer(buffer_dir)
+    store = LocalPromotedMemoryStore(promoted_root)
+    sessions = list_capture_sessions(buffer_dir)[: resolved_policy.max_sessions]
+
+    existing_records = [
+        r for r in store.load_records(project_id)
+        if not branch or not r.branch or r.branch == branch
+    ]
+    processed: list[AutoPromotionSessionResult] = []
+    skipped: list[AutoPromotionSessionResult] = []
+
+    for session_id in sessions:
+        events = buffer.read(session_id)
+        if not _session_matches_scope(events, project_id=project_id, branch=branch):
+            skipped.append(AutoPromotionSessionResult(
+                session_id=session_id, action="skip",
+                reason="session outside requested project/branch scope",
+            ))
+            continue
+        if len(events) < resolved_policy.min_event_count:
+            skipped.append(AutoPromotionSessionResult(
+                session_id=session_id, action="skip",
+                reason=f"too few events ({len(events)} < {resolved_policy.min_event_count})",
+            ))
+            continue
+
+        state = _load_state(buffer_dir, session_id)
+        current_state = _new_state(project_id, session_id, events)
+        if state and state.project_id == project_id and state.signature == current_state.signature:
+            skipped.append(AutoPromotionSessionResult(
+                session_id=session_id, action="skip",
+                reason="no new captured evidence since last promotion",
+            ))
+            continue
+
+        report = run_session_promotion(
+            events=events,
+            session_id=session_id,
+            project_id=project_id,
+            provider=resolved_provider,
+            project_hint=project_hint,
+            branch=branch,
+            commit=commit,
+            existing_records=existing_records,
+            min_confidence=resolved_policy.min_candidate_confidence,
+            memory_profile=memory_profile,
+        )
+        session_records = [r for r in report.session_records if r.memory_type != "noise"]
+        if not session_records:
+            skipped.append(AutoPromotionSessionResult(
+                session_id=session_id, action="skip",
+                reason="no high-confidence durable memory candidates",
+            ))
+            _save_state(buffer_dir, current_state)
+            continue
+
+        existing_records = store.upsert_records(project_id, report.promotion.records)
+        _save_state(buffer_dir, current_state)
+        processed.append(AutoPromotionSessionResult(
+            session_id=session_id,
+            action="promote",
+            promoted_count=len(session_records),
+            highlights=[r.summary for r in session_records[:3]],
+            distillation_trace=report.distillation_trace.model_dump(mode="json"),
+        ))
+
+    return AutoPromotionRunReport(project_id=project_id, processed=processed, skipped=skipped)
+
+
+__all__ = [
+    "AutoPromotionPolicy",
+    "AutoPromotionRunReport",
+    "AutoPromotionSessionResult",
+    "auto_promote_captured_sessions",
+    "list_capture_sessions",
+]

cherry_docs-0.2.0/app/services/capture_adapters.py

@@ -0,0 +1,89 @@
+"""Shared append helpers for capture integrations."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from app.services.capture_core import (
+    CaptureEvent,
+    CaptureEventType,
+    LocalCaptureBuffer,
+    build_capture_event,
+)
+
+_TEST_COMMAND_MARKERS = (
+    "pytest",
+    "pnpm test",
+    "npm test",
+    "yarn test",
+    "bun test",
+    "vitest",
+    "jest",
+    "go test",
+    "cargo test",
+    "mix test",
+    "rspec",
+    "phpunit",
+)
+
+
+def infer_capture_event_type(*, tool_name: str | None = None, command: str | None = None) -> CaptureEventType:
+    normalized_command = " ".join(str(command or "").split()).lower()
+    if normalized_command and any(marker in normalized_command for marker in _TEST_COMMAND_MARKERS):
+        return CaptureEventType.TEST_RESULT
+    if str(tool_name or "").strip() == "Bash":
+        return CaptureEventType.SHELL_RESULT
+    return CaptureEventType.TOOL_RESULT
+
+
+def enrich_capture_metadata(
+    *,
+    event_type: CaptureEventType,
+    command: str | None = None,
+    exit_code: int | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    enriched = dict(metadata or {})
+    if event_type == CaptureEventType.TEST_RESULT:
+        enriched.setdefault("capture_kind", "verification")
+        enriched.setdefault("verification_kind", "test")
+        if exit_code is not None:
+            enriched.setdefault("verification_status", "passed" if exit_code == 0 else "failed")
+    elif event_type == CaptureEventType.SHELL_RESULT and command:
+        enriched.setdefault("capture_kind", "command")
+    return enriched
+
+
+def append_capture_event(
+    *,
+    buffer_dir: str | Path,
+    source: str,
+    event_type: CaptureEventType,
+    session_id: str,
+    cwd: str,
+    text: str | None = None,
+    files: list[str] | None = None,
+    command: str | None = None,
+    exit_code: int | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> CaptureEvent:
+    merged_metadata = enrich_capture_metadata(
+        event_type=event_type,
+        command=command,
+        exit_code=exit_code,
+        metadata=metadata,
+    )
+    event = build_capture_event(
+        source=source,
+        event_type=event_type,
+        session_id=session_id,
+        cwd=cwd,
+        text=text,
+        files=files,
+        command=command,
+        exit_code=exit_code,
+        metadata=merged_metadata,
+    )
+    LocalCaptureBuffer(buffer_dir).append(event)
+    return event