corkern 2.0.0rc2__py3-none-any.whl

corkern/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.0.0rc2"

corkern/claude_commands/corkern-distill.md

@@ -0,0 +1,12 @@
+Run `corkern distill` to synthesise cross-project insights from all corkern memory files.
+
+Steps:
+1. Ask the user whether to run interactively or auto-save:
+   - **Auto** (saves to `memory/global/synthesis.md`): run `corkern distill --auto`
+   - **Interactive** (review with Claude): run `corkern distill`
+2. Run the chosen command via Bash.
+3. If `--auto` was used, read `memory/global/synthesis.md` in the knowledge repo (`$CORKERN_MEMORY_DIR`) and summarise the findings to the user.
+4. For any **Stale Candidates** identified: offer to add `status: stale` to their frontmatter — one file at a time, with user confirmation for each.
+5. For any **Universal Principles** identified (rules appearing in 2+ projects): offer to add them to `memory/global/principles.md` and remove them from the individual project memory files — with user confirmation.
+
+Always confirm with the user before modifying any memory file.

corkern/claude_commands/corkern-harvest.md

@@ -0,0 +1,13 @@
+Run `corkern harvest` to extract memories from past Claude conversations for the current project.
+
+Steps:
+1. Run `corkern prune` first to show which conversations are new, changed or already harvested.
+2. Run `corkern harvest` (detects the project from the current directory). With several conversations it asks which to process — answer `all` or numbers.
+3. Review the new memory files it lists in `memory/<slug>/` of the knowledge repo; they are already added to `MEMORY.md`. Existing files are never overwritten (a new version gets a `.harvested-<time>` suffix) — merge those with the user.
+4. If it saved a `harvested-<date>.md` bulk file instead, run `corkern refine`.
+
+Flags:
+- `corkern harvest --interactive` — opens an interactive Claude session with the conversations as context, so the user can add their own recollections.
+- `corkern harvest --all` — reprocesses already harvested conversations.
+
+Secrets in transcripts are replaced by a marker before anything is committed. After harvesting, run `/corkern-distill` to check whether any extracted memories should be promoted to global.

corkern/claude_commands/corkern-memory-prune.md

@@ -0,0 +1,15 @@
+Run `corkern memory-prune` to archive expired or stale memory files for the current project.
+
+Steps:
+1. Run `corkern memory-prune --dry-run` to preview candidates without touching anything.
+2. Show the user the list of expired/stale files found.
+3. Explain what each candidate is and why it was flagged (expired date, status: stale marker).
+4. Ask the user to confirm before proceeding.
+5. If confirmed, run `corkern memory-prune` (which asks for confirmation again in the terminal).
+
+Notes:
+- Files with `expires: YYYY-MM-DD` in frontmatter are candidates after that date passes.
+- Files with `status: stale` in frontmatter are candidates regardless of date.
+- Archived files go to `memory/<slug>/archive/` — never deleted, always recoverable.
+- To mark a file stale: add `status: stale` inside its frontmatter `metadata:` block.
+- To mark a file with an expiry: add `expires: YYYY-MM-DD` inside `metadata:`.

corkern/claude_commands/corkern-status.md

@@ -0,0 +1,6 @@
+Run `corkern status` to check corkern's health.
+
+- `corkern status` — summary: sync, signing and trust, secrets removed, memory index sizes, hooks, projects.
+- `corkern status -v` — full diagnostics: every project's wiring, hook scripts, slash commands, Claude Code memory folders not synced into corkern, knowledge graphs per project, IWE.
+
+Run this when something seems off with memory sync, or after setting up on a new machine. Report problems (✗) and warnings (!) to the user with the fix each line suggests.

corkern/claude_print.py

