thread-mind

ThreadMind MCP

为 AI 记忆分支：以 Git 友好的树形结构组织对话摘要。

ThreadMind 是一个 模型上下文协议（MCP）服务，为 AI 编码会话提供记忆：一棵由对话组成的树，每个对话都用 Markdown 存储在你的代码仓库中，并包含某个主题的简短决策摘要。开启新会话时，当前对话的上下文——包括它的决策及其祖先对话的决策——将取代可能已增长到数万个 token 的历史记录。

文档 | npm | GitHub

---

为什么选择 ThreadMind？

使用 AI 编码助手时，对话会不断变长：每个请求都携带完整历史，直到客户端压缩历史，或你从头开始——但从头开始会丢失已经做出的决定。ThreadMind 会保留重要内容：

• 按部分组织的摘要 — 决策、约束、状态、待解决问题、后续步骤
• 沿树继承上下文 — 对话上下文由其摘要及其祖先对话的决策和约束组成；同级分支的内容不会包含在内
• 分支探索 — 在不同对话中尝试各种方案，将胜出方案的结论合并到父对话中，并保留放弃某个方案的原因
• 感知 Git — 在功能分支上创建的对话会在检出该分支时自动激活；当对话所描述的代码发生变化时，摘要会发出警告
• 团队协作 — 对话文件与代码一同提交，并在拉取请求中审查

节省从何而来

ThreadMind 无法缩短正在进行的对话：发送哪些内容由客户端决定。节省来自重新开始时：

Before /clear:   the conversation carries ~48,000 tokens of history
After /clear:    the session starts with the thread's context, ~1,100 tokens

main
├── auth
│   └── auth-ui ← active     context = main + auth (decisions, constraints) + auth-ui
└── dashboard                 dashboard stays out

使用 Claude Code 插件 后，执行 /clear 和压缩后都会自动重新加载上下文，而 stats_show 会测量你自己会话的这两种大小。

---

快速开始

Claude Code 插件（推荐）

/plugin marketplace add mahmoud-nb/thread-mind-mcp
/plugin install thread-mind@thread-mind

该插件会安装服务并添加以下钩子：

• 在启动时、执行 /clear 后以及压缩后加载当前对话的上下文（在没有 ThreadMind 项目的代码仓库中不会执行任何操作）
• 随着对话增长，提醒 Claude 保存摘要，并在上下文窗口即将填满时再提醒一次
• 恢复尚未保存就发生压缩的摘要，并在 /clear 丢弃未保存的工作时通知你
• 跟踪 Git 分支变更，并向 Claude 提供新当前对话的上下文
• 将 Claude 编辑的文件与下一份摘要一同记录，以便在文件发生变化时发出标记
• 即时响应 tm:tree 和 tm:stats，不消耗 token
• 从对话记录中读取对话增长情况，供 stats_show 使用

它还提供命令（/thread-mind:context、/thread-mind:tree、/thread-mind:create、/thread-mind:switch、/thread-mind:summary、/thread-mind:merge、/thread-mind:stats）以及 /config 中的选项。状态行（thread-mind-mcp status-line）会显示当前对话及其未保存的工作。请参阅插件指南。

如果你之前手动配置过 ThreadMind，请移除该配置，以免 Claude Code 运行两个服务。

安装

无需安装——直接使用 npx 运行：

npx thread-mind-mcp

或者全局安装：

npm install -g thread-mind-mcp

配置 Claude Code（不使用插件）

在项目根目录中运行。若要与团队共享此服务，请将其添加到项目范围：Claude Code 会在项目根目录下写入 .mcp.json，并将其提交到版本库。

# macOS / Linux
claude mcp add --scope project thread-mind -- npx -y thread-mind-mcp

# Windows: npx is a .cmd script, wrap it in cmd /c
claude mcp add --scope project thread-mind -- cmd /c npx -y thread-mind-mcp

生成的 .mcp.json（也可以手动编写）：

{
  "mcpServers": {
    "thread-mind": {
      "command": "npx",
      "args": ["-y", "thread-mind-mcp"]
    }
  }
}

