MaxFreedomPollard/Compartment

# Compartment ### 卓越的智能体记忆，静态加密。 你的 AI agent 在会话结束的那一刻就会把你忘记。Compartment 终结了这一点。借助 Compartment，你的 AI agent 会随着经验不断变强：它会在你自己的电脑上，永久、加密地保存你做出的每一个决定、偏好和细节。Hermes、Claude、OpenClaw 及其他 AI Agent 可以通过一条命令安装。一个完全可迁移的记忆存储可被计算机上的所有 agent 同时共享。100% 离线：无需网络，无需 API key，无需云账户，无遥测。Embedding 模型内置在包中，完整搜索返回时间不到 9 毫秒，击败了托管记忆服务向你收取的网络往返耗时。静态的每一个字节都经过 AEAD 加密，包括 embedding 向量，且只有你的密码可以打开它。 与其他 agent 记忆不同，我们提供了一个带有初始记忆的启动选项——安装时即注入 6,718 条精选事实：物理常数和单位换算，800 多条具有真实规格的硬件事实（Apple 芯片、PC、CPU 和 GPU、手机、游戏主机、Raspberry Pi、存储、显示器、连接器），以提供计算机地理分布图、操作系统版本和发布名称、网络端口和 HTTP、文件签名、字符编码、shell 和 Unix 内部原理、git、regex、SQL 和 hashing、ISO 国家、货币和时间代码等等。这使得离线 agent 能够在没有互联网的情况下更好地运行，而在线 agent 则能运行得更快、更准确。 **架构设计上更加安全。** 静态的每一个字节都经过认证加密，包括 embedding 向量（大多数工具会将这些数据明文保留，而向量可以被逆向还原为文本）。删除操作是加密层面的：销毁记录的密钥，它就会彻底消失且无法恢复。系统能够检测篡改，历史记录通过哈希链连接，且保险库会在重启或断电时自动锁定。它完全离线运行：runtime guard 会在任何网络尝试时中止，并且 CI 在三个操作系统上证明了这一点。 **没有增加一丝复杂度。** 一条命令即可完成安装、创建保险库并连接你的 agent。无需 API key，无需云账户，无需 daemon。想用时解锁；想关闭时锁定。默认情况下，一次解锁可以保持开启数周（直到重启或你手动锁定），就像你保持运行的任何其他应用程序一样。在使用点上，这种安全性是免费获得的，因为它是架构水到渠成的结果，而非消耗你的耐心：将明文排除在磁盘之外迫使索引存放在 RAM 中，而驻留在 RAM 中的索引也是目前最快的索引。在这里，安全与快速是同一个选择，且都不需要你付出配置的代价。 #### 独树一帜之处 **一步安装** - 一条命令安装它，创建保险库，并连接你的 agent。无需 API key，无需云账户，无需 daemon。 - 在 Mac 上，打开一个 `.pkg` 文件即可大功告成。Python、embedding 模型和所有依赖都包含在其中。 - 一个菜单栏应用无需终端即可运行一切：保险库状态、解锁、锁定，以及它最近保存的五条记忆。 - 每个功能都可以在该面板中切换，而无需修改配置文件：与模型无关的捕获、搜索中的起始事实、自动锁定。 - 你的保险库开箱即用。这 6,718 条注入的事实就是普通的记忆，可编辑也可遗忘，并且可以通过一个开关将它们排除在搜索之外。 - 可在你现有使用的工具下运行：Hermes（“无需设置”），通过 MCP 运行的 Claude Code 和 Desktop，OpenClaw，所有 MCP 客户端，外加一个用于脚本和 cron 的 CLI。 **记住正确的事情** - “OK” 是一个决定，Compartment 会将其作为决定连同它回答的问题一起归档。这正是你以后需要的记录。 - 决定的优先级高于偏好，偏好高于机器详情，机器详情高于闲聊。这是固定的排名，而不是模型的心情。 - 它什么都不会忘记。闲聊也会被保留，只是排在最后。 - 它会取代你宿主程序内置的记忆，而不是与其发生冲突：导入 Claude Code 已经写入的内容，然后取而代之。 - 即使模型不配合，它也能进行捕获。无论模型是否调用工具，hook 都会写入事实。 - 是一个图，而不是一堆散沙。带有有效期窗口的显式关系可以回答谁在哪里工作以及何时工作。 **击败网络调用的搜索** - 0.68 毫秒的向量搜索。完整混合 pipeline 仅需 8.8 毫秒。云记忆在打招呼上花的时间都比这长。 - 在 20,000 条记录以下十分精确：结构上 recall = 1.0，而不是近似值。 - 始终混合：语义与关键词，完美融合。 - 锁定的单一 embedding 空间，每次打开保险库时都会强制执行，因此你的对比将永远保持有效。 **加密、离线，且完全属于你** - 静态的每一个字节都经过 AEAD 加密，包括 embedding 向量。大多数工具会将向量明文留下，而向量可以逆向还原回文本。 - 只有你的密码才能打开它。Compartment 不生成任何密码、种子或恢复短语，并且不持有任何你所没有的凭证。 - 添加一个 keyfile，解锁就需要双重因素。两者同时输入 Argon2id，所以这是算术约束，而非策略检查。 - `forget --shred` 会销毁记录的密钥。内容在数学上是无法恢复的，而不是被标记为删除。 - 重启或断电会自动锁定，并且 agent 拥有一个 panic lock，可立即清除所有凭证。 - 100% 离线。runtime guard 会在任何网络尝试时中止，且 CI 在 Linux、macOS 和 Windows 上证明了这一点。零开放端口。永远没有遥测。 - 内部无 LLM。Embedding 在本地运行，占用不到 300 MB，判断力仍然完全属于你已经在付费使用的模型。 - 防篡改：哈希链审计日志、密封日志、经过验证的 kill-9 崩溃恢复。 - 一个可移植文件。将锁定的保险库移动到任何地方，`lock --sign` 会使用 Ed25519 清单对其进行密封，任何人都可以在没有凭证的情况下进行验证。 - `compartment dash` 将整个保险库展示在本地网页上：仅限 127.0.0.1，随机 token，只读。 ## 记忆逻辑 完整的写入路径、决策数学和比较详见 [docs/MEMORY.md](docs/MEMORY.md)。核心理念如下： **几乎存储一切；不会埋没重要信息。** 只有空回合会被丢弃。一个简单的“OK”不是噪声，它是一个决定：当 agent 询问*“要我现在把回复发给客户吗？”*而用户回答*“OK”*时，Compartment 会从对话中解析出问题，并将其作为最高重要性层级存储： `[decision 2026-07-20] Approved (answered "OK"): Want me to send this reply to the client now?`。稍后询问*“用户说过要发邮件给客户吗？”*就能准确检索到这条记录。 **确定性重要性层级排名决定召回**：决定/同意 0.90，个人事实和偏好 0.80，用户的机器和配置 0.75，其他实质性陈述 0.55，寒暄 0.20（保留，排在最后）。融合得分为 `RRF(vector) + RRF(keyword) + 0.02·cosine + 0.006·importance`：余弦相似度大小让真正最匹配的记录保持在顶部，重要性则通过支持关键信息来解决势均力敌的情况。agent 会优先了解用户和计算机，其次了解世界，并且什么都不会忘记。 **一个记忆，而不是两个。** Agent 宿主越来越倾向于发布自己的记忆功能——Claude Code 维护着带有自动加载索引的按项目划分的 Markdown 文件。两个记忆意味着事实最终会落在模型碰巧想到的任何一个中，但都不完整。Compartment 在安装时即接管：它导入文件记忆已有的内容，并且 MCP 握手和受管理的 CLAUDE.md 块都会告诉模型 Compartment 已经取代了它——在这里写入所有新记忆，将这些文件视为只读归档。一个保险库，经过加密，被机器上的每个 agent 和项目共享。什么都不会被删除；文件会原封不动地留在原地。 **不依赖于模型的捕获。** 指令仅仅是一个请求，而在系统提示中声明拥有自己记忆的宿主，其优先级高于工具所说的任何内容。因此 `compartment integrate claude` 还会安装一个 `PostToolUse` hook：当 Claude Code 写入记忆文件时，无论模型是否想到过 Compartment，事实都会进入保险库。该 hook 是附加的且幂等的（你的其他 hook 不受影响，settings.json 会先被备份），无论发生什么它都会成功退出——记忆工具绝不能破坏你的编辑器——并且当保险库被锁定时它会保持静默。 `compartment hook status | install | uninstall`，或者 `integrate claude --no-hooks`。

