<!-- mcp-name: io.github.omega-memory/omega-obsidian -->

# omega-obsidian

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

[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)

## 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

```bash
pip install omega-obsidian
```

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

```bash
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`):

```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`:

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

### Cursor

Add to `.cursor/mcp.json`:

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

### Windsurf

Add to your Windsurf MCP config:

```json
{
  "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](https://github.com/omega-memory/omega-memory), persistent memory for AI coding agents. If you need full agent memory (not just Obsidian vault search), check out OMEGA.