agcore/docs/6-memory-system.md

# 记忆系统设计方案

> 设计日期：2026-06-07
> 状态：待实现

---

## 1. 背景与目标

### 1.1 背景

AG Core 已完成 Phase 0（LLM 调用周期）、Phase 1（提示词工程）、Phase 2（工具系统）。Phase 3 的目标是构建记忆系统，为 Phase 4（Agent 运行时）提供记忆存储、管理与检索能力。

### 1.2 目标

提供一套可插拔的记忆抽象层，支持以下记忆形态：

- **对话记忆（ConversationMemory）** — 管理多轮对话消息历史，支持 sliding window / 全量策略
- **知识库（KnowledgeStore）** — 基于 LLM Wiki 模式的结构化知识管理，Agent 可自主编译和维护知识页面
- **知识图谱（KnowledgeGraph）** — 实体-关系图存储，支持关联检索与图遍历
- **检索器（MemoryRetriever）** — 组合多种检索策略，提供统一的记忆查找入口

### 1.3 设计原则

- **不引入 embedding 依赖** — 采用 Karpathy's LLM Wiki 模式的 index + keyword 检索，替代传统向量检索
- **trait + 轻量默认实现** — 所有抽象接口均提供纯内存默认实现（InMemory），满足原型和测试需求
- **模块间松耦合** — 记忆系统与 LlmCycle 的集成推迟到 Phase 4 Agent Runtime，Phase 3 只定义接口和数据操作

---

## 2. 需求分析

### 2.1 功能需求

| ID | 需求 | 优先级 | 说明 |
|----|------|--------|------|
| F1 | 存储任意键值对 | P0 | MemoryStore 提供通用的 save/get/delete/list |
| F2 | 对话消息管理 | P0 | 按 session 管理多轮对话历史，支持滑动窗口裁剪 |
| F3 | 知识页面管理 | P1 | 创建/更新/删除/检索知识页面（标题+摘要+内容+标签+交叉引用） |
| F4 | 知识页面索引 | P1 | 维护可遍历的内容目录（index） |
| F5 | 知识页面关键词检索 | P1 | 基于标题/摘要/标签的关键词匹配 |
| F6 | 实体-关系图存储 | P1 | 实体节点增删查 + 关系边管理 + 图遍历 |
| F7 | 组合检索 | P2 | 综合 KnowledgeStore + KnowledgeGraph 的多策略检索 |
| F8 | 可插拔后端 | P0 | 所有存储抽象提供 trait，下游可实现自定义后端（文件/SQLite/图数据库等） |
| F9 | 记忆淘汰 | P1 | 支持 TTL 过期淘汰、容量上限淘汰、Hybrid 组合策略 |
| F10 | 消息条目级淘汰 | P1 | ConversationMemory 达到上限后删除最旧消息，而非仅压缩内容 |
| F11 | 基于召回价值的淘汰 | P2 | 根据召回频率、匹配评分、时效性综合计算"记忆价值"，淘汰价值最低的记忆 |
| F12 | 召回统计记录 | P2 | MemoryStore 记录每次召回事件（recall_count + score），供淘汰策略使用 |

### 2.2 非功能需求

| ID | 需求 | 说明 |
|----|------|------|
| NF1 | 零 embedding 依赖 | 核心库不引入任何向量数据库或 embedding 模型依赖 |
| NF2 | 错误体系完善 | MemoryError 枚举，支持 is_recoverable() 分类 |
| NF3 | 线程安全 | 所有存储实现满足 Send + Sync |
| NF4 | 异步 API | 所有 IO 操作为 async |
| NF5 | 模块化 | 各组件独立可替换（通过 trait） |

---

## 3. 方案设计

### 3.1 总体架构

```
┌─────────────────────────────────────────────────────────────┐
│                    MemoryRetriever                          │
│              (组合检索：index + keyword + graph)             │
├──────────────────┬──────────────────┬───────────────────────┤
│ ConversationMemory│  KnowledgeStore  │    KnowledgeGraph    │
│ (对话消息管理)    │  (知识页面管理)  │   (实体-关系图)      │
├──────────────────┴──────────────────┴───────────────────────┤
│                      MemoryStore                            │
│              (底层存储抽象：save/get/delete/list)            │
│                   InMemoryStore (默认)                       │
└─────────────────────────────────────────────────────────────┘
```

### 3.2 模块结构

```
src/
  memory.rs                  # 模块根：pub mod + pub use 重导出
  memory/
    store.rs                 # MemoryStore trait + InMemoryStore
    conversation.rs          # ConversationMemory（对话管理）
    knowledge.rs             # KnowledgeStore trait + InMemoryKnowledgeStore
    graph.rs                 # KnowledgeGraph trait + InMemoryGraph
    retriever.rs             # MemoryRetriever（组合检索器）
    error.rs                 # MemoryError
    types.rs                 # 核心数据类型
```

### 3.3 接口定义

