perseus vault

Perseus Vault

Memória persistente e criptografada para agentes de IA. Um binário Rust, um arquivo, sem nuvem.

Publicado em Official MCP Registry · Glama · mcpservers.org · Docker (GHCR)

Dê aos seus agentes memória que sobrevive à sessão, para que eles parem de redescobrir o que já aprenderam e parem de repetir erros passados. Recuperação híbrida (BM25 + denso + RRF), histórico bi-temporal e AES-256-GCM em repouso são expostos por meio de uma superfície MCP canônica que funciona com qualquer host. O snapshot exato do --no-default-features v2.23.2 publicado na referência da API versionada contém 175 ferramentas canônicas únicas; as contagens são específicas de cada release/perfil e também são registradas no metadata.json publicado.

A alegação LongMemEval verificada no código-fonte é a medição totalmente offline de recall em nível de sessão em benchmark/longmemeval/: na divisão pública _s (500 perguntas, 23.867 sessões), o caminho híbrido confirmado atinge 83,2% recall@1, 98,8% recall@5, 99,8% recall@10 e 0,8949 MRR contra answer_session_ids. É livre de julgamento e usa o binário real com embeddings locais empacotados; é uma métrica de recuperação, não precisão de QA ponta a ponta. O relatório exato, o harness e o comando de reprodução estão documentados nesse diretório.

Perseus Context Engine resolve o presente; Perseus Ledger registra as evidências. O Vault é a camada de memória durável entre eles.

Um binário. Um arquivo. Sem Docker. Sem Postgres. Sem nuvem. Local-first, pronto para air-gap, MIT.

Instalação em uma linha

curl -sSf https://raw.githubusercontent.com/Perseus-Computing-LLC/perseus-vault/main/scripts/install.sh | sh

É isso. O Perseus Vault é instalado em ~/.local/bin/perseus-vault. Inicie-o:

perseus-vault serve --db ~/.perseus-vault/data/perseus-vault.db

A criptografia é ativada automaticamente na instalação padrão. A primeira execução cria ~/.perseus-vault/secret.key com permissões somente do proprietário e um canário de banco de dados criptografado. Faça backup dessa chave: ela não pode ser recuperada. Caminhos explícitos de --encryption-key continuam suportados, e bancos de dados existentes em texto puro são preservados para migração com perseus-vault init --rekey. Use doctor para inspecionar o estado real em disco.

Nota para macOS (Apple Silicon). Um binário recém-compilado ou copiado é morto com SIGKILL na primeira execução (Killed: 9, sem outra saída) pela política binária do SO — mesmo sem atributo de quarentena. O instalador de uma linha e o instalador de compilação a partir do código-fonte bootstrap.sh assinam ad-hoc o Perseus Vault para você. Se você compilar o binário você mesmo, assine-o uma vez após cada recompilação:

cargo build --release
cp target/release/perseus-vault ~/.local/bin/perseus-vault
codesign --force --sign - ~/.local/bin/perseus-vault   # necessário no Apple Silicon; corrige "Killed: 9"

--force re-assina um binário já assinado (necessário após cada recompilação); a etapa é inofensiva no macOS Intel e desnecessária no Linux/Windows.

Em seguida, conecte seu(s) cliente(s) MCP — e o loop completo de recall/captura — em um comando:

perseus-vault install-client --hooks --rules

Isso detecta automaticamente Claude Code / Codex / Cursor (passe --client <name> para claude-desktop, hermes, windsurf, vscode, zed ou genérico; --all-detected conecta todos os clientes detectados), mescla o registro do servidor MCP na configuração do cliente sem sobrescrever nada (um backup .bak-perseus é gravado primeiro), aponta cada cliente para um banco de dados de memória compartilhado, registra os hooks do ciclo de vida da sessão (injeção de recall no SessionStart, higiene no fim da sessão — o contrato docs/lifecycle-hooks.md) e anexa as regras de uso de memória a CLAUDE.md/AGENTS.md. Reexecutar é um no-op; adicione --dry-run para pré-visualizar cada arquivo que seria tocado.

Ou conecte qualquer host MCP manualmente (Claude Desktop, Cursor, Hermes Agent, Perseus, etc.):

{
  "mcpServers": {
    "perseus-vault": {
      "command": "perseus-vault",
      "args": ["serve", "--db", "~/.perseus-vault/data/perseus-vault.db"]
    }
  }
}

Para Agentes: Conecte-se via MCP

Quando o consumidor principal é um agente, a interface é MCP — o agente adota o Vault por meio do seu cliente MCP, e nenhuma instalação CLI por máquina é necessária além de executar o próprio servidor:

# 1. Run the server (one line)
perseus-vault serve --db ~/.perseus-vault/data/perseus-vault.db &

# 2. Register it in the agent's MCP client config
#    { "mcpServers": { "perseus-vault": {
#        "command": "perseus-vault",
#        "args": ["serve", "--db", "~/.perseus-vault/data/perseus-vault.db"] } } }

# 3. Verify the agent-facing surface
perseus-vault doctor

perseus-vault install-client --hooks --rules conecta todo o loop de recall/captura para Claude Code / Codex / Cursor / Hermes em um comando. Para o mapa de capacidades voltado ao agente — qual ferramenta faz qual trabalho, e o padrão de limite de planejamento — veja docs/integration/agent-adoption.md. Para a arquitetura entre camadas e o limite do avaliador, veja o Evaluator Guide.

Início rápido em 30 segundos

# Start Perseus Vault
perseus-vault serve --db memory.db &
sleep 1

# Remember a fact (via MCP JSON-RPC on stdio)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"perseus_vault_remember","arguments":{"category":"demo","key":"hello","body_json":"{\"text\":\"Hello from Perseus Vault!\"}"}}}' | perseus-vault serve --db memory.db

# Search for it
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"perseus_vault_recall","arguments":{"query":"Hello"}}}' | perseus-vault serve --db memory.db

Modelo de memória e limites operacionais

O Perseus Vault mantém três planos distintos:

• Contexto de trabalho implícito é o prompt atual do host, a transcrição e qualquer bloco de contexto que um cliente escolha injetar. É efêmero e de propriedade do host; não é persistido apenas porque o Vault o retornou.
• Memória durável explícita é gravada por uma operação explícita de perseus_vault_remember, perseus_vault_capture, write ou capture. O servidor Vault é dono do registro SQLite, do histórico, do diário, da decadência, do arquivamento e do ciclo de vida de purga.
• Projeções derivadas incluem registros consolidados ou sintetizados e Markdown exportado. Elas carregam proveniência, mas não substituem os registros-fonte duráveis e podem precisar de limpeza separada.

perseus-vault prepare e perseus_vault_context leem registros duráveis para produzir um contexto de trabalho ativo limitado e relevante à tarefa. Isso é um instantâneo contínuo, não uma gravação em segundo plano nem uma promessa de que o cliente o reterá: atualize-o quando a tarefa mudar e não trate texto de prompt como memória durável a menos que uma operação explícita de captura/gravação tenha sucesso. A saída recall-first é orçada (1500 caracteres por padrão, 6000 para hosts com janela grande, ou um max_context_chars explícito); o conjunto always_on é limitado a cinco. Veja retention and context semantics.

