code-memory-router

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)

# 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