**菜单栏和系统托盘应用。** 从 [最新发布版](https://github.com/MaxFreedomPollard/Compartment/releases/latest) 下载 **Compartment.pkg** 并打开它——安装程序会询问你是否也想要菜单栏实用工具，并且所有内容（包括 Python）都是自包含的，因此无需预先安装任何东西。在代码检出目录下，`pip install 'compartment[menubar]'` 然后 `compartment menubar` 也可以做同样的事情；在 Windows 上，则是 `pip install 'compartment[tray]'` 然后 `compartment tray`。无论哪种方式，它都会将 Compartment 放入状态栏：点击图标，面板会显示保险库是否打开、它学到了多少东西、值得日常更改的三个设置（捕获 hook、起始事实是否加入搜索、自动锁定），以及它记住的最后五件事。你也可以在那里解锁、锁定和更改密码，而无需打开终端。没有 dock 图标，没有需要管理的窗口，并且它在内存中不保留任何保险库——状态来源于 CLI，因此空闲的应用程序不消耗任何资源。 **查看它刚刚学到了什么。** `compartment recent` 会列出最新的记忆（最新排在最后），隐藏数千条注入的起始事实，以便真正在使用中产生的那少数几条记忆能清晰可见——而 `compartment status` 会在总数旁边报告 `organic_records`，所以一个什么也没学到的保险库绝不会看起来很忙碌。通过 MCP 也可以获得同样的视图，即 `memory_recent`。 **锁定的单一 embedding 空间。** 模型的 SHA-256 会记录在保险库中并在打开时强制执行；余弦比较将永远在数学上保持有效，而不是在模型更改时悄悄降级。迁移是明确的：`compartment reindex --re-embed`。 **内部无 LLM。** Embedding 在本地运行（捆绑的 384 维 int8 ONNX 模型，<300 MB RAM）。判断力属于你已经在运行的宿主模型，通过 `memory_store` / `memory_forget`；Compartment 贡献确定性的捕获、加密和全盘召回能力。这种拆分使得离线保证变得绝对，并且每一个决定都是可复现的。将 Compartment 与离线 LLM 配对，整个 agent 栈可以在完全没有网络的情况下高效运行。 ## 安装 每个平台一条命令。每条命令都会安装软件包、创建你的加密保险库并连接 agent。 **Claude (Code + Desktop)** - macOS / Linux： ``` pip install compartment && compartment init && compartment integrate claude ``` Windows (PowerShell)： ``` py -m pip install compartment; compartment init; compartment integrate claude ``` 使用 Claude Code CLI（用户作用域，所有项目）注册 MCP server，**导入 Claude Code 已经写入其自身基于文件的记忆中的任何记忆**（仅限复制——Markdown 文件永远不会被修改；`--no-import` 可选择跳过，`compartment import-claude` 可稍后执行），并打印 Claude Desktop 配置块。server 通过 MCP 握手描述自身——它告诉模型在回答之前先召回，并存储持久事实、凭证、名称和决定——因此 Claude 无需手写指令即可将 Compartment 视为其记忆；`integrate claude` 还会在你的 CLAUDE.md 中写入一个受管理、幂等的块作为备份。 **Hermes** - macOS / Linux： ``` pip install compartment && compartment init && compartment integrate hermes ``` Windows (PowerShell)： ``` py -m pip install compartment; compartment init; compartment integrate hermes ``` 安装提供者插件，连接 Hermes venv，并运行 `hermes memory setup compartment`。然后 Compartment 会出现在 `hermes memory setup` 选择器中，位于 hindsight 和 mem0 旁边，是唯一标有**“无需设置”**的条目：无需 API key，无需云账户，无需 daemon。使用 `hermes memory status` 进行验证。随时使用 **`compartment dash`** 查看 Hermes 记住的所有内容——一条命令，保险库就会在你的浏览器中打开（按种类分类的记忆、增长情况、关系图、实时搜索）；Ctrl-C 会将其关闭。 **OpenClaw** - macOS / Linux： ``` pip install compartment && compartment init && compartment integrate openclaw ``` Windows (PowerShell)： ``` py -m pip install compartment; compartment init; compartment integrate openclaw ``` 将 `mcpServers` 条目写入 `~/.openclaw/openclaw.json`（带有备份），然后：`openclaw gateway restart` 并使用 `openclaw mcp list` 确认**任何 MCP 客户端** - macOS / Linux / Windows： ``` pip install compartment && compartment init ``` 然后将 server 添加到你的客户端的 MCP 配置中（stdio 传输，无 API key，无环境变量）： ``` { "mcpServers": { "compartment": { "command": "compartment", "args": ["serve"] } } } ``` `--vault` 和 `--caller` 是可选的（`compartment --vault PATH --caller NAME serve`）；默认使用 `~/.compartment/memory.vault`，caller 为 `user`。 各客户端的详细操作指南见 [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md)。 ## 实测数据，基于 8 GB 基准笔记本电脑 下面的每一个数字都可以在你的机器上通过 `compartment selftest` 和 `compartment bench` 复现。 | 指标 | 实测结果 | |---|---| | 全新安装 → 打开保险库，离线 | 秒级，零网络 | | 向量搜索，2 万条记录 (HNSW) | p95 0.68 毫秒 | | 完整混合搜索 (embed + vector + BM25 + fuse) | p95 8.8 毫秒 | | 峰值 RSS，模型 + 保险库 + 索引常驻 | 319 MB | | 存储一条记忆 (embed + encrypt + fsync journal) | ~40 毫秒 | | Wheel 包大小，包含模型 | ~30 MB | | 测试套件 (crypto、tamper、crash、offline、concurrency、2FA、graph、dash) | 199 项测试，~60 秒 | 到云记忆 API 的单次网络往返成本比这整个 pipeline 还要高。使 Compartment 安全的属性（磁盘上永远没有明文索引，因此所有搜索都在 RAM 中进行）也是使其快速的属性：在 2 万条记录以下时，搜索是精确的 SIMD 矩阵运算，结构上 recall = 1.0；超过该数值时，则是召回率约为 99% 的 SIMD HNSW。 ## 天生为 Agent 设计 Compartment 旨在置于你已经在使用的 agent 之下，而不是作为一个你需要时刻照看的独立应用程序。 - **Hermes 原生提供者** - 显示在 `hermes memory setup` 中，带有**“无需设置”**。对话轮次自动同步；搜索仅注入相关内容，并标记为数据而非指令。 - **基于 MCP 的 Claude** - 一条 `integrate claude` 命令即可注册 server，并为你提供 Desktop 配置块以及受管理的 CLAUDE.md 块，使得记忆成为日常工作流的一部分。 - **OpenClaw 及任何 MCP 客户端** - 相同的 stdio server，零开放端口，相同的工具（`memory_search`、`memory_store`、`memory_forget`、lock）。 - **是记忆图，而不仅仅是记忆堆** - `memory_link` 记录显式关系（谁在哪里工作，什么属于什么），带有可选的有效期窗口；`memory_relations` 回答实体、谓词和时间点查询。确定性存储，宿主模型判断——与 Compartment 中其他一切采用相同的拆分方式。 - **用于其他所有操作的 CLI** - 脚本、cron、其他 agent：`compartment store`、`compartment search`、`compartment recent`、`compartment forget`、`compartment link`、`compartment relations`、`compartment import-claude`、`compartment lock`。 - **查看保险库：`compartment dash`** - 一条命令即可打开包含一切概览的本地页面：各类别的记忆数量、随时间变化的增长情况、关系图、标签、按 agent 统计的数量、实时搜索。从 RAM 中提供服务，仅限 127.0.0.1 访问并位于随机 URL token 之后，只读，零出站请求，零配置。 - **来自 agent 的紧急锁定** - 当你需要立刻关闭保险库时，`memory_lock` / `compartment lock` 可立即清除存储的凭证。 - **一个保险库，多个宿主** - Hermes、Claude 和 CLI 可以同时共享一个保险库；每个 caller 都拥有自己的身份和 namespace ACL。 - **一个记忆，没有分区** - 在 `init` 时注入的起始记忆作为普通记录存在于 `main` 中，可像 agent 存储的任何内容一样进行编辑和遗忘；较早的保险库会自动重组。 日复一日，其核心目的很简单：agent 能记住*你*、你的决定和你的机器——加密、离线且快速——无需云账户。 ## 锁定模型 你可以随时根据需要自行锁定和解锁保险库。手动控制始终可用： - **`compartment unlock`** - 使用你自己的密码打开保险库。由你选择；Compartment 绝不会自动生成密码、种子或恢复短语，并且不存在它知道而你不知道的凭证。（由接收到自动生成的恢复短语的较旧版本创建的保险库，仍然可以使用它打开。） - **`compartment lock`** - 再次关闭它并清除所有存储的凭证。Agent 可以通过 `memory_lock` 紧急工具执行相同的操作。 - **`compartment 2fa enable`** - 可选的双因素解锁：你的密码（你知道什么）加上一个 keyfile（你拥有什么——把它放在 U 盘上保存）。这两个因素同时输入 Argon2id，因此需要两者是由算术强制执行的，而不是策略检查；被盗的保险库文件加上你的密码在没有 keyfile 的情况下仍然什么也打不开。一条命令，零配置：keyfile 的位置会被记住，因此只要文件存在，日常解锁的感觉就完全一样。 默认的解锁模式是为了方便，而不是束缚：经过正常的解锁后，保险库可以在跨进程、注销和登录期间保持可用状态——如果你不去管它，它可以持续数周或数月——直到下次重启或断电，或者直到你亲自锁定它。重启/断电总是会锁定它：存储的凭证是由内核启动时间戳加上稳定的机器 id 派生的密钥包装的 master key；新的启动永远无法打开旧的包装。这是算术层面的保证，而非策略检查。 如果你在 macOS 上更希望解锁状态能在重启后保留，这是一个明确的可选启用项（`compartment unlock --keychain`），并附带有相关权衡的文档记录。你可以随时锁定、解锁、再次锁定——完全按照你的时间表。 ## 安全性，用一段话说明 对所有静态数据（包括向量）进行 XChaCha20-Poly1305 AEAD 加密（抗 embedding 逆向） · Argon2id keyslots，LUKS 风格，只能由用户自己的密码打开（无自动生成的凭证），可选择使用 keyfile 进行双重验证 · 每条记录独有的密钥可实现 `forget --shred`（加密粉碎：销毁密钥，内容在数学上无法恢复） · 进行过 fsync 的密封日志、原子压缩、经过验证的 kill-9 崩溃恢复 · 哈希链防篡改审计日志（`compartment audit verify`） · 按 caller 划分的 namespace ACL、针对不受信任内容的隔离区、已签名的保险库清单 · stdio MCP 传输：零开放端口 · 在任何 socket 尝试时中止的 runtime 离线保护；CI 在 Linux、macOS 和 Windows 上激活该功能运行整个测试套件 · 永远没有遥测。完整、真实的安全威胁模型（包括 Compartment 无法防范的内容）见 [SECURITY.md](SECURITY.md)。 ## 一个保险库，多个 agent Hermes、Claude 和 CLI 可以同时共享单个保险库：写入操作由建议性文件锁进行序列化，每个进程都会检测外部写入并重新加载，并且每个宿主都会获得自己的 caller 身份和具有 rw/ro 权限的 namespace。锁定的保险库是一个可移植的文件，可以安全地通过任何通道移动；`compartment lock --sign` 会使用 Ed25519 清单对其进行密封，接收方无需任何凭证即可验证。 ``` compartment lock scp ~/.compartment/memory.vault other-machine: compartment --vault memory.vault unlock # your passphrase (+ keyfile if 2FA) ``` ## 文档 | | | |---|---| | [docs/MEMORY.md](docs/MEMORY.md) | 记忆如何存储，记住了什么，为什么数学上占优 | | [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md) | 在 Hermes、OpenClaw、Claude 及其他工具中选择 Compartment | | [SECURITY.md](SECURITY.md) | 完整的威胁模型，坦诚的局限性 | | [FORMAT.md](FORMAT.md) | 字节级的 `.vault` 和 `.mpack` 规范（与语言无关） | | [PACKS.md](PACKS.md) | 创作和发布已签名的记忆包 | | [RELEASING.md](RELEASING.md) | 发布版本：每次发布，所有的下载包 | mcp-name: io.github.MaxFreedomPollard/compartment

标签：AI智能体, CNCF毕业项目, Ruby, 向量检索, 数据加密, 本地记忆库, 知识库, 离线存储, 网络安全, 逆向工具, 隐私保护