kaeru

# 蛙 kaeru `kaeru` 是一个**跨代理认知引擎**，适用于大型语言模型（LLM）代理。它是一个类型化的图，代理在其中思考，并具有一个回忆层，用于长期想法和结果。每个代理都是本地优先的，但可以选择加入一个共享的云层，以便整个团队的代理和人员可以相互借鉴。 `kaeru`的设计灵感来自LLM-wiki模式、Graphiti / Zep的双时间知识图方法、Cognee的知识引擎以及PageIndex的基于推理的分层摘要导航模式。其设计基于海马体/皮层分离的双层结构。 名称：蛙（*kaeru*，“frog”；与日语“帰る”to return和“変える”to change谐音）——返回、回忆和重塑的代理。  _{A kaeru vault rendered by [`kaeru-viz`](kaeru-viz/) — one cluster per initiative, nodes sized by memory layer, with reasoning-chain replay and a time-lapse of how the knowledge grew.} ## 概述 `kaeru` 建立在 CozoDB 中存储的类型化属性图之上。分为两层，类比于生物学： - **认知层（操作层 / 海马体）** — 高速运转的工作图，代理在此积极思考：事件、草稿、假设、实验、审计事件。 - **回忆层（存档层 / 大脑皮层）** — 沉淀的想法、结果、总结、引用；大多为只读。 每个节点和边都是**双时间**的——底层存储原生支持主张/撤销历史，因此时间旅行查询是开箱即用的，冲突解决是非破坏性的（旧版本被标记为无效，而不是删除）。 通过连接关系模式实现每个项目的子图：一个底层，多个项目，多重成员。代理在项目 A 上工作时询问“上次我在这里做了什么？”，并获得仅限于项目 A 的答案。同一节点可以同时属于多个项目。 `kaeru` 是一个**促进者，而不是强制者**。策展人 API 暴露了约 40 个基本操作（`awake`、`recall`、`drill`、`claim`、`synthesise`、`at`、`history`、`consolidate_out`等）供代理使用。代理和用户可以选择何时调用它们；守护进程提供提示，但不会阻止。 ## 功能 - **双层图** — 操作层（认知层 / 海马体）用于主动思考；存档层（回忆层 / 大脑皮层）用于沉淀知识。`consolidate_out` 在边界上保留出处。 - **双时间** — 原生主张 / 撤销历史。`at` 读取节点在当前或过去任何时刻的状态；冲突是非破坏性的（旧版本被标记为无效，而不是删除）。 - **项目范围 + 分层重入** — 一个底层，多个项目。`awake` 通过内存层（核心 → 热点 → 温存）恢复项目的上下文；`surface` 按需访问存档的冷 / 冻结层。 - **跨代理共享** — 默认本地优先；可选的 `kaeru-cloud` 层允许受信任的团队通过两个安全门共享沉淀的知识（项目策略 + 确定性秘密保护）。详见[本地和云端](#本地和云端--共享内存跨团队)。 - **结构化召回** — 精确名称查找、类型化 `walk` / `drill` / `trace`、`between`、全文搜索模糊 fallback。向量不是主要模式。 - **项目管理** — `rename` / `delete` 项目，本地或团队范围内。 - **Markdown 导出** — Obsidian 友好的任何项目快照。 ## 架构说明 - **底层是 CozoDB**，带有 RocksDB 后端；双时间 `Validity` 原生于底层，而不是附加的。 - **边携带操作语义** — 每种边类型都是策展人 API 响应的内容。`derived_from` 支持出处和可解释性；`contradicts` 触发非破坏性 `under_review` 流；`supersedes` 通过双时间底层撤销先前版本。边不仅仅是关联。 - **`audit_event` 是一种一等节点类型** — 每次变更都写入审计节点，因此对内存的变更本身成为代理的推理表面。底层历史（`Validity`）和操作审计（审计节点）保持分离：底层跟踪*存在过什么*，审计节点跟踪*谁做了什么以及为什么*。 - **通过连接关系实现项目范围**，而不是列过滤 — RocksDB 前缀扫描在活动项目上提供 O(log n + k)。 - **检索优先采用结构化方式** — 显式名称查找、类型化图遍历、摘要视图。Cozo FTS 用于模糊 fallback，当忘记确切名称时。向量嵌入不是主要模式。 - **双层且有明确的 `consolidate_out`** — 操作草稿被提升到存档层，作为一个刻意的、记录的操作。出处（`derived_from`）在层边界上存活。 - **单个二进制文件，嵌入式底层** — `kaeru` 在进程内与代理一起运行。无需服务器，无需网络。vault 存储在磁盘上的平台特定默认位置（Linux `$XDG_DATA_HOME/kaeru`，macOS `~/Library/Application Support/ai.lamantin.kaeru`，Windows `%LOCALAPPDATA%\ai.lamantin.kaeru`）；可通过 `KAERU_VAULT_PATH` 重写。 ## 布局 ``` kaeru/ ├── Cargo.toml ← 工作区根目录 ├── kaeru-core/ ← 库：底层、模式、基本操作 ├── kaeru-mcp/ ← 二进制文件 `kaeru-mcp`：模型上下文协议服务器（代理的接口） ├── kaeru-cloud/ ← 二进制文件 `kaeru-cloud`：共享云层（基于 kaeru-core 的 Axum REST） ├── kaeru-rig/ ← 库：`rig` 工具，为 rig 代理提供 kaeru 内存 └── skills/ └── kaeru-skill/ ← 可移植代理技能（Claude Code 等） ``` `kaeru-rig` 是 [rig](https://github.com/0xPlaygrounds/rig) 框架适配器 — 完整的策展人动词集作为离散的 rig `Tool`s，适用于嵌入式 `Arc<Store>`，因此 rig 代理可以读写一个保险库。未来：`kaeru-langchain`（Python 桥），尚未启动。 ## 安装 > **1.0 alpha 版本之前**。底层模式可能会在次版本号之间发生变化 — > 如果您需要保留笔记，请导出到 markdown。 参阅 [QUICK_START.md](QUICK_START.md)，了解源代码构建、MCP 守护进程设置和重入仪式。 ## 快速游览（MCP 工具） ``` # 查看存在的项目： initiatives # 重入仪式：处理状态 + 认知状态。 awake (initiative: "auth-rewrite") overview (initiative: "auth-rewrite") # 捕获（自动命名）： jot (initiative: "auth-rewrite", body: "noticed token expiry differs across platforms") # 模糊查找，当您忘记确切名称时： search (initiative: "auth-rewrite", query: "expiry") # 深入研究某事： drill (initiative: "auth-rewrite", name: "noticed-token-expiry-differs-across-...") # 假设循环： claim (initiative: "auth-rewrite", body: "platform-aware policy is correct", about: "<node>") test (initiative: "auth-rewrite", hypothesis: "<hyp>", method: "compared iOS / Android TTL") confirm (initiative: "auth-rewrite", hypothesis: "<hyp>", by: "<experiment>") # 时间旅行： at (initiative: "auth-rewrite", name: "<name>", when: "5m") history (initiative: "auth-rewrite", name: "<name>") # 知识链 — 两个节点之间最强的加权路径 # （链接带有强：true 的承载边）： path (initiative: "auth-rewrite", from: "<a>", to: "<b>") # 预览线索 chain (initiative: "auth-rewrite", from: "<a>", to: "<b>") # 保存为可回忆的链 # 快照到 Obsidian 友好的 markdown 保险库： export (initiative: "auth-rewrite", path: "/tmp/auth-snapshot") ``` ## 连接到 MCP 感知代理 `kaeru-mcp` 是一个长寿命的 HTTP 服务：**一台机器上的一个守护进程**拥有底层，任意数量的代理会话（Claude Code、Opencode、Cursor 等）并发连接。这是故意的 — RocksDB 是单写入器，因此标准输入/输出 MCP 分叉每个会话的子进程将遇到锁竞争。参阅 `kaeru-mcp/README.md`，获取 systemd / launchd 单元模板和完整的 HTTP 配置。 运行守护进程（或从 `contrib/install/` 设置 systemd 用户单元）： ```bash kaeru-mcp # 前台，Ctrl-C 停止 ``` 然后将您的代理指向它： - **Claude Code**：`claude mcp add --transport http kaeru http://127.0.0.1:9876/mcp` — 参阅 `skills/kaeru-skill/`，获取可移植的系统提示规则。 - **Opencode**：`bash contrib/opencode/install-opencode.sh` — 连接守护进程，将 `AGENTS.kaeru.md` 规则放入 `~/.config/opencode/`，并安装 `/kaeru` / `/lesson` / `/recall` 斜杠命令。设计用于与现有的 OSS 模型提供商配置（Qwen / DeepSeek / GLM / Ollama）共存。参阅 `contrib/opencode/README.md`。 - **Cursor 和其他运行时**：将 `skills/kaeru-skill/SKILL.md` 的内容粘贴到您的代理的规则 / 系统提示部分。对于 MCP 感知客户端，上述守护进程 URL 直接有效。 重启后，代理会看到 `awake`、`drill`、`claim`、`at` 等工具。每个工具都接受一个可选的 `initiative` 参数。 ## 本地和云端 — 跨团队共享内存 `kaeru` **本地优先运行**：您的保险库位于您的机器上，默认情况下没有任何内容离开它。第二个可选层 — `kaeru-cloud` — 是受信任群体的共享存储库（团队、家庭）。每个项目都带有粘性 `share_policy`： - `private`（默认）— 任何内容都不会离开；个人项目。 - `team` — 您明确标记为 `shared` 的节点可能会同步到云端。 共享从不自动进行，并经过两个门槛：项目策略和确定性**预共享秘密保护**，它会阻止类似 API 密钥、令牌或私钥的任何内容。保护措施对干净的内容保持沉默，仅在实际命中时中断。 动词（通过 MCP）：`policy`（标记项目为 `team`）、`share`（推送节点）、`cloud_recall`（查看团队拥有的内容）、`pull`（将共享节点带入本地图）、`link_cloud` / `cloud_links`（引用云节点而不复制），以及 `sync_review`（批量审查仍然本地的节点）。捕获动词（`episode` / `jot` / `cite`）采用 `visibility: shared` 以捕获和共享一步到位。 单个守护进程还可以访问**多个命名云**（例如 `family` 和 `work` 云），通过 `clouds.toml` 文件；云动词然后采用可选的 `cloud: <name>`，软链接记住它们指向哪个云。参阅 [`kaeru-mcp/README.md`](kaeru-mcp/README.md#configuration)，了解文件格式。 每个用户/每个组织隔离（多租户）是未来的新增功能；目前每个云都是一个共享空间，按项目范围划分。参阅 [`kaeru-cloud/README.md`](kaeru-cloud/README.md)。 ## 路线图 - **项目 onboarding** — 生成的“这是什么项目，它包含什么”简介，当代理首次进入项目，遵循 `import` 指南的精神 — 指令覆盖收集的上下文，而不是图机制。 - **PostgreSQL 后端** — 服务器模式的底层与嵌入式 RocksDB 默认值并存。 - **多租户 + 隔离** — 每个用户/每个组织的分离在共享云中。 - **跨项目链接** — 跨项目（目前所有内容都是项目范围）的边和召回。 ## 状态 1.0 版本之前。已实现并被绿色测试套件覆盖：底层和策展人 API、具有分层重入的内存层（`awake` / `surface`）、双时间时间旅行（`at` / `history`）、项目范围内的作用域和 `rename` / `delete`、知识链（加权边 + 最短路径）、前向架构迁移、MCP 服务器、共享 `kaeru-cloud` 层（共享、召回、软链接、同步审查）包括多云、`kaeru-rig` 框架适配器（完整的策展人工具集作为 rig 工具）和 markdown 导出。仍然需要强化： - **多租户**。云是一个共享空间，按项目范围划分；尚未构建每个用户/每个组织的隔离。 - **MCP 并发性**。并发会话共享一个 `Store`；每个调用的作用域通过 `Store::scoped` 序列化，因此两个会话不会破坏彼此的作用域。仍需要解决的是排序 — 当代理异步批量发送调用时，读取可能仍会在尚未应用的写入之前发生。 - **整秒 `Validity` 分辨率**。同一节点/边上的两个相反的突变在 1 秒内（例如 `link` 然后立即 `unlink`，或在写入后立即 `forget`）以不明确的方式解决。交互式使用没问题 — 人类节奏始终会跨越边界；测试套件在这些操作之间会休眠。 - **审计事件** 尚未附加到项目连接（导出按 `affected_refs` 交集过滤 — 一个有效的变通方法）。 - **Rig 适配器已发货，LangChain 尚未**。`kaeru-rig` 为 [rig](https://github.com/0xPlaygrounds/rig) 代理提供完整的内存工具集；Python / LangChain 桥接器仍在开发中。 - **迁移仅向前且仅添加**。`migration_journal` 在打开时运行模式添加（新关系/列）；没有降级或破坏性更改路径。1.0 版本之前，仍建议通过 `export` 快照。 ## 贡献 通过问题进行讨论和设计反馈。欢迎在上述开放项和代理面向的表面感觉粗糙的任何地方提交 PR。动词分类（`awake`、`drill`、`claim`、`flag`、`settle`等）旨在映射到自然的代理思维，而不是简单地暴露图操作。 ## 许可证 MIT — 参见 `LICENSE`。