MindMemOS API 使用说明

生产服务基地址：https://mindmem.bowong.cc。机器可读规范位于 /openapi.json，可直接导入 OpenAPI 工具、Postman 或代码生成器。

快速接入

1. 选择凭据

服务调用可使用管理员签发的 mmos.<key_id>.<secret>；PLog 用户调用可使用其 IdP 为当前用户签发、最长 5 分钟的 RS256 JWT。

2. 建立 PLog 关联

PLog 首次接入调用 POST /v1/accounts/link。服务只把 JWT sub 写入 auth_accounts，再返回内部 user_id；不会直接把 sub 当作 MindMem 用户。

3. 添加认证头

业务请求使用 Authorization: Bearer <mmos-key-or-plog-jwt>。JWT 路径可省略正文 user_id；API Key 路径仍必须提供其绑定用户 ID。

4. 为写请求设置幂等键

写操作必须携带稳定且唯一的 Idempotency-Key。同键同 payload 会重放结果，同键不同 payload 会被拒绝。

最小示例

curl https://mindmem.bowong.cc/v1/memory/add   -H "Authorization: Bearer mmos.<key_id>.<secret>"   -H "Content-Type: application/json"   -H "Idempotency-Key: message-018f6d8d"   -d '{
    "user_id": "user-your-service",
    "messages": [{"role": "user", "content": "我偏好低糖饮品。"}],
    "infer": true,
    "async_mode": false
  }'

PLog JWT 示例

curl -X POST https://mindmem.bowong.cc/v1/accounts/link   -H "Authorization: Bearer <short-lived-plog-jwt>"

curl https://mindmem.bowong.cc/v1/memory/get   -H "Authorization: Bearer <short-lived-plog-jwt>"   -H "Content-Type: application/json"   -d '{"limit": 20}'

响应约定

成功与失败都使用统一包络：

{
  "code": "ok",
  "message": "memory processed",
  "request_id": "request-id",
  "data": {}
}

不要在日志、URL、错误报告或前端持久存储中写入完整 API Key。跨项目或跨用户访问会按资源不存在处理。

接口分组

分组	入口	说明
账号	`/v1/accounts/link`	使用受信任 PLog JWT 幂等建立 account 映射
记忆	`/v1/memory/*`	add、get、update、delete、batch、history
搜索	`/v1/memory/search`	fast、schema、agentic；返回融合与 rerank 降级元数据
反馈/整合	`/v1/memory/feedback` `/v1/memory/dreaming`	反馈影响后续排序；Dreaming 支持同步或异步
任务	`/v1/jobs/{id}`	查询异步 add、Dreaming 或技能演化任务
技能	`/v1/skills/*`	注册、同步、版本内容、演化、回滚与删除

限制与重试

每个 API Key：每分钟最多 120 次请求，同时最多 8 个执行中请求。
429、503、网络超时可使用指数退避重试；重复写入必须沿用原 Idempotency-Key。
异步请求返回 HTTP 202 和 task_id，随后调用 GET /v1/jobs/{id} 查询结果。
单个 Key 的项目、用户、权限和算法版本由签发时固定，不能通过请求正文覆盖。

规范版本 1.1.0 · 下载 OpenAPI JSON · Health · Ready