# Datadata Memory

> Manage AI persistent memory via the Datadata MCP Server — add, search, update, and delete memories, with semantic search and multi-dimensional filtering. Use when the user wants the AI to remember information, recall previous conversations, or manage persistent knowledge. Triggers: remember, memory, recall, don't forget, note this down, previously mentioned, search memory, delete memory.

- Skill: `datadata-team/datadata-memory` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add datadata-team/datadata-memory`
- Raw SKILL.md: https://api.skillmd.com/api/skills/datadata-team/datadata-memory/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: datadata-team (https://skillmd.com/u/datadata-team)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/datadata-team/datadata-memory

---


## 功能概览

本 skill 通过 **Datadata MCP Server** 的记忆工具管理 AI 持久化记忆。记忆是跨会话保留的原子事实、偏好或知识点，Agent 可在后续对话中检索使用。

- **添加记忆** — 存储原子事实，支持标签、分类、元数据（异步索引）
- **搜索记忆** — 关键词或语义搜索，支持按时间、分类、Agent、会话等多维度过滤
- **更新记忆** — 修正或补充已有记忆内容
- **合并压缩** — 检测相似记忆并合并为一条，消除冗余
- **冲突合并** — 发现信息冲突时保留最新、记录历史
- **删除记忆** — 按 ID 移除过时或错误的记忆

## MCP 工具速查

| 工具               | 用途                 | 关键参数                                                                                        |
| ------------------ | -------------------- | ----------------------------------------------------------------------------------------------- |
| `memory_add`       | 添加新记忆（异步）   | `content`（必填）, `category`, `tags`, `agentId`, `metadata`                                    |
| `memory_search`    | 搜索记忆             | `search`（必填）, `limit`, `offset`, `agentId`, `category`, `sessionId`, `startTime`, `endTime` |
| `memory_update`    | 更新已有记忆（异步） | `id`（必填）, `content`（必填）, `tags`, `category`, `agentId`, `metadata`                      |
| `memory_delete`    | 删除记忆             | `id`（必填）                                                                                    |
| `memory_task_wait` | 等待异步任务完成     | `taskId`（必填）, `timeout`（秒，默认 60）                                                      |

> **注意**：所有工具名前缀为 `mcp_datadata_`，如 `mcp_datadata_memory_add`。文档中省略前缀以保持简洁。

## 概念

### 记忆范围（Scope）

| 范围       | 说明                                | 使用场景                     |
| ---------- | ----------------------------------- | ---------------------------- |
| 用户全局   | 不指定 `agentId`，跨所有 Agent 可见 | 用户偏好、通用知识、项目约定 |
| Agent 专属 | 指定 `agentId`，仅特定 Agent 可检索 | Agent 专属上下文、任务状态   |

### 记忆属性

| 属性       | 说明                         | 示例                               |
| ---------- | ---------------------------- | ---------------------------------- |
| `content`  | 原子事实或偏好，一句话说清楚 | "用户偏好使用中文提交信息"         |
| `category` | 自定义分类，用于组织和过滤   | `"preferences"`, `"project-notes"` |
| `tags`     | 可搜索标签数组               | `["git", "convention"]`            |
| `metadata` | 键值对附加信息               | `{"project": "datadata-skills"}`   |

### 异步索引

`memory_add` 和 `memory_update` 是**异步操作**。调用后返回 `taskId`，记忆进入索引队列。在索引完成前，新添加的记忆**不会出现在搜索结果中**。

> 绝大多数情况下索引在毫秒级完成，无需显式等待。`memory_task_wait` 仅作为**保险措施**，在以下场景才需要调用：
>
> - 添加/更新后**立即**要在同一轮对话中搜索该记忆
> - 合并压缩/冲突合并后需要验证结果
>
> 日常添加/更新操作直接调用 `memory_add` / `memory_update` 即可，不必跟 `memory_task_wait`。

## 工作流

### 添加记忆

```
用户要求记住某事 → memory_add → 确认完成
```

> 如需立即检索刚添加的记忆，可在 `memory_add` 后调用 `memory_task_wait` 确保索引完成。

**示例**：

```
用户："记住我喜欢用中文写 commit message"
→ memory_add(content="用户偏好使用中文编写 Git 提交信息", category="preferences", tags=["git", "commit", "chinese"])
→ 确认："已记住。"
```

**原则**：

- 每条记忆应为**单一原子事实**，不要塞多个不相关信息
- 添加前先 `memory_search` 检查是否已有类似记忆，避免重复
- 选择合适的 `category` 便于后续过滤

### 搜索记忆

```
用户询问过去信息 → memory_search → 返回相关记忆
```

**搜索策略**：

| 场景             | 方法                                               |
| ---------------- | -------------------------------------------------- |
| 关键词精确匹配   | `search="关键词"`                                  |
| 语义相关         | 使用自然语言描述，如 `search="用户的编码偏好"`     |
| 限定分类         | 加 `category="preferences"`                        |
| 限定时间范围     | 加 `startTime` / `endTime`（RFC3339 格式）         |
| 首次对话了解用户 | `memory_search(search="用户偏好和习惯", limit=10)` |

**优先级**：搜索记忆应在新对话开始时进行，以获取用户上下文。Agent 应在处理用户请求前检查相关记忆。

### 更新记忆

```
用户纠正或补充信息 → memory_update(id=<记忆ID>, content="修正后的内容") → 确认完成
```

> 如需立即检索更新后的记忆，可调用 `memory_task_wait` 确保索引完成。

**何时更新**：

- 用户明确纠正之前的说法："不对，我之前说的..."
- 信息已过时需要刷新
- 补充更多细节

### 合并压缩

当添加新记忆时，搜索发现存在**语义相似**的已有记忆，应将两者合并为一条，避免信息碎片化。

**触发条件**：`memory_add` 前的 `memory_search` 返回高度相关的结果（语义相似度 > 80%）

**流程**：

```
memory_search(新内容摘要) → 发现相似记忆
    ↓
