Provena Agent Memory

Provena

为 AI Agent 提供有证据支持的记忆。
了解 Agent 记住了什么，以及原因。

Provena 是一款开源、可自托管的 AI Agent 记忆服务。它的 MCP 连接器可让 Codex、Claude Code、Gemini CLI 和其他客户端跨会话获取上下文。每条声明都关联到其来源事件、审核状态和范围，因此你可以检查 Agent 记住了什么，以及原因。

产品演示

观看有关设置、跨会话回忆和管理控制台的演示：

https://github.com/user-attachments/assets/37fe219c-b678-4c6d-811d-bfdd37552628

来源可追溯性为何重要

Agent 可能会检索到相关但错误、过时或来自不可信来源的信息。Provena 将原始证据与衍生记忆分开保存：

Event:         Alex says, "Pineapple on pizza is a crime."
Claim:         Alex dislikes pineapple on pizza.
Evidence:      The claim links to Alex's original words.

Later event:   Alex says, "I tried it. I owe pineapple an apology."
Updated claim: Alex likes pineapple on pizza.

Provena 会保留这两条陈述，因此可以解释 Alex 的偏好为何发生变化。事件和证据只追加，不可修改。声明具有审核状态、可选的有效时间，以及精确的租户和项目或分支范围。模型提取的声明仍是候选项；来源权威性与搜索相关性分开，不会授予执行操作的权限。memory_explain 会追溯声明的来源、审核历史、冲突和已记录的检索记录。

Provena 是一个由 PostgreSQL 和 pgvector 提供支持的 FastAPI 服务。MCP 和宿主钩子会捕获对话轮次并检索带来源信息的上下文；Ollama 或可选的托管模型会提取候选事实和嵌入向量。Next.js 控制台让人类能够检查和审核这些内容。架构详情 · 决策记录

开始使用

你需要 Python 3.11+、pipx、Docker Compose，以及一个受支持的 Agent 宿主。安装连接器并选择你的宿主：

pipx install provena-agent-memory
provena quickstart codex

对于这些宿主，请使用 provena quickstart claude 或 provena quickstart gemini。Quickstart 会启动本地服务、PostgreSQL、Ollama 和控制台；创建 Agent 和审核者凭据；并安装 MCP 以及自动捕获和检索钩子。它会输出控制台 URL。重启 Agent 宿主，并在 /hooks 和 /mcp 下检查 Provena。

首次运行会下载默认模型（约 1.26 GB）。本地 Ollama 镜像是固定摘要的 CPU 构建版本。仅安装软件包不会记录对话；运行 quickstart 才是选择启用的步骤。

检查 API 和数据库是否正在运行：

provena status

连接到现有服务

向其运营者索取 API URL、Agent API 密钥，以及项目或分支范围 ID。安装连接器后，运行：

export PROVENA_API_URL=https://memory.example.com
export PROVENA_API_KEY=paste-agent-key
export PROVENA_SCOPE_ID=paste-scope-id
provena connect codex --install

根据需要，将 codex 替换为 claude 或 gemini。对于其他 MCP 客户端，请使用 provena connect generic 输出其配置。手动设置 MCP 和访问控制台，请参阅连接器指南。

其他设置方式

• 手动自托管：下载 v0.1.15 Compose 文件，并按照部署指南获取其余文件、凭据、升级和备份相关说明。
• **从源代码开发：**按照本地开发指南设置 Python、Docker、控制台和测试。

当前限制

检索使用精确范围；尚未实现分支继承。Provena 会记录交付给 Agent 的声明，但无法证明后续操作是由这些声明导致的。了解当前保证和限制。

贡献

从一个适合新手的议题开始，或阅读 CONTRIBUTING.md。有关私密漏洞报告，请参阅 SECURITY.md；有关发布历史，请参阅 CHANGELOG.md。