# ThoughtDAG

> ThoughtDAG is an open-source MCP server for developer tools. Read-only MCP server that finds past AI coding conversations by file or phrase. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted, macOS, Linux, Windows
- **Website:** https://chenxiachan.github.io/thoughtdag/docs/guides/why-layer
- **Repository:** https://github.com/chenxiachan/thoughtdag/tree/HEAD/cli
- **MCP Registry name:** io.github.chenxiachan/thoughtdag
- **Categories:** developer tools, knowledge and memory
- **Listing updated:** 2026-11-16

## About

ThoughtDAG builds a local index of agent sessions already on your machine, from Claude Code, Codex, DeepSeek Harness, Pi and ThoughtDAG canvases, keyed by the files each turn read, wrote or edited. Facts come straight from tool calls rather than free text or a model. Observed edits are marked separately from candidate explanations inferred from an answer, which the docs say are not verified reasons.

The MCP server offers four read-only tools and cannot edit a canvas or a source session. thoughtdag setup mcp registers it for Claude Code in the project's .mcp.json and for Codex in the user config; thoughtdag setup rules can add a marked block to CLAUDE.md and AGENTS.md asking agents to check history before editing a file, and removes it again on request.

It needs Node.js 20 or newer. Derived indexes live under ~/.thoughtdag and can be deleted with thoughtdag purge. Retrieved history is returned to the calling agent, which may pass it to its model provider, so private history deserves a check of the client's settings.

## Features

- **File history lookup:** Lists the turns that touched a file, URL or arXiv paper.
- **Exact phrase search:** Finds a phrase across questions, answers or attached materials.
- **Full turn recall:** Prints a single turn's question, answer and tool trail.
- **Observed versus inferred:** Separates recorded edits from candidate explanations.
- **Local index:** Derived data stays in ~/.thoughtdag with restrictive permissions.
- **Project rules helper:** Optionally adds and removes a history-check block in CLAUDE.md and AGENTS.md.

## Good for

- Ask why a file looks the way it does before editing it
- Find the conversation where a specific phrase was discussed
- Check whether a file has any past agent history
- Recover the full tool trail of an earlier turn

## Install

### Claude Code (Terminal)

```sh
claude mcp add thoughtdag -- npx -y thoughtdag
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "thoughtdag": {
      "command": "npx",
      "args": [
        "-y",
        "thoughtdag"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "thoughtdag": {
      "command": "npx",
      "args": [
        "-y",
        "thoughtdag"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "thoughtdag": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "thoughtdag"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "thoughtdag": {
      "command": "npx",
      "args": [
        "-y",
        "thoughtdag"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "thoughtdag": {
      "command": "npx",
      "args": [
        "-y",
        "thoughtdag"
      ]
    }
  }
}
```

## Tools

- `why_check`: One-line yes/no check whether a path has history
- `why_file`: Matching turns and observed file changes for a path
- `find`: Exact matches in questions, answers or materials
- `recall_turn`: Full question, answer and tool trail for one turn

## FAQ

### Can it modify my sessions?

No. Session files are read, never written, and the MCP tools are read-only.

### Which agents' history does it read?

Claude Code, Codex, DeepSeek Harness, Pi and ThoughtDAG canvas conversations.

### How do I start the server?

Run npx -y thoughtdag@0.2.2 mcp, or thoughtdag setup mcp inside a project.

### How do I remove its data?

thoughtdag purge deletes all derived data, or only rebuildable caches with --cache.

### Is ThoughtDAG free?

Yes. ThoughtDAG is open source, so you can use and self-host it for free.

### How do I add ThoughtDAG to Claude Code?

Run this command in your terminal: claude mcp add thoughtdag -- npx -y thoughtdag

### What are the best alternatives to ThoughtDAG?

The closest alternatives to ThoughtDAG are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Nautilus Compass Memory](https://ai-powered.com/mcp/nautilus-compass-memory): Nautilus Compass Memory is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/thoughtdag
