01
五个动词
内核对外的全部接口，不多不少。remember
写入。对话、单条事实、整段文本、设备事件均可；新旧矛盾时旧的标记失效，不删除。
recall
检索。多路并行后融合；带 explain 时给出每条的命中路径与有效状态。
profile
画像。由事实推演出的结构化槽位与一段叙事，每一项都可追溯到依据。
forget
遗忘。单条否决需写明理由、可恢复；删除会话连带派生内容；全量清除返回回执。
explain
溯源。这条记忆来自哪句话、哪个模型、哪个 prompt，被谁取代。
02
接入
与控制台「快速开始」同一份代码，登录后可以直接复制带密钥的版本。选一种接入方式。它们用同一把 API 密钥，写进同一个记忆库。
准备一把 API 密钥
在「API → 密钥」里创建。密钥只在创建时显示一次，请当场保存。 去创建密钥 →
安装
pip install openai调用
from openai import OpenAI
client = OpenAI(
base_url="https://api.reglos.ai/v1",
api_key="<你的 API 密钥>",
)
resp = client.chat.completions.create(
model="gemini-2.5-flash",
user="alice", # 记忆归属
messages=[{"role": "user", "content": "我周末喜欢做什么？"}],
)
print(resp.choices[0].message.content)已经在用 OpenAI SDK 的应用，只改 base_url 就有了长期记忆：每轮提问前先检索记忆，回答后在后台写回。user 字段就是记忆归属。检索超时或出错时，会降级成一次不带记忆的普通对话，不会让你的对话中断。没有配置自己的模型时，请求会转发到服务端的模型，model 请填 gemini-2.5-flash。
密钥在控制台「API → 密钥」中创建，仅在创建时显示一次。服务端密钥可代任意 subject 读写，不可下发到终端；终端使用设备 token。
03
错误码与限流
错误体只有一种形状 {"detail": "…"}；按状态码分支，按 detail 前缀细分。| 状态 | 什么时候 | 该做什么 |
|---|---|---|
| 400 | 请求语义不成立：五选一一个没给、confirm 不等于 subject、幂等键不合法 | 改请求，不要重试 |
| 401 | 未携带 key、key 无效或已停用、设备 token 无效 | 更换 key，不要重试 |
| 403 | 该 key 或设备 token 绑定了其他 subject | 去掉 subject 参数，或更换正确的 key |
| 404 | 记忆 / 会话 / 文档不存在 | 视业务决定，不要重试 |
| 422 | 缺参数、类型不对、超长；detail 是字段数组 | 改请求，不要重试 |
| 429 | 每分钟限流，或本月配额用尽；带 Retry-After | 等 Retry-After 秒；配额用尽则升级 |
| 5xx | 服务端故障 | 指数退避重试，最多 3 次 |
限制
- 每分钟限流 / 月度配额
- 按 API key 配置，一次鉴权请求算 1 次调用，读写同价、不按 token
- services/quota.py
- 请求体
- ≤ 30 MB；remember:batch ≤ 200 条；observations ≤ 5000 条
- 网关 + kernel.py
- 检索
- 缺省 45 条；单次 2.5 s 超时后返回其余各路的结果并列出 timed_out_paths，不 5xx
- recall.py
- 同步写入
- mode=sync 一段对话 5–30 s；网关读超时 300 s
- nginx
- 幂等
- Idempotency-Key ≤ 128 个 ASCII，保留 7 天；重放返回首次回执
- idempotency.py
- 活跃 key
- 同一账号最多 5 把
- api_key.py
完整表（每条 detail 文案、重试矩阵、curl 与 Python 例子）在仓库 docs/API_ERRORS.md 与 docs/API_LIMITS.md。