Provena

Provena

Memoria persistente respaldada por evidencia para agentes de IA.
Sepa qué recuerda un agente, de dónde proviene y por qué se recuperó.

Provena brinda a Codex, Claude Code, Gemini CLI, agentes personalizados y otros clientes MCP una capa de memoria a largo plazo compartida con procedencia explícita. Almacena eventos fuente por separado de las afirmaciones estructuradas, vincula cada afirmación a evidencia inmutable, registra el historial de revisión y recuperación, y mantiene la autoridad de la fuente separada de la relevancia semántica.

El resultado es un contexto de agente que puede inspeccionarse, cuestionarse, delimitarse y explicarse, en lugar de una colección opaca de coincidencias vectoriales.

Demostración del producto

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

Pruebe Provena →   ·   Vea cómo funciona   ·   Contribuya

Se buscan colaboradores

Provena busca colaboradores iniciales interesados en Python, TypeScript, MCP, PostgreSQL, seguridad de agentes, redacción técnica y herramientas para desarrolladores.

Comience con la lista de good first issue abiertos. Cada tarea para principiantes incluye las habilidades esperadas, el esfuerzo estimado, los archivos probables, los criterios de aceptación y los comandos de verificación. Comente en un issue antes de comenzar para que los colaboradores no dupliquen trabajo.

• Lea CONTRIBUTING.md para la configuración local y las expectativas de pull requests.
• Lea AGENTS.md antes de cambiar el comportamiento de procedencia, confianza, alcance o base de datos.
• Use GitHub Issues para errores confirmados y cambios acotados.
• Reporte vulnerabilidades de forma privada a través de la pestaña de Seguridad del repositorio, como se describe en SECURITY.md.

La documentación, las pruebas, las mejoras de accesibilidad, los informes de errores reproducibles y los cambios de código enfocados son contribuciones útiles.

¿Qué es Provena?

Provena es un servicio de memoria y un arnés de integración para flujos de trabajo de desarrollo asistidos por IA. Se sitúa entre un host de agente y el almacenamiento duradero mediante REST, MCP o enlaces de ciclo de vida.

El arnés es responsable de:

• capturar turnos seleccionados de usuario y asistente como eventos fuente inmutables;
• aceptar memorias explícitas y estructuradas de un agente o aplicación;
• extraer hechos candidatos con un modelo local o alojado configurado;
• recuperar afirmaciones relevantes de una organización y alcance exactos;
• devolver atribución de fuente, estado y autoridad con el contexto recuperado; y
• registrar qué afirmaciones se entregaron durante cada recuperación.

Provena no ejecuta el código ni las tareas de un agente. Su papel en el contexto de ejecución es hacer que la captura de memoria y el ensamblaje de contexto sean trazables. Los registros de recuperación mejoran la reproducibilidad al mostrar qué afirmaciones almacenadas se suministraron a un agente, pero Provena actualmente no reproduce una ejecución de modelo ni demuestra que una afirmación recuperada influyó en una acción posterior.

Modelo central

Las afirmaciones pueden ser candidatas, activas, verificadas, en conflicto, reemplazadas, en cuarentena, caducadas, efímeras o eliminadas. Cambiar el estado nunca borra la evidencia fuente de la afirmación.

Por qué importa la procedencia

La memoria de un agente puede ser relevante y aun así estar equivocada, desactualizada, ser especulativa o maliciosa. Un resultado vectorial por sí solo no puede responder quién afirmó un hecho, qué dijo la fuente original, si un humano lo revisó o qué contexto de ejecución lo recibió.

Provena preserva esas distinciones:

• Trazabilidad: memory_explain sigue una afirmación hasta su evento fuente, credencial, ejecución de extracción, relaciones, historial de estado y recuperaciones registradas.
• Verificación: las credenciales humanas revisan las transiciones de estado; los resúmenes generados por agentes no pueden promoverse a hechos de alta autoridad.
• Auditabilidad: los eventos, enlaces de evidencia, relaciones y acciones de memoria son de solo anexión.
• Claridad temporal: el tiempo registrado y el tiempo de validez del hecho se almacenan por separado.
• Conciencia de conflictos: las afirmaciones superpuestas con valores diferentes permanecen visibles hasta que un revisor registra una contradicción, un cambio temporal o un descarte.
• Aislamiento: los registros propiedad del inquilino incluyen ID de organización, y la recuperación requiere un alcance exacto.
• Seguridad: el contenido recordado se trata como datos no confiables y nunca otorga permiso para realizar una acción.

