thread-mind-mcp

# ThreadMind MCP

[![npm version](https://img.shields.io/npm/v/thread-mind-mcp.svg)](https://www.npmjs.com/package/thread-mind-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Branches for your AI's memory: a git-friendly tree of thread summaries.**

ThreadMind is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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](https://mahmoud-nb.github.io/thread-mind-mcp/)** | **[npm](https://www.npmjs.com/package/thread-mind-mcp)** | **[GitHub](https://github.com/mahmoud-nb/thread-mind-mcp)**

---

## 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](#claude-code-plugin-recommended), 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`:

```bash
npx thread-mind-mcp
```

Or install globally:

```bash
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:**
```json
{
  "mcpServers": {
    "thread-mind": {
      "command": "npx",
      "args": ["-y", "thread-mind-mcp"]
    }
  }
}
```

**Windows:**
```json
{
  "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:

```json
{
  "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`:

```json
{
  "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

| 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. |

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

```markdown
---
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

| 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"`) |

### Thread Management

| 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 do