---
name: code-memory-router
description: "Routes memory and retrieval tasks between MemPalace and QMD. Use this skill whenever the user asks WHERE something is in the codebase (route to QMD), WHY something was built a certain way or what was decided (route to MemPalace), or needs BOTH code and historical context (combined). Trigger on phrases like: 'where is X', 'find X in the code', 'search the codebase for X', 'what did we decide about X', 'why does X work this way', 'show me X and why we built it', 'look up X', 'what's in the handoffs about X', 'pull the relevant files for X'. Use proactively whenever a question could benefit from codebase search OR project memory — don't wait for the user to explicitly ask for a search."
---

# 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)

```bash
# 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):
```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):
```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:
```bash
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

```bash
# 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`