记忆编排器（Memory Orchestrator）

面向 AI Agent 的智能记忆管理系统，用四层记忆架构与多模式检索，提供从存储到检索到摘要的全生命周期编排，让 Agent 记忆真正可控可观测。

设计动机：四大高频痛点

四层记忆架构

┌────────────────────────────────────────────────┐
│           四层记忆架构                          │
├────────────────────────────────────────────────┤
│                                                │
│  第四层：重要记忆（important）                  │
│          永不清理、最高优先级                   │
│          用户核心偏好、关键决策、身份信息       │
│          容量：无上限                           │
│                                                │
│  第三层：长期记忆（long-term）                  │
│          持久化存储、定期归档                   │
│          历史交互、项目背景、领域知识           │
│          容量：无上限（建议 < 10000）           │
│                                                │
│  第二层：短期记忆（short-term）                 │
│          最近活跃、自动清理                     │
│          当前会话上下文、近期决策               │
│          容量：上限 100 条（FIFO 淘汰）         │
│                                                │
│  第一层：工作记忆（working）                    │
│          当前任务上下文、超快读写               │
│          容量：上限 20 条（超限自动晋升短期）   │
│                                                │
└────────────────────────────────────────────────┘

层级流转规则

写入 → 工作记忆（容量 20）
         │
         ├─ 超限 → 自动晋升到短期记忆
         │
         └─ 标记重要 → 直接晋升到重要记忆

短期记忆（容量 100）
         │
         ├─ 超限 → FIFO 淘汰最旧（移到长期或删除）
         │
         ├─ 标记重要 → 晋升到重要记忆
         │
         └─ 7 天未访问 → 自动归档到长期记忆

长期记忆
         │
         ├─ 被引用 → 临时提升到短期（LRU）
         │
         └─ 180 天未引用 → 提示归档/遗忘

重要记忆
         │
         └─ 永不清理，仅可手动修改

快速开始（< 60 秒）

添加记忆

// 添加长期记忆
await skills.memoryOrchestrator({
  action: "add",
  content: "用户喜欢喝咖啡，不加糖，每周三下午喝奶茶",
  type: "long-term",
  persist: true
});

// 添加重要记忆（永不清理）
await skills.memoryOrchestrator({
  action: "add",
  content: "用户是项目负责人，最终决策权在用户",
  type: "important",
  persist: true
});

搜索记忆

const result = await skills.memoryOrchestrator({
  action: "search",
  query: "用户喜好",
  limit: 3,
  searchMode: "hybrid"  // 关键词+语义混合检索
});

生成会话摘要

const summary = await skills.memoryOrchestrator({
  action: "summarize",
  typeFilter: "short-term",
  maxTokens: 500
});

持久化与加载

// 保存所有记忆到磁盘
await skills.memoryOrchestrator({
  action: "save",
  persistPath: "./my-memory.json"
});

// 从磁盘加载记忆
await skills.memoryOrchestrator({
  action: "load",
  persistPath: "./my-memory.json"
});

参数说明

三模式检索

混合检索算法

score = keyword_score * 0.4 + semantic_score * 0.4 + recency_score * 0.1 + importance_score * 0.1

说明：
- keyword_score：关键词匹配（TF-IDF）
- semantic_score：语义相似度（有向量库时用 cosine，无则降级为关键词）
- recency_score：近期加权
- importance_score：重要度加权

自动摘要生成

摘要策略

1. 提取关键信息
   - 事件：时间、地点、参与者、结果
   - 决策：决策内容、原因、影响
   - 教训：问题、原因、规避方法
   - 待办：任务、优先级、截止时间

2. 压缩冗余
   - 去重复（相同信息只保留一次）
   - 去过程（保留结果，省略中间步骤）
   - 去客套（移除寒暄与无信息内容）

3. 结构化输出
   - 按类别分组
   - 层级列表呈现
   - 保留关键时间戳

摘要质量评估器

质量不达标处理：

• 保留率 < 90%：补充遗漏关键信息，重新生成
• 压缩比 < 3：加强去冗余
• 可读性 < 0.8：增加结构化层级
• 准确性 < 95%：校对事实性内容

记忆健康度仪表盘

const health = await skills.memoryOrchestrator({
  action: "health"
});

四维健康度指标

{
  "capacity": {
    "working": { "used": 18, "limit": 20, "utilization": 0.9 },
    "short_term": { "used": 87, "limit": 100, "utilization": 0.87 },
    "long_term": { "used": 342, "limit": null, "utilization": null },
    "important": { "used": 15, "limit": null, "utilization": null }
  },
  "distribution": {
    "by_type": { "preference": 45, "decision": 30, "fact": 20, "lesson": 15 },
    "by_age": { "last_7d": 60, "last_30d": 120, "older": 200 }
  },
  "hit_rate": {
    "last_7d": 0.72,
    "last_30d": 0.65,
    "trend": "improving"
  },
  "staleness": {
    "stale_count": 23,
    "stale_ratio": 0.06,
    "oldest_unaccessed_days": 45
  },
  "alerts": [
    { "level": "warning", "message": "工作记忆使用率 90%，建议晋升到短期" },
    { "level": "info", "message": "23 条长期记忆 30 天未访问，建议归档" }
  ]
}

