重构 Memory 模块

[ztygod]

背景

当前 Pixelle 已经有 memory 架构入口：

loadRunMemory?(run)
loadProjectMemory?(run)
saveRunMemory?(run)

但默认实现是 createNoopMemory()：

• loadRunMemory() 返回空
• loadProjectMemory() 返回空
• saveRunMemory() 不做任何事

也就是说 memory 目前只是“接入了架构”，但默认没有真实持久化能力。

现有不足：

• 默认不存储任何记忆
• memory 没有结构化 schema
• 用户偏好、项目事实、架构决策、工具经验没有分类
• memory 加载偏全量，没有相关性筛选
• 没有 source、confidence、status，无法判断可信度和是否过期
• saveRunMemory(run) 没有默认提取策略

思路

Memory 不应该保存完整聊天记录，而应该沉淀经过筛选的长期有价值信息。

例如：

• 用户偏好
• 项目结构事实
• 架构决策
• 工具使用经验
• 测试 / verification 命令经验
• 失败教训
• 代码约定

目标链路：

Run / Tool Results / Workspace
  ↓
MemoryExtractor
  ↓
MemoryEvaluator
  ↓
MemoryStore
  ↓
MemoryRetriever
  ↓
ContextManager

设计

1. 定义 Memory Scope

type MemoryScope = "user" | "project" | "session";

说明：

user:
- 用户长期偏好

project:
- 项目结构
- 架构决策
- 工具命令
- 代码约定

session:
- 当前任务状态
- 已读文件
- 已改文件
- 失败尝试

2. 定义 MemoryItem

type MemoryItem = {
  id: string;
  scope: "user" | "project" | "session";
  kind:
    | "user_preference"
    | "project_fact"
    | "architecture_decision"
    | "tool_lesson"
    | "failure_lesson"
    | "code_convention";

  content: string;

  source: {
    type: "user" | "assistant" | "tool" | "system";
    runId?: string;
    filePath?: string;
  };

  confidence: number;
  priority: number;
  tags: string[];
  relatedFiles?: string[];

  createdAt: number;
  updatedAt: number;
  status: "active" | "stale" | "superseded" | "archived";
};

3. 实现 FileMemoryStore

第一版不引入数据库或向量库，使用本地 JSON 文件：

.pixelle/memory/project.json
.pixelle/memory/sessions/{sessionId}.json

后续可以替换为 SQLite、向量库或远程 memory provider。

4. 实现 Memory Retriever

Memory 不应该全量进入 prompt。

第一版使用简单规则检索：

• priority
• confidence
• tags
• kind
• active files
• task keywords
• status

默认只返回 top N 条相关 memory。

5. 实现 Memory Extraction

在 run 结束前，从本轮运行中提取候选记忆：

• 用户明确偏好
• 项目稳定事实
• 架构决策
• 成功 / 失败的工具经验
• verification/test 命令经验

不保存：

• 大段日志
• 一次性报错
• 未验证的模型猜测
• 过于泛化的信息

方案

• 定义 MemoryItem、MemoryScope、MemoryKind
• 实现 FileMemoryStore
• 支持 project/session memory 持久化
• 实现 MemoryRetriever，根据当前任务召回相关 memory
• 实现 MemoryExtractor，从 AgentRunState 中提取候选记忆
• 实现 MemoryEvaluator，决定 save / merge / discard
• 将 memory 接入 ContextManager
• 保留 createNoopMemory()，保证默认兼容
• 后续支持 SQLite / vector store 扩展

验收标准

• 默认可启用本地文件型 memory
• project memory 可写入 .pixelle/memory/project.json
• session memory 可写入 .pixelle/memory/sessions/{sessionId}.json
• memory item 具有 scope / kind / source / confidence / status
• memory 不再全量进入 prompt
• ContextManager 只注入当前任务相关 memory
• 支持 stale / superseded，避免过期记忆污染上下文
• 保持 memory 模块可插拔