meshnote 0.1.0

Meshnote

A second brain, built for AI agents.

Meshnote is an Obsidian alternative where your LLM agent is the primary maintainer of the knowledge base. You curate sources and ask questions; your agent (Claude Code, Codex, Cursor, or any MCP-compatible client) does all the bookkeeping — ingest, cross-reference, summarize, lint. Think of it as a native implementation of Andrej Karpathy's LLM Wiki pattern instead of a DIY folder + CLAUDE.md setup.

Meshnote is designed around multiple brains. Each meshnote project is a distinct wiki with its own LLM operating instructions. You pick a template when you create it, and the LLM works differently for each:

Each template seeds a different schema.md — the operating manual the LLM reads first before touching the wiki. You and your agent co-evolve it as your workflow settles.

Want the full narrative? docs/how-it-works.md walks through what it feels like to use meshnote, what the LLM sees through MCP, and how the pieces fit together.

Status

v0.1 (local-first) and v0.2 (hosted mode foundations) are functional.

• CLI — meshnote init/search/serve/mcp/project/source/page/graph
• MCP server — 13 tools exposing the wiki to any LLM agent over stdio
• Web viewer — Blazor Server + Tailwind, read-only browsing with backlinks, graph, and search
• Hosted mode — EF Core + SQL Server LocalDB + Firebase auth + per-tenant storage for multi-user deployment
• 63 automated tests across Core + Wiki + MCP

Architecture

A meshnote project is a plain markdown directory — fully compatible with Obsidian, VS Code, and any text editor. Meshnote does not own the file format; markdown + YAML frontmatter does.

my-wiki/
├── .meshnote/config.json   Project metadata (id, template, description)
├── schema.md               LLM operating instructions (template-specific)
├── raw/
│   ├── sources/            Immutable source documents
│   └── assets/             Images, PDFs, referenced media
└── wiki/
    ├── index.md            LLM-maintained catalog
    ├── log.md              Chronological timeline of ingests/queries/lints
    ├── entities/           People, orgs, products, characters — whatever "thing" means
    ├── concepts/           Topics, ideas, themes
    ├── summaries/          One page per raw source
    └── synthesis/          Cross-cutting analysis, comparisons, your evolving thesis

The three layers

1. Raw sources — immutable source material in raw/. You drop files here; meshnote never modifies them.
2. The wiki — LLM-generated, structured markdown in wiki/. The agent owns this.
3. The schema — schema.md at the project root. Operating instructions for the agent.

The three operations

• Ingest — agent reads a raw source, writes a summary page, updates affected entity/concept pages, appends to log.md, refreshes index.md.
• Query — agent searches the wiki, reads relevant pages, synthesizes an answer with [[wikilinks]]. Can file non-trivial answers back as new synthesis pages.
• Lint — agent health-checks the wiki: orphan pages, missing concepts, contradictions, stale claims.

All three are performed by the LLM, via the MCP tools that meshnote exposes. The CLI provides the primitives; the agent orchestrates.

How it works (condensed)

You install meshnote as a dotnet tool. You create one or more brains with meshnote init, each picking a template that writes a different schema.md. You tell Claude Code (or any MCP-compatible agent) that meshnote is an MCP server. The agent can now see your brains through 13 MCP tools: list_projects, get_schema, search_wiki, read_page, write_page, append_log, register_source, get_backlinks, get_graph, and a few more. Every tool takes a project argument — the agent picks which brain to operate on.

You drop raw sources into raw/sources/ in any brain. You tell Claude "ingest the new source in my research brain." Claude reads the brain's schema.md first (to learn how this brain wants things done), then reads the source, discusses key takeaways with you, and writes summary / entity / concept pages into the wiki via write_page — all as atomic markdown writes. A month later when you ask a question, Claude searches the wiki with BM25, reads relevant pages, synthesizes an answer with [[wikilinks]], and optionally files the answer as a new synthesis page so future questions benefit from it.

You can browse everything in a local web viewer (meshnote serve → localhost:5173) with a dark-themed UI showing project cards, rendered markdown with backlinks panels, an interactive search, and a link graph — but editing still happens via the LLM or in your text editor of choice.

Local mode (default): your brains live in directories on your laptop, registered in ~/.meshnote/projects.json. No server, no account, no database. Back it up with git.

Hosted mode (for meshnote.io): same code, with Firebase auth, SQL Server metadata, and per-tenant directories on the server. Each user sees only their own brains. You can always export and fall back to local mode — the files stay plain markdown.

Read docs/how-it-works.md for the full walkthrough including concrete code paths, multi-tenancy details, and what a Claude Code ingest session looks like step by step.

Quick start

Requires the .NET 10 SDK.

1. Build

git clone https://github.com/meshnote/meshnote
cd meshnote
dotnet build meshnote.slnx

2. Create some brains

# A research wiki for a topic you're digging into
dotnet run --project src/Meshnote.Cli -- init ~/brains/research \
  --template research \
  --name "LLM Training Dynamics" \
  --description "Deep dive into how transformers actually learn"

