ThreadMind MCP

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

Why ThreadMind?

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:

• Summaries in sections — Decisions, Constraints, State, Open questions, Next steps
• Inheritance through the tree — a thread's context is its summary plus its ancestors' decisions and constraints; sibling branches stay out
• Branching exploration — try approaches in separate threads, merge the winner's conclusions into the parent, keep the reason an approach was abandoned
• Git-aware — a thread created on a feature branch becomes active whenever that branch is checked out, and summaries warn when the code they describe has changed
• Team collaboration — thread files are committed with the code and reviewed in pull requests

Where the savings come from

ThreadMind can't shrink a conversation in progress: your client decides what it sends. The savings come when you start over:

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

With the Claude Code plugin, the context reloads automatically after /clear and after compaction, and stats_show measures both sizes on your own sessions.

Quick Start

Claude Code plugin (recommended)

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

The plugin installs the server and adds:

• a SessionStart hook that loads the active thread's context at startup, after /clear and after compaction (nothing happens in repositories without a ThreadMind project)
• a SessionEnd hook that records how large the conversation grew, read from its transcript, for stats_show
• commands: /thread-mind:context, /thread-mind:tree, /thread-mind:create, /thread-mind:switch, /thread-mind:summary, /thread-mind:merge, /thread-mind:stats

If you configured ThreadMind manually before, remove that configuration so Claude Code doesn't run two servers.

Installation

No installation required — run directly with npx:

npx thread-mind-mcp

Or install globally:

npm install -g thread-mind-mcp

Configure with Claude Code

Add to your Claude Code MCP settings (~/.claude/settings.json or project .claude/settings.json):

macOS / Linux:

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

Windows:

{
  "mcpServers": {
    "thread-mind": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "thread-mind-mcp"],
      "env": {}
    }
  }
}

On Windows, npx must be wrapped with cmd /c because npx is a .cmd wrapper 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:

{
  "mcpServers": {
    "thread-mind": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "volta", "run", "npx", "-y", "thread-mind-mcp"],
      "env": {}
    }
  }
}

Or via CLI: claude mcp add thread-mind-mcp --scope project -- cmd /c volta run npx -y thread-mind-mcp

Configure with other MCP clients

ThreadMind uses the stdio transport, compatible with any MCP client. Use the same configuration above for your platform.

Workspace location

ThreadMind stores its data in .threadmind/ at the root of your workspace, found in this order:

1. The THREADMIND_ROOT environment variable, if set
2. The workspace roots advertised by the MCP client (a root that already contains .threadmind/ wins)
3. The directory the server was started from

A client that starts servers outside your project without advertising roots (for example a desktop chat app with no project folder) needs THREADMIND_ROOT:

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

Teach your AI client to use ThreadMind

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.

How It Works

Core Concepts

Storage

ThreadMind stores everything in a .threadmind/ directory at your project root:

.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

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.

---
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 and mergedInto only appear when set.

Context Assembly

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:

## 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_

• Only the direct ancestor chain is included — sibling branches are excluded
• Summaries written before code changes are flagged, using the commit and paths recorded with them
• maxTokens leaves out the farthest ancestors first when the context would be too large

Available Tools

Each tool declares a title and MCP annotations (read-only, destructive, idempotent), which clients can use to decide when to ask for confirmation.

Project Management

project_create

Thread Management