Provena Agent Memory

[Provena logo]

Provena

Evidence-backed memory for AI agents.
Know what an agent remembers—and why.

[CI] [PyPI] [M8ven Score]

Provena is an open-source, self-hosted memory service for AI agents. Its MCP connector gives Codex, Claude Code, Gemini CLI, and other clients context across sessions. Each claim stays linked to its source event, review status, and scope, so you can inspect what an agent remembers and why.

Product demo

Watch a walkthrough of setup, cross-session recall, and the operator console:

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

Why provenance matters

An agent can retrieve a relevant fact that is wrong, stale, or taken from an untrusted source. Provena keeps the original evidence and the derived memory separate:

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 keeps both statements, so it can explain why Alex's preference changed. Events and evidence are append-only. Claims have review status, optional validity time, and exact tenant and project or branch scope. Model-extracted claims remain candidates; source authority is separate from search relevance and never grants permission to act. memory_explain traces a claim back to its source, review history, conflicts, and recorded retrievals.

Provena is one FastAPI service backed by PostgreSQL and pgvector. MCP and host hooks capture turns and retrieve attributed context; Ollama or an optional hosted model extracts candidate facts and embeddings. The Next.js console lets a human inspect and review them. Architecture details · Decisions

Get started

You need Python 3.11+, pipx, Docker Compose, and one supported agent host. Install the connector and choose your host:

pipx install provena-agent-memoryprovena quickstart codex

Use provena quickstart claude or provena quickstart gemini for those hosts. Quickstart starts the local service, PostgreSQL, Ollama, and the console; creates agent and reviewer credentials; and installs MCP plus automatic capture and retrieval hooks. It prints the console URL. Restart your agent host and review Provena under /hooks and /mcp.

The first run downloads the default models (about 1.26 GB). The local Ollama image is a digest-pinned CPU build. Installing the package alone does not record conversations; running quickstart is the opt-in step.

To check that the API and database are running:

provena status

Connect to an existing service

Ask its operator for an API URL, agent API key, and project or branch scope ID. With the connector installed, run:

export PROVENA_API_URL=https://memory.example.comexport PROVENA_API_KEY=paste-agent-keyexport PROVENA_SCOPE_ID=paste-scope-idprovena connect codex --install

Replace codex with claude or gemini as needed. For another MCP client, use provena connect generic to print its configuration. See the connector guide for manual MCP setup and console access.

Other setup paths

• Manual self-hosting: download the v0.1.15 Compose file and follow the deployment guide for the remaining files, credentials, upgrades, and backups.
• Develop from source: follow the local development guide for Python, Docker, the console, and tests.

Current limits

Retrieval uses an exact scope; branch inheritance is not implemented. Provena records which claims were delivered to an agent, but cannot prove that a later action was caused by them. More on current guarantees and limits.

Contributing

Start with a good first issue or read CONTRIBUTING.md. See SECURITY.md for private vulnerability reporting and CHANGELOG.md for release history.