---
id: "0002"
date: 2026-06-03
status: Accepted
supersedes:
superseded-by:
affected-paths: []
affected-components: []
migration_confidence: medium
migration_source: "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).