cc-os/docs/superpowers/specs/2026-06-09-memsearch-episodic-layer-design.md

Step 4 — Memsearch Episodic Layer Design

Last updated: 2026-06-09 Status: Approved, pending implementation

Goal

Add time-anchored episodic memory to the personal Claude Code memory system. Enable queries like "what was I working on last Tuesday?" or "did we discuss X recently?" across all projects.

Guiding Principle

Install memsearch as a standard global plugin. Audit its default behavior before adding anything custom. Every deviation from defaults requires a concrete reason observed after install — not assumed in advance. The expected outcome is a working episodic layer with zero custom code.

Architecture Fit

The system has two memory types kept as separate systems:

• Episodic ("what happened, when") → memsearch (this step)
• Semantic/knowledge ("how do we…") → Obsidian vault + Graphify (already live)

memsearch is the purpose-built episodic layer. It is not a replacement for Graphify and does not index the vault.

Components

1. memsearch Plugin

Installed via Claude Code plugin marketplace:

/plugin marketplace add zilliztech/memsearch
/plugin install memsearch

Ships with its own Stop hook (fires after each response turn), its own Claude guidance, and tool definitions. No custom code needed.

2. Configuration

After install, run memsearch config list to audit actual defaults before changing anything.

The one setting to confirm: memory_dir must be global (~/.memsearch/memory/) so all projects share one episodic store — essential for cross-project recall. Run memsearch config list after install; if memory_dir is not already global, set it explicitly in ~/.memsearch/config.toml. memsearch's Milvus database already defaults to a global path (~/.memsearch/milvus.db), so memory_dir may match — verify rather than assume.

All other defaults are kept:

• Embedding: ONNX bge-m3-onnx-int8 (CPU, no API key, ~558MB one-time download)
• Storage: Milvus Lite at ~/.memsearch/milvus.db

3. Built-in Guidance Audit

memsearch ships as a full Claude Code plugin with its own system prompt instructions and tool guidance. After install, observe what it adds to Claude's context before adding anything.

Expected outcome: no custom skill needed. A memory-search skill is only warranted if — after seeing the default install — memsearch's built-in guidance fails to handle cross-project episodic recall, or creates routing confusion with memory-vault/memory-project. This will be evaluated at install time.

Data Flow

Each response turn:
  memsearch Stop hook fires (ships with plugin)
    → extracts last user question + Claude response from transcript
    → summarizes via Haiku (2-10 bullet points, third-person)
    → appends to ~/.memsearch/memory/YYYY-MM-DD.md
    → runs `memsearch index` immediately (incremental, SHA-256 dedup)
    → stored in Milvus Lite at ~/.memsearch/milvus.db

On-demand recall:
  memsearch search "<query>"
    → hybrid search (dense bge-m3 vectors + BM25)
    → L1 snippets by default; L2/L3 drill-down available

Hook Integration

session-end.sh: unchanged.

The existing hook writes vault provenance (which vault notes were touched, project, end reason) to ~/Documents/SecondBrain/journal/YYYY-MM-DD.md. This is complementary to memsearch, not redundant:

System	Captures	Answers
memsearch Stop hook	Per-turn Q&A summaries	"What were we discussing last Tuesday?"
session-end.sh	Vault notes touched per session	"Which notes did I update during that sprint?"

What This Step Does Not Do

• Does not index the vault (~/Documents/SecondBrain/) — Graphify owns that
• Does not replace or modify session-end.sh
• Does not add custom hook code
• Does not configure Milvus Server or Zilliz Cloud (Milvus Lite is correct for personal use)
• Does not assume SessionStart hook injection is needed — evaluate after seeing what the default global install provides
• Step 4 is complete when: plugin is installed, memory_dir is confirmed global, and at least one session has produced a daily memory file at ~/.memsearch/memory/YYYY-MM-DD.md. SessionStart injection is a distinct future step.

Installation Checklist

1. Install plugin via marketplace commands above
2. Run memsearch config list — record actual defaults
3. If memory_dir is project-local, set memory_dir = "~/.memsearch/memory/" in ~/.memsearch/config.toml
4. Verify Stop hook is registered (~/.claude/settings.json or plugin config)
5. Run one test session — confirm ~/.memsearch/memory/YYYY-MM-DD.md is created after a turn
6. Audit Claude plugin instructions — note what guidance memsearch adds
7. Add custom memory-search skill only if gaps exist in built-in guidance