@@ -0,0 +1,30 @@
+"""Text-in/text-out `claude -p` calls (distill --auto, harvest, refine).
+
+The prompt carries memory text that teammates wrote, so these calls get nothing beyond the
+text: no tools at all (`--tools ""`), only the user's own settings (`--setting-sources user`:
+no project or local settings, so no hooks from a repo), no MCP servers (`--strict-mcp-config`
+without `--mcp-config`), and they start in a fresh private empty folder instead of the
+knowledge repo (guard.capture_tool_isolated). Flags checked against Claude Code 2.1.285 and
+2.1.287 (`claude --help`).
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from corkern import guard
+
+ISOLATION = ("--setting-sources", "user", "--strict-mcp-config", "--tools", "")
+
+
+def ask(claude: str, prompt: str, model: str | None = None) -> "guard.subprocess.CompletedProcess":
+    argv = [claude, "-p", *ISOLATION, *(["--model", model] if model else [])]
+    return guard.capture_tool_isolated(argv, prompt)
+
+
+def interactive_cwd(preferred: Path | None = None) -> Path:
+    """Where an interactive claude session starts: `preferred` (default: the current folder)
+    unless it is missing or inside the knowledge repo — then $HOME."""
+    where = Path(preferred) if preferred is not None else Path.cwd()
+    if not where.is_dir() or guard.in_knowledge_repo(where):
+        return Path.home()
+    return where

corkern/commands/add_cmd.py

@@ -0,0 +1,104 @@
+import sys
+from pathlib import Path
+import typer
+from corkern import guard
+from corkern.commands.signing_cmd import _ask
+from corkern.config import (
+    UnstorablePath, _parse_conf, check_projects, confirm_projects, conf_entries, load_config,
+    resolve_project_path, same_path, store_project_path, valid_slug,
+)
+
+
+def _fail(message: str) -> None:
+    typer.echo(message, err=True)
+    raise typer.Exit(1)
+
+
+def add_project(
+    slug: str = typer.Argument(None, help="Project slug (default: the folder name, like v1)"),
+    path: Path = typer.Argument(None, help="Project path (default: cwd)"),
+    confirm_all: bool = typer.Option(False, "--confirm-all",
+                                     help="List every project not confirmed on this machine; confirm them after one question"),
+    confirm_listed: bool = typer.Option(False, "--confirm-listed",
+                                        help="Confirm the projects whose path matches the slug:path lines on stdin "
+                                             "(this machine's own v1 registry; used by migrate/3)"),
+) -> None:
+    """Add a project to tracking — or confirm on this machine a project that is already registered.
+
+    corkern.conf is shared: a project's path is used to read its Claude Code conversations
+    (harvest, prune) or to wire its folder (init-device) only once this machine confirmed it.
+    """
+    if confirm_all or confirm_listed:
+        _confirm_many(confirm_listed)
+        return
+    if slug is None:
+        slug = (path or Path(".")).resolve().name
+    if not valid_slug(slug):
+        _fail(f"Invalid slug {slug!r}: use letters, digits, '.', '_' or '-', "
+              "starting with a letter or digit.")
+    resolved = (path or Path(".")).resolve()
+    try:
+        stored = store_project_path(resolved)
+    except UnstorablePath as e:
+        _fail(f"Invalid path {str(resolved)!r}: {e}.")
+
+    repo, projects = load_config()
+    # Like v1: any line for the slug counts, including other devices' (e.g. Windows) lines
+    if slug in {s for s, _ in conf_entries(guard.read_text(repo.conf_file))}:
+        check = check_projects(repo.path).get(slug)
+        match = next((p for p in (check.candidates if check else ()) if same_path(p, resolved)), None)
+        if match is None:
+            _fail(f"Slug '{slug}' already exists. Remove it first.")
+        _confirm(repo.path, {slug: match})
+        typer.echo(f"Confirmed {slug} → {match} on this machine")
+        return
+    for other, other_path in projects.items():
+        if other_path.resolve() == resolved:
+            _fail(f"Path '{resolved}' is already tracked under slug '{other}'.")
+
+    _confirm(repo.path, {slug: resolve_project_path(stored)})
+    guard.append_text(repo.conf_file, f"{slug}:{stored}\n")
+    typer.echo(f"Added {slug} → {resolved}")
+
+
+def _confirm(repo: Path, items: dict[str, Path]) -> None:
+    try:
+        confirm_projects(repo, items)
+    except (OSError, guard.V1ProtectedError) as e:
+        _fail(f"Could not record the confirmation in {repo}/.git/corkern: {e}")
+
+
+def _confirm_many(listed: bool) -> None:
+    repo, _ = load_config()
+    open_ = [c for c in check_projects(repo.path).values() if not c.confirmed]
+    if listed:
+        theirs = _parse_conf(sys.stdin.read(), "stdin")
+        found: dict[str, Path] = {}
+        for c in open_:
+            if c.slug not in theirs:
+                continue
+            match = next((p for p in c.candidates if same_path(p, theirs[c.slug])), None)
+            if match is None:
+                typer.echo(f"  ! {c.slug}: the registry's path differs from the listed one "
+                           f"({', '.join(map(str, c.candidates))} ≠ {theirs[c.slug]}) — not confirmed")
+            else:
+                found[c.slug] = match
+        _confirm(repo.path, found)
+        for slug, p in sorted(found.items()):
+            typer.echo(f"  ✓ {slug} → {p} confirmed on this machine")
+        return
+    single = [c for c in open_ if not c.duplicate]
+    if not open_:
+        typer.echo("✓ Every project is confirmed on this machine.")
+        return
+    typer.echo("Not confirmed on this machine (corkern.conf is shared — check each path is yours):")
+    for c in single:
+        typer.echo(f"  {c.slug} → {c.candidates[0]}    ({c.lines[0]})")
+    for c in open_:
+        if c.duplicate:
+            typer.echo(f"  ! {c.explain()}")
+    if single and _ask(f"Confirm these {len(single)} project(s) on this machine? [y/N] ", False):
+        _confirm(repo.path, {c.slug: c.candidates[0] for c in single})
+        typer.echo(f"✓ {len(single)} project(s) confirmed")
+    elif single:
+        typer.echo("Nothing confirmed.")

corkern/commands/ai_cmd.py

@@ -0,0 +1,238 @@
+"""get-AIinstructions and session-context — what Claude sees at the start of a session.
+
+`session-context` is called by the SessionStart hook; its stdout is injected into Claude's
+context, so it prints only useful text and never fails loudly.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime, timedelta
+from pathlib import Path
+
+import typer
+
+from corkern import devices, guard
+from corkern.commands import metrics_cmd
+from corkern.commands.reminders import GLOBAL, format_items, open_items, read_todo
+from corkern.commands.secrets_cmd import log_entries
+from corkern.commands.trust_cmd import UNTRUSTED, held_entries
+from corkern.config import NOT_CONFIRMED, check_projects, conf_entries, load_config, valid_slug
+from corkern.knowledge_repo import repo_symlinks, shown, tracked_machine_local
+from corkern.memory_index import usage
+
+PROG = "corkern"
+
+
+def instructions_text() -> str:
+    repo, _ = load_config()
+    rows = []
+    for slug, raw in conf_entries(repo.read_conf()):
+        if valid_slug(slug):
+            rows.append(f"- `{slug}` → {raw.strip() or '~ (home)'}")
+    projects = "\n".join(rows) or "- (none yet)"
+    kr = repo.path
+    return f"""# Corkern — AI Instructions
+
+Corkern is this developer's memory sync system for Claude Code. A private git
+"knowledge repo" keeps Claude's memory files in sync across machines automatically.
+
+## What it does
+
+1. Pulls other devices' memories when a session starts, and between replies
+2. Commits each memory write immediately, with the file name in the commit message
+3. Pushes memories (global ones right away, project ones at session end)
+4. Never blocks Claude and never loses text: conflicting edits are kept side by side
+   as `<name>.conflict-<host>-<time>.md` — mention these to the user if you see them
+
+## Knowledge repo
+
+  `{kr}`
+
+Memory files live under `{kr}/memory/<slug>/`. Global (cross-project) memories live
+under `{kr}/memory/global/`.
+
+## Tracked projects
+
+{projects}
+
+## CLI ({PROG})
+
+  {PROG} list | ls                    Tracked projects and whether their paths exist
+  {PROG} add <slug> [path]            Track a project (default path: current directory)
+  {PROG} remove | rm <slug>           Stop tracking a project
+  {PROG} status | doctor              Knowledge repo and project overview
+  {PROG} remind "text" [slug]         Add a reminder (default: current project, else global)
+  {PROG} todos | todo [slug|--all]    List open reminders
+  {PROG} done <n> [slug]              Mark reminder n as done
+  {PROG} sessions [slug]              Recent session notes
+  {PROG} log [slug]                   Git history of a project's memory
+  {PROG} signing                      This machine's commit-signing key
+  {PROG} trust                        Which devices' memories this machine accepts
+  {PROG} secrets [--scan]             Secrets removed before commit / check the repo
+  {PROG} init-device                  Point Claude Code's memory for each project here
+  {PROG} iwe [--setup|--install]      IWE knowledge graph over the memories (MCP server)
+  {PROG} graphify [slug] [--install] [--full]  Build/update the project knowledge graph
+  {PROG} crg [slug] [--install]                code-review-graph (fast, AST-only)
+  {PROG} metrics                             Memory size, context pressure, growth
+  {PROG} harvest [slug] [--all] [-i]         Memories from past Claude conversations
+  {PROG} refine [slug]                       Split harvested-*.md bulk files
+  {PROG} prune [slug]                        Conversation inventory (harvested / pending)
+  {PROG} distill [--auto]                    Cross-project synthesis with Claude
+                                               (confirm with the user first)
+  {PROG} memory-prune [slug] [--dry-run]       Archive expired/stale memories (never deletes;
+                                               confirm with the user first)
+  {PROG} get-AIinstructions | ai      This document
+
+## Secrets
+
+Never write passwords, tokens or keys into memory files. If one slips in, corkern replaces it
+with `[secret removed by corkern: <kind>]` before the commit; the original stays on this
+machine only. Tell the user when you see such a marker.
+
+## Reminders
+
+Add a reminder when work starts but won't finish this session, or when the user wants
+to come back to something; clear it with `{PROG} done <n> [slug]` when the work is done.
+Open reminders are shown at the start of every session.
+
+## Session notes
+
+At the end of significant work, write a short note (5–10 bullets: done, next, decisions):
+
+  `{kr}/memory/<slug>/sessions/YYYY-MM-DD-HHmm.md`
+
+It is committed and synced automatically; the next session on any machine sees it.
+"""
+
+
+def get_ai_instructions() -> None:
+    """Print the corkern context document for AI assistants."""
+    typer.echo(instructions_text())
+
+
+def _box(title: str, rows: list[str], footer: str | None = None) -> str:
+    lines = [f"╔═ Corkern: {title} " + "═" * max(3, 50 - len(title))]
+    lines += [f"║{row}" for row in rows]
+    if footer:
+        lines.append(f"║  {footer}")
+    lines.append("╚" + "═" * 55)
+    return "\n".join(lines)
+
+
+def _todo_box(repo, slug: str) -> str | None:
+    lines = read_todo(repo, slug)
+    if not lines or not open_items(lines):
+        return None
+    return _box(f"open reminders [{slug}]", format_items(lines),
+                f"→ clear with: {PROG} done <n> {slug}")
+
+
+def _surfacing_files(repo, slug: str) -> str | None:
+    """Memory files marked `surfaces: true` in their frontmatter (v1 'actionable' files)."""
+    rows = []
+    folder = repo.memory_dir / slug
+    for name, _ in sorted(guard.list_files(folder, ".md")):
+        if name in ("MEMORY.md", "todo.md"):
+            continue
+        head = guard.read_text(folder / name).split("\n")[:10]
+        if any("".join(line.split()) == "surfaces:true" for line in head):
+            desc = next((line.split(":", 1)[1].strip().strip('"') for line in head
+                         if line.startswith("description:")), "")
+            rows.append(f"  → {name}" + (f" — {desc}" if desc else ""))
+    return _box(f"actionable memory files [{slug}]", rows) if rows else None
+
+
+def _unconfirmed_box(checks) -> list[str]:
+    open_ = sorted(s for s, c in checks.items() if not c.confirmed)
+    if not open_:
+        return []
+    return [_box(f"{len(open_)} project(s) {NOT_CONFIRMED}", [
+        f"  {' '.join(open_[:10])}" + (" …" if len(open_) > 10 else ""),
+        "  corkern.conf is shared; until this machine confirms a project's path, corkern does not",
+        "  read its conversations, wire its folder or show its reminders. Tell the user."],
+        f"→ {PROG} add <slug> <path>, or {PROG} init-device to confirm")]
+
+
+def _safety_boxes(repo, slug: str | None) -> list[str]:
+    """Things the user must know at session start: held-back commits, removed secrets,
+    an index Claude Code no longer loads completely."""
+    boxes = []
+    links = repo_symlinks(repo.path)
+    if links:
+        boxes.append(_box("symlinks in the knowledge repo — held/ignored", [
+            "  These synced files are symlinks; corkern never follows them and treats them",
+            "  as absent (a link can point at any file on this machine):",
+            *[f"    {shown(rel)}" for rel in links[:10]],
+            *([f"    … and {len(links) - 10} more"] if len(links) > 10 else []),
+            "  Tell the user. Do not read or write them; replace them with regular files."],
+            f"→ {PROG} status lists them"))
+    tracked = tracked_machine_local(repo.path)
+    if tracked:
+        boxes.append(_box("per-machine files tracked in the knowledge repo", [
+            *[f"  tracked per-machine file: {shown(rel)} — remove it on the remote" for rel in tracked[:10]],
+            "  corkern never stages them again (this machine's copy stays local). Tell the user."],
+            f"→ {PROG} status"))
+    entries = held_entries(repo.path)
+    if entries:
+        untrusted = len({sha for sha, reason in entries if reason == UNTRUSTED})
+        reasons = list(dict.fromkeys(reason for sha, reason in entries if reason != UNTRUSTED))
+        boxes.append(_box("memories held back", [
+            "  Nothing new from the remote was loaded this session. Reasons:",
+            *([f"  - {untrusted} commit(s) not signed by a device this machine trusts"] if untrusted else []),
+            *[f"  - {shown(reason)}" for reason in reasons[:8]],
+            "  Tell the user; never recreate held content by hand. Review with:"],
+            f"→ {PROG} trust"))
+    recent = [e for e in log_entries()
+              if e[0] >= f"{datetime.now() - timedelta(days=3):%Y-%m-%d %H:%M:%S}"]
+    if recent:
+        rows = [f"  {when[:16]}  {rel}  ({kinds})" for when, rel, kinds, _ in recent[-5:]]
+        boxes.append(_box("secrets removed before commit", [
+            "  A secret was written into a memory and replaced by a marker before syncing:",
+            *rows, "  Tell the user, and do not write secrets into memory files."],
+            f"→ originals stay on this machine: {PROG} secrets"))
+    index = guard.read_shared(repo.memory_dir / slug / "MEMORY.md") if slug else None
+    if index is not None:
+        u = usage(index)
+        if u.over or u.near:
+            state = "OVER" if u.over else "close to"
+            boxes.append(_box(f"MEMORY.md {state} Claude Code's read limit [{slug}]", [
+                f"  {u.describe()}" + (" — entries past it are not loaded." if u.over else "."),
+                "  Please shorten it now: one line per entry, details in topic files,",
+                "  merge or drop stale entries (lines also arrive from other devices)."]))
+    return boxes
+
+
+def _cwd_from_hook_stdin() -> Path:
+    if not sys.stdin.isatty():
+        try:
+            event = json.loads(sys.stdin.read() or "{}")
+            if isinstance(event, dict) and event.get("cwd"):
+                return Path(event["cwd"])
+        except (json.JSONDecodeError, OSError):
+            pass
+    return Path.cwd()
+
+
+def session_context() -> None:
+    """(For the SessionStart hook) instructions, open reminders, actionable files."""
+    repo, projects = load_config()
+    cwd = _cwd_from_hook_stdin().resolve()
+    here = next((s for s, p in projects.items() if p.resolve() == cwd), None)
+    checks = check_projects(repo.path)
+    # only a path this machine confirmed brings a project's reminders and files into the session
+    slug = next((s for s, c in checks.items() if c.confirmed and c.path.resolve() == cwd), None)
+    text = instructions_text()
+    try:
+        devices.update(repo, projects, touch=here)  # this device's manifest: last seen here
+    except (OSError, guard.SymlinkInRepoError):
+        pass                                       # never break session start
+    if here:
+        try:
+            metrics_cmd.record(repo, here, text)   # a session count, no project content
+        except (OSError, guard.SymlinkInRepoError):
+            pass                                   # metrics must never break session start
+    parts = [text, *_safety_boxes(repo, slug), *_unconfirmed_box(checks)]
+    for s in [GLOBAL] + ([slug] if slug and slug != GLOBAL else []):
+        parts += [box for box in (_todo_box(repo, s), _surfacing_files(repo, s)) if box]
+    typer.echo("\n".join(parts))

