perseus vault

Perseus Vault es un único binario de Rust que otorga a los agentes de IA memoria duradera entre sesiones. Un binario. Un archivo. Sin Docker. Sin Postgres. Sin nube. Solo memoria persistente que funciona con cualquier host MCP.

GitHub

Prueba este MCPPatrocinado

Documentación

Perseus Vault

Memoria persistente y cifrada para agentes de IA. Un binario de Rust, un archivo, sin nube.

Publicado en Registro Oficial de MCP · Glama · mcpservers.org · Docker (GHCR)

Dale a tus agentes memoria que sobreviva a la sesión, para que dejen de re-derivar lo que ya aprendieron y dejen de repetir errores pasados. Recuperación híbrida (BM25 + densa + RRF), historial bi-temporal y AES-256-GCM en reposo se exponen a través de una superficie MCP canónica que funciona con cualquier host. La instantánea exacta v2.23.2 --no-default-features publicada en la referencia de API versionada contiene 175 herramientas canónicas únicas; los recuentos son específicos de la versión/perfil y también se registran en el metadata.json publicado.

La afirmación LongMemEval verificada por código fuente es la medición de recuperación a nivel de sesión totalmente offline en benchmark/longmemeval/: en la división pública _s (500 preguntas, 23,867 sesiones), la ruta híbrida confirmada alcanza 83.2% recall@1, 98.8% recall@5, 99.8% recall@10 y 0.8949 MRR contra answer_session_ids. No requiere juez y usa el binario real con incrustaciones locales incluidas; es una métrica de recuperación, no precisión QA de extremo a extremo. El informe exacto, el arnés y el comando de reproducción están documentados en ese directorio.

Perseus Context Engine resuelve el presente; Perseus Ledger registra la evidencia. Vault es la capa de memoria duradera entre ambos.

Un binario. Un archivo. Sin Docker. Sin Postgres. Sin nube. Local-primero, listo para aire aislado, MIT.

Instalación en una línea

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

Eso es todo. Perseus Vault se instala en ~/.local/bin/perseus-vault. Inícialo:

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

El cifrado se habilita automáticamente para la instalación predeterminada. La primera ejecución crea ~/.perseus-vault/secret.key con permisos solo para el propietario y una base de datos cifrada canaria. Haz una copia de seguridad de esa clave: no se puede recuperar. Las rutas explícitas --encryption-key siguen siendo compatibles, y las bases de datos existentes en texto plano se conservan para migración con perseus-vault init --rekey. Usa doctor para inspeccionar el estado real en disco.

Nota para macOS (Apple Silicon). Un binario recién compilado o copiado es eliminado con SIGKILL en la primera ejecución (Killed: 9, sin otra salida) por la política binaria del sistema operativo — incluso sin atributo de cuarentena. El instalador de una línea y el instalador de compilación desde fuente bootstrap.sh firman ad-hoc el código de Perseus Vault por ti. Si compilas el binario tú mismo, fírmalo una vez después de cada recompilación:
cargo build --release
cp target/release/perseus-vault ~/.local/bin/perseus-vault
codesign --force --sign - ~/.local/bin/perseus-vault   # requerido en Apple Silicon; corrige "Killed: 9"
--force vuelve a firmar un binario ya firmado (necesario después de cada recompilación); el paso es inofensivo en macOS Intel e innecesario en Linux/Windows.

Luego conecta tu(s) cliente(s) MCP — y el bucle completo de recuperación/captura — en un comando:

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

Esto detecta automáticamente Claude Code / Codex / Cursor (pasa --client <name> para claude-desktop, hermes, windsurf, vscode, zed o genérico; --all-detected conecta cada cliente detectado), fusiona el registro del servidor MCP en la configuración del cliente sin sobrescribir nada (se escribe primero una copia de seguridad .bak-perseus), apunta cada cliente a una base de datos de memoria compartida, registra los ganchos del ciclo de vida de la sesión (inyección de recuperación en SessionStart, higiene al final de la sesión — el contrato docs/lifecycle-hooks.md), y agrega las reglas de uso de memoria a CLAUDE.md/AGENTS.md. Volver a ejecutarlo es una operación sin efecto; agrega --dry-run para previsualizar cada archivo que tocaría.

O conecta cualquier 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: Conéctate a través de MCP

Cuando el consumidor principal es un agente, la interfaz es MCP — el agente adopta Vault a través de su cliente MCP, y no se necesita instalación CLI por máquina más allá de ejecutar el propio 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 el bucle de recuperación/captura para Claude Code / Codex / Cursor / Hermes en un comando. Para el mapa de capacidades orientado a agentes — qué herramienta hace qué trabajo, y el patrón de límite de planificación — consulta docs/integration/agent-adoption.md. Para la arquitectura entre niveles y el límite del evaluador, consulta la Guía del Evaluador.

Inicio rápido en 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 memoria y límites operativos

Perseus Vault mantiene tres planos distintos:

Contexto de trabajo implícito es el prompt actual del host, la transcripción y cualquier bloque de contexto que un cliente elija inyectar. Es efímero y propiedad del host; no se persiste simplemente porque Vault lo devolvió.
Memoria duradera explícita se escribe mediante una operación explícita perseus_vault_remember, perseus_vault_capture, write o capture. El servidor Vault posee el registro SQLite, el historial, el diario, la decadencia, el archivo y el ciclo de vida de purga.
Proyecciones derivadas incluyen registros consolidados o sintetizados y Markdown exportado. Llevan procedencia, pero no reemplazan los registros fuente duraderos y pueden necesitar limpieza por separado.

perseus-vault prepare y perseus_vault_context leen registros duraderos para producir un contexto de trabajo activo acotado y relevante a la tarea. Esto es una instantánea móvil, no una escritura en segundo plano ni una promesa de que el cliente la retendrá: actualízala cuando la tarea cambie, y no trates el texto del prompt como memoria duradera a menos que una operación explícita de captura/escritura tenga éxito. La salida de recuperación-primero está presupuestada (1500 caracteres por defecto, 6000 para hosts de ventana grande, o un max_context_chars explícito); el conjunto always_on está limitado a cinco. Consulta semántica de retención y contexto.

Los ganchos de ciclo de vida y los instaladores de cliente son orquestación opcional. Solicitan trabajo de recuperación, captura, mantenimiento y actualización propiedad del servidor; no se convierten en un segundo almacén ni cambian la política de retención. Si el servidor o un gancho no está disponible, continúa la tarea sin memoria inyectada y muestra el estado degradado. Una integración de host puede tener un respaldo local configurado explícitamente, pero ese respaldo debe etiquetarse como solo local y no debe presentarse como recuperación duradera de Vault; una escritura explícita fallida nunca debe informarse como persistida. Para pasos de actualización/recuperación, usa el manual de actualización y migración.

