{"title":"Memory API","slug":"memory","category":"api","summary":"22 个记忆端点的完整参考：存储、回放、搜索、语义搜索、同步、审计等。","audience":["human","llm"],"tags":["api","memory","crud","search","fts5","semantic"],"difficulty":"intermediate","updated":"2026-06-27","word_count":267,"read_minutes":1,"llm_context":"Auth: Mind Key (Authorization: Bearer mk_xxx OR ?key=mk_xxx)\nALWAYS call GET /memory/recall at session start.\nPOST /memory with same category+key updates the existing memory.\nCategories: identity, preference, fact, project, skill, mistake, context, note, credentials\nPriorities: low, normal, high, critical\nSearch: GET /memory/search?q=... (FTS5 syntax: AND, OR, \"phrases\", prefix*)\nSemantic: GET /memory/semantic-search?q=... (slower, conceptual)\nSync: GET /memory/diff?since=TIMESTAMP (incremental sync)\nExport: GET /memory/mind-export (full JSON dump)\n","lang":"zh","translated":true,"requested_lang":"zh","content_markdown":"\n# Memory API\n\nMemory API 是 Synapse 的核心。它提供 22 个端点用于存储、检索、搜索和管理结构化记忆。所有端点都需要 Mind Key 进行认证。\n\n> [!CRITICAL]\n> **务必在每次会话开始时调用 `GET /memory/recall`。** 这是从之前的会话中重建上下文的唯一方式。\n\n## 分类\n\n记忆被组织为 8 个分类：\n\n| 分类 | 用途 |\n|----------|----------|\n| `identity` | 用户名、角色、联系方式、关于自身的偏好 |\n| `preference` | 喜好、厌恶、工作风格、沟通偏好 |\n| `fact` | 可验证的事实（项目细节、日期、URL） |\n| `project` | 项目状态、里程碑、架构 |\n| `skill` | 用户擅长的事情 |\n| `mistake` | 过去犯的错 — 避免重蹈覆辙 |\n| `context` | 与会话相关的上下文 |\n| `note` | 其他备注 |\n\n## 优先级\n\n- `low` — 知道就好\n- `normal` — 默认\n- `high` — 重要\n- `critical` — 绝不能忘（用户身份、法律信息等）\n\n## 核心端点\n\n### GET /memory/recall\n\n以 LLM 优化的纯文本形式返回所有记忆。请务必在每次会话开始时调用。\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n```\n\n响应（text/plain）：\n\n```\nMind: Michael's Mind\nMemories: 12 total (10 verified)\n\n[001] identity (CRITICAL)\n user_name\n Michael Schäfer\n Tags: person, identity\n\n...\n```\n\n### POST /memory\n\n存储新记忆或更新已有记忆（相同 category + key 视为更新）。\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"category\": \"fact\",\n \"key\": \"user_name\",\n \"content\": \"The user's name is Michael Schäfer\",\n \"tags\": [\"person\", \"identity\"],\n \"priority\": \"critical\"\n }'\n```\n\n响应：`{ \"id\": \"mem_001\", \"status\": \"stored\" }`\n\n### GET /memory\n\n列出记忆，可加可选过滤条件。\n\n```bash\n# 全部记忆（JSON）\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory?limit=50&offset=0\"\n\n# 按分类过滤\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory?category=project\"\n\n# 按标签过滤\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory?tag=docker\"\n```\n\n### PUT /memory/:id\n\n按 ID 更新某条具体记忆。\n\n```bash\ncurl -X PUT https://synapse.schaefer.zone/memory/mem_001 \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\": \"Updated content\", \"priority\": \"high\"}'\n```\n\n### DELETE /memory/:id\n\n删除单条记忆。\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/mem_001\n```\n\n## 搜索端点\n\n### GET /memory/search\n\n使用 FTS5 进行全文搜索。\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/search?q=docker+swarm\"\n```\n\nFTS5 语法：\n\n- 多个词 = AND：`docker swarm`\n- 短语：`\"docker swarm\"`\n- 前缀：`docker*`\n- 布尔：`docker OR kubernetes`\n- 排除：`docker -swarm`\n\n### GET /memory/semantic-search\n\n使用向量嵌入进行概念搜索（比 FTS5 慢，但能理解语义）。\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration\"\n```\n\n返回与查询语义相似的记忆，即使没有关键词匹配。适用于“查找关于 X 的记忆”，即使 X 被用不同的方式描述。\n\n### GET /memory/by-tag\n\n按标签列出记忆。\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/by-tag?tag=docker\"\n```\n\n### GET /memory/related/:id\n\n查找与某条记忆相关的记忆（基于共享标签）。\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/related/mem_001\n```\n\n## 同步与 Diff\n\n### GET /memory/diff\n\n增量同步 — 返回自指定时间戳以来发生变化的记忆。\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/diff?since=1700000000\"\n```\n\n响应：`{ \"added\": [...], \"updated\": [...], \"deleted\": [...] }`\n\n### POST /memory/sync\n\n应用来自另一个实例的 diff（用于自托管同步）。\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/sync \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"added\": [...], \"updated\": [...], \"deleted\": [...]}'\n```\n\n## 批量操作\n\n### POST /memory/bulk-delete\n\n按 ID 批量删除记忆。\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/bulk-delete \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\": [\"mem_001\", \"mem_002\", \"mem_003\"]}'\n```\n\n### POST /memory/embed-batch\n\n为尚未生成向量嵌入的记忆批量生成嵌入（用于语义搜索）。\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/embed-batch \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"limit\": 100}'\n```\n\n### GET /memory/embed-batch-status\n\n检查嵌入生成进度。\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/embed-batch-status\n```\n\n## 验证\n\n记忆有 `verified` 标志。Agent 存储的记忆默认未验证（`source=agent`）；人类存储的记忆默认已验证（`source=user`）。\n\n### POST /memory/verify\n\n将记忆标记为已验证（需要 JWT，而非 Mind Key）。\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \\\n -H \"Authorization: Bearer YOUR_JWT\"\n```\n\n### POST /memory/unverify\n\n将记忆标记为未验证（需要 JWT）。\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/mem_001/unverify \\\n -H \"Authorization: Bearer YOUR_JWT\"\n```\n\n### GET /memory/unverified\n\n列出等待人类验证的记忆。\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/unverified?limit=100\"\n```\n\n## 统计与审计\n\n### GET /memory/stats\n\n当前 Mind 的聚合统计。\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/stats\n```\n\n返回：`{ \"total\": 12, \"verified\": 10, \"unverified\": 2, \"by_category\": {...}, \"by_priority\": {...} }`\n\n### GET /memory/audit\n\n所有状态变更操作的审计日志。\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/audit?limit=100&action=store\"\n```\n\n### GET /memory/contradictions\n\n检测已存储记忆中潜在的矛盾。\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/contradictions\n```\n\n### GET /memory/expiring\n\n列出即将到期的记忆。\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/expiring?within=7d\"\n```\n\n## 健康检查与导出\n\n### GET /memory/health\n\n记忆系统的快速健康检查。\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/health\n```\n\n### GET /memory/mind-export\n\n全部记忆的完整 JSON 导出（用于备份）。\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/mind-export > backup.json\n```\n\n### POST /memory/compact\n\n压缩相似记忆（自动摘要）。\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/compact \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"dry_run\": true}'\n```\n\n## 下一步\n\n- [LLM 快速开始](/docs/getting-started/quick-start-llm)\n- [记忆最佳实践](/docs/guides/memory-best-practices)\n- [FTS5 搜索](/docs/concepts/fts5-search)\n- [语义搜索](/docs/concepts/semantic-search)\n","content_html":"

Memory API

\n

Memory API 是 Synapse 的核心。它提供 22 个端点用于存储、检索、搜索和管理结构化记忆。所有端点都需要 Mind Key 进行认证。

\n
**务必在每次会话开始时调用 `GET /memory/recall`。** 这是从之前的会话中重建上下文的唯一方式。

分类

\n

记忆被组织为 8 个分类：

\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用户名、角色、联系方式、关于自身的偏好
preference喜好、厌恶、工作风格、沟通偏好
fact可验证的事实（项目细节、日期、URL）
project项目状态、里程碑、架构
skill用户擅长的事情
mistake过去犯的错 — 避免重蹈覆辙
context与会话相关的上下文
note其他备注
\n

优先级

\n\n

核心端点

\n

GET /memory/recall

\n

以 LLM 优化的纯文本形式返回所有记忆。请务必在每次会话开始时调用。

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/recall

响应（text/plain）：

\n
Mind: Michael's Mind\nMemories: 12 total (10 verified)\n\n[001] identity (CRITICAL)\n  user_name\n  Michael Schäfer\n  Tags: person, identity\n\n...

POST /memory

\n

存储新记忆或更新已有记忆（相同 category + key 视为更新）。

\n
curl -X POST https://synapse.schaefer.zone/memory \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{\n    "category": "fact",\n    "key": "user_name",\n    "content": "The user's name is Michael Schäfer",\n    "tags": ["person", "identity"],\n    "priority": "critical"\n  }'

响应：{ "id": "mem_001", "status": "stored" }

\n

GET /memory

\n

列出记忆，可加可选过滤条件。

\n
# 全部记忆（JSON）\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory?limit=50&offset=0"\n\n# 按分类过滤\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory?category=project"\n\n# 按标签过滤\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory?tag=docker"

PUT /memory/:id

\n

按 ID 更新某条具体记忆。

\n
curl -X PUT https://synapse.schaefer.zone/memory/mem_001 \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"content": "Updated content", "priority": "high"}'

DELETE /memory/:id

\n

删除单条记忆。

\n
curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/mem_001

搜索端点

\n

GET /memory/search

\n

使用 FTS5 进行全文搜索。

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/search?q=docker+swarm"

FTS5 语法：

\n\n

GET /memory/semantic-search

\n

使用向量嵌入进行概念搜索（比 FTS5 慢，但能理解语义）。

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration"

返回与查询语义相似的记忆，即使没有关键词匹配。适用于“查找关于 X 的记忆”，即使 X 被用不同的方式描述。

\n

GET /memory/by-tag

\n

按标签列出记忆。

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/by-tag?tag=docker"

GET /memory/related/:id

\n

查找与某条记忆相关的记忆（基于共享标签）。

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/related/mem_001

同步与 Diff

\n

GET /memory/diff

\n

增量同步 — 返回自指定时间戳以来发生变化的记忆。

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/diff?since=1700000000"

响应：{ "added": [...], "updated": [...], "deleted": [...] }

\n

POST /memory/sync

\n

应用来自另一个实例的 diff（用于自托管同步）。

\n
curl -X POST https://synapse.schaefer.zone/memory/sync \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"added": [...], "updated": [...], "deleted": [...]}'

批量操作

\n

POST /memory/bulk-delete

\n

按 ID 批量删除记忆。

\n
curl -X POST https://synapse.schaefer.zone/memory/bulk-delete \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"ids": ["mem_001", "mem_002", "mem_003"]}'

POST /memory/embed-batch

\n

为尚未生成向量嵌入的记忆批量生成嵌入（用于语义搜索）。

\n
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"limit": 100}'

