cairn-brain 0.2.1__py3-none-any.whl

cairn/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

cairn/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

cairn/agents.py

@@ -0,0 +1,538 @@
+"""Agent integrations: one MCP server + generated instructions, per detected agent, plus session capture and
+memory at session start.
+
+Every agent starts a session knowing the same thing: the Cairn brief (map hubs, active spec, principles, team
+knowledge) and the session-memory timeline (`agent_context`), computed for the repository it works in. Agents
+with a session-start hook (Claude Code, Gemini CLI, Codex, Cursor) and OpenCode (a plugin that adds it to the
+system prompt) get it fresh at session start. Agents that only read instruction files get it from an untracked
+file of their own (listed in `.git/info/exclude`, never committed), rewritten after each session summary, on
+`cairn sync` and when a memory is stored (`refresh_context`). Nothing dynamic goes into a committed file.
+Session capture rides on each agent's own hooks, written into the repository (`engines/recall/integrations.py`).
+
+Every write is idempotent and reversible: JSON configs are merged key-by-key, Markdown files get a
+marked block, and generated files carry a header so `cairn uninstall` removes exactly what it added.
+"""
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from . import shellcmd
+from .project import Project
+
+TEMPLATES = Path(__file__).resolve().parent / "templates"
+BEGIN, END = "<!-- cairn:begin -->", "<!-- cairn:end -->"
+GENERATED = "<!-- generated by cairn; safe to edit, removed by `cairn uninstall` -->"
+
+AGENTS = {
+    "claude": "Claude Code",
+    "codex": "Codex",
+    "cursor": "Cursor",
+    "gemini": "Gemini CLI",
+    "opencode": "OpenCode",
+    "copilot": "Copilot CLI",
+    "vscode": "VS Code / Copilot",
+    "windsurf": "Windsurf",
+    "antigravity": "Antigravity",
+}
+# Agents that only read instruction files: (untracked file, frontmatter, size limit). Copilot CLI and VS Code
+# read .github/instructions/*.instructions.md (Copilot CLI 1.0 ignores what its session hooks print);
+# Antigravity and Windsurf read always-on rules.
+CONTEXT_FILES = {
+    "copilot": (".github/instructions/cairn-context.instructions.md", '---\napplyTo: "**"\n---\n', None),
+    "vscode": (".github/instructions/cairn-context.instructions.md", '---\napplyTo: "**"\n---\n', None),
+    "antigravity": (".agents/rules/cairn-context.md", "---\ntrigger: always_on\n---\n", None),
+    "windsurf": (".windsurf/rules/cairn-context.md", "---\ntrigger: always_on\n---\n", 12_000),
+}
+# The files are plain Markdown: Copilot CLI drops unknown tags from instruction files together with their
+# content. The two HTML comments (which it drops cleanly) only mark the memory, so captured tool output
+# loses everything between them and memory is never built out of memory.
+CONTEXT_OPEN, CONTEXT_CLOSE = "<!-- cairn:memory:begin -->", "<!-- cairn:memory:end -->"
+CONTEXT_HEADING = "# Cairn: what this repository remembers"
+CONTEXT_NOTE = ("<!-- generated by cairn: this repository's memory for agents that read instruction files; "
+                "refreshed after each session summary and on `cairn sync`; never committed; removed by "
+                "`cairn uninstall` -->")
+MAP_IGNORE = "# cairn: agent hook folders\n.codex/\n.opencode/\n.github/hooks/\n"
+
+
+def command() -> tuple[str, list[str]]:
+    """How agents launch the MCP server. Prefer the portable `cairn` on PATH."""
+    if shutil.which("cairn"):
+        return "cairn", ["mcp"]
+    return sys.executable, ["-m", "cairn", "mcp"]
+
+
+def detect(project: Project) -> list[str]:
+    home, root = Path.home(), project.root
+    found = []
+    apps = Path("/Applications")
+    checks = {
+        "claude": [shutil.which("claude"), (home / ".claude").is_dir(), (root / ".claude").is_dir(), (root / "CLAUDE.md").exists()],
+        "codex": [shutil.which("codex"), (home / ".codex").is_dir()],
+        "cursor": [shutil.which("cursor"), shutil.which("cursor-agent"), (home / ".cursor").is_dir(),
+                   (root / ".cursor").is_dir()],
+        "gemini": [shutil.which("gemini"), (home / ".gemini").is_dir(), (root / "GEMINI.md").exists()],
+        "opencode": [shutil.which("opencode"), (home / ".config" / "opencode").is_dir(), (root / ".opencode").is_dir(),
+                     (root / "opencode.json").exists()],
+        "copilot": [shutil.which("copilot"), (home / ".copilot").is_dir()],
+        "vscode": [shutil.which("code"), (root / ".vscode").is_dir()],
+        "windsurf": [shutil.which("windsurf"), (home / ".codeium" / "windsurf").is_dir(), (root / ".windsurf").is_dir(),
+                     (apps / "Windsurf.app").exists()],
+        "antigravity": [shutil.which("agy"), shutil.which("antigravity"), (apps / "Antigravity.app").exists()],
+    }
+    for name, signals in checks.items():
+        if any(signals):
+            found.append(name)
+    return found
+
+
+def installed(project: Project) -> list[str]:
+    """Agents wired to this repository (not merely detected): their config launches the Cairn MCP server, or,
+    for agents Cairn reaches without MCP, their session-capture hooks are in place."""
+    root = project.root
+    configs = {"claude": (root / ".mcp.json", "mcpServers"), "cursor": (root / ".cursor" / "mcp.json", "mcpServers"),
+               "gemini": (root / ".gemini" / "settings.json", "mcpServers"),
+               "vscode": (root / ".vscode" / "mcp.json", "servers")}
+    found = []
+    for name in AGENTS:
+        if name == "codex":  # user-level config written by `codex mcp add`
+            cfg = Path.home() / ".codex" / "config.toml"
+            if cfg.exists() and "mcp_servers.cairn" in cfg.read_text(errors="replace"):
+                found.append(name)
+            continue
+        if name not in configs:  # no MCP entry: wired through capture hooks, or only through a context file
+            from .engines.recall import integrations as recall_hooks
+            state = recall_hooks.project_status(root).get(name)
+            if state["capture"] if state else _context_file(root, name) is not None:
+                found.append(name)
+            continue
+        path, key = configs[name]
+        try:
+            if "cairn" in json.loads(path.read_text()).get(key, {}):
+                found.append(name)
+        except (OSError, ValueError, AttributeError):
+            pass
+    return found
+
+
+# ---- file helpers ------------------------------------------------------------------------------------
+def upsert_block(path: Path, body: str) -> bool:
+    text = path.read_text() if path.exists() else ""
+    block = f"{BEGIN}\n{body.strip()}\n{END}"
+    if BEGIN in text and END in text:
+        new = text[: text.index(BEGIN)] + block + text[text.index(END) + len(END):]
+    else:
+        new = (text.rstrip() + "\n\n" if text.strip() else "") + block + "\n"
+    if new != text:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(new)
+        return True
+    return False
+
+
+def remove_block(path: Path) -> bool:
+    if not path.exists():
+        return False
+    text = path.read_text()
+    if BEGIN not in text:
+        return False
+    new = (text[: text.index(BEGIN)] + text[text.index(END) + len(END):]).strip()
+    if new:
+        path.write_text(new + "\n")
+    else:
+        path.unlink()
+    return True
+
+
+def merge_json(path: Path, mutate) -> bool:
+    try:
+        data = json.loads(path.read_text()) if path.exists() else {}
+    except json.JSONDecodeError:
+        return False  # never clobber a file we cannot parse
+    before = json.dumps(data, sort_keys=True)
+    mutate(data)
+    if json.dumps(data, sort_keys=True) != before:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(data, indent=2) + "\n")
+        return True
+    return False
+
+
+def write_generated(path: Path, content: str) -> bool:
+    if path.exists() and GENERATED not in path.read_text():
+        return False  # user-owned file with the same name: leave it
+    parts = content.split("---", 2)
+    if content.startswith("---") and len(parts) == 3:  # keep frontmatter first
+        content = f"---{parts[1]}---\n{GENERATED}{parts[2]}"
+    else:
+        content = f"{GENERATED}\n{content}"
+    if path.exists() and path.read_text() == content:
+        return False
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content)
+    return True
+
+
+def _is_ours(entry: object) -> bool:
+    """One hook entry Cairn wrote: its session-start brief or status line (the capture entries are recognised by
+    the session engine). Matched on the exact command shape, never on a path that merely contains "cairn"."""
+    cmd = str(entry.get("command") or "") if isinstance(entry, dict) else ""
+    return bool(re.search(r"(^|[\s\"'/])cairn( hook session-start| statusline)$|-m cairn (hook session-start|statusline)$",
+                          cmd.strip()))
+
+
+def _without_ours(groups: list) -> list:
+    """Drop Cairn's own entries from `[{matcher, hooks: [...]}]`, keeping every other entry and group."""
+    out = []
+    for g in groups if isinstance(groups, list) else []:
+        if isinstance(g, dict) and isinstance(g.get("hooks"), list):
+            hooks = [h for h in g["hooks"] if not _is_ours(h)]
+            if hooks:
+                out.append({**g, "hooks": hooks})
+            elif not g["hooks"]:
+                out.append(g)
+        else:
+            out.append(g)
+    return out
+
+
+# ---- memory at session start ------------------------------------------------------------------------
+def project_brief(root: Path | str, cairn=None) -> str:
+    """The Cairn brief (map hubs, active spec, principles, team knowledge): what `cairn hook session-start`
+    gives Claude Code. Empty when the repository has no Cairn state yet."""
+    if cairn is None:
+        from .core import Cairn
+        proj = Project.discover(Path(root))
+        if proj is None or not proj.db_path.exists():
+            return ""
+        cairn = Cairn(proj)
+    return cairn.brief(max_tokens=550)
+
+
+def session_timeline(root: Path | str) -> str:
+    """The session-memory timeline (what the capture SessionStart hook gives Claude Code)."""
+    from .engines.recall.context import inject_context
+    from .engines.recall.projects import project_context
+    return inject_context(root, project_context(str(root)).all_projects)
+
+
+def agent_context(project: Project, cairn=None) -> str:
+    """What every agent is given at session start: the brief, then the timeline."""
+    parts = (project_brief(project.root, cairn), session_timeline(project.root))
+    return "\n\n".join(p.strip() for p in parts if p and p.strip())
+
+
+# A context file is not read the moment it is written: leave out what only makes sense right now, so it
+# is rewritten only when the memory itself changes.
+_VOLATILE = (re.compile(r"^(# \[[^\]\n]*\] recent context), [^\n]*$", re.MULTILINE),
+             re.compile(r" \((?:\d+(?:y|mo|d|h|m) ago|just now)\)"))
+
+
+def _context_file(root: Path, agent: str) -> Path | None:
+    """The agent's context file, when Cairn wrote one."""
+    if agent not in CONTEXT_FILES:
+        return None
+    path = root / CONTEXT_FILES[agent][0]
+    try:
+        return path if path.exists() and CONTEXT_NOTE in path.read_text() else None
+    except OSError:
+        return None
+
+
+def write_context_file(root: Path, agent: str, text: str) -> bool:
+    """Write the agent's untracked context file; True when it changed. A same-named file of the user's is left
+    alone."""
+    rel, header, limit = CONTEXT_FILES[agent]
+    path = root / rel
+    if path.exists() and _context_file(root, agent) is None:
+        return False
+    text = _VOLATILE[1].sub("", _VOLATILE[0].sub(r"\1", text.strip()))
+    if limit:
+        room = limit - len(header) - len(CONTEXT_NOTE) - len(CONTEXT_OPEN) - len(CONTEXT_HEADING) - len(CONTEXT_CLOSE) - 8
+        text = text[:room]
+    content = f"{header}{CONTEXT_NOTE}\n{CONTEXT_OPEN}\n{CONTEXT_HEADING}\n\n{text}\n{CONTEXT_CLOSE}\n"
+    if path.exists() and path.read_text() == content:
+        return False
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content)
+    return True
+
+
+def _exclude_path(project: Project) -> Path | None:
+    """This clone's `.git/info/exclude` (git resolves worktrees and custom git dirs)."""
+    if not project.is_git:
+        return None
+    rel = project.git("rev-parse", "--git-path", "info/exclude").strip()
+    if not rel:
+        return None
+    p = Path(rel)
+    return p if p.is_absolute() else (project.root / p).resolve()
+
+
+def _set_excluded(project: Project, rel: str, excluded: bool) -> bool:
+    """Add or remove `/<rel>` in `.git/info/exclude`: untracked for this clone, without touching .gitignore."""
+    path = _exclude_path(project)
+    if path is None:
+        return False
+    line = "/" + rel
+    lines = path.read_text().splitlines() if path.exists() else []
+    if excluded == (line in lines):
+        return False
+    lines = [*lines, line] if excluded else [ln for ln in lines if ln != line]
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("\n".join(lines) + "\n")
+    return True
+
+
+def remove_legacy_memory_block(path: Path) -> bool:
+    """Earlier installs kept the memory in AGENTS.md; it moved out of committed files."""
+    if not path.exists():
+        return False
+    text = path.read_text()
+    start, end = text.find(CONTEXT_OPEN), text.find(CONTEXT_CLOSE)
+    if start == -1 or end < start:
+        return False
+    rest = (text[:start].rstrip() + "\n\n" + text[end + len(CONTEXT_CLOSE):].lstrip()).strip()
+    if rest:
+        path.write_text(rest + "\n")
+    else:
+        path.unlink()
+    return True
+
+
+def refresh_context(project: Project, cairn=None) -> bool:
+    """Rewrite the context files Cairn installed (after a session summary, on sync, when a memory is stored);
+    True when one changed. A no-op where none are installed."""
+    agents = [a for a in CONTEXT_FILES if _context_file(project.root, a) is not None]
+    if not agents:
+        return False
+    text = agent_context(project, cairn)
+    changed = [write_context_file(project.root, a, text) for a in agents]  # every file, not just the first
+    return any(changed)
+
+
+def codex_hooks_approved(project: Project) -> bool | None:
+    """Whether Codex has approved Cairn's hooks for this repository (read from `~/.codex/config.toml`, never
+    written); None when there are no Codex hooks here."""
+    from .engines.recall import integrations as recall_hooks
+    return recall_hooks.codex_hooks_approved(project.root)
+
+
+def memory_status(project: Project) -> dict[str, dict]:
+    """Per agent: how memory reaches it at session start (`injection`, None when it doesn't) and whether its
+    sessions are captured (`capture`)."""
+    from .engines.recall import integrations as recall_hooks
+    root = project.root
+    hooks = recall_hooks.project_status(root)
+    brief = False
+    try:
+        brief = "cairn hook session-start" in json.dumps(
+            json.loads((root / ".claude" / "settings.json").read_text()).get("hooks", {}).get("SessionStart", []))
+    except (OSError, ValueError, AttributeError):
+        pass
+    out = {}
+    for agent in AGENTS:
+        state = hooks.get(agent, {})
+        injection = None
+        if agent == "claude":
+            injection = "SessionStart hook" if brief or state.get("start_hook") else None
+        elif agent == "opencode":
+            injection = "system prompt (plugin)" if state.get("start_hook") else None
+        elif state.get("start_hook"):
+            injection = "SessionStart hook"
+        elif _context_file(root, agent) is not None:
+            injection = f"{CONTEXT_FILES[agent][0]} (untracked)"
+        row = {"injection": injection, "capture": bool(state.get("capture"))}
+        if agent == "codex" and state.get("start_hook"):
+            row["approved"] = recall_hooks.codex_hooks_approved(root)
+        out[agent] = row
+    return out
+
+
+def _hook_cmd(event: str) -> str:
+    """Claude Code runs hook and status-line commands through sh (Git Bash on Windows, PowerShell there when Git
+    Bash is missing): a bare ``cairn`` reads the same in all of them; otherwise the interpreter, spelled for them."""
+    if shutil.which("cairn"):
+        return f"cairn hook {event}"
+    return f"{shellcmd.python_prefix(sys.executable, 'gitbash')} -m cairn hook {event}"
+
+
+def install(project: Project, agents: list[str] | None = None, capture: bool = True) -> dict[str, list[str]]:
+    agents = agents or detect(project)
+    root = project.root
+    cmd, args = command()
+    instructions = (TEMPLATES / "instructions.md").read_text()
+    changed: dict[str, list[str]] = {}
+
+    def note(agent, path, did):
+        if did:
+            changed.setdefault(agent, []).append(str(Path(path).relative_to(root)) if str(path).startswith(str(root)) else str(path))
+
+    note("generic", root / "AGENTS.md", upsert_block(root / "AGENTS.md", instructions))
+    if "claude" in agents:
+        note("claude", root / ".mcp.json", merge_json(root / ".mcp.json", lambda d: d.setdefault("mcpServers", {})
+                                                        .update({"cairn": {"command": cmd, "args": args}})))
+
+        def settings(d):
+            brief = {"hooks": [{"type": "command", "command": _hook_cmd("session-start")}]}
+            if capture:  # session memory: every lifecycle event, handled by the light `cairn.capture` entry
+                from .engines.recall import integrations as recall_hooks
+                current = dict(d.get("hooks") or {})
+                current["SessionStart"] = _without_ours(current.get("SessionStart", []))
+                ours = recall_hooks.claude_code_hooks(python=sys.executable)
+                ours.setdefault("SessionStart", []).append(brief)  # one merge places every Cairn hook, idempotently
+                d["hooks"] = recall_hooks.merge_hook_groups(current, ours)
+            hooks = d.setdefault("hooks", {})
+            ss = hooks.setdefault("SessionStart", [])
+            if not any("cairn hook session-start" in json.dumps(h) for h in ss):
+                ss.append(brief)
+            d.setdefault("statusLine", {"type": "command", "command": _hook_cmd("statusline").replace(
+                "hook statusline", "statusline"), "padding": 0})
+            perms = d.setdefault("permissions", {}).setdefault("allow", [])
+            if "mcp__cairn" not in perms:
+                perms.append("mcp__cairn")
+        note("claude", root / ".claude/settings.json", merge_json(root / ".claude" / "settings.json", settings))
+        for f in (TEMPLATES / "claude" / "commands").glob("*.md"):
+            p = root / ".claude" / "commands" / "cairn" / f.name
+            note("claude", p, write_generated(p, f.read_text()))
+        for f in (TEMPLATES / "claude" / "agents").glob("*.md"):
+            p = root / ".claude" / "agents" / f.name
+            note("claude", p, write_generated(p, f.read_text()))
+        if capture:
+            from .engines.recall import integrations as recall_hooks
+            for name in recall_hooks.install_skills(root / ".claude" / "skills"):
+                note("claude", root / ".claude" / "skills" / name, True)
+        note("claude", root / "CLAUDE.md", upsert_block(root / "CLAUDE.md", instructions))
+    if "cursor" in agents:
+        note("cursor", root / ".cursor/mcp.json", merge_json(root / ".cursor" / "mcp.json", lambda d: d.setdefault(
+            "mcpServers", {}).update({"cairn": {"command": cmd, "args": args}})))
+        rule = "---\ndescription: Cairn project memory\nalwaysApply: true\n---\n" + instructions
+        p = root / ".cursor" / "rules" / "cairn.mdc"
+        note("cursor", p, write_generated(p, rule))
+    if "gemini" in agents:
+        note("gemini", root / ".gemini/settings.json", merge_json(root / ".gemini" / "settings.json", lambda d: d.setdefault(
+            "mcpServers", {}).update({"cairn": {"command": cmd, "args": args}})))
+        note("gemini", root / "GEMINI.md", upsert_block(root / "GEMINI.md", instructions))
+    if "vscode" in agents:
+        note("vscode", root / ".vscode/mcp.json", merge_json(root / ".vscode" / "mcp.json", lambda d: d.setdefault(
+            "servers", {}).update({"cairn": {"type": "stdio", "command": cmd, "args": args}})))
+    if "codex" in agents and shutil.which("codex"):
+        try:
+            listed = subprocess.run(["codex", "mcp", "list"], capture_output=True, text=True, timeout=20).stdout
+            if "cairn" not in listed:
+                subprocess.run(["codex", "mcp", "add", "cairn", "--", cmd, *args], capture_output=True, timeout=30)
+                changed.setdefault("codex", []).append("~/.codex/config.toml (codex mcp add cairn)")
+        except (OSError, subprocess.TimeoutExpired):
+            pass
+    # session capture (and Gemini CLI's SessionStart memory), in each agent's per-repository hook config
+    from .engines.recall import integrations as recall_hooks
+    for agent in agents:
+        if agent in recall_hooks.PROJECT_AGENTS and agent != "claude":
+            rep = recall_hooks.install_project(agent, root, python=sys.executable, capture=capture)
+            for path in rep["written"] + rep["removed"]:
+                note(agent, path, True)
+            if rep.get("error"):
+                changed.setdefault(agent, []).append(f"skipped: {rep['error']}")
+    ignore = project.dir / "graphignore"  # the hook folders are tool config, not part of the system's map
+    if project.dir.is_dir() and MAP_IGNORE.split("\n", 1)[0] not in (ignore.read_text() if ignore.exists() else ""):
+        text = ignore.read_text() if ignore.exists() else ""
+        ignore.write_text(text + ("\n" if text and not text.endswith("\n") else "") + MAP_IGNORE)
+    # memory for the agents that only read instruction files: an untracked file each
+    wanted = [a for a in agents if a in CONTEXT_FILES]
+    if wanted:
+        text = agent_context(project)
+        for agent in wanted:
+            note(agent, root / CONTEXT_FILES[agent][0], write_context_file(root, agent, text))
+            if _context_file(root, agent) is not None:
+                _set_excluded(project, CONTEXT_FILES[agent][0], True)
+    note("generic", root / "AGENTS.md", remove_legacy_memory_block(root / "AGENTS.md"))
+    return changed
+
+
+def connect(project: Project, server_url: str, project_id: str, env_var: str = "CAIRN_TOKEN") -> list[str]:
+    """Point this repository's agents at a team server's MCP endpoint instead of the local process.
+
+    The token is never written to disk: configs reference `${CAIRN_TOKEN}`, which each developer exports (the
+    configs are usually committed)."""
+    url = f"{server_url.rstrip('/')}/mcp/{project_id}/"
+    header = {"Authorization": f"Bearer ${{{env_var}}}"}
+    root, changed = project.root, []
+    project.set_cfg("team.server", server_url.rstrip("/"))  # session capture pushes here (`cairn sessions push`)
+    project.set_cfg("team.project", project_id)
+    project.set_cfg("team.token_env", env_var)  # `cairn sessions push` reads the token from the same variable
+    project.set_cfg("recall.worker_model", False)  # the server turns pushed events into observations with a model
+    changed.append(".cairn/config.toml [team]")
+    if merge_json(root / ".mcp.json", lambda d: d.setdefault("mcpServers", {}).update(
+            {"cairn": {"type": "http", "url": url, "headers": header}})):
+        changed.append(".mcp.json")
+    for rel, key in ((".cursor/mcp.json", "mcpServers"), (".gemini/settings.json", "mcpServers")):
+        if (root / rel).exists() and merge_json(root / rel, lambda d, k=key: d.setdefault(k, {}).update(
+                {"cairn": {"url": url, "headers": header}})):
+            changed.append(rel)
+    if (root / ".vscode" / "mcp.json").exists() and merge_json(root / ".vscode" / "mcp.json", lambda d: d.setdefault(
+            "servers", {}).update({"cairn": {"type": "http", "url": url, "headers": header}})):
+        changed.append(".vscode/mcp.json")
+    return changed
+
+
+def uninstall(project: Project) -> list[str]:
+    root, removed = project.root, []
+    if remove_legacy_memory_block(root / "AGENTS.md"):
+        removed.append("AGENTS.md (memory block)")
+    for agent in CONTEXT_FILES:
+        path = _context_file(root, agent)
+        if path is not None:
+            path.unlink()
+            removed.append(CONTEXT_FILES[agent][0])
+        if _set_excluded(project, CONTEXT_FILES[agent][0], False):
+            removed.append(f".git/info/exclude (/{CONTEXT_FILES[agent][0]})")
+    from .engines.recall import integrations as recall_hooks
+    for agent in recall_hooks.PROJECT_AGENTS:
+        if agent != "claude":
+            rep = recall_hooks.uninstall_project(agent, root)
+            removed += [str(Path(p).relative_to(root)) if str(p).startswith(str(root)) else str(p)
+                        for p in rep["removed"]]
+    for md in ("AGENTS.md", "CLAUDE.md", "GEMINI.md"):
+        if remove_block(root / md):
+            removed.append(md)
+    def drop_server(d, k):
+        servers = d.get(k)
+        if isinstance(servers, dict) and servers.pop("cairn", None) is not None and not servers:
+            d.pop(k)  # the map only held Cairn's entry
+    for rel, key in ((".mcp.json", "mcpServers"), (".cursor/mcp.json", "mcpServers"),
+                     (".gemini/settings.json", "mcpServers"), (".vscode/mcp.json", "servers")):
+        if merge_json(root / rel, lambda d, k=key: drop_server(d, k)):
+            removed.append(rel)
+
+    def clean(d):
+        from .engines.recall import integrations as recall_hooks
+        hooks, _ = recall_hooks.remove_hook_groups(d.get("hooks") or {})  # the session engine's entries
+        for event in list(hooks):
+            hooks[event] = _without_ours(hooks[event])                  # the brief; the user's own stay
+            if not hooks[event]:
+                hooks.pop(event)
+        if hooks:
+            d["hooks"] = hooks
+        else:
+            d.pop("hooks", None)
+        if _is_ours(d.get("statusLine", {})):
+            d.pop("statusLine")
+        allow = d.get("permissions", {}).get("allow", [])
+        if "mcp__cairn" in allow:
+            allow.remove("mcp__cairn")
+    if merge_json(root / ".claude" / "settings.json", clean):
+        removed.append(".claude/settings.json")
+    from .engines.recall import integrations as recall_hooks
+    removed += [f".claude/skills/{name}" for name in recall_hooks.uninstall_skills(root / ".claude" / "skills")]
+    for p in [*(root / ".claude" / "commands" / "cairn").glob("*.md"), *(root / ".claude" / "agents").glob("cairn-*.md"),
+              root / ".cursor" / "rules" / "cairn.mdc"]:
+        if p.exists() and GENERATED in p.read_text():
+            p.unlink()
+            removed.append(str(p.relative_to(root)))
+    if shutil.which("codex"):
+        subprocess.run(["codex", "mcp", "remove", "cairn"], capture_output=True, timeout=30)
+    return removed