#### MemoryStore — 底层存储抽象

```rust
#[async_trait]
pub trait MemoryStore: Send + Sync {
    async fn save(&self, item: MemoryItem) -> Result<(), MemoryError>;
    async fn get(&self, id: &str) -> Result<Option<MemoryItem>, MemoryError>;
    async fn delete(&self, id: &str) -> Result<(), MemoryError>;
    async fn list(&self, filter: &MemoryFilter) -> Result<Vec<MemoryItem>, MemoryError>;
}
```

#### InMemoryStore — 默认实现

```rust
pub struct InMemoryStore {
    items: Mutex<HashMap<String, MemoryItem>>,
}
```

基于 `HashMap<String, MemoryItem>` + `Mutex`，纯内存，线程安全。

#### ConversationMemory — 对话记忆

```rust
pub struct ConversationMemory {
    store: Arc<dyn MemoryStore>,
    session_id: String,
    config: ConversationMemoryConfig,
}

pub struct ConversationMemoryConfig {
    pub strategy: MemoryStrategy,       // sliding_window | full
    pub max_turns: usize,               // sliding window 的最大轮数
    pub compact_config: Option<CompactConfig>,  // 复用现有压缩配置
}
```

- 基于 `MemoryStore` 持久化消息
- `add_message()` 写入，`get_history()` 读取
- sliding window 模式：超出 `max_turns` 后，调用 `llm::compact::microcompact()` 裁剪
- 复用现有 `CompactConfig`（context_window, reserved_tokens, keep_recent）

#### KnowledgeStore — 知识库

```rust
#[async_trait]
pub trait KnowledgeStore: Send + Sync {
    async fn add_page(&self, page: KnowledgePage) -> Result<(), MemoryError>;
    async fn get_page(&self, id: &str) -> Result<Option<KnowledgePage>, MemoryError>;
    async fn update_page(&self, page: KnowledgePage) -> Result<(), MemoryError>;
    async fn delete_page(&self, id: &str) -> Result<(), MemoryError>;
    async fn search(&self, query: &str) -> Result<Vec<KnowledgePage>, MemoryError>;
    async fn get_index(&self) -> Result<Vec<PageIndexEntry>, MemoryError>;
}
```

- `add_page` 自动更新 index
- `search` 基于页面标题/摘要/标签的关键词匹配（不依赖 embedding）
- `get_index` 返回所有页面的摘要目录（类似 LLM Wiki 的 index.md）

#### InMemoryKnowledgeStore — 知识库默认实现

```rust
pub struct InMemoryKnowledgeStore {
    pages: Mutex<HashMap<String, KnowledgePage>>,
    index: Mutex<Vec<PageIndexEntry>>,
}
```

- `search()` 使用简单的字符串包含匹配（可替换为更复杂的检索算法）

#### KnowledgeGraph — 知识图谱

图谱检索的核心流程：**输入 → 关键词提取 → 实体标签匹配 → 图遍历**

```rust
#[async_trait]
pub trait KnowledgeGraph: Send + Sync {
    async fn add_entity(&self, entity: GraphEntity) -> Result<(), MemoryError>;
    async fn get_entity(&self, id: &str) -> Result<Option<GraphEntity>, MemoryError>;
    async fn remove_entity(&self, id: &str) -> Result<(), MemoryError>;
    async fn add_relation(&self, relation: GraphRelation) -> Result<(), MemoryError>;
    async fn remove_relation(&self, source_id: &str, target_id: &str, relation_type: &str) -> Result<(), MemoryError>;
    async fn get_related(&self, entity_id: &str, depth: usize) -> Result<Vec<ScoredEntity>, MemoryError>;
    async fn find_by_keywords(&self, keywords: &[String]) -> Result<Vec<GraphEntity>, MemoryError>;
}
```

- `find_by_keywords()` — 用关键词匹配实体的 `name`（精准/前缀匹配）和 `tags`（完全匹配），不模糊搜索全字段
- `get_related()` — 找到匹配实体后，按 `depth` 遍历关联实体，同时返回关联关系

- `get_related()` 按指定深度遍历邻居节点
- `search_entities()` 按实体名称/类型搜索

#### InMemoryGraph — 知识图谱默认实现

```rust
pub struct InMemoryGraph {
    entities: Mutex<HashMap<String, GraphEntity>>,
    relations: Mutex<Vec<GraphRelation>>,
}
```

- 图遍历使用 BFS/DFS，`depth` 控制搜索深度
- 适合原型和小规模图

#### MemoryRetriever — 组合检索器（含关联度评分）

两种检索通道会产出大量结果，因此需要**关联度评分机制**来排序和过滤。

##### ScoringStrategy — 评分策略

不依赖 embedding，基于可计算的文本和图结构特征：

