Code Memory Router

Routes requests between MemPalace (project memory) and QMD (codebase search).

Two tools. Different jobs. Not interchangeable.

Read references/tool_selection.md for routing examples and edge cases.

What each tool does

QMD — indexes your codebase and docs. Hybrid BM25 + semantic search. Finds where things live in code.

MemPalace — persistent project memory. Stores past decisions, handoffs, architectural rationale, mission history. Answers why things exist.

Discover your setup (first time or if unsure)

# See what QMD collections exist
qmd collection list

# See what MemPalace wings/rooms exist
python -m mempalace status

Use these to confirm collection and wing names before searching.

Routing Decision

Choose QMD when the question is about:

• Where a function, symbol, or pattern lives in code
• How something is implemented right now
• Finding files matching a concept or term
• "Where is X defined / called / used?"

Choose MemPalace when the question is about:

• Why something was built a certain way
• What was decided in a previous session
• What's in the handoffs, planning docs, or architecture research
• "What did we decide about X?" / "Why does X work this way?"

Choose combined when the question needs both:

• "Show me X AND explain why it was built that way"
• Pattern A — code-first: QMD first → MemPalace for rationale
• Pattern B — history-first: MemPalace first → QMD to verify current state

Always state the routing decision before executing:

Dominant need: [code search / memory recall / mixed] → [QMD / MemPalace / combined]

QMD Execution

MCP tools (use if mcp__qmd__* appears in active tool list):

• mcp__qmd__query — hybrid semantic+BM25 search ← primary
• mcp__qmd__get — fetch a specific file by path

CLI fallback (always works via Bash):

# Hybrid search — best results for natural language questions
qmd query "your question here"

# Keyword/BM25 — fast, good for exact symbols or filenames
qmd search "exact term"

# Fetch a specific file
qmd get "qmd://<collection-name>/path/to/file.rs"

# Batch fetch by glob pattern
qmd multi-get "<collection-name>/src/api/*.rs"

Structured query syntax (for precise control):

intent: what you're looking for
lex: exact symbol or term
vec: natural language description

MemPalace Execution

MCP tools (use if mcp__mempalace__* appears in active tool list):

• mcp__mempalace__search — semantic search over palace ← primary
• mcp__mempalace__status — show wing/room overview

CLI fallback (always works via Bash):

# On Windows
PYTHONUTF8=1 python -m mempalace search "your query"

# Or with explicit venv path if needed
PYTHONUTF8=1 "<path-to-mempalace-venv>/Scripts/python.exe" -m mempalace search "your query"

Optional: auto-detect which tool has the data

Run if you're unsure whether the answer is in QMD or MemPalace:

python "<skill-dir>/scripts/inspect_embedding_metadata.py" <repo-root>

This scans CLAUDE.md, MEMORY.md, qmd configs, and mempalace configs for embedding metadata and returns a routing recommendation.

Maintenance

# Re-index QMD after new commits
qmd update && qmd embed -f

# Re-mine MemPalace after new handoffs or planning docs
python -m mempalace mine <docs-dir> --wing <your-wing-name>

Config locations:

• QMD: ~/.config/qmd/index.yml
• MemPalace palace: ~/.mempalace/palace