Hooks de ciclo de vida e instaladores de cliente são orquestração opcional. Eles solicitam trabalho de recall, captura, manutenção e atualização de propriedade do servidor; eles não se tornam um segundo armazenamento nem alteram a política de retenção. Se o servidor ou um hook estiver indisponível, continue a tarefa sem memória injetada e sinalize o estado degradado. Uma integração de host pode ter um fallback local explicitamente configurado, mas esse fallback deve ser rotulado como somente local e não deve ser apresentado como recall durável do Vault; uma gravação explícita com falha nunca deve ser relatada como persistida. Para etapas de upgrade/recuperação, use o upgrade and migration playbook.

Funciona com Todos os Clientes MCP

O Perseus Vault é um servidor MCP stdio padrão — o mesmo comando perseus-vault serve funciona em qualquer lugar. Execute perseus-vault doctor para validar sua instalação e imprimir esta matriz localmente.

Cliente	Status	Config
Claude Desktop	✅	claude_desktop_config.json
Claude Code / Hermes	✅	.mcp.json / config.yaml
Cursor	✅	.cursor/mcp.json
Windsurf	✅	mcp_config.json
VS Code + Continue.dev	✅	config.json
Zed	✅	settings.json
Codex CLI	✅	~/.codex/config.toml

Trechos de configuração copiáveis para cada um: docs/clients/.

Em seguida, conecte o loop recall → trabalho → captura → consolidação aos eventos de sessão do seu cliente (hooks SessionStart/Stop para Claude Code, Codex e Cursor, além de um fallback portátil AGENTS.md): docs/lifecycle-hooks.md.

Compondo com um lavador de memória (CoalWash) e um compactador de saída em tempo de execução (Noisegate) para controle de orçamento de contexto ponta a ponta: docs/integration/context-budget-stack.md.

Auditando o que o Vault lembra, de onde e sob qual autoridade: docs/evidence-chain-guidance.md — cadeias de evidência, tags de proveniência em tempo de gravação e atestação contínua para memória durável.

Bancos de memória (isolamento por cliente, um perfil)

Agência executando 50 clientes com o mesmo playbook? Não duplique perfis — designe o banco de memória por projeto e mantenha um perfil Hermes, um Vault e uma biblioteca de habilidades compartilhada:

# .hermes.md
memory_bank: acme-seo            # name → deterministic workspace hash
memory_bank_workspace: <64-hex>  # optional explicit workspace override

O provedor de memória Hermes (hermes plugins install Perseus-Computing-LLC/hermes-plugin-perseus-vault) resolve o banco uma vez por sessão e escopa cada leitura e gravação do Vault — pré-busca de recall, perseus_recall / perseus_remember / perseus_forget, captura no fim da sessão — para um workspace dedicado. Os nomes dos bancos mapeiam deterministicamente (sha256("memory-bank:" + name)), então cada instância apontando para o mesmo nome acessa o mesmo workspace sem registro para manter. Workspaces são cidadãos de primeira classe no servidor: manutenção escopada, isolamento de deduplicação entre bancos e manifestos de autoridade por workspace. A descoberta espelha as regras de contexto de projeto do Hermes (o .hermes.md mais próximo vence, limitado à raiz do git); um arquivo de contexto sem diretiva significa sem banco — o workspace configurado permanece em vigor.

Por que Perseus Vault

O Perseus Vault é projetado para ser MCP-nativo, local-first, zero-dependência e agente-first.

Recuperação LongMemEval (offline, sem julgamento)

A medição pública atual é a pista de recuperação reproduzível em benchmark/longmemeval/, não o experimento obsoleto de resposta-e-julgamento por LLM. Ela executa o binário real via MCP stdio e verifica se uma sessão de evidência dourada aparece na janela de classificação solicitada, usando o answer_session_ids do LongMemEval na divisão pública _s.

O relatório confirmado cobre 500 perguntas e 23.867 sessões ingeridas:

caminho	recall@1	recall@3	recall@5	recall@10	MRR
somente palavra-chave (fts5)	4,2%	12,2%	19,2%	33,6%	0,1069
denso	75,8%	88,0%	91,8%	96,0%	0,8296
híbrido (RRF)	83,2%	96,6%	98,8%	99,8%	0,8949

Estas são métricas de recuperação em nível de sessão: offline, sem julgamento e não precisão de QA ponta a ponta. Reproduza o relatório exato verificado no código-fonte com os comandos no README do benchmark; o artefato confirmado é report-currentmain-2026-08-16.json. O obsoleto benchmarks/LONG_MEM_EVAL.md explica por que os números anteriores de modelo/julgamento não são usados como alegações públicas.

LOCOMO (harness próprio do mem0)

Medido no harness LOCOMO do próprio mem0 (nosso fork), não no nosso — categorias 1–4, 1.540q, top-200, gpt-5 como respondedor + julgador:

Engine	Geral	Única	Temporal	Multi	Open-domain
Perseus Vault 2.20.2	87,9%	89,1	92,2	85,1	70,8
Mem0 Platform Starter	82,2%	85,0	82,9	78,0	67,7
Zep Cloud Flex	33,8%	36,9	6,9	50,0	49,0

Cat-5 adversarial (446q): Perseus 63,5, Mem0 55,6, Zep 49,8. Nossa medição do Mem0 está 9,4 pontos abaixo do arquivo publicado por eles (deriva de julgador/plataforma — divulgado). Leaderboard completo →

Viagem no tempo bi-temporal (três eixos)

Nosso diferencial estrutural mais forte — histórico bi-temporal SQL:2011 completo (tempo de transação e tempo de validade) — medido contra um desafio reproduzível e totalmente offline. Ele executa o binário real enviado via MCP stdio pelos casos difíceis que concorrentes de eixo único erram (correções retroativas, fatos proativos com data futura, chegada fora de ordem, divergência crença-vs-verdade, períodos fechados):

Eixo	Pergunta que responde	Verificações	Passa
tempo de validade (valid_at)	"o que era verdade no mundo em T"	10	10
tempo de transação (as_of)	"o que acreditávamos em T"	1	1
bi-temporal (bitemporal)	"conforme a crença em T, o que era verdade em V"	2	2
Total		13	13 (100%)

Reproduza com um único comando (sem chave de API, sem rede, sem LLM):

cargo build --release
python benchmark/temporal/gauntlet.py --bin target/release/perseus-vault

Os veredictos PASS/FAIL são determinísticos (os timestamps de relógio de parede variam, os veredictos não), portanto uma compilação correta é reexecutada para um signature_sha256 idêntico. O gauntlet_report.json confirmado é a referência. Metodologia e conjunto de dados →

Matriz de Comparação

	Perseus Vault	Mem0	Letta	Zep