告警规则

并发写入冲突解决

支持多 Agent 安全并发写入：

乐观锁机制

1. 读取记忆时获取版本号 version
2. 写入时携带 version
3. 若 version 与当前不匹配 → 冲突
4. 冲突时触发版本合并

版本合并策略

冲突类型 A：同条目不同字段修改
  → 字段级合并，各取所改

冲突类型 B：同条目同字段不同值
  → 保留两版本，标记冲突，等待用户裁决

冲突类型 C：同时新增不同条目
  → 无冲突，直接合并

冲突示例

Agent 1：更新用户偏好（version=3）→ "深色模式"
Agent 2：同时更新用户偏好（version=3）→ "自动切换"

冲突解决：
  → 保留两版本
  → 标记为冲突
  → 提示用户："检测到偏好冲突，请选择"
    [深色模式] [自动切换] [两者都记]

过期记忆自动清理

清理策略

清理日志

所有清理操作记录到 memory-cleanup.log：

2026-07-18T10:30:00Z | short-term→long-term | memory-id-123 | "用户偏好深色模式"
2026-07-18T10:31:00Z | long-term→archive | memory-id-456 | "旧项目背景"

模块化扩展接口

语义检索可插拔对接向量数据库：

// 配置向量数据库（可选）
await skills.memoryOrchestrator({
  action: "configure",
  semantic: {
    provider: "chroma",  // chroma | lancedb | qdrant | none
    path: "./.chroma",
    embeddingModel: "all-MiniLM-L6-v2"
  }
});

无向量数据库时：semantic 模式降级为关键词检索，不影响基本功能。

典型工作流（3 个真实场景）

场景一：长会话上下文管理

用户："这个会话已经聊了 30 轮，上下文快爆了"

流程：
1. summarize 短期记忆（保留关键决策与待办）
2. 压缩后的摘要替换原始短期记忆
3. 工作记忆仅保留最近 5 轮
4. 继续会话
5. token 占用减少 70%

场景二：多 Agent 共享记忆

场景：Agent A 与 Agent B 同时操作共享记忆库

流程：
1. Agent A 读取用户偏好（version=3）
2. Agent B 读取用户偏好（version=3）
3. Agent A 写入更新（version=3→4）
4. Agent B 写入更新（version=3，冲突！）
5. 触发版本合并
6. 字段级合并或标记冲突
7. 通知用户裁决（如需要）

场景三：记忆健康度巡检

心跳任务：每天检查记忆健康度

流程：
1. 调用 health 获取仪表盘
2. 检查告警项
3. 工作记忆 > 85%：触发晋升
4. 短期记忆 > 85%：触发归档
5. 陈旧率 > 10%：提示清理
6. 命中率 < 30%：提示优化检索策略
7. 生成健康度报告

技术实现说明

• 内置记忆自动清理机制，短期记忆上限 100 条，避免内存溢出
• 模块化设计，可轻松对接向量数据库实现语义检索
• 全链路类型安全，参数自动校验
• 轻量无外部依赖，开箱即用，也支持自定义扩展
• 并发安全，乐观锁 + 版本合并
• 持久化支持内存与磁盘，重启不丢失

FAQ

Q1：四层架构会不会太复杂？ A：不会。日常使用只需指定 type（默认 short-term），层级流转自动处理。四层架构的价值在于：重要信息不被淹没、短期记忆不爆、长期记忆可归档。

Q2：没有向量数据库能用语义检索吗？ A：可以，但会降级。semantic 模式在无向量库时退化为关键词检索，仍可用但召回率降低。接入向量库后效果最佳。

Q3：并发冲突频繁怎么办？ A：(1) 减少同一记忆的并发写入；(2) 不同 Agent 写不同记忆条目；(3) 必要时用锁机制串行化；(4) 冲突后及时人工裁决。

Q4：摘要质量评估器能保证摘要准确吗？ A：评估器检测信息保留率与准确性，不达标自动重试。但 100% 准确无法保证，建议关键场景人工复核摘要。

Q5：健康度仪表盘多久看一次？ A：建议每天看一次（心跳任务），重点关注告警项。每周做一次深度审查（分布、陈旧度趋势）。

故障排查

依赖说明

运行环境

• Agent 平台：支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
• 操作系统：Windows / macOS / Linux
• 运行时：Node.js（如用 TypeScript SDK）

第三方依赖

API Key 配置

• 本技能核心功能无需额外 API Key（LLM 由 Agent 平台提供）
• 语义检索增强（可选）如用云向量服务，需对应服务 Key

可用性分类

• 分类：MD+EXEC（纯 Markdown 指令，部分功能需 exec 执行持久化操作）
• 说明：基于 Markdown 的 AI Skill，通过自然语言指令驱动 Agent 管理四层记忆系统