Provena

Provena

Memória persistente com respaldo em evidências para agentes de IA.
Saiba o que um agente lembra, de onde veio e por que foi recuperado.

O Provena oferece ao Codex, Claude Code, Gemini CLI, agentes personalizados e outros clientes MCP uma camada compartilhada de memória de longo prazo com proveniência explícita. Ele armazena eventos de origem separadamente de afirmações estruturadas, vincula cada afirmação a evidências imutáveis, registra o histórico de revisão e recuperação e mantém a autoridade da origem separada da relevância semântica.

O resultado é um contexto de agente que pode ser inspecionado, questionado, delimitado e explicado, em vez de uma coleção opaca de correspondências vetoriais.

Demonstração do Produto

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

Experimente o Provena →   ·   Veja como funciona   ·   Contribua

Colaboradores Bem-Vindos

O Provena está procurando colaboradores iniciais interessados em Python, TypeScript, MCP, PostgreSQL, segurança de agentes, redação técnica e ferramentas para desenvolvedores.

Comece pela lista de good first issue em aberto. Cada tarefa para iniciantes inclui as habilidades esperadas, o esforço estimado, os arquivos prováveis, os critérios de aceitação e os comandos de verificação. Comente em uma issue antes de começar para que os colaboradores não dupliquem o trabalho.

• Leia CONTRIBUTING.md para configuração local e expectativas de pull requests.
• Leia AGENTS.md antes de alterar o comportamento de proveniência, confiança, escopo ou banco de dados.
• Use GitHub Issues para bugs confirmados e mudanças delimitadas.
• Reporte vulnerabilidades de forma privada pela aba Security do repositório, conforme descrito em SECURITY.md.

Documentação, testes, melhorias de acessibilidade, relatórios de bugs reproduzíveis e mudanças de código focadas são todas contribuições úteis.

O que é o Provena?

O Provena é um serviço de memória e um harness de integração para fluxos de trabalho de desenvolvimento assistidos por IA. Ele fica entre um host de agente e o armazenamento durável por meio de REST, MCP ou hooks de ciclo de vida.

O harness é responsável por:

• capturar turnos selecionados do usuário e do assistente como eventos de origem imutáveis;
• aceitar memórias explícitas e estruturadas de um agente ou aplicação;
• extrair fatos candidatos com um modelo local ou hospedado configurado;
• recuperar afirmações relevantes de uma organização e escopo exatos;
• retornar atribuição de origem, status e autoridade com o contexto recuperado; e
• registrar quais afirmações foram entregues durante cada recuperação.

O Provena não executa o código ou as tarefas de um agente. Seu papel no contexto de execução é tornar a captura de memória e a montagem de contexto rastreáveis. Os registros de recuperação melhoram a reprodutibilidade ao mostrar quais afirmações armazenadas foram fornecidas a um agente, mas o Provena atualmente não reproduz uma execução de modelo nem prova que uma afirmação recuperada influenciou uma ação posterior.

Modelo principal

As afirmações podem ser candidatas, ativas, verificadas, conflitantes, substituídas, em quarentena, expiradas, efêmeras ou excluídas. Mudar o estado nunca apaga a evidência de origem da afirmação.

Por que a Proveniência Importa

A memória do agente pode ser relevante e ainda assim estar errada, desatualizada, especulativa ou maliciosa. Um resultado vetorial sozinho não pode responder quem afirmou um fato, o que a fonte original disse, se um humano o revisou ou qual contexto de execução o recebeu.

O Provena preserva essas distinções:

• Rastreabilidade: memory_explain segue uma afirmação de volta ao seu evento de origem, credencial, execução de extração, relações, histórico de status e recuperações registradas.
• Verificação: credenciais humanas revisam transições de estado; resumos gerados por agentes não podem se promover a fatos de alta autoridade.
• Auditabilidade: eventos, vínculos de evidência, relações e ações de memória são somente de acréscimo.
• Clareza temporal: o tempo registrado e o tempo de validade do fato são armazenados separadamente.
• Consciência de conflitos: afirmações sobrepostas com valores diferentes permanecem visíveis até que um revisor registre uma contradição, mudança temporal ou descarte.
• Isolamento: registros de propriedade do locatário incluem IDs de organização, e a recuperação exige um escopo exato.
• Segurança: o conteúdo lembrado é tratado como dados não confiáveis e nunca concede permissão para executar uma ação.

