67 lines
4.6 KiB
Markdown
67 lines
4.6 KiB
Markdown
|
## Context
|
||
|
|
|
||
|
|
The personal Claude Code memory system currently has two intended layers: episodic (per-turn Q&A history across all projects) and semantic/knowledge (the Obsidian vault + Graphify). The semantic layer is live. The episodic layer does not exist yet — there is no durable record of what was discussed across sessions.
|
||
|
|
|
||
|
|
memsearch is a purpose-built episodic memory plugin for Claude Code, developed by Zilliz (the company behind Milvus). It ships with its own Stop hook, Claude guidance, and tool definitions. The design principle for this step is: install first, audit defaults, deviate only if evidence demands it.
|
||
|
|
|
||
|
|
**Current state:** No episodic memory. No memsearch installed.
|
||
|
|
|
||
|
|
**Constraints:**
|
||
|
|
- Must be a global install (all projects share one episodic store)
|
||
|
|
- No external API keys — embeddings must run locally
|
||
|
|
- No daemon or cron — freshness is lazy (write-time + incremental index)
|
||
|
|
- No custom code unless audit reveals concrete gaps
|
||
|
|
|
||
|
|
## Goals / Non-Goals
|
||
|
|
|
||
|
|
**Goals:**
|
||
|
|
- Install memsearch via the Claude Code plugin marketplace
|
||
|
|
- Confirm `memory_dir` points to a global path (`~/.memsearch/memory/`)
|
||
|
|
- Verify the memsearch Stop hook fires and produces `~/.memsearch/memory/YYYY-MM-DD.md` after a session
|
||
|
|
- Audit the built-in plugin guidance to check for routing conflicts with `memory-vault`/`memory-project`
|
||
|
|
|
||
|
|
**Non-Goals:**
|
||
|
|
- Does not index the Obsidian vault — Graphify owns semantic search
|
||
|
|
- Does not add a SessionStart hook injection (evaluate after seeing what the default install provides)
|
||
|
|
- Does not configure Milvus Server or Zilliz Cloud (Milvus Lite is correct for personal use)
|
||
|
|
- Does not write a custom `memory-search` skill unless the audit reveals gaps
|
||
|
|
- Does not modify `session-end.sh` or any existing hooks
|
||
|
|
|
||
|
|
## Decisions
|
||
|
|
|
||
|
|
**Use the plugin marketplace, not manual install**
|
||
|
|
memsearch ships as a complete Claude Code plugin. Installing via `/plugin marketplace add` + `/plugin install` wires the Stop hook, tool definitions, and Claude guidance automatically. Manual installation would require replicating that work without benefit.
|
||
|
|
|
||
|
|
*Alternative considered: clone repo and wire manually* — rejected; more work with no gain given a working plugin exists.
|
||
|
|
|
||
|
|
**Milvus Lite over Milvus Server**
|
||
|
|
Personal use case: one developer, one machine, low write volume. Milvus Lite runs in-process with no daemon. Milvus Server adds operational overhead that isn't warranted here.
|
||
|
|
|
||
|
|
*Alternative considered: Zilliz Cloud* — rejected; requires account, network dependency, and cost for a personal tool.
|
||
|
|
|
||
|
|
**ONNX bge-m3 embeddings over API-based embeddings**
|
||
|
|
Ships with the plugin; runs on CPU; ~558MB one-time download; no API key required. Consistent with the system's principle of local-first tooling (same reason Ollama is used for Graphify extraction).
|
||
|
|
|
||
|
|
**Audit-first policy**
|
||
|
|
memsearch's built-in guidance may already handle cross-project episodic recall correctly. Adding a custom skill before seeing what the default install provides would be premature. Evaluate after one real session.
|
||
|
|
|
||
|
|
## Risks / Trade-offs
|
||
|
|
|
||
|
|
- **`memory_dir` defaults to project-local path** → Mitigation: run `memsearch config list` immediately after install; set global path in `~/.memsearch/config.toml` if needed. Spec requires this verification step.
|
||
|
|
- **Plugin marketplace unavailability** → Mitigation: if `/plugin marketplace add` fails, check memsearch GitHub for alternative install path.
|
||
|
|
- **558MB embedding model download** → Mitigation: one-time cost; happens on first use. No action needed, just awareness.
|
||
|
|
- **Built-in guidance conflicts with `memory-vault`/`memory-project` routing** → Mitigation: audit after install; add a minimal `memory-search` skill only if routing confusion is observed in practice.
|
||
|
|
- **Stop hook not auto-registering** → Mitigation: verification step in the checklist confirms hook is wired; manual registration in `~/.claude/settings.json` is fallback.
|
||
|
|
|
||
|
|
## Migration Plan
|
||
|
|
|
||
|
|
1. Install plugin via marketplace commands
|
||
|
|
2. Run `memsearch config list` — record actual defaults (do not assume)
|
||
|
|
3. If `memory_dir` is project-local, set `memory_dir = "~/.memsearch/memory/"` in `~/.memsearch/config.toml`
|
||
|
|
4. Verify Stop hook is registered (check `~/.claude/settings.json` or plugin config)
|
||
|
|
5. Run one test session — confirm `~/.memsearch/memory/YYYY-MM-DD.md` is created
|
||
|
|
6. Audit Claude plugin instructions — note what guidance memsearch adds to context
|
||
|
|
7. If routing gaps exist, write a minimal `memory-search` skill
|
||
|
|
|
||
|
|
**Rollback:** Uninstall the plugin (`/plugin uninstall memsearch`). The Milvus database and daily memory files are inert without the plugin. No changes to existing hooks or skills, so nothing to revert there.
|