Perseus Vault

为AI代理提供持久、加密的记忆。一个Rust二进制文件，一个文件，无需云服务。

已发布在 官方 MCP 注册表 · Glama · mcpservers.org · Lulu MCPs · Docker (GHCR)

为你的代理提供跨会话持久化的记忆，让它们不再重复推导已经学到的知识，也不再重复过去的错误。混合召回（BM25 + 密集 + RRF）、双时态历史记录，以及静态 AES-256-GCM 加密，以 168 个规范的 MCP 工具 形式暴露，可与任何主机配合使用。旧的 mimir_*/mneme_* 别名已在 2026-27 主要版本中移除，不单独计数。在 LongMemEval 官方测试工具上达到 73.8%（对比 Zep 63.8%，Mem0 49.0%）。 一个二进制文件。一个文件。无需 Docker。无需 Postgres。无需云服务。 本地优先，可离线部署，MIT 许可证。

一行安装

curl -sSf https://raw.githubusercontent.com/Perseus-Computing-LLC/perseus-vault/main/scripts/install.sh | sh

就这样。Perseus Vault 已安装到 ~/.local/bin/perseus-vault。启动它：

perseus-vault serve --db ~/.perseus-vault/data/perseus-vault.db

默认安装会自动启用加密。 首次运行会创建 ~/.perseus-vault/secret.key，权限仅限所有者，并生成一个加密数据库的 canary 文件。请备份该密钥：它无法恢复。显式的 --encryption-key 路径仍然支持，现有的明文数据库会保留以便通过 perseus-vault init --rekey 迁移。使用 doctor 检查实际的磁盘状态。

macOS 注意（Apple Silicon）。 新构建或复制的二进制文件在首次运行时会被操作系统二进制策略 SIGKILL（输出 Killed: 9，无其他输出）——即使没有隔离属性。一行安装程序和 bootstrap.sh 从源码构建安装程序会为你临时代码签名 Perseus Vault。如果你自己构建二进制文件，请在每次重新构建后签名一次：

cargo build --release
cp target/release/perseus-vault ~/.local/bin/perseus-vault
codesign --force --sign - ~/.local/bin/perseus-vault   # required on Apple Silicon; fixes "Killed: 9"

--force 会重新签名已签名的二进制文件（每次重新构建后需要）；该步骤在 Intel macOS 上无害，在 Linux/Windows 上不需要。

然后通过一条命令将你的 MCP 客户端——以及完整的召回/捕获循环——连接起来：

perseus-vault install-client --hooks --rules

这会自动检测 Claude Code / Codex / Cursor（传递 --client <name> 用于 claude-desktop、hermes、windsurf、vscode、zed 或 generic；--all-detected 会连接所有检测到的客户端），将 MCP 服务器注册合并到客户端的配置中而不破坏任何内容（会先写入 .bak-perseus 备份），将所有客户端指向一个共享的记忆数据库，注册会话生命周期钩子（SessionStart 时注入召回，会话结束时进行清理——参见 docs/lifecycle-hooks.md 契约），并将记忆使用规则追加到 CLAUDE.md/AGENTS.md。重新运行是无害的；添加 --dry-run 可以预览它将触及的所有文件。

或者手动连接任何 MCP 主机（Claude Desktop、Cursor、Hermes Agent、Perseus 等）：

{
  "mcpServers": {
    "perseus-vault": {
      "command": "perseus-vault",
      "args": ["serve", "--db", "~/.perseus-vault/data/perseus-vault.db"]
    }
  }
}

Related MCP server: GroundMemory

为代理：通过 MCP 连接

当主要消费者是代理时，接口是 MCP——代理通过其 MCP 客户端采用 Vault，除了运行服务器本身外，无需每台机器安装 CLI：

# 1. Run the server (one line)
perseus-vault serve --db ~/.perseus-vault/data/perseus-vault.db &

# 2. Register it in the agent's MCP client config
#    { "mcpServers": { "perseus-vault": {
#        "command": "perseus-vault",
#        "args": ["serve", "--db", "~/.perseus-vault/data/perseus-vault.db"] } } }

# 3. Verify the agent-facing surface
perseus-vault doctor