PostgreSQL es el sistema de registro autoritativo. Los embeddings de pgvector son índices derivados; no reemplazan la evidencia ni determinan la autoridad.

Cómo funciona Provena

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]

Un flujo típico de escritura y recuperación es:

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

La salida del modelo nunca eleva la autoridad de la fuente ni activa una afirmación. Las afirmaciones candidatas pueden devolverse como contexto provisional claramente marcado hasta que un humano las promueva, ponga en cuarentena o elimine.

Casos de uso

• Memoria de agente entre sesiones: comparta hechos de proyecto revisados o restricciones de usuario entre Codex, Claude Code, Gemini CLI y clientes personalizados usando la misma organización y alcance.
• Preferencias explicables: preserve una declaración como una restricción dietética y muestre el evento exacto detrás de la preferencia estructurada.
• Memoria de arquitectura: registre decisiones como una base de datos de producción, tiempo de ejecución o política de implementación con tiempo de validez y evidencia fuente.
• Revisión de conflictos: distinga una contradicción de una migración temporal o de un hecho que pertenece a otro entorno.
• Experimentos de rama: aísle hechos de ramas de características en un alcance de rama para que no entren silenciosamente en la recuperación del alcance del proyecto.
• Auditoría de contexto: inspeccione las afirmaciones exactas entregadas en una recuperación de agente sin tratar la navegación del operador como otra recuperación de agente.

Primeros pasos

Configuración autohospedada más rápida

Instale el conector publicado con pipx, que gestiona Provena en su propio entorno y expone el comando globalmente. No necesita crear ni activar un entorno virtual. Elija el host de agente que use:

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

Si pipx no está instalado, siga las instrucciones oficiales de instalación de pipx. Un pip install normal sigue siendo compatible cuando ya tiene un entorno Python persistente.

Esto prepara la implementación de Compose con versiones coincidentes, preserva una base de datos existente y .env, inicia PostgreSQL y los modelos locales de Ollama, arranca credenciales separadas de agente y revisor, instala enlaces MCP y de ciclo de vida para el host seleccionado e inicia la consola de operador. El comando imprime la URL de consola específica del alcance.

Después de esta configuración explícita, los mensajes ordinarios y las respuestas finales se capturan automáticamente y las afirmaciones candidatas o revisadas relevantes se suministran a turnos posteriores. Reinicie el host seleccionado y revise Provena en /hooks y /mcp. pip install solo nunca edita la configuración de un agente ni comienza la captura. Consulte ADR 0020 y ADR 0021.

Configuración manual de lanzamiento autohospedado

Los lanzamientos publicados proporcionan imágenes precompiladas de API y consola. Descargue los tres archivos de implementación del lanzamiento de GitHub correspondiente y luego cree la configuración local:

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

Genere valores separados para POSTGRES_PASSWORD y BOOTSTRAP_TOKEN, colóquelos en .env e inicie el modo central:

python -c 'import secrets; print(secrets.token_urlsafe(32))'
docker compose up -d postgres api
docker compose exec api provena status --api-url http://127.0.0.1:8000
docker compose exec api provena init --format shell

El modo central admite memorias explícitas y revisión sin descargar un modelo. Para habilitar la extracción automática local y la recuperación semántica, agregue la superposición de Ollama:

docker compose -f compose.yaml -f compose.ollama.yaml up -d

Guarde las credenciales de un solo uso impresas por provena init. Agregue la clave humana y el ID de alcance a .env antes de iniciar el perfil de consola opcional. Consulte deploy/README.md para actualizaciones y copias de seguridad.

Requisitos previos

Para desarrollo local:

• Python 3.12 o más reciente
• Node.js 20 o más reciente y npm
• Docker Engine con Docker Compose, usado para PostgreSQL y Ollama local
• curl

Para la configuración contenedorizada, solo se requieren Docker Engine, Docker Compose y curl.

git clone https://github.com/admiralpunk/Provena.git
cd Provena

Opción 1: Ejecutar localmente

Instale el servicio de Python y sus dependencias MCP y de prueba:

python3 -m venv .venv
.venv/bin/pip install -e '.[server,test]'
cp .env.example .env

