thread-keeper

thread-keeper

Multi-agent shared brain across Claude Code/Desktop, Codex, Antigravity CLI (`agy`), Copilot, and VS Code. Cross-session memory, self-improving skill loops, and inter-agent signaling — one local MCP server turns parallel agent instances into a coordinated multi-agent system instead of N isolated chats.

Every connected client (Claude Code, Claude Desktop, Codex CLI + desktop, Antigravity CLI, Copilot, every MCP-aware VS Code extension) shares one SQLite store, one set of threads, one user model, and one learning loop that improves the skill library autonomously over time.

The brief format is dense — structural tags, opaque IDs, ~6 KB per session-start injection. Optimized for agent consumption, not human reading.

---

Why

Every agent CLI starts cold. Context dies at session boundaries. Skills you taught Claude don't transfer to Codex. Threads you closed in yesterday's Antigravity chat are invisible to today's Copilot. Parallel agent instances running the same task don't know about each other and duplicate work or step on each other's writes.

thread-keeper is the substrate underneath. Three things that together make it more than a memory store:

• Collective memory — threads, notes, verbatim quotes, dialectic claims about you. Survives session, restart, CLI swap. One agent records, every other agent (any CLI) reads. The brief injected at session start gives a new agent everything the previous one knew.
• Multi-agent coordination — spawn primitive launches child agents in parallel, each gets a self_cid + sees the same memory. broadcast / whisper / inbox / wait / ask / respond let concurrent sessions signal each other across CLIs. Parent / children / sibling agents become a coordinated swarm, not isolated chats.
• Self-improving skill library — autonomous background loops (auto-review on thread close, shadow-review daemon, extract harvester, candidate-reviewer, weekly Curator, and a thread-janitor that auto-closes idle threads so abandoned work reaches the harvest path — closing is reversible, a note reopens a closed thread) materialize class-level skills as the agents work. Adapted to multi-CLI: SKILL.md is the primary write target and gets mirrored to every known/configured skills root simultaneously (~/.claude/skills/, ~/.codex/skills/, ~/.gemini/config/skills/ for Antigravity, existing ~/.agents/skills/, extra roots from THREADKEEPER_EXTRA_SKILLS_DIRS, and ~/.threadkeeper/skills/), with lessons.md as a fallback for CLIs without a native skills loader. A managed skill write reports success only after every mirror has the expected file set and hashes; ERR mirror_partial_failure keeps the canonical copy and names only the affected consumer plus relative file. Retry safely with skill_manage(action="reconcile", name=" ").

Foreground MCP servers also run a daily self-update check by default. Source checkouts fast-forward their tracked git branch and reinstall the editable package; PyPI/pipx/venv installs run pip install --upgrade in the current interpreter environment only after the latest PyPI release files have matching Integrity API provenance from the expected GitHub Trusted Publisher. Dirty or diverged git checkouts are skipped rather than overwritten. Restarts are gated on install/setup success plus a subprocess import smoke check, so a broken or unverified update is recorded but the current server keeps running. Interpreters without pip (uv-created or pipx venvs) install through uv pip install --python when uv is available. Upstream PyPI publishing is intentionally gated: green merge-to-main builds are auto-tagged, but every upload pauses for a human approval on the protected pypi GitHub Environment (a maintainer-signed annotated v* tag remains the manual override path), as described in docs/RELEASING.md.

They also run a twice-weekly installed-skill updater by default. It keeps all configured CLI skill roots in sync, adopts newer local copies installed into a non-primary root, and updates GitHub-backed skills when a tracked upstream source changes.

---

Quickstart

The shortest path — PyPI + pipx (recommended):

pipx install 'threadkeeper[semantic]' && thread-keeper-setup

thread-keeper-setup detects every CLI you have installed (Claude Code / Claude Desktop / Codex CLI + desktop / Antigravity CLI agy / Copilot / VS Code), registers the MCP server in each one's config, copies hooks to ~/.threadkeeper/hooks/, and writes a managed instructions block into each CLI's per-user instructions file (CLAUDE.md / AGENTS.md / copilot-instructions.md — Claude Desktop and VS Code have no global instructions file, so that step is skipped for them). The generated MCP entry pins imports to this configured installation, so an agent launched inside another thread-keeper checkout cannot load that checkout's unmerged code against the live memory database.

