概念指引
在调用 HTTP API 或配置 MCP 之前，先理解印格的两条产品线：Agent 记忆库（Persona / Scope / Topic / Atom + L0–L3 栈）与 AI Gateway（平台 Key + 逻辑路由）。
建议阅读顺序
若你是第一次集成，按下面顺序浏览公开文档即可覆盖主要概念与端点：
- 本页 — 记忆分层、记忆栈与 Gateway 核心名词
- 记忆库 API — 鉴权、/api/v1/memory 端点与写入/检索示例
- 记忆库 MCP 或 Agent Skills — 为 Cursor 等编码 Agent 配置工具与工作流
- Gateway 接入 — baseUrl、访问协议与 SDK 示例
- 逻辑路由 — 请求如何在 Gateway 端点解析与转发
记忆分层：Persona → Scope → Topic → Atom
记忆库 API 的请求与响应均使用下列四层术语。写入前先选定 Scope / Topic；Persona 通常由团队默认绑定，跨层引用在正文中以路径链接表达。
- Persona
- 召回与索引的隔离边界。同一团队可为不同 Agent、用户画像或业务角色维护独立人格空间。
- 示例：团队默认人格、客服 Bot、个人助理
- Scope
- 粗粒度主题桶，划分工作/生活大域，而不是单条记忆的标题。写入时若未填写，系统可自动建议。
- 示例：engineering、finance、operations
- Topic
- Scope 下的窄主题，按语义聚类。默认不按日历分桶；若需时间阶段，可写入 Scope / Topic 命名。
- 示例：billing、api-auth、onboarding
- Atom
- 最小可检索单元：结构化正文、可选附件，以及语义向量。一条 Atom 对应 API 中创建/检索的基本对象。
- 示例：一条结账规则、一次故障复盘摘要
记忆栈（L0–L3）与公开 API
与四层归档配合，决定 Agent 启动与对话时先加载什么、再搜索什么。集成方通过下列 HTTP 端点调用对应层级（均需 memory:read 或 memory:write）：
| Level | Role | API |
|---|---|---|
| L0 Identity | 稳定自我描述，会话身份上下文 | POST /api/v1/memory/wake-up（与 L1 一并返回） |
| L1 Core narrative | 高显著性 Atom 精选，用于快速唤醒 | POST /api/v1/memory/wake-up |
| L2 Recall | 按需召回，可限定 Persona / Scope / Topic | POST /api/v1/memory/recall |
| L3 Deep search | 全库语义检索，适合开放域问答 | POST /api/v1/memory/search |
Atom 之间的引用（Wikilink）
Atom 正文支持路径式 Wikilink，便于 Agent 在回答中跳转关联记忆。控制台可查看 Backlink 图；公开 API 写入时在 document 字段内嵌链接即可。
[[/finance/billing/invoice-rules: 每月 25 日结账]]
路径格式为 /{scope}/{topic}/{slug-or-title}。集成方无需单独调用「建边」API；引擎在索引阶段解析链接并维护反向引用。
Gateway 核心概念
Gateway 对外暴露 Gemini / OpenAI 兼容 HTTP 端点。客户端 SDK 的 model 字段与官方用法相同；路由、回退与上游 Key 在控制台配置，由网关端点解析。
- 平台 API Key
- 在控制台创建，用于访问 /g/<public-id>/... 或记忆库 /api/v1/memory。不是上游 Gemini/OpenAI Key。
- Public ID
- Gateway 详情页「访问端点」中 /g/ 后的 10 位短码，拼入 SDK baseUrl。
- 访问协议
- gemini-v1beta、openai-chat 等入口可单独启用；未启用协议返回 403。
- 逻辑路由
- 按 model、Header 或输入格式分支，串联模型连接、IF/ELSE、回退链与 prompt 模板。同一 Gateway 仅一条路由为启用。
- 模型连接
- 控制台绑定的上游提供商 Key 与模型端点；Gateway 代理请求时使用，不暴露给集成方 SDK。