Funciona con Cada Cliente MCP

Perseus Vault es un servidor MCP stdio estándar — el mismo comando perseus-vault serve funciona en todas partes. Ejecuta perseus-vault doctor para validar tu instalación e imprimir esta matriz localmente.

Cliente	Estado	Configuración
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`

Fragmentos de configuración copiar-pegar para cada uno: docs/clients/.

Luego conecta el bucle recuperación → trabajo → captura → consolidación a los eventos de sesión de tu cliente (ganchos SessionStart/Stop para Claude Code, Codex y Cursor, más un respaldo portátil AGENTS.md): docs/lifecycle-hooks.md.

Componer con un lavador de memoria (CoalWash) y un compactador de salida en tiempo de ejecución (Noisegate) para control de presupuesto de contexto de extremo a extremo: docs/integration/context-budget-stack.md.

Auditar lo que Vault recuerda, desde dónde y bajo qué autoridad: docs/evidence-chain-guidance.md — cadenas de evidencia, etiquetas de procedencia en tiempo de escritura y atestación continua para memoria duradera.

Bancos de memoria (aislamiento por cliente, un perfil)

¿Una agencia ejecutando 50 clientes con el mismo manual? No dupliques perfiles — designa el banco de memoria por proyecto y mantén un perfil de Hermes, un Vault y una biblioteca de habilidades compartida:

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

El proveedor de memoria de Hermes (hermes plugins install Perseus-Computing-LLC/hermes-plugin-perseus-vault) resuelve el banco una vez por sesión y limita cada lectura y escritura de Vault — recuperación previa, perseus_recall / perseus_remember / perseus_forget, captura al final de la sesión — a un espacio de trabajo dedicado. Los nombres de banco se asignan determinísticamente (sha256("memory-bank:" + name)), por lo que cada instancia que apunta al mismo nombre aborda el mismo espacio de trabajo sin registro que mantener. Los espacios de trabajo son de primera clase en el servidor: mantenimiento limitado, aislamiento de deduplicación entre bancos y manifiestos de autoridad por espacio de trabajo. El descubrimiento refleja las reglas de contexto de proyecto de Hermes (el .hermes.md más cercano gana, limitado en la raíz de git); un archivo de contexto sin directiva significa sin banco — el espacio de trabajo configurado permanece en efecto.

Por qué Perseus Vault

Perseus Vault está diseñado para ser nativo de MCP, local-primero, sin dependencias y agente-primero.

Recuperación LongMemEval (offline, sin juez)

La medición pública actual es el carril de recuperación reproducible en benchmark/longmemeval/, no el experimento obsoleto de respuesta-y-juez con LLM. Impulsa el binario real a través de MCP stdio y verifica si una sesión de evidencia dorada aparece en la ventana de rango solicitada, usando el answer_session_ids de LongMemEval en la división pública _s.

El informe confirmado cubre 500 preguntas y 23,867 sesiones ingeridas:

ruta	recall@1	recall@3	recall@5	recall@10	MRR
solo palabras clave (`fts5`)	4.2%	12.2%	19.2%	33.6%	0.1069
densa	75.8%	88.0%	91.8%	96.0%	0.8296
híbrida (RRF)	83.2%	96.6%	98.8%	99.8%	0.8949

Estas son métricas de recuperación a nivel de sesión: offline, sin juez y no precisión QA de extremo a extremo. Reproduce el informe exacto verificado por código fuente con los comandos en el README del benchmark; el artefacto confirmado es report-currentmain-2026-08-16.json. El benchmarks/LONG_MEM_EVAL.md obsoleto explica por qué los números anteriores de modelo/juez no se usan como afirmaciones públicas.

LOCOMO (el propio arnés de mem0)

Medido en el arnés LOCOMO de mem0 (nuestro fork), no el nuestro — categorías 1–4, 1,540 preguntas, top-200, respondedor gpt-5 + juez:

Motor	General	Individual	Temporal	Múltiple	Dominio abierto
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

Categoría-5 adversarial (446 preguntas): Perseus 63.5, Mem0 55.6, Zep 49.8. Nuestra medición de Mem0 está 9.4 puntos por debajo de su archivo publicado (deriva de juez/plataforma — divulgada). Tabla de clasificación completa →

Viaje en el tiempo bi-temporal (tres ejes)

Nuestro diferenciador estructural más fuerte — historial bi-temporal SQL:2011 completo (tiempo de transacción y tiempo válido) — medido contra una prueba de obstáculos reproducible y totalmente offline. Impulsa el binario real enviado a través de MCP stdio a través de los casos difíciles que los competidores de un solo eje fallan (correcciones retroactivas, hechos proactivos con fecha futura, llegada fuera de orden, divergencia creencia-vs-verdad, períodos cerrados):

Eje	Pregunta que responde	Comprobaciones	Aprobado
tiempo válido (`valid_at`)	"qué era verdad en el mundo en T"	10	10
tiempo de transacción (`as_of`)	"qué creíamos en T"	1	1
bi-temporal (`bitemporal`)	"según la creencia en T, qué era verdad en V"	2	2
Total		13	13 (100%)

Reproduce con un solo comando (sin clave API, sin red, sin LLM):

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

Los veredictos PASS/FAIL son deterministas (las marcas de tiempo de pared varían, los veredictos no), por lo que una compilación correcta se vuelve a ejecutar con un signature_sha256 idéntico. El gauntlet_report.json confirmado es la referencia. Metodología y conjunto de datos →

Matriz de comparación

	Perseus Vault	Mem0	Letta	Zep
Implementación	Binario único	Nube + autoalojado	Docker/Postgres	Docker/Neo4j
Dependencias	Ninguna (SQLite integrado)	Python + base de datos vectorial	Postgres + Python	Neo4j + Go (Graphiti)
Nativo MCP	✅ Superficie MCP canónica versionada	❌ No nativo MCP	❌ No nativo MCP	❌ No nativo MCP
Sin conexión/Local	✅ Totalmente local	Dependiente de la nube	Docker necesario	Docker necesario
Cifrado	AES-256-GCM ✅	❌	❌	❌
Búsqueda híbrida	BM25 + Denso + RRF	Solo vectorial	Solo vectorial	Vectorial + Grafo
Ciclo de vida de entidades	Decaimiento + Promoción + Archivo	❌	❌	❌
Grafo de entidades	Enlace + Recorrido	❌	❌	✅
Registro de auditoría	✅ Inmutable	❌	❌	❌
Gestión de estado	✅ Clave-valor + TTL	❌	❌	❌
Herramientas MCP	Versionadas; referencia de API pública	5	8	0
Licencia	MIT	Apache 2.0	Apache 2.0	Apache 2.0

Comparación completa: Perseus Vault vs Mem0 → vs Letta → vs Zep →

Prueba de esfuerzo: 100K entidades

Perseus Vault maneja cargas de trabajo de prueba sostenidas en hardware modesto. Los números a continuación provienen del artefacto confirmado benchmark/scale/report.json: el binario de lanzamiento real ejecutado a través de MCP stdio (un proceso persistente por tamaño de corpus), AMD64 de 16 núcleos, Windows 11, cada escritura duradera antes de que se envíe la siguiente.

Métrica	10K	100K
Rendimiento de escritura, sostenido (MCP stdio)	479 docs/s	40 docs/s
Recuperación híbrida p50	19.03 ms	79.73 ms
Recuperación FTS5 p50	3.14 ms	15.67 ms

Percentiles completos, búsquedas puntuales as_of, recuperación temporal y números de arranque en frío están en benchmark/scale/.

Pruébelo usted mismo: python benchmark/scale/run.py

Precisión de recuperación a escala: las palabras clave colapsan, el híbrido se mantiene

La velocidad es lo básico: la pregunta que importa para la memoria del agente es ¿la memoria correcta realmente sale a la superficie? Medido en corpus de contenido distinto (de primera parte, reproducible; consulte benchmark/lambda/), recall@k por modo:

100,000 entidades (1×H100, nomic-embed-text en Ollama):

recall@k	palabra clave (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

Con 100K entidades, la recuperación híbrida es perfecta @5 mientras que la búsqueda por palabras clave acierta ~1.5% de las veces — una brecha de ~66×. Y se amplía con la escala: con 10K entidades, el recall de palabras clave @5 fue 0.008 mientras que el híbrido ya era 1.000; la memoria solo por palabras clave se degrada silenciosamente a medida que un agente acumula historial, el híbrido (BM25 + denso + fusión de rango recíproco) no. Este es el argumento central para la recuperación híbrida de Perseus Vault.

Cara a cara, misma máquina, mismo corpus, todo totalmente local (1×H100, Ollama — conjunto de hechos, consultas y juez de subcadenas idénticos para cada sistema):

Sistema	Precisión de recuperación	Latencia p50	Notas
Perseus Vault (híbrido)	1.00	35.6 ms	binario único autocontenido, en proceso
Letta (archivo / pgvector)	1.00	135.5 ms	servidor + Postgres/pgvector
Mem0 (vectorial)	0.60	37.9 ms	Python + base de datos vectorial
Zep (KG temporal Graphiti)	0.20	49.7 ms	servidor + Neo4j; grafo extraído por modelo local

Cada competidor fue levantado y ejecutado en vivo en la misma máquina contra el mismo Ollama local (qwen2.5:14b-instruct + nomic-embed-text) — sin nube, sin números inventados. Letta se ejecutó como el servidor letta/letta (Postgres/pgvector incluido) y coincidió con Perseus Vault en 1.00. El servidor de la Edición Comunitaria autoalojada de Zep está obsoleto y su API de memoria zep_python ahora es solo de Zep Cloud, por lo que medimos el motor OSS real de Zep — KG temporal Graphiti en Neo4j — con extracción de entidades/bordes y incrustaciones en el mismo Ollama local. Su 0.20 refleja el costo honesto de construir un grafo de conocimiento con un modelo local (la extracción estructurada es pérdida: 5 entidades / 2 bordes de 6 hechos) — no Zep Cloud, que usa modelos de frontera. Artefacto completo + metodología: benchmark/lambda/results/competitors.json.

Arranque en frío: una máquina GPU desnuda alcanza su primera respuesta RAG fundamentada en 3.3s (modelos preparados en disco).

Reproducir: benchmark/lambda/scale_bench.py y competitors_bench.py.

¿Implementando junto a un servidor de modelos en un host GPU (vLLM en MI300X/H100)? Consulte la referencia de implementación AMD MI300X — números de co-residencia medidos más los problemas de /dev/shm, PID-1 y fijación de versiones que rompen estas pilas en la práctica.

Integraciones de frameworks

Adaptadores listos para usar que convierten a Perseus Vault en el backend de memoria predeterminado para frameworks populares de agentes de IA:

Framework	Integración	Tipo
LangGraph	`PerseusVaultStore`	implementación `BaseStore`
CrewAI	`PerseusVaultMemoryTool`	Herramienta de agente
AutoGen	`PerseusVaultMemory`	implementación `Memory`

Cada adaptador:

Se conecta mediante subproceso MCP stdio (sesión persistente)
Mapea la interfaz de memoria del framework a las herramientas de Perseus Vault
Incluye un inicio rápido README (5 minutos para funcionar)
Tiene pruebas que pasan con transporte MCP simulado

Cualquier framework compatible con MCP funciona directamente con Perseus Vault. Consulte Integraciones de clientes MCP y frameworks para la lista completa.

Herramientas MCP canónicas versionadas

El recuento es específico de la versión/perfil. La instantánea --no-default-features v2.23.2 en la referencia de API pública publica 175 herramientas MCP canónicas. El metadata.json de la referencia registra el commit fuente, el perfil de características, las versiones del generador y el resumen de la instantánea sin procesar. Las nuevas integraciones deben usar el espacio de nombres canónico perseus_vault_* y verificar el servidor instalado con perseus-vault doctor o la instantánea publicada. El material de migración histórico está aislado en docs/migration/legacy-tool-prefixes.md.

Perfiles de anuncio de herramientas

La configuración recomendada para un host de agente LLM es el perfil explícito reducido:

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

--profile lean reduce la respuesta tools/list anunciada a la superficie de memoria central: perseus_vault_remember, perseus_vault_recall, perseus_vault_forget, perseus_vault_correct, perseus_vault_context, perseus_vault_workspace_status y perseus_vault_health. En modo reducido, perseus_vault_workspace_status está limitado al llamador según el clientInfo.name MCP con sello de transporte y no revela otros enlaces de perfil/espacio de trabajo. El perfil es una reducción de anuncio, no un límite de autorización; las herramientas canónicas ocultas permanecen disponibles para solicitudes tools/call explícitamente gobernadas.

default (el predeterminado) y all son equivalentes y anuncian el registro canónico completo. La configuración existente PERSEUS_VAULT_TOOL_SCOPE puede reducir aún más la vista completa para implementaciones que usan los niveles antiguos de agente/ops; los recuentos siguen siendo específicos de la versión/perfil y deben derivarse del registro verificado.

Ámbitos de herramientas (niveles de anuncio, #1051)

Por defecto, tools/list anuncia cada herramienta canónica. Establezca PERSEUS_VAULT_TOOL_SCOPE para reducir la superficie anunciada para clientes de agentes con restricciones de tokens y atención:

Configuración	Superficie anunciada	Recuento
`full` (predeterminado)	todo	175
`ops`	superficie de agente + mantenimiento operativo, limpieza, gobernanza, exportación	168
`agent`	memoria cotidiana + superficie de coordinación (recall / remember / context / handoffs / state, más las llamadas AAR del lado del agente)	55

Los ámbitos son solo de anuncio: una herramienta oculta sigue siendo totalmente invocable mediante tools/call, y la autorización permanece con el enlace de espacio de trabajo y los manifiestos de autoridad. La clasificación de niveles es una tabla lateral 1:1 (TOOL_SCOPES en src/mcp.rs), aplicada por CI mediante scripts/registry_metadata_check.py — cada nueva herramienta debe clasificarse. Las herramientas de nivel admin (migrate, purge, erase, vault_import, authority_set / authority_revoke / authority_set_signed) nunca aparecen en una lista con ámbito.

Para implementaciones multiagente o HTTP, establezca PERSEUS_VAULT_STRICT_SCOPE=1. El modo de ámbito estricto requiere que cada lectura o mutación con ámbito lleve un clientInfo.name MCP con sello de transporte, un workspace_hash no vacío y un enlace de espacio de trabajo exacto activo. Las sesiones heredadas sin enlace permanecen disponibles solo cuando esta puerta de implementación está explícitamente desactivada; no son un sustituto de los manifiestos de autoridad en una implementación compartida.

CRUD de entidades

Herramienta	Descripción
`perseus_vault_remember`	Almacenar/actualizar entidad. Idempotente por (categoría, clave); un cambio de contenido captura la versión anterior en el historial.
`perseus_vault_recall`	Búsqueda con modos FTS5/denso/híbrido, filtros, expansión de derivación. Contrato de consulta (#562): `query=""` es enumeración de coincidencia total (la ruta "listar todo"); `""` y otros comodines son términos FTS5 literales, no globs — `""` no coincide con nada.
`perseus_vault_scan`	Enumeración paginada determinista de una categoría o de todo el almacén (#562): páginas de conjunto de claves `id ASC` inmutables con un contrato `next_cursor`/`has_more`, para que los llamadores de exportación/sincronización/restablecimiento puedan recorrer cada entidad exactamente una vez. Solo lectura — sin efectos secundarios de recuento de recuperación/decaimiento, sin límite de desplazamiento.
`perseus_vault_hygiene`	Informe de higiene de memoria de arranque de solo lectura (#675): puntúa las memorias activas por "capacidad de acción" (anclas concretas — claves de problema, #refs, rutas, URLs, decisiones — vs vagas/solo fecha/cortas) y lista los peores infractores con razones, para curación de archivo/consolidación.
`perseus_vault_recall_layer`	Recuperación de una capa biomimética específica (mundo, episódica, semántica).
`perseus_vault_recall_when`	Recuperación proactiva justo a tiempo: superficie de entidades cuyos disparadores `recall_when` coinciden.
`perseus_vault_get_entity`	Obtener una entidad por ID con `body_json` completo.
`perseus_vault_as_of`	Viaje en el tiempo en tiempo de transacción: la versión de un hecho (categoría + clave) que se creía en un instante pasado.
`perseus_vault_valid_at`	Búsqueda de tiempo válido: la versión que realmente era verdadera en el mundo en un instante, según el conocimiento actual (SQL:2011 APPLICATION_TIME).
`perseus_vault_bitemporal`	Consulta bitemporal completa de 2 ejes: "al tiempo de transacción T, ¿qué creíamos que era verdadero al tiempo válido V?" — la celda rectangular exacta.
`perseus_vault_history`	Listar versiones superadas de un hecho (categoría + clave), más recientes primero — paginado (`limit` predeterminado 20, más `offset`); `total` informa el tamaño completo del rastro (compañero de `perseus_vault_as_of`).
`perseus_vault_forget`	Eliminación suave (archivado=1).

Búsqueda y RAG

Herramienta	Descripción
`perseus_vault_ask`	RAG: recupera contexto, consulta el LLM y devuelve una respuesta fundamentada con fuentes.
`perseus_vault_embed`	Genera vectores densos mediante el modelo incluido, Ollama o un endpoint compatible con OpenAI.
`perseus_vault_semantic_search`	Atajo de búsqueda semántica solo densa: encuentra entidades por significado, clasificadas puramente por similitud de incrustaciones (sin respaldo de palabras clave).
`perseus_vault_context`	Bloque de markdown preformateado para inyección en sesión. Recuperación primero por defecto: pasa `query` (la tarea/mensaje actual) y solo se inyectan entidades temáticamente relevantes, limitadas a un presupuesto por modelo; el volcado incondicional heredado requiere `mode: "always_inject"`.
`perseus_vault_ingest`	Activa sincronizaciones de conectores (GitHub, observador de archivos); el contenido sin cambios se omite mediante reproducción de contención (#1050).
`perseus_vault_span_audit`	Red de pérdida de extracción (#1048): retiene oraciones que el extractor omitió como tramos residuales, textualmente con procedencia.
`perseus_vault_report_refusal`	Red de pérdida de extracción (#1048): rechazo como señal: vuelve a puntuar tramos frente a la consulta, devuelve un payload de reintento y marca unidades con pérdida.
`perseus_vault_report_success`	Red de pérdida de extracción (#1048): confirma un reintento: adjunta una clave de consulta provisional para que la consulta repetida idéntica se sirva en primera pasada.
`perseus_vault_ingest_file`	Extrae localmente el texto de un documento (texto plano/markdown siempre; DOCX/PDF con la función `multimodal`) y lo almacena como entidad recuperable.
`perseus_vault_extract`	Extracción de conocimiento local, determinista y basada en reglas (hechos / preferencias / eventos temporales / episodios) a partir de texto o una entidad almacenada. Solo lectura.
`perseus_vault_capture`	Captura opcional en sesión (#520): destila un payload de transcripción/percepción (texto, markdown o JSONL) en entidades duraderas (causa raíz / trampa / decisión / patrón / conclusión) en el momento en que se resuelve un problema. Destilador local basado en reglas por defecto, `llm: true` opcional con respaldo elegante; la fusión de casi duplicados permanece ACTIVADA más un límite por invocación (anti-inundación). También un verbo CLI: `perseus-vault capture`.
`perseus_vault_memories`	Interfaz de archivos compatible con la herramienta de memoria de Anthropic (`view`/`create`/`str_replace`/`insert`/`delete`/`rename` bajo `/memories`), respaldada por entidades de la bóveda.

📖 docs/retrieval-modes.md — una referencia enumerada para cada modo de recuperación (palabras clave · denso · híbrido · grafo · GraphRAG · recall_when proactivo · as_of temporal): mecanismo, cuándo usar, invocación y ejemplos.

Grafo

Herramienta	Descripción
`perseus_vault_link`	Crea enlaces de relaciones tipadas entre entidades.
`perseus_vault_unlink`	Elimina enlaces de entidades.
`perseus_vault_traverse`	Recorre el grafo de enlaces de entidades hasta una profundidad configurable.
`perseus_vault_communities`	Detección de comunidades GraphRAG sobre el grafo de enlaces (propagación de etiquetas determinista o "louvain" de modularidad codiciosa; Rust puro, sin conexión).
`perseus_vault_community_summary`	Resumen extractivo (opcionalmente pulido por LLM) de una comunidad, materializado como entidad con enlaces `evidence_for` a los miembros.
`perseus_vault_global_recall`	Búsqueda global GraphRAG: amplitud sobre resúmenes de comunidades, luego profundidad en los miembros de las mejores comunidades: respuestas holísticas entre clústeres.
`perseus_vault_graph_drift`	Informe de deriva de solo lectura de grafo/entidades/índices/recibos (#869): bordes no atestiguados, colgantes, archivados/expirados-objetivo y entre espacios de trabajo, membresías de comunidades obsoletas, deriva FTS, referencias de diario a entidades faltantes.
`perseus_vault_graph_attest`	Sella el id de entidad del lado desde como ancla de evidencia en bordes heredados para que sean servibles por los brazos de recuperación de grafo (#869); vista previa de ejecución en seco, registrada en diario.

Diario

Herramienta	Descripción
`perseus_vault_journal`	Agrega evento estructurado con atribución de actor.
`perseus_vault_check_failure_pattern`	Guardia de déjà-vu: verifica una acción contra fallos previamente registrados (diario + entidades de fallo/trampa) antes de reintentarla. Solo lectura.
`perseus_vault_timeline`	Consulta el diario por rango de tiempo con filtros.

Estado

Herramienta	Descripción
`perseus_vault_state_set`	Establece estado clave-valor con TTL opcional.
`perseus_vault_state_get`	Obtiene el valor de estado. Devuelve null si expiró.
`perseus_vault_state_delete`	Elimina entrada de estado.
`perseus_vault_state_list`	Lista claves de estado, opcionalmente filtradas por prefijo.

Ciclo de vida

Herramienta	Descripción
`perseus_vault_decay`	Recalcula puntuaciones de decaimiento de Ebbinghaus (transacciones por lotes de 1000 entidades).
`perseus_vault_prune`	Archivo masivo por categoría, umbral de decaimiento o antigüedad.
`perseus_vault_purge`	Elimina permanentemente entidades archivadas + VACUUM. Destructivo.
`perseus_vault_expire`	Barrido de ciclo de vida basado en tiempo: entidades más allá de su `expires_at` de cuerpo transicionan a `status='expired'` (contenido retenido, ejecución en seco compatible).
`perseus_vault_redact`	Redacción de contenido: limpia el cuerpo de una entidad con ámbito de espacio de trabajo a un marcador solo hash, elimina historial + texto FTS, conserva metadatos (re-ingesta permitida). Requiere `workspace_hash` explícito.
`perseus_vault_erase`	Borrado físico de una entidad con ámbito de espacio de trabajo en TODAS las capas derivadas (FTS, historial, comunidades, enlaces, diario) + supresión permanente de re-ingesta. Requiere `workspace_hash` explícito; ejecución en seco compatible.
`perseus_vault_cohere`	Pasada autónoma de pulido de coherencia: promueve, decae, enlaza, archiva.
`perseus_vault_autocohere`	Pulido atómico completo: coherencia → decaimiento → compactación en una pasada (compatible con ejecución en seco).
`perseus_vault_compact`	Archiva entidades por debajo del umbral de decaimiento.
`perseus_vault_reindex`	Reconstruye el índice de búsqueda FTS5 desde la tabla de entidades.
`perseus_vault_consolidate`	Fusiona entidades superpuestas/duplicativas en una categoría en observaciones duraderas con evidencia rastreada (imagen espejo de `perseus_vault_conflicts`).
`perseus_vault_dream`	Consolidación LLM en tiempo de sueño: reflexiona sobre clústeres de memorias episódicas relacionadas mediante el LLM configurado y escribe percepciones semánticas duraderas, vinculadas por procedencia a cada fuente. Idempotente (hash de conjunto de evidencia), consciente de contradicciones, acotado; requiere `--llm-endpoint`.

Calidad

Herramienta	Descripción
`perseus_vault_score`	Asigna puntuación de calidad (0.0-1.0).
`perseus_vault_conflicts`	Detecta entidades conflictivas mediante similitud de trigramas; `resolve=true` opcional invalida el lado de menor certeza en el historial (reversible, ejecución en seco por defecto).
`perseus_vault_correct`	Captura estructurada de correcciones para aprender de errores.
`perseus_vault_supersede`	Marca un nuevo hecho como reemplazante de uno antiguo (establece la entidad antigua a `deprecated`).
`perseus_vault_follow`	Registra si una entidad fue realmente SEGUIDA u OMITIDA: señal de eficacia de tasa de seguimiento que alimenta tanto la puntuación de decaimiento como la clasificación de recuperación ponderada por resultados (#681).

Piedras angulares (reglas de política)

Herramienta	Descripción
`perseus_vault_keystone_set`	Redacta una Piedra angular: una regla de política obligatoria que sobrevive a la compactación de contexto (#683). Con ámbito (inquilino/flota/agente), clasificada por peso, encadenada criptográficamente en cada mutación; la redacción está restringida por nivel de confianza.
`perseus_vault_keystone_get`	Obtiene las Piedras angulares fusionadas para un ámbito, ordenadas por peso (mayor primero) y luego especificidad de ámbito: la contraparte determinista de inicio de sesión para la recuperación. Un renderizador inyecta estas antes de todo otro contexto.
`perseus_vault_agent`	Registra/actualiza o busca un agente en el registro multiagente (#684): identidad + nivel de confianza (0-3) + flota. El nivel de confianza restringe operaciones sensibles (p. ej., redactar piedras angulares requiere nivel ≥ 2) y impulsa la aplicación de visibilidad en la recuperación.

Transferencia de bóveda (federación entre pares deshabilitada)

Herramienta	Descripción
`perseus_vault_vault_export`	Exporta entidades a archivos .md con frontmatter YAML.
`perseus_vault_vault_import`	Importa desde directorio de bóveda .md (idempotente).
`perseus_vault_share`	Comparte una entidad (por categoría + clave) en otro espacio de trabajo, preservando el contenido.
`perseus_vault_workspace_list`	Lista todas las categorías de entidades distintas.

perseus_vault_federate está intencionalmente no anunciado ni ejecutable. La transferencia entre pares permanece deshabilitada hasta que se implementen autoridad autenticada, custodia con capacidad de reversión, manejo de conflictos y propagación de tumba/borrado. Usa las herramientas explícitas vault_export / vault_import para transferencias revisadas basadas en archivos.

Métricas y operaciones

Herramienta	Descripción
`perseus_vault_stats`	Estadísticas completas de la base de datos en todas las tablas.
`perseus_vault_health`	Verificación de salud del servidor y la base de datos.
`perseus_vault_bench`	Seguimiento de benchmarks de rendimiento.
`perseus_vault_maintenance`	Mantenimiento de la base de datos: deduplicación, detección de huérfanos, VACUUM, reindexación FTS5 (compatible con ejecución en seco).
`perseus_vault_synthesize`	Síntesis de sesión LLM: extrae lecciones de transcripciones.
`perseus_vault_migrate`	Migra base de datos v0.1.x al esquema actual.

Herramientas por trabajo (hoja de referencia del agente)

No es un listado de categorías, sino un listado de trabajos. Elige la fila para lo que el agente está intentando hacer:

Trabajo	Herramientas
Recordar un hecho / decisión / corrección duradero	`remember`, `capture`, `journal`, `correct`
Recuperar antes de planificar	`recall`, `recall_batch`, `recall_when`, `context`, `ask`
Reconstruir la narrativa de desarrollo (rastro de intención, próximo trabajo)	`handoff_pack` (con `include_intent_trail` / `include_next_work`), `delegation_brief`, `timeline`, `traverse`
Decisiones: reemplazo y autoridad	`supersede`, `history`, `authority_get`, `action_receipt_get`, `keystone_get`
Preguntar "¿qué creíamos entonces?"	`as_of`, `valid_at`, `bitemporal`, `history`
Corregir el registro / sacar a la luz contradicciones	`correct`, `supersede`, `conflicts`, `reject_value`
Política que sobrevive a la compactación	`keystone_get`, `keystone_set`
Operaciones, confianza y ámbito	`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