在 Windows 上，使用 "command": "cmd" 和 "args": ["/c", "npx", "-y", "thread-mind-mcp"]。每位队友首次在该仓库中启动 Claude Code 时，都需要批准此服务。

仅供自己使用时，移除 --scope project（默认范围为 local：仅你在此项目中使用），或使用 --scope user（仅你使用，适用于每个项目）。这两种配置都存储在 ~/.claude.json 中，由 Claude Code 管理。

范围	存储位置	适用对象
local（默认）	~/.claude.json，位于当前项目下	你，仅在此项目中
project	项目根目录下的 .mcp.json	所有克隆该仓库的人
user	~/.claude.json	你，适用于每个项目

Claude Code 不会从 ~/.claude/settings.json 或 .claude/settings.json 读取 MCP 服务。使用 claude mcp list 或在会话中使用 /mcp 检查配置。

**Windows + Volta：**如果 Claude Code 无法解析 Volta 的 npx 垫片，请改用 volta run：

claude mcp add --scope project thread-mind -- cmd /c volta run npx -y thread-mind-mcp

配置其他 MCP 客户端

ThreadMind 使用 stdio 传输，兼容任何 MCP 客户端。命令始终为 npx -y thread-mind-mcp；不同之处在于各客户端声明该服务的位置，以及是否读取服务发送的使用说明：

客户端	服务配置	使用说明
Cursor	.cursor/mcp.json 或 ~/.cursor/mcp.json	AGENTS.md
VS Code（GitHub Copilot）	.vscode/mcp.json（servers 键）或 .mcp.json	由服务发送
GitHub Copilot CLI	.mcp.json 或 copilot mcp add thread-mind -- npx -y thread-mind-mcp	AGENTS.md
Codex	codex mcp add thread-mind -- npx -y thread-mind-mcp（~/.codex/config.toml）	由服务发送
Gemini CLI	.gemini/settings.json 或 ~/.gemini/settings.json	由服务发送
Windsurf（Devin Desktop）	mcp_config.json	AGENTS.md
Claude Desktop（聊天）	claude_desktop_config.json，并将 THREADMIND_ROOT 设为项目路径	如有需要，配置 Claude 项目说明

Claude Code、VS Code 和 Copilot CLI 共用仓库根目录下的 .mcp.json 文件。各客户端的配置方法请参阅其他 AI 客户端。

工作区位置

ThreadMind 会在工作区根目录下的 .threadmind/ 中存储数据，查找顺序如下：

1. 已设置的 THREADMIND_ROOT 环境变量
2. MCP 客户端声明的工作区根目录（若某个根目录已包含 .threadmind/，则优先使用该目录）。Claude Code 会声明启动时所在的目录，以及通过 --add-dir 添加的目录：请从项目根目录启动它
3. 启动服务时所在的目录

如果客户端在项目之外启动服务，且未声明根目录（例如没有项目文件夹的桌面聊天应用），则需要设置 THREADMIND_ROOT：

{
  "mcpServers": {
    "thread-mind": {
      "command": "npx",
      "args": ["-y", "thread-mind-mcp"],
      "env": { "THREADMIND_ROOT": "/path/to/your/project" }
    }
  }
}

教会 AI 客户端使用 ThreadMind

客户端连接时，服务会发送使用说明（MCP 服务说明）：Claude Code、VS Code（GitHub Copilot）、Codex 和 Gemini CLI 无需设置文件。对于不读取这些说明的 Agent（如 Cursor、Copilot CLI 或 Windsurf），请运行 threadmind_init 以生成 AGENTS.md 文件。

---

工作原理

核心概念

概念	描述
项目	包含线程树的工作区。拥有标题、系统上下文和模式（solo/team）。
线程	树中的一个节点，代表一个讨论主题。保存 Markdown 摘要，并可关联到 git 分支、标记为已完成或已放弃。
摘要	线程中已作出的决定，分为以下部分：决策、约束、状态、待解决问题、后续步骤。
上下文	当前活动线程的摘要，加上其祖先线程的决策和约束——即 AI 加载的内容。
会话	每个客户端会话都有自己的活动线程；新会话从当前检出的 git 分支开始。

