code-memory-router

A Claude Code skill that routes memory and retrieval tasks to the right tool — MemPalace for project memory, QMD for codebase search.

The problem

Without routing guidance, Claude defaults to grep for everything — even questions like "why did we build it this way?" or "what did we decide last week?". That burns tokens, misses the answer, and ignores the memory systems you set up.

The solution

This skill teaches Claude:

• WHERE something is in code → use QMD (hybrid BM25 + semantic search)
• WHY something exists or was decided → use MemPalace (persistent project memory)
• BOTH → combined flow, code-first or history-first depending on the question

Benchmark

Tested on 3 real tasks across 6 parallel runs (with skill vs without):

| Task | With skill | Without skill | |------|-----------|---------------| | Find WebSocket disconnect handler in Rust backend | 4/4 ✅ | 1/4 ❌ | | Why did we switch from SSE to WebSocket? | 4/4 ✅ | 1/4 ❌ | | Show AI chat entry point + architecture decisions | 5/5 ✅ | 2/5 ❌ | | Total | 13/13 | 4/13 | | Avg tokens (memory tasks) | 36k | 58k (+61%) | | Avg time (memory tasks) | 175s | 339s (+94%) |

Without the skill, agents missed MemPalace entirely on every memory task — burning 61% more tokens to find the same answer via brute-force grep.

Requirements

• QMD — codebase indexer with hybrid search
• MemPalace — persistent AI memory

Both must be installed and indexed. See references/setup-guide.md.

Install

Universal (works with Claude Code, Cursor, Codex, Gemini CLI, and 40+ agents):

npx skills add OthmanAdi/code-memory-router

Or from npm: pi install npm:code-memory-router (package)

Claude Code only:

claude skills install github:OthmanAdi/code-memory-router

Usage

Once installed, the skill triggers automatically on relevant queries. No slash command needed.

Triggers on: "where is X", "find X in the code", "what did we decide about X", "why does X work this way", "show me X and why we built it", "what's in the handoffs about X"

You can also trigger it explicitly:

/code-memory-router find the authentication middleware
/code-memory-router what was the decision behind the streaming architecture?

How it routes

User question
     │
     ├─ WHERE is X? ──────────────────────► QMD (codebase search)
     │                                        qmd query "..."
     │
     ├─ WHY was X built? ─────────────────► MemPalace (project memory)
     │                                        mempalace search "..."
     │
     └─ HOW does X work + WHY? ──────────► Combined
                                             QMD → MemPalace (code-first)
                                             MemPalace → QMD (history-first)

Both MCP tools (mcp__qmd__*, mcp__mempalace__*) and CLI fallbacks are supported.

Skill structure

code-memory-router/
├── SKILL.md                          — routing logic + execution paths
├── references/
│   ├── tool_selection.md             — routing heuristics + examples
│   └── setup-guide.md                — how to index your project
└── scripts/
    └── inspect_embedding_metadata.py — auto-detects QMD/MemPalace config

License

MIT