convez.ai
MCP ServerIntegração & APIsIntermediário
Gustav-Proxi

Cortex — Servidor MCP local para seu Obsidian

Gustav-Proxi/cortex

Cérebro local para suas notas — busca semântica + leitura/escrita em Obsidian

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que expõe seu cofre Obsidian inteiro para qualquer cliente LLM, com busca semântica + literal, embeddings locais via Ollama e índice sqlite-vec. Permite leitura e escrita completas de notas, mantendo seu conhecimento sincronizado e local.

Instalação

$npx convez-ai Gustav-Proxi/cortex

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
v0.1.7
Issues abertas
0
Contribuidores
1

Casos de uso

  • Integrar base de conhecimento Obsidian com agentes e assistentes de IA
  • Fazer buscas híbridas (semânticas e literais) sobre seus anotações
  • Permitir que LLMs leiam e escrevam notas diretamente no cofre

Veredito

Cortex é uma solução técnica sólida para quem quer expor um cofre Obsidian a LLMs mantendo tudo local e privado. Recomendado para usuários avançados que dominam Obsidian e querem integração profunda com fluxos de IA; a curva de aprendizado é real, mas a arquitetura (Ollama + sqlite-vec) é confiável e bem pensada.

README

A tradução para o português deste README ainda está na fila.

🧠 Cortex

The local-first brain for your notes — one MCP server that gives every LLM client your entire Obsidian vault.

License: Apache 2.0 Python MCP server 100% local Embeddings: Ollama Vectors: sqlite-vec macOS app

Cortex

"Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase." — Andrej Karpathy, LLM Wiki (2026)

Karpathy's point: a markdown knowledge base only stays alive if something tireless maintains it — "the tedious part of maintaining a knowledge base is not the reading or the thinking — it's the bookkeeping. The LLM handles that." Cortex is the engine that makes that real, and it exposes the whole vault over MCP so every LLM surface (Claude Code, Desktop, agents) shares one brain — not just a single app.

What it does

