You like Obsidian? Your LLM will love it too.

# memex-md-mcp

MCP server for semantic search over markdown vaults. Hybrid FTS5 + embeddings search, wikilink graph traversal, and YAML frontmatter awareness (aliases, tags).

## Quick Start

```bash
claude mcp add memex uvx memex-md-mcp@latest
```

Then ask Claude to help configure your vaults - it has `mcp_info()` which explains everything. Or manually edit your settings (see Configuration below).

## What This Does

Memex gives Claude read access to your markdown vaults. It creates a local index at `~/.local/share/memex-md-mcp/memex.db` containing:

- Full-text search index (FTS5) for keyword matching
- Embeddings (google/embeddinggemma-300m) for semantic similarity
- Wikilink graph for backlink queries
- Extracted frontmatter (aliases, tags)

On each query, memex checks file mtimes and re-indexes any changed files. First run on a large vault takes time to compute embeddings.

Writing to notes happens through Claude Code's normal file tools. 

## Configuration

### Global vault (always available)

In `~/.claude/settings.json`:

```json
{
  "env": {
    "OBSIDIAN_VAULTS": "/home/user/obsidian/knowledge"
  },
  "mcpServers": {
    "memex": {
      "command": "uvx",
      "args": ["memex-md-mcp@latest"]
    }
  }
}
```

### Adding project-specific vaults

In your project's `.mcp.json`, use variable expansion to append to global vaults:

```json
{
  "mcpServers": {
    "memex": {
      "command": "uvx",
      "args": ["memex-md-mcp@latest"],
      "env": {
        "OBSIDIAN_VAULTS": "${OBSIDIAN_VAULTS}:/home/user/projects/myproject/docs"
      }
    }
  }
}
```

This keeps your global vault active while adding project-specific ones.

## Tools

**search(query, vault?, limit=5, concise=False)** finds notes using hybrid search. Works when you don't know exact note names.

```
search("terraform state locking issues")
search("architecture decisions for the auth system", vault="work")
search("preferences for error handling in this codebase")
```

**explore(note_path, vault, concise=False)** shows a note's neighborhood: outlinks (what it references), backlinks (what references it), and semantically similar notes that aren't yet linked.

```
explore("architecture/api-design.md", "work")
```

**mcp_info()** returns this README plus an example workflow.

## Example Workflow

See `examples/claude-md-workflow.md` for a template showing how to integrate memex with handover files and knowledge distillation.

## Development

```bash
uv sync
make check   # ruff + ty
make test    # pytest
```