GET /memory/embed-batch-status

\n

检查嵌入生成进度。

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/embed-batch-status

验证

\n

记忆有 verified 标志。Agent 存储的记忆默认未验证（source=agent）；人类存储的记忆默认已验证（source=user）。

\n

POST /memory/verify

\n

将记忆标记为已验证（需要 JWT，而非 Mind Key）。

\n
curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \\\n  -H "Authorization: Bearer YOUR_JWT"

POST /memory/unverify

\n

将记忆标记为未验证（需要 JWT）。

\n
curl -X POST https://synapse.schaefer.zone/memory/mem_001/unverify \\\n  -H "Authorization: Bearer YOUR_JWT"

GET /memory/unverified

\n

列出等待人类验证的记忆。

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/unverified?limit=100"

统计与审计

\n

GET /memory/stats

\n

当前 Mind 的聚合统计。

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/stats

返回：{ "total": 12, "verified": 10, "unverified": 2, "by_category": {...}, "by_priority": {...} }

\n

GET /memory/audit

\n

所有状态变更操作的审计日志。

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/audit?limit=100&action=store"

GET /memory/contradictions

\n

检测已存储记忆中潜在的矛盾。

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/contradictions

GET /memory/expiring

\n

列出即将到期的记忆。

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/expiring?within=7d"

健康检查与导出

\n

GET /memory/health

\n

记忆系统的快速健康检查。

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/health

GET /memory/mind-export

\n

全部记忆的完整 JSON 导出（用于备份）。

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/mind-export > backup.json

POST /memory/compact

\n

压缩相似记忆（自动摘要）。

\n
curl -X POST https://synapse.schaefer.zone/memory/compact \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"dry_run": true}'

下一步

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