| 策略 | 基准 | 计算方式 | 适用场景 |
|------|------|---------|---------|
| `TextOverlap` | **原始 query** | query 与召回结果的文本重叠度（n-gram Jaccard / Dice 系数），标题 > 摘要 > 内容 | 默认推荐，衡量内容契合度 |
| `GraphDistance` | 实体关系 | 实体间最短路径长度的倒数 → `1 / (1 + distance)` | 图遍历结果排序 |
| `TemporalWeight` | 时间 | 时间衰减：`1.0 / (1 + days_since_update)` | 时间敏感的知识（如新闻） |
| `ReferenceCount` | 页面权威性 | 被其他页面引用的次数归一化（简化版 PageRank） | 权威页面自然排在前面 |
| `Hybrid` | 综合 | 以上加权组合：`w1*overlap + w2*graph + w3*temporal + w4*reference` | 需要多维度权衡的场景 |

##### KeywordExtractor — 关键词提取

检索前先从输入中提取关键词，作为两个通道共享的检索入口：

```rust
pub trait KeywordExtractor: Send + Sync {
    fn extract(&self, query: &str) -> Vec<String>;
}

// 默认实现：按非字母数字字符分割，过滤停用词和单字符词
pub struct SimpleKeywordExtractor {
    stop_words: HashSet<String>,
}
```

##### RetrievalResult — 统一召回结果

```rust
pub struct MemoryRetriever {
    knowledge_store: Arc<dyn KnowledgeStore>,
    knowledge_graph: Arc<dyn KnowledgeGraph>,
    keyword_extractor: Arc<dyn KeywordExtractor>,
    config: RetrieverConfig,
}

pub struct RetrieverConfig {
    pub scoring: ScoringStrategy,
    pub max_results: usize,        // 最大返回条数，默认 20
    pub min_score: f32,            // 最低分数阈值 [0.0, 1.0]，默认 0.1
    pub graph_depth: usize,        // 图遍历深度，默认 2
    pub weights: ScoreWeights,     // Hybrid 策略的权重分配
}

pub struct ScoreWeights {
    pub overlap: f32,    // 默认 0.5 — 文本重叠度，以原始 query 为基准
    pub graph: f32,      // 默认 0.2 — 图距离
    pub temporal: f32,   // 默认 0.1 — 时间衰减
    pub reference: f32,  // 默认 0.2 — 引用计数
}

pub enum ScoringStrategy {
    TextOverlap,           // 以原始 query 为准绳的文本重叠度（默认）
    GraphDistance,
    TemporalWeight,
    ReferenceCount,
    Hybrid(ScoreWeights),
}

pub struct RetrievalResult {
    pub items: Vec<ScoredItem>,
    pub total_found: usize,
    pub query: String,
}

pub struct ScoredItem {
    pub source: RetrievalSource,   // KnowledgeStore | KnowledgeGraph
    pub score: f32,                // [0.0, 1.0] 最终评分
    pub breakdown: ScoreBreakdown,  // 各维度评分明细（可选）
}

pub enum RetrievalSource {
    KnowledgePage(KnowledgePage),
    GraphEntity(GraphEntity),
}

pub struct ScoreBreakdown {
    pub overlap_score: f32,   // 与原始 query 的文本重叠度
    pub graph_score: f32,     // 图距离
    pub temporal_score: f32,  // 时间衰减
    pub reference_score: f32, // 引用计数
}

pub enum RetrievalStrategy {
    Hybrid,            // 结合所有通道 + 评分排序（默认）
    KnowledgeOnly,     // 仅 KnowledgeStore
    GraphOnly,         // 仅 KnowledgeGraph
}
```

检索流程：

```
输入: "LangGraph 的 StateGraph 状态管理原理？"
    │
    ├─ 1. 关键词提取 (KeywordExtractor)
    │      → ["LangGraph", "StateGraph", "状态管理"]
    │
    ├─ 2. 并行召回 ──────────────────────────────────────┐
    │   │                                                  │
    │   ├─ KnowledgeStore.find_by_keywords(keywords)        │
    │   │   → 匹配页面标题/摘要/标签                       │
    │   │   → 返回 KnowledgePage 列表                      │
    │   │                                                  │
    │   └─ KnowledgeGraph.find_by_keywords(keywords) ──┐   │
    │       → 匹配实体 name / tags                      │   │
    │       → 命中: "LangGraph" (framework),            │   │
    │               "StateGraph" (concept)              │   │
    │       → get_related("LangGraph", depth=2)         │   │
    │       → 返回匹配实体 + 关联实体列表                │   │
    │                                                   │   │
    ├─ 3. 逐条评分 (ScoringStrategy)  ←───────────────────┘   │
    │   // 基准：原始 query，而非中间关键词                   │   │
    │   → overlap_score: 结果内容与原始 query 的文本重叠度 │   │
    │     (n-gram Jaccard 系数，标题权重大于正文)           │   │
    │   → graph_score: 实体在图中的距离（如有）             │   │
    │   → temporal_score: 时间衰减                          │   │
    │   → reference_score: 引用次数                         │   │
    │   → score = Σ(weight_i * score_i)                     │   │
    │                                                     │
    ├─ 4. 过滤: score < min_score → 丢弃                   │
    ├─ 5. 排序: score 降序 → 截取 max_results 条            │
    └─ 6. 返回: RetrievalResult                             │
```

