docs(memory): add design spec and implementation plan for crates/memory

Author: lingcoder

docs/design-crates-memory.md

@@ -0,0 +1,394 @@
+# Design: `crates/memory/` — 独立记忆系统 crate
+
+> Status: Approved
+> Date: 2026-04-14
+
+---
+
+## 1. 动机
+
+当前记忆系统的 6 个模块散落在 `crates/session/` 中：
+
+| 文件 | 行数 | 职责 |
+|------|------|------|
+| `memory.rs` | 452 | MemoryStore CRUD |
+| `memory_types.rs` | 305 | MemoryType 枚举 + frontmatter 解析 |
+| `memory_relevance.rs` | 305 | 关键词评分 + 预算选择 |
+| `memory_age.rs` | 250 | 指数衰减 + 修剪建议 |
+| `memory_extract.rs` | 287 | 对话模式提取（依赖 `crab_core::Message`） |
+| `team_memory.rs` | 179 | 团队共享记忆 |
+
+**问题**：
+
+1. **职责不匹配** — `session` crate 的核心是会话管理 + 上下文压缩，记忆是正交关注点
+2. **依赖反向渗透** — `memory_extract.rs` 为了 `Message` 拉入了 `crab-core`，使 session → core 依赖因为记忆而变重
+3. **复用受限** — 如果 daemon、IDE 插件也想访问记忆，必须依赖整个 `crab-session`
+4. **缺失 CCB 关键能力** — 路径安全校验、MEMORY.md 截断、LLM 驱动的语义选择、prompt 构建器
+
+## 2. 目标
+
+- 将记忆系统提取为 `crates/memory/`（Layer 2 Service Layer）
+- 最小依赖：`crab-common` + `serde` — 不依赖 `crab-core`
+- 对齐 CCB `memdir/` 的全部能力
+- 保持 `memory_extract`（对话提取）在 `crates/agent/` 中作为桥接层
+
+## 3. 架构层级
+
+```
+Layer 3: agent ──────┐
+                     │ uses MemoryStore, MemorySelector
+Layer 2: memory ◄────┘
+         │
+         └──► crab-common (errors, path utils)
+              serde / serde_json
+```
+
+`memory` 放在 Layer 2，与 `tools`、`fs`、`skill` 同级。
+`agent` 和 `session` 都可以依赖它，`memory_extract`（对话 → 记忆桥接）留在 `agent` 中。
+
+## 4. 模块设计
+
+```
+crates/memory/
+├── Cargo.toml
+└── src/
+    ├── lib.rs              # 公开 API re-exports
+    ├── types.rs            # MemoryType, MemoryMetadata, MemoryFile
+    ├── store.rs            # MemoryStore — 文件 CRUD + frontmatter 解析
+    ├── index.rs            # MEMORY.md 索引文件读写 + 截断
+    ├── relevance.rs        # MemorySelector — 评分 + 预算选择
+    ├── age.rs              # 指数衰减 + 修剪建议
+    ├── prompt.rs           # MemoryPromptBuilder — 构建注入 system prompt 的完整记忆段
+    ├── paths.rs            # 记忆目录路径解析（per-project + global）
+    ├── team.rs             # 团队记忆 — 路径、读写、同步
+    └── security.rs         # 路径安全校验（穿越、symlink、Unicode 正规化）
+```
+
+### 4.1 `types.rs` — 核心类型
+
+```rust
+/// 四类记忆分类（封闭枚举）
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum MemoryType {
+    User,
+    Feedback,
+    Project,
+    Reference,
+}
+
+/// 从 frontmatter 解析出的元数据
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MemoryMetadata {
+    pub name: String,
+    pub description: String,
+    pub memory_type: MemoryType,
+    pub created_at: Option<String>,
+    pub updated_at: Option<String>,
+}
+
+/// 完整的记忆文件（元数据 + body）
+#[derive(Debug, Clone)]
+pub struct MemoryFile {
+    pub filename: String,
+    pub path: PathBuf,
+    pub metadata: MemoryMetadata,
+    pub body: String,
+    /// 文件修改时间（用于排序和新鲜度）
+    pub mtime: Option<SystemTime>,
+}
+```
+
+**vs 现状改进**：
+- `MemoryFile.memory_type` 从 `String` → `MemoryType` 枚举（类型安全）
+- 新增 `mtime` 字段（CCB 用 `mtimeMs` 排序）
+- `MemoryFile` 统一了现在分散在 `memory.rs` 和 `memory_relevance.rs` 中的两个不同结构体
+
+### 4.2 `store.rs` — 记忆存储
+
+```rust
+pub struct MemoryStore {
+    dir: PathBuf,
+}
+
+impl MemoryStore {
+    pub fn new(dir: impl Into<PathBuf>) -> Self;
+
+    // ── CRUD ──
+    pub fn save(&self, filename: &str, content: &str) -> Result<()>;
+    pub fn load(&self, filename: &str) -> Result<Option<String>>;
+    pub fn delete(&self, filename: &str) -> Result<()>;
+
+    // ── 批量操作 ──
+    /// 扫描目录，解析 frontmatter，按 mtime 降序排列，上限 200 个
+    pub fn scan(&self) -> Result<Vec<MemoryFile>>;
+
+}
+
+// ── Frontmatter 解析（自由函数，定义在 types.rs）──
+pub fn parse_frontmatter(content: &str) -> Option<MemoryMetadata>;
+pub fn extract_body(content: &str) -> &str;
+pub fn format_frontmatter(metadata: &MemoryMetadata) -> String;
+```
+
+**vs 现状改进**：
+- `scan()` 替代 `load_all()`，返回 `MemoryFile`（包含 mtime），按 mtime 排序（CCB 行为）
+- `format_frontmatter()` 新增 — 当前 `team_memory.rs` 手动拼接 YAML，应统一
+
+### 4.3 `index.rs` — MEMORY.md 索引
+
+```rust
+pub struct MemoryIndex {
+    pub entries: Vec<IndexEntry>,
+    pub truncation: Option<Truncation>,
+}
+
+pub struct IndexEntry {
+    pub title: String,
+    pub filename: String,
+    pub hook: String,  // 一行描述
+}
+
+pub struct Truncation {
+    pub original_lines: usize,
+    pub original_bytes: usize,
+    pub was_line_truncated: bool,
+    pub was_byte_truncated: bool,
+}
+
+/// 读取 MEMORY.md，应用截断限制
+pub fn load_index(dir: &Path) -> Result<MemoryIndex>;
+
+/// 保存 MEMORY.md（entries → markdown）
+pub fn save_index(dir: &Path, entries: &[IndexEntry]) -> Result<()>;
+
+/// 截断 MEMORY.md 内容（200 行 / 25KB 上限）
+pub fn truncate_index(content: &str) -> (String, Truncation);
+```
+
+**新增能力**（对齐 CCB `truncateEntrypointContent`）：
+- MEMORY.md 的 200 行 / 25KB 截断保护
+- 截断信息返回，caller 可选择是否提示用户
+
+### 4.4 `relevance.rs` — 记忆选择
+
+```rust
+pub struct MemorySelector {
+    pub max_memories: usize,
+    pub max_total_bytes: usize,
+}
+
+/// 评分后的记忆条目
+pub struct ScoredMemory {
+    pub file: MemoryFile,
+    pub score: f64,
+}
+
+impl MemorySelector {
+    /// 关键词评分选择（本地，无 LLM 调用）
+    pub fn select_by_keywords(
+        &self,
+        memories: &[MemoryFile],
+        context: &str,
+    ) -> Vec<ScoredMemory>;
+}
+
+/// 为未来 LLM 驱动的选择预留的 trait
+pub trait MemoryRanker: Send + Sync {
+    /// 从 manifest 中选择最相关的记忆文件名（最多 max_count 个）
+    fn rank(
+        &self,
+        query: &str,
+        manifest: &str,
+        max_count: usize,
+    ) -> Pin<Box<dyn Future<Output = crab_common::Result<Vec<String>>> + Send + '_>>;
+}
+```
+
+**vs 现状改进**：
+- 将 `MemoryEntry` 统一为 `ScoredMemory`（组合而非重复定义）
+- 新增 `MemoryRanker` trait — CCB 用 Sonnet 做语义选择，我们先用关键词评分，trait 为 LLM 选择留接口
+- `agent` 层注入 `MemoryRanker` 实现（调 LLM），`memory` crate 本身不依赖 `crab-api`
+
+### 4.5 `age.rs` — 记忆老化
+
+基本保持现有实现，改进：
+
+```rust
+/// 用 mtime（SystemTime）而非字符串日期计算年龄
+pub fn age_days(mtime: SystemTime) -> u64;
+
+/// 指数衰减评分（30 天半衰期）
+pub fn decay_score(age_days: u64) -> f64;
+
+/// 人类可读的年龄文本
+pub fn age_text(age_days: u64) -> String;
+
+/// 新鲜度警告（>1 天的记忆附加校验提示）
+pub fn freshness_caveat(age_days: u64) -> Option<String>;
+
+/// 修剪建议
+pub fn suggest_pruning(memories: &[MemoryFile], threshold: f64) -> Vec<&MemoryFile>;
+```
+
+**vs 现状改进**：
+- 用 `SystemTime` 替代手写的日期字符串解析 + Hinnant 算法
+- 删除 `parse_date_to_days()` 和 `days_to_civil()` — 这些应该用 `SystemTime` 直接计算
+
+### 4.6 `prompt.rs` — 提示词构建器（新增）
+
+CCB 的 `memdir.ts` 核心能力：构建完整的记忆 system prompt 段。
+
+```rust
+pub struct MemoryPromptBuilder {
+    pub display_name: Option<String>,
+    pub include_guidelines: bool,
+}
+
+impl MemoryPromptBuilder {
+    /// 构建完整的记忆 prompt 段（索引 + 类型说明 + 行为指南）
+    pub fn build(
+        &self,
+        index: &MemoryIndex,
+        selected: &[MemoryFile],
+    ) -> String;
+
+    /// 仅构建行为指南（不含记忆内容，用于 agent 子任务）
+    pub fn build_guidelines_only(&self) -> String;
+}
+```
+
+### 4.7 `paths.rs` — 路径解析（新增）
+
+对齐 CCB `memdir/paths.ts`：
+
+```rust
+/// 自动记忆目录：~/.crab/projects/<sanitized-git-root>/memory/
+pub fn auto_memory_dir(git_root: Option<&Path>) -> PathBuf;
+
+/// 全局记忆目录：~/.crab/memory/
+pub fn global_memory_dir() -> PathBuf;
+
+/// 团队记忆目录：~/.crab/teams/<name>/memory/
+pub fn team_memory_dir(team_name: &str) -> PathBuf;
+
+/// 路径是否在记忆目录内（用于权限豁免判断）
+pub fn is_memory_path(path: &Path) -> bool;
+
+/// 将 git root 路径清理为安全的目录名
+fn sanitize_path_component(path: &Path) -> String;
+```
+
+### 4.8 `security.rs` — 路径安全（新增）
+
+对齐 CCB `teamMemPaths.ts` 的安全加固：
+
+```rust
+/// 校验团队记忆路径安全性
+pub fn validate_team_mem_path(path: &Path, team_dir: &Path) -> Result<PathBuf>;
+
+/// 校验文件名（key）安全性
+pub fn validate_memory_key(key: &str) -> Result<String>;
+
+// 内部检查：
+// - null byte 检测
+// - 路径穿越检测（.., %2e%2e, Unicode fullwidth）
+// - symlink 解析校验（dunce::canonicalize）
+// - 前缀攻击防护（team-evil vs team）
+```
+
+### 4.9 `team.rs` — 团队记忆
+
+```rust
+pub struct TeamMemoryStore {
+    store: MemoryStore,  // 复用基础 MemoryStore
+    team_name: String,
+}
+
+impl TeamMemoryStore {
+    pub fn new(team_name: &str) -> Self;
+    pub fn save(&self, metadata: &MemoryMetadata, body: &str) -> Result<()>;
+    pub fn load_all(&self) -> Vec<MemoryFile>;
+    // 安全校验委托给 security 模块
+}
+```
+
+## 5. 依赖关系
+
+```toml
+[dependencies]
+crab-common.workspace = true    # Error types, path::home_dir()
+serde.workspace = true
+serde_json.workspace = true
+dunce.workspace = true          # Windows 路径正规化（已在 workspace）
+
+[dev-dependencies]
+tempfile.workspace = true
+```
+
+**关键决策**：不依赖 `crab-core`。
+
+- `memory_extract.rs`（依赖 `Message`）**不迁入** `crates/memory/`
+- 它留在 `crates/agent/` 作为"对话 → 记忆"桥接层
+- `MemoryRanker` trait 定义在 `memory` crate，实现在 `agent`（注入 LLM 调用）
+
+## 6. 迁移计划
+
+### Phase 1: 创建 crate + 迁移纯数据类型
+
+1. `cargo new crates/memory --lib`
+2. 迁移 `types.rs`（MemoryType, MemoryMetadata）+ `store.rs`（MemoryStore）
+3. `crab-session` 的 `memory.rs` + `memory_types.rs` 改为 `pub use crab_memory::*` 的 re-export
+4. 确保 `cargo test --workspace` 通过
+
+### Phase 2: 迁移评分 + 老化
+
+1. 迁移 `relevance.rs` 和 `age.rs`
+2. 统一 `MemoryEntry` 和 `MemoryFile` 为单一类型
+3. `session` 中删除原模块，更新 re-export
+
+### Phase 3: 新增能力
+
+1. 实现 `index.rs`（MEMORY.md 截断）
+2. 实现 `paths.rs`（per-project 路径解析）
+3. 实现 `security.rs`（路径安全校验）
+4. 实现 `prompt.rs`（prompt 构建器）
+
+### Phase 4: 团队记忆 + 桥接层
+
+1. 迁移 `team_memory.rs` → `team.rs`，集成 `security.rs`
+2. 将 `memory_extract.rs` 移到 `crates/agent/src/memory_extract.rs`
+3. 清理 `crab-session` 中的 memory 相关 re-export
+
+## 7. 与 CCB 的功能对照
+
+| CCB memdir 文件 | 功能 | crab-memory 模块 | 状态 |
+|-----------------|------|------------------|------|
+| `memoryTypes.ts` | 四类型分类 | `types.rs` | ✅ 已有 |
+| `memdir.ts` (MemoryStore) | 文件 CRUD | `store.rs` | ✅ 已有 |
+| `memdir.ts` (truncate) | MEMORY.md 截断 | `index.rs` | 🆕 新增 |
+| `memdir.ts` (buildPrompt) | prompt 构建 | `prompt.rs` | 🆕 新增 |
+| `memoryScan.ts` | 文件扫描 + header 解析 | `store.rs` scan() | ✅ 已有（需加 mtime） |
+| `findRelevantMemories.ts` | LLM 语义选择 | `relevance.rs` + `MemoryRanker` trait | 🔧 增强 |
+| `memoryAge.ts` | 新鲜度计算 | `age.rs` | ✅ 已有 |
+| `paths.ts` | per-project 路径 | `paths.rs` | 🆕 新增 |
+| `teamMemPaths.ts` | 团队路径 + 安全 | `team.rs` + `security.rs` | 🔧 增强 |
+| `teamMemPrompts.ts` | 团队记忆 prompt | `prompt.rs` | 🆕 新增 |
+| `extractMemories.ts` | 对话提取 | 留在 `agent/` | ⏸️ 不迁移 |
+| `memoryShapeTelemetry.ts` | 遥测 | 不实现（项目不远程遥测） | ❌ 跳过 |
+
+## 8. Rust 生态 crate 选型
+
+| 需求 | 选项 | 决策 |
+|------|------|------|
+| 路径正规化 | `dunce` | ✅ 已在 workspace（Windows UNC 路径处理） |
+| 目录遍历 | `walkdir` vs `std::fs::read_dir` | `read_dir` 够用（记忆目录单层扁平） |
+| YAML 解析 | `serde_yml` vs 手写 | 手写简单 K-V 解析够用（CCB 也是手写） |
+| 日期计算 | `chrono` vs `SystemTime` | `SystemTime`（避免重依赖，用 mtime 而非字符串日期） |
+| Unicode 正规化 | `unicode-normalization` | 需新增到 workspace（安全校验用） |
+
+## 9. 设计决策记录
+
+1. **MEMORY.md 截断警告用英文** — 注入 system prompt 的指令文本固定英文（LLM 读的，不是用户看的），用户侧 TUI 提示将来可国际化
+2. **MemoryRanker LLM 实现推到 Phase 4 之后** — trait 在 Phase 3 定义好 API surface，关键词评分 MVP 覆盖 80%；LLM ranking 在 `crates/agent/` 中实现 `struct LlmMemoryRanker`，注入 `crab-api` client
+3. **git root 由 caller 传入** — `auto_memory_dir(git_root: Option<&Path>)` 不做 git 发现，调用方（cli/agent）已知 git root 直接传入，`None` 时 fallback 到全局 `~/.crab/memory/`