perseus-vault install-client --hooks --rules 通过一条命令为 Claude Code / Codex / Cursor / Hermes 连接整个召回/捕获循环。关于面向代理的能力映射——哪个工具负责哪个工作，以及规划边界模式——请参见 docs/integration/agent-adoption.md。

30 秒快速入门

# Start Perseus Vault
perseus-vault serve --db memory.db &
sleep 1

# Remember a fact (via MCP JSON-RPC on stdio)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"perseus_vault_remember","arguments":{"category":"demo","key":"hello","body_json":"{\"text\":\"Hello from Perseus Vault!\"}"}}}' | perseus-vault serve --db memory.db

# Search for it
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"perseus_vault_recall","arguments":{"query":"Hello"}}}' | perseus-vault serve --db memory.db

记忆模型与操作边界

Perseus Vault 保持三个层面清晰分离：

• 隐式工作上下文 是主机的当前提示、对话记录以及客户端选择注入的任何上下文块。它是临时的，归主机所有；仅仅因为 Vault 返回了它，它不会被持久化。

• 显式持久记忆 是通过显式的 perseus_vault_remember、perseus_vault_capture、write 或 capture 操作写入的。Vault 服务器拥有 SQLite 记录、历史、日志、衰减、归档和清理生命周期。

• 派生投影 包括合并或合成的记录以及导出的 Markdown。它们带有来源信息，但不能替代持久的源记录，可能需要单独清理。

perseus-vault prepare 和 perseus_vault_context 读取持久记录以生成一个有限的、与任务相关的活动工作上下文。这是一个滚动快照，不是后台写入，也不承诺客户端会保留它：当任务变化时刷新它，并且不要将提示文本视为持久记忆，除非显式的 capture/write 操作成功。以召回为主的输出有预算限制（默认 1500 字符，大窗口主机为 6000，或显式的 max_context_chars）；always_on 集合上限为五个。参见 保留与上下文语义。

生命周期钩子和客户端安装程序是可选的编排。它们请求服务器拥有的召回、捕获、维护和刷新工作；它们不会成为第二个存储或改变保留策略。如果服务器或钩子不可用，继续任务而不注入记忆，并标明降级状态。主机集成可以有显式配置的本地回退，但该回退必须标记为仅本地，并且不能呈现为持久的 Vault 召回；失败的显式写入绝不能报告为已持久化。关于升级/恢复步骤，请使用 升级与迁移手册。

与每个 MCP 客户端兼容

Perseus Vault 是一个标准的 MCP stdio 服务器——相同的 perseus-vault serve 命令在任何地方都能工作。运行 perseus-vault doctor 验证你的安装，并在本地打印此矩阵。

每个客户端的复制粘贴配置片段：docs/clients/。

然后将 召回 → 工作 → 捕获 → 合并 循环连接到客户端的会话事件（Claude Code、Codex 和 Cursor 的 SessionStart/Stop 钩子，以及可移植的 AGENTS.md 回退）：docs/lifecycle-hooks.md。

与记忆清洗器（CoalWash）和运行时输出压缩器（Noisegate）组合，实现端到端的上下文预算控制：docs/integration/context-budget-stack.md。

审计 Vault 记住了什么、来自哪里、以及由谁授权：docs/evidence-chain-guidance.md——证据链、写入时来源标签，以及持久记忆的持续认证。

记忆库（每个客户端隔离，一个配置文件）

代理使用相同剧本运行 50 个客户端？不要复制配置文件——为每个项目指定记忆库，并保持一个 Hermes 配置文件、一个 Vault 和一个共享技能库：

# .hermes.md
memory_bank: acme-seo            # name → deterministic workspace hash
memory_bank_workspace: <64-hex>  # optional explicit workspace override

Hermes 记忆提供者（hermes plugins install Perseus-Computing-LLC/hermes-plugin-perseus-vault）在每个会话中解析一次库，并将每个 Vault 读写操作——预取召回、perseus_recall / perseus_remember / perseus_forget、会话结束捕获——限定到专用工作空间。库名称确定性地映射（sha256("memory-bank:" + name)），因此指向相同名称的每个实例都寻址到相同的工作空间，无需维护注册表。工作空间在服务器上是第一类对象：限定范围的维护、库之间的去重隔离，以及每个工作空间的权限清单。发现机制镜像 Hermes 项目上下文规则（最近的 .hermes.md 获胜，以 git 根为边界）；没有指令的上下文文件意味着没有库——配置的工作空间保持有效。