流程说明：
1. **关键词提取** — 先用 `KeywordExtractor` 从输入中提取候选关键词，两个通道共享
2. **KnowledgeStore 检索** — 用关键词匹配页面的 `title`（精准/前缀）、`tags`（完全）、`summary`（包含）
3. **KnowledgeGraph 检索** — 用关键词匹配实体 `name` 和 `tags`，命中后按 `depth` 图遍历获取关联实体
4. **评分** — 对每条召回结果计算 `score ∈ [0.0, 1.0]`
5. **过滤排序** — 丢弃低分、按分排序、截取 top N

这样设计的好处：
- 关键词生成在两个通道间共享，避免重复计算
- 图谱检索从"模糊搜索"变为"标签精确匹配 → 图遍历"，更精准
- 每个步骤职责单一，可独立替换实现

### 3.4 核心数据类型

```rust
pub struct MemoryItem {
    pub id: String,
    pub content: String,
    pub metadata: serde_json::Value,
    pub created_at: chrono::DateTime<chrono::Utc>,
}

pub struct MemoryFilter {
    pub prefix: Option<String>,
    pub since: Option<chrono::DateTime<chrono::Utc>>,
    pub limit: Option<usize>,
}

pub struct KnowledgePage {
    pub id: String,
    pub title: String,
    pub summary: String,
    pub content: String,
    pub tags: Vec<String>,
    pub references: Vec<String>,    // 交叉引用的页面 ID 列表
    pub created_at: chrono::DateTime<chrono::Utc>,
    pub updated_at: chrono::DateTime<chrono::Utc>,
}

pub struct PageIndexEntry {
    pub id: String,
    pub title: String,
    pub summary: String,
    pub tags: Vec<String>,
    pub updated_at: chrono::DateTime<chrono::Utc>,
}

pub struct GraphEntity {
    pub id: String,
    pub name: String,
    pub entity_type: String,        // "person" | "concept" | "project" | ...
    pub description: String,
}

pub struct GraphRelation {
    pub source_id: String,
    pub target_id: String,
    pub relation_type: String,      // "works_on" | "part_of" | "related_to" | ...
    pub weight: f32,                // 关系强度 [0.0, 1.0]
}

pub enum MemoryStrategy {
    SlidingWindow,
    Full,
}

pub enum ScoringStrategy {
    KeywordDensity,
    GraphDistance,
    TemporalWeight,
    ReferenceCount,
    Hybrid(ScoreWeights),
}

pub struct ScoreWeights {
    pub keyword: f32,     // 默认 0.4
    pub graph: f32,       // 默认 0.3
    pub temporal: f32,    // 默认 0.1
    pub reference: f32,   // 默认 0.2
}

pub struct RetrieverConfig {
    pub scoring: ScoringStrategy,
    pub max_results: usize,
    pub min_score: f32,
    pub graph_depth: usize,
    pub weights: ScoreWeights,
}

pub struct RetrievalResult {
    pub items: Vec<ScoredItem>,
    pub total_found: usize,
    pub query: String,
}

pub struct ScoredItem {
    pub source: RetrievalSource,
    pub score: f32,
    pub breakdown: ScoreBreakdown,
}

pub struct ScoreBreakdown {
    pub keyword_score: f32,
    pub graph_score: f32,
    pub temporal_score: f32,
    pub reference_score: f32,
}

pub enum RetrievalSource {
    KnowledgePage(KnowledgePage),
    GraphEntity(GraphEntity),
}

pub enum RetrievalStrategy {
    Hybrid,
    KnowledgeOnly,
    GraphOnly,
}
```

### 3.5 错误类型

```rust
#[derive(Debug, thiserror::Error)]
pub enum MemoryError {
    #[error("Item not found: {0}")]
    NotFound(String),

    #[error("Item already exists: {0}")]
    AlreadyExists(String),

    #[error("Storage error: {0}")]
    Storage(String),

    #[error("Serialization error: {0}")]
    Serialization(String),

    #[error("Invalid input: {0}")]
    InvalidInput(String),

    #[error("Graph error: {0}")]
    GraphError(String),

    #[error("Retrieval error: {0}")]
    RetrievalError(String),
}

impl MemoryError {
    pub fn is_recoverable(&self) -> bool {
        matches!(self, Self::NotFound(_) | Self::RetrievalError(_))
    }
}
```

### 3.6 ConversationMemory 与 compact 模块的集成

