threadctx-mcp

threadctx-mcp

Shared memory MCP server for AI coding agents. Works identically withClaude Code and Cursor — same package, same config shape, noper-client integration work.

Modes

• Local (default, free, no signup): memory stored as a plain JSON fileat ~/.threadctx/local.json — zero native dependencies, sonpx threadctx-mcp installs instantly on any machine with Node 18+ (nocompiler, no node-gyp step). No network calls except to whichever LLMprovider your agent already uses. Matching is keyword-based, scoped tothe current repo (detected via git remote). Run npx threadctx-mcp listany 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 fromthreadctx.dev (or your own self-hosteddeployment — see ../cloud/README.md).

Quick start

# Local mode — nothing to configure
npx threadctx-mcp

# Optional: write a committable config + drop "check team memory" into your
# agent's project rules (CLAUDE.md / .cursorrules). Works in local mode too.
npx threadctx-mcp init

# Cloud mode — prints the exact MCP config block to paste
npx threadctx-mcp init --mode=cloud --api-key=tctx_xxx

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

init writes a .threadctx.json file (just { "mode": "cloud" }) to thecurrent directory. It is safe to commit — it never contains your API key.The key is read from the THREADCTX_API_KEY environment variable atruntime (set it in your MCP client's env block, as shown below), sosecrets stay out of version control by construction.

init also adds a small, clearly-marked block to your CLAUDE.md and.cursorrules instructing the agent to call memory_query before a taskand memory_write after — this is what makes the memory reliably getread, since MCP tools are pull-based (pass --no-rules to skip). Re-runninginit refreshes that block in place instead of duplicating it.

Claude Code setup

Add to your Claude Code MCP config (claude mcp add or edit~/.claude/mcp.json directly):

{
  "mcpServers": {
    "threadctx": {
      "command": "npx",
      "args": ["-y", "threadctx-mcp"],
      "env": {
        "THREADCTX_MODE": "cloud",
        "THREADCTX_API_KEY": "tctx_xxx"
      }
    }
  }
}

Cursor setup

Add the same block to .cursor/mcp.json in your project root (or viaCursor Settings → Tools & MCP):

{
  "mcpServers": {
    "threadctx": {
      "command": "npx",
      "args": ["-y", "threadctx-mcp"],
      "env": {
        "THREADCTX_MODE": "cloud",
        "THREADCTX_API_KEY": "tctx_xxx"
      }
    }
  }
}

That's it — the same package and config work in both clients becauseMCP is a portable, open protocol.

Environment variables

Local development

npm install
npm run dev     # runs the server via tsx, watches for changes
npm run build   # compiles to dist/ for publishing

How the tools work

• memory_write(content, tags?) — the agent calls this after resolving anon-obvious bug, making an architectural decision, or learningsomething worth remembering.
• memory_query(task_description, max_results?) — the agent calls thisbefore starting risky or repeated work. Results are returned with aconsistent attribution footer (· via threadctx — shared team memory (N hits)) so the same string is recognizable whether you're readingClaude Code's terminal output or Cursor's agent panel.

Tool descriptions are deliberately written to bias the model towardcalling memory_query proactively — MCP is pull-based, so the agent hasto be prompted by the description to use it; it isn't automatic. For themost reliable behavior, run npx threadctx-mcp init, which adds an explicit"check team memory before/after each task" instruction to your CLAUDE.mdand .cursorrules.

CLI subcommands