Actualizaciones en vivo sin reiniciar la sesión

perseus-vault serve detecta cuando su propio binario es reemplazado en disco a mitad de sesión (el flujo normal de cargo build / reinstalación) y se niega a servir resultados desde la imagen de proceso obsoleta: cada herramienta responde con un error explícito y sonoro en lugar de degradarse a resultados vacíos (#858, #1045). Dos rutas de recuperación, ambas en la misma conexión stdio (sin reinicio del cliente):

Explícito: llama a perseus_vault_handoff_restart {"confirm": true}: el proceso intercambia en caliente al nuevo binario y la sesión continúa sin problemas, con el estado de sesión MCP (inicialización + identidad del agente) preservado.
Automático (opt-in): inicia el servidor con PERSEUS_VAULT_AUTO_HANDOFF=1 y el intercambio ocurre de forma transparente en la siguiente llamada de herramienta, que el nuevo binario responde directamente.

En macOS/Linux el intercambio es un verdadero exec (mismo PID, mismas tuberías). Windows bloquea un ejecutable en ejecución, por lo que el reemplazo a mitad de sesión no es posible allí; actualiza a través de un límite de sesión. Contrato completo y flujo de trabajo de desarrollo local: docs/specs/live-update-handoff.md.

Ediciones manuales de la base de datos. Los verbos de mantenimiento anteriores y la ruta de escritura MCP normal mantienen el índice FTS5 sincronizado automáticamente. Editar la tabla entities directamente con sqlite3 (un DELETE/UPDATE manual) omite esa sincronización y puede dejar filas de índice huérfanas: "fantasmas" de aciertos de recuperación para contenido que ya no existe. Después de cualquier edición SQL directa, ejecuta perseus-vault maintain --db <path> (o perseus-vault reindex) para reconciliar el índice FTS.

Banderas

Flag	Descripción
`--db`	Ruta de la base de datos SQLite (predeterminado: `~/.perseus-vault/data/perseus-vault.db`)
`--profile`	Perfil de anuncio MCP: `default`/`all` (registro completo) o `lean` (superficie de memoria central; recomendado para hosts LLM)
`--web`	Iniciar panel web
`--port`	Puerto del panel (predeterminado: 8767)
`--web-bind`	Dirección de enlace del panel (predeterminado: 127.0.0.1)
`--transport`	Transporte MCP: `stdio` (predeterminado), `sse` o `http`
`--mcp-token`	Token Bearer para autenticación de transporte SSE/HTTP
`--encryption-key`	Ruta del archivo de clave AES-256-GCM
`--llm-endpoint`	Endpoint de API LLM para `perseus_vault_ask` y embeddings
`--llm-model`	Nombre del modelo LLM (predeterminado: llama3)
`--llm-api-key`	Clave API para endpoints LLM (OpenAI, Azure, etc.)
`--embedding-endpoint`	Endpoint de embeddings compatible con OpenAI
`--connectors-config`	Ruta a connectors.yaml

Ubicación de la base de datos

La ruta canónica de la base de datos es:

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

Pase siempre --db (o establezca $PERSEUS_VAULT_DB_PATH) en scripts, configuraciones de host MCP y trabajos cron/harvest para que cada invocación apunte al mismo archivo. Cuando no se establece ninguno, Perseus Vault resuelve el predeterminado en este orden y usa el primero que ya exista (para que las actualizaciones y las instalaciones heredadas de un solo usuario se detecten en lugar de iniciar silenciosamente vacías):

~/.perseus-vault/data/perseus-vault.db — canónico (nombre actual)
~/.perseus-vault/data/perseus-vault.db — antes del cambio de nombre
~/.perseus-vault/data/perseus-vault.db — antes del cambio de nombre
~/perseus-vault.db — ubicación heredada de instalación de un solo usuario

Si no existe ninguno, crea ~/.perseus-vault/data/perseus-vault.db. Si más de uno de estos existe y no pasó --db/$PERSEUS_VAULT_DB_PATH, Perseus Vault imprime una advertencia en stderr nombrando el archivo elegido y los demás que ignoró, de modo que un estado ambiguo de múltiples bases de datos sea visible en lugar de silencioso. Establecer --db o $PERSEUS_VAULT_DB_PATH explícitamente siempre tiene prioridad y suprime la advertencia.

Su memoria de IA en Obsidian

Perseus Vault es la memoria a largo plazo de su agente de IA — y funciona también como su segundo cerebro. Cada entidad que su agente recuerda se exporta a una nota Markdown simple con frontmatter YAML, de modo que la memoria de su IA se convierte en una base de conocimiento personal navegable dentro de las herramientas que ya usa: Obsidian, Logseq o 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 la bóveda en Obsidian y obtendrá un grafo del conocimiento de su agente.

Backlinks WikiLink. Cuando una entidad enlaza a otra (mediante perseus_vault_link o una relación depends_on / implements / references), la nota exportada recibe una sección ## Links con backlinks [[WikiLink]] que se resuelven de forma nativa en la vista de grafo de Obsidian:

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

{"content":"axum service"}

## Links

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

Los enlaces se resuelven por id de entidad (las notas se escriben como <id>.md) por lo que nunca se rompen, y Obsidian muestra el key legible por humanos como etiqueta del enlace. Abra la vista de grafo y la arquitectura, decisiones y conocimientos de su agente se convierten en un mapa de conocimiento clicable.

--watch consulta el resumen de estado determinista y económico de Perseus Vault en un intervalo y re-exporta solo cuando la memoria realmente cambia. Detecta naturalmente cada escritura perseus_vault_remember sin dependencia de un observador de archivos y sin acoplamiento con el servidor. Ajuste el intervalo con PERSEUS_VAULT_SYNC_INTERVAL_SECS (predeterminado: 2s).

Otras herramientas PKM

Herramienta	Cómo
Obsidian	`perseus-vault obsidian-sync <vault>` — los WikiLinks se resuelven en la vista de grafo de forma nativa.
Logseq	Apunte `obsidian-sync` al directorio de su grafo de Logseq. Logseq lee la misma sintaxis `[[WikiLink]]` y el frontmatter Markdown.
Notion	Ejecute `perseus-vault vault-export`, luego use Import → Markdown & CSV de Notion para importar las notas.

A diferencia de las herramientas de "segundo cerebro" solo en la nube, Perseus Vault se ejecuta 100% local, está escrito en Rust, cifra en reposo con AES-256-GCM y aplica puntuación de decaimiento para que los recuerdos obsoletos se desvanezcan — su base de conocimiento sigue siendo suya y se mantiene fresca.

Características

Búsqueda semántica (activada por defecto)

Embeddings integrados, en proceso — un modelo cuantizado all-MiniLM-L6-v2 (384-dim) está compilado en el binario, por lo que la búsqueda densa/semántica funciona con cero configuración y cero red: sin Ollama, sin clave API, sin descarga de modelo. Este es el build predeterminado (característica bundled-embeddings).
Auto-embed al escribir (#271) — perseus_vault_remember genera embeddings de cada entidad nueva (o con contenido modificado) sincrónicamente al escribirla, usando el modelo integrado. El embedding de una sola entidad es determinista y está cacheado con LRU, por lo que es económico y no agrega tareas en segundo plano. Los fallos de embedding no son fatales (se registran en stderr); la escritura siempre tiene éxito.
El híbrido es el modo de recuperación predeterminado (#271) — perseus_vault_recall(query=...) sin bandera mode selecciona automáticamente híbrido (denso + palabra clave fusionados mediante RRF) siempre que existan embeddings, y retrocede de forma transparente a la búsqueda de palabras clave fts5 cuando no los hay. Sin paso manual perseus_vault_embed, sin banderas que recordar.
perseus_vault_semantic_search(query, limit) — un atajo de una sola herramienta para búsqueda puramente densa, basada en significado (sin retroceso por palabra clave) cuando solo quiere "encontrar cosas similares a esto".
Embedder alternativo opcional — para usar Ollama o cualquier endpoint /v1/embeddings compatible con OpenAI en lugar del modelo integrado, establezca --llm-endpoint (y --embedding-endpoint / --llm-api-key según sea necesario). Esto es completamente opcional; el modelo integrado se usa por defecto.
Construya un binario ligero sin embeddings integrados mediante cargo build --no-default-features — la recuperación entonces usa búsqueda de palabras clave por defecto a menos que se configure un embedder remoto.

Internals de búsqueda híbrida

Búsqueda de palabras clave FTS5 con retroceso LIKE y expansión de stemming Porter
Búsqueda de vectores densos mediante similitud coseno en embeddings almacenados
Fusión de rango recíproco (RRF) — combina resultados de palabras clave + vectores
Expansión de consulta — variantes automáticas de stemming para mayor recuperación

Ciclo de vida de la memoria

Perseus Vault modela la memoria usando tres capas biomiméticas, inspiradas en las vías de memoria humana:

Mundo (Núcleo): Hechos globales de decaimiento lento sobre el entorno.
Episódica (Buffer): Historial de interacción específico de sesión, de decaimiento rápido.
Semántica (Trabajo): Conocimiento general y conceptos aprendidos, de decaimiento medio.

Puede interactuar con estas capas directamente usando la herramienta perseus_vault_recall_layer o especificando el parámetro layer en perseus_vault_remember.

Decaimiento de Ebbinghaus — los recuerdos se desvanecen naturalmente a menos que se recuperen (refresco al acceder)
Promoción de capas — buffer → trabajo → núcleo según la frecuencia de acceso
Archivo automático — las entidades obsoletas se archivan; purgue para eliminar permanentemente + VACUUM
Entidades siempre activas — fije recuerdos críticos de identidad para inyección de sesión (con tope duro bajo recall-first; prefiera disparadores recall_when)
Sugerencias de consulta prospectiva (#919) — 1–3 frases opcionales en lenguaje natural por entidad (hints en perseus_vault_remember) indexadas en FTS5 junto con el cuerpo, cerrando brechas de vocabulario entre consultas en lenguaje simple y el texto almacenado. Desactivado por defecto (PERSEUS_VAULT_HINTS_ENABLED=1); rechazado mientras esté desactivado. Ver docs/specs/prospective-query-hints.md.

Inyección de contexto recall-first

La bóveda es la capa de consulta — recupera los pocos hechos que un turno necesita en lugar de entregar al host un bloque permanente para insertar en cada prompt de sistema. perseus_vault_context y perseus-vault prepare son recall-first por defecto:

Filtrado por relevancia — pase query (la tarea/mensaje actual) y solo las entidades cuyos disparadores recall_when o contenido indexado coincidan se inyectan. Sin consulta, sin inyección temática: el bloque es un puntero de recuperación compacto, estable en bytes entre escrituras no relacionadas en la bóveda (amigable con caché de prefijo).
Presupuesto de recuperación por modelo — la salida se limita a un presupuesto de caracteres resuelto del modelo host: perfil predeterminado/ligero 1500 caracteres; perfil de ventana grande ("opus") 6000 caracteres; max_context_chars anula ambos.
Siempre activo con tope — always_on: true sigue funcionando para hechos críticos de identidad, pero el conjunto recall-first tiene un tope duro (top 5) y el desbordamiento emite una advertencia que lo orienta a disparadores recall_when.
Opt-in heredado — el antiguo volcado incondicional top-N sigue disponible con mode: "always_inject" (--legacy-context para prepare), sin límite a menos que pase un presupuesto.

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 y embeddings

perseus_vault_ask — preguntas y respuestas en lenguaje natural sobre memorias almacenadas mediante cualquier LLM (Ollama, OpenAI, etc.)
perseus_vault_embed — genera y almacena vectores densos mediante Ollama o /v1/embeddings compatible con OpenAI
Admite embedding de entidad única y por categoría por lotes

Cifrado

Cifrado transparente AES-256-GCM para body_json de entidades
Activado por defecto para instalaciones nuevas — la clave estándar se genera automáticamente en ~/.perseus-vault/secret.key en la primera escritura
Bandera --encryption-key para claves explícitas; perseus-vault keygen para generación de claves personalizada
Las bases de datos de texto plano existentes fallan de forma cerrada con una ruta de migración init --rekey (o PERSEUS_VAULT_ALLOW_PLAINTEXT=1 explícito)
El índice FTS5 permanece en texto plano para búsqueda

Panel web

Servidor HTTP Axum integrado (perseus-vault serve --web --port 8767)
Panel con tema oscuro con búsqueda, tabla de entidades, grafo vis.js, línea de tiempo
Enlace predeterminado: 127.0.0.1 (use --web-bind 0.0.0.0 para exponer)
Conexión SQLite separada en modo WAL para lecturas concurrentes

Conectores externos

Conector de issues de GitHub — ingiere issues/PRs por repositorio, consciente de límite de tasa
Observador de archivos — escanea directorios en busca de archivos .md/.txt/.json con deduplicación por hash de contenido
Configuración de conectores basada en YAML mediante --connectors-config

Multi-transporte

stdio (predeterminado) — cero configuración, funciona con cualquier host MCP
SSE — Server-Sent Events para clientes MCP basados en HTTP
HTTP — endpoint MCP estilo REST
Autenticación con token Bearer — para transportes SSE/HTTP

Integración con Perseus

Perseus Vault es el backend de memoria predeterminado 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

Gobierno y contratación federal

Perseus Vault está construido para despliegue gubernamental desde el inicio.

Capacidad	Estado
Licencia	MIT — sin copyleft, sin GPL/AGPL
SBOM	Publicado — elementos mínimos NTIA
Aislado de red	Totalmente offline — sin telemetría, sin llamadas API, sin red por defecto
Cifrado en reposo	AES-256-GCM en cuerpos, activado por defecto para instalaciones nuevas
Rastro de auditoría	Diario inmutable con cadena de custodia
Cadena de suministro	Atestación SLSA en progreso

Para compradores federales: Ver docs/federal-buyers.md para información de contratación, estado de cumplimiento y modelos de despliegue (aislado de red, on-premises, entornos clasificados).

Perseus Computing LLC es una pequeña empresa de propiedad estadounidense. Los identificadores de contratación actuales y las afirmaciones de preparación publicadas por el propietario se mantienen en la declaración de capacidad pública. Esas afirmaciones están fechadas y delimitadas; no constituyen certificación CMMC, un ATO ni una autorización cATO. NAICS: 541715, 541511, 541512.

Política de privacidad

Perseus Vault es un servidor MCP local-first — se ejecuta completamente en su máquina.

Recopilación de datos

Sin recopilación de datos. Perseus Vault no recopila, transmite ni envía a casa ningún dato de usuario, estadísticas de uso ni telemetría.
Todos los datos permanecen en su archivo de base de datos SQLite local.

Uso y almacenamiento de datos

Todas las entidades de memoria, entradas de diario y estado se almacenan localmente en una base de datos SQLite en la ruta que especifique mediante --db.
El cifrado opcional AES-256-GCM en reposo está disponible — cuando se activa, los cuerpos de entidades se cifran antes del almacenamiento.
Ningún dato se comparte con Perseus Computing LLC ni con terceros.

Compartición con terceros

Ninguna. Perseus Vault está completamente aislado de red por defecto. Sin llamadas API, sin servicios en la nube, sin solicitudes de red externas.
La característica opcional de embeddings de vectores densos usa un modelo compilado localmente — no se llama a ninguna API de embedding externa.

Retención de datos

Usted controla la retención con cuatro operaciones de ciclo de vida distintas (consulte docs/specs/data-boundaries-retention-lifecycle.md): eliminación suave (perseus_vault_forget, contenido recuperable), caducidad (perseus_vault_expire, basada en tiempo status='expired' con contenido conservado), redacción (perseus_vault_redact, contenido depurado a solo hash, metadatos conservados) y borrado físico (perseus_vault_erase, eliminación en todas las capas derivadas con supresión permanente de re-ingesta). perseus_vault_purge recupera espacio de filas archivadas.
No se realiza ninguna copia de seguridad automática fuera de la máquina.

Contacto

Correo electrónico: privacy@perseus.observer
GitHub: Perseus-Computing-LLC/perseus-vault

Verificación de versiones

Los binarios de las versiones se compilan a partir de confirmaciones etiquetadas mediante GitHub Actions. Cada versión incluye:

Artefacto	Descripción	Verificación
`perseus-vault-<target>.tar.gz`	Compilación completa (embeddings incluidos, glibc)	Suma de verificación SHA-256 en el archivo secundario `.sha256`
`perseus-vault-lite-<target>.tar.gz`	Compilación ligera (`--no-default-features`, musl/estático)	Suma de verificación SHA-256 en el archivo secundario `.sha256`
Atestación de procedencia SLSA	Procedencia de compilación firmada con Sigstore	`gh attestation verify <archive> --repo Perseus-Computing-LLC/perseus-vault`

Verificar un binario de versión

# 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)

Compilar de forma reproducible desde el código fuente

# 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

Licencia

MIT — consulte LICENSE.