```
ConversationMemory (src/memory/conversation.rs)
    │
    │  add_message()
    │  ├─ store.save(message)               ← 写到底层存储
    │  ├─ if sliding_window && over_limit:
    │  │    messages = store.list(session)
    │  │    compact_config.should_compact()  ← 复用 CompactConfig
    │  │    microcompact(&mut messages)      ← 复用 microcompact()
    │  │    store.save(pruned)               ← 写回
    │  └─ return
    │
    │  get_history()
    │  └─ store.list(session)
    │
    └─ imports: llm::compact::{CompactConfig, microcompact, should_compact}
```

---

---

## 4. 物理存储策略

### 4.1 存储层次

```
┌─────────────────────────────────────────────────┐
│               MemoryRetriever                   │
│              (检索 + 评分，无状态)               │
├─────────────────────────────────────────────────┤
│  MemoryStore / KnowledgeStore / KnowledgeGraph  │
│         (存储抽象接口，不感知存储介质)            │
├──────────────────┬──────────────────────────────┤
│  InMemoryStore   │  下游自定义实现               │
│  (HashMap)       │  (FileStore / SqliteStore    │
│   进程内 volatile│   / RedisStore / ... )        │
│   测试/原型适用  │   生产环境适用                │
└──────────────────┴──────────────────────────────┘
```

### 4.2 InMemoryStore 的物理存储

**当前默认实现：**

| 组件 | 数据结构 | 存储位置 | 持久化 | 生命周期 |
|------|---------|---------|--------|---------|
| `InMemoryStore` | `HashMap<String, MemoryItem>` | 进程堆内存 | ❌ | 随进程销毁 |
| `InMemoryKnowledgeStore` | `HashMap<String, KnowledgePage>` + `Vec<PageIndexEntry>` | 进程堆内存 | ❌ | 随进程销毁 |
| `InMemoryGraph` | `HashMap<String, GraphEntity>` + `Vec<GraphRelation>` | 进程堆内存 | ❌ | 随进程销毁 |
| `InMemoryStore.recall_stats` | `HashMap<String, RecallStats>` | 进程堆内存 | ❌ | 随进程销毁 |

**适用场景：**
- 单元测试和集成测试
- 本地快速原型开发
- 单次会话的临时 Agent（不期望跨会话持久化）
- Phase 4 开发阶段的验证

**不适合场景：**
- 生产部署
- 需要跨进程/跨会话共享记忆
- 需要数据持久化和恢复

### 4.3 持久化存储方案（下游实现）

agcore 核心库**不内置**持久化实现，用户通过实现 `MemoryStore` / `KnowledgeStore` / `KnowledgeGraph` trait 对接所需后端：

| 后端 | 实现建议 | 适用场景 | 复杂度 |
|------|---------|---------|--------|
| **JSON 文件** | MemoryStore trait → 序列化为单文件 JSON | 单机、轻量持久化 | 低 |
| **SQLite** | MemoryStore + KnowledgeStore → 关系表 | 单机、中小规模 | 中 |
| **PostgreSQL** | MemoryStore + KnowledgeStore → 关系表 | 多进程共享、中等规模 | 中 |
| **Redis** | MemoryStore → Hash/JSON 类型 | 高速缓存、会话共享 | 低 |
| **Neo4j** | KnowledgeGraph → 图数据库 | 大规模图谱检索 | 高 |

**示例：FileStore 结构示意（由用户自行实现）**

```
~/.agcore/memory/
  store.json              # MemoryStore 数据
  knowledge.json          # KnowledgeStore 数据
  graph_entities.json     # KnowledgeGraph 实体
  graph_relations.json    # KnowledgeGraph 关系
```

### 4.4 对下游实现的约束

MemoryStore / KnowledgeStore / KnowledgeGraph 三个 trait 对持久化实现没有任何特殊约束：
- 方法签名不涉及文件路径、连接字符串等存储细节
- 所有方法均为 `async`，持久化实现可以自由选择同步（`spawn_blocking`）或异步 driver
- 初始化参数在具体实现的构造函数中注入（如 `SqliteStore::new("path/to/db").await`）

### 4.5 序列化

核心类型均实现 `Serialize` / `Deserialize`（通过 `#[derive(serde)]`），便于持久化实现直接复用：

```rust
#[derive(Serialize, Deserialize)]
pub struct MemoryItem { ... }
#[derive(Serialize, Deserialize)]
pub struct KnowledgePage { ... }
// ...
```

所有类型基于 `serde_json::Value` 作为 metadata 类型，不引入 protobuf/msgpack 等序列化框架。

---

### 4.1 问题

所有存储组件（MemoryStore、KnowledgeStore、KnowledgeGraph）如果不设上限，会随运行时间无限增长。ConversationMemory 当前的 sliding window 只做 tool result 压缩，不删除消息条目。

### 4.2 淘汰策略

在 `MemoryStore` trait 层提供可选的淘汰配置，上层组件按需设置：

