核心概念
Markdown 版API 背后的数据模型:Space、Entry 与版本、文件、知识、记忆、分支和访问控制。
Mirabase 的来源层只有一种数据:Entry 加不可变版本。文件是 Entry 的定位方式,知识是它的处理结果,记忆的一部分来源于它。
Entry
├─ id, space_id, title, metadata
├─ latest_version_id newest committed version
├─ current_version_id version serving search
├─ file { path, size, media_type, etag } or null
├─ knowledge { state, indexed_version_id }
├─ memory { scope, kind, pinned, exclude } or null
├─ memory_exclude kept out of memory distillation
└─ access { role, capabilities }Space
Space 是权限和路径的边界。每个账户有一个默认 Space,也可以用 POST /v2/spaces 创建更多 Space。成员、角色和文件树都按 Space 划分。
一个账户可以有多个 Space(上限为 tenant_spaces,见 限流与限额),因此可以为每个最终用户或每个项目分别创建一个。删除 Space 会删除其中的全部内容,不能撤销,默认 Space 不能删除,见 DELETE /v2/spaces/{space_id}。
一个最终用户一个 Space
最终用户之间要硬隔离时,给每个用户一个 Space:文件、知识和记忆都按 Space 分开,元数据做不到这一点。把你自己的用户 id 设为 Space 的 external_id,之后在需要 Space id 的地方写 ext:<external_id>,例如 ext:user-42。路径、?space_id= 和请求体中的 space_ids 均支持这种写法,无需维护映射表。
PUT /v2/spaces/ext:<external_id> 有则返回、无则创建。同时到达的两个请求只创建一个 Space,重复调用也是安全的,所以给新用户写入之前调用一次即可。SDK 里对应 spaces.ensure,spaceFor(Python 是 space_for)还会返回一个固定在这个 Space 上的客户端。
# Returns the Space whose external_id is user-42 (200), or creates it (201).
curl -X PUT "https://api.mirabase.dev/v2/spaces/ext:user-42" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "User 42"}'
# ext:user-42 works wherever a Space id does.
curl -X PUT "https://api.mirabase.dev/v2/spaces/ext:user-42/files?path=/notes/plan.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: text/markdown" \
--data-binary "We ship on Friday."search、context和answer不传space_ids时读取这个 Key 能读取的全部 Space,不只是默认 Space。请求只涉及一个用户时,请指定这个用户的 Space。SDK 中固定在一个 Space 上的客户端只读那个 Space。GET /v2/spaces?external_id=按external_id查找,最多返回一个 Space,不会创建(SDK 的spaces.findByExternalId、spaces.find_by_external_id)。- 删除 Space 之后,它的
external_id可以再次使用。
Entry 与版本
Entry 是一份来源的稳定身份:文件、网址或一段文本。每次内容变化产生一个版本,版本不可变,版本链一直保留。
latest_version_id是最新提交的版本,读取操作默认使用该版本,因此刚写入的内容立即可读。current_version_id是search和context读取的版本。最新版本完成索引后它等于latest_version_id;更新的版本还在处理时,它仍是之前的版本。第一版处理完之前不存在。- 修改标题也会产生新版本,因为标题会编入索引。版本上唯一可修改的字段是
message。
同一个 Entry 可以按路径、按 id 或按语义(检索)到达。身份、权限和版本链是同一套。
文件
有路径的 Entry 即文件。路径即身份:两个路径存放相同的字节即为两个文件。改名和移动不改变 Entry id。没有路径的 Entry 也合法,比如用 ingest 导入的网址和文本,它们的 file 是 null。
有路径用 `files`,按 id 用 `entries`,两者的读取参数相同。详见 文件与版本。
知识
知识不是单独的资源,而是 Entry 的处理状态。写入提交后,后台解析、切块、建索引,状态在 knowledge.state 上:
| 状态 | 含义 | 能做什么 |
|---|---|---|
readable | 已提交 | 按路径或 id 读取原件 |
searchable | 请求体中 64 KiB 以内的文本已进入新鲜缓冲 | 词法检索 |
indexed | 处理完成 | 全文检索、向量检索和重排检索 |
failed | 处理失败,字节仍可读 | 读取原件,或调用 reprocess |
写入在处理完成之前就已提交。需要等待处理完成时,在写入请求中带上 Prefer: wait=N,见 PUT /v2/spaces/{space_id}/files。
记忆
记忆是一条有范围、状态和来源的陈述:账户记忆、以 Entry 写入的记忆,或从 Entry 提炼出的事实。提炼出的事实不是 Entry,它的 id 也不是 Entry id;范围、状态和有效期见 记忆模型。
分支
分支是叠在 Space 主线上的写时复制层,用作 Agent 的工作区。分支里的内容不产生版本、不处理,合并进主线时每个路径才成为一个新版本。详见 分支与挂载。
访问控制
每个请求以一个主体(人或 Agent)的身份执行,由 API Key 携带。请求能做什么,取决于主体和 Key 共同持有的能力、主体在 Space 里的角色,以及 Space 所有者为成员设的读写根路径,见 权限。
