---
name: Hipocampus Search
slug: hipocampus-search
category: AI Engineering
description: Hipocampus Search looks up memory with qmd using BM25 and optional vector search, then follows the compaction tree when needed. Use ROOT.md first to decide whether to search memory or look externally.
github: "https://github.com/kevin-hs-sohn/hipocampus/tree/main/skills/search"
language: JavaScript
stars: 206
forks: 10
install: "npx degit https://github.com/kevin-hs-sohn/hipocampus/tree/main/skills/search ~/.claude/skills/search"
installs_to: ~/.claude/skills/search
source_path: skills/search/SKILL.md
collection_size: 8
category_size: 3101
collection_url: "https://dirskills.com/collections/kevin-hs-sohn/hipocampus"
added: 2026-09-05T05:29:03.469Z
last_synced: 2026-09-05T05:29:03.469Z
canonical_url: "https://dirskills.com/skills/hipocampus-search"
---

# Hipocampus Search

Hipocampus Search looks up memory with qmd using BM25 and optional vector search, then follows the compaction tree when needed. Use ROOT.md first to decide whether to search memory or look externally.

**Install:**

```bash
npx degit https://github.com/kevin-hs-sohn/hipocampus/tree/main/skills/search ~/.claude/skills/search
```

## README

# 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:

```bash
qmd update
```