Restart your CLI of choice. Hook-capable clients inject a brief on the first message; hookless clients such as Codex and Antigravity CLI either follow the managed instructions block and call brief() / context() before answering, or — on hosts that support MCP resources — pull the brief as the read-only memory://brief resource the host attaches automatically (see MCP primitives).

The MCP initialization response also carries concise, static lifecycle guidance: load the brief/context, open/note/close substantive threads, prefer read-only resources for host-attached context, and use dry-run plus confirmation before destructive maintenance. Hooks and the managed files remain reinforcement for clients that do not surface server instructions.

Alternative installs

If you don't have pipx and don't want to install it:

# uv (Rust-fast Python tool runner) — no clone, single binary on PATH

uv tool install 'threadkeeper[semantic]' && thread-keeper-setup

Plain pip into a venv

python3 -m venv ~/.threadkeeper-venv ~/.threadkeeper-venv/bin/pip install 'threadkeeper[semantic]' ~/.threadkeeper-venv/bin/thread-keeper-setup

For development (editable install from a git checkout) or to track the bleeding edge:

# One-liner installer — clones to ~/thread-keeper, makes a venv,

editable-installs, wires every detected CLI. Idempotent — re-run to

update (it git-pulls + reinstalls).

curl -fsSL https://raw.githubusercontent.com/po4erk91/thread-keeper/main/install.sh | bash -s -- --semantic

Or fully manual

git clone https://github.com/po4erk91/thread-keeper ~/thread-keeper cd ~/thread-keeper && python3 -m venv .venv .venv/bin/pip install -e '.[semantic]' .venv/bin/thread-keeper-setup

To preview without writing anything:

thread-keeper-setup --dry-run

---

Multi-CLI integration

Every CLI that produces parseable transcripts feeds the same dialog_messages table with a source tag, so dialog_search() finds matches regardless of where the conversation happened. Claude Desktop and the VS Code adapter are the exceptions — MCP registration only; their chats don't reach the table for now (Electron IndexedDB on the Claude Desktop side; per-extension stores on the VS Code side). Antigravity keeps one SQLite file per conversation with protobuf step payloads; thread-keeper opens it read-only (never creating WAL sidecars next to it) and keeps only user prompts and final model answers, skipping tool calls and thinking.

VS Code's user-level mcp.json is the central host that every MCP-aware VS Code extension consumes — GitHub Copilot Chat, the Anthropic Claude IDE plugin, the OpenAI Codex IDE plugin, Continue, Cline, … — so a single registration there reaches all of them at once.

Adding a new CLI = one file under threadkeeper/adapters/ implementing the CLIAdapter contract. See CONTRIBUTING.md.

Python MCP SDK surface

thread-keeper requires MCP Python SDK 2.3 or later (mcp>=2.3.0,<3). Its stable Skills and durable Tasks extensions use the MCP 2026-07-28 extension surface, while tools, resources, prompts, annotations, structured content, elicitation, and stdio continue to use the same MCPServer instance.

MCP primitives (tools, resources, prompts, Apps, elicitation)

MCP has three server primitives. thread-keeper uses all three, mapped to the read/act split, plus MCP elicitation for host-native confirmations:

Resources back the genuinely read-only memory views with the same render functions as the matching tools, so the content is identical — memory://brief is brief(), memory://context is context(), and so on. The win is for hookless CLIs: instead of depending on the agent *remembering* to call brief() (agents focused on their task often skip it), a resource lets the host surface memory as attachable / @-mentionable context through a mechanical channel. The brief resource renders lean and agent-status uses a cached snapshot, so an automatic host pull is side-effect-free.

search and dialog_search also return structured hits and resource_link blocks. Read a hit's resource_uri with resources/read to inspect its evidence without