---

slug: "memory-orchestrator-v2"
name: "memory-orchestrator-v2"
version: 1.0.1
displayName: "记忆编排器"
summary: "解决分层不清、摘要不稳、并发冲突、无健康度指标的智能记忆编排器。记忆编排器是面向 AI Agent 的智能记忆管理系统，针对"分层体系不够清晰、自动摘要质量不稳定、并发写入冲突、缺乏记忆健康"
license: "Proprietary"
description: |-
  记忆编排器是面向 AI Agent 的智能记忆管理系统，针对"分层体系不够清晰、自动摘要质量不稳定、并发写入冲突、缺乏记忆健康度指标"四大高频痛点而设计。它用四层记忆架构（工作/短期/长期/重要）与多模式检索，提供从存储到检索到摘要的全生命周期编排，让 Agent 记忆真正可控可观测。Use when 需要AI模型调用、智能对话、Agent编排、LLM应用时使用。不适用于需要100%确定性的关键决策.
tags: 记忆编排器,四层记忆架构,多模式检索,自动摘要,健康度仪表盘,并发冲突
tools:
  - read
  - exec
  - write
  - glob
  - grep
homepage: ""
category: "Agents"

---

# 记忆编排器（Memory Orchestrator）
面向 AI Agent 的**智能记忆管理系统**，用四层记忆架构与多模式检索，提供从存储到检索到摘要的全生命周期编排，让 Agent 记忆真正可控可观测.
## 设计动机：四大高频痛点
| 痛点 | 典型表现 | 本技能对策 |
|---|----|-----|
| 分层体系不清 | 短期/长期混在一起，重要信息被淹没 | 四层架构：工作/短期/长期/重要，独立策略 |
| 自动摘要质量不稳 | 摘要丢关键信息或过于冗长 | 摘要质量评估器，信息保留率+可读性双指标 |
| 并发写入冲突 | 多 Agent 同时写记忆，互相覆盖 | 乐观锁 + 版本合并，安全并发 |
| 缺乏健康度指标 | 记忆多少、命中率、陈旧度全凭感觉 | 健康度仪表盘，四维量化+主动告警 |

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

### 层级流转规则
```text
写入 → 工作记忆（容量 20）
         │
         ├─ 超限 → 自动晋升到短期记忆
         │
         └─ 标记重要 → 直接晋升到重要记忆
# ...
短期记忆（容量 100）
         │
         ├─ 超限 → FIFO 淘汰最旧（移到长期或删除）
         │
         ├─ 标记重要 → 晋升到重要记忆
         │
         └─ 7 天未访问 → 自动归档到长期记忆
# ...
长期记忆
         │
         ├─ 被引用 → 临时提升到短期（LRU）
         │
         └─ 180 天未引用 → 提示归档/遗忘
# ...
重要记忆
         │
         └─ 永不清理，仅可手动修改
```

## 使用流程
1. 阅读## 核心能力章节了解skill功能
2. 按## 依赖说明配置环境
3. 执行所需能力对应的命令
4. 参考## 错误处理章节处理异常
5. 查看## FAQ解答常见疑问

### 添加记忆
```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"
});
```

## 快速开始

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

> 详细的输入输出格式请参考下方章节说明。

## 参数说明
| 参数 | 类型 | 必填 | 说明 |
|:-----|:-----|:-----|:-----|
| 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 条，避免内存溢出
- 模块化设计，可轻松对接向量数据库实现语义检索
- 全链路类型安全，参数自动校验
- 轻量无外部依赖，开箱即用，也支持自定义扩展
- 并发安全，乐观锁 + 版本合并
- 持久化支持内存与磁盘，重启不丢失

## 错误处理

| 序号 | 错误场景 | 原因 | 处理方式 | 优先级 |
|:------:|--------|:-------|:------:|--------|
| 1 | 输入参数缺失 | 用户未提供必要参数 | 提示用户提供所需参数后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令 | P0 |
| 2 | 执行超时 | 处理时间过长 | 检查输入数据量,分批处理 | P1 |
| 3 | 输出格式错误 | 结果不符合预期格式 | 检查`output_format`参数配置 | P1 |

