# 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