memory-router

Memory Router — Team Unified Knowledge Retrieval Skill

• Author: Daniel Li
• Copyright © Daniel Li. All rights reserved.

Purpose

All team agents (小a/ops/code/quant/data/finance/research/market/pm/content/law) MUST route knowledge retrieval through this standardized pipeline before answering questions about:

• 系统配置、架构、部署
• 历史决策、TODO、进度
• Skill 用法与触发条件
• 项目状态与交付件
• 人物、日期、数字

QMD Feature Map (all features agents should use)

Feature	Command	When to Use
Hybrid search	qmd query "<question>"	DEFAULT: combines BM25 + vector + rerank. Best for most queries
Structured query	qmd query $'lex: keyword\nvec: semantic'	When you need precise keyword AND semantic results
BM25 keyword	qmd search "<exact term>"	Exact term/filename/config key lookup
Vector similarity	qmd vsearch "<concept>"	Conceptual/fuzzy similarity (e.g., "how to deploy")
Get document	qmd get path/to/file.md:42 -l 30	Read specific lines after search identifies a file
Multi-get	qmd multi-get "reports/*.md"	Batch fetch multiple files (e.g., all reports)
Collection filter	qmd query -c skills "<question>"	Restrict search to one collection for precision
Full output	qmd query --full "<question>"	Get complete document content instead of snippets
JSON output	qmd query --json "<question>"	Machine-readable output for scripts
List files	qmd ls skills	Browse what's indexed in a collection
Status	qmd status	Health check: pending embeds, collection sizes
Update index	qmd update	Re-index after file changes
Embed vectors	qmd embed	Generate embeddings for new/changed files
Context notes	qmd context list	View collection descriptions/usage hints
MCP server	qmd mcp	Expose as MCP tool for IDE/agent integration

Collections (current)

Collection	Content	Use For
clawd-memory	~/clawd/**/*.md (1603 files)	Memory, docs, reports, runbooks
daily-memory	~/clawd/memory/*.md (44 files)	Daily work logs
team	~/.openclaw/agents/**/*.json (860 files)	Agent configs, models, auth
openclaw-config	~/.openclaw/**/*.json (1031 files)	OpenClaw system config
projects	~/clawd/projects/**/*.md (100 files)	Project PRDs, deliverables
skills	~/clawd/skills/**/SKILL.md (468 files)	All skill documentation
reports	~/clawd/reports/*.md (2 files)	Research & review reports

Routing Algorithm

Input: user question Q

Step 1 — CLASSIFY
  A = "prior decisions / todos / people / dates / what happened"
  B = "system config / how-to / skill usage / architecture"
  C = "project status / deliverables / PRD"
  D = "external facts / live data" (falls through to web)

Step 2 — RETRIEVE (execute ALL applicable, not just one)

  if A:
    → qmd query -c daily-memory "<Q>" -n 5
    → qmd query -c clawd-memory "<Q>" -n 5
    → Also check ~/clawd/MEMORY.md directly for TODOs/decisions

  if B:
    → qmd query -c openclaw-config "<Q>" -n 5
    → qmd query -c skills "<Q>" -n 5
    → qmd query -c clawd-memory "<Q>" -n 3  (for runbooks/docs)

  if C:
    → qmd query -c projects "<Q>" -n 5
    → qmd query -c reports "<Q>" -n 3

  if D:
    → qmd query "<Q>" -n 5  (all collections, no filter)
    → If low recall → web_fetch / browser

Step 3 — CITE
  Every answer MUST include 1-3 source citations:
  - File path: `~/clawd/docs/memory-router.md:15`
  - QMD URI: `qmd://skills/geo-agent/SKILL.md`
  - Or: "Source: qmd query -c projects 'content factory status'"

Agent Integration (mandatory AGENTS.md section)

Each agent's AGENTS.md must contain:

## 知识库 / Memory Router（强制）

- 你在回答任何「配置/流程/历史/怎么做」类问题前，**必须先检索本地知识库**：
  1) 优先 QMD：`qmd query "<问题>"`（必要时加 `--collection openclaw-config|projects|skills|reports|clawd-memory`）
  2) 涉及待办/决策/人/日期 → 再查工作区记忆文件（`~/clawd/memory/YYYY-MM-DD.md` 与 `~/clawd/MEMORY.md`）
- 输出时至少引用 1-3 个来源（文件路径或 `qmd://...` URI）。

Health Monitoring

Daily Cron (recommended)

# qmd-health: run daily at 08:00
qmd status | grep -E "Total|Vectors|Pending|Updated"
qmd update

Weekly Embed Refresh

# qmd-embed: run weekly Sunday 03:00
qmd embed
qmd status

Health Metrics to Track

• 覆盖率: Vectors / Total (target: >90%)
• Pending: should be <100 after weekly embed
• Collection freshness: Updated timestamps should be <24h for active collections
• Query latency: hybrid query should return <2s

Troubleshooting

Problem	Solution
qmd embed hangs	Check if node-llama-cpp is compiling (first run). Wait ~10min.
CUDA errors	Normal on CPU-only servers. QMD auto-falls back to CPU.
Ollama not found	QMD uses node-llama-cpp, NOT Ollama. Ignore Ollama references.
Low recall	Try --full flag, or use qmd search (BM25) for exact terms
Missing files	Run qmd update to re-index, then qmd embed for new vectors

Script: memory_router.sh

For automated context injection into agent prompts:

#!/bin/bash
# Usage: ./memory_router.sh "question" [collection]
QUERY="$1"
COLLECTION="${2:-}"

if [ -n "$COLLECTION" ]; then
  qmd query -c "$COLLECTION" "$QUERY" -n 5 --line-numbers
else
  qmd query "$QUERY" -n 5 --line-numbers
fi

---

Last updated: 2026-03-03 Maintainer: 小a (CEO)