A
Artific DocsMemoryEcho API产品介绍 ↗

MemoryEcho API

MemoryEcho（MemEcho 意回）为大语言模型提供长期记忆能力。通过 REST API 创建记忆库、写入对话、做语义召回，让您的 AI 应用无视上下文窗口限制，真正记住每一位用户。

Base URL
https://api.artific.social
格式
JSON（部分接口 SSE 流式）
认证
API Key（Bearer）/ 会话 Cookie

架构上，API 网关（Rust）负责鉴权、配额与消息持久化，背后的记忆引擎（Python + Milvus 向量库 + MongoDB）负责向量化、聚类与召回。引擎短暂不可用时，读写接口以 degraded 模式降级响应而不是直接失败——客户端应始终检查响应中的 degraded / pipeline 字段。

认证

API Key（推荐服务器端使用）

在 MemoryEcho 管理页创建 as_ 前缀的 API Key（完整密钥仅创建时展示一次），随请求放入 Authorization 头即可，无需会话： 

Authorization: Bearer as_xxxxxxxx_…

Key 的 scope 决定可访问的能力：

  • memory —— 记忆服务全部接口（管理页创建的 Key 默认此 scope）。
  • memory:read —— 只读：列表 / 详情 / query-readonly / 文件读取。
  • memory:write —— 写入：创建 / 更新 / 删除 / query / append / 导入 / chat。
  • 未设置任何 scope 的 Key 视为全功能 Key（不限服务）。

scope 不足返回 403 {"error":"insufficient scope: …"}；Key 无效、已撤销或已过期按未认证处理（回退会话认证，均无效则 401）。

会话 Cookie（浏览器端）

登录 artific.social 后，浏览器持有 HttpOnly 会话 Cookie。同源前端请求带上 credentials: 'include' 即可；命令行调试也可从浏览器开发者工具复制 Cookie 头使用。