O PostgreSQL é o sistema de registro autoritativo. Os embeddings pgvector são índices derivados; eles não substituem evidências nem determinam autoridade.

Como o Provena Funciona

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]

Um fluxo típico de escrita e recuperação é:

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

A saída do modelo nunca eleva a autoridade da origem nem ativa uma afirmação. Afirmações candidatas podem ser retornadas como contexto provisório claramente marcado até que um humano as promova, coloque em quarentena ou exclua.

Casos de Uso

• Memória de agente entre sessões: compartilhe fatos de projeto revisados ou restrições do usuário entre Codex, Claude Code, Gemini CLI e clientes personalizados usando a mesma organização e escopo.
• Preferências explicáveis: preserve uma declaração como uma restrição alimentar e mostre o evento exato por trás da preferência estruturada.
• Memória de arquitetura: registre decisões como um banco de dados de produção, runtime ou política de implantação com tempo de validade e evidência de origem.
• Revisão de conflitos: distinga uma contradição de uma migração temporal ou de um fato que pertence a outro ambiente.
• Experimentos de branch: isole fatos de branch de funcionalidade em um escopo de branch para que não entrem silenciosamente na recuperação do escopo do projeto.
• Auditoria de contexto: inspecione as afirmações exatas entregues em uma recuperação de agente sem tratar a navegação do operador como outra recuperação de agente.

Primeiros Passos

Configuração self-hosted mais rápida

Instale o conector publicado com pipx, que gerencia o Provena em seu próprio ambiente e expõe o comando globalmente. Você não precisa criar ou ativar um ambiente virtual. Escolha o host de agente que você usa:

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

Se o pipx não estiver instalado, siga as instruções oficiais de instalação do pipx. Um pip install regular continua suportado quando você já tem um ambiente Python persistente.

Isso prepara a implantação Compose com versão correspondente, preserva um banco de dados existente e o .env, inicia PostgreSQL e modelos locais Ollama, inicializa credenciais separadas de agente e revisor, instala hooks MCP e de ciclo de vida para o host selecionado e inicia o console do operador. O comando imprime a URL do console específica do escopo.

Após essa configuração explícita, prompts comuns e respostas finais são capturados automaticamente e afirmações candidatas ou revisadas relevantes são fornecidas para turnos posteriores. Reinicie o host selecionado e revise o Provena em /hooks e /mcp. pip install sozinho nunca edita a configuração de um agente nem inicia a captura. Veja ADR 0020 e ADR 0021.

Configuração manual de release self-hosted

Os releases publicados fornecem imagens pré-construídas da API e do console. Baixe os três arquivos de implantação do release correspondente no GitHub e crie a configuração 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

Gere valores separados para POSTGRES_PASSWORD e BOOTSTRAP_TOKEN, coloque-os em .env e inicie o modo principal:

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

O modo principal suporta memórias explícitas e revisão sem baixar um modelo. Para habilitar extração automática local e recuperação semântica, adicione o override do Ollama:

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

Salve as credenciais únicas impressas por provena init. Adicione a chave humana e o ID de escopo ao .env antes de iniciar o perfil opcional do console. Veja deploy/README.md para upgrades e backups.

Pré-requisitos

Para desenvolvimento local:

• Python 3.12 ou mais recente
• Node.js 20 ou mais recente e npm
• Docker Engine com Docker Compose, usado para PostgreSQL e Ollama local
• curl

Para a configuração conteinerizada, apenas Docker Engine, Docker Compose e curl são necessários.

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

Opção 1: Executar Localmente

Instale o serviço Python e suas dependências MCP e de teste:

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

Defina um BOOTSTRAP_TOKEN privado em .env, depois inicie PostgreSQL e Ollama e instale os modelos locais padrão:

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 o banco de dados e inicie a 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

A API agora está disponível em http://127.0.0.1:8000; a documentação OpenAPI interativa está em http://127.0.0.1:8000/docs. Verifique a prontidão da API e do banco de dados com:

.venv/bin/provena status

Em um segundo terminal Bash, carregue a mesma configuração e crie uma organização local, escopo de projeto, credencial de agente e credencial humana de revisão:

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

As credenciais de bootstrap são retornadas uma vez e exportadas apenas no shell atual. Inicie o console do operador com a 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.