Implantação	Binário único	Nuvem + auto-hospedado	Docker/Postgres	Docker/Neo4j
Dependências	Nenhuma (SQLite embutido)	Python + banco vetorial	Postgres + Python	Neo4j + Go (Graphiti)
Nativo MCP	✅ Superfície MCP canônica versionada	❌ Não nativo MCP	❌ Não nativo MCP	❌ Não nativo MCP
Offline/Local	✅ Totalmente local	Dependente de nuvem	Requer Docker	Requer Docker
Criptografia	AES-256-GCM ✅	❌	❌	❌
Busca Híbrida	BM25 + Denso + RRF	Somente vetorial	Somente vetorial	Vetorial + Grafo
Ciclo de Vida de Entidades	Decaimento + Promoção + Arquivamento	❌	❌	❌
Grafo de Entidades	Vincular + Percorrer	❌	❌	✅
Trilha de Auditoria (Journal)	✅ Imutável	❌	❌	❌
Gerenciamento de Estado	✅ Chave-valor + TTL	❌	❌	❌
Ferramentas MCP	Versionadas; referência de API pública	5	8	0
Licença	MIT	Apache 2.0	Apache 2.0	Apache 2.0

Comparação completa: Perseus Vault vs Mem0 → vs Letta → vs Zep →

Teste de Estresse: 100 mil entidades

O Perseus Vault lida com cargas de trabalho de teste sustentadas em hardware modesto. Os números abaixo são do artefato confirmado benchmark/scale/report.json: o binário de lançamento real executado via MCP stdio (um processo persistente por tamanho de corpus), AMD64 16 núcleos, Windows 11, cada gravação durável antes do envio da próxima.

Métrica	10 mil	100 mil
Taxa de gravação sustentada (MCP stdio)	479 docs/s	40 docs/s
Recall híbrido p50	19,03 ms	79,73 ms
Recall FTS5 p50	3,14 ms	15,67 ms

Percentis completos, lookups de ponto as_of, recall temporal e números de inicialização a frio estão em benchmark/scale/.

Execute você mesmo: python benchmark/scale/run.py

Precisão de Recall em Escala: Palavras-chave Colapsam, Híbrido Mantém

Velocidade é o mínimo — a pergunta que importa para a memória de agentes é a memória certa realmente aparece? Medido em corpora de conteúdo distinto (de primeira parte, reproduzível; veja benchmark/lambda/), recall@k por modo:

100.000 entidades (1×H100, nomic-embed-text no Ollama):

recall@k	palavra-chave (BM25/FTS5)	denso	híbrido (RRF)
@1	0,003	0,680	0,785
@5	0,015	0,859	1,000
@10	0,029	0,899	1,000

Com 100 mil entidades, o recall híbrido é perfeito @5 enquanto a busca por palavra-chave acerta ~1,5% das vezes — uma lacuna de ~66×. E ela aumenta com a escala: com 10 mil entidades, o recall por palavra-chave @5 era 0,008 enquanto o híbrido já era 1,000; a memória somente por palavra-chave degrada silenciosamente conforme um agente acumula histórico, o híbrido (BM25 + denso + fusão de classificação recíproca) não. Este é o argumento central para a recuperação híbrida do Perseus Vault.

Cara a cara, mesma máquina, mesmo corpus, tudo totalmente local (1×H100, Ollama — mesmo conjunto de fatos, consultas e avaliador de substrings para cada sistema):

Sistema	Precisão de recall	Latência p50	Notas
Perseus Vault (híbrido)	1,00	35,6 ms	binário único autocontido, em processo
Letta (arquivamento / pgvector)	1,00	135,5 ms	servidor + Postgres/pgvector
Mem0 (vetorial)	0,60	37,9 ms	Python + banco vetorial
Zep (KG temporal Graphiti)	0,20	49,7 ms	servidor + Neo4j; grafo extraído por modelo local

Todos os concorrentes foram implantados e executados ao vivo na mesma máquina contra o mesmo Ollama local (qwen2.5:14b-instruct + nomic-embed-text) — sem nuvem, sem números inventados. O Letta foi executado como o servidor letta/letta (Postgres/pgvector incluído) e igualou o Perseus Vault em 1,00. O servidor da Community Edition auto-hospedada do Zep está obsoleto e sua API de memória zep_python agora é exclusiva do Zep Cloud, então medimos o mecanismo OSS real do Zep — KG temporal Graphiti no Neo4j — com extração de entidades/arestas e embeddings no mesmo Ollama local. Seu 0,20 reflete o custo honesto de construir um grafo de conhecimento com um modelo local (extração estruturada é perda: 5 entidades / 2 arestas de 6 fatos) — não o Zep Cloud, que usa modelos de fronteira. Artefato completo + metodologia: benchmark/lambda/results/competitors.json.

Inicialização a frio: uma máquina GPU nua atinge sua primeira resposta RAG fundamentada em 3,3s (modelos preparados em disco).

Reproduza: benchmark/lambda/scale_bench.py e competitors_bench.py.

Implantando ao lado de um servidor de modelo em um host GPU (vLLM em MI300X/H100)? Veja a referência de implantação AMD MI300X — números de co-residência medidos, além das armadilhas de /dev/shm, PID-1 e fixação de versão que quebram essas pilhas na prática.

Integrações com Frameworks

Adaptadores prontos para uso que tornam o Perseus Vault o backend de memória padrão para frameworks populares de agentes de IA:

Framework	Integração	Tipo
LangGraph	PerseusVaultStore	implementação BaseStore
CrewAI	PerseusVaultMemoryTool	Ferramenta de agente
AutoGen	PerseusVaultMemory	implementação Memory

Cada adaptador:

• Conecta via subprocesso MCP stdio (sessão persistente)
• Mapeia a interface de memória do framework para as ferramentas do Perseus Vault
• Inclui um quickstart README (5 minutos para funcionar)
• Tem testes aprovados com transporte MCP simulado

Qualquer framework compatível com MCP funciona diretamente com o Perseus Vault. Veja integrações de cliente MCP e frameworks para a lista completa.

Ferramentas MCP Canônicas Versionadas

A contagem é específica de lançamento/perfil. O snapshot --no-default-features v2.23.2 na referência de API pública publica 175 ferramentas MCP canônicas. O metadata.json da referência registra o commit de origem, o perfil de recursos, as versões do gerador e o digest bruto do snapshot. Novas integrações devem usar o namespace canônico perseus_vault_* e verificar o servidor instalado com perseus-vault doctor ou o snapshot publicado. O material de migração histórico está isolado em docs/migration/legacy-tool-prefixes.md.

Perfis de anúncio de ferramentas

A configuração recomendada para um host de agente LLM é o perfil enxuto explícito:

perseus-vault serve --profile lean --db ~/.perseus-vault/data/perseus-vault.db

--profile lean reduz a resposta tools/list anunciada para a superfície de memória central: perseus_vault_remember, perseus_vault_recall, perseus_vault_forget, perseus_vault_correct, perseus_vault_context, perseus_vault_workspace_status e perseus_vault_health. No modo enxuto, perseus_vault_workspace_status é limitado ao chamador pelo MCP clientInfo.name com carimbo de transporte e não divulga outras associações de perfil/espaço de trabalho. O perfil é uma redução de anúncio, não um limite de autorização; ferramentas canônicas ocultas permanecem disponíveis para solicitações tools/call explicitamente governadas.

