# `CMDC.Plugin.Builtin.EpisodicMemory`
[🔗](https://github.com/tupleyun/cmdc/blob/v0.5.3/lib/cmdc/plugin/builtin/episodic_memory.ex#L1)

情景记忆 few-shot Plugin。

长期记忆的「情景记忆（episodic）」类型 — 记住"成功的过往交互"作为下次类似
query 的 few-shot 示例。

## 与现有 Memory 模块的关系

CMDC 现有记忆模块各司其职：

| 模块 | 类型 | 用途 |
|---|---|---|
| `Plugin.Builtin.MemoryLoader` | 程序记忆 | 加载 AGENTS.md 静态规则到 system prompt |
| `Plugin.Builtin.MemoryFlush` | 语义记忆 | 压缩前提取关键事实 → AGENTS.md |
| `cmdc_skill_engine` | 可复用能力 | Skill 进化（成功/失败评分） |
| **`Plugin.Builtin.EpisodicMemory`**（本模块） | **情景记忆** | **完整成功对话的 few-shot 复用** |

情景记忆与 Skill 的区别：
- **Skill**：抽象的可复用能力（"如何做 X"）
- **Episodic**：具体的成功对话片段（"上次 X 是怎么做成的"）

## 工作流程

1. **`:session_end`**：检查 session 是否成功（自定义 `judge_fn` 或简单启发式）
2. **成功 session** → 抽取 `{query, plan, tool_trajectory, final_answer}`
   → 写入 `CMDC.Memory` 后端（默认 `CMDC.Memory.ETS`）
3. **`:session_start`**：用当前用户首条消息 → 语义检索 top-K episodes
   → inject 到 system prompt 作为 few-shot 示例

## 配置

    {EpisodicMemory, [
      memory_store: :episodic_memory,                        # 必填，CMDC.Memory backend 表名
      memory_module: CMDC.Memory.ETS,                        # 默认 ETS（cmdc_memory_pg 可换 PG）
      judge_fn: &MyApp.judge_success/2,                      # 自定义成功判断函数
      top_k: 3,                                              # session_start 检索 top-K
      max_episodes_per_user: 100                             # 按 user_id 上限避免内存爆
    ]}

## v0.4.0 实现说明

- `judge_fn` 默认启发式：session.turn >= 2 且无 abort/error 视为成功
- 语义检索：调用 `CMDC.Memory` behaviour 的 `search/3` callback（关键词包含匹配；若 backend 支持向量检索会自动升级为语义检索）
- 按 `ctx.user_data[:user_id]` namespace 隔离（多租户支持）

# `default_judge`

```elixir
@spec default_judge(map(), map()) :: boolean()
```

默认 judge：session.turn >= 2 且无 abort/error 视为成功。

用户可通过 `:judge_fn` 选项覆盖（例如接入 LLM-as-judge 或自定义规则）。

---

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