Como gerenciar artefatos de agentes de código com S3 e busca vetorial

Um desenvolvedor expôs o padrão que usa para tirar notas de arquitetura, ADRs e specs geradas por agentes de código do meio do repositório Git, guardando tudo no S3 com busca semântica via S3 Vectors.

Quem trabalha com agentes de código em spec-driven development conhece o problema: brainstorm, ADR, spec, revisão de arquitetura, nota de troubleshooting. Em pouco tempo um projeto pequeno acumula centenas de arquivos .md; um projeto de time, dezenas de milhares.

O desenvolvedor que publica como mlnrt no DEV Community documentou a solução que construiu para esse problema: um servidor MCP chamado Arkeology, que guarda esses artefatos fora do repositório, em S3, com busca semântica via S3 Vectors e embeddings do Bedrock. O código está publicado em github.com/amanoxsolutions/arkeology.

Este guia replica a arquitetura descrita na fonte para quem quer montar o próprio pipeline. Não é a documentação oficial do Arkeology (que você acompanha pelo README do projeto), mas o roteiro de infraestrutura AWS por trás dele: bucket, índice vetorial, acesso ao modelo de embedding e a ponta MCP que conecta tudo ao agente.

O que você vai construir

Um pipeline de três peças que resolve a dor de documentação poluindo o código: um bucket S3 guarda os artefatos markdown; um índice do S3 Vectors guarda um embedding por seção ## de cada artefato (não do documento inteiro); e um servidor MCP expõe ferramentas de escrever, buscar e compartilhar esses artefatos para qualquer agente que fale o protocolo, como Claude Code, Claude Desktop ou VS Code com GitHub Copilot.

O ganho prático, segundo a fonte, é consistência imediata de escrita-leitura: um artefato salvo numa chamada do agente já aparece buscável na chamada seguinte, sem PR, sem revisão de código e sem esperar merge. Artefatos marcados como compartilhados ficam visíveis para agentes de outros times e projetos; os demais ficam isolados no prefixo do próprio time.

Pré-requisitos

• Conta AWS com acesso a S3, Bedrock e S3 Vectors. Confira a disponibilidade regional do S3 Vectors antes de começar, já que nem todo serviço da AWS está disponível em todas as regiões; os comandos abaixo usam us-east-1 como referência.
• Acesso habilitado ao modelo Titan Text Embeddings v2 na página Model access do console do Bedrock.
• Permissões IAM mínimas: s3:PutObject, s3:GetObject, s3:ListBucket restritas ao prefixo do seu projeto; s3vectors:CreateVectorBucket, s3vectors:CreateIndex, s3vectors:PutVectors, s3vectors:QueryVectors; bedrock:InvokeModel para o ARN do Titan Text Embeddings v2.
• AWS CLI v2 configurada com um profile (aws configure sso ou credenciais de longa duração para desenvolvimento local).
• Git e um host MCP compatível: Claude Desktop, Claude Code ou VS Code com extensão de agente que leia mcp.json.

Passo a passo

1. Clone o repositório do projeto:

git clone https://github.com/amanoxsolutions/arkeology.git
cd arkeology

1. Crie o bucket que vai guardar os artefatos markdown:

aws s3 mb s3://seu-time-arkeology-artifacts --region us-east-1

1. Crie o vector bucket e o índice do S3 Vectors. A dimensão do índice precisa bater com a dimensão de saída configurada para o Titan Text Embeddings v2 (consulte a documentação do modelo no Bedrock para confirmar os valores suportados):

aws s3vectors create-vector-bucket \
 --vector-bucket-name seu-time-arkeology-vectors \
 --region us-east-1

aws s3vectors create-index \
 --vector-bucket-name seu-time-arkeology-vectors \
 --index-name artifacts-index \
 --dimension 1024 \
 --distance-metric cosine

1. Configure o servidor MCP apontando para o bucket, o índice e o profile da AWS, seguindo o arquivo de configuração do próprio repositório (o README do Arkeology detalha as variáveis exatas; a ideia geral é informar nome do bucket S3, nome do vector bucket, nome do índice e a região).

1. Suba o servidor localmente e registre-o no host MCP. Em VS Code, por exemplo, isso significa adicionar uma entrada em mcp.json apontando para o comando de start do servidor; em Claude Desktop, a entrada vai em claude_desktop_config.json.

