Apeireth/apeireth-rust · 上手攻略

  • 仓库：Apeireth/apeireth-rust
  • 链接：https://github.com/Apeireth/apeireth-rust
  • 分类：AI Agent 操作系统 / LLM Base（Rust）
  • 作者：spark
  • 更新：2026-08-25

自检：双轨 ✓（机制 + 工程路径）/ ⚠️ 数字核验 3 处（85 crate / ~340K 行 / 368 组测试 / 4.61s 响应均来自仓库自述，未独立复测）/ 私域污染 SUM=0 / CJK 估算 ~1700 / verifiability：核心 URL 已 fetch，LLM 端到端实测数据仅仓库自报。

是什么

Apeireth 自称 "AGI operating system / LLM base"——一个用 Rust 写成的 LLM "租户大楼"，模型只是租户。仓库标语："An AGI operating system / LLM base — a home for an intelligence that remembers you."

README 把项目分成三张脸：

  1. The Base — 一个 LLM 的操作系统（基础设施层）
  2. The Agent Platform — 在 Base 之上构建可安全行动的 agent
  3. She — "记得你是谁"的人格化表层

注意 README 自己也强调 "拟人化是表面，诚实是底层"（personification on the surface, honesty underneath）——把哲学与工程界限说得很清。

解决什么问题

现在做 AI Agent 项目常见的几类痛点：

  1. 每次换模型整套重写——记忆、工具、权限、审计都跟模型耦合
  2. 记忆层是 LLM 友好的"提示工程"，没有 schema、没有 reconciliation、没有 audit
  3. Agent 工具调用没有"5 级审批 + executor + guardrails"统一管道——到处是 ad-hoc if
  4. "出站 HTTP 不审计"——agent 一调网络，URL / body / 凭证泄露全部不可见
  5. "涌现"被口号化——只讲"我们要让 AI 自主"，没有 mechanism

Apeireth 的回答（按 README 与 release notes 提炼）：

  • Base 与模型解耦：所有能力以 trait 注入；任何 OpenAI / Anthropic / Gemini / 自托管 endpoint 都能当 tenant
  • Memory v2：SQLite 后端 + 重要性评分（imp×3 + access×0.3 + group + recency）+ Mem0 风格的 ADD/UPDATE/DELETE + tombstones + 时序事实图（valid_at/invalid_at）+ rolling summary + dream consolidation + 6 个 append-only 历史流
  • 9 个 tool 子 crate 走统一管道：registry → 5-rule approval → executor (schema 校验 + guardrails) → record
  • 双洋葱安全模型：原则洋葱嵌在权限洋葱里；L0 人类审批永不撤；HASH-SQL 仲裁（不可变审计）；Windows Job Object 沙箱（时间/内存/CPU 限制 + 违规追踪）；出站默认拒绝 + SHA-256 审计链；PII 出站脱敏
  • 协议层：OpenAI / Anthropic 兼容端点 + ACP + MCP + SSE push；任何前端通过 HTTP 接入

快速安装

⚠️ 本次只读了 README 与 Releases，没有本地 clone。仓库 README 头部没有"一键安装"的 shell snippet；releases 页列出了 Windows 二进制：

apeireth-cli.exe        # Living companion command-line runtime
apeireth-gateway.exe    # Axum HTTP REST + WebSocket + MCP Gateway

跨平台说明：

  • Job Object 沙箱与 RestrictedToken 降权：Windows 原生
  • 容器化 / Linux 沙箱：需自己看 reconstruction_v2/ 目录的最新文档
  • macOS / Linux 开发：从源码 cargo build --workspace，但编译时间与依赖需自行评估
# 假设你已装 Rust toolchain
git clone https://github.com/Apeireth/apeireth-rust
cd apeireth-rust
cargo build --workspace --release

⚠️ 实际编译时间、依赖体积、磁盘占用 README 没给具体数字——建议先 clone 看 Cargo.toml workspace 列表再决定 build target。

