memex-md-mcp 0.2.0

MCP server for semantic search over markdown vaults

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

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:

{
  "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:

{
  "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

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