memex-md-mcp 0.2.4

MCP server for semantic search over markdown vaults

You like Obsidian? Your LLM will love it too.

memex-md-mcp (WIP!)

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 and logs to ~/.local/share/memex-md-mcp/memex.log. The index contains:

• 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.

Note: Initial indexing of large vaults can take several minutes (embedding computation). Subsequent queries only re-index changed files and are fast.

Hidden directories (.obsidian, .trash, .git, etc.) are excluded from indexing.

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

Configuration

Add to ~/.claude/mcp.json (global) or .mcp.json (per-project):

{
  "mcpServers": {
    "memex": {
      "command": "uvx",
      "args": ["memex-md-mcp@latest"],
      "env": {
        "MEMEX_VAULTS": "/home/user/knowledge:/home/user/project/docs"
      }
    }
  }
}

Multiple vault paths are colon-separated. Project .mcp.json overrides global config entirely (no merging), so list all vaults you need.

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.

TODO replace slop workflow example with my actual workflow:

Example Workflow

Template for integrating memex into your project's CLAUDE.md instructions:

## Knowledge Base (memex MCP)

This project uses memex for persistent knowledge across sessions. The vault contains architecture decisions, debugging learnings, and context that survives agent handovers.

### When to Search

Before starting significant work, search for relevant prior knowledge:

- search("authentication patterns") - architecture decisions
- search("docker networking issues") - past debugging learnings
- search("gradient descent variants") - conceptual knowledge

The search uses both keywords AND semantic similarity, so you don't need exact note names.

If you find a relevant note, use explore() to see its neighborhood - what links to it, what it links to, and semantically similar notes.

### Handover Workflow

Plan files are your working memory that survives context exhaustion.

**During work:**
1. Create/update plan file continuously as you work
2. Capture: current state, decisions made, next steps, dead ends
3. The plan file should always reflect "where am I right now"

**When context runs low:**
1. Your plan file already has everything important (you've been updating it)
2. No panic - the next agent reads plan + searches vault and continues

**After feature completion:**
1. Distill learnings: What worked? What didn't? What should future agents know?
2. Update vault with permanent knowledge
3. Plan files can be archived or deleted - they're ephemeral

### What Goes Where

- **Current task state, decisions, next steps** → Plan file (ephemeral)
- **Code conventions, project-specific rules** → CLAUDE.md
- **Architecture decisions, patterns, tech debt** → Architecture doc in vault
- **Debugging learnings, gotchas** → Notes in vault
- **General knowledge about tools/libraries** → Notes in vault  

### Note Writing Guidelines

- **Atomic notes**: One concept per note when possible
- **Descriptive titles**: `runpod-cli-gotchas.md` not `notes-2024-12.md`
- **Update over duplicate**: Search first, update existing notes rather than creating duplicates
- **Link related notes**: Use [[wikilinks]] to connect related concepts

Development

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