Skip to main content

Memory API

intermediate 🤖 LLM 友好 1 分钟 · 267 字 更新于： 2026-06-27 中文

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

阅读本文： 📄 纯文本 ⚡ JSON 🤖 LLM 格式
语言: English中文हिन्दीEspañolFrançaisالعربيةPortuguêsРусский日本語DeutschItaliano한국어NederlandsPolskiTürkçeSvenskaTiếng ViệtไทยBahasa IndonesiaУкраїнська

Memory API

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

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

分类

记忆被组织为 8 个分类：

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

优先级

  • low — 知道就好
  • normal — 默认
  • high — 重要
  • critical — 绝不能忘（用户身份、法律信息等）

核心端点

GET /memory/recall

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

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

响应（text/plain）：

Mind: Michael's Mind
Memories: 12 total (10 verified)

[001] identity (CRITICAL)
  user_name
  Michael Schäfer
  Tags: person, identity

...

POST /memory

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

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

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

GET /memory

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

# 全部记忆（JSON）
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?limit=50&offset=0"

# 按分类过滤
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?category=project"

# 按标签过滤
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?tag=docker"

PUT /memory/:id

按 ID 更新某条具体记忆。

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

DELETE /memory/:id

删除单条记忆。

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

搜索端点

GET /memory/search

使用 FTS5 进行全文搜索。

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

FTS5 语法：

  • 多个词 = AND：docker swarm
  • 短语："docker swarm"
  • 前缀：docker*
  • 布尔：docker OR kubernetes
  • 排除：docker -swarm

GET /memory/semantic-search

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

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

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

GET /memory/by-tag

按标签列出记忆。

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

GET /memory/related/:id

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

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

同步与 Diff

GET /memory/diff

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

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

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

POST /memory/sync

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

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

批量操作

POST /memory/bulk-delete

按 ID 批量删除记忆。

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

POST /memory/embed-batch

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

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

GET /memory/embed-batch-status

检查嵌入生成进度。

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

验证

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

POST /memory/verify

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

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

POST /memory/unverify

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

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

GET /memory/unverified

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

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

统计与审计

GET /memory/stats

当前 Mind 的聚合统计。

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

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

GET /memory/audit

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

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

GET /memory/contradictions

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

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

GET /memory/expiring

列出即将到期的记忆。

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

健康检查与导出

GET /memory/health

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

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

GET /memory/mind-export

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

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

POST /memory/compact

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

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

下一步

← 返回 API 参考