██████╗ ██████╗ ███████╗██╗██████╗ ██╗ █████╗ ███╗   ██╗
██╔═══██╗██╔══██╗██╔════╝██║██╔══██╗██║██╔══██╗████╗  ██║
██║   ██║██████╔╝███████╗██║██║  ██║██║███████║██╔██╗ ██║
██║   ██║██╔══██╗╚════██║██║██║  ██║██║██╔══██║██║╚██╗██║
╚██████╔╝██████╔╝███████║██║██████╔╝██║██║  ██║██║ ╚████║
 ╚═════╝ ╚═════╝ ╚══════╝╚═╝╚═════╝ ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝

██╗      ██████╗  ██████╗ █████╗ ██╗         ███╗   ███╗ ██████╗██████╗
██║     ██╔═══██╗██╔════╝██╔══██╗██║         ████╗ ████║██╔════╝██╔══██╗
██║     ██║   ██║██║     ███████║██║         ██╔████╔██║██║     ██████╔╝
██║     ██║   ██║██║     ██╔══██║██║         ██║╚██╔╝██║██║     ██╔═══╝
███████╗╚██████╔╝╚██████╗██║  ██║███████╗    ██║ ╚═╝ ██║╚██████╗██║
╚══════╝ ╚═════╝  ╚═════╝╚═╝  ╚═╝╚══════╝    ╚═╝     ╚═╝ ╚═════╝╚═╝

Gives your AI coding assistant a memory of your codebase. Instead of grepping around blindly every session, it asks a local graph "what does this touch, what breaks if I change it, and what did we already learn about it?"

No API keys, no network calls, no embeddings. Everything runs on your machine.

What it does, in plain words

You ask your assistant to change something. Without this server, it searches for text and hopes for the best. With it:

You:  "the daily podcast is generating twice, fix it"

Assistant calls retrieve_context("daily podcast cron") and gets back:
  MUST_READ    the files that actually implement it
  MAY_CHANGE   what depends on them and would break
  MUST_TEST    the tests that cover it
  KNOWLEDGE    your note from three weeks ago explaining why the cron
               runs at 540s and what already went wrong once
  DANGER       anything flagged as risky to touch

Two things make that possible:

1. A graph of your code, built mechanically by reading your files (Python ast, TypeScript tree-sitter) and your git history. Files, symbols, who imports whom, who calls whom, what gets edited together.

2. An Obsidian vault of notes — plain .md files where you (or the assistant) write down the why: decisions, incidents, gotchas. Things that are nowhere in the code.

The code half gets rebuilt whenever you reindex. The notes half is yours and never gets overwritten.

Related MCP server: Threadnote

What you need

• uv — handles Python for you (it downloads Python 3.13 automatically; that version is pinned because tree-sitter-typescript wheels lag newer ones).

• A folder for your vault. That is all a vault is: a folder of .md files. Installing Obsidian is optional and only needed if you want to browse your notes and see the graph visually.

• Git repos you want indexed. Only files tracked by git are scanned.

Optional: a GPU or Apple Silicon, if you want the decision model. It is too slow on a CPU.

Setup

1. Install

git clone <this repo>
cd obsidian-local-mcp
uv sync

2. Set up your vault

uv run obsidian-local-mcp-setup

It asks two questions — whether to install the decision model (say no for now) and where your vault is — then writes ~/.obsidian-local-mcp/vaults.yaml and prints the block for step 3.

Copy vaults.example.yaml to somewhere outside this repo — it contains real paths from your machine, so it must never be committed:

default_vault: main

vaults:
  main:
    path: /path/to/your/vault-folder
    conventions: generic          # "generic" = no rules about note format
    repos:
      frontend:
        path: /path/to/your/frontend
        include: ["src/**"]
        exclude: ["**/node_modules/**"]
        languages: [ts, tsx]
      backend:
        path: /path/to/your/backend
        include: ["app/**", "tests/**"]
        languages: [py]