```rust
pub struct EvictionConfig {
    pub policy: EvictionPolicy,
    pub check_interval: usize,   // 每写入 N 条后检查一次淘汰条件
}

pub enum EvictionPolicy {
    None,                                // 不淘汰（默认，KnowledgeStore/KnowledgeGraph 适用）
    Ttl { ttl_secs: u64 },               // 超过存活时间淘汰（MemoryStore 通用）
    Capacity { max_items: usize },        // 超过容量淘汰最旧（ConversationMemory 适用）
    RecallBased {
        max_items: usize,
        recall_weight: f32,              // 召回频率权重，默认 0.3
        score_weight: f32,               // 平均匹配评分权重，默认 0.5
        recency_weight: f32,             // 最近召回时间权重，默认 0.2
    },
    Hybrid {
        ttl_secs: Option<u64>,
        max_items: Option<usize>,
        recall: Option<RecallBasedConfig>,
    },
}
```

### 4.3 RecallBased 淘汰策略

基于记忆的实际使用价值决定淘汰优先级，而非简单的写入时间。

#### 记忆价值评分

```rust
pub struct RecallStats {
    pub recall_count: u64,           // 累计被召回的次数
    pub total_score: f64,            // 累计评分（平均分 = total_score / recall_count）
    pub last_recall_at: i64,         // 最后一次被召回的时间戳（秒）
}

// 记忆价值 = recall_freq * recall_weight + avg_score * score_weight + recency * recency_weight
impl RecallStats {
    pub fn value(&self, now: i64, config: &RecallBasedConfig) -> f64 {
        let recency = 1.0 / (1.0 + (now - self.last_recall_at) as f64 / 86400.0);
        let freq = (self.recall_count as f64).ln_1p();
        let avg = if self.recall_count > 0 {
            self.total_score / self.recall_count as f64
        } else {
            0.0
        };
        freq * config.recall_weight as f64
            + avg * config.score_weight as f64
            + recency * config.recency_weight as f64
    }
}
```

淘汰时按 `value()` 升序排列，淘汰价值最低的记忆。

#### 召回统计的更新时机

在 `MemoryStore` trait 中增加可选方法 `record_recall()`：

```rust
#[async_trait]
pub trait MemoryStore: Send + Sync {
    async fn save(&self, item: MemoryItem) -> Result<(), MemoryError>;
    async fn get(&self, id: &str) -> Result<Option<MemoryItem>, MemoryError>;
    async fn delete(&self, id: &str) -> Result<(), MemoryError>;
    async fn list(&self, filter: &MemoryFilter) -> Result<Vec<MemoryItem>, MemoryError>;

    /// 记录一次召回事件（可选，仅 RecallBased 淘汰策略需要）
    async fn record_recall(&self, id: &str, score: f32) -> Result<(), MemoryError> {
        // 默认空实现，不强制实现
        Ok(())
    }
}
```

#### 召回统计的存储

`InMemoryStore` 内部额外维护一个 `HashMap<String, RecallStats>`：

```rust
pub struct InMemoryStore {
    items: Mutex<HashMap<String, MemoryItem>>,
    recall_stats: Mutex<HashMap<String, RecallStats>>,  // 召回统计
    eviction: EvictionConfig,
    created_at: Mutex<HashMap<String, i64>>,            // 写入时间（用于 TTL）
}
```

淘汰时的完整流程：

```
save(item)
  │
  ├─ items.insert(id, item)
  ├─ created_at.insert(id, now)
  │
  └─ if writes_since_last_check >= check_interval:
       switch policy:
         Ttl         → items.retain(created_at > cutoff)
         Capacity    → items: 按 created_at 升序排列，截断到 max_items
                       recall_stats: 同步清理
         RecallBased → 每条计算 value(now)
                       按 value 升序排列，截断到 max_items
                       recall_stats: 同步清理
         Hybrid      → 先 TTL → 再 Capacity 或 RecallBased
```

### 4.4 MemoryRetriever 对召回统计的联动

`MemoryRetriever` 每次成功检索后，对被选中的结果调用 `store.record_recall(id, score)`：

```
retrieve(query)
  │
  ├─ 关键词提取 → 并行召回
  ├─ 评分 → 过滤 → 排序
  ├─ return results
  │
  └─ 后台（非阻塞）:
       for item in results:
           store.record_recall(item.id, item.score).await;
           graph.record_recall(entity_id, item.score).await;
```

这样，被频繁召回且评分高的记忆会获得高价值分，自然保留；长期不被使用或评分低的会被优先淘汰。

### 4.3 各组件淘汰策略

| 组件 | 推荐策略 | 理由 |
|------|---------|------|
| **ConversationMemory** | `Capacity { max_items }` | 对话是流式的，旧消息价值递减，达到上限后淘汰最旧的消息条目 |
| **MemoryStore**（通用） | `Ttl { ttl_secs }` 或 `Hybrid` | 通用存储由调用方按场景决定 |
| **KnowledgeStore** | `None`（默认不淘汰） | 知识是累积的，新增不淘汰旧；如需要可按 `Hybrid` 配置 |
| **KnowledgeGraph** | `None`（默认不淘汰） | 实体关系是长期资产，不应自动淘汰 |