corkern/commands/crg_cmd.py

@@ -0,0 +1,60 @@
+"""crg — build or install code-review-graph for a project (v1 `corkern crg` parity).
+
+Same safety rules as graphify: projects inside v1 / ~/.claude are refused, and --install is
+refused when it would write a protected place (code-review-graph install writes the
+project's .claude/settings.json, .mcp.json and CLAUDE.md).
+"""
+from __future__ import annotations
+
+import typer
+
+from corkern import guard
+from corkern.commands.reminders import fail, slug_for_cwd
+from corkern.config import check_projects, load_config
+
+TOOL = "code-review-graph"
+
+
+def crg(
+    slug: str = typer.Argument(None, help="Project slug (default: current project)"),
+    install: bool = typer.Option(False, "--install", help="Install MCP server, hooks, CLAUDE.md"),
+) -> None:
+    """Build/update the project's code-review-graph (fast, AST-only, no LLM)."""
+    repo, projects = load_config()
+    slug = slug or slug_for_cwd(projects)
+    if not slug:
+        fail("Could not detect project slug. Usage: corkern crg [slug] [--install]\n"
+             f"    Known slugs: {' '.join(sorted(projects))}")
+    if slug not in projects:
+        fail(f"Slug '{slug}' not found in corkern.conf")
+    check = check_projects(repo.path)[slug]      # corkern.conf is shared: only a path confirmed here
+    if not check.confirmed:
+        fail(f"Refusing to run code-review-graph in the folder of {check.explain()}")
+    project = check.path
+    if not project.is_dir():
+        fail(f"Project directory not found: {project}")
+    guard.assert_safe(project)
+    exe = guard.which(TOOL)
+    if not exe:
+        fail(f"{TOOL} is not installed.\n    Install it with: pipx install {TOOL}")
+
+    typer.echo(f"\ncorkern crg: {slug}\n  Project: {project}")
+    if install:
+        try:
+            guard.assert_safe(project / ".claude")
+        except guard.V1ProtectedError:
+            fail(f"Refusing --install for '{slug}': {TOOL} would write {project / '.claude'}, "
+                 "which is protected (global Claude settings).")
+        if guard.run_tool(project, [exe, "install"]) != 0:
+            fail(f"{TOOL} install failed")
+        typer.echo(f"  ✓ {TOOL} installed (MCP server + hooks + CLAUDE.md) — restart Claude Code")
+        return
+
+    db = project / ".code-review-graph"
+    typer.echo(f"  {'Updating' if db.exists() else 'Building'} the graph (AST only, no LLM)...")
+    rc = guard.run_tool(project, [exe, "build", "--repo", str(project)])
+    if rc != 0:
+        fail(f"{TOOL} build exited with code {rc}")
+    typer.echo(f"  ✓ Graph: {db}")
+    if not (project / ".mcp.json").exists():
+        typer.echo(f"  Next step — register it with Claude Code: corkern crg {slug} --install")