合并内容（保留所有不重复信息）→ memory_update(已有记忆ID, 合并后内容)
    ↓
（可选）memory_task_wait → 确认合并完成
```

**合并原则**：

| 场景                   | 处理方式                           |
| ---------------------- | ---------------------------------- |
| 新信息是已有信息的子集 | 不操作，已有记忆已覆盖             |
| 新信息是已有信息的超集 | `memory_update` 替换为更完整的版本 |
| 新信息与已有信息互补   | 合并为一条，用分号或编号整合       |
| 新信息与已有信息重复   | 不操作，跳过添加                   |

**示例**：

```
已有："用户偏好使用中文编写 Git 提交信息"
新增："用户用 AngularJS 风格写 commit，类型有 feat/fix/docs 等"
→ 合并为："用户偏好使用中文编写 Git 提交信息，遵循 AngularJS 风格（feat/fix/docs/chore 等）"
```

### 冲突合并

当新信息与已有记忆**矛盾**（如用户先说电话是 1111，后又说电话是 2222），应以最新信息为准，同时保留变更历史。

**触发条件**：`memory_add` 前搜索发现语义相似但**内容矛盾**的记忆

**流程**：

```
memory_search → 发现冲突记忆
    ↓
将旧值写入 metadata.history，用新值更新 content
    ↓
memory_update(id, content="最新值", metadata={..., "history": [{"value": "旧值", "updatedAt": "..."}]})
    ↓
（可选）memory_task_wait → 确认
```

**metadata.history 格式**：

```json
{
  "history": [
    { "value": "电话: 1111", "updatedAt": "2026-06-01T10:00:00Z" },
    { "value": "电话: 2222", "updatedAt": "2026-06-10T14:00:00Z" }
  ]
}
```

> `history` 数组按时间倒序，最新在前。每次冲突合并时追加一条记录。

**判定冲突的标准**：

- 同一主题下的事实性信息不一致（电话号码、地址、版本号等）
- 用户明确说"不对，我之前说的..."或"改一下，应该是..."
- 偏好或习惯发生明确变化（"我现在不用 VS Code 了，改用 Fleet"）

**不是冲突的情况**（应合并压缩而非冲突合并）：

- 对同一主题的补充说明（不矛盾）
- 不同上下文的不同选择（"项目 A 用 pnpm，项目 B 用 yarn"）

### 删除记忆

```
用户要求忘记某事 / 记忆明显错误 → memory_delete(id=<记忆ID>)
```

删除是**同步操作**，无需等待索引。不可逆，执行前应确认。

## 规则

### 🟡 添加前先搜索，避免重复

调用 `memory_add` 前应先 `memory_search` 检查是否已有相似记忆。若存在相关记忆，优先 `memory_update` 更新而非重复添加。

### 🟡 仅在需要时等待索引

`memory_add` 和 `memory_update` 的索引通常在毫秒级完成，**无需每次都调用 `memory_task_wait`**。仅当需要在同一轮对话中**立即检索**刚添加/更新的记忆时才调用，作为保险措施。

### 🟡 记忆内容应原子化

每条记忆只包含一个独立事实。反面示例：

```
❌ "用户偏好中文 commit、喜欢用 VS Code、项目使用 TypeScript"
✅ "用户偏好使用中文编写 Git 提交信息"
✅ "用户使用 VS Code 作为主力编辑器"
✅ "项目 datadata-skills 使用 TypeScript"
```

### 🟡 搜索优先于猜测

当用户问"我之前说过..."或需要上下文时，**必须先搜索记忆**，不要凭当前对话猜测。

### 🟡 删除需确认

在 `memory_delete` 前，向用户展示要删除的记忆内容并请求确认。记忆删除不可逆。

## 常见问题

### Q: 添加记忆后搜索不到？

索引通常在毫秒级完成，极少数情况下可能需要几秒。若添加后立即搜索不到，可调用 `memory_task_wait` 等待索引完成后再试。

### Q: 搜索返回太多结果？

使用过滤参数缩小范围：`category`、`agentId`、`startTime`/`endTime`、或减小 `limit`。

### Q: 如何区分 tags 和 metadata？

- `tags`：用于搜索过滤的简短标签，会建立索引
- `metadata`：附加键值对，用于存储不参与搜索过滤的补充信息

### Q: 记忆和 session memory 有什么区别？

- **Datadata 记忆**（本 skill）：持久化存储，跨会话、跨 Agent 保留
- **Session memory**（`/memories/session/`）：仅当前会话有效，会话结束后清除

## References

| 文档                                                         | 说明                             |
| ------------------------------------------------------------ | -------------------------------- |
| [./references/memory-guide.md](./references/memory-guide.md) | 搜索策略、索引机制、最佳实践详解 |