3.9 KiB

Raw Blame History

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.

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 verify: memory_dir. memsearch's Milvus database defaults to ~/.memsearch/milvus.db (global). If memory_dir also defaults to a global path, no config change is needed. If it defaults to project-local (.memsearch/memory/), set it to ~/.memsearch/memory/ so all projects share one episodic store — essential for cross-project recall.

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 and likely includes its own system prompt instructions telling Claude when and how to use memsearch search. After install, audit what it adds to Claude's context. Add a custom memory-search skill only if there are genuine gaps in the built-in guidance or conflicts with the existing memory-vault/memory-project skill boundary.

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 integrate memsearch recall into SessionStart hook injection (deferred)

Installation Checklist

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

3.9 KiB Raw Blame History