记忆编排器

记忆编排器是面向 AI Agent 的智能记忆管理系统，针对"分层体系不够清晰、自动摘要质量不稳定、并发写入冲突、缺乏记忆健康度指标"四大高频痛点而设计。它用四层记忆架构（工作/短期/长期/重要）与多模式检索，提供从存储到检索到摘要的全生命周期编排，让 Agent 记忆真正可控可观测。 核心能力：四层记忆架构（工作记忆/短期记忆/长期记忆/重要记忆）、三模式检索（关键词/语义/混合）、自动摘要生成（支持长会话压缩，token 占用减少 70%）、持久化与加载（内存/磁盘）、记忆健康度仪表盘（容量/分布/命中率/陈旧度）、并发写入冲突解决（乐观锁+版本合并）、过期记忆自动清理、模块化扩展接口（可对接向量数据库）。 适用场景：长会话 Agent、聊天机器人上下文管理、RAG 应用记忆层、任务型 Agent 长期记忆、客服助理上下文治理、多 Agent 共享记忆。 差异化：相比仅提供"add/search/summarize"的基础管理器，本技能新增 (1) 四层记忆架构，工作/短期/长期/重要四层清晰分工，每层独立容量与清理策略；(2) 记忆健康度仪表盘，量化容量、分布、命中率、陈旧度四维指标，主动告警；(3) 并发写入冲突解决，乐观锁 + 版本合并，支持多 Agent 安全并发；(4) 摘要质量评估器，量化摘要的信息保留率与可读性，质量不达标自动重试；(5) 模块化扩展接口，语义检索可插拔对接向量数据库（Chroma/LanceDB/Qdrant）。 触发关键词：记忆编排、记忆管理、长期记忆、语义检索、记忆摘要、记忆持久化、memory manager、memory orchestration、semantic search

记忆编排器（Memory Orchestrator）

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

设计动机：四大高频痛点

痛点	典型表现	本技能对策
分层体系不清	短期/长期混在一起，重要信息被淹没	四层架构：工作/短期/长期/重要，独立策略
自动摘要质量不稳	摘要丢关键信息或过于冗长	摘要质量评估器，信息保留率+可读性双指标
并发写入冲突	多 Agent 同时写记忆，互相覆盖	乐观锁 + 版本合并，安全并发
缺乏健康度指标	记忆多少、命中率、陈旧度全凭感觉	健康度仪表盘，四维量化+主动告警

四层记忆架构

text

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

层级流转规则

text

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

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

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

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

快速开始（< 60 秒）

添加记忆

typescript

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

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

搜索记忆

typescript

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

生成会话摘要

typescript

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

持久化与加载

typescript

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

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

参数说明

参数	类型	必填	说明
action	string	是	操作类型：add/search/summarize/clear/list/load/save/health
content	string	否	add 操作必填，记忆内容
type	string	否	add 操作可选，记忆类型：working/short-term/long-term/important，默认 short-term
query	string	否	search 操作必填，搜索关键词
limit	number	否	search/list 操作可选，返回数量，默认 5/20
typeFilter	string	否	过滤记忆类型，默认 all
searchMode	string	否	检索模式：keyword/semantic/hybrid，默认 keyword
persist	boolean	否	add 操作可选，是否持久化，默认 false
persistPath	string	否	load/save 操作可选，持久化路径，默认 ./memory-store.json
importance	number	否	重要度 0-1，默认 0.5
tags	string[]	否	标签列表，便于检索
maxTokens	number	否	summarize 操作可选，摘要最大 token，默认 500

三模式检索

模式	适用场景	优势	依赖
keyword	精确匹配、快速检索	零依赖、快	无
semantic	语义相似、模糊查询	召回率高	需向量数据库（可选）
hybrid	综合检索、最佳效果	兼顾精确与召回	默认可用（语义部分降级为关键词）

混合检索算法

text

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：重要度加权

自动摘要生成

摘要策略

text

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

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

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

摘要质量评估器

指标	计算方法	及格线
信息保留率	摘要含关键信息数 / 原始关键信息数	>= 90%
压缩比	原始 token / 摘要 token	>= 3 倍
可读性	结构化程度（标题/列表/层级）	>= 0.8
准确性	摘要与原始内容一致性	>= 95%

质量不达标处理：

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

记忆健康度仪表盘

typescript

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

四维健康度指标

json

{
  "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 天未访问，建议归档" }
  ]
}

告警规则

指标	阈值	告警级别
工作记忆使用率	> 85%	warning
短期记忆使用率	> 85%	warning
命中率（7天）	< 30%	warning
陈旧率	> 10%	info
重要记忆被修改	任意	info（记录审计）

并发写入冲突解决

支持多 Agent 安全并发写入：

乐观锁机制

text

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

版本合并策略

text

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

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

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

冲突示例

text

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

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

过期记忆自动清理

清理策略

记忆类型	清理规则	清理动作
工作记忆	超 20 条	最旧的晋升到短期
短期记忆	超 100 条	FIFO 淘汰，移到长期或删除
短期记忆	7 天未访问	自动归档到长期
长期记忆	180 天未引用	提示归档/遗忘
长期记忆	含 expires_at 且过期	自动归档
重要记忆	永不清理	仅可手动修改

清理日志

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

text

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

模块化扩展接口

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

typescript

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

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

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

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

text

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

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

场景二：多 Agent 共享记忆

text

场景：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. 通知用户裁决（如需要）

场景三：记忆健康度巡检

text

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

流程：
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：建议每天看一次（心跳任务），重点关注告警项。每周做一次深度审查（分布、陈旧度趋势）。

故障排查

症状	可能原因	解决方案
搜索结果不准	检索模式不匹配	切换 searchMode，复杂查询用 hybrid
摘要丢信息	质量评估未达标	检查保留率，补充关键信息重试
并发写入失败	版本冲突	触发版本合并，必要时人工裁决
工作记忆爆满	未及时晋升	检查健康度，触发自动晋升
持久化失败	路径无权限	检查 persistPath 写入权限
语义检索不工作	未配置向量库	配置 semantic provider 或用 keyword 模式

依赖说明

运行环境

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

第三方依赖

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由 Agent 内置 LLM 提供
向量数据库（可选）	外部依赖	可选	Chroma / LanceDB / Qdrant，语义检索增强
Embedding 模型（可选）	模型	可选	all-MiniLM-L6-v2 等，配合向量库使用

API Key 配置

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

可用性分类

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