98 lines
4.7 KiB
Markdown
98 lines
4.7 KiB
Markdown
# 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
|