### 4.4 ConversationMemory 淘汰行为

当前方案的 sliding window 仅压缩 tool result 内容，但不删除消息。升级后：

```
add_message(msg)
  │
  ├─ store.save(msg)
  │
  ├─ if eviction.policy == Capacity:
  │     history = store.list(session)
  │     while history.len() > max_items:
  │         oldest = history.remove(0)     ← 删除最旧消息
  │         store.delete(oldest.id)
  │
  ├─ maybe_compact()                        ← 复用 microcompact() 做内容压缩
  │
  └─ return
```

两种机制分层：
- **淘汰（eviction）**：删除整条消息，控制条目总数上限
- **压缩（compaction）**：压缩剩余消息的 tool result 内容，节省 token

### 4.5 InMemoryStore 的淘汰实现

```rust
impl InMemoryStore {
    pub fn with_eviction(config: EvictionConfig) -> Self { ... }
}

// 在 save() 内部：
async fn save(&self, item: MemoryItem) -> Result<(), MemoryError> {
    self.items.lock().insert(item.id.clone(), item);
    self.maybe_evict().await;    // 写入后检查淘汰条件
}

async fn maybe_evict(&self) {
    match &self.eviction.policy {
        EvictionPolicy::Ttl { ttl_secs } => {
            let cutoff = Utc::now() - Duration::seconds(*ttl_secs as i64);
            self.items.lock().retain(|_, v| v.created_at > cutoff);
        }
        EvictionPolicy::Capacity { max_items } => {
            let mut items = self.items.lock();
            if items.len() > *max_items {
                let mut vec: Vec<_> = items.drain().collect();
                vec.sort_by_key(|(_, v)| v.created_at);
                vec.truncate(*max_items);
                *items = vec.into_iter().collect();
            }
        }
        EvictionPolicy::Hybrid { ttl_secs, max_items } => {
            // 先按 TTL 淘汰，再按容量淘汰
        }
        EvictionPolicy::None => {}
    }
}
```

---

### Step 1：基础类型 + MemoryStore（含淘汰机制）

**文件**：`src/memory.rs`、`src/memory/types.rs`、`src/memory/error.rs`、`src/memory/store.rs`

- 创建 `memory.rs` + `memory/` 目录
- 定义 `MemoryItem`、`MemoryFilter`、`MemoryStrategy` 类型
- 定义 `MemoryError` 枚举
- 定义 `MemoryStore` trait 与 `InMemoryStore` 实现
- 定义 `EvictionConfig`、`EvictionPolicy`（None / Ttl / Capacity / Hybrid）
- `InMemoryStore.save()` 内部实现淘汰检查
- 单元测试：TTL 过期淘汰、容量上限淘汰、不淘汰（None）、Hybrid 组合
- 验收：`cargo build` + `cargo test` 通过

**依赖**：chrono（日期时间）、serde（序列化）

### Step 2：ConversationMemory（含消息淘汰）

**文件**：`src/memory/conversation.rs`

- 定义 `ConversationMemoryConfig`、`MemoryStrategy`
- 实现 `ConversationMemory`
  - `add_message()` → 写入 MemoryStore → 触发容量淘汰（删除最旧消息）
  - 复用 `llm::compact` 的 `CompactConfig` 和 `microcompact()` 做内容压缩
- 单元测试：sliding window 消息淘汰、tool result 内容压缩、full 模式、空 session
- 验收：`cargo build` + `cargo test` 通过

**依赖**：MemoryStore（含 EvictionConfig）+ llm::compact

### Step 3：KnowledgeStore

**文件**：`src/memory/knowledge.rs`

- 定义 `KnowledgePage`、`PageIndexEntry` 类型
- 定义 `KnowledgeStore` trait
- 实现 `InMemoryKnowledgeStore`
  - index 自动维护（add/update/delete 时同步）
  - search 基于标题/摘要/标签的关键词匹配
- 单元测试：页面 CRUD、index 一致性、搜索
- 验收：`cargo build` + `cargo test` 通过

### Step 4：KnowledgeGraph

**文件**：`src/memory/graph.rs`

- 定义 `GraphEntity`、`GraphRelation` 类型
- 定义 `KnowledgeGraph` trait
- 实现 `InMemoryGraph`
  - BFS/DFS 图遍历
  - search_entities 按名称/类型匹配
- 单元测试：实体 CRUD、关系添加/删除、图遍历、搜索
- 验收：`cargo build` + `cargo test` 通过

### Step 5：MemoryRetriever（关键词提取 + 评分机制）+ 模块整合

**文件**：`src/memory/retriever.rs`、`src/memory.rs`