repos names (frontend, backend) are yours to pick — you will use them when indexing. Use conventions: englora instead of generic if you want strict note contracts enforced (see Vault profiles).

3. Connect it to your assistant

Create a .mcp.json in each repo you work from:

{
  "mcpServers": {
    "obsidian": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/obsidian-local-mcp", "obsidian-local-mcp"],
      "env": {
        "OBSIDIAN_MCP_CONFIG": "/path/to/your/vaults.yaml",
        "OBSIDIAN_MCP_VAULT": "main"
      }
    }
  }
}

Restart your assistant. In Claude Code, /mcp should now list obsidian.

4. Build the graph (once)

Just ask your assistant, in plain language:

"index the frontend and backend repos, then index the git co-edits"

Or, if you prefer to know what it runs under the hood:

index_repo(repo="frontend")
index_repo(repo="backend")
index_git_coedits(repo="frontend")
index_git_coedits(repo="backend")

Then ask for graph_stats() to confirm. A few thousand nodes for a mid-sized repo is normal. This takes seconds, not minutes.

The CLI

One command, three subcommands. Run them from this repo with uv run.

uv run obsidian-local-mcp-setup           # set up your vault (and optionally the model)
uv run obsidian-local-mcp-setup serve     # run the decision model, if you installed one
uv run obsidian-local-mcp-setup doctor    # check everything and print the triage latency

doctor is the one to run when something looks wrong — it checks the config, your vaults, whether the graph is built and whether the model answers, and says what to do about anything it finds.

To set up without the questions:

uv run obsidian-local-mcp-setup install --vault ~/notes --no-model --force

Config lives at ~/.obsidian-local-mcp/vaults.yaml and the model in ~/.obsidian-local-mcp/kev-env/. OBSIDIAN_MCP_CONFIG and OBSIDIAN_MCP_HOME move them.

The decision model (optional)

Skip this unless you have a GPU or Apple Silicon.

retrieve_context ranks candidates by how your code is wired together, which cannot tell that a well-connected file is irrelevant to the question you asked. Your assistant finds that out by opening them — and every one that did not matter is now in its context for good.

triage_candidates(query) runs the same search, then asks Kev, a small model running on your machine, which candidates are worth reading. You get those in full and the rest as one-line stubs.

uv run obsidian-local-mcp-setup install --model 0.8b   # once
uv run obsidian-local-mcp-setup serve                  # leave running
uv run obsidian-local-mcp-setup doctor                 # check the latency

Tune it in vaults.yaml under kev: (enabled, base_url, timeout_ms, threshold, max_candidates — see vaults.example.yaml).

It cannot break anything. If the model is down, slow or disabled, triage_candidates returns every candidate with triaged: false and a reason — exactly what retrieve_context would have given you. Never an error. So it is safe to leave configured, and safe to kill serve.

But check the latency. Triage has to cost less than the reading it saves. We measured kev-4b scoring 15 candidates on a CPU with no GPU: ~73 seconds. Unusable — it would just time out and fail open every time. 0.8b is ~5x smaller and still probably too slow. Without a GPU, leave it off and use retrieve_context.

The judgement itself is good, which was the part in doubt: on a Spanish query against Spanish notes, kev-4b kept exactly the five candidates that mattered and dropped eight structural neighbours and an unrelated billing module at 0.00–0.07.

Using it day to day

You do not call these tools yourself. You work exactly as you always did — the assistant decides when to reach for the graph, because every tool describes when it should be used.

You:  "why does the newsletter send the wrong level sometimes?"
      → assistant calls retrieve_context, reads your notes, then the code

Three things worth knowing:

Ask it to use the graph when it forgets. A nudge works ("check the graph first"). To make it permanent, put one line in your CLAUDE.md:

Before using Grep/Glob to understand code or relationships, call retrieve_context first. Grep is only for locating a known literal string.

Reindex after you move things. Adding, deleting, renaming files or changing imports makes the graph drift. A stale map is worse than no map:

"reindex the files I just changed" → reindex_paths(repo, paths=[...])