Establezca un BOOTSTRAP_TOKEN privado en .env, luego inicie PostgreSQL y Ollama e instale los modelos locales predeterminados:

docker compose up -d postgres ollama
docker compose exec ollama ollama pull qwen2.5:1.5b
docker compose exec ollama ollama pull nomic-embed-text

Migre la base de datos e inicie la API:

set -a
source .env
set +a
.venv/bin/alembic upgrade head
.venv/bin/uvicorn provena.api:app --reload --host 127.0.0.1 --port 8000

La API ahora está disponible en http://127.0.0.1:8000; la documentación interactiva de OpenAPI está en http://127.0.0.1:8000/docs. Verifique la preparación de la API y la base de datos con:

.venv/bin/provena status

En una segunda terminal de Bash, cargue la misma configuración y cree una organización local, un alcance de proyecto, una credencial de agente y una credencial de revisión humana:

set -a
source .env
set +a
eval "$(.venv/bin/provena init --format shell)"

Las credenciales de arranque se devuelven una vez y se exportan solo en el shell actual. Inicie la consola de operador con la credencial humana:

cat > frontend/.env.local <<EOF
PROVENA_API_URL=http://127.0.0.1:8000
PROVENA_API_KEY=$PROVENA_HUMAN_KEY
PROVENA_SCOPE_ID=$PROVENA_SCOPE_ID
EOF

cd frontend
npm ci
npm run dev

Abra http://127.0.0.1:3000/overview?scope=$PROVENA_SCOPE_ID.

Opción 2: Ejecutar con Docker

docker compose exec -T postgres pg_dump -U provena -Fc provena > provena-before-volume.dump
docker compose down
docker compose up -d postgres
until docker compose exec -T postgres pg_isready -U provena -d provena; do sleep 1; done
docker compose exec -T postgres pg_restore -U provena --clean --if-exists --no-owner -d provena < provena-before-volume.dump

Copie la plantilla de entorno y reemplace BOOTSTRAP_TOKEN con un valor privado:

cp .env.example .env
docker compose up --build -d

El primer inicio descarga los modelos de extracción y embeddings de Ollama configurados. Siga el progreso y verifique la API:

docker compose logs -f ollama-models api
curl -fsS http://127.0.0.1:8000/openapi.json > /dev/null && echo "Provena API is ready"

Presione Ctrl+C después de que los servicios estén listos; los contenedores continúan ejecutándose en segundo plano.

Cree el espacio de trabajo inicial desde dentro del contenedor de la API:

eval "$(docker compose exec -T api python scripts/bootstrap_workspace.py --format shell)"

Luego inicie el perfil de consola con la credencial humana emitida y el alcance del proyecto:

PROVENA_API_KEY="$PROVENA_HUMAN_KEY" \
PROVENA_SCOPE_ID="$PROVENA_SCOPE_ID" \
docker compose --profile console up --build -d console

Abra:

• Documentación de API: http://127.0.0.1:8000/docs
• Consola de operador: http://127.0.0.1:3000/overview?scope=$PROVENA_SCOPE_ID

Detenga el stack sin eliminar la memoria:

docker compose --profile console stop

PostgreSQL y Ollama usan volúmenes con nombre. Agregue docker compose --profile console down --volumes solo cuando quiera destruir intencionalmente la base de datos local y los modelos descargados.

Conectar un agente de IA

Para un servicio Provena existente, instale el conector como un comando gestionado y configure MCP más la captura automática y la recuperación usando la credencial de agente y un alcance exacto. Reemplace codex con claude o gemini para ese host:

pipx install provena-agent-memory
export PROVENA_API_URL=http://127.0.0.1:8000
export PROVENA_API_KEY=paste-agent-key
export PROVENA_SCOPE_ID=paste-project-or-branch-scope-id
provena connect codex --install

Reinicie el host seleccionado y revise la integración instalada en /hooks y /mcp. Use provena connect <host> sin --install para imprimir la configuración sin cambiar el host. Use generic para imprimir JSON MCP estándar para otro cliente. El comando MCP impreso usa:

{
  "command": "/home/user/.venvs/provena/bin/provena-mcp",
  "env": {
    "PROVENA_API_URL": "http://127.0.0.1:8000",
    "PROVENA_API_KEY": "paste-agent-key",
    "PROVENA_SCOPE_ID": "paste-project-or-branch-scope-id"
  }
}

