MMemHub API Docs
PUBLIC API · v1.1

让 AI 真正
记住每一次交互

MemHub 提供统一的长期记忆、语义搜索、关系图谱和陪伴式 AI 能力。本文档包含可直接运行的示例，以及与当前 OpenAPI 实时同步的接口目录。

一分钟接入打开 API Explorer ↗
Base URLhttps://memhub0.sonari.dev
01

鉴权

所有业务接口使用 API Key；文档、健康检查和登录页保持公开。

请求头：将管理员 Key 或租户 Key 放入 X-API-Key。请只在服务端保存密钥，不要写入浏览器代码或 Git 仓库。
HTTP Header
X-API-Key: YOUR_MEMHUB_API_KEY
A

管理员 Key

拥有跨租户访问和配置权限，仅供内部运维、迁移与管理任务使用。

T

租户 Key

绑定一个租户和 ID 前缀。密钥只在创建或轮换时展示一次。

02

一分钟快速开始

写入一段对话，再用自然语言检索相关记忆。

1

获取 API Key

由管理员在租户管理中创建租户并安全交付 Key。

2

选择作用域 ID

租户请求中的 user_id、agent_id 或 group_id 必须使用分配的前缀。

3

发起第一条请求

下面示例会将一句对话写入用户的长期记忆。

cURL · 创建记忆
curl -X POST "https://memhub0.sonari.dev/memories"   -H "X-API-Key: YOUR_MEMHUB_API_KEY"   -H "Content-Type: application/json"   -d '{
    "user_id": "YOUR_PREFIX_user_001",
    "messages": [{"role": "user", "content": "我喜欢喝无糖拿铁"}]
  }'
成功响应：返回创建结果。若内容已结构化，可传 "infer": false 直接存储。
03

租户与 ID 作用域

租户隔离由 API Key 与作用域前缀共同保证。

标识用途示例
user_id人类用户的长期记忆与画像acme_user_001
agent_idAI 角色、助手或 Persona 的记忆acme_agent_luna
run_id会话、任务或一次运行的临时边界run_20260802_01
group_id关系或群组级数据边界acme_group_family
租户规则：租户 Key 的所有非空作用域 ID 都必须以该租户的 scope_prefix 开头；越权请求返回 HTTP 403。
04

写入记忆

支持单条对话、批量写入，以及人类与 Agent 两类记忆主体。

对话提取

默认从 messages 中提取可复用事实，并自动去重与更新。

直接存储

设置 infer=false，按原文保存结构化内容。

批量写入

POST /memories/batch 单次最多 200 项。

Python · requests
import requests
response = requests.post(
    "https://memhub0.sonari.dev/memories",
    headers={"X-API-Key": "YOUR_MEMHUB_API_KEY"},
    json={"user_id": "YOUR_PREFIX_user_001", "messages": [
        {"role": "user", "content": "周末更喜欢徒步而不是逛商场"}
    ]},
    timeout=30,
)
response.raise_for_status()
print(response.json())
Node.js · fetch
const response = await fetch("https://memhub0.sonari.dev/memories", {
  method: "POST",
  headers: {"X-API-Key": "YOUR_MEMHUB_API_KEY", "Content-Type": "application/json"},
  body: JSON.stringify({
    user_id: "YOUR_PREFIX_user_001",
    messages: [{role: "user", content: "周末更喜欢徒步而不是逛商场"}]
  })
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
06

关系与对话提取

将对话转换为社交事实、事件与群组信息，并维护关系数据。

E

对话提取

POST /extract 从消息中提取 social、episodic 和 group 信息。

R

关系维护

/relations 支持单条/批量写入、查询和删除。

建议：应用侧应设置合理超时。上游 LLM 暂时不可用时，服务返回明确的 HTTP 503。
07

Companion API

面向长期陪伴产品的关系演化、情绪分析、里程碑、任务和 Webhook 能力。

关系演化

写入 episode 后更新亲密度、信任和依恋等指标。

情绪与信号

分析文本或音频情绪，写入可解释关系信号。

异步集成

通过 jobs 查询长任务，通过 Webhook 接收结果。

cURL · 查询关系
curl "https://memhub0.sonari.dev/v1/users/YOUR_PREFIX_user_001/relationships"   -H "X-API-Key: YOUR_MEMHUB_API_KEY"
08

限流与错误

错误使用标准 HTTP 状态码，并返回 JSON 形式的 detail。

状态码含义处理建议
400参数或作用域 ID 缺失检查请求体和必需 ID。
401API Key 无效检查 X-API-Key。
403权限不足或 ID 越界确认租户状态和 scope_prefix。
422请求结构校验失败按 Schema 修正字段。
429请求过于频繁指数退避后重试。
503后端或上游 AI 不可用稍后重试并检查供应商配置。
错误响应
{"detail": "X-API-Key header is required."}
09

接口清单

实时读取当前服务的 OpenAPI Schema，可按关键词、方法和分组筛选。

正在加载 OpenAPI 接口清单…

查看完整请求模型和响应 Schema：API Explorer ↗

已复制到剪贴板