🧠 cortex

A local, Obsidian-compatible second brain for agents.

An agent that re-derives the same facts every session is spending tokens to stay ignorant. cortex gives it a durable, wikilinked knowledge base on disk: it distils what it learns into small interconnected markdown notes, then recalls just enough of them later. Notes link to each other with [[wikilinks]], so the brain becomes a graph you can traverse — backlinks, related notes, hubs, orphans — not a flat pile of memories.

Every note is a plain markdown file in a folder, so you can open the exact same vault in Obsidian and watch the graph grow. Based on Andrej Karpathy's LLM Wiki pattern: compile knowledge once into an interconnected wiki instead of asking the model the same questions over and over.

Part of tools-for-agents. Zero dependencies — Node standard library + built-in node:sqlite with FTS5. The markdown files are the source of truth; the SQLite index is derived and rebuildable at any time.

Why

Related MCP server: Obsidian MCP Server

The vault

cortex keeps notes in $CORTEX_VAULT (default ./vault), organised by type — the Karpathy LLM-Wiki layout:

vault/
├── concepts/     # ideas, frameworks, theories
├── entities/     # people, orgs, products, tools
├── sources/      # captured raw material + summaries
├── synthesis/    # comparisons, analyses, themes
├── daily/        # timestamped journal, one file per day
├── notes/        # anything else
└── .cortex/      # the derived SQLite index (safe to delete & rebuild)

A note is just markdown with YAML frontmatter:

---
title: Backpropagation
type: concept
tags: [deeplearning]
---

The algorithm that trains [[Neural Networks]] by propagating error via the
chain rule. Uses [[Gradient Descent]]. #optimization

Write [[Other Note]] to link and #tags to categorise. Links to notes that don't exist yet are broken links — cortex tracks them as suggestions, and they heal automatically the moment you write that note.

CLI

cortex write "Neural Networks" --type concept --tags ml,ai \
  --body "Function approximator. Trained by [[Backpropagation]]. #deeplearning"
cortex write "Neural Networks" --append --body "Modern variants: [[Transformers]]."
cortex capture "raw article text…" --source https://example.com   # inbox for later
cortex search "train network error" -k 6 --tag deeplearning        # ranked snippets
cortex read "Neural Networks"                                      # full note
cortex links "Neural Networks" --in                                # backlinks
cortex related "Backpropagation"                                   # graph neighbourhood
cortex suggest "Backpropagation"                                   # notes to link that aren't linked yet
cortex lint                                                        # health report: orphans/broken/untagged/stubs
cortex tags | cortex tags deeplearning                             # tags → notes
cortex graph                                                       # hubs, orphans, broken links
cortex daily "shipped the retriever"                               # journal
cortex sync                                                        # re-index after Obsidian edits
cortex serve --port 7800                                           # live graph web view
cortex stats

Vault location: $CORTEX_VAULT (default ./vault).

Web view

cortex serve starts a zero-dependency web app at http://localhost:7800 — a premium, Obsidian-style knowledge graph of your vault rendered on canvas: glowing nodes (sized by connections, coloured by type) joined by [[wikilink]] synapses.

• Hover any note to trace its neighbourhood — connected notes light up with energy flowing along the links, everything else dims — and a tooltip previews the note at a glance: its type, connection count, a ★ hub marker for the most-linked notes, and its #tags, so you can read what a note is about without opening it.

• Click a note to read it in a side panel (fetched live): its body with clickable [[wikilinks]], its tags, and its links to / linked from lists — navigate note-to-note with a back button.

• Related notes — the panel also surfaces notes that share a tag but aren't linked yet (ranked by shared-tag count), each showing the tag they have in common — the latent connections worth writing, so your second brain keeps knitting itself together.

• Search from the top bar (ranked dropdown, keyboard-navigable), filter by type from the legend, click the stat for a graph overview — hubs, type breakdown, and the gaps worth closing: orphans (notes with no links, ready to connect) and unwritten notes (broken-link targets to write). Click an orphan to open it, or an unwritten one to fly to what references it.

• Drag to rearrange, scroll/pinch to zoom, recenter, and a light/dark theme toggle.

• Path finder — hit the ⤳ path control, then click two notes: cortex traces the shortest chain of [[wikilinks]] connecting them (breadth-first over the link graph), lighting the route in a pulse from start to end and dimming everything else, with a readout of the hops (Backpropagation → Neural Networks → Transformers · 2 hops). The answer to "how are these two ideas related?" — or "are they connected at all?" — at a glance.

• Focus mode — open a note and hit ◎ focus neighbourhood to isolate its corner of the brain: everything within a 1 / 2 / 3-hop radius stays lit, everything else fades. Dial the radius live and see how far the idea reaches (recall · 2 hops · 11 notes) — a clean read of one note's context without the whole graph competing for attention.