Después de agregar la configuración, verifique la misma credencial y alcance de forma independiente:

~/.venvs/provena/bin/provena doctor

El adaptador MCP expone:

• memory_context y memory_search para recuperación atribuida;
• memory_record_event y memory_capture_turn para captura de fuentes;
• memory_remember y memory_propose_claim para afirmaciones candidatas respaldadas por evidencia; y
• memory_explain para procedencia, revisión, conflictos e historial de recuperación.

Las claves de agente pueden crear eventos y afirmaciones candidatas. Solo las credenciales humanas pueden revisar el estado de las afirmaciones o resolver conflictos. Las sesiones de host proporcionan etiquetas de procedencia; no crean almacenes de memoria separados. Consulte ADR 0014 para conocer el límite de integración independiente del modelo.

Configuración

Ajustes de servicio y modelo

Ajustes de consola, MCP y hooks

Use una credencial humana para la consola local si necesita acciones de revisión y conflicto. Use una credencial de agente para MCP y captura automática. No le dé a un agente conversacional la clave de revisión humana.

Desarrollo

Inicie solo las dependencias de desarrollo:

docker compose up -d postgres ollama

Cree y migre la base de datos desechable de pruebas de integración, luego ejecute la suite determinista:

docker compose exec -T postgres sh -c 'createdb -U provena provena_test 2>/dev/null || true'
DATABASE_URL=postgresql+psycopg://provena:provena_dev@127.0.0.1:5437/provena_test \
  .venv/bin/alembic upgrade head
TEST_DATABASE_URL=postgresql+psycopg://provena:provena_dev@127.0.0.1:5437/provena_test \
  .venv/bin/pytest -q

Valide las migraciones y la compilación de producción del frontend:

DATABASE_URL=postgresql+psycopg://provena:provena_dev@127.0.0.1:5437/provena_test \
  .venv/bin/alembic check
cd frontend
npm run typecheck
npm run build

El comportamiento dependiente del modelo está aislado detrás de la interfaz de inteligencia de memoria. Las pruebas deterministas usan transportes falsos y no requieren llamadas al modelo.

Estructura del proyecto

src/
  core/           domain enums and state-transition rules
  persistence/    SQLAlchemy mappings and database invariants
  memory/         extraction and embedding providers
  integrations/   MCP, conversation capture, and host lifecycle hooks
  web/            FastAPI routes, policies, schemas, and operator projections
alembic/           versioned PostgreSQL migrations
frontend/          Next.js operator console
scripts/           local setup helpers
deploy/            versioned self-hosted release Compose files
docs/adr/          durable architecture decisions
examples/          deterministic MCP client flow
tests/             domain and real-PostgreSQL integration tests
compose.yaml       local PostgreSQL, Ollama, API, and optional console stack
server.json        official MCP Registry package metadata

Lea la guía de arquitectura para conocer las garantías y límites actuales. Las decisiones aceptadas viven en docs/adr/.

Límites actuales

Provena actualmente usa recuperación de alcance exacto; la herencia de ramas y la promoción entre alcances no están implementadas. Registra la entrega de afirmaciones pero no si una acción de agente fue causada por esa afirmación. El almacenamiento de artefactos binarios, la federación de identidad de producción, la resolución de duplicados semánticos, la resolución temporal automática y un sandbox general de ejecución de tareas están fuera de la implementación actual.

Los payloads de eventos sin procesar, afirmaciones, evidencia, acciones, metadatos de extracción, incrustaciones y membresía de recuperación se almacenan en PostgreSQL. Esto mantiene la transacción de procedencia atómica mientras el almacenamiento de artefactos más amplio permanece diferido.

Contribuciones

Elija una tarea abierta para principiantes, comente que está trabajando en ella y mantenga la solicitud de extracción enfocada en ese problema. Preserve la evidencia y los invariantes de límite de tenant, use Alembic para cambios de esquema, agregue cobertura real de PostgreSQL para garantías de base de datos y registre decisiones de arquitectura duraderas en docs/adr/.

Consulte CONTRIBUTING.md para comandos de configuración y verificación, CODE_OF_CONDUCT.md para expectativas de la comunidad, SECURITY.md para informes de vulnerabilidades privados y CHANGELOG.md para el historial de versiones.