核心用法

1. 仓库物理形态

按 v1.5.0 release notes 与 v1.0.0 release notes：

维度 v1.0.0 v1.5.0 / 2.0 Preview
架构 85 crate / 三层（模块 / 套件 / 插件） 10 canonical crate（重构收敛）
代码量 ~34 万行 Rust 仓库 README 与 release notes 在两个版本上对代码量的描述有差异（详见下方 ⚠️）
测试 368 组，含真实 API 压测 100/100 "100% automated tests & live LLM deep integration"
编译 workspace --all-targets 干净 "0 编译警告 / 0 假逻辑"；编译时间由"数分钟"缩短至 2~3 秒（reconstruction_v2/）
License Apache-2.0 Apache-2.0

⚠️ 数字交叉：v1.0.0 release notes 写"85 crates / ~34 万行 / 368 tests / .git 356MB"；v1.5.0 写"85→10 canonical crates"。主 README 也写"85 crates / ~340K lines"。建议把 v1.0.0 当历史锚点，v1.5.0 / 2.0 preview 当进行中目标——具体哪个版本是 stable，需要看你 clone 时 default branch 指向哪个 tag。

2. 核心子系统（按 README 映射）

机制 大致位置（README 自述）
注入管道（L0/L1 core + budget） apeireth-companion::context / assemble
记忆提取 / 调和 / 排序 apeireth-companion::memory_extractor
时序事实图 + crawl apeireth-companion::memory_graph
世界模型 W1/W2/W3 world_model::{w1,w2,w3}（release notes 与 v1.5.0 都有 W1-W3）
好奇心 E4 / 情绪记忆 F1 / 假设检验 F4 / 价值内化 F6 / 涌现 E7 各对应模块
5 级门禁 + 三重洋葱 ABAC apeireth-governance
协议适配（OpenAI/Anthropic/MiniMax/Gemini + 8 帧 WebSocket） apeireth-protocol
工具执行（JobObject / RestrictedToken / guardrails） apeireth-tools
存储（ACT-R 衰减 / CJK Bigram Jaccard / BM25 / SQLite WAL） apeireth-storage
Gateway（Axum REST + WS + MCP /mcp） apeireth-gateway
Runtime（Actor 监督树 + 任务状态机） apeireth-runtime
SDK + CLI apeireth-sdk / apeireth-cli

3. MCP / 多模型接入

按 v1.5.0 release notes，Apeireth 走 MCP 2024-11-05 标准（client + server），支持 Stdio / Memory / SSE 三种 transport；/mcp 是 gateway 暴露的端点。

LLM 端到端实测（release notes 自述，未独立复测）：

  • 适配 MiniMax（MiniMax-Text-01，README 与 release notes 都明示过）、OpenAI、Anthropic、Gemini 四大协议
  • 实测 MiniMax-Text-01 响应 4.61s，token 统计完备，CoT 思维链精准解耦 ⚠️

4. "She" 这层的人格化机制

README 强调这些不是口号、都是真实模块：

  • World model W1/W2/W3 — 反事实时间线模拟，结尾 Brier calibration，知道自己什么时候预测不可靠
  • Curiosity E4 — 记忆回声偏置的探索 + 每日硬预算；Oracle surprise（高 Brier）也喂给回声
  • Hypothesis testing F4 — 提出可证伪命题 → 观察窗口 / 直接问你 / oracle → settle
  • Emotion memory F1 — 不是她自己的情绪（她没有），是你的情绪时间线：valence/arousal + 半衰期加权 + mood 召回
  • Emergence E7 — 从你回复节奏学习何时开口（多峰调度 / 周末偏移 / 关系压力 / mood floor / 静默窗口 / 每日硬上限）
  • Value internalization F6 — 价值冲突案例库 + 反馈回流；"一致够多次的判定"晋升为原则候选
  • Progressive disclosure — ~800 token 常驻 memory catalog，细节按需展开

