cherry-docs 0.2.0__py3-none-any.whl

app/services/promoted_memory_store.py

@@ -0,0 +1,57 @@
+"""Project-scoped local store for promoted CherryDocs memory."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from app.repo_scope import normalize_project_id
+from app.services.memory_lifecycle import MemoryRecord
+
+DEFAULT_PROMOTED_ROOT: str = os.environ.get(
+    "CHERRY_PROMOTED_ROOT",
+    str(Path.home() / ".cherrydocs" / "promoted"),
+)
+
+
+class LocalPromotedMemoryStore:
+    def __init__(self, root: str | Path):
+        self.root = Path(root)
+
+    def path_for(self, project_id: str) -> Path:
+        normalized = normalize_project_id(project_id)
+        return self.root / f"{normalized}.json"
+
+    def load_records(self, project_id: str) -> list[MemoryRecord]:
+        path = self.path_for(project_id)
+        if not path.exists():
+            return []
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(payload, list):
+            return []
+        return [MemoryRecord.model_validate(item) for item in payload]
+
+    def save_records(self, project_id: str, records: list[MemoryRecord]) -> Path:
+        normalized = normalize_project_id(project_id)
+        path = self.path_for(normalized)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(
+            json.dumps([record.model_dump(mode="json") for record in records], indent=2),
+            encoding="utf-8",
+        )
+        return path
+
+    def upsert_records(self, project_id: str, records: list[MemoryRecord]) -> list[MemoryRecord]:
+        existing = {record.memory_id: record for record in self.load_records(project_id)}
+        for record in records:
+            existing[record.memory_id] = record
+        merged = sorted(
+            existing.values(),
+            key=lambda item: (item.project_id or "", item.created_at, item.memory_id),
+        )
+        self.save_records(project_id, merged)
+        return merged
+
+
+__all__ = ["LocalPromotedMemoryStore", "DEFAULT_PROMOTED_ROOT"]

cherry_docs-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,42 @@
+app/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+app/repo_scope.py,sha256=6uX3xSfEy96jbgztw7vRjwAOQaKsz2WeljcEOrhlQuA,842
+app/services/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+app/services/agent_protocol.py,sha256=DEXm3pDRoX6ahMuT_oNVMXUZV50-el9MVq6jPSAR2S8,2085
+app/services/auto_promote_sessions.py,sha256=-B_6qC-zliZ2JjzyGsYBLvYOY-fcIczeYfSdDlcCpB8,8615
+app/services/capture_adapters.py,sha256=ZBbC0gIkkFs39Pwf7s2I8u2vQ7zeXvNWoTdBsf-sNl8,2465
+app/services/capture_core.py,sha256=M-EmGs7tKDMpW75RDrrvsQJPEfSdUXx6j0T3oYFLRTY,4931
+app/services/internal_memory_agent.py,sha256=qH6En8u97Tn2yPSYPiOTIP_h5dOH0uhrenjUVX30mtY,7878
+app/services/memory_evidence.py,sha256=31ok2CdnDnt_QhxWJURUT_69q6NgldrQi9k96Vcf9pY,3255
+app/services/memory_extraction_normalize.py,sha256=B8_KnjkyW7aAwORFBvzd2vl_QW5n6_DpcPnQr03SfiE,4898
+app/services/memory_lifecycle.py,sha256=DLvu3rhHeONDE5CEVIaOxKQHNAQOdK34tdlrebOIoyw,9713
+app/services/memory_profiles.py,sha256=3nnefae4nX3OX2Ko7RYlsYeQkJrtE6BA5OD-TtBKVpE,4346
+app/services/memory_providers.py,sha256=8hAFljCIprMqpbSJ0D6LP8bMGoL3KiXUGE8_I-EDTEE,3851
+app/services/memory_retrieval.py,sha256=hyy0g_FU-oa_QpjTqZaOcy-OR865n2xwX9H5MwSBWAI,12296
+app/services/memory_retrieval_scoring.py,sha256=bgnfW8F55mOU2NH_oQHh9adqvQ9ej8F8Uj8dB3-hUmw,3121
+app/services/memory_retrieval_text.py,sha256=jfAsppy2R5JaDRR9bBoTUG-fV1rbeK61FBWKIGnCtsE,2990
+app/services/memory_similarity.py,sha256=tQlMBp7eb3AXQNOaQ3RhxX5S5EyB5wQSU7uUu6tqZTg,4994
+app/services/privacy.py,sha256=7yGNofkyogYeEJdp7DVSGuZkwRC8mqD0xrOsb3fxMd0,3097
+app/services/promoted_memory_answer.py,sha256=TJF6Vm-wdijSabj49gS3zz467IpmPGxKt4yDfkqp3pE,5161
+app/services/promoted_memory_pipeline.py,sha256=Iyy38z23emWzTEgpxJafDEpRGJie0j9n2uwQ7FjKZBU,6869
+app/services/promoted_memory_store.py,sha256=jrruqbUpRpLmL1B9mPBnvhnfXN5B7bUIvZS-RJV1pnw,1961
+cherrydocs/__init__.py,sha256=9C6yXI1iBUV9yVf0AxLb4U6qa_X4Nl8blK8PuhX-Cng,83
+cherrydocs/cli.py,sha256=MNr-7mC6sej7Mb8TKgAjUNDURRRTaXqLYOP7MAY6QI0,7762
+cherrydocs/hook.py,sha256=xdIgmvSvf_Z0YcEJCVvSRjNcEeDipkip7GvqUB-01_o,812
+cherrydocs/mcp.py,sha256=2Idg4cp-NIAPzoa8uW9Bx1Xu5l2FgFu0J-5yIJlshTY,578
+scripts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+scripts/auto_promote_capture.py,sha256=W8m4eaVG-GeQ83SV3Y_NhO3IF_pKRcYxo60F9DkeVwI,2670
+scripts/check_size_limits.py,sha256=Ewh99opzN485UCgRkNNE5TpgdXkgBtayXstWAm2wSOw,3350
+scripts/ci_auto_capture.py,sha256=6J1MhOZczAJ21M6uUksLo0alUQzNNa3Wv7lCEkyrqtE,11564
+scripts/coverage_regression_gate.py,sha256=NYbst5mEw8mHwozoaSGT0-ZUeViwILDOvFRUBxGaKfE,4298
+scripts/eval_projects.py,sha256=PwOM6xXdgXk0Om4qF1dVnx2Og8Rf9Dky_IxLJ-_gig4,8359
+scripts/install.py,sha256=RnP69G5eqgO91hL1mbCsM2LWLZFEPXXVvRxy2XPG2pU,7125
+scripts/pr_gate_report.py,sha256=g1Iql-8vAdRdWsT5SGhYeAD6uejlBG8tFJf-b3RO_To,10985
+scripts/promptfoo_regression_gate.py,sha256=hy50dHqPvMpA19UsUiDK41qZcTN5Sg_EakEAXA67Nhk,5861
+scripts/render_agent_prompts.py,sha256=-SP12hhw4u9s-cx79qyA8GvVEVDa12vckMIVV2R-Qzw,1948
+scripts/claude_hooks/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+scripts/claude_hooks/state_manager.py,sha256=DCsespEIVl015Zz4DYbaRc_52yg5L8kAbIjLrarMk9Q,18418
+cherry_docs-0.2.0.dist-info/METADATA,sha256=_SAeCP9SSfNBmYE3Xd_HDeVm68U1i48xSAWsiFlUupM,4137
+cherry_docs-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+cherry_docs-0.2.0.dist-info/entry_points.txt,sha256=8dydb3U_sVhcXNytyTUFbwVr3zpT_98TN4yLvQZOqvo,120
+cherry_docs-0.2.0.dist-info/top_level.txt,sha256=wtvfFLYf6tx66P5KqfU0pBNxSoctKviWbW46IxsLRe0,23
+cherry_docs-0.2.0.dist-info/RECORD,,

cherry_docs-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cherry_docs-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+cherry = cherrydocs.cli:main
+cherry-docs-mcp = cherrydocs.mcp:main
+cherry-hook = cherrydocs.hook:main

cherry_docs-0.2.0.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+app
+cherrydocs
+scripts

cherrydocs/__init__.py

@@ -0,0 +1,3 @@
+"""CherryDocs — local-first AI memory for Claude Code."""
+
+__version__ = "0.1.0"

cherrydocs/cli.py

@@ -0,0 +1,213 @@
+"""Entry point for the `cherry` CLI command.
+
+Subcommands:
+    cherry install      — wire CherryDocs into Claude Code globally
+    cherry status       — show current hook + MCP health
+    cherry eval         — evaluate memory quality across all projects
+    cherry uninstall    — remove global hooks and MCP server entry
+    cherry why <file>   — show memories anchored to commits that touched <file>
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_PKG_ROOT = Path(__file__).resolve().parent.parent
+if str(_PKG_ROOT) not in sys.path:
+    sys.path.insert(0, str(_PKG_ROOT))
+
+
+def main() -> None:
+    args = sys.argv[1:]
+    if not args or args[0] in ("-h", "--help"):
+        _usage()
+        sys.exit(0)
+
+    cmd = args[0]
+    if cmd == "install":
+        from scripts.install import main as _install  # noqa: PLC0415
+        sys.exit(_install())
+    elif cmd == "status":
+        _status()
+    elif cmd == "eval":
+        from scripts.eval_projects import main as _eval  # noqa: PLC0415
+        sys.argv = ["cherry", *args[1:]]
+        sys.exit(_eval())
+    elif cmd == "uninstall":
+        _uninstall()
+    elif cmd == "why":
+        _why(args[1:])
+    else:
+        print(f"cherry: unknown command '{cmd}'", file=sys.stderr)
+        _usage()
+        sys.exit(1)
+
+
+def _usage() -> None:
+    print(
+        "Usage: cherry <command>\n"
+        "\n"
+        "Commands:\n"
+        "  install          Wire CherryDocs into Claude Code globally\n"
+        "  status           Show current hook + MCP health\n"
+        "  eval             Evaluate memory quality across all projects\n"
+        "  eval --no-llm    Heuristic only (no Ollama required)\n"
+        "  eval --project X Evaluate a single project\n"
+        "  uninstall        Remove global hooks and MCP entry\n"
+        "  why <file>       Show memories anchored to commits that touched <file>\n"
+    )
+
+
+def _status() -> None:
+    import json
+    import os
+    import shutil
+    from pathlib import Path
+
+    settings_path = Path.home() / ".claude" / "settings.json"
+    has_hooks = False
+    if settings_path.exists():
+        try:
+            d = json.loads(settings_path.read_text())
+            hooks = d.get("hooks", {})
+            has_hooks = any(
+                "state_manager" in h.get("command", "") or "cherry-hook" in h.get("command", "")
+                for event in hooks.values()
+                for group in event
+                for h in group.get("hooks", [])
+            )
+        except Exception:
+            pass
+
+    mcp_cmd = shutil.which("cherry-docs-mcp") or shutil.which("cherry-hook")
+    central = Path.home() / ".cherrydocs" / "capture"
+
+    explicit = os.getenv("CHERRY_DISTILL_PROVIDER", "").strip().lower()
+    if explicit == "anthropic" or (not explicit and os.getenv("ANTHROPIC_API_KEY")):
+        model = os.getenv("CHERRY_ANTHROPIC_MODEL", "claude-3-5-haiku-20241022")
+        provider_line = f"✓ Anthropic ({model})"
+    else:
+        model = os.getenv("CHERRY_OLLAMA_MODEL", "qwen2.5:7b-instruct")
+        provider_line = f"✓ Ollama local ({model})  — set ANTHROPIC_API_KEY for prod"
+
+    print(f"Hooks in ~/.claude/settings.json : {'✓' if has_hooks else '✗ missing — run cherry install'}")
+    print(f"cherry-docs-mcp in PATH          : {'✓' if mcp_cmd else '✗ missing'}")
+    print(f"Central capture store            : {'✓' if central.exists() else '✗ missing — run cherry install'}")
+    print(f"Distillation provider            : {provider_line}")
+
+
+def _uninstall() -> None:
+    import json
+    import subprocess
+    from pathlib import Path
+
+    # Remove MCP
+    subprocess.run(["claude", "mcp", "remove", "cherry-docs", "-s", "user"], check=False)
+    print("→ Removed cherry-docs MCP (user scope)")
+
+    # Remove hooks from ~/.claude/settings.json
+    settings_path = Path.home() / ".claude" / "settings.json"
+    if settings_path.exists():
+        try:
+            d = json.loads(settings_path.read_text())
+            hooks = d.get("hooks", {})
+            for event in list(hooks.keys()):
+                hooks[event] = [
+                    g for g in hooks[event]
+                    if not any(
+                        "state_manager" in h.get("command", "") or "cherry-hook" in h.get("command", "")
+                        for h in g.get("hooks", [])
+                    )
+                ]
+                if not hooks[event]:
+                    del hooks[event]
+            d["hooks"] = hooks
+            settings_path.write_text(json.dumps(d, indent=2))
+            print("→ Removed hooks from ~/.claude/settings.json")
+        except Exception as e:
+            print(f"  ✗ Could not update settings: {e}")
+    print("✅ Uninstalled.")
+
+
+def _why(args: list[str]) -> None:
+    """Show memories anchored to commits that touched <file>."""
+    import json
+    import os
+    import subprocess
+    from pathlib import Path
+
+    if not args:
+        print("Usage: cherry why <file>", file=sys.stderr)
+        sys.exit(1)
+
+    target = args[0]
+
+    # Collect commit hashes that touched the file.
+    try:
+        result = subprocess.run(
+            ["git", "log", "--pretty=format:%H %h", "--", target],
+            capture_output=True, text=True, check=True, timeout=5,
+        )
+        commit_pairs = [line.split() for line in result.stdout.strip().splitlines() if line.strip()]
+        long_hashes = {pair[0] for pair in commit_pairs if pair}
+        short_hashes = {pair[1] for pair in commit_pairs if len(pair) > 1}
+        all_hashes = long_hashes | short_hashes
+    except Exception as exc:
+        print(f"cherry why: git log failed — {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    if not all_hashes:
+        print(f"No commits found touching '{target}' in this repository.")
+        sys.exit(0)
+
+    # Detect project id.
+    try:
+        from app.repo_scope import normalize_project_id
+        from app.services.capture_core import capture_repo_context
+        ctx = capture_repo_context(os.getcwd())
+        project_id = normalize_project_id(ctx.get("repo") or Path(os.getcwd()).name)
+    except Exception:
+        project_id = Path(os.getcwd()).name
+
+    # Load promoted memories.
+    promoted_root = Path(os.environ.get("CHERRY_PROMOTED_ROOT", str(Path.home() / ".cherrydocs" / "promoted")))
+    store_file = promoted_root / f"{project_id}.json"
+    if not store_file.exists():
+        print(f"No promoted memories found for project '{project_id}' ({store_file}).")
+        sys.exit(0)
+
+    try:
+        records = json.loads(store_file.read_text(encoding="utf-8"))
+        if not isinstance(records, list):
+            records = records.get("records", [])
+    except Exception as exc:
+        print(f"cherry why: could not read store — {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    # Filter by commit overlap.
+    hits = [
+        r for r in records
+        if isinstance(r, dict) and r.get("commit") and r["commit"] in all_hashes
+    ]
+
+    if not hits:
+        print(
+            f"No commit-anchored memories found for '{target}' in project '{project_id}'.\n"
+            f"({len(all_hashes)} commit(s) checked, {len(records)} memories in store)"
+        )
+        sys.exit(0)
+
+    print(f"Memories anchored to commits touching '{target}' [{project_id}]:\n")
+    for record in hits:
+        kind = record.get("kind", "?")
+        mtype = record.get("memory_type", "?")
+        summary = record.get("summary", "")
+        rationale = record.get("rationale", "")
+        commit = record.get("commit", "")
+        confidence = record.get("confidence", 0.0)
+        print(f"  [{mtype}/{kind}] {summary}")
+        if rationale:
+            print(f"    why: {rationale}")
+        print(f"    commit: {commit}  confidence: {confidence:.2f}")
+        print()

cherrydocs/hook.py

@@ -0,0 +1,27 @@
+"""Entry point for the cherry-hook CLI command.
+
+Delegates to scripts/claude_hooks/state_manager.py so Claude Code hooks work
+when cherry-docs is installed as a package (not run from source).
+
+Usage (set by Claude Code hooks):
+    cherry-hook session-start
+    cherry-hook post-tool-use
+    cherry-hook stop
+    cherry-hook reset
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# Ensure the installed package root is on sys.path so app.* imports work.
+_PKG_ROOT = Path(__file__).resolve().parent.parent
+if str(_PKG_ROOT) not in sys.path:
+    sys.path.insert(0, str(_PKG_ROOT))
+
+
+def main() -> None:
+    # Import and delegate — state_manager uses its own __file__ to find ROOT.
+    from scripts.claude_hooks import state_manager  # noqa: PLC0415
+    sys.exit(state_manager.main())

cherrydocs/mcp.py

@@ -0,0 +1,22 @@
+"""Entry point for the cherry-docs-mcp CLI command.
+
+Runs the MCP stdio server. Used when cherry-docs is installed as a package:
+    claude mcp add cherry-docs cherry-docs-mcp --scope user
+
+Instead of the source-path form:
+    claude mcp add cherry-docs python /absolute/path/to/mcp_server.py
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_PKG_ROOT = Path(__file__).resolve().parent.parent
+if str(_PKG_ROOT) not in sys.path:
+    sys.path.insert(0, str(_PKG_ROOT))
+
+
+def main() -> None:
+    import mcp_server  # noqa: PLC0415
+    mcp_server.run()

scripts/auto_promote_capture.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+"""Auto-promote recent captured sessions into durable CherryDocs memory."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from app.services.auto_promote_sessions import AutoPromotionPolicy, auto_promote_captured_sessions
+from app.services.memory_providers import OllamaMemoryProvider, resolve_provider
+from app.services.promoted_memory_store import DEFAULT_PROMOTED_ROOT
+
+_HOME_CHERRY = Path.home() / ".cherrydocs"
+_DEFAULT_BUFFER = os.environ.get("CHERRY_CAPTURE_BUFFER_DIR", str(_HOME_CHERRY / "capture"))
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="CherryDocs auto-promote recent captured sessions")
+    parser.add_argument("--project-id", required=True, help="Project id to promote into")
+    parser.add_argument("--buffer-dir", default=_DEFAULT_BUFFER, help="Capture buffer directory")
+    parser.add_argument("--promoted-root", default=DEFAULT_PROMOTED_ROOT, help="Promoted memory store root")
+    parser.add_argument("--model", default="qwen2.5:7b-instruct", help="Ollama model name")
+    parser.add_argument("--project-hint", help="Optional project label for the extraction prompt")
+    parser.add_argument("--memory-profile", default="default",
+                        help="Prompt profile (default, noise_strict, verification_first)")
+    parser.add_argument("--branch", help="Optional branch filter")
+    parser.add_argument("--min-event-count", type=int, default=3)
+    parser.add_argument("--min-candidate-confidence", type=float, default=0.8)
+    parser.add_argument("--max-sessions", type=int, default=10)
+    parser.add_argument("--commit-hash", default=None, help="Git commit hash to anchor promoted memories to")
+    return parser
+
+
+def main() -> int:
+    args = _parser().parse_args()
+    report = auto_promote_captured_sessions(
+        project_id=args.project_id,
+        buffer_dir=args.buffer_dir,
+        promoted_root=args.promoted_root,
+        provider=OllamaMemoryProvider(model=args.model),
+        project_hint=args.project_hint,
+        memory_profile=args.memory_profile,
+        branch=args.branch,
+        commit=args.commit_hash or None,
+        policy=AutoPromotionPolicy(
+            min_event_count=args.min_event_count,
+            min_candidate_confidence=args.min_candidate_confidence,
+            max_sessions=args.max_sessions,
+        ),
+    )
+    print(json.dumps(report.model_dump(mode="json"), indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())