# Provena Agent Memory

Provena Agent Memory maintains cross-session agent context linked directly to raw evidence. Helpful when an assistant needs verifiable memory across work runs.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 8 repo stars
- Author: admiralpunk
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/admiralpunk/Provena
- Updated: 2026-10-19
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/provena-agent-memory

## What it does

The server links each stored memory to the exact interaction where it originated. Instead of keeping isolated notes, it stores the source event, review stage, and tenant scope. The `memory_explain` tool lets developers inspect why a claim exists and whether earlier statements contradicted it.

Under the hood runs a FastAPI backend with PostgreSQL and pgvector, backed by Ollama or hosted inference. A Next.js web dashboard provides an interface to review extracted claims manually. All events and evidence remain strictly append-only.

Running the full stack locally demands Python 3.11+, pipx, and Docker Compose. Initial setup downloads approximately 1.26 GB of model weights for Ollama. Scopes require an exact identifier match, so branch context inheritance does not work yet.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `PROVENA_API_URL`, `PROVENA_API_KEY`, `PROVENA_SCOPE_ID` — keys and tokens: ask the human for the values, never commit them or put them in shared files.
- Works with: PostgreSQL

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env PROVENA_API_URL=<PROVENA_API_URL> --env PROVENA_API_KEY=<PROVENA_API_KEY> --env PROVENA_SCOPE_ID=<PROVENA_SCOPE_ID> --transport stdio provena-agent-memory -- uvx provena-agent-memory
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from provena-agent-memory <command>

### Codex

**Platform CLI**
```bash
codex mcp add provena-agent-memory --env PROVENA_API_URL=<PROVENA_API_URL> --env PROVENA_API_KEY=<PROVENA_API_KEY> --env PROVENA_SCOPE_ID=<PROVENA_SCOPE_ID> -- uvx provena-agent-memory
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from provena-agent-memory <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "provena-agent-memory": {
            "command": "uvx",
            "args": [
                "provena-agent-memory"
            ],
            "env": {
                "PROVENA_API_URL": "<PROVENA_API_URL>",
                "PROVENA_API_KEY": "<PROVENA_API_KEY>",
                "PROVENA_SCOPE_ID": "<PROVENA_SCOPE_ID>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from provena-agent-memory <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "provena-agent-memory": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "provena-agent-memory"
            ],
            "env": {
                "PROVENA_API_URL": "<PROVENA_API_URL>",
                "PROVENA_API_KEY": "<PROVENA_API_KEY>",
                "PROVENA_SCOPE_ID": "<PROVENA_SCOPE_ID>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from provena-agent-memory <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e PROVENA_API_URL=<PROVENA_API_URL> -e PROVENA_API_KEY=<PROVENA_API_KEY> -e PROVENA_SCOPE_ID=<PROVENA_SCOPE_ID> provena-agent-memory uvx provena-agent-memory
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from provena-agent-memory <command>

## When to use it
- trace agent facts back to originating dialogue turns
- review candidate claims through a dedicated web dashboard
- isolate memory records by project or tenant scope
- audit how preferences and assertions evolve over time

## Example prompts
- Run `memory_explain` to show where you learned the deployment targets for this service.
- Check your stored memory records for this scope before updating the architecture.

## Similar
- [Memory Vault](https://affpapa.org/en/nevibecode/mcp/memory-vault.md) — MCP server · ★ 67 repo stars
- [myco-brain](https://affpapa.org/en/nevibecode/mcp/myco-brain.md) — MCP server · ★ 7 repo stars
- [Kagura Memory Cloud](https://affpapa.org/en/nevibecode/mcp/kagura-memory-cloud.md) — MCP server · ★ 14 repo stars
- [memory-industry](https://affpapa.org/en/nevibecode/mcp/memory-industry.md) — MCP server · ★ 30 repo stars
- [RE-call MCP Memory Server](https://affpapa.org/en/nevibecode/mcp/re-call-mcp-memory-server.md) — MCP server · ★ 7 repo stars
- [stash-ai-memory](https://affpapa.org/en/nevibecode/skills/stash-ai-memory.md) — skill · 299 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