为什么选择 Perseus Vault

Perseus Vault 是唯一同时具备 MCP 原生、本地优先、零依赖且代理优先的记忆引擎。

LongMemEval QA（官方测试工具）

在 LongMemEval 的官方测试工具上测量的召回质量，而非自制脚本：

longmemeval_s（500 个问题），gpt-4o-2024-08-06 回答器 + LongMemEval 官方评判器；竞争对手数字为其已发布值。Perseus Vault 的 73.8% 是 3 次运行的平均值；使用官方 CoT 时为 79.0%。方法论与内容哈希（sha256）结果 →

LOCOMO（mem0 自己的测试工具）

在 mem0 自己的 LOCOMO 测试工具上测量（我们的分支），而非我们的——类别 1–4，1540 个问题，top-200，gpt-5 回答器 + 评判器：

类别 5 对抗性（446 个问题）：Perseus 63.5，Mem0 55.6，Zep 49.8。我们对 Mem0 的测量值比其已发布文件低 9.4 个百分点（评判器/平台漂移——已披露）。完整排行榜 →

双时态时间旅行（三轴）

我们最强的结构性差异化——完整的 SQL:2011 双时态历史（事务时间 和 有效时间）——在可重现、完全离线的测试集上测量。它驱动实际发布的二进制文件通过 MCP stdio，处理单轴竞争对手会出错（追溯性修正、前瞻性未来日期事实、乱序到达、信念与真相分歧、封闭时段）的困难情况：

用一条命令重现（无需 API 密钥、无需网络、无需 LLM）：

cargo build --release
python benchmark/temporal/gauntlet.py --bin target/release/perseus-vault

PASS/FAIL 判决是确定性的（墙上时钟时间戳会变化，但判决结果不会），因此正确的构建会重新运行到相同的 signature_sha256。已提交的 gauntlet_report.json 是参考。 方法论与数据集 →

对比矩阵

完整对比：Perseus Vault vs Mem0 → vs Letta → vs Zep →

压力测试：10 万个实体

Perseus Vault 可在普通硬件上处理生产工作负载。以下数据来自已提交的构件 benchmark/scale/report.json：通过 MCP stdio 驱动的真实发布二进制文件（每个语料库大小一个持久进程），AMD64 16 核，Windows 11，每次写入在发送下一条之前持久化。

完整百分位数、as_of 点查询、时间点召回和冷启动数据均在 benchmark/scale/ 中。

自行运行：python benchmark/scale/run.py

大规模召回精度：关键词失效，混合检索保持

速度只是入场券——对智能体记忆而言真正重要的问题是正确的记忆是否真正浮现？ 基于不同内容的语料库（第一方，可重现；参见 benchmark/lambda/）测量 recall@k 按模式：

100,000 个实体（1×H100，nomic-embed-text 在 Ollama 上）：

在 10 万个实体下，混合检索在 @5 时达到完美 1.000，而关键词检索仅命中约 1.5% 的时间——这产生了约 66 倍的差距。而且这个差距随着规模扩大而拉大：在 1 万个实体时，关键词 recall@5 为 0.008，而混合检索已经是 1.000；当智能体积累历史时，纯关键词记忆会悄然退化，而混合检索（BM25 + 稠密检索 + 倒数排名融合）则不会。这是 Perseus Vault 混合检索的核心论点。

同台竞技，相同机器，相同语料库，完全本地化（1×H100，Ollama — 每个系统使用完全相同的事实集、查询和子串判断器）：

