MemoryEcho API

创建记忆库

{
  "name": "my-agent-memory",
  "description": "可选描述",
  "vault_type": "normal"
}

{
  "id": "0197c9a2-…",
  "user_id": 1024,
  "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"
}

• 按次计费：每个记忆库 45,000 配额，经配额服务预授权后扣除（见「配额与计费」）；被拒返回 402，error_code 说明原因（见「错误处理」）。
• vault_type 省略时默认 normal。

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

[ MemoryVault, … ]

获取记忆库详情

• 非本人记忆库返回 403，不存在返回 404。

更新记忆库名称 / 描述

{
  "name": "新名称",
  "description": "新描述"
}

• 两个字段均可选，只更新提供的字段。

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

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

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

[
  {
    "id": "0197c9c1-…",
    "base_id": "0197c9a2-…",
    "original_name": "my-agent-memory",
    "deleted_at": "2026-07-17T12:00:00Z"
  }
]

• id 为回收站条目 ID（恢复 / 彻底删除时使用），base_id 为原记忆库 ID。

从回收站恢复记忆库

MemoryVault

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

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

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

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

[
  {
    "id": "0197c9b0-…",
    "library_id": "0197c9a2-…",
    "user_id": 1024,
    "role": "user",
    "content": "我喜欢深色模式",
    "metadata": null,
    "created_at": "2026-07-16T12:01:00Z"
  }
]

• limit 默认 50，offset 默认 0。
• 已删除的消息不再出现在列表里。

按 id 删除几条记忆消息（不可恢复）

{
  "memory_ids": ["0197c9b0-…", "0197c9b1-…"]
}

{
  "erased": ["0197c9b0-…"],
  "already_erased": [],
  "missing": ["0197c9b1-…"],
  "unmapped": [],
  "derived_cleanup_failed": false
}

• 一次 1～50 条。删除后语义查询里再也召回不到它们，消息列表里也不再出现；不调模型、不消耗配额。
• erased 删掉的；already_erased 之前已删过的；missing 不在这个库里的（都不报错，同一批重复删没有额外效果）。
• unmapped：2026-11 之前写入、尚未与记忆引擎建立对应关系的消息，暂时删不了（不会只删一半）。
• 记忆引擎暂时不可达时返回 502，且什么都没删，可原样重试。由其它服务托管的库返回 403。

更正一条记忆消息：删掉原条，追加一条注明「更正」的新消息

{
  "message": "我住在杭州"
}

{
  "erased": "0197c9b0-…",
  "correction_memory_id": "0197d1e4-…",
  "pipeline": "ok",
  "derived_cleanup_failed": false
}

• 新消息以 user 角色追加在库末尾，正文形如「【更正】2026-07-16 20:01（北京时间）记下的一条内容已删除，以此为准：我住在杭州」，召回时只会看到更正后的内容。
• 原条已删过返回 409；不在库里返回 404。更正写入按「写入」计费（摘要），删除本身不计费。

写入一条用户消息（进入记忆管线）

{
  "library_id": "0197c9a2-…",
  "message": "我喜欢深色模式"
}

{
  "status": "ok",
  "memory_id": "0197c9b0-…",
  "pipeline": "ok"
}

• pipeline 为 degraded 表示记忆引擎暂时不可用：消息已保存进记忆库的消息列表，但没有进入记忆管线，也不会自动补入，因此不会被语义召回。需要被召回的内容请在恢复后重新写入。
• 记忆管线处理消息时会调用模型，按 token 以配额计费（见「配额与计费」）。扣费被拒时返回 402：{"error_code": "INSUFFICIENT_BALANCE", "error": "…", "memory_id": "…", "pipeline": "denied"}——消息同样已保存进消息列表、但没有进入记忆管线；处理好 error_code 对应的问题后重新写入。

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

{
  "library_id": "0197c9a2-…",
  "message": "好的，已为您切换深色模式。"
}

{
  "status": "ok",
  "memory_id": "0197c9b1-…",
  "pipeline": "ok"
}

