Threadctx

threadctx-mcp

面向 AI 编码 Agent 的共享记忆 MCP 服务。与 Claude Code、Cursor 和任何 MCP 客户端的运行方式都完全相同——同一个包、同一种配置格式，无需针对不同客户端进行集成。首次启动时，它还会将一条“检查团队记忆”的指令写入仓库所用 Agent 的规则文件（AGENTS.md、CLAUDE.md、Copilot、Windsurf、Cline、Gemini），确保 Agent 真正读取记忆，而不仅仅是能够访问。

这个仓库本身也在使用它：仓库自己的 AGENTS.md 和 CLAUDE.md 是通过 npx threadctx-mcp init 设置的，这就是你也可以运行的命令——查看 git 历史记录即可了解整个过程。

模式

• **本地（默认，免费，无需注册）：**记忆以普通 JSON 文件的形式存储在 ~/.threadctx/local.json 中——零原生依赖，因此在任何安装了 Node 18+ 的机器上，npx threadctx-mcp 都能即时安装（无需编译器，也无需执行 node-gyp）。除 Agent 已使用的 LLM 提供商外，不会进行任何网络调用。匹配基于关键词，并限定在当前仓库范围内（通过 git remote 检测）。随时运行 npx threadctx-mcp list 即可准确查看 Agent 存储的内容。
• **云端（付费 Team 层级及以上）：**记忆在仓库所有成员之间共享，并支持真正的语义搜索。需要从 threadctx.dev 获取 API 密钥（或使用你自己的可自托管部署——请参阅 ../cloud/README.md）。

快速开始

# 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 会写入三个可提交且不含密钥的文件：.threadctx.json （仅包含 { "mode": ... }）、.mcp.json（Claude Code 项目配置）和 .cursor/mcp.json（Cursor 项目配置）。将这三个文件全部提交——之后，每位在 Claude Code 或 Cursor 中打开仓库的团队成员都会收到提示，自动启用 threadctx，无需安装或配置任何内容。 使用其他 MCP 客户端的团队成员运行 npx threadctx-mcp join，即可用同样的方式设置自己的机器，并打印适用于其客户端的配置块。

你的 API 密钥绝不会出现在任何已提交文件中。运行时会从 THREADCTX_API_KEY 环境变量读取密钥（在 shell 配置文件中导出该变量），因此从机制上保证密钥不会进入版本控制。

threadctx 还会在项目规则中添加一条简短且有明确标记的指令，告知 Agent 在任务开始前调用 memory_query，并在完成后调用 memory_write。每次都会写入两个通用文件——AGENTS.md（由 Copilot、Cursor、Windsurf、Zed、Codex、Aider 等约 24 种工具读取的跨工具标准）和 CLAUDE.md（Claude Code 更丰富的原生格式）——以及 .cursor/rules/threadctx.mdc。 只有检测到仓库中存在相应工具的痕迹时，才会添加该工具专属文件，因此不会为你未使用的工具在项目中到处创建规则文件：

工具	写入的文件	写入条件
跨工具标准	AGENTS.md	始终
Claude Code	CLAUDE.md	始终
Cursor	.cursor/rules/threadctx.mdc	始终
GitHub Copilot	.github/copilot-instructions.md	存在 .github/
Windsurf	.windsurf/rules/threadctx.md	存在 .windsurf/
Cline	.clinerules/threadctx.md	存在 .clinerules
Gemini CLI	GEMINI.md	存在 .gemini/

对于共享文件（AGENTS.md、CLAUDE.md、Copilot、Gemini），会插入带标记边界的内容块，并保留周边的自有内容；专用文件则由 threadctx 完全管理。**MCP 服务首次在项目中启动时，这些操作会自动进行——无需运行 init。**运行 init 只会显式触发这些操作并打印结果；无论哪种方式，操作都是幂等的（可以安全地重复运行，且不会重复添加）。使用 THREADCTX_NO_AUTO_RULES=1 完全退出，或在单次 init 调用中使用 --no-rules。

同一条指令也会作为 MCP initialize 握手的一部分发送（即协议的 instructions 字段），因此即使规则文件尚不存在，模型也能收到指令；不读取项目规则文件的客户端也能收到。基于文件的规则则在此基础上提供双重保障，因为无法保证每个 MCP 客户端都会显著展示 instructions。

Claude Code 设置

将以下内容添加到 Claude Code MCP 配置中（使用 claude mcp add，或直接编辑 ~/.claude/mcp.json）：

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

Cursor 设置

将相同的配置块添加到项目根目录下的 .cursor/mcp.json（或通过 Cursor Settings → Tools & MCP 添加）：

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

完成——相同的包和配置可用于这两个客户端，因为 MCP 是可移植的开源协议。