# A reading companion for a book
dotnet run --project src/Meshnote.Cli -- init ~/brains/dune \
  --template book \
  --name "Dune Companion"

# A private journal brain
dotnet run --project src/Meshnote.Cli -- init ~/brains/personal \
  --template personal

# A team knowledge base
dotnet run --project src/Meshnote.Cli -- init ~/brains/acme \
  --template business \
  --description "Shared knowledge for Acme team"

Each init scaffolds the directory tree, writes a template-specific schema.md, seeds index.md and log.md, and registers the project in ~/.meshnote/projects.json.

List what you have:

dotnet run --project src/Meshnote.Cli -- project list

3. Wire it into your LLM agent via MCP

Meshnote can talk to MCP clients in two ways: stdio (local mode, runs on your machine) or HTTP with bearer auth (hosted mode, runs at meshnote.io).

Local stdio (the simple case) — for Claude Code running on the same machine as your brains, add this to ~/.claude/mcp_servers.json (or equivalent):

{
  "mcpServers": {
    "meshnote": {
      "command": "meshnote",
      "args": ["mcp"]
    }
  }
}

Claude Code launches meshnote mcp as a subprocess. The stdio MCP server reads/writes the files in your local ~/.meshnote/projects.json registry directly. No authentication needed because everything runs as your local user.

Hosted HTTP (multi-user, remote) — for connecting Claude Code to a hosted meshnote.io deployment, point at the /mcp endpoint with a bearer token:

{
  "mcpServers": {
    "meshnote": {
      "type": "http",
      "url": "https://meshnote.io/mcp",
      "headers": {
        "Authorization": "Bearer <your-firebase-id-token-or-dev-email>"
      }
    }
  }
}

The bearer token is validated by MeshnoteBearerHandler against the configured auth provider — Firebase ID tokens in production, dev emails when Meshnote:Auth:Provider = "dev". The same provider that gates the cookie-based web UI also gates the MCP endpoint, so the user identity is consistent across both. Every MCP tool call is automatically scoped to the authenticated user via DbProjectStore — alice's list_projects only returns alice's brains.

In either mode, your agent can now call list_projects, get_schema, search_wiki, read_page, write_page, append_log, register_source, and the rest of the 13 tools — all scoped by a project argument. The first thing a well-behaved agent should do on a new project is call get_schema to read the template's operating instructions.

4. Browse in the web UI (optional)

dotnet run --project src/Meshnote.Cli -- serve

Opens a Blazor viewer on http://localhost:5173. Project picker, per-brain sidebar with color-coded template badges, page view with rendered markdown and backlinks panel, full link graph, and BM25 search. Read-only by design — editing happens via the LLM or your text editor.

CLI reference

The -p / --project flag defaults to the current directory if it's a meshnote project, or to the single registered project if exactly one is known.

CLI design note

ingest, query, and lint are not user-facing commands — they are things the LLM does via MCP. The CLI exposes the primitives (read, write, search, register) that an agent needs to perform those higher-level operations. This keeps meshnote a substrate, not an agent.

MCP tool reference

See docs/mcp-spec.md for the full tool and prompt surface. Highlights:

• Discovery: list_projects, get_schema, get_index
• Reading: read_page, read_source, list_pages, list_sources
• Search: search_wiki
• Graph: get_backlinks, get_graph
• Writing: write_page, append_log, register_source
• Prompts: ingest_source, lint_wiki, answer_query

Project layout

src/
  Meshnote.Core/     Domain types (Project, Page, Source, LogEntry, ...)
  Meshnote.Wiki/     File IO, markdown, search, templates, scaffolding
  Meshnote.Cli/      `meshnote` command-line tool (System.CommandLine)
  Meshnote.Mcp/      MCP server (stdio transport, C# SDK)
  Meshnote.Data/     EF Core + MSSQL (scaffolded for v0.2 hosted mode)
  Meshnote.Web/      Blazor Server + Tailwind viewer
tests/               xUnit tests — Core, Wiki, MCP
samples/demo-wiki/   A minimal browsable example project
docs/
  schema-spec.md     On-disk format reference
  mcp-spec.md        MCP tool and prompt reference

Compatibility with Obsidian

A meshnote project is a valid Obsidian vault. You can open the project root in Obsidian directly and use the graph view, backlinks panel, and community plugins. Meshnote never touches .obsidian/ — that's your space.

Conversely, a plain Obsidian vault can be converted to a meshnote project by running meshnote init . in the vault root. This creates .meshnote/config.json and scaffolds any missing directories; existing files are left alone.

What's next (v0.2)

• Hosted meshnote.io — auth, multi-tenancy, sync, in-browser editor
• EF Core + MSSQL backing store for the hosted tier (already scaffolded)
• File watcher → live reload in the web viewer
• Proper dotnet tool install packaging with bundled web assets
• Embeddings search option alongside BM25

License

TBD.