cairn/capture.py

@@ -0,0 +1,36 @@
+"""Session capture: the agent hook entry point for Cairn's session memory (recall engine).
+
+Runs on every prompt and tool call, so it stays tiny: standard library only, a few SQLite writes into
+``<repo>/.cairn/sessions.db``, no model, and it never breaks the agent (bad input or a locked store
+is ignored, exit code 0). The Stop and SessionEnd events start the recall worker in the background,
+which turns the queued events into observations and summaries (``engines/recall/worker.py``).
+
+Usage (from an agent hook, JSON payload on stdin):
+  python -m cairn.capture [--platform claude-code|codex|cursor|windsurf|antigravity|gemini|raw] <event>
+  events: context, session-init, observation, file-context, summarize, session-end, user-message, file-edit
+  (the earlier names prompt, tool and stop still work)
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from .engines.recall.hooks import main, record  # noqa: F401  (re-exported entry points)
+from .engines.recall.projects import find_store_root as find_root  # noqa: F401
+from .engines.recall.schema import store_path  # noqa: F401
+from .engines.recall.tags import redact  # noqa: F401
+
+
+def _rel(path: str, root: Path, cwd: str) -> str:
+    """``path`` relative to the repository root ('' when it lies outside)."""
+    if not path:
+        return ""
+    p = Path(path)
+    p = p if p.is_absolute() else Path(cwd) / p
+    try:
+        return p.resolve().relative_to(Path(root).resolve()).as_posix()
+    except (ValueError, OSError):
+        return ""
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())