• pipeline 的 degraded 与扣费被拒（402）同 append-user-message。

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

{
  "library_id": "0197c9a2-…",
  "message": "用户偏好是什么？"
}

{
  "memory_id": "0197c9b2-…",
  "results": [ … 召回的记忆条目 … ],
  "degraded": false
}

• results 为记忆引擎返回的召回条目数组（含相关记忆内容与元信息）。
• degraded 为 true 表示记忆引擎降级：返回结果可能不完整，建议按普通上下文处理。
• 召回快照会持久化到该条查询消息的 metadata.recalls 中，便于审计与回放。
• 召回同样按模型 token 以配额计费。扣费被拒时返回 402（{"error_code", "error", "memory_id"}），不会以 degraded 的空结果代替——请按 error_code 处理，不要当成「没想起来」。

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

{
  "library_id": "0197c9a2-…",
  "message": "用户偏好是什么？"
}

{
  "results": [ … ],
  "degraded": false
}

• 降级时返回 { "results": [], "messages": [ 最近消息列表 ], "degraded": true }，可用 messages 兜底拼接上下文。
• 扣费被拒时返回 402（{"error_code", "error"}），与 query 相同。

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

{
  "model": "deepseek-flash",
  "messages": [
    { "role": "user", "content": "帮我总结一下最近的偏好" }
  ],
  "stream": true
}

• 只接受并转发以下字段：model（必填）、messages、stream、max_tokens、temperature、tools、thinking，其余字段会被忽略。含义与 LLM Hub 的 POST /api/v1/llm-hub/chat 相同（见 LLM Hub 文档）。
• model 必须是 GET /api/v1/llm-hub/models 列出的公开模型：缺 model 返回 400；不在公开列表里返回 403 {"error": "model '…' is not available for direct use"}；模型列表暂时取不到返回 503，稍后重试。
• stream: true 时响应为 text/event-stream（SSE），否则为普通 JSON；两种形状与 LLM Hub /chat 相同。
• 网关以服务身份调用 LLM Hub，模型用量按 LLM Hub 的模型价目以配额从您的账户扣除。
• 扣费被拒时在调用模型之前返回 403（不是 402），响应体是 LLM Hub 的格式：{"detail": {"error_code": "INSUFFICIENT_BALANCE", "message": "…"}}。error_code 取值同「错误处理」里 402 的 PAYG_CONFIRM_REQUIRED / INSUFFICIENT_BALANCE / QUOTA_EXHAUSTED；对话不校验地区。

导入文件到记忆库（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：解析 → 切分 → 写入记忆的进度事件逐条推送。
• 走 /vaults/{vault_id}/import_file 时 library_id 可省略（以路径为准）。
• preset / running_mode / short_memory_style 为可选调优参数，默认即可。
• 导入过程中调用模型同样按 token 以配额计费。扣费被拒时以一条 type 为 error 的终止事件结束，事件里带 error_code（取值同「错误处理」的 402），请据此处理而不是重试。

列出记忆库已导入的文件

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

本月记忆服务的配额消耗汇总

{
  "vault_count": 3,
  "period": {
    "kind": "calendar_month",
    "start": "2026-10-01T00:00:00Z",
    "end": "2026-11-01T00:00:00Z"
  },
  "units_per_credit": 100000000,
  "memory_create": { "units": 4500000000000, "user_paid_units": 0, "count": 1 },
  "memory_query":  { "units": 120000000, "user_paid_units": 120000000, "count": 42 }
}

• 金额是配额的存储单位：units ÷ units_per_credit（10^8）= 配额数。
• memory_create 是建库的按次费；memory_query 是记忆管线（写入、召回、导入）的模型消耗。units 为净消耗（含套餐额度代付），user_paid_units 是其中从您账户余额扣的部分，count 为扣款笔数。
• 统计窗口为本自然月（UTC），与按量付费的月上限同一窗口。只统计经 artific.social 记忆前台与 API Key 发起的调用。
• 用量暂时取不到时返回 502 {"error": "usage_unavailable"}，不会返回 0。