API Reference
学习如何调用 Spomory 的 6 个记忆工具。
鉴权方式
本地版——MCP Server 通过 stdio 跟客户端通信，不需要任何鉴权：信任边界是「能启动这个进程的人」。
云端版——两种鉴权方式，同一套工具
x-api-key 请求头，给不支持 OAuth 的客户端用（Cursor、豆包、魔搭 MCP 广场、mcp-remote）——连 https://api.yliuai.com/mcp-apikey/。OAuth 2.1 + PKCE，Anthropic Connector 目录要求的方式——连 https://api.yliuai.com/mcp。两条路径共用同一套工具逻辑，落到同一个用户的记忆图谱上。
响应 & 错误
每个工具和 REST 接口都只有这两种真实结果，直接来自线上 api.yliuai.com/openapi.json 这份 spec——没有 400/401/404/500 可写，因为真实部署的接口里就没定义这些。
不管背后工具返回了什么，每个 REST 接口对外都是同一个信封格式：
{"result": "<字符串>"}参数缺失或者格式不对，返回 FastAPI 标准的校验错误格式：
{
"detail": [
{
"loc": ["query", "query"],
"msg": "Field required",
"type": "missing"
}
]
}工具
写入
add_memory 把 text 交给 LLM 抽取成 (主体, 谓语, 客体) 三元组，写进记忆图谱。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
text | string | 必填 | 用来抽取记忆的文本。 |
source_id | string | "mcp-session" | 标记这段文本的来源。 |
返回： 一句摘要，比如「新增实体 2 个，合并已有实体 1 个，新增关系 3 条」。
读取
search_memory 把 query 匹配到已抽取的三元组，再用个性化 PageRank 在图上扩散，拼出一段自然语言上下文。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
query | string | 必填 | 要搜索的内容。 |
top_k | number | 10 | 作为搜索起点的最大匹配事实数。 |
返回： 拼好的上下文；没匹配到时返回「没有找到相关记忆。」
严格来说不是纯只读——会顺带更新被检索到的事实的「最近一次被访问」时间戳，用来支撑陈旧度感知排序。
get_graph 只读 返回 entity_name 周围 hops 跳以内的子图。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
entity_name | string | 必填 | 子图的中心实体。 |
hops | number | 1 | 包含几跳关系。 |
返回： JSON 格式的 {entities, relations}；没匹配到实体时返回 {}。
export_memory 只读 导出完整记忆图谱为「记忆护照」JSON 文档。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
subject_id | string | "default" | 导出哪一份记忆图谱。 |
返回： 护照 JSON。
删除
forget_memory 破坏性操作 找到跟 query 最匹配的一条事实，永久删除——有意设计成一次只删一条：查询太模糊会匹配很多条时，应该收窄重试，而不是一次性静默删掉一堆。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
query | string | 必填 | 用来定位要删除的那一条事实。 |
返回： 「已忘记：主体—谓语—客体」；记忆图谱是空的话会给出提示。
forget_all_memory 破坏性操作 一次调用物理删除整个记忆图谱——所有实体、关系、以及归档的历史版本。forget_memory 刻意设计成一次只删一条，这个是它的批量版本——新增原因是一个真实用户为了清空 4 条已存事实，不得不把 forget_memory 连续调用 4 次（每次都要在客户端里手动点一次授权）。两步式设计：不传 confirm（默认 false）不会删除任何东西，只会报告真正执行会删掉多少——destructive_hint 只是 MCP 协议里的一个提示，不强制客户端拦截，真正起防护作用的是 confirm 这个参数，不管客户端把提示当真还是当摆设，或者调用方是个自动批准危险操作的 agent，都拦得住。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
confirm | boolean | false | 必须传 true 才会真正删除；false 只预览数量。 |
返回： confirm=false 时：报告真正执行会删除多少个实体/关系。confirm=true 时：实际删除了多少个实体、多少条关系的摘要；记忆图谱本来就是空的话会给出提示。
完整源码：GitHub 上的 memory_core/mcp_server/server.py →
REST API
同样的六个工具，走普通 HTTP 而不是 MCP——给 n8n、Zapier 或者任何能发 HTTP 请求的脚本用。Base URL 是 https://api.yliuai.com。鉴权方式跟云端 MCP 端点一样，x-api-key 请求头或者 Authorization: Bearer <key>——去「云端 / 跨 App」页面拿 Key。
示例——用 curl 调用 add_memory：
curl -X POST https://api.yliuai.com/v1/memories \
-H "x-api-key: <你的key>" \
-H "Content-Type: application/json" \
-d '{"text": "我在某某公司做后端开发。"}'写入
/v1/memories 对应 add_memory 的 REST 版本。
| 参数 | 位置 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
text | body | string | 必填 | 用来抽取记忆的文本。 |
source_id | body | string | "api" | 标记这段文本的来源。 |
返回： {"result": "新增实体 2 个，合并已有实体 1 个，新增关系 3 条。"}
读取
/v1/memories/search 对应 search_memory 的 REST 版本。
| 参数 | 位置 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
query | query | string | 必填 | 要搜索的内容。 |
top_k | query | number | 10 | 作为搜索起点的最大匹配事实数。 |
返回： {"result": "<拼好的上下文，或者 \"没有找到相关记忆。\">"}
/v1/graph 只读 对应 get_graph 的 REST 版本。
| 参数 | 位置 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
entity_name | query | string | 必填 | 子图的中心实体。 |
hops | query | number | 1 | 包含几跳关系。 |
返回： {"result": "{\"entities\": [...], \"relations\": [...]}"}
/v1/export 只读 对应 export_memory 的 REST 版本。
| 参数 | 位置 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
subject_id | query | string | "default" | 导出哪一份记忆图谱。 |
返回： {"result": "<护照 JSON，字符串形式>"}
删除
/v1/memories/forget 破坏性操作 对应 forget_memory 的 REST 版本——删除最匹配的那一条事实。
| 参数 | 位置 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
query | body | string | 必填 | 用来定位要删除的那一条事实。 |
返回： {"result": "已忘记：主体—谓语—客体"}
/v1/memories/forget-all 破坏性操作 对应 forget_all_memory 的 REST 版本。同样是两步式设计：confirm=false（默认）不会删除任何东西，只会报告真正执行会删掉多少。
| 参数 | 位置 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
confirm | query | boolean | false | 必须传 true 才会真正删除；false 只预览数量。 |
返回： {"result": "<会删除/已删除的数量>"}