存储

ThreadMind 会将所有内容存储在项目根目录的 .threadmind/ 目录中：

.threadmind/
  config.json              # Local state: where sessions start, author ID, session measurements
  .gitignore               # Excludes config.json from git
  projects/
    my-app.json            # Project configuration
  threads/
    my-app/
      main.md              # Root thread (markdown + YAML frontmatter)
      auth-system.md       # Child thread
      auth-api.md          # Grandchild thread

线程文件使用 YAML frontmatter。每个文件都会记录其父线程：树会根据这些文件重建，无需维护索引，也不会在 git 中产生冲突。

---
id: auth-system
title: Authentication System
parentId: main
author: mahmoud-a3f9
createdAt: 2026-04-15T10:00:00.000Z
updatedAt: 2026-04-15T12:30:00.000Z
branch: feature/auth
commit: 3f2a9c1e5b7d4a8f0c6e2b1d9a7f5c3e1b0d8a6f
paths: ["src/auth"]
---

## Decisions
- JWT with refresh tokens, stored in httpOnly cookies
- Passport.js over custom middleware, for maintainability

## State
- Login and refresh done, logout pending

只有设置了 status、branch、commit、paths 和 mergedInto 时，它们才会出现。

上下文组装

请求上下文时，ThreadMind 会从活动线程向上遍历到根节点。它会保留活动线程的完整摘要，而其祖先线程仅保留 决策 和 约束：

## System Context
You are building a Next.js e-commerce application...

---

## Thread: My App

## Decisions
- Next.js 15, PostgreSQL, Stripe

---

## Thread: Authentication System

## Decisions
- JWT with refresh tokens, bcrypt, Passport.js

---

## Thread: Auth API Endpoints (active)

_⚠ 2 commits changed src/api since this summary was written: check it is still accurate._

## Decisions
- POST /auth/login, POST /auth/register, POST /auth/refresh

## Next steps
- Rate limiting on /auth/login

---
_ThreadMind context: ~160 tokens | depth: 3 threads_

• 仅包含直接祖先链——不包含同级分支
• 如果摘要是在代码变更之前编写的，会根据其记录的 commit 和 paths 标记出来
• 如果上下文过大，maxTokens 会优先省略距离最远的祖先线程

---

可用工具

每个工具都会声明标题和 MCP 注释（只读、具有破坏性、幂等），客户端可据此决定何时请求确认。

项目管理

工具	描述
project_create	创建新项目，并附带一个根“main”线程
project_list	列出所有项目（显示会话所属项目）
project_switch	将会话切换到其他项目（只有一个项目时会自动选中）

project_create

参数	类型	必填	描述
title	string	是	项目标题（用于生成 ID）
systemContext	string	否	系统提示词或全局指令
mode	"solo" | "team"	否	项目模式（默认值："solo"）

线程管理

工具	描述
thread_create	创建子线程；在功能分支上时，将其关联到该分支
thread_switch	将此会话切换到其他线程，并返回组装好的上下文
thread_list	显示线程树及其状态和关联分支
thread_status	将线程标记为已完成或已放弃（原因会保留在其决策中），或重新打开线程
thread_merge	将已完成的线程合并到其父线程：替换父线程的摘要，并将该线程标记为已完成
thread_delete	删除线程及其所有后代线程
thread_rebase	将线程移至其他父线程（类似于 git rebase）

thread_create

参数	类型	必填	描述
title	string	是	线程标题（用于生成 ID）
parentId	string	否	父线程 ID（默认为活动线程）

thread_status

参数	类型	必填	描述
status	"active" | "done" | "abandoned"	是	新状态
threadId	string	否	目标线程（默认为活动线程）
reason	string	否	原因，会添加到线程的“决策”部分

thread_merge

参数	类型	必填	描述
parentSummary	string	是	父线程的新摘要，包含该线程的结论
threadId	string	否	要合并的线程（默认为活动线程）

