NOAT

Notion-style notes that live in your IDE. Local-first, git-versioned, searchable, and readable/writable by your AI agents over MCP.

Stop taking notes in stray .md files or a separate app. NOAT gives you a real block editor inside Cursor / VS Code, keeps every note on your machine with its own git history, and hands your agents a full set of tools to read, search, and write your notes.

Features

A real editor, not a text file

Notes open as normal editor tabs with a Notion-style block editor: type / for headings, checklists, tables, quotes, and code blocks (with syntax highlighting that uses your editor font). Native dirty-state and undo, plus auto-save moments after you stop typing.

Link to code with @

Type @ in a note to fuzzy-search every file in your workspace and insert a link chip. Click a chip and the file opens in the column beside your note. Paths are stored repo-relative, so links keep working across machines.

Repo-scoped or global

Notes are either global (visible everywhere) or scoped to a repository (keyed by its origin remote, so clones on other machines see the same notes). Organize freely with folders; move notes between scopes from the sidebar.

Search that works like a personal Google

Cmd+Shift+S opens a search palette combining two engines:

• Keyword — fuzzy, prefix-matching, BM25-ranked full-text search (instant)
• Semantic — a local embedding model (all-MiniLM-L6-v2, ~25 MB one-time download) finds notes by meaning: "stop charging customers twice" finds your double-charge incident postmortem

Results merge via reciprocal rank fusion. Everything runs locally — no API key, nothing leaves your machine.

Agent access via MCP

A bundled MCP server exposes your notes to AI agents:

Agents write plain markdown; NOAT converts it to real editor blocks. In Cursor the server registers itself automatically — no configuration.

Git-versioned, synced to your commits

~/.noat is its own git repository. Note edits save to disk immediately, and whenever you commit in any workspace repo, NOAT snapshots your pending note changes with a message linking the two histories:

sync(my-repo): 3942d13 Fix webhook ordering [2026-07-07 16:35]

No hooks are installed in your repositories — NOAT watches for commits through the editor's git integration.

Install

From source (marketplace release coming):

git clone https://github.com/pintchom/noat && cd noat
npm install
npm run install-local   # builds, packages, and installs into Cursor

Reload your editor window. You'll find the NOAT book icon in the activity bar.

Note: the packaged extension currently bundles native binaries for the platform you build on (e.g. Apple Silicon). Per-platform marketplace builds are on the roadmap.

Quick start

1. Click the NOAT icon in the activity bar → New Note (scoped to your repo or global).
2. Write. Type / for blocks, @ to link a file. It auto-saves.
3. Cmd+Shift+S to search everything.
4. Commit code like you always do — your notes snapshot themselves alongside.
5. Ask your agent things like "search my notes for the ledger migration plan" or "save what we just learned to a note in this repo's scope."

Keybindings & commands

Command palette: NOAT: New Note, NOAT: New Folder, NOAT: Search Notes, NOAT: Rebuild Search Index, NOAT: Open Notes Store in Terminal, NOAT: Refresh Notes.

MCP setup outside Cursor

Cursor registers the MCP server automatically. For other MCP clients, point at the bundled server:

{
  "mcpServers": {
    "noat": {
      "command": "node",
      "args": ["/path/to/extension/dist/mcp-server.js"]
    }
  }
}

The server works standalone — it reads ~/.noat directly and doesn't need the editor running. Set NOAT_HOME to use a different store location.

Storage

Everything lives in ~/.noat (override with NOAT_HOME):

~/.noat/
  .git/                  # your notes' own git history
  .cache/                # embedding model cache (gitignored)
  .index/                # search indexes — derived, rebuildable (gitignored)
  notes/
    global/              # universal notes, nested folders allowed
    repos/<repo-key>/    # notes scoped to one repository

Notes are .noat.json files: a small envelope (id, title, timestamps) around a BlockNote block array. Plain files — grep them, script against them, take them with you.

Architecture

┌─────────────────────────────┐
│ Cursor / VS Code            │
│  ┌──────────┐ ┌───────────┐ │      ┌──────────────┐
│  │ Webview  │ │ Extension │ │      │  MCP server  │◄── agents
│  │ editor   │◄┤ host      │ │      │  (stdio)     │
│  └──────────┘ └─────┬─────┘ │      └──────┬───────┘
└─────────────────────┼───────┘             │
                      ▼                     ▼
                ┌─────────────────────────────┐
                │  ~/.noat  (git repository)  │
                └─────────────────────────────┘

• Extension host — sidebar tree, commands, git sync, search engine, file-open actions
• Webview — React + BlockNote custom editor for *.noat.json
• MCP server — standalone stdio binary sharing the same core code and store
• Core (src/core/) — note model, store I/O, repo scoping, search; no VS Code dependency

Development

npm install
npm run watch        # rebuild on change; F5 to launch a dev host
npm test             # core unit tests
npm run typecheck    # all three targets
npm run lint
npm run seed         # fill your store with rich demo notes + backdated history

See CONTRIBUTING.md for project layout and conventions.

Roadmap

• Note history viewer (versions live in git already; UI pending)
• Line-number file links (file.ts:42)
• Title edits renaming the underlying file
• Per-platform marketplace builds (OpenVSX + VS Code Marketplace)

License

MIT