CMDC.Memory behaviour (cmdc v0.4.0)

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

定义 Agent 经验记忆的通用接口，支持多种存储后端：

Entry 结构

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

entry()

entry_id()

search_opts()

store()

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

list(store)

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

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

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

存储一条记忆 entry。

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

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

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

@type store() :: term()

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

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

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

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

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

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

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

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

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

存储一条记忆 entry。

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