Let it write notes. When you explain something non-obvious ("we cap it at 540s because Cloud Run was OOMing"), tell it to save that:

"write that down in the vault" → write_note(...)

That note is what shows up in KNOWLEDGE next month, long after you and the assistant have both forgotten the conversation.

Searching well

Seeding is lexical (SQLite FTS5 + bm25), not semantic. So queries work best with few, distinctive words:

If the buckets come back unrelated to what you asked, retry with fewer and rarer words (a file name, a feature name, a symbol).

The two kinds of data

This distinction matters, and it is the one thing to get right:

For a note to surface as KNOWLEDGE when someone touches a file, it needs a documents edge pointing at that file:

upsert_edge(src="feature:daily-podcast", dst="file:back/app/podcast.py", type="documents")

Without that edge the note only appears when your query happens to match its text. With it, the note appears whenever that file is in play — which is the whole point.

Troubleshooting

Changed the server's code and nothing happened. The running process still has the old code loaded. Restart the MCP server (in Claude Code: restart the session, or reconnect via /mcp).

KNOWLEDGE is always empty. Your notes probably have no documents edges yet. See The two kinds of data.

Results point at files that no longer exist. The graph drifted. Run detect_divergence() to see what broke, then reindex_paths or a full index_repo.

A note says something that is no longer true. Notes carry status and confidence in their frontmatter. status: "assumed" means a past session inferred it without verifying — always confirm against the code before trusting it. consolidation_report() lists stale and orphaned notes.

Nothing gets indexed. Only git-tracked files are scanned. Check your include/exclude globs and that the files are actually committed.

Anything looks wrong. Run obsidian-local-mcp-setup doctor first. It checks the config, your vaults, the graph and the model, and says what to do about whatever it finds.

triage_candidates always says triaged: false. The model is not answering; the reason field says why. Your results are unaffected — kept holds every candidate.

Vault profiles

Set per-vault with conventions::

• generic — no rules. Notes are plain markdown; write whatever you want. Good for a personal wiki.

• englora — enforces a note contract (id, type, area, status, confidence, source, created, updated, decay, supersedes, links) and refuses to mark inferred claims as verified. Good when you want the assistant held to a standard.

Multiple vaults can be configured at once; OBSIDIAN_MCP_VAULT picks the default per repo, and every tool takes an optional vault= argument.

Internals

Everything below is for working on this server rather than with it.

Architecture

src/obsidian_local_mcp/
├── server.py            FastMCP instance + all tools (thin: validate → call → model)
├── instructions.py       server-level instructions handed to the connecting assistant
├── config.py              vaults.yaml → Config/VaultConfig/RepoConfig/KevConfig
├── models.py               pydantic request/response types for every tool
├── setup_cli.py             the obsidian-local-mcp-setup command (install/serve/doctor)
├── triage/
│   ├── client.py            stdlib-only HTTP client for the Kev sidecar
│   └── candidates.py         RetrievalResult → one Kev request → keep/drop verdicts
├── graph/
│   ├── store.py           SQLite (<vault>/.graph/graph.db): nodes, edges, FTS5
│   ├── ids.py               file:<repo>/<path>, fn:<repo>/<path>#<symbol>, feature:, ext:, note:
│   ├── weights.py            edge-type weight / reverse-factor / origin table
│   └── retrieve.py            seed_fts() + personalized_pagerank() + classify()
├── index/
│   ├── scan.py             repo file listing (git ls-files) + parser dispatch + test-edge derivation
│   ├── python_parser.py      ast: contains/call/import, two-pass (forward refs resolve)
│   ├── ts_parser.py           tree-sitter: contains/call/import + JSX-usage-as-call
│   └── git_coedit.py         co_edit edges from `git log --name-only`
└── vault/
    ├── conventions.py       vault "profiles": englora (strict) vs generic (unenforced)
    ├── notes.py               frontmatter read/write, wikilink-tolerant YAML, secret guard
    └── maintenance.py         decay/orphan/divergence reports, additive sync_note_links