thread_delete

参数	类型	必填	描述
threadId	string	是	要删除的线程 ID（会级联删除其后代）

thread_rebase

参数	类型	必填	描述
threadId	string	是	要移动的线程 ID
newParentId	string	是	新的父线程 ID

摘要与上下文

工具	描述
summary_update	更新线程摘要或其中一个章节
context_get	获取组装后的上下文及令牌估算

summary_update

参数	类型	必填	描述
content	string	是	新摘要，或要添加到 section 的文本（markdown）
threadId	string	否	目标线程（默认为当前活动线程）
section	string	否	decisions、constraints、state、open-questions 或 next-steps：仅更新该章节
replaceSection	boolean	否	替换章节，而不是向其中添加内容
paths	string[]	否	线程涉及的文件或目录；它们发生变化时会标记摘要

context_get

参数	类型	必填	描述
maxTokens	number	否	令牌预算；优先省略最远的祖先（thread_switch 也接受此参数）

设置

工具	描述
threadmind_init	为不读取 MCP 服务指令的 Agent 生成指令文件（AGENTS.md 等）

threadmind_init

参数	类型	必填	描述
clients	string[]	否	要生成的文件："agents"、"claude"、"cursor"、"generic"（默认：agents 和 generic）

写入与服务端发送给 MCP 客户端的相同指令：

目标	文件	读取方
agents	AGENTS.md	Codex、Cursor、GitHub Copilot 和其他 Agent
claude	CLAUDE.md	Claude Code — 不需要，它会接收服务端指令
cursor	.cursor/rules/threadmind.mdc	Cursor，作为始终应用的项目规则，取代 AGENTS.md（Cursor 会读取两者）
generic	.threadmind/instructions.md	粘贴到任意客户端的自定义指令中

早期版本会写入 CLAUDE.md 和 .cursorrules。生成 Cursor 规则时，threadmind_init 会将 ThreadMind 章节从 .cursorrules 移出，并报告任一文件中遗留的章节。

统计信息

工具	描述
stats_show	显示摘要大小；使用 Claude Code 插件时，还会显示测量得到的对话大小

使用插件时，每个会话都会记录其对话达到的大小（从 Claude Code 转录记录中读取），以及下一个会话开始时加载的上下文。stats_show 会报告这两项：

Measured sessions (Claude Code plugin):
  Conversation size when sessions ended: ~48,200 tokens on average, ~96,000 at most (12 sessions)
  ThreadMind context loaded at session start: ~1,150 tokens on average (14 sessions)

---

可用资源

资源	URI	描述
当前上下文	threadmind://context	当前活动线程的组装后上下文
线程树	threadmind://tree	线程树的 ASCII 可视化图
线程摘要	threadmind://thread/{threadId}	单个线程的摘要，不含其祖先

当前活动项目中的每个线程都会列为资源：在 Claude Code 中，输入 @ 提及某个线程，即可将兄弟线程的摘要带入对话。

---

可用提示词

提示词	描述
tm-help	显示所有可用的 ThreadMind 命令
tm-context	将当前线程的上下文载入对话
tm-tree	显示线程树
tm-stats	显示统计信息
tm-create	创建新线程（通过 thread_create）
tm-switch	切换到某个线程（通过 thread_switch）
tm-rebase	将线程移动到其他父线程下（通过 thread_rebase）
tm-summary	保存给定的摘要，或让 AI 撰写摘要（通过 summary_update）
tm-init	生成指令文件（通过 threadmind_init）
start-thread	与 tm-context 相同，为兼容性保留
summarize-thread	与不带内容的 tm-summary 相同，为兼容性保留

tm-context、tm-tree 和 tm-stats 会直接嵌入结果，不调用工具。其他提示词会让 AI 调用相应的工具，因此客户端的确认设置仍适用于这些变更。线程 ID 参数支持自动补全。

在 Claude Code 中，这些会显示为斜杠命令：/mcp__thread-mind__tm-help、/mcp__thread-mind__tm-create 等。

快捷命令