corkern/commands/distill_cmd.py

@@ -0,0 +1,106 @@
+"""distill — synthesise cross-project insights from all memories with Claude (v1 parity).
+
+  corkern distill           build the prompt, open an interactive Claude session with it
+  corkern distill --auto    run Claude non-interactively → memory/global/synthesis.md
+
+Fixes vs v1 distill.sh:
+- the previous synthesis.md is only replaced when Claude succeeds (v1 truncated it before
+  running Claude, so a failed run destroyed the last synthesis)
+- no crash after saving (v1 referenced $BRAIN — a variable left over from the tool's old name
+  "brain" that is never set — under `set -u`)
+- the project list in the prompt comes from corkern.conf (v1 hard-coded it)
+- the prompt file (a copy of every memory) is written to this machine's state dir (0600), never
+  into the knowledge repo, where a synced symlink could redirect the write
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+import typer
+
+from corkern import claude_print, guard
+from corkern.commands.reminders import fail
+from corkern.config import conf_entries, load_config, state_dir, valid_slug
+
+PROMPT_NAME = ".distill-prompt.md"
+
+HEADER = """You are analyzing a personal knowledge base ("corkern") that captures everything
+Claude Code has learned working with this developer across multiple projects.
+
+Memory files are organized as: memory/<project>/<topic>.md
+Projects present: {projects}
+
+Please produce a structured synthesis with these sections:
+
+## Universal Principles
+Rules or preferences that appear across 2+ projects (verbatim or in spirit).
+For each: quote the source project(s) and note if it should be added to global/CLAUDE.md.
+
+## Cross-Project Opportunities
+Insights from one project that would benefit others where NOT yet recorded.
+
+## Stale Candidates
+Memory files that appear outdated, superseded, or about completed work.
+For each: state why it may be stale.
+
+## Contradictions
+Rules or preferences that conflict between projects.
+For each: surface the tension and suggest resolution.
+
+## Who This Developer Is
+A short paragraph synthesising working style, values, and instincts from all evidence combined.
+Be specific — avoid generic statements.
+
+---
+MEMORY FILES:
+"""
+
+
+def build_prompt(repo) -> tuple[str, int]:
+    slugs = list(dict.fromkeys(s for s, _ in conf_entries(repo.read_conf())
+                               if valid_slug(s)))
+    files = guard.walk_files(repo.memory_dir, ".md")
+    parts = [HEADER.format(projects=", ".join([*slugs, "global"]))]
+    for f in files:
+        parts.append(f"\n=== {f.relative_to(repo.path)} ===\n{guard.read_text(f)}\n")
+    return "".join(parts), len(files)
+
+
+def distill(
+    auto: bool = typer.Option(False, "--auto", help="Run non-interactively → memory/global/synthesis.md"),
+    model: str = typer.Option(None, "--model", help="Claude model (default: Claude Code's default)"),
+) -> None:
+    """Synthesise cross-project insights from all memories with Claude."""
+    repo, _ = load_config()
+    typer.echo("=== Corkern Distill ===\n\nCollecting memories...")
+    prompt, count = build_prompt(repo)
+    prompt_file = state_dir() / PROMPT_NAME
+    guard.write_private(prompt_file, prompt)
+    typer.echo(f"✓ Collected {count} files ({len(prompt.encode())} bytes).\n")
+    claude = guard.which("claude")
+    model_args = ["--model", model] if model else []
+
+    if auto:
+        if not claude:
+            fail("'claude' CLI not found — install Claude Code or run without --auto.")
+        typer.echo("Running Claude analysis...")
+        result = claude_print.ask(claude, prompt, model)
+        if result.returncode != 0 or not result.stdout.strip():
+            fail(f"Claude failed (exit {result.returncode}) — previous synthesis.md left unchanged.")
+        now = datetime.now()
+        front = (f"---\nname: synthesis\ndescription: Cross-project synthesis — {now:%Y-%m-%d}\n"
+                 f"metadata:\n  type: reference\n  generated: {now:%Y-%m-%dT%H:%M}\n---\n\n")
+        guard.write_text(repo.memory_dir / "global" / "synthesis.md", front + result.stdout)
+        typer.echo("✓ Saved: memory/global/synthesis.md")
+        typer.echo("  (Committed and synced by the next corkern hook run.)")
+        return
+
+    typer.echo(f"Prompt saved: {prompt_file}\n")
+    if not claude:
+        typer.echo(f"Claude CLI not found. To analyse manually, paste {prompt_file} into any Claude session.")
+        return
+    typer.echo("Starting interactive Claude analysis session...\n"
+               "(Claude will open with all your memories as context.)\n")
+    # from where the user is — unless that is inside the knowledge repo (its .claude/ is shared)
+    guard.exec_tool([claude, "--append-system-prompt-file", str(prompt_file), *model_args],
+                    cwd=claude_print.interactive_cwd())