The origin rule

Every node/edge carries origin: scanner | git | manual. Reindexing only ever rewrites rows it owns:

• index_repo/reindex_paths delete+rewrite scanner-origin rows for the paths touched, then purge any scanner-origin edge left dangling.

• index_git_coedits delete+rewrite git-origin edges for the repo.

• manual-origin rows (written by upsert_node/upsert_edge — curated feature:/ext: nodes, depends_on/documents/decided_by/dangerous edges) are never touched by either indexer.

This is what lets an assistant curate knowledge on top of a graph that gets mechanically rebuilt.

Retrieval

retrieve_context(query): FTS5 bm25 over node id/label/path/curated-note body seeds a personalized-PageRank walk (restart α=0.15, both edge directions at their type's weight/reverse_factor). The ranked result is then classified into MUST_READ / MAY_CHANGE / MUST_TEST / KNOWLEDGE / DANGER by walking the same edges. impact_of(node_id) runs the same classification anchored on one explicit node instead of a query.

documents/decided_by edges run note → code, so the note explaining an anchor is reached by walking into the anchor (by_dst), not out of it. Those notes are surfaced even with no lexical hit of their own — curated prose exists precisely for the queries whose wording does not match it.

No embeddings by default — seed_fts() is the one seam where a vector search could be substituted later without touching the ranking/ classification code.

Triage

retrieve_context ranks by topology. Topology cannot tell that a well-connected file is irrelevant to this particular question, so the assistant settles that by opening the candidates — and every one that turns out not to matter has already been paid for and is in its context for good.

triage_candidates(query) runs the same search, then asks Kev — a small local decision model — which candidates are worth reading. Kev is a pointer model: one state plus N typed questions go in, one prefill pass runs, and the answers are read off the logits. Nothing is generated. Questions share the state's activations and cannot see each other, so 25 candidates cost about what one costs and no candidate's verdict is dragged around by its neighbours'.

Consequences that shaped the code, all in triage/candidates.py:

• One Noul per candidate, never one big Choice. Choice options are read in order and the ranking moves when you permute them; independent yes/no questions have no order to be biased by, and they let several candidates be essential at once.

• must_read is never dropped. The graph put it there off the query's own seeds; a model wrong on that one would hide the file you came for.

• A missing or malformed answer keeps the candidate. Silence must not be indistinguishable from rejection.

• Fail-open, always. Kev down, slow, disabled or throwing returns every candidate with triaged: false and a reason. A filter that can hide results is never allowed to be the reason a lookup fails.

Kev is reached over HTTP and never imported: it needs torch and a multi-GB checkpoint, and this server is loaded by a stdio client that would otherwise wait on that at every start. That is why the sidecar lives in its own virtualenv and why setup_cli.py exists at all.

The user-facing half — installing it, running it, configuring it, and the measured latency that decides whether it is worth running — is in The decision model.

Tools

Graph write: upsert_node[s], upsert_edge[s], delete_node, delete_edge, rename_node, set_node_status.

Graph read: get_node, neighbors, search_nodes, retrieve_context, triage_candidates, impact_of, path_between, graph_stats.

Indexing: index_repo, reindex_paths, index_git_coedits, detect_divergence, clear_graph (requires confirm=True).

Vault notes: read_note, write_note, update_note_frontmatter, promote_node_to_note (scaffold graph nodes into vault notes), list_notes, search_vault, archive_note.

Maintenance: consolidation_report, sync_note_links, get_status.

Tests

uv run pytest

All 116 tests pass (one skips unless kev is importable). Key fixtures:

• tests/fixtures/mini_repo/ — a small backend (5 Python files) that reproduces a complete indexing workflow: index_repo → index_git_coedits → retrieve_context.

• tests/fixtures/mini_vault/ — a minimal vault used to test note read/write, frontmatter validation, and promote_node_to_note.

• Dynamic mini_repo_git fixture — builds a throwaway git repo with two commits to test co-edit detection.