threadctx-dev/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
- **Local (default, free, no signup):** memory stored as a plain JSON file
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.
- **Cloud (paid Team tier+):** memory shared across everyone on the repo,
with real semantic search. Requires an API key from
threadctx.dev (or your own self-hosted
deployment — see ../cloud/README.md).
Quick start
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
THREADCTX_API_KEY 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 memory_query before a task and
memory_write 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:
| Tool | File written | Written when |
|---|---|---|
| Cross-tool standard | AGENTS.md | always |
| Claude Code | CLAUDE.md | always |
| Cursor | .cursor/rules/threadctx.mdc | always |
| GitHub Copilot | .github/copilot-instructions.md | .github/ exists |
| Windsurf | .windsurf/rules/threadctx.md | .windsurf/ exists |
| Cline | .clinerules/threadctx.md | .clinerules exists |
| Gemini CLI | GEMINI.md | .gemini/ exists |
Shared files (AGENTS.md, CLAUDE.md, Copilot, Gemini) get a marker-fenced
block spliced in, preserving your own content around it; dedicated files are
owned in full. **This happens automatically the first time the server starts
in a project — you don't need to run init for it.** Running init just
triggers it explicitly and prints the result; either way it's idempotent
(safe to re-run, never duplicates). Opt out entirely with
THREADCTX_NO_AUTO_RULES=1, or per-init-call with --no-rules.
The same instruction is also sent as part of the MCP initialize handshake