每个竞品均在同一台机器上启动并运行，针对相同的本地 Ollama（qwen2.5:14b-instruct + nomic-embed-text）——无云服务，无编造数据。Letta 以 letta/letta 服务器运行（捆绑 Postgres/pgvector），在 1.00 上与 Perseus Vault 持平。Zep 的自托管社区版服务器已弃用，其 zep_python 记忆 API 现仅为 Zep 云服务独有，因此我们测量了 Zep 的实际 OSS 引擎——Graphiti 时间点知识图谱（基于 Neo4j）——实体/边提取和嵌入均在相同的本地 Ollama 上完成。其 0.20 分反映了使用本地模型构建知识图谱的真实成本（结构化提取有损失：从 6 个事实中提取 5 个实体 / 2 条边）——而非使用前沿模型的 Zep 云服务。完整构件和方法论：benchmark/lambda/results/competitors.json。

冷启动：一台裸 GPU 机器在 3.3 秒内获得其首个基于 grounding 的 RAG 答案（模型暂存在磁盘上）。

可重现： benchmark/lambda/scale_bench.py 和 competitors_bench.py。

部署在 GPU 主机（vLLM 在 MI300X/H100 上）上的模型服务器旁？查看 AMD MI300X 部署参考 — 包括实测的共驻机数字以及 /dev/shm、PID-1 和版本固定等在实际中会破坏这些堆栈的陷阱。

框架集成

即用型适配器，使 Perseus Vault 成为流行 AI 智能体框架的默认记忆后端：

每个适配器：

• 通过 MCP stdio 子进程连接（持久会话）

• 将框架的记忆接口映射到 Perseus Vault 工具

• 附带 README 快速入门指南（5 分钟即可运行）

• 具有通过模拟 MCP 传输的通过测试

任何兼容 MCP 的框架均可直接使用 Perseus Vault。请参阅 MCP 客户端和框架集成 获取完整列表。

150 个规范 MCP 工具

规范产品和工具名称。 Perseus Vault 是产品名称，集成使用规范的 perseus_vault_* 工具（例如，perseus_vault_remember）。历史遗留的 mimir_* / mneme_* / plutus_* 名称已在 2026-27 主要版本中移除——规范名称是唯一的接口。 计数是源注册表中独特规范工具的数量。兼容性别名可调用但不单独计数。 历史遗留的 perseus_vault_* 和 perseus_vault_* 名称仍然完全可调用——每个前缀都会分发到相同的处理程序——但它们在 tools/list 中不再被公告。这使公告清单保持每个工具一个名称，而不是将其翻三倍（3 倍别名膨胀），因此连接的客户端无需在每次请求时重新加载三倍的模板有效载荷。要恢复公告所有三个前缀的历史行为，请设置 PERSEUS_VAULT_TOOL_ALIASES=all（历史遗留环境变量 PERSEUS_VAULT_TOOL_ALIASES 同样生效；PERSEUS_VAULT_ 优先级更高）。

