omega-obsidian

Persistent semantic memory for Obsidian vaults. Your coding agent remembers what it learned from your notes.

License: Apache-2.0 Python 3.11+

Why omega-obsidian?

Existing Obsidian MCP servers let agents read your files. omega-obsidian lets agents remember what they learned from your vault, across sessions, with semantic search.

The difference:

Feature	File-based MCP servers	omega-obsidian
Read notes	Yes	Yes
Search by filename	Yes	Yes
Semantic search (search by meaning)	No	Yes
Persistent index (instant startup after first run)	No	Yes
Incremental updates (only re-indexes changed files)	No	Yes
Write back (agent stores memories into your vault)	No	Yes
Knowledge graph (backlinks, wikilinks, shared tags)	No	Yes

Install

pip install omega-obsidian

For higher-quality embeddings (bge-small-en-v1.5 via ONNX), install with the OMEGA engine:

pip install omega-obsidian[omega]

Without [omega], the server uses a built-in TF-IDF fallback that requires no extra dependencies.

MCP Configuration

Claude Code

Add to your Claude Code MCP settings (~/.claude.json or project .claude/settings.json):

{
  "mcpServers": {
    "omega-obsidian": {
      "command": "omega-obsidian",
      "args": ["--vault-path", "/path/to/your/obsidian/vault"],
      "env": {}
    }
  }
}

Or use an environment variable instead of --vault-path:

{
  "mcpServers": {
    "omega-obsidian": {
      "command": "omega-obsidian",
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "omega-obsidian": {
      "command": "omega-obsidian",
      "args": ["--vault-path", "/path/to/your/obsidian/vault"]
    }
  }
}

Windsurf

Add to your Windsurf MCP config:

{
  "mcpServers": {
    "omega-obsidian": {
      "command": "omega-obsidian",
      "args": ["--vault-path", "/path/to/your/obsidian/vault"]
    }
  }
}

Tools

omega-obsidian exposes 6 MCP tools:

vault_search

Semantic search across all indexed vault notes. Returns matches ranked by relevance with scores and content snippets.

query: "authentication flow design"
limit: 5

vault_read

Read a specific note by its vault-relative path. Returns the full content with parsed frontmatter, tags, and wikilinks.

path: "Projects/auth-redesign.md"

vault_remember

Store a new memory or note into the vault from agent context. Creates a markdown file with frontmatter and indexes it immediately.

title: "Auth API Decision"
content: "We decided to use JWT with refresh tokens..."
tags: ["architecture", "auth"]
folder: "Decisions"

vault_graph

Get notes related to a given note via backlinks, wikilinks, and shared tags. Useful for exploring connections in your knowledge base.

path: "Projects/auth-redesign.md"

vault_index

Reindex the entire vault. Rebuilds embeddings for all files. Run this after making bulk changes to the vault outside the agent.

vault_recent

Get recently modified notes, sorted by modification time (newest first).

limit: 10

How It Works

1. First startup: omega-obsidian walks your Obsidian vault, parses every .md file (extracting frontmatter, wikilinks, and tags), generates semantic embeddings, and stores everything in a local SQLite database at ~/.omega-obsidian/index.db.

2. Subsequent startups: Only new or modified files are re-indexed (incremental). The index persists across sessions, so startup is fast.

3. Semantic search: When you search, the query is embedded using the same model and compared against all note embeddings via cosine similarity. This finds notes by meaning, not just keyword matching.

4. Knowledge graph: Wikilinks ([[note]]) and tags (#tag) are parsed and stored, enabling graph traversal to find related notes.

5. Write-back: The vault_remember tool creates real Obsidian-compatible markdown files in your vault with proper frontmatter, so your agent's memories become part of your knowledge base.

Embedding Backends

omega-obsidian supports two embedding backends:

• OMEGA engine (recommended): Uses bge-small-en-v1.5 via ONNX for high-quality 384-dimensional embeddings. Install with pip install omega-obsidian[omega].
• TF-IDF fallback: A built-in hashed TF-IDF embedder that requires no extra dependencies. Lower quality but works everywhere.

The server auto-detects which backend is available and uses the best one.

Configuration

Setting	CLI Flag	Environment Variable	Default
Vault path	--vault-path	OBSIDIAN_VAULT_PATH	(required)
Database path	--db-path	OBSIDIAN_DB_PATH	~/.omega-obsidian/index.db
Excluded folders	-	OBSIDIAN_EXCLUDED_FOLDERS	.obsidian,.trash
Verbose logging	--verbose / -v	-	off

Powered by OMEGA

omega-obsidian uses the embedding engine from OMEGA, persistent memory for AI coding agents. If you need full agent memory (not just Obsidian vault search), check out OMEGA.