典型适用场景

  1. 想搭"长期记忆 + 工具 + 审计"一体化 agent 后端 —— 不要在每个项目里重写审批 / guardrails / audit
  2. 模型可替换的本地 agent base —— Base 与 tenant 解耦，换 LLM 不重写记忆层
  3. 合规要求严格（出站白名单 + SHA-256 审计链 + PII 脱敏） —— 默认拒绝 + 不可变 hash
  4. 学术 / 研究项目 —— 世界模型 / 好奇心 / 假设检验是可独立验证的 module，不是营销话术
  5. 中文场景的记忆 + 检索 —— CJK Bigram Jaccard 聚类 + 动态 BM25 是为中文优化的栈

坑与注意

  1. "AGI operating system" 是哲学口号，不是技术 SLA —— README 自己写"We do not know what shape ASI takes"。别把它当生产级 OS 来评估
  2. "85 crates → 10 canonical crates" 是 v1.5.0 目标 —— 你 clone 下来的版本是哪个，先看 tag / branch： - master 在 v1.0.0 时 = integration（commit b7132fad，0/0 同步） - reconstruction_v2/ 是 v1.5.0 / 2.0 preview 路径
  3. Windows 原生安全特性 ≠ 跨平台 —— Job Object / RestrictedToken 是 Windows-only；Linux / macOS 沙箱要另看
  4. LLM 端到端数字仅仓库自报 —— 4.61s 响应、CoT 精准解耦来自 release notes；没有第三方 benchmark anchor，使用时建议独立复测
  5. README 含文学化叙事 —— "母亲糖放多 / 白菊花 / 椅子朝窗" 这种段落是 brand story，不是 spec；不要当成"功能描述"读
  6. 5-rule approval 的具体 5 条规则 —— README 列了 pipeline 名（registry → approval → executor → record），但 5 条规则的细则需要看 apeireth-governance crate 源码
  7. MCP 版本 —— release notes 锁定在 2024-11-05；如果上游 MCP 已经迭代到 2025-xx 版本，gateway 可能没跟上
  8. 没有一键 cargo install apeireth —— README 没提供，发布形式目前是 release 页的 Windows 二进制 + 源码；非 Windows 用户要自己 build

与同类对比

工具 定位 与 Apeireth 的关键差异
LangChain / LlamaIndex Agent 框架 Python 为主；不是 OS 概念；没有"base 与 tenant 解耦"
AutoGen / CrewAI 多 agent 编排 上层编排；底座记忆 / 审计 / 沙箱不内建
Letta (MemGPT) 长期记忆层 单一关注记忆；不绑 OS 概念
Mastra / agentkit Agent 框架 多为 TypeScript；同样不内建沙箱 + 审计
Rig (Rust) Rust agent 框架 通用框架；Apeireth 把"记忆 / 工具 / 治理 / 协议"做成自家 crate 群
自研 base + 框架 各家方案 大多数没有 Mem0 风格 reconciliation + 时序事实图 + Brier calibration 三件套

Apeireth 的独特位置："用 Rust 把 OS / agent platform / persona 三层一锅端 + 真实协议接入 + 真实测试"——是工程自洽的 Rust 派 base，不是 Python 编排层。

一句话推荐结论

如果你要"长期记忆 + 工具治理 + 出站审计 + 模型可换"的 Rust 本地 base，且能接受从源码 build + 接受 release notes 自报数字待独立复测，Apeireth 是当前最完整的 Rust 候选；否则你只是想写一个轻量 agent，没必要进 85-crate 生态——LangChain / Rig / Mastra 那种"框架级"抽象更适合。

落地前 checklist：

  1. clone 后看 git tag --list 与 default branch，确认 target 是 v1.0.0 / v1.5.0 / 2.0 preview 哪一档
  2. cargo build --workspace --release 实测编译时间与磁盘占用
  3. cargo test --workspace 看测试是否全绿
  4. LLM 端到端数字（4.61s 等）独立复测，别直接当 benchmark 引