服务说明会教 AI 识别可直接在聊天中输入的简短文本命令：

命令	操作
tm:help	显示所有可用命令
tm:context	加载汇总后的上下文
tm:tree	显示线程树
tm:create <title>	创建新线程
tm:switch <id>	切换到某个线程
tm:summary	撰写并保存摘要
tm:summary <content>	保存指定的摘要内容
tm:merge	将线程合并到其父线程中
tm:done [reason]	将线程标记为已完成
tm:abandon <reason>	将线程标记为已放弃
tm:stats	显示统计信息
tm:delete <id>	删除线程
tm:rebase <id> <newParentId>	将线程移动到其他父线程下
tm:init	生成指令文件
tm:project <title>	创建新项目
tm:projects	列出所有项目

---

使用示例

1. 开始新项目

You: Create a new ThreadMind project called "E-Commerce App" with system context
     "Building a Next.js e-commerce platform with Stripe payments"

AI: [calls project_create] → Project "e-commerce-app" created. Main thread active.

Claude Code 无需进一步设置。若要让其他 Agent（Codex、Cursor、Copilot……）也使用该项目，请请求运行 threadmind_init，它会生成 AGENTS.md 文件。

2. 工作并撰写摘要

You: [discuss the architecture with AI...]
You: tm:summary

AI: [writes the summary in sections, then calls summary_update]
     ## Decisions
     - Next.js 15 App Router, PostgreSQL with Prisma, Stripe Checkout
     ## Next steps
     - Authentication

You: We'll use Stripe webhooks for order confirmation, record it.

AI: [calls summary_update with section "decisions"] → Section "decisions" updated.

3. 在其 git 分支上创建子主题分支

$ git switch -c feature/payments

You: tm:create Payment Integration

AI: [calls thread_create] → Thread "payment-integration" created under "main".
     Linked to git branch "feature/payments".

     main
     └── payment-integration [branch: feature/payments] ← active

4. 对话变长时重新开始

You: tm:summary
You: /clear

(the plugin loads the context of payment-integration: main's decisions
 and constraints, then the whole payment-integration summary)

如果没有插件，请在新会话中请求 tm:context。

5. 完成线程

You: tm:merge