所有 /api/v1/memory/* 接口按认证所属用户隔离数据；未认证请求返回 401 {"error":"unauthorized"}。

服务间集成（HMAC）合作接入

平台内一方服务（如 GamEcho）通过内部 HMAC 签名通道接入记忆能力，绕过会话与配额、由接入方自行计费。如需此级别的深度集成，请联系我们。

快速开始

三步接入：创建记忆库 → 写入记忆 → 语义查询。

# 0. 在 MemoryEcho 管理页创建 API Key（见「认证」一节）
API_KEY='as_xxxxxxxx_…'

# 1. 创建记忆库
curl -X POST https://api.artific.social/api/v1/memory/vaults \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"name": "quickstart"}'
# => { "id": "<vault_id>", … }

# 2. 写入记忆
curl -X POST https://api.artific.social/api/v1/memory/append-user-message \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"library_id": "<vault_id>", "message": "我喜欢深色模式，讨厌弹窗"}'
# => { "status": "ok", "memory_id": "…", "pipeline": "ok" }

# 3. 语义查询
curl -X POST https://api.artific.social/api/v1/memory/query \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"library_id": "<vault_id>", "message": "用户的界面偏好？"}'
# => { "memory_id": "…", "results": [ … ], "degraded": false }

数据模型

MemoryVault — 记忆库

idUUID记忆库 ID（即各接口中的 library_id）
user_idUUID所属用户
namestring名称
descriptionstring | null描述
vault_typestring类型：normal（默认）或 snapshot
share_codestring | null分享码（预留）
clone_source_idUUID | null克隆来源
memory_countnumber记忆条数统计
storage_bytesnumber占用存储（字节）
deleted_attimestamp | null软删除时间（回收站）
created_at / updated_attimestamp创建 / 更新时间

Memory — 记忆消息

idUUID记忆消息 ID
library_idUUID所属记忆库
user_idUUID所属用户
rolestring消息角色：user 或 assistant
contentstring消息内容
metadataobject | null附加数据；查询消息会带 recalls（召回快照）与 degraded 标记
created_attimestamp写入时间

记忆库 Vaults

记忆库（Vault）是记忆的隔离单元——每个 Agent、每个用户会话或每个知识域一个库。接口中的 library_id 均指记忆库 ID。

POST/api/v1/memory/vaults

创建记忆库

请求体
{
  "name": "my-agent-memory",
  "description": "可选描述",
  "vault_type": "normal"
}
响应
{
  "id": "0197c9a2-…",
  "user_id": "0195aa10-…",
  "name": "my-agent-memory",
  "description": "可选描述",
  "vault_type": "normal",
  "memory_count": 0,
  "storage_bytes": 0,
  "created_at": "2026-07-16T12:00:00Z",
  "updated_at": "2026-07-16T12:00:00Z"
}
  • 创建计入套餐配额；套餐额度用尽时自动尝试按量计费（PAYG），两者都不可用返回 402。
  • vault_type 省略时默认 normal。
GET/api/v1/memory/vaults

列出当前用户的所有记忆库（不含已删除，按更新时间倒序）

响应
[ MemoryVault, … ]
GET/api/v1/memory/vaults/{id}

获取记忆库详情

  • 非本人记忆库返回 403，不存在返回 404。
PATCH/api/v1/memory/vaults/{id}

更新记忆库名称 / 描述

请求体
{
  "name": "新名称",
  "description": "新描述"
}
  • 两个字段均可选，只更新提供的字段。
DELETE/api/v1/memory/vaults/{id}

删除记忆库（软删除，移入回收站）

  • 成功返回 204 No Content。
  • 删除后可在回收站中恢复或彻底删除，见下方回收站接口。
GET/api/v1/memory/vaults/trash

列出当前用户回收站中的记忆库（按删除时间倒序）

响应
[
  {
    "id": "0197c9c1-…",
    "base_id": "0197c9a2-…",
    "original_name": "my-agent-memory",
    "deleted_at": "2026-07-17T12:00:00Z"
  }
]
  • id 为回收站条目 ID（恢复 / 彻底删除时使用），base_id 为原记忆库 ID。
POST/api/v1/memory/vaults/trash/{id}/restore

从回收站恢复记忆库

响应
MemoryVault
  • {id} 为回收站条目 ID。
  • 恢复后记忆库回到列表中，回收站条目被移除；条目不属于当前用户或已不存在返回 404。
DELETE/api/v1/memory/vaults/trash/{id}

彻底删除回收站中的记忆库（不可恢复）

  • {id} 为回收站条目 ID。成功返回 204 No Content。
  • 记忆库及其全部记忆、权限记录一并删除；记忆库已被恢复时返回 409。

记忆消息

记忆库内的原始消息流。写入的用户消息 / AI 回复与语义查询记录都以消息形式留存。

GET/api/v1/memory/memories/{library_id}/messages?limit=50&offset=0

获取记忆库内的记忆消息列表

响应
[
  {
    "id": "0197c9b0-…",
    "library_id": "0197c9a2-…",
    "user_id": "0195aa10-…",
    "role": "user",
    "content": "我喜欢深色模式",
    "metadata": null,
    "created_at": "2026-07-16T12:01:00Z"
  }
]
  • limit 默认 50，offset 默认 0。

查询与写入

核心记忆管线：append 写入消息并异步向量化，query 做语义召回。典型的一轮 Agent 对话 = query（取上下文）→ 生成回复 → append-user-message + append-assistant-message（写回记忆）。

POST/api/v1/memory/append-user-message

写入一条用户消息（进入记忆管线，异步向量化）

请求体
{
  "library_id": "0197c9a2-…",
  "message": "我喜欢深色模式"
}
响应
{
  "status": "ok",
  "memory_id": "0197c9b0-…",
  "pipeline": "ok"
}
  • pipeline 为 degraded 表示记忆引擎暂时不可用：消息已持久化，稍后自动补入记忆管线。
POST/api/v1/memory/append-assistant-message

写入一条 AI 回复（与用户消息共同构成完整记忆）

请求体
{
  "library_id": "0197c9a2-…",
  "message": "好的，已为您切换深色模式。"
}
响应
{
  "status": "ok",
  "memory_id": "0197c9b1-…",
  "pipeline": "ok"
}
POST/api/v1/memory/query

语义查询相关记忆（本次查询写入历史，可被后续召回）

请求体
{
  "library_id": "0197c9a2-…",
  "message": "用户偏好是什么？"
}
响应
{
  "memory_id": "0197c9b2-…",
  "results": [ … 召回的记忆条目 … ],
  "degraded": false
}
  • results 为记忆引擎返回的召回条目数组（含相关记忆内容与元信息）。
  • degraded 为 true 表示记忆引擎降级：返回结果可能不完整，建议按普通上下文处理。
  • 召回快照会持久化到该条查询消息的 metadata.recalls 中，便于审计与回放。
POST/api/v1/memory/query-readonly

只读语义查询（不写入查询历史、不留痕）

请求体
{
  "library_id": "0197c9a2-…",
  "message": "用户偏好是什么？"
}
响应
{
  "results": [ … ],
  "degraded": false
}
  • 降级时返回 { "results": [], "messages": [ 最近消息列表 ], "degraded": true }，可用 messages 兜底拼接上下文。

对话生成 Chat

不想自己接大模型？让 MemoryEcho 直接代理一轮记忆增强的对话生成（经 Artific LLM Hub）。

POST/api/v1/memory/chat

记忆增强对话生成（经 LLM Hub，SSE 流式返回）

请求体
{
  "model": "gemini-2.5-flash",
  "messages": [
    { "role": "user", "content": "帮我总结一下最近的偏好" }
  ],
  "stream": true
}
  • 请求体透传给 LLM Hub 对话接口，字段与 LLM Hub /chat 一致（model 可通过 GET /api/v1/llm-hub/models 查询）。
  • stream: true 时响应为 text/event-stream（SSE），否则为普通 JSON。
  • 网关自动携带服务身份调用 LLM Hub，用量计入您的账户。

文件导入

将文档批量导入记忆库：Markdown、纯文本等格式解析后切分向量化，导入过程通过 SSE 推送进度。

POST/api/v1/memory/memories/import_file

导入文件到记忆库（SSE 流式返回处理进度）

请求体
{
  "library_id": "0197c9a2-…",
  "file_name": "notes.md",
  "data_url": "data:text/markdown;base64,IyBO…",
  "preset": "default"
}
  • 文件以 data URL（base64）内联上传，请求体上限 16 MiB。
  • 响应为 text/event-stream：解析 → 切分 → 向量化的进度事件逐条推送。
  • preset / running_mode / short_memory_style 为可选调优参数，默认即可。
GET/api/v1/memory/files?library_id={id}

列出记忆库已导入的文件

GET/api/v1/memory/files/content?library_id={id}&attachment_id={aid}

获取已导入文件的原始内容（Content-Type 与原文件一致）

用量查询

查询记忆库数量与按量计费汇总。

GET/api/v1/dashboard/services/memory/usage

当前用户的 MemoryEcho 用量概览

响应
{
  "vault_count": 3,
  "payg_summary_create": {
    "frozen_cents": 0,
    "settled_this_month_cents": 150
  },
  "payg_summary_query": {
    "frozen_cents": 0,
    "settled_this_month_cents": 20
  }
}
  • payg_summary_* 仅在开通按量计费后返回；套餐内额度用量见订阅中心。

配额与计费

订阅按 28 天为一个计费周期，三档主套餐互斥（升级即时生效、降级于周期末生效），可叠加附加包；未订阅或额度用尽时可走按量计费（PAYG，需钱包余额）。套餐购买与管理见 订阅中心。

套餐价格容量周期额度
入门版 starter¥19 / 28天3 记忆库 · 50MB500 写入 · 1,000 查询 · 2,000 API 调用
标准版 standard¥99 / 28天10 记忆库 · 500MB10,000 查询 · 20,000 API 调用
旗舰版 extreme¥299 / 28天50 记忆库 · 2GB100,000 查询 · 200,000 API 调用
对话加量包（附加包）¥49 / 次—+500 写入 · +1,000 查询

按量计费（PAYG）单价

创建记忆库¥0.50 / 个
记忆写入 append¥0.01 / 次
语义查询 query¥0.01 / 次
快照创建¥1.00 / 次
文件导入¥0.05 / MB

当前公测阶段，配额在记忆库创建时强制校验（套餐额度 → PAYG → 402）；其余操作的额度按套餐记账，超量控制将逐步收紧——请按套餐额度规划用量，避免后续策略调整影响业务。

错误处理

所有错误响应为裸 JSON：{"error": "描述信息"}（无统一 envelope 包装）。

状态码error处理建议
401unauthorizedAPI Key 无效 / 已撤销 / 已过期，或会话过期。检查 Key 或重新登录 artific.social。
402quota exceeded: …套餐配额用尽且按量计费不可用。升级套餐或在钱包充值后开通 PAYG。
403forbidden / insufficient scope: …访问了不属于当前用户的记忆库，或 API Key 的 scope 不足（见「认证」一节）。
404not found记忆库或资源不存在（含已删除）。
413payload too large请求体超限（文件导入上限 16 MiB）。
500 / 502internal error / upstream error服务端错误或记忆引擎暂时不可用；读写接口会尽量以 degraded 模式响应而非直接失败。

路线图

  • 事件订阅 —— 记忆创建 / 导入等事件的 Webhook 推送。
  • 官方 SDK —— Python / TypeScript 客户端库。
© 2026 Artific Socius, Inc. · MemEcho 意回文档基于 memory_echo 网关当前版本编写 · 最后更新 2026-07