Add memsearch episodic layer design spec (Step 4)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
jared
parent
61a33f137b
commit
98cc49c063
|
|
@ -0,0 +1,90 @@
|
|||
# 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
|
||||
|
||||
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
|
||||
Loading…
Reference in New Issue