thread-keeper — Claude Code MCP server: shared agent memory
A local MCP server that gives separate agent CLIs one memory store, lets parallel sessions signal each other, and grows a skill library as they work.
claude mcp add thread-keeper -- uvx threadkeeperWhat thread-keeper does
Connected clients — Claude, Claude Desktop, Claude, Antigravity CLI, Copilot, MCP-aware VS Code extensions — read and write the same SQLite database. Threads, notes, quotes and a user model outlive a restart or a switch between tools. At session start the server injects a compressed brief of about 6 KB filled with structural tags and opaque IDs. It is built for an agent to parse, not for you to read.
Parallelism comes from the spawn primitive: children each get a self_cid and the same memory. The broadcast, whisper, inbox, wait, ask and respond calls let sessions talk across different CLIs. Class-level skills are written to SKILL.md and mirrored into every known skills root — ~/.claude/skills/, ~/.codex/skills/, ~/.gemini/config/skills/, extra dirs listed in THREADKEEPER_EXTRA_SKILLS_DIRS. For hosts with no native skill loader there is lessons.md as a fallback.
Python 3.11+ is required, and the server runs through uvx. Install 'threadkeeper[semantic]' with pipx, then run thread-keeper-setup, which registers the MCP entry in each detected CLI config, copies hooks into ~/.threadkeeper/hooks/ and writes a managed instructions block into CLAUDE.md, AGENTS.md or copilot-instructions.md. A daily self-update runs by default; a dirty or diverged git checkout is skipped instead of being overwritten, so local commits survive.
The brief at session start is dense on purpose and will look like noise if you open it yourself.
What it helps with
- carry context from a Claude session into Claude without retyping it
- stop two parallel agents from duplicating the same task
- keep notes and quotes after a thread is closed
- collect skills from several CLIs into one directory
- load a project brief at the start of a fresh session
Example prompts for the agent
- Open a thread for the auth work and note everything you find in it
- Spawn two child agents: one fixes the tests, the other updates the docs
- Check
inboxfor messages from the other session
How to install thread-keeper
Platform CLI
claude mcp add thread-keeper -- uvx threadkeeperuvx runs the command named after the package; if the README names another one, use uvx --from threadkeeper <command>
Platform CLI
codex mcp add thread-keeper -- uvx threadkeeperuvx runs the command named after the package; if the README names another one, use uvx --from threadkeeper <command>
Config file
{
"mcpServers": {
"thread-keeper": {
"command": "uvx",
"args": [
"threadkeeper"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from threadkeeper <command>
Config file
{
"servers": {
"thread-keeper": {
"type": "stdio",
"command": "uvx",
"args": [
"threadkeeper"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from threadkeeper <command>
Platform CLI
gemini mcp add thread-keeper uvx threadkeeperuvx runs the command named after the package; if the README names another one, use uvx --from threadkeeper <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about thread-keeper
How do I install thread-keeper in Claude Code?
Run claude mcp add thread-keeper -- uvx threadkeeper, then restart the CLI.
What does thread-keeper do?
It keeps shared memory and coordination for several agent CLIs on top of one SQLite store, and adds to a skill library while the agents work.
What is needed to run it?
Python 3.11+ and uvx. The full setup with hooks and instructions comes from thread-keeper-setup after pipx install 'threadkeeper[semantic]'.