Cortex turns a folder of markdown (your Obsidian vault) into something an LLM can actually use:

  • 🔎 Search — semantic (local embeddings), literal (grep), and hybrid (keyword ⊕ vector); plus frontmatter/property filters and the [[wikilink]] graph (backlinks / outgoing_links).
  • ✍️ Read & write — full note CRUD, frontmatter, templates, daily notes. The LLM can file answers back into the wiki, so knowledge compounds instead of vanishing into chat history.
  • 📚 Research helpers — DOI/arXiv → APA + BibTeX, deadline extraction from your notes, unlinked-neighbour suggestions.
  • 🕸️ Graph intelligence — shortest path between notes, "god nodes" (hubs), topical communities, and semantic bridges (notes that read as related but aren't [[linked]]); export to mermaid/cypher/graphml.
  • 📎 Beyond markdown — point CORTEX_EXTRA_ROOTS at a papers folder or a project's codebase and Cortex indexes PDFs and source code too, searchable alongside your notes.
  • ⚡ Always current — a background watcher re-embeds changed notes within ~2 s; the index is a single sqlite file.

It reads and writes the vault's markdown directly — no Obsidian process, no HTTP bridge, no bearer token. Nothing leaves the machine: embeddings run locally via Ollama.

Why it's different

CortexPlain RAGIn-Obsidian plugins
Works inevery MCP client (Code, Desktop, agents)one app/integrationObsidian only
Reads and writes✅ full CRUD — knowledge compounds❌ retrieval onlypartial
Privacy🔒 100% local (Ollama)often cloudvaries
Moving partsone sqlite file + one processvector DB + serviceObsidian + plugin
Beyond retrievalmaintains the wiki (links, files, prunes)re-searches every querymanual

The point isn't "search your notes." It's a persistent, compounding knowledge layer the LLM maintains for you — reachable everywhere through one open protocol.

Architecture

The one-way pipeline that keeps search current:

flowchart LR
    V["vault\n~/Claude"] -->|chunk| C["nomic-embed-text\nOllama"]
    C --> S["sqlite-vec"]
    S -->|watchdog re-embeds changes| V
    V --> FS["vault.py\nfile CRUD · links · search"]
    FS --> MCP["FastMCP server"]
    FS --> HTTP["http_api :8788"]
    MCP -->|stdio| LC["Claude Code / Desktop"]
    MCP -->|--http| RE["remote clients"]
    HTTP --> OBS["Obsidian plugin"]
    HTTP --> APP["Cortex.app · macOS"]

One engine, three clients: Claude over MCP, and the Obsidian plugin + the native macOS app over the loopback JSON API.

Design choices

ConcernChoiceWhy
Embeddingsnomic-embed-text via Ollama768-dim, strong, fully local, fast on M-series. Vault text never leaves the Mac.
Vector storesqlite-vecSingle file, no server, no Docker.
ServerFastMCPstdio for local Claude; --http for remote later.
SyncwatchdogRe-embeds only changed notes, prunes deleted ones.
Filesdirect disk I/O (vault.py)No Obsidian process needed — read/write markdown straight, with path-safety.

Location

The repo lives at ~/cortex — deliberately outside ~/Documents, which macOS syncs to iCloud. A 2,500-file venv in an iCloud folder triggers an upload storm and EDEADLK lock-contention crashes; keeping Cortex in ~/ avoids it. The index (~/.cortex/index.db) is also outside the vault so it never indexes itself.

Requirements

NeedMinimumNotes
OSmacOS 13+ (Apple Silicon)Works on Linux too; only the launchd auto-start is macOS-specific (use systemd/cron elsewhere).
Python3.10+The installer creates a repo-local .venv.
Ollamarunning locallyServes the embedding model. Nothing leaves the machine.
Embedding modelnomic-embed-text (768-dim)ollama pull nomic-embed-text. Any Ollama embed model works if you also set CORTEX_EMBED_DIM to match.
A markdown folderan Obsidian vault, or any dir of .mdPointed to by CORTEX_VAULT. Obsidian itself does not need to be running.
An MCP clientClaude Code, Claude Desktop, or any MCP-capable clientThis is what connects to Cortex (see Connect it to an MCP client).
Diska few hundred MBthe venv + the sqlite index at ~/.cortex/index.db.

Python deps (installed automatically by pip install -e .): sqlite-vec, mcp, watchdog, pyyaml, ruamel.yaml.

Install (macOS, Apple Silicon)

cd ~/cortex
CORTEX_VAULT="$HOME/Claude" bash install.sh

Installs Ollama + the model, makes a venv, builds the first index. Manual:

brew install ollama && brew services start ollama   # auto-starts on login
ollama pull nomic-embed-text
python3 -m venv .venv && ./.venv/bin/pip install -e .
CORTEX_VAULT="$HOME/Claude" ./.venv/bin/python -m cortex.index build

CLI

./.venv/bin/python -m cortex.index search "what did I decide about baselines?"
./.venv/bin/python -m cortex.index build          # incremental (changed notes)
./.venv/bin/python -m cortex.index build --full   # rebuild everything
./.venv/bin/python -m cortex.index stats

The MCP tools (33)

Search & recall — semantic_search, related_notes, search_text (grep), search_property (frontmatter status/type/domain), hybrid_search (keyword ⊕ vector), search_filtered (semantic within a property), backlinks, outgoing_links Graph intelligence — graph_overview, graph_path (shortest [[link]] path), graph_hubs ("god nodes"), graph_communities (topical clusters), graph_bridges (semantic-but-unlinked pairs), graph_export (mermaid/cypher/graphml/json) Read — get_note, get_section, get_metadata, list_notes, list_folders, vault_stats Write & manage — write_note, append_note, patch_note, set_property, delete_note, move_note (rewrites [[wikilinks]] vault-wide) Templates & daily — create_from_template, daily_note Research — lookup_paper (DOI/arXiv → APA + BibTeX), deadlines (gates from STATE.md), suggest_links (unlinked semantic neighbours) System — reindex, run_command (gated; off unless CORTEX_ALLOW_EXEC=1)

Anything the write tools touch is re-embedded by the watcher within ~2 s, so search stays current. The only things not here are live-UI actions (open a note in the running app, fire an Obsidian command) — those genuinely need the client.

Inside Obsidian — the Cortex plugin

Cortex also has an in-Obsidian face: a plugin (obsidian-plugin/, symlinked into the vault) that talks to the engine over a small loopback JSON API (cortex/http_api.py, served by the watcher on 127.0.0.1:8788). It adds a semantic search pane, auto-connections (embedding-nearest notes for the active note, Smart-Connections-style, refreshing as you navigate), look up selection, and capture (create a note via the engine — a write).

So the brain has three faces over one engine: Claude via MCP (full read+write, stdio), Obsidian via the plugin (search / connections / capture, HTTP), and a native macOS app (the constellation + reader + Spotlight, HTTP — see below). Install the plugin: symlink obsidian-plugin/ to ~/Claude/.obsidian/plugins/cortex and enable it — see obsidian-plugin/README.md.

The desktop app — Cortex.app

A native macOS app (desktop/) is the third face over the same engine — a thin SwiftUI + Core-Graphics client of the loopback JSON API (127.0.0.1:8788). It bakes in nothing: embeddings stay in Ollama, the index in ~/.cortex. It needs the engine running (the watcher serves the :8788 API).

  • Constellation — a live force-directed graph of the whole vault: luminous orbs coloured by domain (top-level folder as a fallback), curved links, hover focus-paths, hub labels, and full pan / wheel-&-pinch zoom / node-drag. Settles, then idles at ~0 CPU.
  • Reader + inspector — a serif markdown reader with a local-graph mini-map of the open note's neighbourhood, its properties, and semantic-related notes. Library grid + inline editing.
  • Spotlight (⌘K) — semantic / hybrid search and a grounded Ask (shells to the Claude CLI; answers on your own subscription, with sources).
  • Live — an FSEvents watcher + a short poll keep the graph, link counts, and chunk total in sync as you edit notes anywhere, with no reload; a footer pulse confirms each save.
  • Onboarding with a vault folder picker.

Get it — download the latest release (Cortex-macos.zip), unzip, drag Cortex.app to /Applications. It's ad-hoc signed, so on first launch right-click → Open (or xattr -dr com.apple.quarantine /Applications/Cortex.app).

Build from source — no Xcode project, just system swiftc:

cd desktop && bash build.sh        # → desktop/Cortex.app
open desktop/Cortex.app

Connect it to an MCP client

How the connection works

Cortex is a stdio MCP server. The client launches python -m cortex.server as a subprocess and speaks JSON-RPC over stdin/stdout — for local use there's no port, no daemon, and no auth to manage. The client starts the process when it connects and kills it on exit, so the MCP server needs no auto-start of its own (only the background watcher does — see Auto-start). Each tool call routes to store+embed (search) or vault (read/write) and the result streams back to the client.

To register Cortex anywhere you need exactly three things:

  1. command — the absolute path to the venv's Python (clients don't inherit your shell, so a relative path or bare python will fail).
  2. args — ["-m", "cortex.server"]
  3. env — CORTEX_VAULT pointing at your vault (plus any overrides from Config).

