Threadctx MCP server

threadctx-mcp

Shared memory MCP server for AI coding agents. Works identically with Claude Code, Cursor, and any MCP client — same package, same config shape, no per-client integration work. On first start it also drops a "check team memory" instruction into whichever agents' rule files your repo uses (AGENTS.md, CLAUDE.md, Copilot, Windsurf, Cline, Gemini) so the memory actually gets read, not just exposed.

This repo runs on itself: its own AGENTS.md and CLAUDE.md were set up

with npx threadctx-mcp init, the same command you'd run — check the git

history if you want to see it happen.

Modes

at ~/.threadctx/local.json — zero native dependencies, so npx threadctx-mcp installs instantly on any machine with Node 18+ (no compiler, no node-gyp step). No network calls except to whichever LLM provider your agent already uses. Matching is keyword-based, scoped to the current repo (detected via git remote). Run npx threadctx-mcp list any time to see exactly what your agents have stored.

• Local (default, free, no signup): memory stored as a plain JSON file

with real semantic search. Requires an API key from threadctx.dev (or your own self-hosted deployment — see ../cloud/README.md).

• Cloud (paid Team tier+): memory shared across everyone on the repo,

Quick start

# Local mode — nothing to configure. Also auto-adds the "check team memory"
# instruction to your agents' rule files (AGENTS.md, CLAUDE.md, and any
# detected tool-specific files) on first start.
npx threadctx-mcp

# Set a repo up for your whole team (run once, commit the results)
npx threadctx-mcp init

# Cloud mode — shared team memory via threadctx.dev
npx threadctx-mcp init --mode=cloud --api-key=tctx_xxx

# Joining a repo a teammate already set up? One command:
npx threadctx-mcp join

# See what your agents have written to this machine
npx threadctx-mcp list            # this repo
npx threadctx-mcp list --all      # every repo

init writes three committable, secret-free files: .threadctx.json (just { "mode": ... }), .mcp.json (Claude Code project config), and .cursor/mcp.json (Cursor project config). Commit all three — every teammate who then opens the repo in Claude Code or Cursor is prompted to enable threadctx automatically, with nothing to install or configure. Teammates on other MCP clients run npx threadctx-mcp join, which sets up their machine the same way and prints the config block for their client.

Your API key never appears in any committed file. It is read from the THREADCTXAPIKEY environment variable at runtime (export it in your shell profile), so secrets stay out of version control by construction.

threadctx also adds a small, clearly-marked instruction to your project rules telling the agent to call memoryquery before a task and memorywrite after. It writes the two universal files every time — AGENTS.md (the cross-tool standard read by Copilot, Cursor, Windsurf, Zed, Codex, Aider, and ~24 others) and CLAUDE.md (Claude Code's richer native format) — plus .cursor/rules/threadctx.mdc. It then adds a tool-specific file only when that tool's footprint is detected in the repo, so it never litters your project with rule files for tools you don't use:

Shortened. The full README is on GitHub.