被动捕获——将 git 历史转化为记忆

记忆不应依赖 Agent 记得调用 memory_write。 threadctx capture 会读取上次运行后新增的提交，使用你自己的大模型提供商密钥提炼真正可复用的决策和注意事项（跳过琐碎提交），将其与已存储的内容去重，并写入筛选后保留的内容。它与工具无关——无论工作是在 Claude Code、Cursor、Copilot 还是普通编辑器中完成，都没有影响。

# Off by default because it calls an LLM (billed to your provider). Enable it:
export THREADCTX_CAPTURE_ENABLED=1
export ANTHROPIC_API_KEY=sk-...     # or OPENAI_API_KEY

npx threadctx-mcp capture --dry-run     # preview what it would store
npx threadctx-mcp capture               # store them (incremental since last run)
npx threadctx-mcp capture --since=v1.2.0 --diffs   # a range, with patches

# Scaffold a GitHub Action that captures every merged PR automatically:
npx threadctx-mcp capture --print-workflow > .github/workflows/threadctx-capture.yml

捕获过程会直接调用你的大模型提供商——不会通过 threadctx 的服务器转发任何内容，因此本地模式仍会遵守“除你自己的大模型提供商外，不进行网络调用”的承诺。除非设置 THREADCTX_CAPTURE_ENABLED=1（或单次使用 --force），否则此功能默认关闭，因此绝不会意外产生 token 费用。

环境变量

变量	必需	描述
THREADCTX_MODE	否	local（默认）或 cloud
THREADCTX_API_KEY	仅在 cloud 模式下	通过 cloud/scripts/create-tenant.ts 签发
THREADCTX_API_URL	否	默认为 https://threadctx.dev/api/v1；可覆盖此值以进行自托管
THREADCTX_REPO	否	覆盖根据 git remote 自动检测的仓库
THREADCTX_DB_PATH	否	local 模式下的存储路径；默认为 ~/.threadctx/local.json
THREADCTX_NO_AUTO_RULES	否	设为 1 可在服务启动时禁用自动注入 Agent 规则文件
THREADCTX_CAPTURE_ENABLED	capture 所需	设为 1 可启用由大模型支持的 capture 命令（默认关闭）
THREADCTX_CAPTURE_PROVIDER	否	同时提供两个密钥时，强制使用 anthropic 或 openai
THREADCTX_CAPTURE_MODEL	否	覆盖提取模型（默认：Haiku / gpt-4o-mini）
ANTHROPIC_API_KEY / OPENAI_API_KEY	capture 所需	你自己的提供商密钥；capture 会直接调用该提供商

本地开发

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

工具的工作方式

• memory_write(content, tags?) — Agent 在解决不明显的错误、做出架构决策或学到值得记住的内容后调用此工具。
• memory_query(task_description, max_results?) — Agent 在开始风险较高或重复性的工作前调用此工具。结果会附带一致的归属说明页脚（· via threadctx — shared team memory (N hits)），因此无论你是在阅读 Claude Code 的终端输出，还是 Cursor 的 Agent 面板，都能通过相同的字符串识别。

工具描述旨在引导模型主动调用 memory_query；从 0.3.0 起，服务还会以另外两种方式强化这一点，且无需任何设置：MCP initialize 响应会向每个连接的客户端附带相同的指令；首次启动时，还会自动注入 CLAUDE.md / .cursor/rules/threadctx.mdc。MCP 工具本质上仍是拉取式的（没有任何机制可以强制调用工具），但这三个层面共同构成了我们能够实现的最强保障。

CLI 子命令

命令	功能
npx threadctx-mcp	运行 MCP 服务（Claude Code / Cursor 启动的就是它）。在项目中首次启动时自动注入项目规则。
npx threadctx-mcp init [--mode=cloud --api-key=…] [--no-rules]	为团队配置仓库：写入 .threadctx.json、可提交的 Claude Code/Cursor 项目 MCP 配置，以及项目规则文件。
npx threadctx-mcp join	加入队友已配置好的仓库：获取项目 MCP 配置、规则和各客户端的说明。
npx threadctx-mcp list [--all] [--full] [--json]	显示本地磁盘记忆中存储的内容。
npx threadctx-mcp capture [--dry-run] [--since=<ref>] [--max=N] [--diffs] [--model=ID] [--print-workflow]	使用你自己的大模型密钥，将近期 Git 历史提炼为记忆。除非设置 THREADCTX_CAPTURE_ENABLED=1（或使用 --force），否则此功能处于关闭状态。

在人工操作的仪表板中浏览、搜索、编辑和清理团队（cloud）记忆： threadctx.dev/dashboard — 使用团队 API 密钥登录。