- 定义 `KeywordExtractor` trait + `SimpleKeywordExtractor` 默认实现（分割 + 停用词过滤）
- 定义 `ScoringStrategy` 枚举（TextOverlap / GraphDistance / TemporalWeight / ReferenceCount / Hybrid）
- 定义 `ScoreWeights`、`ScoredItem`、`ScoreBreakdown`、`RetrieverConfig`
- 实现评分函数：
  - `TextOverlap`: 以原始 query 为基准，计算召回内容与 query 的 n-gram Jaccard/Dice 系数
  - 图距离、时间衰减、引用计数
- 实现 `MemoryRetriever`：
  - `retrieve(query)`: 关键词提取 → 并行召回 → 逐条评分（以原始 query 为基准）→ 阈值过滤 → 排序截取
  - 支持 `RetrievalStrategy` 切换检索通道
  - 可选：启用 `ScoreBreakdown` 明细（默认 off，减少计算开销）
- 在 `memory.rs` 中用 `pub use` 重导出所有公共类型
- 在 `src/lib.rs` 中声明 `pub mod memory`
- 单元测试：关键词提取、各评分策略的正确性、阈值过滤、排序正确性
- 集成测试：端到端检索流程
- 验收：`cargo build` + `cargo test` 通过

---

## 5. 风险评估

| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|---------|
| KnowledgeStore 的 keyword 检索在大规模下效率低 | 中 | 中 | search 算法可替换——下游通过实现 trait 使用 BM25/TF-IDF |
| InMemoryGraph 不支持复杂图查询 | 中 | 中 | `depth` 参数限制遍历深度；生产场景替换为专用图数据库 |
| ConversationMemory 与 compact 耦合引入循环依赖 | 低 | 高 | 仅引用 `CompactConfig`（纯数据结构）和 `microcompact()`（纯函数），不引用 cycle.rs |
| chrono 增加依赖体积 | 低 | 低 | chrono 已是 Rust 生态标准，且仅用于时间戳 |
| Phase 4 集成时发现 Memory trait 设计不合理 | 低 | 高 | 按最小可行接口设计，预留扩展空间 |

---

## 6. 验收标准

- [ ] `MemoryStore` trait 定义清晰的 4 个方法，`InMemoryStore` 通过单元测试
- [ ] `EvictionConfig` 支持 None / Ttl / Capacity / RecallBased / Hybrid 五种策略
- [ ] `EvictionPolicy::RecallBased` 按记忆价值公式正确计算并淘汰低价值记忆
- [ ] `InMemoryStore` 在 save() 后正确执行 TTL 淘汰、容量淘汰、基于召回价值淘汰
- [ ] `InMemoryStore::record_recall()` 记录召回次数和评分
- [ ] `MemoryRetriever` 每次检索后调用 `record_recall()` 更新召回统计
- [ ] `ConversationMemory` 支持 sliding window 和 full 两种策略
- [ ] `ConversationMemory` sliding window 模式下达到上限后删除最旧消息条目
- [ ] `ConversationMemory` 正确复用 `llm::compact` 的压缩逻辑
- [ ] `KnowledgeStore` trait + `InMemoryKnowledgeStore` 支持页面 CRUD 和 index 维护
- [ ] `KnowledgeGraph` trait + `InMemoryGraph` 支持实体 CRUD、关系管理和图遍历
- [ ] `MemoryRetriever` 组合 KnowledgeStore + KnowledgeGraph 返回统一检索结果
- [ ] 无 embedding 相关依赖（不引入 fastembed、pgvector、qdrant 等 crate）
- [ ] 模块结构符合项目惯例：`memory.rs` + `memory/` 目录 + `pub use` 重导出
- [ ] `MemoryError` 枚举定义完善，支持 `is_recoverable()`
- [ ] 所有公开 API 有文档注释（`///`）
- [ ] `cargo build` 和 `cargo test` 通过
- [ ] 单个文件不超过 300 行（遵循现有代码库风格）

---

## 附录：与 Karpathy's LLM Wiki 的关系

本方案受 Karpathy's LLM Wiki 模式启发，但做了一些调整以适应 Agent 核心库的定位：

| Karpathy LLM Wiki | AG Core Memory System | 差异原因 |
|-------------------|----------------------|---------|
| 三层：Raw → Wiki → Schema | 四组件：MemoryStore → ConversationMemory + KnowledgeStore + KnowledgeGraph + MemoryRetriever | Agent 场景需要区分对话记忆和知识记忆 |
| index.md + log.md | PageIndexEntry（同 index.md）+ 无 log（Phase 4 Agent 负责） | 日志是工作流层职责，非存储层 |
| LLM Agent 全权维护 | KnowledgeStore 提供数据接口，Phase 4 Agent 编排工作流 | core 只提供存储能力，不编排 |
| 文件系统为后端 | MemoryStore trait 抽象后端 | 可插拔设计需要 trait 抽象 |
| 基于文件系统搜索 | index + keyword + graph 混合检索 | 文件系统搜索不适合所有后端 |