Provena

Evidence-backed persistent memory for AI agents.
Know what an agent remembers, where it came from, and why it was retrieved.

Provena gives Codex, Claude Code, Gemini CLI, custom agents, and other MCP clients a shared long-term memory layer with explicit provenance. It stores source events separately from structured claims, links every claim to immutable evidence, records review and retrieval history, and keeps source authority separate from semantic relevance.

The result is agent context that can be inspected, challenged, scoped, and explained instead of an opaque collection of vector matches.

Product Demo

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

Try Provena →   ·   See how it works   ·   Contribute

Contributors Wanted

Provena is looking for early contributors interested in Python, TypeScript, MCP, PostgreSQL, agent security, technical writing, and developer tooling.

Start with the open good first issue list. Each beginner task includes its expected skills, estimated effort, likely files, acceptance criteria, and verification commands. Comment on an issue before starting so contributors do not duplicate work.

• Read CONTRIBUTING.md for local setup and pull-request expectations.
• Read AGENTS.md before changing provenance, trust, scope, or database behavior.
• Use GitHub Issues for confirmed bugs and scoped changes.
• Report vulnerabilities privately through the repository Security tab as described in SECURITY.md.

Documentation, tests, accessibility improvements, reproducible bug reports, and focused code changes are all useful contributions.

What is Provena?

Provena is a memory service and integration harness for AI-assisted development workflows. It sits between an agent host and durable storage through REST, MCP, or lifecycle hooks.

The harness is responsible for:

• capturing selected user and assistant turns as immutable source events;
• accepting explicit, structured memories from an agent or application;
• extracting candidate facts with a configured local or hosted model;
• retrieving relevant claims from one exact organization and scope;
• returning source attribution, status, and authority with retrieved context; and
• recording which claims were delivered during each retrieval.

Provena does not execute an agent's code or tasks. Its role in the execution context is to make memory capture and context assembly traceable. Retrieval records improve reproducibility by showing which stored claims were supplied to an agent, but Provena does not currently replay a model run or prove that a retrieved claim influenced a later action.

Core model

Claims can be candidates, active, verified, conflicted, superseded, quarantined, expired, ephemeral, or deleted. Changing state never erases the claim's source evidence.

Why Provenance Matters

Agent memory can be relevant and still be wrong, stale, speculative, or malicious. A vector result alone cannot answer who asserted a fact, what the original source said, whether a human reviewed it, or which execution context received it.

Provena preserves those distinctions:

• Traceability: memory_explain follows a claim back to its source event, credential, extraction run, relationships, status history, and recorded retrievals.
• Verification: human credentials review state transitions; agent-generated summaries cannot promote themselves into high-authority facts.
• Auditability: events, evidence links, relationships, and memory actions are append-only.
• Temporal clarity: recorded time and fact-validity time are stored separately.
• Conflict awareness: overlapping claims with different values remain visible until a reviewer records a contradiction, temporal change, or dismissal.
• Isolation: tenant-owned records include organization IDs, and retrieval requires an exact scope.
• Security: remembered content is treated as untrusted data and never grants permission to perform an action.

PostgreSQL is the authoritative system of record. pgvector embeddings are derived indexes; they do not replace evidence or determine authority.

How Provena Works

flowchart LR
    A[Agent, CLI, or host application] --> B[REST, MCP, or lifecycle hook]
    B --> C[Provena capture and retrieval harness]
    C --> D[FastAPI policy and transaction boundary]
    D --> E[(PostgreSQL + pgvector)]
    C --> F[Ollama or OpenAI\noptional extraction and embeddings]
    E --> G[Attributed context or explain response]
    G --> A
    E --> H[Next.js operator console]

A typical write and retrieval flow is:

source turn or explicit memory
  → immutable event
  → candidate claim linked through evidence
  → duplicate and conflict checks
  → optional human review
  → exact-scope semantic retrieval
  → attributed context plus retrieval audit record

Model output never raises source authority or activates a claim. Candidate claims may be returned as clearly marked provisional context until a human promotes, quarantines, or deletes them.

Use Cases

• Cross-session agent memory: share reviewed project facts or user constraints across Codex, Claude Code, Gemini CLI, and custom clients using the same organization and scope.
• Explainable preferences: preserve a statement such as a dietary restriction and show the exact event behind the structured preference.
• Architecture memory: record decisions such as a production database, runtime, or deployment policy with validity time and source evidence.
• Conflict review: distinguish a contradiction from a temporal migration or a fact that belongs to another environment.
• Branch experiments: isolate feature-branch facts in a branch scope so they do not silently enter project-scope retrieval.
• Context auditing: inspect the exact claims delivered in an agent retrieval without treating operator browsing as another agent retrieval.

Getting Started

Fastest self-hosted setup

Install the published connector with pipx, which manages Provena in its own environment and exposes the command globally. You do not need to create or activate a virtual environment. Choose the agent host you use:

pipx install provena-agent-memory
provena quickstart codex
# Or: provena quickstart claude
# Or: provena quickstart gemini

If pipx is not installed, follow the official pipx installation instructions. A regular pip install remains supported when you already have a persistent Python environment.

This prepares the version-matched Compose deployment, preserves an existing database and .env, starts PostgreSQL and local Ollama models, bootstraps separate agent and reviewer credentials, installs MCP and lifecycle hooks for the selected host, and starts the operator console. The command prints the scope-specific console URL.

Quickstart uses a digest-pinned, third-party CPU-only Ollama image. Its Linux/amd64 image download is about 32 MB; the default extraction and embedding models still download about 1.26 GB. This setup does not use GPU acceleration. See ADR 0022 for the image choice and its trust tradeoff.

After this explicit setup, ordinary prompts and final responses are captured automatically and relevant candidate or reviewed claims are supplied to later turns. Restart the selected host and review Provena under /hooks and /mcp. pip install alone never edits an agent's configuration or begins capture. See ADR 0020 and ADR 0021.

Manual self-hosted release setup

Published releases provide prebuilt API and console images. Download the three deployment files from the matching GitHub release, then create local configuration:

mkdir provena && cd provena
curl -LO https://github.com/admiralpunk/Provena/releases/download/v0.1.13/compose.yaml
curl -LO https://github.com/admiralpunk/Provena/releases/download/v0.1.13/compose.ollama.yaml
curl -Lo .env.example https://github.com/admiralpunk/Provena/releases/download/v0.1.13/default.env.example
cp .env.example .env