Thread Mind

Name: Thread Mind
Author: mahmoud-nb

by mahmoud-nbversion 0.5.0i★ –iRuns on your computer

Registry nameio.github.mahmoud-nb/thread-mind

Install

Overview

Description from the maker (original English)

Git-friendly memory for AI coding: a tree of thread summaries with inherited context

PopNx MCP’s three pillars

These three are never merged into one score: opinions, measurements and popularity are different things.

User voiceiNo reviews yetReviews open together with accounts in a later step
Our basic checksi1 of 1 passedChecked from public information; code not scanned yet
UsageiNot measured yet★ –

What you can do with it

We have not written a plain-language summary for this one yet. Below are the facts we read from the registry.

Connection: Runs on your computer
Transport: stdio
Category: Search & AI memory

Install

Pick the AI app you use, then copy the settings.

Before you install

Basic checks: 1 of 1 passed
Runs on your computer with your user’s permissions (files, network, apps).
You fill in yourself: THREADMIND_ROOT, THREADMIND_AUTHOR

You need

npmNode.js installed (for the npx command)

Which app do you use?

ClaudeClaude CodeCursorVS CodeChatGPT

Pick your app above. We remember it, so next time the button says “Install in …”.

Open Claude Desktop → Settings → Developer → Edit Config, and paste this into claude_desktop_config.json

{
  "mcpServers": {
    "thread-mind": {
      "command": "npx",
      "args": [
        "-y",
        "thread-mind-mcp"
      ],
      "env": {
        "THREADMIND_ROOT": "your-value",
        "THREADMIND_AUTHOR": "your-value"
      }
    }
  }
}

Run this in your terminal

claude mcp add thread-mind --env THREADMIND_ROOT=your-value --env THREADMIND_AUTHOR=your-value -- npx -y thread-mind-mcp

Fill in the empty values before running it.

Open in Cursor

Or copy the settings yourself

Paste into .cursor/mcp.json in your project, or ~/.cursor/mcp.json

{
  "mcpServers": {
    "thread-mind": {
      "command": "npx",
      "args": [
        "-y",
        "thread-mind-mcp"
      ],
      "env": {
        "THREADMIND_ROOT": "your-value",
        "THREADMIND_AUTHOR": "your-value"
      }
    }
  }
}

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

Open in VS Code

Or copy the settings yourself

Paste into .vscode/mcp.json in your project

{
  "servers": {
    "thread-mind": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "thread-mind-mcp"
      ],
      "env": {
        "THREADMIND_ROOT": "your-value",
        "THREADMIND_AUTHOR": "your-value"
      }
    }
  }
}

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

This one runs on your computer, and ChatGPT can only connect to servers on the internet. Pick another app.

Your choice stays on this device in a cookie; no account needed.

Values you fill in

THREADMIND_ROOT env
Project directory holding .threadmind/, for clients that start servers outside your project
THREADMIND_AUTHOR env
Author ID used for team-mode ownership (defaults to one derived from your git identity)

These settings are generated from the maker’s registry entry. If the README says otherwise, follow the README.

What it can do

Runs on your computer; the tool list appears in your AI app after you install it.

Basic checksi

We check information anyone can see; we have not read the code. Checks that do not apply are left out of the count. · Checked Nov 7, 2026

✓ Pass
Maker matches the repo
The registry name was verified with the GitHub account mahmoud-nb, which owns the repo
… Not checked yet
Still maintained
We have not read this repo from GitHub yet
… Not checked yet
Has a licence
We have not read this repo from GitHub yet
– Not applicable
Endpoint responds
This one runs on your computer; there is no internet endpoint
– Not applicable
Sign-in with OAuth
Runs on your computer and uses local settings instead
… Not checked yet
No hidden instructions in tool descriptions
Runs on your computer; we can only read tool lists from internet endpoints

Compared with others in Search & AI memoryi

More stars than 0% of the other 7249 servers in this category
Published to the registry more recently than 49% of the other 7249 servers in this category
Basic checks equal to or better than 100% of the other 7249 servers in this category

Compared with every active server in this category in the registry. Stars count only when the publisher owns the repo.

Common questions

Is Thread Mind safe?

It passed 1 of 1 applicable basic checks. We have not read the code. Before adding a key or token, see what access the server asks for and use a key with only the permissions you need.

What keys or codes does it need?

The registry does not list a required key, though some servers ask you to sign in on first use.

Does it run on my computer or in the cloud?

It runs on your computer. Your AI app starts it when needed, and data does not pass through the maker’s servers (unless it calls an online service itself).

Is it still maintained?

The GitHub repo last changed –, and the latest version (0.5.0) reached the registry 40 days ago.

Which apps can use it?

Apps that support MCP, such as Claude Desktop, Claude Code, Cursor and VS Code. You also need Node.js on your computer.

What can I use instead?

In the same category: Context7, Codebase Memory, Exa

Alternatives

Servers in the same category from other makers, sorted by stars.

Reading a card:★ GitHub starsiThree pillars: reviews · checks · usageiUpdated = latest version published to the registryi

Context7

by upstash

