cc-os/docs/adr/0002-memsearch-for-the-episodic-layer.md

id	date	status	supersedes	superseded-by	affected-paths	affected-components	migration_confidence	migration_source
0002	2026-06-03	Accepted					medium	docs/memory-system/03-architecture-decisions.md### ADR-002 — memsearch for the episodic layer

0002 — memsearch for the episodic layer

Context

Need timeline/"what happened" memory (Goal 3) that's NL-queryable and lazy.

Decision

Adopt memsearch (Zilliz) off-the-shelf for episodic memory.

• Rationale: It already implements the OpenClaw daily-notes + "dreaming" pattern and the markdown-as-truth / disposable-shadow-index philosophy we'd otherwise build. Embedded Milvus Lite (single file), hybrid BM25+vector+RRF search, local ONNX embeddings (no API key/cost), a FileWatcher that handles deletions — no Docker, no server. Two-line install.

Consequences

memsearch is adopted off-the-shelf for episodic memory instead of building a custom daily-notes/dreaming system, giving embedded Milvus Lite storage, hybrid BM25+vector+RRF search, and local ONNX embeddings with no Docker or API key required. This means the episodic layer depends on memsearch's design and behavior rather than a bespoke implementation.

Alternatives rejected

claude-mem (MCP-based — Claude must actively call search; opaque blobs vs readable markdown; overkill features). Hand-building daily notes + dreaming ourselves (reinventing a solved tool).