# Memory API
SUMMARY: 22 个记忆端点的完整参考：存储、回放、搜索、语义搜索、同步、审计等。

KEY CONTEXT:
Auth: Mind Key (Authorization: Bearer mk_xxx OR ?key=mk_xxx)
ALWAYS call GET /memory/recall at session start.
POST /memory with same category+key updates the existing memory.
Categories: identity, preference, fact, project, skill, mistake, context, note, credentials
Priorities: low, normal, high, critical
Search: GET /memory/search?q=... (FTS5 syntax: AND, OR, "phrases", prefix*)
Semantic: GET /memory/semantic-search?q=... (slower, conceptual)
Sync: GET /memory/diff?since=TIMESTAMP (incremental sync)
Export: GET /memory/mind-export (full JSON dump)

Memory API
Memory API 是 Synapse 的核心。它提供 22 个端点用于存储、检索、搜索和管理结构化记忆。所有端点都需要 Mind Key 进行认证。
> [!CRITICAL]
> 务必在每次会话开始时调用 。 这是从之前的会话中重建上下文的唯一方式。
分类
记忆被组织为 8 个分类：
| 分类 | 用途 |
|----------|----------|
|  | 用户名、角色、联系方式、关于自身的偏好 |
|  | 喜好、厌恶、工作风格、沟通偏好 |
|  | 可验证的事实（项目细节、日期、URL） |
|  | 项目状态、里程碑、架构 |
|  | 用户擅长的事情 |
|  | 过去犯的错 — 避免重蹈覆辙 |
|  | 与会话相关的上下文 |
|  | 其他备注 |
优先级
-  — 知道就好
-  — 默认
-  — 重要
-  — 绝不能忘（用户身份、法律信息等）
核心端点
GET /memory/recall
以 LLM 优化的纯文本形式返回所有记忆。请务必在每次会话开始时调用。
[CODE BLOCK]
响应（text/plain）：
[CODE BLOCK]
POST /memory
存储新记忆或更新已有记忆（相同 category + key 视为更新）。
[CODE BLOCK]
响应：
GET /memory
列出记忆，可加可选过滤条件。
[CODE BLOCK]
PUT /memory/:id
按 ID 更新某条具体记忆。
[CODE BLOCK]
DELETE /memory/:id
删除单条记忆。
[CODE BLOCK]
搜索端点
GET /memory/search
使用 FTS5 进行全文搜索。
[CODE BLOCK]
FTS5 语法：
- 多个词 = AND：
- 短语：
- 前缀：
- 布尔：
- 排除：
GET /memory/semantic-search
使用向量嵌入进行概念搜索（比 FTS5 慢，但能理解语义）。
[CODE BLOCK]
返回与查询语义相似的记忆，即使没有关键词匹配。适用于“查找关于 X 的记忆”，即使 X 被用不同的方式描述。
GET /memory/by-tag
按标签列出记忆。
[CODE BLOCK]
GET /memory/related/:id
查找与某条记忆相关的记忆（基于共享标签）。
[CODE BLOCK]
同步与 Diff
GET /memory/diff
增量同步 — 返回自指定时间戳以来发生变化的记忆。
[CODE BLOCK]
响应：
POST /memory/sync
应用来自另一个实例的 diff（用于自托管同步）。
[CODE BLOCK]
批量操作
POST /memory/bulk-delete
按 ID 批量删除记忆。
[CODE BLOCK]
POST /memory/embed-batch
为尚未生成向量嵌入的记忆批量生成嵌入（用于语义搜索）。
[CODE BLOCK]
GET /memory/embed-batch-status
检查嵌入生成进度。
[CODE BLOCK]
验证
记忆有  标志。Agent 存储的记忆默认未验证（）；人类存储的记忆默认已验证（）。
POST /memory/verify
将记忆标记为已验证（需要 JWT，而非 Mind Key）。
[CODE BLOCK]
POST /memory/unverify
将记忆标记为未验证（需要 JWT）。
[CODE BLOCK]
GET /memory/unverified
列出等待人类验证的记忆。
[CODE BLOCK]
统计与审计
GET /memory/stats
当前 Mind 的聚合统计。
[CODE BLOCK]
返回：
GET /memory/audit
所有状态变更操作的审计日志。
[CODE BLOCK]
GET /memory/contradictions
检测已存储记忆中潜在的矛盾。
[CODE BLOCK]
GET /memory/expiring
列出即将到期的记忆。
[CODE BLOCK]
健康检查与导出
GET /memory/health
记忆系统的快速健康检查。
[CODE BLOCK]
GET /memory/mind-export
全部记忆的完整 JSON 导出（用于备份）。
[CODE BLOCK]
POST /memory/compact
压缩相似记忆（自动摘要）。
[CODE BLOCK]
下一步
- LLM 快速开始
- 记忆最佳实践
- FTS5 搜索
- 语义搜索