The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Thread Mind listing page.
Branches for your AI's memory: a git-friendly tree of thread summaries.
ThreadMind is a Model Context Protocol (MCP) server that gives AI coding sessions a memory: a tree of threads, each holding a short summary of what was decided about one topic, stored as Markdown in your repository. Start a fresh session and the active thread's context — its decisions and those of its ancestors — replaces a history that had grown to tens of thousands of tokens.
Documentation | npm | GitHub
With AI coding assistants, conversations grow long: every request carries the whole history, until the client compacts it or you start over — and starting over loses what was decided. ThreadMind keeps what matters:
ThreadMind can't shrink a conversation in progress: your client decides what it sends. The savings come when you start over:
With the Claude Code plugin, the context reloads automatically after /clear and after compaction, and stats_show measures both sizes on your own sessions.
The plugin installs the server and adds:
/clear and after compaction (nothing happens in repositories without a ThreadMind project)stats_show/thread-mind:context, /thread-mind:tree, /thread-mind:create, /thread-mind:switch, /thread-mind:summary, /thread-mind:merge, /thread-mind:statsIf you configured ThreadMind manually before, remove that configuration so Claude Code doesn't run two servers.
No installation required — run directly with npx:
Or install globally:
Add to your Claude Code MCP settings (~/.claude/settings.json or project .claude/settings.json):
macOS / Linux:
Windows:
On Windows,
npxmust be wrapped withcmd /cbecausenpxis a.cmdwrapper and cannot be spawned directly by the MCP stdio transport.
Windows + Volta:
If you use Volta as your Node.js version manager, use volta run to ensure the correct Node.js version is resolved when Claude Code spawns the MCP subprocess:
Or via CLI: claude mcp add thread-mind-mcp --scope project -- cmd /c volta run npx -y thread-mind-mcp
ThreadMind uses the stdio transport, compatible with any MCP client. Use the same configuration above for your platform.
ThreadMind stores its data in .threadmind/ at the root of your workspace, found in this order:
THREADMIND_ROOT environment variable, if set.threadmind/ wins)A client that starts servers outside your project without advertising roots (for example a desktop chat app with no project folder) needs THREADMIND_ROOT:
The server sends its usage instructions when the client connects (MCP server instructions): Claude Code needs no setup file. For agents that don't read them, run threadmind_init to generate an AGENTS.md file, read by Codex, Cursor, GitHub Copilot and others.
| Concept | Description |
|---|---|
| Project | A workspace containing a thread tree. Has a title, system context, and mode (solo/team). |
| Thread | A node in the tree representing a discussion topic. Stores a markdown summary, and may be linked to a git branch, done or abandoned. |
| Summary | What was decided in a thread, in sections: Decisions, Constraints, State, Open questions, Next steps. |
| Context | The active thread's summary plus its ancestors' decisions and constraints — what the AI loads. |
| Session | Each client session has its own active thread; new sessions start from the checked-out git branch. |
ThreadMind stores everything in a .threadmind/ directory at your project root:
Thread files use YAML frontmatter. Each one records its parent: the tree is rebuilt from the files, with no index to keep in sync or to conflict in git.
status, branch, commit, paths and mergedInto only appear when set.
When you request context, ThreadMind walks up from the active thread to the root. It keeps the whole summary of the active thread, and only the Decisions and Constraints of its ancestors:
paths recorded with themmaxTokens leaves out the farthest ancestors first when the context would be too largeEach tool declares a title and MCP annotations (read-only, destructive, idempotent), which clients can use to decide when to ask for confirmation.
| Tool | Description |
|---|---|
project_create | Create a new project with a root "main" thread |
project_list | List all projects (shows the session's project) |
project_switch | Switch the session to a different project (a single project is selected automatically) |
project_create| Parameter | Type | Required | Description |
|---|---|---|---|
title | string | Yes | Project title (used to generate ID) |
systemContext | string | No | System prompt or global instructions |
mode | "solo" | "team" | No | Project mode (default: "solo") |
| Tool | Description |
|---|---|
thread_create | Create a child thread; on a feature branch, link it to the branch |
thread_switch | Switch this session to a different thread and return its assembled context |
thread_list | Display the thread tree, with statuses and linked branches |
thread_status | Mark a thread done or abandoned (the reason is kept in its decisions), or reopen it |
thread_merge | Fold a finished thread into its parent: replaces the parent's summary, marks the thread done |
thread_delete | Delete a thread and all its descendants |
thread_rebase | Move a thread to a different parent (like git rebase) |
thread_create| Parameter | Type | Required | Description |
|---|---|---|---|
title | string | Yes | Thread title (used to generate ID) |
parentId | string | No | Parent thread ID (defaults to active thread) |
thread_status| Parameter | Type | Required | Description |
|---|---|---|---|
status | "active" | "done" | "abandoned" | Yes | New status |
threadId | string | No | Target thread (defaults to active thread) |
reason | string | No | Why, added to the thread's Decisions section |
thread_merge| Parameter | Type | Required | Description |
|---|---|---|---|
parentSummary | string | Yes | The parent's new summary, including the thread's conclusions |
threadId | string | No | Thread to merge (defaults to active thread) |
thread_delete| Parameter | Type | Required | Description |
|---|---|---|---|
threadId | string | Yes | Thread ID to delete (cascades to descendants) |
thread_rebase| Parameter | Type | Required | Description |
|---|---|---|---|
threadId | string | Yes | Thread ID to move |
newParentId | string | Yes | New parent thread ID |
| Tool | Description |
|---|---|
summary_update | Update the summary of a thread, or one of its sections |
context_get | Get the assembled context with token estimation |
summary_update| Parameter | Type | Required | Description |
|---|---|---|---|
content | string | Yes | New summary, or the text to add to section (markdown) |
threadId | string | No | Target thread (defaults to active thread) |
section | string | No | decisions, constraints, state, open-questions or next-steps: only update that section |
replaceSection | boolean | No | Replace the section instead of adding to it |
paths | string[] | No | Files or directories the thread is about, to flag the summary when they change |
context_get| Parameter | Type | Required | Description |
|---|---|---|---|
maxTokens | number | No | Token budget; the farthest ancestors are left out first (thread_switch accepts it too) |
| Tool | Description |
|---|---|
threadmind_init | Generate instruction files for agents that don't read MCP server instructions (AGENTS.md, etc.) |
threadmind_init| Parameter | Type | Required | Description |
|---|---|---|---|
clients | string[] | No | Files to generate: "agents", "claude", "cursor", "generic" (default: agents and generic) |
Writes the same instructions the server sends to MCP clients:
| Target | File | Read by |
|---|---|---|
agents | AGENTS.md | Codex, Cursor, GitHub Copilot and other agents |
claude | CLAUDE.md | Claude Code — not needed, it receives the server instructions |
cursor | .cursor/rules/threadmind.mdc | Cursor, as an always-applied project rule |
generic | .threadmind/instructions.md | Paste into any client's custom instructions |
Earlier versions wrote CLAUDE.md and .cursorrules. threadmind_init moves the ThreadMind section out of .cursorrules when it generates the Cursor rule, and reports any section left in either file.
| Tool | Description |
|---|---|
stats_show | Show summary sizes and, with the Claude Code plugin, measured conversation sizes |
With the plugin, each session records the size its conversation reached (read from the Claude Code transcript) and the context loaded when the next one started. stats_show reports both:
| Resource | URI | Description |
|---|---|---|
| Current Context | threadmind://context | Assembled context for the active thread |
| Thread Tree | threadmind://tree | ASCII visualization of the thread tree |
| Thread Summary | threadmind://thread/{threadId} | Summary of one thread, without its ancestors |
Every thread of the active project is listed as a resource: in Claude Code, type @ to mention one and bring a sibling thread's summary into the conversation.
| Prompt | Description |
|---|---|
tm-help | Show all available ThreadMind commands |
tm-context | Load the active thread's context into the conversation |
tm-tree | Show the thread tree |
tm-stats | Show statistics |
tm-create | Create a new thread (via thread_create) |
tm-switch | Switch to a thread (via thread_switch) |
tm-rebase | Move a thread to a different parent (via thread_rebase) |
tm-summary | Save the given summary, or have the AI write one (via summary_update) |
tm-init | Generate instruction files (via threadmind_init) |
start-thread | Same as tm-context, kept for compatibility |
summarize-thread | Same as tm-summary without content, kept for compatibility |
tm-context, tm-tree and tm-stats embed their result directly, without a tool call. The other prompts ask the AI to call the matching tool, so your client's confirmation settings still apply to changes. Thread ID arguments support autocompletion.
In Claude Code, these appear as slash commands: /mcp__thread-mind__tm-help, /mcp__thread-mind__tm-create, etc.
The server instructions teach the AI short text commands you can type directly in chat:
| Command | Action |
|---|---|
tm:help | Show all available commands |
tm:context | Load assembled context |
tm:tree | Show thread tree |
tm:create <title> | Create a new thread |
tm:switch <id> | Switch to a thread |
tm:summary | Write and save the summary |
tm:summary <content> | Save specific summary content |
tm:merge | Fold the thread into its parent |
tm:done [reason] | Mark the thread done |
tm:abandon <reason> | Mark the thread abandoned |
tm:stats | Show statistics |
tm:delete <id> | Delete a thread |
tm:rebase <id> <newParentId> | Move a thread to a different parent |
tm:init | Generate instruction files |
tm:project <title> | Create a new project |
tm:projects | List all projects |
Claude Code needs no further setup. To let other agents (Codex, Cursor, Copilot…) use the project too, ask for threadmind_init, which generates an AGENTS.md file.
Without the plugin, ask for tm:context in the new session.
Team mode enables collaborative thread trees shared via git.
Create a project in team mode:
Each team member gets an author ID on their first write, derived from git config user.name and a short hash of git config user.email (stable across clones; override it with the THREADMIND_AUTHOR environment variable)
Thread files (.threadmind/threads/) are tracked by git. Each one records its parent, so two people creating threads never conflict, even under the same parent
The local config (.threadmind/config.json) is gitignored — each member has their own session state and measurements
A teammate who checks out your feature branch starts on the thread linked to it
| Action | Own threads | Teammates' threads |
|---|---|---|
| Read summary | Yes | Yes |
| Update summary, change status | Yes | No |
| Merge into parent | If you own the parent too | No |
| Delete | Yes, unless a descendant is a teammate's | No |
| Create child thread | Yes | Yes |
| Switch to | Yes | Yes |
Ownership prevents accidental edits; it is not access control.
Upgrading from 0.4: the tree used to live in
.threadmind/trees/. ThreadMind now moves it into the thread files on first use and deletestrees/<project>.json— commit that change, and upgrade the whole team together..threadmind/stats/is no longer used and can be deleted.
Development setup, tests, releases and publishing to the MCP Registry are described in SETUP.md.
.md file, readable by both humans and tools"Auth System" → "auth-system"), collision-safe with auto-suffix, restricted to a-z, 0-9 and - (which also rules out path traversal)threadmind_init writes the same text to AGENTS.md and other files for agents that don't read themTHREADMIND_ROOT, then the client's roots, then the working directory