default (o padrão) e all são equivalentes e anunciam o registro canônico completo. A configuração existente PERSEUS_VAULT_TOOL_SCOPE pode reduzir ainda mais a visão completa para implantações que usam os níveis antigos de agente/ops; as contagens permanecem específicas de lançamento/perfil e devem ser derivadas do registro verificado.

Escopos de ferramentas (níveis de anúncio, #1051)

Por padrão, tools/list anuncia todas as ferramentas canônicas. Defina PERSEUS_VAULT_TOOL_SCOPE para restringir a superfície anunciada para clientes de agente com restrição de token e atenção:

Configuração	Superfície anunciada	Contagem
full (padrão)	tudo	175
ops	superfície de agente + manutenção operacional, limpeza, governança, exportação	168
agent	superfície de memória cotidiana + coordenação (recall / remember / context / handoffs / state, além das chamadas AAR do lado do agente)	55

Os escopos são somente anúncio: uma ferramenta oculta permanece totalmente chamável via tools/call, e a autorização permanece com associação de espaço de trabalho e manifestos de autoridade. A classificação de nível é uma tabela lateral 1:1 (TOOL_SCOPES em src/mcp.rs), aplicada por CI via scripts/registry_metadata_check.py — toda nova ferramenta deve ser classificada. Ferramentas de nível admin (migrate, purge, erase, vault_import, authority_set / authority_revoke / authority_set_signed) nunca aparecem em uma lista com escopo.

Para implantações multiagente ou HTTP, defina PERSEUS_VAULT_STRICT_SCOPE=1. O modo de escopo estrito exige que toda leitura ou mutação com escopo carregue um MCP clientInfo.name com carimbo de transporte, um workspace_hash não vazio e uma associação de espaço de trabalho exata ativa. Sessões legadas não vinculadas permanecem disponíveis somente quando este portão de implantação está explicitamente desligado; elas não substituem manifestos de autoridade em uma implantação compartilhada.

CRUD de Entidades

Ferramenta	Descrição
perseus_vault_remember	Armazenar/atualizar entidade. Idempotente por (categoria, chave); uma alteração de conteúdo captura a versão anterior no histórico.
perseus_vault_recall	Busca com modos FTS5/denso/híbrido, filtros, expansão de radical. Contrato de consulta (#562): query="" é enumeração de correspondência total (o caminho "listar tudo"); "*" e outros curingas são termos FTS5 literais, não globs — "*" não corresponde a nada.
perseus_vault_scan	Enumeração paginada determinística de uma categoria ou de todo o armazenamento (#562): páginas de keyset id ASC imutáveis com contrato next_cursor/has_more, para que chamadores de exportação/sincronização/redefinição possam percorrer cada entidade exatamente uma vez. Somente leitura — sem efeitos colaterais de contagem de recuperação/decaimento, sem limite de deslocamento.
perseus_vault_hygiene	Relatório de higiene de memória de inicialização somente leitura (#675): pontua memórias ativas por "acionabilidade" (âncoras concretas — chaves de issue, #refs, caminhos, URLs, decisões — vs. vagas/somente data/curtas) e lista os piores infratores com motivos, para curadoria de arquivamento/consolidação.
perseus_vault_recall_layer	Recall de uma camada biomimética específica (mundo, episódica, semântica).
perseus_vault_recall_when	Recall proativo just-in-time: superfície entidades cujos gatilhos recall_when correspondem.
perseus_vault_get_entity	Buscar uma entidade por ID com body_json completo.
perseus_vault_as_of	Viagem no tempo no momento da transação: a versão de um fato (categoria + chave) que era acreditada em um instante passado.
perseus_vault_valid_at	Consulta de tempo válido: a versão que era realmente verdadeira no mundo em um instante, de acordo com o conhecimento atual (SQL:2011 APPLICATION_TIME).
perseus_vault_bitemporal	Consulta bitemporal completa de 2 eixos: "no tempo de transação T, o que acreditávamos ser verdade no tempo válido V" — a célula exata do retângulo.
perseus_vault_history	Listar versões substituídas de um fato (categoria + chave), da mais nova para a mais antiga — paginado (limit padrão 20, mais offset); total relata o tamanho total da trilha (companheiro de perseus_vault_as_of).
perseus_vault_forget	Exclusão suave (arquivado=1).

Busca & RAG

Ferramenta	Descrição
perseus_vault_ask	RAG: recupera contexto, consulta o LLM, retorna resposta fundamentada com fontes.
perseus_vault_embed	Gera vetores densos via modelo integrado, Ollama ou endpoint compatível com OpenAI.
perseus_vault_semantic_search	Atalho de busca semântica apenas com vetores densos — encontra entidades por significado, ranqueadas puramente por similaridade de embedding (sem fallback por palavras-chave).
perseus_vault_context	Bloco markdown pré-formatado para injeção em sessão. Recall-first por padrão: passe query (a tarefa/mensagem atual) e apenas entidades topicamente relevantes são injetadas, limitadas a um orçamento por modelo; o despejo incondicional legado requer mode: "always_inject".
perseus_vault_ingest	Dispara sincronizações de conectores (GitHub, file watcher); conteúdo inalterado é ignorado via replay de contenção (#1050).
perseus_vault_span_audit	Rede de perda de extração (#1048): retém sentenças que o extrator não capturou como spans residuais, verbatim com proveniência.
perseus_vault_report_refusal	Rede de perda de extração (#1048): recusa-como-sinal — reavalia spans contra a consulta, retorna payload de nova tentativa, sinaliza unidades com perda.
perseus_vault_report_success	Rede de perda de extração (#1048): confirma uma nova tentativa — anexa uma chave de consulta provisória para que a consulta repetida idêntica seja atendida na primeira passagem.
perseus_vault_ingest_file	Extrai localmente o texto de um documento (plaintext/markdown sempre; DOCX/PDF com o recurso multimodal) e o armazena como entidade recuperável.
perseus_vault_extract	Extração de conhecimento local, determinística e baseada em regras (fatos / preferências / eventos temporais / episódios) a partir de texto ou entidade armazenada. Somente leitura.
perseus_vault_capture	Captura opcional em sessão (#520): destila um payload de transcrição/insight (texto, markdown ou JSONL) em entidades duráveis (causa-raiz / armadilha / decisão / padrão / aprendizado) no momento em que um problema é resolvido. Destilador local baseado em regras por padrão, llm: true opcional com fallback gracioso; mesclagem de quase-duplicados permanece ATIVADA com um limite por invocação (anti-inundação). Também é um verbo de CLI: perseus-vault capture.
perseus_vault_memories	Interface de arquivo compatível com memory-tool da Anthropic (view/create/str_replace/insert/delete/rename sob /memories), apoiada por entidades do vault.

📖 docs/retrieval-modes.md — uma referência enumerada para cada modo de recuperação (palavras-chave · denso · híbrido · grafo · GraphRAG · recall_when proativo · as_of temporal): mecanismo, quando usar, invocação e exemplos.

Grafo

Ferramenta	Descrição
perseus_vault_link	Cria links de relacionamento tipados entre entidades.
perseus_vault_unlink	Remove links de entidades.
perseus_vault_traverse	Percorre o grafo de links de entidades até profundidade configurável.
perseus_vault_communities	Detecção de comunidades GraphRAG sobre o grafo de links (propagação de rótulos determinística ou "louvain" por modularidade gulosa; Rust puro, offline).
perseus_vault_community_summary	Resumo extrativo (opcionalmente polido por LLM) de uma comunidade, materializado como entidade com links evidence_for para os membros.
perseus_vault_global_recall	Busca global GraphRAG: amplitude sobre resumos de comunidades, depois profundidade nos membros das melhores comunidades — respostas holísticas entre clusters.
perseus_vault_graph_drift	Relatório de deriva somente leitura de grafo/entidades/índices/recibos (#869): arestas não atestadas, pendentes, arquivadas/expiradas e entre workspaces, associações de comunidade obsoletas, deriva de FTS, referências de diário a entidades ausentes.
perseus_vault_graph_attest	Carimba o id da entidade de origem como âncora de evidência em arestas legadas para que se tornem atendíveis pelos braços de recall de grafo (#869); pré-visualização dry-run, registrada em diário.

Diário

Ferramenta	Descrição
perseus_vault_journal	Acrescenta evento estruturado com atribuição de ator.
perseus_vault_check_failure_pattern	Guarda de déjà-vu: verifica uma ação contra falhas registradas anteriormente (diário + entidades de falha/armadilha) antes de tentar novamente. Somente leitura.
perseus_vault_timeline	Consulta o diário por intervalo de tempo com filtros.

Estado

Ferramenta	Descrição
perseus_vault_state_set	Define estado chave-valor com TTL opcional.
perseus_vault_state_get	Obtém valor de estado. Retorna null se expirado.
perseus_vault_state_delete	Exclui entrada de estado.
perseus_vault_state_list	Lista chaves de estado, opcionalmente filtradas por prefixo.

Ciclo de vida

Ferramenta	Descrição
perseus_vault_decay	Recalcula pontuações de decaimento de Ebbinghaus (transações em lote de 1000 entidades).
perseus_vault_prune	Arquivamento em massa por categoria, limite de decaimento ou idade.
perseus_vault_purge	Exclui permanentemente entidades arquivadas + VACUUM. Destrutivo.
perseus_vault_expire	Varredura de ciclo de vida baseada em tempo: entidades além do expires_at do corpo transitam para status='expired' (conteúdo retido, dry-run suportado).
perseus_vault_redact	Redação de conteúdo: limpa o corpo de uma entidade com escopo de workspace para um marcador apenas com hash, exclui histórico + texto FTS, mantém metadados (re-ingestão permitida). Requer workspace_hash explícito.
perseus_vault_erase	Apagamento físico de uma entidade com escopo de workspace em TODAS as camadas derivadas (FTS, histórico, comunidades, links, diário) + supressão permanente de re-ingestão. Requer workspace_hash explícito; dry-run suportado.
perseus_vault_cohere	Passagem autônoma de polimento de coerência — promove, decai, vincula, arquiva.
perseus_vault_autocohere	Polimento atômico completo: coere → decai → compacta em uma única passagem (suporta dry-run).
perseus_vault_compact	Arquiva entidades abaixo do limite de decaimento.
perseus_vault_reindex	Reconstrói o índice de busca FTS5 a partir da tabela de entidades.
perseus_vault_consolidate	Mescla entidades sobrepostas/duplicadas em uma categoria em observações duráveis com rastreio de evidência (imagem espelhada de perseus_vault_conflicts).
perseus_vault_dream	Consolidação LLM em horário de inatividade: reflete sobre clusters de memórias episódicas relacionadas via LLM configurado e grava insights semânticos duráveis, com proveniência vinculada a cada fonte. Idempotente (hash de conjunto de evidências), ciente de contradições, limitado; requer --llm-endpoint.

Qualidade

Ferramenta	Descrição
perseus_vault_score	Atribui pontuação de qualidade (0,0-1,0).
perseus_vault_conflicts	Detecta entidades conflitantes via similaridade de trigramas; resolve=true opcional invalida o lado de menor certeza no histórico (reversível, dry-run por padrão).
perseus_vault_correct	Captura estruturada de correção para aprender com erros.
perseus_vault_supersede	Marca um novo fato como substituto de um antigo (define a entidade antiga como deprecated).
perseus_vault_follow	Registra se uma entidade foi realmente SEGUIDA ou PERDIDA — sinal de eficácia de taxa de seguimento que alimenta tanto a pontuação de decaimento quanto o ranqueamento de recall ponderado por resultado (#681).

Keystones (regras de política)

Ferramenta	Descrição
perseus_vault_keystone_set	Redige um Keystone — uma regra de política obrigatória que sobrevive à compactação de contexto (#683). Com escopo (tenant/frota/agente), ranqueado por peso, encadeado criptograficamente em cada mutação; a redação é controlada por nível de confiança.
perseus_vault_keystone_get	Busca os Keystones mesclados para um escopo, ordenados por peso (maior primeiro) e depois especificidade de escopo — a contraparte determinística de início de sessão do recall. Um renderizador injeta estes antes de todo o outro contexto.
perseus_vault_agent	Registra/atualiza ou consulta um agente no registro multi-agente (#684): identidade + nível de confiança (0-3) + frota. O nível de confiança controla operações sensíveis (ex.: redigir keystones requer nível ≥ 2) e orienta a aplicação de visibilidade no recall.

Transferência de Vault (federação entre pares desabilitada)

Ferramenta	Descrição
perseus_vault_vault_export	Exporta entidades para arquivos .md com frontmatter YAML.
perseus_vault_vault_import	Importa do diretório de vault .md (idempotente).
perseus_vault_share	Compartilha uma entidade (por categoria + chave) em outro workspace, preservando o conteúdo.
perseus_vault_workspace_list	Lista todas as categorias distintas de entidades.

perseus_vault_federate é intencionalmente não anunciado nem executável. A transferência entre pares permanece desabilitada até que autoridade autenticada, custódia com capacidade de reversão, tratamento de conflitos e propagação de tombstone/erasure sejam implementados. Use as ferramentas explícitas vault_export / vault_import para transferências revisadas baseadas em arquivo.

Métricas & Operações

Ferramenta	Descrição
perseus_vault_stats	Estatísticas completas do banco de dados em todas as tabelas.
perseus_vault_health	Verificação de saúde do servidor e do banco de dados.
perseus_vault_bench	Rastreamento de benchmark de desempenho.
perseus_vault_maintenance	Manutenção do banco: deduplicação, detecção de órfãos, VACUUM, reindexação FTS5 (suporta dry-run).
perseus_vault_synthesize	Síntese de sessão LLM — extrai lições de transcrições.
perseus_vault_migrate	Migra banco v0.1.x para o esquema atual.

Ferramentas por tarefa (cola do agente)

Não é uma listagem por categoria — é uma listagem por tarefa. Escolha a linha para o que o agente está tentando fazer:

Tarefa	Ferramentas
Lembrar um fato durável / decisão / correção	remember, capture, journal, correct
Recuperar antes de planejar	recall, recall_batch, recall_when, context, ask
Reconstruir a narrativa de desenvolvimento (trilha de intenção, próximo trabalho)	handoff_pack (com include_intent_trail / include_next_work), delegation_brief, timeline, traverse
Decisões: substituição e autoridade	supersede, history, authority_get, action_receipt_get, keystone_get
Perguntar "no que acreditávamos então?"	as_of, valid_at, bitemporal, history
Corrigir o registro / expor contradições	correct, supersede, conflicts, reject_value
Política que sobrevive à compactação	keystone_get, keystone_set
Operações, confiança e escopo	health, stats, agent, workspace_status, doctor (CLI)

CLI

# Server
perseus-vault serve --db /data/perseus-vault.db
perseus-vault serve --web --port 8767 --encryption-key ~/.perseus-vault/secret.key
perseus-vault serve --llm-endpoint http://localhost:11434/api/generate --llm-model llama3
perseus-vault serve --transport sse --port 8787 --mcp-token my-secret-token

# Maintenance (operate directly on DB, no server needed)
perseus-vault stats          --db /data/perseus-vault.db
perseus-vault forget         --db /data/perseus-vault.db --category decision --key stale-choice --reason "superseded"
perseus-vault prune          --db /data/perseus-vault.db --category junk --min-decay 0.1 --dry-run
perseus-vault purge          --db /data/perseus-vault.db --dry-run
perseus-vault decay          --db /data/perseus-vault.db
perseus-vault reindex        --db /data/perseus-vault.db
perseus-vault vault-export   --db /data/perseus-vault.db --vault-dir ./export/
perseus-vault vault-import   --db /data/perseus-vault.db --vault-dir ./export/
perseus-vault obsidian-sync  ~/obsidian-vault/Perseus Vault/          # one-shot export to an Obsidian vault
perseus-vault obsidian-sync  ~/obsidian-vault/Perseus Vault/ --watch  # continuous sync on every memory change

# Key management
perseus-vault keygen --key-file ~/.perseus-vault/secret.key

# #918: read-only TUI inspector (retrieval telemetry, claim cards, entity
# state, decay, bi-temporal history). Never writes; repairs go through the
# governed MCP tools. Requires the default `tui` feature.
perseus-vault inspect --db /data/perseus-vault.db --key-file ~/.perseus-vault/secret.key

Atualizações ao vivo sem reiniciar a sessão

perseus-vault serve detecta quando seu próprio binário é substituído no disco no meio da sessão (o fluxo normal de cargo build / reinstalação) e se recusa a servir resultados da imagem de processo obsoleta — cada ferramenta responde com um erro explícito e alto em vez de degradar para resultados vazios (#858, #1045). Dois caminhos de recuperação, ambos na mesma conexão stdio (sem reiniciar o cliente):

• Explícito: chame perseus_vault_handoff_restart {"confirm": true} — o processo faz hot-swap para o novo binário e a sessão continua perfeitamente, com o estado da sessão MCP (inicialização + identidade do agente) preservado.
• Automático (opt-in): inicie o servidor com PERSEUS_VAULT_AUTO_HANDOFF=1 e o swap acontece de forma transparente na próxima chamada de ferramenta, que o novo binário responde diretamente.

No macOS/Linux o swap é um verdadeiro exec (mesmo PID, mesmos pipes). O Windows bloqueia um executável em execução, então a substituição no meio da sessão não é possível lá; atualize através de um limite de sessão. Contrato completo e o fluxo de trabalho de desenvolvimento local: docs/specs/live-update-handoff.md.

Edições manuais no banco. Os verbos de manutenção acima e o caminho normal de escrita MCP mantêm o índice FTS5 sincronizado automaticamente. Editar a tabela entities diretamente com sqlite3 (um DELETE/UPDATE manual) ignora essa sincronização e pode deixar linhas de índice órfãs — hits de recall "fantasma" para conteúdo que já não existe. Após qualquer edição SQL direta, execute perseus-vault maintain --db <path> (ou perseus-vault reindex) para reconciliar o índice FTS.

Flags

Flag	Descrição
--db	Caminho do banco de dados SQLite (padrão: ~/.perseus-vault/data/perseus-vault.db)
--profile	Perfil de anúncio MCP: default/all (registro completo) ou lean (superfície de memória principal; recomendado para hosts LLM)
--web	Iniciar painel web
--port	Porta do painel (padrão: 8767)
--web-bind	Endereço de bind do painel (padrão: 127.0.0.1)
--transport	Transporte MCP: stdio (padrão), sse ou http
--mcp-token	Token Bearer para autenticação de transporte SSE/HTTP
--encryption-key	Caminho do arquivo de chave AES-256-GCM
--llm-endpoint	Endpoint da API LLM para perseus_vault_ask e embeddings
--llm-model	Nome do modelo LLM (padrão: llama3)
--llm-api-key	Chave de API para endpoints LLM (OpenAI, Azure, etc.)
--embedding-endpoint	Endpoint de embedding compatível com OpenAI
--connectors-config	Caminho para connectors.yaml

Localização do banco de dados

O caminho canônico do banco de dados é:

~/.perseus-vault/data/perseus-vault.db

Sempre passe --db (ou defina $PERSEUS_VAULT_DB_PATH) em scripts, configurações de host MCP e trabalhos cron/coleta para que cada invocação aponte para o mesmo arquivo. Quando nenhum estiver definido, o Perseus Vault resolve o padrão nesta ordem e usa o primeiro que já existir (para que upgrades e instalações legadas de usuário único sejam detectados em vez de iniciar silenciosamente vazios):

1. ~/.perseus-vault/data/perseus-vault.db — canônico (nome atual)
2. ~/.perseus-vault/data/perseus-vault.db — pré-renomeação
3. ~/.perseus-vault/data/perseus-vault.db — pré-renomeação
4. ~/perseus-vault.db — local de instalação legada de usuário único

Se nenhum existir, ele cria ~/.perseus-vault/data/perseus-vault.db. Se mais de um desses existir e você não passou --db/$PERSEUS_VAULT_DB_PATH, o Perseus Vault imprime um aviso em stderr nomeando o arquivo escolhido e os outros que ignorou, para que um estado ambíguo de múltiplos bancos de dados seja visível em vez de silencioso. Definir --db ou $PERSEUS_VAULT_DB_PATH explicitamente sempre vence e suprime o aviso.

Sua Memória de IA no Obsidian

O Perseus Vault é a memória de longo prazo do seu agente de IA — e também funciona como seu segundo cérebro. Cada entidade que seu agente lembra é exportada para uma nota Markdown simples com frontmatter YAML, para que a memória da sua IA se torne uma base de conhecimento pessoal navegável dentro das ferramentas que você já usa: Obsidian, Logseq ou Notion.

# Export your entire memory to an Obsidian vault as linked Markdown notes
perseus-vault obsidian-sync ~/obsidian-vault/Perseus Vault/

# Keep it live — re-export automatically on every memory change
perseus-vault obsidian-sync ~/obsidian-vault/Perseus Vault/ --watch

Abra o vault no Obsidian e você terá um grafo do conhecimento do seu agente.

Backlinks WikiLink. Quando uma entidade vincula a outra (via perseus_vault_link ou um relacionamento depends_on / implements / references), a nota exportada ganha uma seção ## Links com backlinks [[WikiLink]] que resolvem nativamente na visualização de grafo do Obsidian:

---
id: cli-de8dfb8364b6
category: architecture
key: api
type: insight
decay_score: 0.5000
---

{"content":"axum service"}

## Links

- [[cli-99756b494c7d|database]] (depends_on)

Os links resolvem por id da entidade (as notas são escritas como <id>.md) para que nunca quebrem, e o Obsidian mostra o key legível como rótulo do link. Abra a visualização de grafo e a arquitetura, decisões e insights do seu agente se tornam um mapa de conhecimento clicável.

--watch consulta o resumo de estado determinístico e barato do Perseus Vault em um intervalo e re-exporta apenas quando a memória realmente muda. Ele naturalmente captura cada gravação perseus_vault_remember sem dependência de observador de sistema de arquivos e sem acoplamento ao servidor. Ajuste o intervalo com PERSEUS_VAULT_SYNC_INTERVAL_SECS (padrão: 2s).

Outras ferramentas PKM

Ferramenta	Como
Obsidian	perseus-vault obsidian-sync <vault> — WikiLinks resolvem na visualização de grafo imediatamente.
Logseq	Aponte obsidian-sync para o diretório do grafo do Logseq. O Logseq lê a mesma sintaxe [[WikiLink]] e frontmatter Markdown.
Notion	Execute perseus-vault vault-export e use Import → Markdown & CSV do Notion para importar as notas.

Diferente de ferramentas de "segundo cérebro" somente em nuvem, o Perseus Vault roda 100% local, é escrito em Rust, criptografa em repouso com AES-256-GCM e aplica pontuação de decaimento para que memórias obsoletas desapareçam — sua base de conhecimento permanece sua e atualizada.

Recursos

Busca Semântica (ativada por padrão)

• Embeddings integrados, em processo — um modelo quantizado all-MiniLM-L6-v2 (384-dim) é compilado no binário, então a busca densa/semântica funciona com zero configuração e zero rede: sem Ollama, sem chave de API, sem download de modelo. Este é o build padrão (recurso bundled-embeddings).
• Auto-embed na gravação (#271) — perseus_vault_remember incorpora cada entidade nova (ou com conteúdo alterado) sincronamente conforme é gravada, usando o modelo integrado. A incorporação de entidade única é determinística e armazenada em cache LRU, então é barata e não adiciona tarefas em segundo plano. Falhas de incorporação não são fatais (registradas em stderr); a gravação sempre é bem-sucedida.
• Híbrido é o modo de recall padrão (#271) — perseus_vault_recall(query=...) sem flag mode seleciona automaticamente híbrido (denso + palavra-chave fundidos via RRF) sempre que embeddings existirem, e cai transparentemente para busca por palavra-chave fts5 quando não houver. Sem etapa manual de perseus_vault_embed, sem flags para lembrar.
• perseus_vault_semantic_search(query, limit) — um atalho de ferramenta única para busca puramente densa, baseada em significado (sem fallback de palavra-chave) quando você só quer "encontrar coisas parecidas com isso".
• Incorporador alternativo opcional — para usar Ollama ou qualquer endpoint /v1/embeddings compatível com OpenAI em vez do modelo integrado, defina --llm-endpoint (e --embedding-endpoint / --llm-api-key conforme necessário). Isso é totalmente opcional; o modelo integrado é usado por padrão.
• Crie um binário enxuto sem embeddings integrados via cargo build --no-default-features — o recall então usa busca por palavra-chave por padrão, a menos que um incorporador remoto seja configurado.

Internals da Busca Híbrida

• Busca por palavra-chave FTS5 com fallback LIKE e expansão de stemming Porter
• Busca vetorial densa via similaridade de cosseno em embeddings armazenados
• Fusão de Classificação Recíproca (RRF) — combina resultados de palavra-chave + vetor
• Expansão de consulta — variantes automáticas de stemming para recall mais amplo

Ciclo de Vida da Memória

O Perseus Vault modela a memória usando três camadas biomiméticas, inspiradas nas vias de memória humana:

• Mundo (Núcleo): Fatos globais de decaimento lento sobre o ambiente.
• Episódica (Buffer): Histórico de interação específico da sessão, com decaimento rápido.
• Semântica (Trabalho): Conhecimento geral e conceitos aprendidos, com decaimento médio.

Você pode interagir com essas camadas diretamente usando a ferramenta perseus_vault_recall_layer ou especificando o parâmetro layer em perseus_vault_remember.

• Decaimento de Ebbinghaus — memórias desaparecem naturalmente a menos que sejam recuperadas (atualização no acesso)
• Promoção de camada — buffer → trabalho → núcleo com base na frequência de acesso
• Arquivamento automático — entidades obsoletas são arquivadas; purgue para excluir permanentemente + VACUUM
• Entidades sempre ativas — fixe memórias críticas de identidade para injeção na sessão (limite rígido sob recall-first; prefira gatilhos recall_when)
• Dicas de consulta prospectiva (#919) — 1–3 frases opcionais em linguagem natural por entidade (hints em perseus_vault_remember) indexadas no FTS5 junto com o corpo, preenchendo lacunas de vocabulário entre consultas em linguagem simples e texto armazenado. Desativado por padrão (PERSEUS_VAULT_HINTS_ENABLED=1); rejeitado enquanto desativado. Veja docs/specs/prospective-query-hints.md.

Injeção de Contexto Recall-First

O vault é a camada de consulta — ele recupera os poucos fatos que um turno precisa em vez de entregar ao host um bloco fixo para anexar a cada prompt de sistema. perseus_vault_context e perseus-vault prepare são recall-first por padrão:

• Filtragem por relevância — passe query (a tarefa/mensagem atual) e apenas entidades cujos gatilhos recall_when ou conteúdo indexado correspondam a ela são injetadas. Sem consulta, sem injeção tópica: o bloco é um ponteiro de recuperação compacto, estável em bytes entre gravações não relacionadas no vault (amigável a cache de prefixo).
• Orçamento de recall por modelo — a saída é limitada a um orçamento de caracteres resolvido do modelo do host: perfil padrão/enxuto 1500 caracteres; perfil de janela grande ("opus") 6000 caracteres; max_context_chars substitui ambos.
• Sempre ativo limitado — always_on: true ainda funciona para fatos críticos de identidade, mas o conjunto recall-first tem limite rígido (top 5) e o excesso emite um aviso direcionando você para gatilhos recall_when.
• Opt-in legado — o antigo despejo incondicional de top-N ainda está disponível com mode: "always_inject" (--legacy-context para prepare), sem limite, a menos que você passe um orçamento.

perseus-vault prepare --task "deploying the payments service" --model claude-sonnet-4-6
perseus-vault prepare --task "..." --max-context-chars 800     # explicit budget
perseus-vault prepare --task "..." --legacy-context            # old dump, opt-in

RAG e Embeddings

• perseus_vault_ask — perguntas e respostas em linguagem natural sobre memórias armazenadas via qualquer LLM (Ollama, OpenAI, etc.)
• perseus_vault_embed — gera e armazena vetores densos via Ollama ou /v1/embeddings compatível com OpenAI
• Suporta incorporação de entidade única e por categoria em lote

Criptografia

• Criptografia transparente AES-256-GCM para body_json de entidades
• Ativada por padrão para instalações novas — a chave padrão é gerada automaticamente em ~/.perseus-vault/secret.key na primeira gravação
• Flag --encryption-key para chaves explícitas; perseus-vault keygen para geração de chave personalizada
• Bancos de dados existentes em texto puro falham fechados com um caminho de migração init --rekey (ou PERSEUS_VAULT_ALLOW_PLAINTEXT=1 explícito)
• O índice FTS5 permanece em texto puro para busca

Painel Web

• Servidor HTTP Axum integrado (perseus-vault serve --web --port 8767)
• Painel com tema escuro com busca, tabela de entidades, grafo vis.js, linha do tempo
• Bind padrão: 127.0.0.1 (use --web-bind 0.0.0.0 para expor)
• Conexão SQLite separada em modo WAL para leituras concorrentes

Conectores Externos

• Conector de issues do GitHub — ingere issues/PRs por repositório, ciente de limite de taxa
• Observador de arquivos — escaneia diretórios para arquivos .md/.txt/.json com deduplicação por hash de conteúdo
• Configuração de conector baseada em YAML via --connectors-config

Multi-Transporte

• stdio (padrão) — zero configuração, funciona com qualquer host MCP
• SSE — Server-Sent Events para clientes MCP baseados em HTTP
• HTTP — endpoint MCP estilo REST
• Autenticação com token Bearer — para transportes SSE/HTTP

Integração Perseus

O Perseus Vault é o backend de memória padrão para Perseus:

perseus_vault:
  enabled: true
  transport: "stdio"
  command: ["perseus-vault", "serve", "--db", "~/.perseus-vault/data/perseus-vault.db"]
  timeout_s: 30.0
  merge_strategy: "local_first"
  fallback_to_local: true
  context_categories: ["decision", "architecture", "convention"]
  context_limit: 10

Governo e Compras Federais

O Perseus Vault é construído para implantação governamental desde o início.

Capacidade	Status
Licença	MIT — sem copyleft, sem GPL/AGPL
SBOM	Publicado — elementos mínimos NTIA
Isolado de rede	Totalmente offline — sem telemetria, sem chamadas de API, sem rede por padrão
Criptografia em repouso	AES-256-GCM nos corpos, ativada por padrão para instalações novas
Trilha de auditoria	Diário imutável com cadeia de custódia
Cadeia de suprimentos	Atestação SLSA em andamento

Para compradores federais: Veja docs/federal-buyers.md para informações de compras, status de conformidade e modelos de implantação (isolado de rede, on-premises, ambientes classificados).

A Perseus Computing LLC é uma pequena empresa de propriedade dos EUA. Identificadores de compras atuais e declarações de prontidão publicadas pelo proprietário são mantidos na declaração de capacidade pública. Essas declarações são datadas e escopadas; não constituem certificação CMMC, um ATO ou autorização cATO. NAICS: 541715, 541511, 541512.

Política de Privacidade

O Perseus Vault é um servidor MCP local-first — ele roda inteiramente na sua máquina.

Coleta de Dados

• Sem coleta de dados. O Perseus Vault não coleta, transmite ou envia para casa nenhum dado do usuário, estatísticas de uso ou telemetria.
• Todos os dados permanecem no seu arquivo de banco de dados SQLite local.

Uso e Armazenamento de Dados

• Todas as entidades de memória, entradas de diário e estado são armazenados localmente em um banco de dados SQLite no caminho que você especificar via --db.
• Criptografia opcional AES-256-GCM em repouso está disponível — quando ativada, os corpos das entidades são criptografados antes do armazenamento.
• Nenhum dado é compartilhado com a Perseus Computing LLC ou terceiros.

Compartilhamento com Terceiros

• Nenhum. O Perseus Vault é totalmente isolado de rede por padrão. Sem chamadas de API, sem serviços em nuvem, sem solicitações de rede externa.
• O recurso opcional de embeddings vetoriais densos usa um modelo compilado localmente — nenhuma API de incorporação externa é chamada.

Retenção de Dados

• Você controla a retenção com quatro operações distintas de ciclo de vida (veja docs/specs/data-boundaries-retention-lifecycle.md): exclusão suave (perseus_vault_forget, conteúdo recuperável), expiração (perseus_vault_expire, baseada em tempo status='expired' com conteúdo retido), redação (perseus_vault_redact, conteúdo removido para apenas hash, metadados mantidos) e apagamento físico (perseus_vault_erase, remoção em todas as camadas derivadas com supressão permanente de re-ingestão). perseus_vault_purge recupera espaço de linhas arquivadas.
• Nenhum backup automático fora da máquina é realizado.

Contato

• E-mail: privacy@perseus.observer
• GitHub: Perseus-Computing-LLC/perseus-vault

Verificação de Lançamento

Os binários de lançamento são construídos a partir de commits marcados via GitHub Actions. Cada lançamento inclui:

Artefato	Descrição	Verificação
perseus-vault-<target>.tar.gz	Build completo (embeddings agrupados, glibc)	Checksum SHA-256 no sidecar .sha256
perseus-vault-lite-<target>.tar.gz	Build enxuto (--no-default-features, musl/estático)	Checksum SHA-256 no sidecar .sha256
Atestação de proveniência SLSA	Proveniência de build assinada por Sigstore	gh attestation verify <archive> --repo Perseus-Computing-LLC/perseus-vault

Verificar um binário de lançamento

# 1. Verify SHA-256 checksum
sha256sum -c perseus-vault-lite-x86_64-unknown-linux-musl.tar.gz.sha256

# 2. Verify SLSA build provenance (requires gh CLI + OIDC session)
gh attestation verify perseus-vault-lite-x86_64-unknown-linux-musl.tar.gz \
  --repo Perseus-Computing-LLC/perseus-vault

# 3. Confirm the binary identity
./perseus-vault --version
# Should show both the release version AND the git commit hash, e.g.:
#   perseus-vault 2.23.2 (v2.23.2-0-gabcdef1)

# 4. Confirm the doctor reports the same identity
./perseus-vault doctor --db /tmp/test.db | head -1
#   perseus-vault doctor — v2.23.2 (v2.23.2-0-gabcdef1)

Construir reproduzivelmente a partir do código-fonte

# The exact same binary (bit-for-bit) requires matching:
#   - Rust toolchain version (see rust-toolchain.toml)
#   - Locked dependencies: `cargo build --locked`
#   - Build flags: `--release` for release builds

cargo build --locked --release
./target/release/perseus-vault --version

Licença

MIT — veja LICENSE.