memory_mcp: Instructions file for Claude Code

Memory MCP

Persistent memory and session search for AI coding assistants, exposed as an MCP server.

What this is

A Python MCP server that:

1. Indexes session history from Claude Code (~/.claude/projects/) and OMP (~/.omp/agent/sessions/)
2. Provides full-text search across all historical sessions via SQLite FTS5
3. Offers explicit save_memory/search_memory tools for cross-session knowledge persistence

No Flask, no Postgres, no file watchers. SQLite handles everything. The MCP SDK handles transport.

Architecture

memory_mcp/
  server.py              # FastMCP entry point, lifespan yields fast then runs scan in background
  readiness.py           # Lazy embedder + scan/backfill coordination (v0.3.0)
  config.py              # Auto-detects session dirs, DB path (~/.memory_mcp/memory.db)
  db.py                  # SQLite + FTS5 + sqlite-vec schema, all query functions
  embeddings.py          # Lazy fastembed wrapper (BAAI/bge-small-en-v1.5)
  scanner.py             # Walks session dirs, dispatches to parsers, indexes into DB
  parsers/
    base.py              # ParsedSession / ParsedMessage dataclasses, SessionParser protocol
    claude_code.py       # Claude Code JSONL parser (merges streamed assistant blocks)
    omp.py               # OMP JSONL parser
  tools/
    memory.py            # save_memory, search_memory, list_memories, delete_memory
    sessions.py          # list_sessions, get_session, search_sessions, refresh_sessions

Startup contract (v0.3.0)

This is a hard contract. Breaking it causes MCP clients (Claude Code, Codex, VS Code) to silently miss the server's tools on startup, the bug that motivated v0.3.0.

Rule: lifespan MUST yield in <500ms on every cold boot. Anything that blocks longer than that goes in a background task started after yield.

What this means in practice:

• server.py:lifespan does only init_db() + ReadinessState.new() + init_readiness(state) + asyncio.create_task(_background_startup(...)) before yielding. Do not add anything else pre-yield.
• The embedding model is never loaded pre-yield. The background startup task warm-starts it (readiness.warm_start_semantic) right after the initial scan, so it's usually ready before the user's first prompt. If a semantic call races the warm-start, ensure_semantic_ready() loads the model on demand — but it must never wait for scan or backfill completion; semantic queries search whatever vectors exist and backfill catches up in the background. Blocking on backfill is what caused the 30s MCP client timeouts fixed in v0.5.0.
• save_memory uses readiness.get_embedder_if_ready() — opportunistic embedding only. It never triggers a cold load. Backfill embeds any rows saved before the model was up.
• The initial session scan runs in a background task, not in lifespan. Tools work as soon as MCP is ready.
• All scan/backfill work runs in worker threads via asyncio.to_thread. SQLite connections are thread-bound, so worker threads always open their own connection via init_db(). Never pass the lifespan connection into to_thread.
• Scan + backfill are serialised via state.maintenance_lock to prevent concurrent writers and to keep semantic results consistent.
• embeddings.py does not import fastembed at module top. The import lives inside Embedder.__init__. Probe availability with importlib.util.find_spec("fastembed") instead.