mindbase

# MindBase

> **An AI research assistant that builds and maintains a wiki from your sources.** Not RAG-in-a-vector-DB. A real markdown wiki on your disk, that an LLM gardens for you between conversations.

MindBase implements Andrej Karpathy's [LLM-Wiki pattern](https://x.com/karpathy/status/1911080091498963196) as a product. You feed it sources (papers, articles, thoughts). The LLM reads, cross-references, flags contradictions, and writes structured wiki pages. Later, when you ask a question, the wiki already has the synthesized answer — no vector search re-derivation at query time.

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/hero-dark.svg">
    <img alt="MindBase: you feed sources, the LLM gardens them into a wiki that compounds — plain markdown on your disk" src="docs/assets/hero-light.svg" width="920">
  </picture>
</p>

**Status:** Early access. Beta for feedback (2026-Q3). Data model + core loop stable; some UI features still in v1 → v2 migration.

---

## Table of contents

- [Why MindBase](#why-mindbase)
- [How it works (30 seconds)](#how-it-works-30-seconds)
- [What makes it different](#what-makes-it-different)
- [Prerequisites](#prerequisites)
- [Install — choose your AI editor](#install--choose-your-ai-editor)
  - [Claude Code (flagship experience)](#claude-code-flagship-experience)
  - [Cursor](#cursor)
  - [Windsurf](#windsurf)
  - [Cline (VSCode)](#cline-vscode)
  - [Continue.dev](#continuedev)
  - [Any other MCP-compatible client](#any-other-mcp-compatible-client)
- [First project (2 minutes)](#first-project-2-minutes)
- [Core workflows](#core-workflows)
- [Working with multiple projects](#working-with-multiple-projects)
- [Web UI (optional companion)](#web-ui-optional-companion)
- [Feature matrix by editor](#feature-matrix-by-editor)
- [Where your data lives](#where-your-data-lives)
- [Architecture at a glance](#architecture-at-a-glance)
- [Troubleshooting](#troubleshooting)
- [Roadmap](#roadmap)
- [Beta feedback](#beta-feedback)
- [License](#license)

---

## Why MindBase

You read a lot. Papers, articles, tweets, docs. You want to remember them, connect them, form opinions from them. Today you have two bad options:

- **Notion / Obsidian / Roam:** Passive containers. You do all the organizing. AI features are bolted-on generation, not maintenance.
- **NotebookLM / Perplexity Pages / ChatGPT search:** RAG-based. Nothing accumulates. Every question re-derives the answer from raw sources.

**MindBase is the third option:** the LLM actively maintains a persistent, structured wiki as you feed it sources. Knowledge compounds. Your `context.md` gets sharper every time you contribute. The AI *remembers you across sessions* because your beliefs are written down in markdown files — not stored in a chat history that gets summarized away.

Think of it as **a personal Wikipedia that an AI intern writes for you**, kept up to date, cross-referenced, and honest about what it doesn't know.

---

## How it works (30 seconds)

Three physical layers on disk (Karpathy's model):

```
Layer 1 — sources/          You add these. Append-only. LLM reads, never rewrites.
   ├─ contributors/          Your thoughts, dated per-user (like a lab notebook)
   ├─ research/              Wiki pages the LLM writes (concepts, entities, syntheses)
   └─ raw/                   PDFs, URL captures, pastes — original binaries

Layer 2 — README.md          The rules of your wiki. You edit. LLM reads at every op.
          context.md         The synthesized current truth. LLM writes. You read.
          index.yaml         Auto-generated file catalog. LLM maintains.

Layer 3 — logs/              Chronological log of every operation. LLM appends.
          artifacts/         Generated outputs: daily briefs, exports, lint reports.
```

Three operations the AI can run:

| Operation | What happens |
|---|---|
| **Contribute** | You feed a thought / PDF / URL. LLM reads, discusses key takeaways with you, updates 5-15 relevant wiki pages, appends log. |
| **Ask** | You ask a question. LLM reads your `context.md` first (already-synthesized truth), then drills into cited source pages. Cited answers with `[[wikilink]]` provenance. |
| **Lint** | LLM audits the whole wiki for contradictions, stale claims, orphan pages, missing cross-references, gaps that need investigation. |

They form a loop — good answers and lint findings flow back in as new contributions, so the wiki compounds:

```mermaid
flowchart LR
    C["contribute<br/><small>thought · PDF · URL</small>"] --> S[("sources/<br/><small>append-only</small>")]
    S --> B["build<br/><small>LLM synthesizes</small>"]
    B --> W[("context.md<br/>research/*.md")]
    W --> Q["ask<br/><small>cited answers</small>"]
    W --> L["lint<br/><small>contradictions · orphans · gaps</small>"]
    Q -. "good answers filed back" .-> C
    L -. "follow-up notes" .-> C
```

That's the entire product. Everything else is UX.

---

## What makes it different

**vs. Notion:** You own the data (markdown files, not a proprietary DB). The AI is a **maintainer**, not a bolt-on generator. `context.md` evolves; Notion pages don't.

**vs. Obsidian:** You get the same local-first markdown vault, but with an AI that **actively writes** the wiki — you don't have to hand-craft every note. Comes with `[[wikilinks]]` cross-referencing done for you.

**vs. NotebookLM / Perplexity:** Knowledge **compounds**. Ask "what's my view on RAG?" and the answer already exists in `context.md`. NotebookLM re-derives it from raw sources every time — nothing accumulates.

**vs. any RAG tool:** RAG is stateless retrieval. MindBase is **stateful synthesis**. The wiki gets richer with every ingest. Answers get faster and more consistent over time.

---

## Prerequisites

- **Node.js 20+** (that's it for Cursor / Windsurf / Cline / Continue — the MCP server installs itself via `npx`)
- One of: Claude Code, Cursor, Windsurf, Cline, Continue.dev, or another MCP-compatible AI editor
- **pnpm 10+** only if you install the Claude Code plugin or the web UI from source
- (Optional) A modern browser, if you want the web UI

MindBase runs **entirely on your machine**. No cloud upload, no signup, no telemetry.

---

## Install — choose your AI editor

MindBase ships as an **MCP (Model Context Protocol) server** — published on npm as [`mindbase-mcp`](https://www.npmjs.com/package/mindbase-mcp). Every MCP-compatible AI editor can use its tools with a one-line config; no clone, no build. Claude Code gets an extra layer of polish (slash commands, sub-agents) via the plugin.

---

### Claude Code (flagship experience)

Get the full Karpathy 8-step ingest with sub-agents, slash commands, auto-context, and per-agent tool boundaries.

**Install the plugin** — two commands inside Claude Code, no clone, no build:

```
/plugin marketplace add frankchu91/mindbase
/plugin install mb@mindbase
```

Restart Claude Code when prompted. (The plugin launches its MCP server via `npx -y mindbase-mcp`, so npm delivers the server automatically.)

<details>
<summary>Developing the plugin from a clone?</summary>

```bash
git clone https://github.com/frankchu91/mindbase.git
cd mindbase && pnpm install
claude --plugin-dir apps/plugin
```

</details>

**Verify:** Open Claude Code, type `/`. You should see `/mb:contribute`, `/mb:ask`, `/mb:build`, `/mb:status`, and 8 others. Run `/mcp` — you should see `mb` connected with 49 tools.

**What you get:**
- 12 slash commands (`/mb:*`)
- 5 sub-agents with security boundaries (`contributor`, `builder`, `curator`, `researcher`, `migrator`) — each has a strict tool allowlist
- SessionStart hook — every new Claude Code session auto-injects your project's README + context + recent log entries
- The full Karpathy 8-step ingest: read → discuss takeaways → propose plan → wait for approval → execute

Skip to [First project](#first-project-2-minutes).

---

### Cursor

Add to `~/.cursor/mcp.json` (create the file if missing):

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

Restart Cursor. Open Cursor Chat → the tool picker should list `mindbase_contribute`, `mindbase_ask_wiki`, and 47 others.

**Optional but recommended:** teach Cursor's LLM about MindBase conventions by adding to `~/.cursor/rules.md` (or per-project `.cursorrules`):

```
# MindBase conventions

When the user mentions "mindbase", "mb", "my wiki", "记一下", or "记忆",
the following MCP tools are available: mindbase_contribute, mindbase_ask_wiki,
mindbase_status, mindbase_load_project, and more.

Rules:
1. When user says "add to mindbase X" or "记一下 X", ALWAYS call mindbase_contribute
   with text=X. Never just acknowledge without calling the tool.
2. When user says "ask mindbase X" or "问问我的 wiki", call mindbase_ask_wiki
   with query=X.
3. When ingesting a PDF/URL, follow the 8-step Karpathy loop:
   read → discuss 3 key takeaways with user → propose plan → wait for approval
   → then call mindbase_contribute with the summary.
4. Default project comes from config.json currentProjectId. If the user says
   "for project X" or "在 X 项目里", pass projectId=X to the tool call.
```

Skip to [First project](#first-project-2-minutes).

---

### Windsurf

Windsurf uses the same MCP config format. Open Cascade settings → MCP → add:

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

Restart Windsurf. Same rules-file approach as Cursor works — put a `MindBase conventions` block in your Cascade rules.

Skip to [First project](#first-project-2-minutes).

---

### Cline (VSCode)

Open VSCode → Cline extension settings → **MCP Servers**. Add:

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

Cline auto-detects. Every tool call gets a confirmation dialog by default (transparency win). Skip to [First project](#first-project-2-minute