1. Peça ao agente para gravar o primeiro artefato, seguindo o frontmatter do Open Knowledge Format (OKF) que o projeto adota:

---
type: adr
status: accepted
shared: true
tags: [database, architecture]
---

## Contexto
O time de pagamentos avaliou DynamoDB versus RDS para o novo serviço de cobrança.

## Decisão
DynamoDB venceu pela latência de leitura e pelo padrão de acesso por chave.

Cada bloco ## desse artefato vira um embedding separado no índice, o que é o ponto central da arquitetura: a granularidade de busca não é o documento inteiro, é a seção.

Testando

Com o artefato gravado, peça ao agente para buscar algo que só existe naquela seção, por exemplo: "encontre a decisão sobre banco de dados do time de pagamentos". O servidor gera o embedding da pergunta com o mesmo modelo Titan, chama QueryVectors no índice e retorna a seção de Decisão, não o documento inteiro.

Vale testar também o filtro por metadado, pedindo ao agente para restringir a busca por type: adr ou por tag. É aqui que compensa saber do bug documentado pela própria fonte: a API QueryVectors do S3 Vectors só devolve a distância entre vetores se você passar returnDistance: true na chamada. Sem esse parâmetro, uma implementação que assume distância zero por padrão transforma todo resultado num score perfeito de 1.0, e a ordenação da busca quebra silenciosamente, com todos os testes unitários passando.

O metadado do vetor é limitado a 2 KB filtráveis e 40 KB totais por vetor.

Vector metadata is limited to 2 KB filterable and 40 KB total per vector.mlnrt, criador do projeto Arkeology

Esse limite é o motivo pelo qual o Arkeology não guarda referências completas e relacionamentos entre artefatos no metadado vetorial: só os 20 commits mais recentes entram no índice, e a lista completa fica nas anotações do objeto S3, fora do caminho de busca.

Limpando os recursos

Apague o índice e o vector bucket primeiro, depois o bucket de artefatos:

aws s3vectors delete-index \
 --vector-bucket-name seu-time-arkeology-vectors \
 --index-name artifacts-index

aws s3vectors delete-vector-bucket \
 --vector-bucket-name seu-time-arkeology-vectors

aws s3 rm s3://seu-time-arkeology-artifacts --recursive
aws s3 rb s3://seu-time-arkeology-artifacts

Revise também a permissão de acesso ao modelo Titan Text Embeddings v2 no Bedrock se não for mais usar o ambiente, e remova a role ou o profile de IAM criado só para este teste. Fora do Free Tier, armazenamento e consultas no S3 Vectors e cada chamada de embedding no Bedrock são cobrados por uso; a fonte não traz valores, então confira o AWS Pricing Calculator antes de deixar o ambiente rodando sem necessidade.

Próximos passos

Dois cuidados de produção que a fonte descreve valem a pena antes de rodar isso com um time inteiro. Primeiro, a separação por time é imposta pelo servidor MCP, não pelo S3: qualquer pessoa com permissão de leitura no bucket inteiro pode usar o AWS CLI direto e ignorar o MCP, então o isolamento real por prefixo tem que estar na política de IAM, não só na lógica do servidor.

Segundo, isso não vale para o índice vetorial compartilhado: qualquer time com acesso de consulta ao índice lê título, descrição, tags e embeddings de artefatos de outros times, mesmo sem conseguir ler o objeto S3 original. Na prática, isso significa que um índice compartilhado só deve ir para times que já têm confiança mútua, não como atalho de conveniência.

A fonte lista como próximos passos do projeto hospedar o próprio servidor MCP na AWS, reforçar o princípio de menor privilégio para fechar esse desvio pelo CLI, e construir um frontend web para contornar a limitação de hoje: o Arkeology Studio (o navegador visual de artefatos embutido no servidor) só funciona em hosts MCP que suportam MCP Apps, como Claude Desktop, claude.ai e VS Code Copilot; o Claude Code, por exemplo, ainda não suporta.

Para quem já lida com documentação de arquitetura espalhada entre repositórios e quer dar aos próprios agentes de código acesso a ADRs de outros times, o repositório github.com/amanoxsolutions/arkeology é o ponto de partida: o código é aberto e inclui uma skill de migração para importar a documentação de um projeto existente para o formato OKF.

Fonte: DEV Community — #aws