Find the absolute venv python: from the repo root run echo "$PWD/.venv/bin/python".

Two transports are available:

  • stdio (default) — for local clients: python -m cortex.server
  • streamable-http — for remote/shared use: python -m cortex.server --http (serves 127.0.0.1:8787; front it with auth before exposing — see Going remote).

Claude Code (CLI)

claude mcp add cortex \
  -s user \
  -e CORTEX_VAULT="$HOME/Claude" \
  -- /absolute/path/to/cortex/.venv/bin/python -m cortex.server
  • -s user registers it for all your projects. Use -s local for just the current one, or -s project to commit it to a shared .mcp.json.
  • Verify: claude mcp list should print cortex … ✓ Connected. Inside a session, /mcp lists the tools.
  • Remove/re-add after a code change isn't needed — but the client caches the running process per session, so reconnect (or restart the client) to pick up edits to the server code.

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json), then fully quit and reopen Claude:

{
  "mcpServers": {
    "cortex": {
      "command": "/absolute/path/to/cortex/.venv/bin/python",
      "args": ["-m", "cortex.server"],
      "env": { "CORTEX_VAULT": "/absolute/path/to/your/vault" }
    }
  }
}

Any other MCP client

It's a standard stdio MCP server — point any client at the same command / args / env:

command: /absolute/path/to/cortex/.venv/bin/python
args:    ["-m", "cortex.server"]
env:     { "CORTEX_VAULT": "/absolute/path/to/your/vault" }

