# `CMDC.Memory`
[🔗](https://github.com/tupleyun/cmdc/blob/v0.5.0/lib/cmdc/memory.ex#L1)

Memory behaviour 接口 — 可插拔的语义记忆存储。

定义 Agent 经验记忆的通用接口，支持多种存储后端：
- `CMDC.Memory.ETS` — 内存存储（开发/测试）

## Entry 结构

存入的 entry 为 map，必须包含 `:content` 字段（用于文本搜索），
其余字段自由扩展（如 `:task`、`:outcome`、`:tags`、`:inserted_at`）。
存储时自动注入 `:id` 和 `:inserted_at` 元数据。

# `entry`

```elixir
@type entry() :: %{
  :id => entry_id(),
  :content => String.t(),
  :inserted_at => DateTime.t(),
  optional(atom()) => term()
}
```

# `entry_id`

```elixir
@type entry_id() :: String.t()
```

# `search_opts`

```elixir
@type search_opts() :: [
  limit: pos_integer(),
  order: :desc | :asc,
  filters: [{atom(), term()}]
]
```

# `store`

```elixir
@type store() :: term()
```

# `delete`

```elixir
@callback delete(store(), entry_id()) :: :ok | {:error, term()}
```

按 id 删除一条记忆 entry，id 不存在时也返回 :ok。

# `list`

```elixir
@callback list(store()) :: {:ok, [entry()]} | {:error, term()}
```

返回所有记忆 entry，按插入时间降序排列。

# `search`

```elixir
@callback search(store(), String.t(), search_opts()) ::
  {:ok, [entry()]} | {:error, term()}
```

按文本关键词搜索记忆 entry（大小写不敏感）。

# `similarity_search`

```elixir
@callback similarity_search(store(), String.t(), search_opts()) ::
  {:ok, [map()]} | {:error, term()}
```

按语义相似度检索（ETS 降级为关键词匹配）。

# `store`

```elixir
@callback store(store(), entry_id(), map()) :: :ok | {:error, term()}
```

存储一条记忆 entry。

`id` 为调用方指定的唯一标识符，`data` 必须包含 `:content` 字段。

---

*Consult [api-reference.md](api-reference.md) for complete listing*