客户端兼容性 (#633)。 那些依据公告列表进行门控的客户端——它们在调用前检查 tools/list 并跳过未看到的工具——会静默地跳过针对 2.x 保险库的历史遗留 perseus_vault_* 调用，尽管调用本身会成功。已知情况：perseus CLI ≤ 1.0.22 硬编码了 perseus_vault_recall 并降级为空的仅本地召回。从任一侧修复：将 CLI 升级到 ≥ 1.0.23（调用规范名称，具有动态回退），或者在保险库上设置 PERSEUS_VAULT_TOOL_ALIASES=all 作为旧客户端仍在部署时的桥梁。

工具范围（公告层级，#1051）

默认情况下，tools/list 公告每一个规范工具。设置 PERSEUS_VAULT_TOOL_SCOPE 以为令牌和注意力受限的智能体客户端缩小公告面：

范围仅用于公告：隐藏的工具仍然可以通过 tools/call 完全调用，并且授权保持与工作空间绑定和权限清单一致。层级分类是一个 1:1 的侧表（src/mcp.rs 中的 TOOL_SCOPES），由 scripts/registry_metadata_check.py 在 CI 中强制实施——每个新工具都必须分类。admin 层级工具（migrate、purge、erase、vault_import、authority_set / authority_revoke / authority_set_signed）永远不会出现在有范围限制的列表中。

实体 CRUD

搜索与 RAG

📖 docs/retrieval-modes.md — 每种检索模式的枚举参考（keyword · dense · hybrid · graph · GraphRAG · proactive recall_when · temporal as_of）：机制、使用时机、调用方式和示例。

日志

状态

生命周期

质量

关键件（策略规则）

保险库与联邦

指标与运维

按任务分类的工具（智能体速查表）

不是类别列表——而是任务列表。根据智能体尝试执行的操作选择对应行：

CLI

# Server
perseus-vault serve --db /data/perseus-vault.db
perseus-vault serve --web --port 8767 --encryption-key ~/.perseus-vault/secret.key
perseus-vault serve --llm-endpoint http://localhost:11434/api/generate --llm-model llama3
perseus-vault serve --transport sse --port 8787 --mcp-token my-secret-token

# Maintenance (operate directly on DB, no server needed)
perseus-vault stats          --db /data/perseus-vault.db
perseus-vault forget         --db /data/perseus-vault.db --category decision --key stale-choice --reason "superseded"
perseus-vault prune          --db /data/perseus-vault.db --category junk --min-decay 0.1 --dry-run
perseus-vault purge          --db /data/perseus-vault.db --dry-run
perseus-vault decay          --db /data/perseus-vault.db
perseus-vault reindex        --db /data/perseus-vault.db
perseus-vault vault-export   --db /data/perseus-vault.db --vault-dir ./export/
perseus-vault vault-import   --db /data/perseus-vault.db --vault-dir ./export/
perseus-vault obsidian-sync  ~/obsidian-vault/Perseus Vault/          # one-shot export to an Obsidian vault
perseus-vault obsidian-sync  ~/obsidian-vault/Perseus Vault/ --watch  # continuous sync on every memory change

# Key management
perseus-vault keygen --key-file ~/.perseus-vault/secret.key

# #918: read-only TUI inspector (retrieval telemetry, claim cards, entity
# state, decay, bi-temporal history). Never writes; repairs go through the
# governed MCP tools. Requires the default `tui` feature.
perseus-vault inspect --db /data/perseus-vault.db --key-file ~/.perseus-vault/secret.key

无需重启会话的实时更新

perseus-vault serve 会检测自身二进制文件在会话期间是否被替换（正常的 cargo build / 重新安装流程），并拒绝从过时的进程映像提供结果——每个工具都会返回一个明确的错误，而不是降级为空结果（#858、#1045）。两种恢复路径，均在同一 stdio 连接上（无需客户端重启）：

• 显式： 调用 perseus_vault_handoff_restart {"confirm": true}——进程热切换到新二进制文件，会话无缝继续，MCP 会话状态（初始化 + 智能体身份）得以保留。

• 自动（选择加入）： 使用 PERSEUS_VAULT_AUTO_HANDOFF=1 启动服务器，切换在下次工具调用时透明进行，由新二进制文件直接响应。

在 macOS/Linux 上，切换是真正的 exec（相同 PID，相同管道）。Windows 会锁定正在运行的可执行文件，因此无法在会话期间进行替换；请在会话边界进行更新。完整协议和本地开发工作流：docs/specs/live-update-handoff.md。

手动数据库编辑。 上述维护命令和正常的 MCP 写入路径会自动保持 FTS5 索引同步。使用 sqlite3 直接编辑 entities 表（手动 DELETE/UPDATE）会绕过该同步，并可能留下孤立的索引行——对已消失内容的“幽灵”召回命中。进行任何直接 SQL 编辑后，运行 perseus-vault maintain --db <path>（或 perseus-vault reindex）以协调 FTS 索引。

标志

数据库位置

规范数据库路径为：

~/.perseus-vault/data/perseus-vault.db

在脚本、MCP 主机配置和 cron/采集任务中始终传递 --db（或设置 $PERSEUS_VAULT_DB_PATH），以便每次调用都指向同一文件。当两者均未设置时，Perseus Vault 按以下顺序解析默认路径，并使用第一个已存在的路径（以便升级者和旧版单用户安装被识别，而不是静默地以空状态启动）：

1. ~/.perseus-vault/data/perseus-vault.db — 规范（当前名称）

2. ~/.perseus-vault/data/perseus-vault.db — 重命名前

3. ~/.perseus-vault/data/perseus-vault.db — 重命名前

4. ~/perseus-vault.db — 旧版单用户安装位置

如果都不存在，则创建 ~/.perseus-vault/data/perseus-vault.db。如果存在多个且您未传递 --db/$PERSEUS_VAULT_DB_PATH，Perseus Vault 会在 stderr 上打印警告，指明所选文件及其忽略的其他文件，从而使多数据库的歧义状态可见而非静默。显式设置 --db 或 $PERSEUS_VAULT_DB_PATH 始终优先并抑制该警告。

Obsidian 中的 AI 记忆

Perseus Vault 是您 AI 智能体的长期记忆——同时它也是您的第二大脑。您的智能体记住的每个实体都会导出为带有 YAML 前置元数据的纯 Markdown 笔记，因此您 AI 的记忆成为您已在使用的工具中可导航的个人知识库：Obsidian、Logseq 或 Notion。

# Export your entire memory to an Obsidian vault as linked Markdown notes
perseus-vault obsidian-sync ~/obsidian-vault/Perseus Vault/

# Keep it live — re-export automatically on every memory change
perseus-vault obsidian-sync ~/obsidian-vault/Perseus Vault/ --watch

在 Obsidian 中打开仓库，您将获得智能体知识的图谱。

WikiLink 反向链接。 当一个实体链接到另一个实体时（通过 perseus_vault_link 或 depends_on / implements / references 关系），导出的笔记会获得一个 ## Links 部分，其中包含在 Obsidian 图谱视图中原生解析的 [[WikiLink]] 反向链接：

---
id: cli-de8dfb8364b6
category: architecture
key: api
type: insight
decay_score: 0.5000
---

{"content":"axum service"}

## Links

- [[cli-99756b494c7d|database]] (depends_on)

链接按实体 ID 解析（笔记写为 <id>.md），因此它们永远不会中断，Obsidian 会显示人类可读的 key 作为链接标签。打开图谱视图，您的智能体的架构、决策和见解将变为可点击的知识地图。

--watch 按间隔轮询 Perseus Vault 廉价、确定的状态摘要，仅在内存实际更改时重新导出。它自然能捕获每次 perseus_vault_remember 写入，无需文件系统监视器依赖，也无需与服务器耦合。使用 PERSEUS_VAULT_SYNC_INTERVAL_SECS 调整间隔（默认：2 秒）。

其他 PKM 工具

与纯云端的“第二大脑”工具不同，Perseus Vault 100% 本地运行，使用 Rust 编写，使用 AES-256-GCM 进行静态加密，并应用衰减评分，使过时的记忆逐渐淡出——您的知识库始终属于您并保持新鲜。

功能

语义搜索（默认开启）

• 捆绑的内嵌嵌入 — 一个量化的 all-MiniLM-L6-v2 模型（384 维）被编译到二进制文件中，因此密集/语义搜索可以零配置和零网络工作：无需 Ollama，无需 API 密钥，无需模型下载。这是默认构建（bundled-embeddings 特性）。

• 写入时自动嵌入 (#271) — perseus_vault_remember 在写入每个新实体（或内容发生变化的实体）时同步地使用捆绑模型进行嵌入。单实体嵌入是确定性的，并采用 LRU 缓存，因此成本低廉且不会增加后台任务。嵌入失败不致命（记录到 stderr）；写入始终成功。

• 混合是默认的召回模式 (#271) — 当存在嵌入时，perseus_vault_recall(query=...) 不带 mode 标志会自动选择混合（密集 + 关键词通过 RRF 融合），并在没有嵌入时透明地回退到 fts5 关键词搜索。无需手动执行 perseus_vault_embed 步骤，无需记住任何标志。

• perseus_vault_semantic_search(query, limit) — 一个单工具快捷方式，用于纯密集的、基于含义的搜索（无关键词回退），当您只想“查找类似内容”时使用。

• 可选的外部嵌入器 — 要使用 Ollama 或任何兼容 OpenAI 的 /v1/embeddings 端点替代捆绑模型，请设置 --llm-endpoint（以及必要的 --embedding-endpoint / --llm-api-key）。这完全是可选的；默认使用捆绑模型。

• 通过 cargo build --no-default-features 构建一个没有捆绑嵌入的精简二进制文件 — 召回将默认为关键词搜索，除非配置了远程嵌入器。

混合搜索内部机制

• FTS5 关键词搜索，带有 LIKE 回退和波特词干扩展

• 密集向量搜索，通过存储嵌入的余弦相似度

• 倒数排名融合 (RRF) — 结合关键词和向量结果

• 查询扩展 — 自动词干变体以扩大召回范围

记忆生命周期

Perseus Vault 使用三个仿生层来模拟记忆，灵感来自人类记忆路径：

• 世界（核心）：缓慢衰减的、关于环境的全局事实。

• 情景（缓冲区）：快速衰减的、特定会话的交互历史。

• 语义（工作）：中等衰减的、通用知识和已学概念。

您可以使用 perseus_vault_recall_layer 工具或通过指定 perseus_vault_remember 中的 layer 参数直接与这些层交互。

• 艾宾浩斯遗忘曲线 — 记忆会自然衰减，除非被检索（访问时刷新）

• 层提升 — 基于访问频率，缓冲区 → 工作 → 核心

• 自动归档 — 过期实体自动归档；清除以永久删除并执行 VACUUM

• 始终在线实体 — 固定身份关键记忆以进行会话注入（在召回优先模式下硬性上限；优先使用 recall_when 触发器）

• 前瞻查询提示 (#919) — 每个实体可选的 1-3 个自然语言表述（perseus_vault_remember 上的 hints），这些提示与正文一起被索引到 FTS5 中，弥合了普通语言查询和存储措辞之间的词汇差距。默认关闭（PERSEUS_VAULT_HINTS_ENABLED=1）；禁用时被拒绝。请参阅 docs/specs/prospective-query-hints.md。

召回优先上下文注入

存储库是查询层 — 它检索当前轮次所需的少数事实，而不是向主机提供一个固定的文本块来塞入每个系统提示。perseus_vault_context 和 perseus-vault prepare 默认使用召回优先模式：

• 相关性门控 — 传递 query（当前任务/消息），只有其 recall_when 触发器或索引内容匹配的实体才会被注入。没有查询，就没有主题注入：该块是一个紧凑的检索指针，在不相关的存储库写入之间保持字节稳定（对前缀缓存友好）。

• 每个模型的召回预算 — 输出被限制为一个从主机模型解析的字符预算：默认/精简配置文件 1500 字符；大窗口（"opus"）配置文件 6000 字符；max_context_chars 覆盖两者。

• 上限的始终在线 — always_on: true 仍然适用于身份关键事实，但召回优先集有硬性上限（前 5 个），溢出时会发出警告，引导您使用 recall_when 触发器。

• 旧版选择加入 — 旧的、无条件的前 N 个转储仍然可以通过 mode: "always_inject"（prepare 的 --legacy-context）使用，除非您传递预算，否则不加限制。

perseus-vault prepare --task "deploying the payments service" --model claude-sonnet-4-6
perseus-vault prepare --task "..." --max-context-chars 800     # explicit budget
perseus-vault prepare --task "..." --legacy-context            # old dump, opt-in

RAG 与嵌入

• perseus_vault_ask — 通过任何 LLM（Ollama、OpenAI 等）对存储的记忆进行自然语言问答

• perseus_vault_embed — 通过 Ollama 或兼容 OpenAI 的 /v1/embeddings 生成并存储密集向量

• 支持单实体和批量类别嵌入

加密

• AES-256-GCM 对实体 body_json 进行透明加密

• 新安装默认启用 — 标准密钥在首次写入时自动生成于 ~/.perseus-vault/secret.key

• --encryption-key 标志用于显式密钥；perseus-vault keygen 用于自定义密钥生成

• 现有的明文数据库在 init --rekey 迁移路径下会安全关闭（或显式设置 PERSEUS_VAULT_ALLOW_PLAINTEXT=1）

• FTS5 索引保持明文以支持搜索

网页仪表盘

• 内置 Axum HTTP 服务器（perseus-vault serve --web --port 8767）

• 深色主题仪表盘，包含搜索、实体表、vis.js 图形、时间线

• 默认绑定：127.0.0.1（使用 --web-bind 0.0.0.0 暴露）

• 独立的 SQLite 连接，采用 WAL 模式以支持并发读取

外部连接器

• GitHub 问题连接器 — 按仓库摄取问题/PR，具有速率限制感知

• 文件监视器 — 扫描目录中的 .md/.txt/.json 文件，并使用内容哈希去重

• 基于 YAML 的连接器配置，通过 --connectors-config

多传输

• stdio（默认）— 零配置，适用于任何 MCP 主机

• SSE — 服务器发送事件，用于基于 HTTP 的 MCP 客户端

• HTTP — REST 风格的 MCP 端点

• Bearer 令牌认证 — 用于 SSE/HTTP 传输

Perseus 集成

Perseus Vault 是 Perseus 的默认记忆后端：

perseus_vault:
  enabled: true
  transport: "stdio"
  command: ["perseus-vault", "serve", "--db", "~/.perseus-vault/data/perseus-vault.db"]
  timeout_s: 30.0
  merge_strategy: "local_first"
  fallback_to_local: true
  context_categories: ["decision", "architecture", "convention"]
  context_limit: 10

政府与联邦采购

Perseus Vault 从一开始就为政府部署而构建。

对于联邦买家： 请参阅 docs/federal-buyers.md 了解采购信息、合规状态和部署模型（离线环境、本地部署、机密环境）。

Perseus Computing LLC 是一家美国独资的小企业。SAM.gov 注册正在进行中。 NAICS：541715、541511、541512。

隐私政策

Perseus Vault 是一个本地优先的 MCP 服务器 — 它完全在您的机器上运行。

数据收集

• 无数据收集。 Perseus Vault 不收集、传输或回传任何用户数据、使用统计或遥测信息。

• 所有数据保留在您的本地 SQLite 数据库文件中。

数据使用与存储

• 所有记忆实体、日志条目和状态都存储在您通过 --db 指定的路径的本地 SQLite 数据库中。

• 可选的 AES-256-GCM 静态加密 可用 — 启用后，实体主体在存储前会被加密。

• 不会与 Perseus Computing LLC 或任何第三方共享数据。

第三方共享

• 无。 Perseus Vault 默认完全离线。没有 API 调用、没有云服务、没有外部网络请求。

• 可选的密集向量嵌入功能使用本地编译的模型 — 不调用外部嵌入 API。

数据保留

• 您通过四种不同的生命周期操作控制保留（请参阅 docs/specs/data-boundaries-retention-lifecycle.md）：软删除（perseus_vault_forget，内容可恢复）、过期（perseus_vault_expire，基于时间的 status='expired'，内容保留）、编辑（perseus_vault_redact，内容被清除为仅哈希，元数据保留）和物理擦除（perseus_vault_erase，从所有派生层中移除，并永久抑制重新摄取）。perseus_vault_purge 从归档行中回收空间。

• 不执行自动的异地备份。

联系方式

• 电子邮件： privacy@perseus.observer

• GitHub： Perseus-Computing-LLC/perseus-vault

发布验证

发布二进制文件通过 GitHub Actions 从标记的提交构建。每个发布提供：

验证发布二进制文件

# 1. Verify SHA-256 checksum
sha256sum -c perseus-vault-lite-x86_64-unknown-linux-musl.tar.gz.sha256

# 2. Verify SLSA build provenance (requires gh CLI + OIDC session)
gh attestation verify perseus-vault-lite-x86_64-unknown-linux-musl.tar.gz \
  --repo Perseus-Computing-LLC/perseus-vault

# 3. Confirm the binary identity
./perseus-vault --version
# Should show both the release version AND the git commit hash, e.g.:
#   perseus-vault 2.20.2 (v2.20.2-0-gabcdef1)

# 4. Confirm the doctor reports the same identity
./perseus-vault doctor --db /tmp/test.db | head -1
#   perseus-vault doctor — v2.20.2 (v2.20.2-0-gabcdef1)

从源码可重现构建

# The exact same binary (bit-for-bit) requires matching:
#   - Rust toolchain version (see rust-toolchain.toml)
#   - Locked dependencies: `cargo build --locked`
#   - Build flags: `--release` for release builds

cargo build --locked --release
./target/release/perseus-vault --version

许可证

MIT — 请参阅 LICENSE。