Opção 2: Executar com 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 o modelo de ambiente e substitua BOOTSTRAP_TOKEN por um valor privado:

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

O primeiro início baixa os modelos de extração e embedding Ollama configurados. Acompanhe o progresso e verifique a 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"

Pressione Ctrl+C depois que os serviços estiverem prontos; os contêineres continuam rodando em segundo plano.

Crie o workspace inicial de dentro do contêiner da API:

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

Depois inicie o perfil do console com a credencial humana emitida e o escopo do projeto:

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

Abra:

• Documentação da API: http://127.0.0.1:8000/docs
• Console do operador: http://127.0.0.1:3000/overview?scope=$PROVENA_SCOPE_ID

Pare o stack sem excluir a memória:

docker compose --profile console stop

PostgreSQL e Ollama usam volumes nomeados. Adicione docker compose --profile console down --volumes apenas quando você quiser intencionalmente destruir o banco de dados local e os modelos baixados.

Conecte um Agente de IA

Para um serviço Provena existente, instale o conector como um comando gerenciado e configure MCP mais captura automática e recuperação usando a credencial de agente e um escopo exato. Substitua codex por claude ou gemini para esse 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 o host selecionado e revise a integração instalada em /hooks e /mcp. Use provena connect <host> sem --install para imprimir a configuração sem alterar o host. Use generic para imprimir o JSON MCP padrão para outro cliente. O comando MCP impresso 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"
  }
}

Depois de adicionar a configuração, verifique a mesma credencial e escopo de forma independente:

~/.venvs/provena/bin/provena doctor

O adaptador MCP expõe:

• memory_context e memory_search para recuperação atribuída;
• memory_record_event e memory_capture_turn para captura de fontes;
• memory_remember e memory_propose_claim para alegações candidatas com respaldo de evidências; e
• memory_explain para histórico de proveniência, revisão, conflito e recuperação.

Chaves de agente podem criar eventos e alegações candidatas. Apenas credenciais humanas podem revisar o status de alegações ou resolver conflitos. Sessões de host fornecem rótulos de proveniência; elas não criam armazenamentos de memória separados. Consulte ADR 0014 para o limite de integração agnóstico de modelo.

Configuração

Configurações de serviço e modelo

Configurações de console, MCP e hooks

Use uma credencial humana para o console local se precisar de ações de revisão e conflito. Use uma credencial de agente para MCP e captura automática. Não forneça a chave de revisão humana a um agente conversacional.

Desenvolvimento

Inicie apenas as dependências de desenvolvimento:

docker compose up -d postgres ollama

Crie e migre o banco de dados descartável de teste de integração e execute a suíte determinística:

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 migrações e a compilação de produção do 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

O comportamento dependente de modelo é isolado atrás da interface de inteligência de memória. Testes determinísticos usam transportes falsos e não exigem chamadas de modelo.

Estrutura do Projeto

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

Leia o guia de arquitetura para garantias e limites atuais. Decisões aceitas estão documentadas em docs/adr/.

Limites Atuais

O Provena atualmente usa recuperação de escopo exato; herança de branch e promoção entre escopos não são implementadas. Ele registra a entrega de alegações, mas não se uma ação de agente foi causada por essa alegação. Armazenamento de artefatos binários, federação de identidade de produção, resolução semântica de duplicatas, resolução temporal automática e um sandbox geral de execução de tarefas estão fora da implementação atual.

Cargas úteis de eventos brutos, alegações, evidências, ações, metadados de extração, incorporações e associação de recuperação são armazenadas no PostgreSQL. Isso mantém a transação de proveniência atômica enquanto o armazenamento mais amplo de artefatos permanece adiado.

Contribuindo

Escolha uma tarefa inicial aberta, comente que você está trabalhando nela e mantenha a solicitação de pull focada nesse problema. Preserve as evidências e os invariantes de limite de locatário, use Alembic para mudanças de esquema, adicione cobertura PostgreSQL real para garantias de banco de dados e registre decisões de arquitetura duráveis em docs/adr/.

Consulte CONTRIBUTING.md para comandos de configuração e verificação, CODE_OF_CONDUCT.md para expectativas da comunidade, SECURITY.md para relato privado de vulnerabilidades e CHANGELOG.md para histórico de versões.