OneLedger

自托管的 Agent 记忆总账：本机收集、安全扫描、蒸馏队列、MCP 供给其他 Code Agent 调用，并可与远端节点同步。版本 0.4.9。桌面壳 只使用 Tauri，禁止 Electron。

服务器地址和存储后端不写死，在管理界面里配置。默认本机 SQLite；中心节点可改接 Postgres。

要求

• Node.js 22+

• Rust（Tauri）

默认只在本机跑。数据在 ~/.oneledger（可用 ONELEDGER_HOME 改）。

Related MCP server: heropen

启动

npm install
npm run check
npm run dev

npm run dev 打开 Tauri 窗口。发版：npm run pack（OneLedger-Setup.exe / OneLedger-Portable.exe）。

无窗口 API（仅服务，不是管理台入口）：npm run start 或 npm run dev:server。

给其他 Agent 用的 MCP

本机 stdio：

{
  "mcpServers": {
    "oneledger": {
      "command": "npx",
      "args": ["tsx", "src/index.ts", "mcp"],
      "env": {
        "ONELEDGER_HOME": "C:/Users/you/.oneledger"
      }
    }
  }
}

HTTP：管理台签发 Agent 密钥后，url 为 http://127.0.0.1:7443/mcp，Authorization: Bearer ol_...。

桌面版 HTTP MCP 继续使用现有 Agent 密钥。每把密钥从同一来源地址首次连接时，Tauri 原生窗口会要求用户确认，确认时可勾选「记住此设备」——勾选后这台电脑上该密钥从同一地址连接不再询问，记录保存在本机 SQLite，可随时在管理台 MCP 密钥页的「记住的连接」里撤销；未勾选则维持原行为，重启 OneLedger 后重新确认。拒绝则本次请求不会进入 MCP 工具。新签发的密钥除哈希外，还会以 Windows DPAPI 加密保存在本机，可在 Tauri 管理台逐次确认后再次查看完整值。升级前仅存哈希的旧密钥保持可用，但无法从哈希恢复原值；若首次默认密钥仍保存在本机 FIRST_MCP_KEY.txt，启动时会将其加密补存，不改变密钥本身。

工具：memory.search / memory.remember / memory.forget / memory.list / memory.get / memory.export / memory.import。覆盖已有作用域时先读取 rev，再在 memory.remember 中传入 expectedRev；版本不一致会返回 conflict。完整识别的凭据只以脱敏占位符写入；无法安全脱敏的材料会拒收，原始 secret 不进入可检索记忆，也不会同步到远端。memory.export 导出一份 oneledger-backup JSON（同一格式，桌面控制台导出的是全量备份，MCP 导出为可共享的记忆子集：不含 secret/pii 记忆、收件箱、凭据密文与密钥材料）；memory.import 把这份文件按 id 合并回账本（记忆仅当文件 rev 更新时覆盖），每次导入都要在 Tauri 窗口原生确认。管理台「记忆」页的「导出全部数据 / 导入备份」使用同一个备份文件，覆盖数据库全部内容（含收件箱、凭据密文、Agent 密钥、审计等；config.json 设置不在备份内）。

运行模式

命令：oneledger serve · oneledger mcp · oneledger collect · oneledger version

版本与热更新

• 程序版本：package.json / APP_VERSION

• 图标源：brand/oneledger.svg；窗口、exe、安装包、向导页都从这份 SVG 生成

• 通道文件：app_update.json（累计 history）

• 检查更新：顶栏或「服务器与存储 → 关于与更新」

• 便携版：下载 OneLedger-Portable.exe，校验固定仓库域名与 .sha256 后替换正在运行的 exe 并重启

• 安装版：下载 OneLedger-Setup.exe，同样校验后退出并打开安装程序覆盖安装

• 两套互不混用。数据在 ~/.oneledger，热更新不碰用户数据。不要求代码签名证书

• 配置 schema：config.schemaVersion；数据 schema 启动时迁移；同步协议：X-OneLedger-Protocol

发版前把新说明插到 app_update.json 的 history 最前面，再打 v* tag。Release 正文用当前这条的 title / body。

安全边界

• 入库扫描密钥、连接串、高熵串；出库不再返回 secret

• 管理台 token 与 Agent MCP key 分离

• 蒸馏默认规则摘要；若配置了兼容 OpenAI 的接口，只发送已脱敏文本

本机凭据空间

Tauri 管理台的「凭据空间」可保存需要保留原值的敏感文本。Windows DPAPI 以当前登录用户保护原值，用户无需再管理第二把密钥。每次保存、替换、整理、查看和删除都需要在原生窗口明确确认；查看结果在管理台显示 15 秒。

人与 Agent 可以协作整理凭据：Tauri 管理台可保存、替换、改名、移动、查看和删除；桌面版 HTTP MCP 提供 vault.list（仅目录元数据）、vault.put（新增或替换）、vault.organize（只改名称或作用域，保留密文）和 vault.delete。现有 Agent 密钥沿用记忆工具的读写权限，不需要再签发第二把密钥；每次 Agent 写入、整理或删除都须在 Tauri 窗口原生确认。MCP 没有查看已保存原值的工具。Agent 提交原值时，该原值会经过 Agent 的上下文与工具调用，请只提交已授权它处理的内容。

原值不进入记忆、inbox、FTS 搜索、蒸馏、普通导出和节点同步。名称和仓库名属于未加密的目录信息，不能填入原值。凭据协作工具只在桌面版 HTTP MCP 上提供，独立的 stdio MCP 仍只提供记忆工具。

DPAPI 密文通常只能由保存时的 Windows 用户在原电脑解锁。当前版本尚无跨电脑恢复功能，不能把单份数据库文件当作凭据备份。