## 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 管理四层记忆系统

## 核心能力
### 记忆编排器是面向 AI Agent 的智
记忆编排器是面向 AI Agent 的智能记忆管理系统，针对"分层体系不够清晰、自动摘要质量不稳定、并发写入冲突、缺乏记忆健康度指标"四大高频痛点而设计

**输入**: 用户提供记忆编排器是面向 AI Agent 的智所需的指令和必要参数.
**处理**: 解析记忆编排器是面向 AI Agent 的智的输入参数,完成核心逻辑,返回结构化响应.
**输出**: 返回记忆编排器是面向 AI Agent 的智的响应数据,包含状态码、结果和日志.
- 执行此能力时使用`input_params`参数,支持创建/查询/导出操作

### 它用四层记忆架构（工作/短期/长期/重要
它用四层记忆架构（工作/短期/长期/重要）与多模式检索，提供从存储到检索到摘要的全生命周期编排，让 Agent 记忆真正可控可观测

**输入**: 用户提供它用四层记忆架构（工作/短期/长期/重要所需的指令和必要参数.
**处理**: 解析它用四层记忆架构（工作/短期/长期/重要的输入参数,完成核心逻辑,返回结构化响应.
**输出**: 返回它用四层记忆架构（工作/短期/长期/重要的响应数据,包含状态码、结果和日志.
- 执行此能力时使用`input_params`参数,支持创建/查询/导出操作

### 适用场景
适用场景：长会话 Agent、聊天机器人上下文管理、RAG 应用记忆层、任务型 Agent 长期记忆、客服助理上下文治理、多 Agent 共享记忆

**输入**: 用户提供适用场景所需的指令和必要参数.
**处理**: 解析适用场景的输入参数,完成核心逻辑,返回结构化响应.
**输出**: 返回适用场景的响应数据,包含状态码、结果和日志.
- 执行此能力时使用`input_params`参数,支持创建/查询/导出操作

### 差异化
差异化：相比仅提供"add/search/summarize"的基础管理器，本技能新增 (1) 四层记忆架构，工作/短期/长期/重要四层清晰分工，每层独立容量与清理策略

**输入**: 用户提供差异化所需的指令和必要参数.
**处理**: 解析差异化的输入参数,完成核心逻辑,返回结构化响应.
**输出**: 返回差异化的响应数据,包含状态码、结果和日志.
- 执行此能力时使用`input_params`参数,支持创建/查询/导出操作

### (2) 记忆健康度仪表盘
(2) 记忆健康度仪表盘，量化容量、分布、命中率、陈旧度四维指标，主动告警

**输入**: 用户提供(2) 记忆健康度仪表盘所需的指令和必要参数.
**处理**: 解析(2) 记忆健康度仪表盘的输入参数,完成核心逻辑,返回结构化响应.
**输出**: 返回(2) 记忆健康度仪表盘的响应数据,包含状态码、结果和日志.
- 执行此能力时使用`input_params`参数,支持创建/查询/导出操作

**技术参数**：使用`input_params`和`output_format`参数控制执行行为,支持`json`/`text`/`csv`输出格式.
**能力覆盖范围**：本skill的核心能力覆盖以下场景关键词：解决分层不清、摘要不稳、并发冲突、无健康度指标的智、能记忆编排器、Use、when、模型调用、智能对话、LLM、应用时使用、不适用于需要、确定性的关键决策等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持.
## 适用场景(补充)
### 场景一：长会话上下文管理(补充)
```text
用户："这个会话已经聊了 30 轮，上下文快爆了"
# ...
流程：
1. summarize 短期记忆（保留关键决策与待办）
2. 压缩后的摘要替换原始短期记忆
3. 工作记忆仅保留最近 5 轮
4. 继续会话
5. token 占用减少 70%
```

## 已知限制
- 需LLM支持,无LLM环境不可用
- 复杂业务场景建议结合人工经验判断
- 执行效率受模型能力与网络环境影响

## 输出格式
```json
{
  "success": true,
  "data": {
    "result": "记忆编排器处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "memory orchestrator v2"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}
```