AI: [writes main's new summary with the payment decisions, calls thread_merge]
     → Thread "payment-integration" merged into "main", which is now the active thread.

     main ← active
     └── payment-integration [done] [branch: feature/payments]

---

团队模式

团队模式可通过 git 共享线程树，支持协作。

工作原理

1. 以团队模式创建项目：

   project_create with title "Shared Project" and mode "team"
   

2. 每位团队成员首次写入时都会获得一个作者 ID，该 ID 根据 git config user.name 和 git config user.email 的短哈希生成（在不同克隆中保持稳定；可通过 THREADMIND_AUTHOR 环境变量覆盖）

3. 线程文件（.threadmind/threads/）会由 git 跟踪。每个文件都会记录其父线程，因此即使两个人在同一个父线程下创建线程，也不会发生冲突

4. 本地配置（.threadmind/config.json）会被 git 忽略——每位成员都有自己的会话状态和度量数据

5. 检出你的功能分支的队友会从与该分支关联的线程开始

规则

操作	自己的线程	队友的线程
读取摘要	是	是
更新摘要、更改状态	是	否
合并到父线程	若你也拥有该父线程	否
删除	是，除非某个后代线程属于队友	否
创建子线程	是	是
切换到	是	是

所有权可防止意外编辑；它不是访问控制。

从 0.4 升级： 线程树以前位于 .threadmind/trees/。ThreadMind 现在会在首次使用时将其移入线程文件，并删除 trees/<project>.json——请提交此变更，并让整个团队一起升级。.threadmind/stats/ 已不再使用，可以删除。

工作流

# Pull teammates' threads
git pull

# View the full tree (includes everyone's threads)
# → Use thread_list

# Branch from a teammate's thread
# → Use thread_create with parentId set to their thread

# Push your new threads
git add .threadmind/
git commit -m "Add payment-integration thread"
git push

---

开发与发布

开发环境设置、测试、版本发布以及发布到 MCP Registry 的说明，请参阅 SETUP.md。

---

架构

src/
  index.ts              # Entry point — stdio server, `hook <event>` or `status-line` for Claude Code
  server.ts             # McpServer factory (tools + resources + prompts + instructions)
  services.ts           # Services over one .threadmind directory, shared by server and hooks
  types/
    index.ts            # All TypeScript interfaces
  core/
    frontmatter.ts      # YAML frontmatter parser/serializer (zero deps)
    ids.ts              # ID validation, slugification, title normalization
    lock.ts             # Cross-process lock file
    clock.ts            # Strictly increasing timestamps
    storage.ts          # File I/O with atomic writes; tree derived from thread files
    workspace.ts        # Workspace root resolution (env, client roots, cwd)
    session.ts          # Active thread per session, per git branch
    git.ts              # Current branch, commits since a summary
    summary.ts          # Summary sections: inheritance, section updates
    project.ts          # Project lifecycle management
    thread.ts           # Thread CRUD, status, merge, tree rendering
    context.ts          # Context assembly, outdated summary notes, token budget
    instructions.ts     # Server instructions and instruction files
    stats.ts            # Session measurements and statistics report
  hooks/
    index.ts            # SessionStart / SessionEnd command hooks of the Claude Code plugin
    guard.ts            # Session hooks: reminders, compaction, branch changes, edited files
    session-context.ts  # Context injected by hooks, sized to Claude Code's limit
    transcript.ts       # Conversation sizes read from Claude Code transcripts
    settings.ts         # Hook options, from the server's environment
    session-cache.ts    # State shared between the hooks and the status line
    status-line.ts      # Claude Code status line
  tools/
    index.ts            # 14 MCP tools with Zod schemas and annotations
    hook.ts             # threadmind_hook, called by the plugin's hooks
  resources/
    index.ts            # 2 MCP resources + the thread resource template
  prompts/
    index.ts            # 11 MCP prompts
plugin/                 # Claude Code plugin (manifest, .mcp.json, hooks, commands)
.claude-plugin/         # Marketplace listing the plugin
server.json             # MCP Registry metadata

设计决策

• 基于文件的存储优于 SQLite — 适合 Git 管理、可供人阅读、无需原生依赖
• 以线程文件作为唯一可信来源 — 每个文件都记录其父线程；无需担心树索引发生偏移或在 Git 中产生冲突
• YAML frontmatter — 线程元数据和内容保存在同一个 .md 文件中，人和工具都能读取
• 不使用外部 YAML 解析器 — 针对简单的扁平 frontmatter 格式，使用精简的手写解析器
• 原子写入 — 写入临时文件并刷新，然后将其重命名为目标文件，因此崩溃不会留下不完整的文件
• 串行化更新 — 读-改-写操作逐一执行，跨会话和钩子也不例外，通过锁文件实现
• Slug 化 ID — 线程 ID 根据标题生成（"Auth System" → "auth-system"），通过自动添加后缀避免冲突，并限制为 a-z、0-9 和 -（也因此杜绝路径遍历）
• 每个会话只有一个活动线程 — 会话之间不会互相移动；新会话从已检出的 Git 分支开始
• 选择性继承 — 祖先线程会传递其决策和约束，而非其状态或后续步骤
• MCP Prompts — 斜杠命令；只读提示词会直接嵌入结果，而不是请求调用工具
• 服务端指令 — 服务会告知客户端如何使用，因此无需指令文件；threadmind_init 会将相同文本写入 AGENTS.md 和其他文件，供不会读取这些文件的 Agent 使用
• 工作区解析 — 依次使用 THREADMIND_ROOT、客户端的根目录，然后是工作目录
• 衡量而非估算的节省量 — 对话大小取自 Claude Code 转录记录；上下文大小为估算值（每个 token 约 3.5 个字符）

---

要求

• Node.js >= 18.0.0
• Git（可选：用于团队模式作者检测、线程与分支关联以及过期摘要警告）

许可证

MIT