hipocampus-search

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

1. Use 2-4 specific keywords — more precise = better results
2. No natural language — strip filler words
3. 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