Feeds AI the latest docs for libraries and frameworks before it answers, so code it writes does not use outdated, removed functions.

Computer or cloud★ 64,224MITUpdated today

Install

Codebase Memory

by DeusData

Codebase knowledge graph for AI agents — 162 languages, sub-ms queries, 99% fewer tokens.

Runs on your computer★ 48,148MITUpdated 20 days ago

Install

Exa

by exa-labs

Connect AI agents to Exa for web search, content fetching, and multi-step research.

Runs in the cloud★ 5,213MITUpdated last month

Install

README from the maker

Open the README

Copied from the maker’s repo as written. PopNx MCP has not reviewed or endorsed it. HTML, images and scripts are removed. Links lead off this site.

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](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, 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 hooks that:

load the active thread's context at startup, after /clear and after compaction (nothing happens in repositories without a ThreadMind project)
remind Claude to save the summary as the conversation grows, and once more when the context window is nearly full
recover the summary after a compaction that happened before it was saved, and tell you when /clear dropped unsaved work
follow git branch changes, giving Claude the new active thread's context
record the files Claude edits with the next summary, so it gets flagged when they change
answer `tm:tree` and `tm:stats` instantly, without using tokens
measure how large conversations grow, read from their transcripts, for stats_show

It also brings commands (/thread-mind:context, /thread-mind:tree, /thread-mind:create, /thread-mind:switch, /thread-mind:summary, /thread-mind:merge, /thread-mind:stats) and options in /config. A status line (thread-mind-mcp status-line) keeps the active thread and its unsaved work in view. See the plugin guide.

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 (without the plugin)

Run from your project root. To share the server with your team, add it at project scope: Claude Code writes .mcp.json at the project root, which you commit.

# 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

The resulting .mcp.json (you can also write it by hand):

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

On Windows, use "command": "cmd" and "args": ["/c", "npx", "-y", "thread-mind-mcp"]. Each teammate approves the server the first time Claude Code starts it in the repository.

For yourself only, drop --scope project (default local scope: you, in this project) or use --scope user (you, in every project). Both are stored in ~/.claude.json, which Claude Code manages.

Scope	Stored in	Applies to
`local` (default)	`~/.claude.json`, under the current project	You, in this project
`project`	`.mcp.json` at the project root	Everyone who clones the repository
`user`	`~/.claude.json`	You, in every project

Claude Code doesn't read MCP servers from ~/.claude/settings.json or .claude/settings.json. Check the configuration with claude mcp list, or /mcp inside a session.

Windows + Volta: if Claude Code can't resolve Volta's npx shim, delegate to volta run:

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

Configure with other MCP clients

ThreadMind uses the stdio transport, compatible with any MCP client. The command is always npx -y thread-mind-mcp; what changes is where each client declares it, and whether it reads the usage instructions the server sends:

Client	Server configuration	Usage instructions
Cursor	`.cursor/mcp.json` or `~/.cursor/mcp.json`	`AGENTS.md`
VS Code (GitHub Copilot)	`.vscode/mcp.json` (`servers` key) or `.mcp.json`	Sent by the server
GitHub Copilot CLI	`.mcp.json` or `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`)	Sent by the server
Gemini CLI	`.gemini/settings.json` or `~/.gemini/settings.json`	Sent by the server
Windsurf (Devin Desktop)	`mcp_config.json`	`AGENTS.md`
Claude Desktop (chat)	`claude_desktop_config.json`, with `THREADMIND_ROOT` set to the project	Claude Project instructions, if needed

Claude Code, VS Code and Copilot CLI share the .mcp.json file at the repository root. See Other AI Clients for each client's configuration.

Workspace location

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

The THREADMIND_ROOT environment variable, if set
The workspace roots advertised by the MCP client (a root that already contains .threadmind/ wins). Claude Code advertises the directory you started it in, plus those added with --add-dir: start it from the project root
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, VS Code (GitHub Copilot), Codex and Gemini CLI need no setup file. For agents that don't read them, such as Cursor, Copilot CLI or Windsurf, run threadmind_init to generate an AGENTS.md file.

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.

---

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

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

Only the beginning is shown; read the rest in the repo

Thread Mind

Overview

PopNx MCP’s three pillars

What you can do with it

Install

Before you install

Values you fill in

What it can do

Basic checksi

Maker matches the repo

Still maintained

Has a licence

Endpoint responds

Sign-in with OAuth

No hidden instructions in tool descriptions

Compared with others in Search & AI memoryi

Common questions

Alternatives

Context7

Codebase Memory

Exa

README from the maker

ThreadMind MCP

Why ThreadMind?

Where the savings come from

Quick Start

Claude Code plugin (recommended)

Installation

Configure with Claude Code (without the plugin)

Windows: npx is a .cmd script, wrap it in cmd /c

Configure with other MCP clients

Workspace location

Teach your AI client to use ThreadMind

How It Works

Core Concepts

Storage

Decisions

State

Context Assembly

Thread: My App

Decisions

Thread: Authentication System

Decisions

Thread: Auth API Endpoints (active)

Decisions

Next steps

Available Tools

Project Management

project_create

`project_create`