This is the only vault MCP you need — it replaces the old Obsidian REST-API / MCP-Connector plugins (and their bearer token) entirely.

Auto-start in the background

# install.sh does this for you. To do it by hand, from the repo root:
sed -e "s#__VENV_PYTHON__#$PWD/.venv/bin/python#" \
    -e "s#__WORKDIR__#$PWD#" \
    -e "s#__VAULT__#${CORTEX_VAULT:-$HOME/Claude}#" \
  launchd/cortex.watch.plist.template > ~/Library/LaunchAgents/dev.cortex.watch.plist
launchctl load -w ~/Library/LaunchAgents/dev.cortex.watch.plist

RunAtLoad + KeepAlive start the watcher on login; ProcessType=Background + Nice keep it gentle on the M4. Ollama auto-starts via brew services. The stdio MCP server is spawned on demand by each Claude client, so it needs no agent of its own.

Going remote later

python -m cortex.server --http serves streamable-http on 127.0.0.1:8787. Front it with auth (Cloudflare Tunnel / Fly) and expose only a sanitized subset — never the private research vault.

Config (env vars)

VarDefaultNotes
CORTEX_VAULT~/Claudevault root
CORTEX_DB~/.cortex/index.dbvector store (keep private)
CORTEX_EMBED_MODELnomic-embed-textany Ollama embed model
CORTEX_EMBED_DIM768must match the model
OLLAMA_HOSThttp://127.0.0.1:11434
CORTEX_CHUNK_CHARS / CORTEX_CHUNK_OVERLAP1200 / 150chunking
CORTEX_DAILY_FOLDER / CORTEX_DAILY_FORMATdaily / %Y-%m-%ddaily notes
CORTEX_HTTP_API_PORT8788loopback JSON API for the Obsidian plugin
CORTEX_ALLOW_EXECunset1 enables run_command
CORTEX_EXEC_TIMEOUT60seconds, for run_command

Troubleshooting

SymptomLikely causeFix
Client shows cortex failed / not connectedwrong python path, or deps not installedUse the absolute venv python; re-run pip install -e .. Sanity check: run the exact command in a terminal — it should start and wait silently (Ctrl-C to exit).
Vault not found / no resultsCORTEX_VAULT unset or wrong in the client configPass -e CORTEX_VAULT=/path/to/vault; clients do not read your shell env.
Errors mentioning Ollama / connection refusedOllama not running or model not pulledollama serve (or brew services start ollama) and ollama pull nomic-embed-text.
EmbedError dimension mismatchmodel ≠ CORTEX_EMBED_DIMSet CORTEX_EMBED_DIM to the model's width and rebuild: … index build --full.
Vault edits don't appear in searchthe watcher isn't runningStart python -m cortex.watch (or load the launchd agent), or run … index build once.
Tools work but server code changes don't take effectclient cached the spawned processReconnect MCP / restart the client — the stdio server is launched per client session.

Security note

  • The index embeds note text. ~/.cortex/index.db is gitignored — keep it out of any synced or public folder.
  • The loopback JSON API can read and write the vault. It binds to 127.0.0.1 only and sends no CORS headers, so other local processes can reach it but web pages cannot. Don't bind it off-loopback or re-add permissive CORS; put authentication in front before any remote exposure.
  • run_command is gated behind CORTEX_ALLOW_EXEC=1 (off by default) — leave it off unless you mean it.
  • Scrub secrets before sharing a vault. If you ever used the old Obsidian REST API, its bearer token may linger in old notes — remove it before exporting anything.

License

Apache-2.0 © 2026 Vaishak G Kumar (Gustav-Proxi).

Ver o original no GitHub

Bom para

Relacionados