Provena

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

Provena connects Codex, Claude Code, Gemini CLI, and other MCP clients to a shared memory service. Every structured claim retains evidence pointing to its immutable source event, along with scope, authority, review state, validity time, conflicts, and retrieval history.

Install the connector

Install the connector into a Python 3.11 or newer environment:

python -m pip install provena-agent-memory

Get access to a Provena service

Ask your Provena operator

Ask your Provena operator for these three values:

• the Provena API URL;
• an agent API key; and
• the project or branch scope ID the agent may access.

Then continue to Connect your agent below.

Or host the server and local Ollama yourself

You need Docker Engine with Docker Compose and curl. Download the current self-hosted release configuration:

mkdir provena-server
cd provena-server
curl -LO https://github.com/admiralpunk/Provena/releases/latest/download/compose.yaml
curl -LO https://github.com/admiralpunk/Provena/releases/latest/download/compose.ollama.yaml
if [ ! -f .env ]; then
  curl -Lo .env https://github.com/admiralpunk/Provena/releases/latest/download/default.env.example
fi

Replace the placeholder database and bootstrap secrets automatically:

python - <<'PY'
from pathlib import Path
import secrets

path = Path(".env")
text = path.read_text()
text = text.replace("replace-with-a-random-database-password", secrets.token_urlsafe(32))
text = text.replace("replace-with-a-long-random-bootstrap-token", secrets.token_urlsafe(32))
path.write_text(text)
PY

Keep this .env file when updating or redownloading the Compose files. PostgreSQL stores its initialized password in the persistent database volume; replacing .env with a newly generated password does not change the password inside an existing volume.

Start PostgreSQL, Provena, Ollama, and the local extraction and embedding models:

docker compose -f compose.yaml -f compose.ollama.yaml up -d
docker compose -f compose.yaml -f compose.ollama.yaml logs -f ollama-models api

The first start downloads the configured Ollama models. Press Ctrl+C after the model download finishes and the API reports that it is ready; the containers remain running.

Load the local bootstrap token, initialize a workspace, and select the issued agent credential:

set -a
. ./.env
set +a
export PROVENA_API_URL="http://127.0.0.1:8000"
eval "$(provena init --format shell)"
export PROVENA_API_KEY="$PROVENA_AGENT_KEY"

provena init also returns PROVENA_HUMAN_KEY. Keep that reviewer credential and BOOTSTRAP_TOKEN private. Do not place either one in an agent configuration.

Connect your agent

The self-hosted steps already set the required values in your shell. If an operator provided them instead, export them now:

export PROVENA_API_URL="https://memory.example.com"
export PROVENA_API_KEY="paste-agent-key"
export PROVENA_SCOPE_ID="paste-scope-id"

Verify the service, credential, and scope:

provena doctor

The generated client configuration points to the provena-mcp executable installed by pip, so keep that Python environment available to the agent client.

Connect Codex

Run:

provena connect codex

The command prints a complete Codex MCP section containing the absolute path to the connector and the three connection values:

[mcp_servers.provena]
command = "/absolute/path/to/python-environment/bin/provena-mcp"

[mcp_servers.provena.env]
PROVENA_API_URL = "https://memory.example.com"
PROVENA_API_KEY = "agent-api-key"
PROVENA_SCOPE_ID = "project-or-branch-scope-id"

Copy the printed section into ~/.codex/config.toml. If that file already contains [mcp_servers.provena], replace the existing Provena section instead of adding a duplicate. Protect the file because it contains the agent API key:

chmod 600 ~/.codex/config.toml

Restart Codex and verify the connection:

codex mcp list

Inside the Codex terminal UI, enter /mcp and confirm that provena is active. Codex documents both the shared ~/.codex/config.toml file and /mcp in its MCP setup guide.

Record and retrieve a memory with prompts such as:

Using Provena, remember that I am allergic to cheese. Return the event and claim IDs.

Then open a new Codex session and ask:

Using Provena memory, suggest pizza ideas suitable for me.

To inspect provenance, ask Codex to search Provena for the relevant memory and call memory_explain on the returned claim.

Connect another MCP client

Generate the appropriate configuration and add the printed JSON to that client's MCP configuration:

provena connect claude
provena connect gemini
provena connect generic

After adding the configuration, restart the client. Provena exposes MCP tools for attributed retrieval, explicit memory capture, candidate claims, and memory_explain provenance traces.

Open the operator console

The pip package installs the CLI and MCP connector. The browser console runs with the Provena service.

If somebody else operates the service, ask them for the console URL, a human reviewer API key, and the scope ID. Use an agent key in Codex and a human key in the console; review actions require the human credential.

For the self-hosted setup above, provena init has already exported PROVENA_HUMAN_KEY and PROVENA_SCOPE_ID. Save them in the console settings in .env:

python - <<'PY'
from pathlib import Path
import os

path = Path(".env")
lines = []
for line in path.read_text().splitlines():
    if line.startswith("PROVENA_API_KEY="):
        line = f"PROVENA_API_KEY={os.environ['PROVENA_HUMAN_KEY']}"
    elif line.startswith("PROVENA_SCOPE_ID="):
        line = f"PROVENA_SCOPE_ID={os.environ['PROVENA_SCOPE_ID']}"
    lines.append(line)
path.write_text("\n".join(lines) + "\n")
PY

Start the console with the human credential:

PROVENA_API_KEY="$PROVENA_HUMAN_KEY" \
docker compose -f compose.yaml -f compose.ollama.yaml \
  --profile console up -d console

Open the console at:

http://127.0.0.1:3000/overview

The API documentation is available at http://127.0.0.1:8000/docs. Add ?scope=YOUR_SCOPE_ID to the console URL to select a scope explicitly.

Recover from a database password mismatch

If the API log reports password authentication failed for user "provena", preserve the database volume and synchronize its role password with the current .env value:

set -a
. ./.env
set +a

docker compose exec -e NEW_PASSWORD="$POSTGRES_PASSWORD" -T postgres \
  psql -v ON_ERROR_STOP=1 -U provena -d provena <<'SQL'
\getenv role_password NEW_PASSWORD
ALTER ROLE provena WITH PASSWORD :'role_password';
SQL

docker compose -f compose.yaml -f compose.ollama.yaml restart api

This changes only the PostgreSQL login credential. It preserves events, claims, evidence, audit records, and the database volume.

Command roles

The pip package is the agent connector. The self-hosted path runs PostgreSQL, Provena, and Ollama as separate containers. Operators can find security, backup, development, and architecture documentation in the GitHub repository.

Why provenance matters

Retrieved context can be relevant while still being stale, speculative, or malicious. Provena keeps relevance separate from source authority and from permission to act. Events and evidence remain append-only, candidate claims remain reviewable, and memory_explain traces a belief back to the information that produced it.

Provena is licensed under the MIT License.