{"title":"记忆模型","slug":"memory-model","category":"concepts","summary":"记忆的结构 — 分类、键、标签、优先级、来源、验证。","audience":["human","llm"],"tags":["concept","memory","model","structure"],"difficulty":"intermediate","updated":"2026-06-27","word_count":424,"read_minutes":2,"lang":"zh","translated":true,"requested_lang":"zh","content_markdown":"\n# 记忆模型\n\nSynapse 的记忆模型专为 LLM Agent 设计 — 既结构化以保证可靠回放，又足够灵活以适应任何领域。\n\n## 记忆结构\n\n```json\n{\n \"id\": \"mem_abc123\",\n \"category\": \"project\",\n \"key\": \"project_synapse_status\",\n \"content\": \"Synapse v1.5.0 deployed on vps1. CI green.\",\n \"tags\": [\"synapse\", \"deployment\", \"v1.5.0\"],\n \"priority\": \"high\",\n \"source\": \"agent\",\n \"verified\": false,\n \"confidence\": 0.85,\n \"expires_at\": null,\n \"mind_id\": \"m_xyz789\",\n \"created_at\": \"2026-06-27T...\",\n \"updated_at\": \"2026-06-27T...\"\n}\n```\n\n## 字段\n\n| 字段 | 类型 | 必填 | 说明 |\n|-------|------|----------|-------------|\n| `id` | string | 自动 | 唯一 ID（mem_xxx） |\n| `category` | enum | ✅ | 8 种分类之一 |\n| `key` | string | ✅ | 稳定标识符（用于更新） |\n| `content` | string | ✅ | 记忆内容（任意文本） |\n| `tags` | string[] | – | 用于搜索和过滤 |\n| `priority` | enum | – | low、normal、high、critical（默认：normal） |\n| `source` | enum | 自动 | user、agent（存储者） |\n| `verified` | bool | 自动 | 是否经过人类验证 |\n| `confidence` | float | – | 0.0 到 1.0（user 默认 1.0，agent 默认 0.7） |\n| `expires_at` | timestamp | – | 何时遗忘此记忆 |\n| `mind_id` | string | 自动 | 所属 Mind |\n| `created_at` | timestamp | 自动 | 首次存储时间 |\n| `updated_at` | timestamp | 自动 | 最后修改时间 |\n\n## 分类\n\n八种分类覆盖了常见的 LLM Agent 用例：\n\n| 分类 | 用途 | 内容示例 |\n|----------|---------|-----------------|\n| `identity` | 用户是谁 | \"User is Michael Schäfer, software engineer in Berlin\" |\n| `preference` | 用户偏好 | \"Prefers concise technical responses\" |\n| `fact` | 可验证的事实 | \"Office is in Berlin, timezone Europe/Berlin\" |\n| `project` | 项目状态 | \"Synapse v1.5.0 deployed, working on v1.6.0 docs\" |\n| `skill` | 用户的技能 | \"Advanced Python, 10+ years\" |\n| `mistake` | 过去犯的错 | \"Forgot to bump npm version — CI failed\" |\n| `context` | 会话上下文 | \"Currently reviewing PR #42\" |\n| `note` | 其他备注 | \"Try Redis for caching next sprint\" |\n\n## Key：稳定标识符\n\n`key` 字段至关重要 — 它是更新记忆而不产生重复的方式。\n\n```python\n# 首次存储\nstore(\"project\", \"project_synapse_status\", \"v1.4.0 deployed\", priority=\"high\")\n\n# 用相同的 key 更新（覆盖，不重复）\nstore(\"project\", \"project_synapse_status\", \"v1.5.0 deployed\", priority=\"high\")\n```\n\n**Key 规则：**\n\n- 在 (category, mind) 内必须唯一\n- 使用 `snake_case`\n- 以分类为前缀提高可读性：`preference_communication`、`mistake_npm_version`\n- 创建后不要修改 key\n\n## Tags：用于搜索\n\n标签可加速过滤与搜索：\n\n```bash\n# 查找所有带 \"docker\" 标签的记忆\nGET /memory/by-tag?tag=docker\n\n# 在带标签的子集中进行 FTS5 搜索\nGET /memory/search?q=swarm&tag=docker\n```\n\n**标签最佳实践：**\n\n- 每条记忆 2-5 个标签（不要过度打标签）\n- 使用小写以保持一致\n- 使用项目名、主题、技术名\n- 标签不区分大小写\n\n## 优先级\n\n| 优先级 | 何时使用 | 回放行为 |\n|----------|-------------|-----------------|\n| `critical` | 身份、法律、不可逆信息 | 始终位于回放顶部 |\n| `high` | 进行中的项目、关键偏好 | 回放中突出显示 |\n| `normal` | 大多数记忆（默认） | 标准回放顺序 |\n| `low` | 临时、知道就好的信息 | 可能被摘要 |\n\n`/memory/recall` 按优先级排序（critical 在前），其次按时间。\n\n## 来源：User 与 Agent\n\n记忆用 `source` 标记：\n\n- `user` — 由人类存储（通过 JWT 或人类 UI）\n- `agent` — 由 LLM Agent 存储（通过 Mind Key）\n\n这会影响：\n\n- **验证**：`user` 记忆自动验证，`agent` 记忆不自动验证\n- **置信度**：`user` 默认 1.0，`agent` 默认 0.7\n- **回放**：`/memory/recall` 会标记未验证记忆为 \"(unverified)\"\n\n> [!NOTE]\n> 对 `agent` 来源的记忆应保持适当的怀疑。它们可能是推断或假设而来，而非用户直接陈述。\n\n## 验证\n\n`verified` 标志表示人类已确认该记忆：\n\n- `user` 记忆：自动验证（`true`）\n- `agent` 记忆：默认未验证（`false`）\n\n通过以下方式验证记忆：\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \\\n -H \"Authorization: Bearer YOUR_JWT\"\n```\n\n> [!NOTE]\n> 验证需要 JWT（人类认证），而非 Mind Key（Agent 认证）。这确保只有人类才能将记忆标记为已验证。\n\n## 置信度\n\n`confidence` 字段（0.0 到 1.0）表示记忆的可靠程度：\n\n- 1.0 — 用户直接陈述\n- 0.7 — 由 Agent 推断\n- 0.5 — 不确定，需要验证\n- 0.0 — 明确存疑\n\n存储时设置置信度：\n\n```json\n{\n \"category\": \"preference\",\n \"key\": \"prefers_dark_mode\",\n \"content\": \"User seems to prefer dark mode (based on their IDE screenshots)\",\n \"confidence\": 0.5,\n \"source\": \"agent\"\n}\n```\n\n## 过期\n\n为时效性记忆设置 `expires_at`：\n\n```json\n{\n \"category\": \"context\",\n \"key\": \"current_meeting_topic\",\n \"content\": \"Discussing Q3 roadmap\",\n \"expires_at\": \"2026-06-28T00:00:00Z\"\n}\n```\n\n已过期的记忆不会出现在 `/memory/recall` 中（但仍在数据库中）。使用 `/memory/expiring?within=7d` 查看即将过期的记忆。\n\n## 记忆生命周期\n\n```\n ┌─────────────────┐\n │ 创建 │\n │ POST /memory │\n └────────┬────────┘\n │\n ▼\n ┌─────────────────┐\n │ 活跃 │ ◀──── PUT /memory/:id (更新)\n │ (在回放中) │\n └────────┬────────┘\n │\n ┌────────────┼────────────┐\n │ │ │\n ▼ ▼ ▼\n ┌──────────┐ ┌──────────┐ ┌──────────┐\n │ 已过期 │ │ 已验证 │ │ 已删除 │\n │ (在 DB) │ │ (标志) │ │ (已消失) │\n └──────────┘ └──────────┘ └──────────┘\n```\n\n## 回放行为\n\n`GET /memory/recall` 返回为 LLM 上下文优化的纯文本摘要：\n\n```\nMind: Michael's Mind\nMemories: 12 total (10 verified, 2 unverified)\n\n[001] identity (CRITICAL) [verified]\n user_name\n Michael Schäfer\n Tags: person, identity\n\n[002] preference (HIGH) [verified]\n communication_style\n Prefers concise technical responses\n Tags: communication\n\n[003] project (HIGH) [unverified]\n synapse_status\n v1.5.0 deployed, working on v1.6.0 docs\n Tags: synapse, deployment\n\n...\n```\n\n- 按优先级排序（critical → low），其次按时间\n- 未验证记忆用 `[unverified]` 标记\n- 包含标签以提供上下文\n- 纯文本（无需解析 JSON）\n\n## 下一步\n\n- [Memory API](/docs/api/memory)\n- [记忆最佳实践](/docs/guides/memory-best-practices)\n- [FTS5 搜索](/docs/concepts/fts5-search)\n","content_html":"

记忆模型

\n

Synapse 的记忆模型专为 LLM Agent 设计 — 既结构化以保证可靠回放，又足够灵活以适应任何领域。

\n

记忆结构

\n
{\n  "id": "mem_abc123",\n  "category": "project",\n  "key": "project_synapse_status",\n  "content": "Synapse v1.5.0 deployed on vps1. CI green.",\n  "tags": ["synapse", "deployment", "v1.5.0"],\n  "priority": "high",\n  "source": "agent",\n  "verified": false,\n  "confidence": 0.85,\n  "expires_at": null,\n  "mind_id": "m_xyz789",\n  "created_at": "2026-06-27T...",\n  "updated_at": "2026-06-27T..."\n}

字段

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
字段类型必填说明
idstring自动唯一 ID（mem_xxx）
categoryenum✅8 种分类之一
keystring✅稳定标识符（用于更新）
contentstring✅记忆内容（任意文本）
tagsstring[]–用于搜索和过滤
priorityenum–low、normal、high、critical（默认：normal）
sourceenum自动user、agent（存储者）
verifiedbool自动是否经过人类验证
confidencefloat–0.0 到 1.0（user 默认 1.0，agent 默认 0.7）
expires_attimestamp–何时遗忘此记忆
mind_idstring自动所属 Mind
created_attimestamp自动首次存储时间
updated_attimestamp自动最后修改时间
\n

分类

\n

八种分类覆盖了常见的 LLM Agent 用例：

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
分类用途内容示例
identity用户是谁"User is Michael Schäfer, software engineer in Berlin"
preference用户偏好"Prefers concise technical responses"
fact可验证的事实"Office is in Berlin, timezone Europe/Berlin"
project项目状态"Synapse v1.5.0 deployed, working on v1.6.0 docs"
skill用户的技能"Advanced Python, 10+ years"
mistake过去犯的错"Forgot to bump npm version — CI failed"
context会话上下文"Currently reviewing PR #42"
note其他备注"Try Redis for caching next sprint"
\n

Key：稳定标识符

\n

key 字段至关重要 — 它是更新记忆而不产生重复的方式。

\n
# 首次存储\nstore("project", "project_synapse_status", "v1.4.0 deployed", priority="high")\n\n# 用相同的 key 更新（覆盖，不重复）\nstore("project", "project_synapse_status", "v1.5.0 deployed", priority="high")

Key 规则：

\n\n

Tags：用于搜索

\n

标签可加速过滤与搜索：

\n
# 查找所有带 "docker" 标签的记忆\nGET /memory/by-tag?tag=docker\n\n# 在带标签的子集中进行 FTS5 搜索\nGET /memory/search?q=swarm&tag=docker

标签最佳实践：

\n\n

优先级

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
优先级何时使用回放行为
critical身份、法律、不可逆信息始终位于回放顶部
high进行中的项目、关键偏好回放中突出显示
normal大多数记忆（默认）标准回放顺序
low临时、知道就好的信息可能被摘要
\n

/memory/recall 按优先级排序（critical 在前），其次按时间。

\n

来源：User 与 Agent

\n

记忆用 source 标记：

\n\n

这会影响：

\n\n
对 `agent` 来源的记忆应保持适当的怀疑。它们可能是推断或假设而来，而非用户直接陈述。

验证

\n

verified 标志表示人类已确认该记忆：

\n\n

通过以下方式验证记忆：

\n
curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \\\n  -H "Authorization: Bearer YOUR_JWT"
验证需要 JWT（人类认证），而非 Mind Key（Agent 认证）。这确保只有人类才能将记忆标记为已验证。

置信度

\n

confidence 字段（0.0 到 1.0）表示记忆的可靠程度：

\n\n

存储时设置置信度：

\n
{\n  "category": "preference",\n  "key": "prefers_dark_mode",\n  "content": "User seems to prefer dark mode (based on their IDE screenshots)",\n  "confidence": 0.5,\n  "source": "agent"\n}

过期

\n

为时效性记忆设置 expires_at：

\n
{\n  "category": "context",\n  "key": "current_meeting_topic",\n  "content": "Discussing Q3 roadmap",\n  "expires_at": "2026-06-28T00:00:00Z"\n}

已过期的记忆不会出现在 /memory/recall 中（但仍在数据库中）。使用 /memory/expiring?within=7d 查看即将过期的记忆。

\n

记忆生命周期

\n
                  ┌─────────────────┐\n                  │     创建        │\n                  │  POST /memory   │\n                  └────────┬────────┘\n                           │\n                           ▼\n                  ┌─────────────────┐\n                  │     活跃        │ ◀──── PUT /memory/:id (更新)\n                  │  (在回放中)     │\n                  └────────┬────────┘\n                           │\n              ┌────────────┼────────────┐\n              │            │            │\n              ▼            ▼            ▼\n        ┌──────────┐ ┌──────────┐ ┌──────────┐\n        │ 已过期   │ │ 已验证   │ │ 已删除   │\n        │ (在 DB)  │ │ (标志)   │ │ (已消失) │\n        └──────────┘ └──────────┘ └──────────┘

回放行为

\n

GET /memory/recall 返回为 LLM 上下文优化的纯文本摘要：

\n
Mind: Michael's Mind\nMemories: 12 total (10 verified, 2 unverified)\n\n[001] identity (CRITICAL) [verified]\n  user_name\n  Michael Schäfer\n  Tags: person, identity\n\n[002] preference (HIGH) [verified]\n  communication_style\n  Prefers concise technical responses\n  Tags: communication\n\n[003] project (HIGH) [unverified]\n  synapse_status\n  v1.5.0 deployed, working on v1.6.0 docs\n  Tags: synapse, deployment\n\n...
\n

下一步

\n\n","urls":{"html":"/docs/concepts/memory-model","text":"/docs/concepts/memory-model?format=text","json":"/docs/concepts/memory-model?format=json","llm":"/docs/concepts/memory-model?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}