• Write a note from the graph — hit ＋ (or n) to author a note straight into the vault: title, type, tags, markdown body with [[wikilinks]]. And the graph's ghosts stop being dead ends: it has always shown you unwritten notes — a dashed node where a [[wikilink]] points at nothing — and then refused to help. Now clicking a ghost opens the composer with its title already in place (“Something already links to Raft — writing it heals that link into the graph”). Write it, and the broken link becomes a real edge. Writing is a POST (a GET reads a note; only a request that means to can rewrite the vault).

• The journal — hit ✎ (or j) and write a line into today: what happened. It appends a timestamped bullet to today's note, and the panel reads the days back — the last leg of cortex's own loop (recall → capture → distil → connect → journal) was the one thing the brain could write and never show. Today becomes a real node in the graph like any other note, so the day you did the work is linked to the work.

• Vault health — a second brain that can't tell you it's decaying will decay quietly. lint has always known the vault's condition — what's orphaned, what points at nothing, what's untagged, what's a stub, and what has gone quiet — and nothing ever showed it: the graph draws broken links as ghosts but never counted them. Now a health chip (13 to tend / vault is healthy) opens the whole report, and every issue is one click from being fixed: a broken link opens the composer with the missing note's title already in place — write it and the link heals itself. Note that fixing one thing can raise the count, honestly: heal a link by writing a two-line note, and it shows up as untagged and barely written. It is not flattering you.

• The inbox — four tools now capture into cortex (recall, lens, anvil, scout), and every capture lands untagged and unlinked — a graph quietly accumulating dead ends. The 📥 inbox (with a count badge) is the maintenance loop, made one-click: it lists every note nothing links to, says why it's stranded (orphan · untagged · stub), and proposes what it belongs with — the notes it already resembles (FTS-similar but unlinked) and the tags those notes carry. Pick, hit weave in, and cortex writes the tags into the note's frontmatter and a Related: [[…]] line into its body — real edits to the file, so the links heal into the graph like any other. Agents get the same loop via cortex_triage + cortex_weave.

• Recency heat — hit the ◔ last updated control and the graph re-shades by time: notes you touched today burn amber, the ones cooling off fade toward slate, and the parts of your brain you have not thought about in a year go cold. The scale is logarithmic in age (a day vs a week matters as much as a month vs half a year), relative to your own vault's span — so the dormant corners are obvious whether you write daily or once a season. Every tooltip also shows updated 3h ago.

• Capture from anywhere — POST /api/capture is the one write the web view exposes (a GET can never create a note), and it is what lets the rest of the toolkit write into your brain: hit 🧠 → cortex on any recall result — something the team knew, a page you read, a line of code — and it lands here as a note, carrying a link back to where it came from. The graph is watching the vault, so it blooms in live.

• Minimap — a small overview of the whole brain sits in the top-left, with a rectangle marking the part you're looking at; click or drag on it to fly across a large graph without losing your place.

• Keyboard-accessible — every control has a visible focus ring, and the legend type-filters, note-panel links and related notes are all reachable with Tab + Enter (not just the mouse), with aria-labels throughout.

• Live — the server watches the vault and pushes updates over SSE, so the graph grows in real time as your agent (or you, in Obsidian) writes notes. It's the same brain your agent writes to — watch it grow.

Want a graph to look at right away? Seed a starter vault (interlinked notes about the toolkit itself):

CORTEX_VAULT=./vault node scripts/seed.js   # 12 connected notes, 0 orphans
node src/cli.js serve

MCP server (for agents)

{
  "mcpServers": {
    "cortex": { "command": "node", "args": ["/abs/path/to/cortex/mcp/mcp-server.js"],
                "env": { "CORTEX_VAULT": "/abs/path/to/your/vault" } }
  }
}

Tools

A good loop for an agent

1. Recall first — cortex_search before solving; you may have already worked this out.

2. Capture raw findings with cortex_capture as you go.

3. Distil into small cortex_write notes, each linking to related concepts with [[…]].

4. Connect — check cortex_graph for orphans and broken links, and write the missing notes.

5. Journal the session with cortex_daily so the next run has a trail.

How it works

• Files are truth. Each note is a markdown file with YAML frontmatter; the SQLite index is derived from them and rebuilt by sync (incremental by mtime). Delete .cortex/ any time — it regenerates.

• Search is FTS5 (porter unicode61) ranked by bm25, filling snippets up to a token budget (≈4 chars/token) — the same discipline as lens, pointed at your brain instead of a codebase.

• The graph is a link table. Every [[target]] is resolved to a note by slug, title or alias; unresolved targets are kept as broken links and heal automatically when the target note appears.

• Slugs are unicode-aware (Turkish and accented titles transliterate to clean ascii filenames).

• Obsidian-compatible end to end: open $CORTEX_VAULT as a vault and the wikilinks, tags and graph view all just work.

The agent toolkit

cortex is the remember leg of tools-for-agents — an operating system for agents. Seven zero-dependency, MCP-native tools that form one loop:

Reading this as an agent? /llms.txt is the map, and /tools.json hands you all 70 MCP tools — every name, every description, every install command — in one fetch, without cloning anything.

MIT licensed.