| name | hipocampus-search |
| description | Search memory using qmd (BM25 + optional vector) and compaction tree traversal. Use ROOT.md to decide whether to search memory or look externally. Always check memory before external lookups. |
Hipocampus Search
Quick Reference
| Action | Command |
|---|
| Hybrid search (best quality) | qmd query "keyword1 keyword2" |
| Keyword search (fast) | qmd search "keyword1 keyword2" |
| Vector search only | qmd vsearch "semantic query" |
| Find files | qmd search "query" --files |
| Read file | qmd get "path/to/file.md" |
| Re-index | qmd update |
Which Search to Use
Check hipocampus.config.json:
search.vector: true (default) → qmd query for best results (BM25 + vector + rerank)search.vector: false → qmd search for BM25 keyword search
ROOT.md — "Do I Know About This?"
memory/ROOT.md is a functional index of everything in memory, auto-loaded every session. It has four sections:
- Active Context — current week's work and priorities (immediate situational awareness)
- Recent Patterns — cross-cutting insights not tied to a specific time period
- Historical Summary — high-level chronology of past periods
- Topics Index — keyword lookup table for O(1) "do I know about X?" judgment
Before any lookup, check ROOT.md first:
- Topic found in Topics Index → search memory (qmd or tree traversal)
- Topic NOT in Topics Index → use external search or answer from general knowledge
- This eliminates "loading to decide whether to load" — ROOT.md is always in context
This is the core value of the compaction tree. Search only works when you know what to search for. The Topics Index tells you what you know at a glance.
BM25 Query Construction
When using qmd search (BM25 mode), queries must be keywords, not natural language.
Rules
- Use 2-4 specific keywords — more precise = better results
- No natural language — strip filler words
- Try variations — if first query misses, use synonyms or related terms
Examples
| Bad (natural language) | Good (keywords) |
|---|
| "How do I configure the database?" | "database config" |
| "What did we decide about caching?" | "caching decision" |
Tree Traversal
When qmd search returns insufficient results, traverse the compaction tree:
1. ROOT.md Topics Index → confirm topic exists, note any file references
2. ROOT.md Historical Summary → identify relevant time period
3. memory/monthly/YYYY-MM.md → identify relevant week
4. memory/weekly/YYYY-WNN.md → identify relevant day
5. memory/daily/YYYY-MM-DD.md → detailed view
6. memory/YYYY-MM-DD.md → full raw original
Always try qmd search first. Tree traversal is the fallback.
When to Search
- Before any external lookup — check ROOT.md, then search memory
- Resuming prior work — search for task context, past progress
- Past decisions — search daily logs and knowledge files
- Credentials/configs — search before asking user
Without qmd
If qmd is not installed (e.g., --no-search was used during init, or the user has a different RAG tool), the memory system still works:
- ROOT.md is always available — use the Topics Index for "do I know about this?" judgment
- Tree traversal works without qmd — just read the files directly: ROOT → monthly/ → weekly/ → daily/ → raw
- Manual file reads — use
ls memory/daily/ to find files, then read them
- Skip
qmd update / qmd search commands — they will fail silently
The compaction tree and checkpoint protocol are fully independent of qmd. Search is a convenience layer, not a requirement.
After Modifying Files
If qmd is installed, re-index after changing memory or knowledge files:
qmd update
