{
  "markdown": "# threadctx-mcp\n\n[![smithery badge](https://smithery.ai/badge/oneprofile-dev/threadctx)](https://smithery.ai/servers/oneprofile-dev/threadctx)\n\nShared memory MCP server for AI coding agents. Works identically with\n**Claude Code**, **Cursor**, and any MCP client — same package, same config\nshape, no per-client integration work. On first start it also drops a\n\"check team memory\" instruction into whichever agents' rule files your repo\nuses (`AGENTS.md`, `CLAUDE.md`, Copilot, Windsurf, Cline, Gemini) so the\nmemory actually gets read, not just exposed.\n\n> This repo runs on itself: its own `AGENTS.md` and `CLAUDE.md` were set up\n> with `npx threadctx-mcp init`, the same command you'd run — check the git\n> history if you want to see it happen.\n\n## Modes\n\n- **Local (default, free, no signup):** memory stored as a plain JSON file\n  at `~/.threadctx/local.json` — **zero native dependencies**, so\n  `npx threadctx-mcp` installs instantly on any machine with Node 18+ (no\n  compiler, no node-gyp step). No network calls except to whichever LLM\n  provider your agent already uses. Matching is keyword-based, scoped to\n  the current repo (detected via `git remote`). Run `npx threadctx-mcp list`\n  any time to see exactly what your agents have stored.\n- **Cloud (paid Team tier+):** memory shared across everyone on the repo,\n  with real semantic search. Requires an API key from\n  [threadctx.dev](https://threadctx.dev) (or your own self-hosted\n  deployment — see `../cloud/README.md`).\n\n## Quick start\n\n```bash\n# Local mode — nothing to configure. Also auto-adds the \"check team memory\"\n# instruction to your agents' rule files (AGENTS.md, CLAUDE.md, and any\n# detected tool-specific files) on first start.\nnpx threadctx-mcp\n\n# Set a repo up for your whole team (run once, commit the results)\nnpx threadctx-mcp init\n\n# Cloud mode — shared team memory via threadctx.dev\nnpx threadctx-mcp init --mode=cloud --api-key=tctx_xxx\n\n# Joining a repo a teammate already set up? One command:\nnpx threadctx-mcp join\n\n# See what your agents have written to this machine\nnpx threadctx-mcp list            # this repo\nnpx threadctx-mcp list --all      # every repo\n```\n\n`init` writes three committable, secret-free files: `.threadctx.json`\n(just `{ \"mode\": ... }`), `.mcp.json` (Claude Code project config), and\n`.cursor/mcp.json` (Cursor project config). Commit all three — every\nteammate who then opens the repo in Claude Code or Cursor is prompted to\nenable threadctx automatically, with nothing to install or configure.\nTeammates on other MCP clients run `npx threadctx-mcp join`, which sets up\ntheir machine the same way and prints the config block for their client.\n\nYour API key never appears in any committed file. It is read from the\n`THREADCTX_API_KEY` environment variable at runtime (export it in your\nshell profile), so secrets stay out of version control by construction.\n\nthreadctx also adds a small, clearly-marked instruction to your project\nrules telling the agent to call `memory_query` before a task and\n`memory_write` after. It writes the two universal files every time —\n[`AGENTS.md`](https://agents.md) (the cross-tool standard read by Copilot,\nCursor, Windsurf, Zed, Codex, Aider, and ~24 others) and `CLAUDE.md`\n(Claude Code's richer native format) — plus `.cursor/rules/threadctx.mdc`.\nIt then adds a tool-specific file **only when that tool's footprint is\ndetected in the repo**, so it never litters your project with rule files for\ntools you don't use:\n\n| Tool | File written | Written when |\n|---|---|---|\n| Cross-tool standard | `AGENTS.md` | always |\n| Claude Code | `CLAUDE.md` | always |\n| Cursor | `.cursor/rules/threadctx.mdc` | always |\n| GitHub Copilot | `.github/copilot-instructions.md` | `.github/` exists |\n| Windsurf | `.windsurf/rules/threadctx.md` | `.windsurf/` exists |\n| Cline | `.clinerules/threadctx.md` | `.clinerules` exists |\n| Gemini CLI | `GEMINI.md` | `.gemini/` exists |\n\nShared files (`AGENTS.md`, `CLAUDE.md`, Copilot, Gemini) get a marker-fenced\nblock spliced in, preserving your own content around it; dedicated files are\nowned in full. **This happens automatically the first time the server starts\nin a project — you don't need to run `init` for it.** Running `init` just\ntriggers it explicitly and prints the result; either way it's idempotent\n(safe to re-run, never duplicates). Opt out entirely with\n`THREADCTX_NO_AUTO_RULES=1`, or per-`init`-call with `--no-rules`.\n\nThe same instruction is also sent as part of the MCP `initialize` handshake\nitself (the protocol's `instructions` field), so it reaches the model even\nbefore any rules file exists, and for clients that don't read project-rules\nfiles at all. The file-based rules are belt-and-suspenders on top of that,\nsince not every MCP client is guaranteed to surface `instructions`\nprominently.\n\n## Claude Code setup\n\nAdd to your Claude Code MCP config (`claude mcp add` or edit\n`~/.claude/mcp.json` directly):\n\n```json\n{\n  \"mcpServers\": {\n    \"threadctx\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"threadctx-mcp\"],\n      \"env\": {\n        \"THREADCTX_MODE\": \"cloud\",\n        \"THREADCTX_API_KEY\": \"tctx_xxx\"\n      }\n    }\n  }\n}\n```\n\n## Cursor setup\n\nAdd the same block to `.cursor/mcp.json` in your project root (or via\nCursor Settings → Tools & MCP):\n\n```json\n{\n  \"mcpServers\": {\n    \"threadctx\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"threadctx-mcp\"],\n      \"env\": {\n        \"THREADCTX_MODE\": \"cloud\",\n        \"THREADCTX_API_KEY\": \"tctx_xxx\"\n      }\n    }\n  }\n}\n```\n\nThat's it — the same package and config work in both clients because\nMCP is a portable, open protocol.\n\n## Passive capture — turn git history into memory\n\nMemory shouldn't depend on an agent *remembering* to call `memory_write`.\n`threadctx capture` reads the commits landed since its last run, uses **your\nown LLM provider key** to distill the genuinely reusable decisions and\ngotchas (skipping trivial commits), dedups them against what's already\nstored, and writes the survivors. It's tool-agnostic — it doesn't matter\nwhether the work happened in Claude Code, Cursor, Copilot, or a plain editor.\n\n```bash\n# Off by default because it calls an LLM (billed to your provider). Enable it:\nexport THREADCTX_CAPTURE_ENABLED=1\nexport ANTHROPIC_API_KEY=sk-...     # or OPENAI_API_KEY\n\nnpx threadctx-mcp capture --dry-run     # preview what it would store\nnpx threadctx-mcp capture               # store them (incremental since last run)\nnpx threadctx-mcp capture --since=v1.2.0 --diffs   # a range, with patches\n\n# Scaffold a GitHub Action that captures every merged PR automatically:\nnpx threadctx-mcp capture --print-workflow > .github/workflows/threadctx-capture.yml\n```\n\nCapture calls your LLM provider directly — nothing is routed through\nthreadctx's servers, so local mode keeps its \"no network call beyond your own\nLLM provider\" promise. It is **off unless `THREADCTX_CAPTURE_ENABLED=1`** (or\na one-off `--force`), so it can never run up token cost as a side effect.\n\n## Environment variables\n\n| Variable | Required | Description |\n|---|---|---|\n| `THREADCTX_MODE` | no | `local` (default) or `cloud` |\n| `THREADCTX_API_KEY` | only in cloud mode | issued via `cloud/scripts/create-tenant.ts` |\n| `THREADCTX_API_URL` | no | defaults to `https://threadctx.dev/api/v1`; override for self-hosting |\n| `THREADCTX_REPO` | no | overrides repo auto-detection from `git remote` |\n| `THREADCTX_DB_PATH` | no | local-mode store path; defaults to `~/.threadctx/local.json` |\n| `THREADCTX_NO_AUTO_RULES` | no | set to `1` to disable auto-injecting agent rule files on server start |\n| `THREADCTX_CAPTURE_ENABLED` | for `capture` | set to `1` to enable the LLM-backed `capture` command (off by default) |\n| `THREADCTX_CAPTURE_PROVIDER` | no | force `anthropic` or `openai` when both keys are present |\n| `THREADCTX_CAPTURE_MODEL` | no | override the extraction model (defaults: Haiku / gpt-4o-mini) |\n| `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` | for `capture` | your own provider key; capture calls it directly |\n\n## Local development\n\n```bash\nnpm install\nnpm run dev     # runs the server via tsx, watches for changes\nnpm run build   # compiles to dist/ for publishing\n```\n\n## How the tools work\n\n- `memory_write(content, tags?)` — the agent calls this after resolving a\n  non-obvious bug, making an architectural decision, or learning\n  something worth remembering.\n- `memory_query(task_description, max_results?)` — the agent calls this\n  before starting risky or repeated work. Results are returned with a\n  consistent attribution footer (`· via threadctx — shared team memory (N\n  hits)`) so the same string is recognizable whether you're reading\n  Claude Code's terminal output or Cursor's agent panel.\n\nTool descriptions are written to bias the model toward calling\n`memory_query` proactively, and — as of 0.3.0 — the server reinforces this\ntwo more ways with zero setup required: the MCP `initialize` response\ncarries the same instruction to every connecting client, and `CLAUDE.md` /\n`.cursor/rules/threadctx.mdc` get it auto-injected on first start. MCP tools\nare still fundamentally pull-based (no mechanism can force a tool call), but\nthese three layers together are the strongest guarantee we can build.\n\n## CLI subcommands\n\n| Command | What it does |\n|---|---|\n| `npx threadctx-mcp` | Runs the MCP server (this is what Claude Code / Cursor launch). Auto-injects project rules on first start in a project. |\n| `npx threadctx-mcp init [--mode=cloud --api-key=…] [--no-rules]` | Sets a repo up for the team: writes `.threadctx.json`, committable Claude Code/Cursor project MCP configs, and the project-rules files. |\n| `npx threadctx-mcp join` | Joins a repo a teammate already set up: project MCP configs, rules, and per-client instructions. |\n| `npx threadctx-mcp list [--all] [--full] [--json]` | Shows what's stored in the local on-disk memory. |\n| `npx threadctx-mcp capture [--dry-run] [--since=<ref>] [--max=N] [--diffs] [--model=ID] [--print-workflow]` | Distills recent git history into memories via your own LLM key. Off unless `THREADCTX_CAPTURE_ENABLED=1` (or `--force`). |\n\nBrowse, search, edit, and prune team (cloud) memory in a human dashboard at\n[threadctx.dev/dashboard](https://threadctx.dev/dashboard) — sign in with your\nteam API key.\n",
  "bytes": 10240,
  "sha": "4a32cb06425962efa9425a12f105b5144421f822bfb69da5eac82b5890e36455",
  "repo_slug": "threadctx-dev/threadctx-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_threadctx_dev_threadctx_mcp_60c46d02/readme"
}