threadkeeper 0.4.0__py3-none-any.whl

threadkeeper/__init__.py

@@ -0,0 +1,8 @@
+"""thread-keeper: local MCP server that persists Claude's working memory
+across conversations on this machine. The brief format is optimized for
+Claude (token density, structural tags, opaque IDs) — not for human
+readability.
+
+Storage : ~/.threadkeeper/db.sqlite (SQLite + FTS5; embeddings optional)
+Wire    : stdio MCP, registered in claude_desktop_config.json
+"""

threadkeeper/_mcp.py

@@ -0,0 +1,6 @@
+"""Singleton FastMCP instance shared by every tool module. All
+@mcp.tool() definitions across the package register on this same instance,
+so server.py can simply import every tool module and call mcp.run()."""
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("thread-keeper")

threadkeeper/_setup.py

@@ -0,0 +1,299 @@
+"""thread-keeper installer / updater.
+
+Idempotently wires thread-keeper into a Claude Code installation:
+  1. Registers `thread-keeper` MCP server in ~/.claude.json
+  2. Installs hooks (SessionStart, PostToolUse, UserPromptSubmit) in
+     ~/.claude/settings.json
+  3. Copies hook scripts to ~/.threadkeeper/hooks/
+  4. Updates the managed block in ~/.claude/CLAUDE.md between sentinel
+     markers — content outside the markers is preserved.
+
+Re-run any time: the script reads existing config, merges its own
+contribution, and writes back. Other MCP servers / hooks / CLAUDE.md
+content are left untouched.
+
+Console entry point:
+    thread-keeper-setup [--dry-run]
+
+Or:
+    python -m threadkeeper._setup [--dry-run]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import sys
+from pathlib import Path
+from typing import Any
+
+# ----------------------------------------------------------------------
+# Paths
+# ----------------------------------------------------------------------
+
+HOME = Path.home()
+PACKAGE_ROOT = Path(__file__).resolve().parent           # .../threadkeeper/
+REPO_ROOT = PACKAGE_ROOT.parent                          # .../ai-memory/
+
+CLAUDE_DIR = HOME / ".claude"
+CLAUDE_MD = CLAUDE_DIR / "CLAUDE.md"
+CLAUDE_JSON = HOME / ".claude.json"
+SETTINGS_JSON = CLAUDE_DIR / "settings.json"
+
+TK_DIR = HOME / ".threadkeeper"
+TK_HOOKS_DIR = TK_DIR / "hooks"
+
+HOOKS_SRC = REPO_ROOT / "scripts" / "hooks"
+
+# Sentinel markers — content between these lines is managed by this
+# installer. The user can edit OUTSIDE the block freely.
+MARK_BEGIN = "<!-- THREADKEEPER:BEGIN — managed by `thread-keeper setup`; do not edit between these markers -->"
+MARK_END = "<!-- THREADKEEPER:END -->"
+
+
+# ----------------------------------------------------------------------
+# Content of the managed CLAUDE.md block
+# ----------------------------------------------------------------------
+
+CLAUDE_MD_BLOCK = """\
+## thread-keeper
+
+thread-keeper holds persistent working memory across conversations.
+At session start:
+  * On Claude Code, the SessionStart hook
+    (`~/.threadkeeper/hooks/tk-brief.sh`) auto-injects `brief()` +
+    `context()` — and `live_status()` if `live=N>0`.
+  * On other CLIs (Codex, Gemini, …) the hook mechanism may not exist;
+    call `brief()` and `context()` yourself before the first answer.
+    If the user's opening message is substantive, pass it as `query`
+    to `brief()` to inline relevant past notes.
+
+During the conversation:
+- New substantive topic → `open_thread()`.
+- Topic resolved with an outcome → `close_thread(thread_id, outcome)`.
+- After every turn that produced a decision or insight →
+  `note(thread_id, ..., kind in ['move','failed','insight','open_q'])`.
+- When the user says something sharp and precise → `verbatim_user()`.
+- When you notice an unused brief field or a missing one →
+  `evolve_format()`.
+- At end of conversation → `session_end(summary)`.
+
+When the brief surfaces a thread or topic relevant to the current
+request (by `question`, `last_move`, or semantic match), don't answer
+from brief alone — dig deeper. Search ladder (stop at the first source
+that gives you enough context):
+
+  1. `thread-keeper.search()` — stored partner notes
+  2. `thread-keeper.dialog_search()` — full transcripts ingested from
+     ALL connected CLIs (Claude Code, Codex, Gemini, Copilot)
+  3. CLI-native conversation history search (e.g. `conversation_search`
+     for Claude Desktop), if available
+
+## Procedural lessons
+
+Accumulated CLI-agnostic procedural knowledge lives in
+`~/.threadkeeper/lessons.md`. The learning loop (auto-review on
+close_thread + shadow_review daemon) materializes lessons there. At
+session start, scan `lesson_list()` for slugs relevant to the user's
+opening message; pull full bodies via `lesson_get(slug)` as needed.
+
+When YOU finish a substantive task and a class-level lesson emerged
+(user corrected a workflow, a non-trivial debugging path generalized,
+etc.), call `lesson_append(title, body, summary, source=thread_id)`
+yourself instead of waiting for the auto-reviewer to catch it.
+
+Do not report these tool calls to the user — they are internal.
+"""
+
+
+# ----------------------------------------------------------------------
+# Sub-installers
+# ----------------------------------------------------------------------
+
+def install_mcp_servers(dry_run: bool) -> list[str]:
+    """Register thread-keeper in every detected CLI's MCP config.
+    Each adapter knows the right config file/format for its CLI."""
+    from .adapters import installed_adapters
+
+    python_bin = sys.executable
+    venv_python = REPO_ROOT / ".venv" / "bin" / "python"
+    if venv_python.exists():
+        python_bin = str(venv_python)
+    args = ["-m", "threadkeeper.server"]
+    env = {"PYTHONPATH": str(REPO_ROOT)}
+
+    lines: list[str] = []
+    adapters = installed_adapters()
+    if not adapters:
+        return ["mcp_server: no CLI detected — nothing to wire"]
+    for adapter in adapters:
+        result = adapter.register_mcp_server(
+            name="thread-keeper",
+            command=python_bin,
+            args=args,
+            env=env,
+            dry_run=dry_run,
+        )
+        lines.append(f"mcp_server[{adapter.name}]: {result}")
+    return lines
+
+
+def install_hooks(dry_run: bool) -> list[str]:
+    """Install hook scripts under ~/.threadkeeper/hooks/ AND wire them
+    up in every detected CLI that supports hooks."""
+    from .adapters import installed_adapters
+    lines: list[str] = []
+
+    # 1) Copy hook scripts. One set lives under ~/.threadkeeper/hooks/
+    # and is referenced by every supporting CLI.
+    if not dry_run:
+        TK_HOOKS_DIR.mkdir(parents=True, exist_ok=True)
+    for fname in ("tk-brief.sh", "tk-status.sh", "inbox-check.sh"):
+        src = HOOKS_SRC / fname
+        dst = TK_HOOKS_DIR / fname
+        if not src.exists():
+            lines.append(f"hooks: source missing ({src}) — skipping {fname}")
+            continue
+        if dst.exists() and dst.read_bytes() == src.read_bytes():
+            lines.append(f"hooks: {fname} already current")
+            continue
+        if dry_run:
+            lines.append(f"hooks: would install {fname}")
+        else:
+            shutil.copy2(src, dst)
+            dst.chmod(0o755)
+            lines.append(f"hooks: installed {fname}")
+
+    # 2) Build the canonical spec list (same three hooks every CLI gets).
+    specs = [
+        {
+            "event": "SessionStart",
+            "matcher": "",
+            "command": str(TK_HOOKS_DIR / "tk-brief.sh"),
+        },
+        {
+            "event": "PostToolUse",
+            "matcher": "mcp__thread-keeper__.*",
+            "command": str(TK_HOOKS_DIR / "tk-status.sh"),
+        },
+        {
+            "event": "UserPromptSubmit",
+            "matcher": "",
+            "command": str(TK_HOOKS_DIR / "inbox-check.sh"),
+        },
+    ]
+
+    # 3) Ask each installed adapter to wire them up in its native
+    # config file. Adapters that don't support hooks (e.g. Codex) emit
+    # an "unsupported" line but don't block setup.
+    for adapter in installed_adapters():
+        if not adapter.hooks_supported():
+            lines.append(f"hooks[{adapter.name}]: no hook mechanism — skip")
+            continue
+        result = adapter.register_hooks(specs, dry_run=dry_run)
+        lines.append(f"hooks[{adapter.name}]: {result}")
+    return lines
+
+
+def _install_managed_block(fp: Path, dry_run: bool) -> str:
+    """Generic 'insert/update managed block between sentinel markers'
+    routine used for every CLI's per-user instructions file. Idempotent.
+    Outside the markers the user's content is preserved verbatim."""
+    block = f"{MARK_BEGIN}\n{CLAUDE_MD_BLOCK}{MARK_END}\n"
+    label = fp.name
+
+    if not fp.exists():
+        if not dry_run:
+            fp.parent.mkdir(parents=True, exist_ok=True)
+            fp.write_text(block)
+        return f"{label}: created"
+
+    body = fp.read_text()
+    if MARK_BEGIN in body and MARK_END in body:
+        head, _, rest = body.partition(MARK_BEGIN)
+        _, _, tail = rest.partition(MARK_END)
+        head = head.rstrip()
+        tail = tail.lstrip()
+        if head and tail:
+            new_body = head + "\n\n" + block + "\n" + tail + "\n"
+        elif head:
+            new_body = head + "\n\n" + block
+        elif tail:
+            new_body = block + "\n" + tail + "\n"
+        else:
+            new_body = block
+        if new_body == body:
+            return f"{label}: managed block already current"
+        if not dry_run:
+            fp.write_text(new_body)
+        return f"{label}: {'would update' if dry_run else 'updated'} managed block"
+
+    # No markers yet → prepend (top placement → visible without scroll).
+    existing = body.strip()
+    if existing:
+        new_body = block + "\n" + existing + "\n"
+    else:
+        new_body = block
+    if not dry_run:
+        fp.write_text(new_body)
+    return f"{label}: {'would prepend' if dry_run else 'prepended'} managed block"
+
+
+def install_instructions(dry_run: bool) -> list[str]:
+    """Write the managed thread-keeper block to every detected CLI's
+    per-user instructions file (CLAUDE.md, AGENTS.md, GEMINI.md). CLIs
+    without a global instructions convention (e.g. Copilot) are skipped."""
+    from .adapters import installed_adapters
+    lines: list[str] = []
+    for adapter in installed_adapters():
+        ip = adapter.instructions_path()
+        if ip is None:
+            lines.append(f"instructions[{adapter.name}]: no global file (skip)")
+            continue
+        result = _install_managed_block(ip, dry_run)
+        lines.append(f"instructions[{adapter.name}]: {result}")
+    return lines
+
+
+def install_tk_dir(dry_run: bool) -> str:
+    """Ensure ~/.threadkeeper/ exists. DB lives here; hooks subdir is
+    handled separately by install_hooks."""
+    if TK_DIR.exists():
+        return f"~/.threadkeeper: already exists"
+    if not dry_run:
+        TK_DIR.mkdir(parents=True, exist_ok=True)
+    return f"~/.threadkeeper: {'would create' if dry_run else 'created'}"
+
+
+# ----------------------------------------------------------------------
+# Main
+# ----------------------------------------------------------------------
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="thread-keeper-setup")
+    p.add_argument("--dry-run", action="store_true",
+                   help="Show what would change without writing anything.")
+    args = p.parse_args(argv)
+
+    print(f"thread-keeper setup ({'dry-run' if args.dry_run else 'apply'})")
+    print(f"  repo: {REPO_ROOT}")
+    print(f"  ~/.threadkeeper: {TK_DIR}")
+    print()
+
+    print(f"  [dir] {install_tk_dir(args.dry_run)}")
+    for line in install_mcp_servers(args.dry_run):
+        print(f"  [{line.split(':', 1)[0]}] {line.split(':', 1)[1].strip()}"
+              if ":" in line else f"  [mcp] {line}")
+    for line in install_instructions(args.dry_run):
+        print(f"  [{line.split(':', 1)[0]}] {line.split(':', 1)[1].strip()}"
+              if ":" in line else f"  [md] {line}")
+    for line in install_hooks(args.dry_run):
+        print(f"  [hooks] {line}")
+    print()
+    print("Done. Restart Claude Code for hooks + MCP changes to take effect.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

threadkeeper/adapters/__init__.py

@@ -0,0 +1,40 @@
+"""CLI adapter registry.
+
+thread-keeper is CLI-agnostic: it can attach to any agent CLI that
+(a) supports MCP servers in its config and (b) writes conversation
+history to disk in a parseable format. Each supported CLI has its
+own adapter under this package, and the registry below enumerates
+them in load order.
+
+To add support for a new CLI:
+  1. Create `threadkeeper/adapters/<name>.py` exporting `ADAPTER`
+     (an instance of CLIAdapter).
+  2. Append it to `ADAPTERS` below.
+  3. That's it. ingest, _setup, and brief will pick it up.
+"""
+from __future__ import annotations
+
+from .base import CLIAdapter, NormalizedMessage
+from .claude_code import ADAPTER as _CLAUDE_CODE
+from .claude_desktop import ADAPTER as _CLAUDE_DESKTOP
+from .codex import ADAPTER as _CODEX
+from .gemini import ADAPTER as _GEMINI
+from .copilot import ADAPTER as _COPILOT
+from .vscode import ADAPTER as _VSCODE
+
+ADAPTERS: list[CLIAdapter] = [
+    _CLAUDE_CODE,
+    _CLAUDE_DESKTOP,
+    _CODEX,
+    _GEMINI,
+    _COPILOT,
+    _VSCODE,
+]
+
+
+def installed_adapters() -> list[CLIAdapter]:
+    """Return adapters whose CLI is detected on this machine."""
+    return [a for a in ADAPTERS if a.is_installed()]
+
+
+__all__ = ["CLIAdapter", "NormalizedMessage", "ADAPTERS", "installed_adapters"]

threadkeeper/adapters/_hook_helpers.py

@@ -0,0 +1,72 @@
+"""Shared helpers for installing Claude-Code-style hooks into a JSON
+config file. Claude Code and Gemini both honor the same shape
+(`settings.json["hooks"]`), so the merging logic is identical — only
+the target file path differs. Pulled out so both adapters can call it
+without code duplication.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Iterable
+
+
+def install_claude_style_hooks(
+    settings_path: Path,
+    specs: Iterable[dict],
+    dry_run: bool = False,
+) -> str:
+    """Merge `specs` into `settings_path` under the "hooks" key.
+
+    Each spec: {event: str, command: str, matcher: str}.
+
+    Idempotent: for each (event, command) pair, leave existing entries
+    in place (and update matcher if it differs); add a new entry if the
+    command isn't already present. Other hooks (from the user or other
+    plugins) are preserved.
+    """
+    if settings_path.exists():
+        try:
+            settings = json.loads(settings_path.read_text())
+        except json.JSONDecodeError:
+            return f"{settings_path.name}: malformed JSON — refused"
+    else:
+        settings = {}
+    hooks = settings.setdefault("hooks", {})
+
+    changed = False
+    for spec in specs:
+        event = spec["event"]
+        command = spec["command"]
+        matcher = spec.get("matcher", "")
+        blocks = hooks.get(event, [])
+        # Look for an existing block whose first hook command matches.
+        found = False
+        for block in blocks:
+            inner = block.get("hooks") or []
+            for h in inner:
+                if h.get("command") == command:
+                    found = True
+                    if block.get("matcher", "") != matcher:
+                        block["matcher"] = matcher
+                        changed = True
+                    break
+            if found:
+                break
+        if not found:
+            new_block = {
+                "hooks": [{"type": "command", "command": command}],
+            }
+            if matcher:
+                new_block["matcher"] = matcher
+            blocks.append(new_block)
+            changed = True
+        hooks[event] = blocks
+
+    if not changed:
+        return f"{settings_path.name}: hooks already current"
+    if dry_run:
+        return f"{settings_path.name}: would update hooks"
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+    settings_path.write_text(json.dumps(settings, indent=2))
+    return f"{settings_path.name}: hooks updated"

threadkeeper/adapters/base.py

@@ -0,0 +1,152 @@
+"""CLIAdapter abstract base — contract every adapter implements.
+
+Each adapter knows three things:
+  1. How to detect that this CLI is installed on the user's machine
+  2. How to register/unregister thread-keeper in that CLI's MCP config
+  3. How to enumerate + parse the conversation transcripts the CLI
+     writes to disk
+
+Adapters return data through a single normalized shape
+(`NormalizedMessage`) so ingest doesn't have to special-case any CLI.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterator, Optional
+
+
+@dataclass
+class NormalizedMessage:
+    """Adapter output: a single user/assistant turn, normalized.
+
+    Fields:
+      uuid        — stable per-message id from the transcript.
+      session_id  — opaque identifier for the conversation/session.
+      role        — 'user' | 'assistant'.
+      content     — extracted text (concatenated text/thinking blocks,
+                    capped tool_result blocks).
+      model       — model name if known, else "".
+      created_at  — unix epoch seconds.
+      raw         — the original parsed dict, in case downstream code
+                    needs to peek into adapter-specific fields (e.g.
+                    Skill tool_use detection in ingest).
+    """
+    uuid: str
+    session_id: str
+    role: str
+    content: str
+    model: str
+    created_at: int
+    raw: dict
+
+
+class CLIAdapter(ABC):
+    """A pluggable target CLI integration."""
+
+    # Stable, lowercase-hyphen identifier ('claude-code', 'codex', etc).
+    # Used in dialog_messages.source and elsewhere as a provenance tag.
+    name: str = ""
+
+    # ------------------------------------------------------------------
+    # Detection
+    # ------------------------------------------------------------------
+    @abstractmethod
+    def is_installed(self) -> bool:
+        """Return True iff this CLI is present on the system (the
+        adapter checks for whatever combination of executable + config
+        dir + log dir is meaningful for that CLI)."""
+
+    # ------------------------------------------------------------------
+    # MCP registration
+    # ------------------------------------------------------------------
+    @abstractmethod
+    def register_mcp_server(
+        self,
+        name: str,
+        command: str,
+        args: list[str],
+        env: dict[str, str],
+        dry_run: bool = False,
+    ) -> str:
+        """Add thread-keeper to the CLI's MCP server config (idempotent).
+
+        Return a one-line human status: 'created', 'updated', 'already
+        current', or 'unsupported: <reason>'.
+        """
+
+    @abstractmethod
+    def unregister_mcp_server(self, name: str, dry_run: bool = False) -> str:
+        """Remove an MCP server entry by name (idempotent)."""
+
+    # ------------------------------------------------------------------
+    # Transcript ingestion
+    # ------------------------------------------------------------------
+    @abstractmethod
+    def transcript_files(self) -> list[Path]:
+        """Return every transcript file this adapter knows about, in
+        any order. ingest will sort/filter by mtime."""
+
+    @abstractmethod
+    def iter_messages(self, fp: Path) -> Iterator[NormalizedMessage]:
+        """Yield NormalizedMessage from one transcript file, in file
+        order. Skip malformed lines silently."""
+
+    # ------------------------------------------------------------------
+    # Optional hooks (default: no-op)
+    # ------------------------------------------------------------------
+    def project_label(self, fp: Path) -> str:
+        """Project tag stored as dialog_messages.project. Default:
+        parent directory name."""
+        return fp.parent.name
+
+    def session_dir(self) -> Optional[Path]:
+        """Root directory under which transcripts live. Used by ingest
+        to decide whether this adapter has anything to scan."""
+        return None
+
+    def instructions_path(self) -> Optional[Path]:
+        """Path to the per-user system-prompt-style file this CLI reads
+        at session start (e.g. Claude's CLAUDE.md, Codex's AGENTS.md).
+        Return None when the CLI has no such global file (e.g. Copilot
+        only supports per-repo instructions)."""
+        return None
+
+    def skills_dir(self) -> Optional[Path]:
+        """Root directory under which this CLI auto-discovers Skill.md
+        files (Anthropic-style skill format: YAML frontmatter +
+        description-based auto-trigger). Examples:
+
+            Claude (Code/Desktop/IDE) → ~/.claude/skills/
+            Codex (CLI/desktop)       → ~/.codex/skills/
+
+        Return None when the CLI doesn't natively consume Skills
+        (Gemini, Copilot, generic MCP clients) — those fall back to
+        the CLI-agnostic ~/.threadkeeper/lessons.md store.
+
+        Multi-mirror writes in skill_manage use this to propagate one
+        SKILL.md across every native skills-store on the machine so a
+        single materialization reaches every detected CLI.
+        """
+        return None
+
+    # ------------------------------------------------------------------
+    # Hooks (optional)
+    # ------------------------------------------------------------------
+    def hooks_supported(self) -> bool:
+        """True iff this CLI honors shell-style lifecycle hooks
+        (SessionStart, PostToolUse, etc.)."""
+        return False
+
+    def register_hooks(
+        self,
+        specs: list[dict],
+        dry_run: bool = False,
+    ) -> str:
+        """Install all `specs` into the CLI's hook config. Each spec is
+        `{event, command, matcher?}` — adapter translates to whatever
+        local format the CLI uses. Idempotent: existing entries for the
+        same event + command are left in place; matchers updated if
+        changed. Default: 'unsupported'."""
+        return f"{self.name}: hooks unsupported"