# code-memory-router

![code-memory-router banner](banner.png)

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](https://github.com/tobil/qmd) — codebase indexer with hybrid search
- [MemPalace](https://github.com/mempalace/mempalace) — persistent AI memory

Both must be installed and indexed. See [references/setup-guide.md](references/setup-guide.md).

## Install

**Universal (works with Claude Code, Cursor, Codex, Gemini CLI, and 40+ agents):**
```bash
npx skills add OthmanAdi/code-memory-router
```

Or from npm: `pi install npm:code-memory-router` ([package](https://www.npmjs.com/package/code-memory-router))

**Claude Code only:**
```bash
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