# Spec: memsearch-episodic

## Purpose

Defines the episodic memory layer backed by the memsearch Claude Code plugin. Episodic memory captures what happened and when — session summaries stored as daily markdown files, queryable by semantic similarity across all projects.

## Requirements

### Requirement: Plugin installed globally
The system SHALL install memsearch as a Claude Code plugin via the marketplace so that episodic memory is available in all sessions.

#### Scenario: Successful marketplace install
- **WHEN** the user runs `/plugin marketplace add zilliztech/memsearch` followed by `/plugin install memsearch`
- **THEN** the memsearch plugin is active, its Stop hook is registered, and `memsearch` tool definitions are available in the session

### Requirement: Global memory directory
The system SHALL store all episodic memory files at a global path (`~/.memsearch/memory/`) so that memories from all projects accumulate in one place and are queryable cross-project.

#### Scenario: memory_dir is already global after install
- **WHEN** the user runs `memsearch config list` after install
- **THEN** `memory_dir` resolves to `~/.memsearch/memory/` (or equivalent global home-relative path)

#### Scenario: memory_dir requires explicit configuration
- **WHEN** `memsearch config list` shows a project-local `memory_dir`
- **THEN** the user sets `memory_dir = "~/.memsearch/memory/"` in `~/.memsearch/config.toml` and re-verifies with `memsearch config list`

### Requirement: Stop hook produces daily memory files
The system SHALL produce a daily memory file at `~/.memsearch/memory/YYYY-MM-DD.md` after each session turn so that episodic history accumulates automatically without manual action.

#### Scenario: Memory file created after first session turn
- **WHEN** a session turn completes (user message + Claude response) with memsearch installed and configured
- **THEN** a file exists at `~/.memsearch/memory/<today-date>.md` containing a summary of that turn

#### Scenario: Stop hook fires on every turn
- **WHEN** multiple turns occur in a session
- **THEN** the daily memory file grows with entries for each turn (SHA-256 dedup prevents duplicate entries)

### Requirement: Built-in guidance audited before customization
The system SHALL audit memsearch's built-in Claude plugin instructions after install before adding any custom skill or configuration, so that custom code is only added when a concrete gap is identified.

#### Scenario: No routing conflict found
- **WHEN** the user reviews memsearch's built-in guidance and runs a test session
- **THEN** episodic recall queries are handled by memsearch's built-in tools without conflicting with `memory-vault` or `memory-project` routing
- **THEN** no custom `memory-search` skill is created

#### Scenario: Routing conflict or gap identified
- **WHEN** memsearch's built-in guidance fails to distinguish episodic from semantic queries, or does not handle cross-project recall correctly
- **THEN** a minimal `memory-search` skill is authored that supplements (not replaces) the built-in guidance

### Requirement: Cross-project episodic recall available
The system SHALL enable the user to query episodic memory across all projects via `memsearch search "<query>"` so that questions like "what were we working on last Tuesday?" are answerable.

#### Scenario: Successful cross-project query
- **WHEN** the user runs `memsearch search "what was I working on last week?"` after at least one session has produced memory files
- **THEN** memsearch returns relevant summaries from `~/.memsearch/memory/` ranked by semantic similarity
