Perseus Vault

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

Publicado en Official MCP Registry · Glama · mcpservers.org · Lulu MCPs · Docker (GHCR)

Dale a tus agentes una 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 + denso + RRF), historial bi-temporal y AES-256-GCM en reposo, expuestos como 168 herramientas MCP canónicas que funcionan con cualquier host. Los alias heredados mimir_*/mneme_* se eliminaron en la versión principal 2026-27 y no se cuentan por separado. 73.8% en el arnés oficial de LongMemEval (frente a Zep 63.8%, Mem0 49.0%). Un binario. Un archivo. Sin Docker. Sin Postgres. Sin nube. Local-primero, preparado para desconexión, 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 un canario de base de datos cifrada. Haz una copia de seguridad de esa clave: no se puede recuperar. Las rutas explícitas de --encryption-key siguen siendo compatibles, y las bases de datos existentes en texto plano se conservan para la 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 recibe 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 el código fuente bootstrap.sh firman el código de Perseus Vault ad-hoc 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   # required on Apple Silicon; fixes "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 solo 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 generic; --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 hooks 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 añade las reglas de uso de memoria a CLAUDE.md/AGENTS.md. Volver a ejecutarlo es una operación nula; añade --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"]
    }
  }
}

Related MCP server: GroundMemory

Para Agentes: Conéctate a través de MCP

Cuando el consumidor principal es un agente, la interfaz es MCP — el agente adopta el 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 solo comando. Para el mapa de capacidades orientado al agente — qué herramienta hace qué trabajo, y el patrón de límite de planificación — consulta docs/integration/agent-adoption.md.

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 decida inyectar. Es efímero y propiedad del host; no se persiste simplemente porque Vault lo haya devuelto.

• Memoria duradera explícita se escribe mediante una operación explícita de 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 son un reemplazo de los registros fuente duraderos y pueden necesitar una limpieza por separado.

perseus-vault prepare y perseus_vault_context leen registros duraderos para producir un contexto de trabajo activo acotado y relevante para la tarea. Esta es una instantánea continua, 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 prioritaria 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 hooks del 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 hook no están disponibles, continúa la tarea sin memoria inyectada y muestra el estado degradado. Una integración de host puede tener una alternativa local explícitamente configurada, pero esa alternativa 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.

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

Luego conecta el bucle recuperación → trabajo → captura → consolidación a los eventos de sesión de tu cliente (hooks SessionStart/Stop para Claude Code, Codex y Cursor, más una alternativa 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 el control del presupuesto de contexto de extremo a extremo: docs/integration/context-budget-stack.md.

Auditar lo que el Vault recuerda, de 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 delimita 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 los bancos se asignan de manera determinista (sha256("memory-bank:" + nombre)), por lo que cada instancia que apunta al mismo nombre se dirige al mismo espacio de trabajo sin necesidad de mantener un registro. Los espacios de trabajo son de primera clase en el servidor: mantenimiento delimitado, aislamiento de deduplicación entre bancos y manifiestos de autoridad por espacio de trabajo. El descubrimiento refleja las reglas de contexto del proyecto de Hermes (gana el .hermes.md más cercano, limitado a la raíz de git); un archivo de contexto sin una directiva significa que no hay banco — el espacio de trabajo configurado permanece en vigor.

Por qué Perseus Vault

Perseus Vault es el único motor de memoria que es simultáneamente nativo de MCP, local-primero, sin dependencias Y primero para agentes.

LongMemEval QA (arnés oficial)

Calidad de recuperación medida en el arnés oficial de LongMemEval, no en un script casero:

longmemeval_s (500 preguntas), respondedor gpt-4o-2024-08-06 + juez oficial de LongMemEval; los números de la competencia son sus valores publicados. El 73.8% de Perseus Vault es la media simple de 3 ejecuciones; 79.0% con CoT oficial. Metodología y resultados con hash de contenido (sha256) →

LOCOMO (arnés propio de mem0)

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

Cat-5 adversarial (446q): 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 del juez/plataforma — divulgado). 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 un desafío reproducible y completamente fuera de línea. 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 resuelven mal (correcciones retroactivas, hechos proactivos con fecha futura, llegada fuera de orden, divergencia creencia-vs-verdad, períodos cerrados):

Reproducir 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 de PASS/FAIL son deterministas (las marcas de tiempo de reloj 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

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

Prueba de estrés: 100K entidades

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

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

Ejecútalo tú mismo: python benchmark/scale/run.py

Precisión de recuperación a escala: colapsos de palabras clave, la híbrida se mantiene

La velocidad es el mínimo indispensable — la pregunta que importa para la memoria del agente es ¿la memoria correcta realmente aparece? Medido en corpus de contenido distinto (de primera parte, reproducible; ver benchmark/lambda/), recall@k por modo:

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

Con 100K entidades, la recuperación híbrida es perfecta en @5 mientras que la búsqueda por palabra clave acierta ~1.5% de las veces — una brecha de ~66×. Y se amplía con la escala: con 10K entidades, la recuperación por palabra clave en @5 fue 0.008 mientras que la híbrida ya era 1.000; la memoria solo por palabras clave se degrada silenciosamente a medida que un agente acumula historial, la híbrida (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 completamente local (1×H100, Ollama — conjunto de hechos, consultas y juez de subcadenas idéntico para cada sistema):

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) e igualó a 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 Zep Cloud, por lo que medimos el motor OSS real de Zep — Graphiti temporal KG en Neo4j — con extracción de entidades/aristas y embeddings 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 con pérdida: 5 entidades / 2 aristas a partir de 6 hechos) — no Zep Cloud, que utiliza 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.

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

Integraciones con frameworks

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

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 una guía rápida en README (5 minutos para funcionar)

• Tiene pruebas exitosas con transporte MCP simulado

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

150 herramientas canónicas MCP

Nombres canónicos de productos y herramientas. Perseus Vault es el nombre del producto, y las integraciones utilizan las herramientas canónicas perseus_vault_* (por ejemplo, perseus_vault_remember). Los nombres heredados mimir_* / mneme_* / plutus_* se eliminaron en la versión principal 2026-27 — los nombres canónicos son la única interfaz. El recuento es el número de herramientas canónicas únicas en el registro fuente. Los alias de compatibilidad se pueden llamar pero no se cuentan por separado. Los nombres heredados perseus_vault_* y perseus_vault_* siguen siendo completamente invocables — cada prefijo se envía al mismo manejador — simplemente ya no se anuncian en tools/list. Esto mantiene el manifiesto anunciado con un nombre por herramienta en lugar de triplicarlo (inflado de 3× alias), por lo que los clientes conectados no recargan una carga útil de esquema de herramientas triplicada en cada solicitud. Para restaurar el comportamiento histórico de anunciar los tres prefijos, establece PERSEUS_VAULT_TOOL_ALIASES=all (la variable de entorno heredada PERSEUS_VAULT_TOOL_ALIASES también se respeta; PERSEUS_VAULT_ tiene prioridad).

Compatibilidad con clientes (#633). Los clientes que se basan en la lista anunciada — verifican tools/list antes de llamar y omiten las herramientas que no ven — omitirán silenciosamente las llamadas heredadas perseus_vault_* contra un vault 2.x aunque la llamada en sí misma tendría éxito. Caso conocido: la CLI perseus ≤ 1.0.22 codifica rígidamente perseus_vault_recall y se degrada a una recuperación local vacía. Solución en cualquiera de los lados: actualiza la CLI a ≥ 1.0.23 (llama a nombres canónicos, con respaldo dinámico), o establece PERSEUS_VAULT_TOOL_ALIASES=all en el vault como puente mientras los clientes antiguos permanezcan desplegados.

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

Por defecto, tools/list anuncia todas las herramientas canónicas. Establece PERSEUS_VAULT_TOOL_SCOPE para reducir la superficie anunciada para clientes agentes con restricciones de tokens y atención:

Los ámbitos son solo de anuncio: una herramienta oculta sigue siendo completamente invocable a través de tools/call, y la autorización permanece con el enlace del 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 ser clasificada. Las herramientas de nivel admin (migrate, purge, erase, vault_import, authority_set / authority_revoke / authority_set_signed) nunca aparecen en una lista con ámbito.

CRUD de entidades

Búsqueda y RAG

📖 docs/retrieval-modes.md — una referencia enumerada para cada modo de recuperación (palabra clave · densa · híbrida · gráfico · GraphRAG · proactiva recall_when · temporal as_of): mecanismo, cuándo usarlo, invocación y ejemplos.

Gráfico

Diario

Estado

Ciclo de vida

Calidad

Keystones (reglas de política)

Vault y Federación

Métricas y Operaciones

Herramientas por trabajo (chuleta para el agente)

No es un listado de categorías, sino un listado de trabajos. Elige la fila correspondiente a lo que el agente intenta hacer:

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 durante la 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 notorio en lugar de degradarse a resultados vacíos (#858, #1045). Dos vías de recuperación, ambas sobre la misma conexión stdio (sin reinicio del cliente):

• Explícita: llama a perseus_vault_handoff_restart {"confirm": true} — el proceso cambia en caliente al nuevo binario y la sesión continúa sin problemas, preservando el estado de la sesión MCP (inicialización + identidad del agente).

• Automática (opt-in): inicia el servidor con PERSEUS_VAULT_AUTO_HANDOFF=1 y el intercambio ocurre de forma transparente en la siguiente llamada a la herramienta, que el nuevo binario responde directamente.

En macOS/Linux el intercambio es un exec real (mismo PID, mismas tuberías). Windows bloquea un ejecutable en ejecución, por lo que el reemplazo durante la 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 normal de MCP mantienen el índice FTS5 sincronizado automáticamente. Editar la tabla entities directamente con sqlite3 (un DELETE/UPDATE manual) evita esa sincronización y puede dejar filas de índice huérfanas: aciertos de recuerdo "fantasma" para contenido que ya no existe. Después de cualquier edición SQL directa, ejecuta perseus-vault maintain --db <ruta> (o perseus-vault reindex) para reconciliar el índice FTS.

Banderas

Ubicación de la base de datos

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

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

Pasa siempre --db (o establece $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 la opción predeterminada en este orden y usa la primera que ya exista (así se recogen las instalaciones actualizadas y las heredadas de un solo usuario, en lugar de comenzar en silencio vacío):

1. ~/.perseus-vault/data/perseus-vault.db — canónica (nombre actual)

2. ~/.perseus-vault/data/perseus-vault.db — antes del cambio de nombre

3. ~/.perseus-vault/data/perseus-vault.db — antes del cambio de nombre

4. ~/perseus-vault.db — ubicación heredada de instalación de un solo usuario

Si no existe ninguna, crea ~/.perseus-vault/data/perseus-vault.db. Si existe más de una de estas y no pasaste --db/$PERSEUS_VAULT_DB_PATH, Perseus Vault imprime una advertencia en stderr nombrando el archivo elegido y los demás que ignoró, para 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 gana y suprime la advertencia.

Tu Memoria de IA en Obsidian

Perseus Vault es la memoria a largo plazo de tu agente de IA — y funciona también como tu segundo cerebro. Cada entidad que tu agente recuerda se exporta a una nota Markdown simple con frontmatter YAML, por lo que la memoria de tu IA se convierte en una base de conocimiento personal navegable dentro de las herramientas que ya usas: 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

Abre el vault en Obsidian y obtienes un grafo del conocimiento de tu agente.

Enlaces WikiLink. Cuando una entidad enlaza a otra (a través de perseus_vault_link o una relación depends_on / implements / references), la nota exportada obtiene una sección ## Links con enlaces [[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 la clave legible como etiqueta del enlace. Abre la vista de grafo y la arquitectura, decisiones e ideas de tu agente se convierten en un mapa de conocimiento interactivo.

--watch sondea el resumen de estado determinista y económico de Perseus Vault en un intervalo y reexporta solo cuando la memoria realmente cambia. Captura naturalmente cada escritura perseus_vault_remember sin dependencia de un vigilante de sistema de archivos y sin acoplamiento al servidor. Ajusta el intervalo con PERSEUS_VAULT_SYNC_INTERVAL_SECS (predeterminado: 2s).

Otras herramientas PKM

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

Características

Búsqueda Semántica (activada por defecto)

• Embeddings empaquetados y en proceso — un modelo cuantizado all-MiniLM-L6-v2 (384-dim) se compila 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. Esta es la compilación predeterminada (característica bundled-embeddings).

• Auto-embedding al escribir (#271) — perseus_vault_remember incrusta cada entidad nueva (o con contenido modificado) de forma síncrona al momento de escritura, utilizando el modelo empaquetado. El embedding de una sola entidad es determinista y se almacena en caché LRU, por lo que es económico y no añade tareas en segundo plano. Los fallos de embedding no son fatales (se registran en stderr); la escritura siempre se realiza correctamente.

• Híbrido es el modo de recuperación predeterminado (#271) — perseus_vault_recall(query=...) sin la bandera mode selecciona automáticamente híbrido (denso + palabras clave fusionadas mediante RRF) cuando existen embeddings, y retrocede de forma transparente a la búsqueda por palabras clave fts5 cuando no los hay. Sin paso manual de 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 a palabras clave) cuando solo quieres "encontrar cosas como esta".

• Incrustador alternativo opcional — para usar Ollama o cualquier endpoint /v1/embeddings compatible con OpenAI en lugar del modelo empaquetado, configura --llm-endpoint (y --embedding-endpoint / --llm-api-key según sea necesario). Esto es completamente opcional; el modelo empaquetado se usa por defecto.

• Compila un binario ligero sin embeddings empaquetados mediante cargo build --no-default-features — la recuperación entonces usa por defecto la búsqueda por palabras clave a menos que se configure un incrustador remoto.

Funcionamiento interno de la búsqueda híbrida

• Búsqueda por palabras clave FTS5 con retroceso LIKE y expansión de stemming de 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 una recuperación más amplia

Ciclo de vida de la memoria

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

• Mundo (Núcleo): Hechos globales y de lenta descomposición sobre el entorno.

• Episódica (Búfer): Historial de interacción de sesión específica y de rápida descomposición.

• Semántica (Trabajo): Conocimiento general y conceptos aprendidos de descomposición media.

Puedes 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 (se actualizan al acceder)

• Promoción de capas — búfer → trabajo → núcleo basado en la frecuencia de acceso

• Archivado automático — las entidades obsoletas se archivan; purga para eliminar permanentemente + VACUUM

• Entidades siempre activas — fija recuerdos críticos de identidad para inyección en la sesión (con un límite máximo bajo recuperación primero; prefiere los disparadores recall_when)

• Pistas de consulta prospectiva (#919) — de 1 a 3 frases opcionales en lenguaje natural por entidad (hints en perseus_vault_remember) que se indexan en FTS5 junto con el cuerpo, cerrando las brechas de vocabulario entre consultas en lenguaje simple y el texto almacenado. Desactivado por defecto (PERSEUS_VAULT_HINTS_ENABLED=1); rechazado mientras esté desactivado. Consulta docs/specs/prospective-query-hints.md.

Inyección de contexto de recuperación primero

La bóveda es la capa de consulta — recupera los pocos hechos que necesita un turno en lugar de entregar al anfitrión un bloque permanente para adjuntar a cada mensaje del sistema. perseus_vault_context y perseus-vault prepare son recuperación primero por defecto:

• Filtrado por relevancia — pasa query (la tarea/mensaje actual) y solo se inyectan las entidades cuyos disparadores recall_when o contenido indexado coinciden. Sin consulta, sin inyección temática: el bloque es un puntero de recuperación compacto, estable en bytes a través de escrituras de bóveda no relacionadas (amigable con el caché de prefijo).

• Presupuesto de recuperación por modelo — la salida se limita a un presupuesto de caracteres resuelto del modelo anfitrión: perfil predeterminado/ligero 1500 caracteres; perfil de ventana grande ("opus") 6000 caracteres; max_context_chars anula ambos.

• Siempre activo con límite — always_on: true aún funciona para hechos críticos de identidad, pero el conjunto de recuperación primero tiene un límite máximo (top 5) y el desbordamiento emite una advertencia que te dirige a los disparadores recall_when.

• Legado opt-in — el antiguo volcado incondicional de los N principales aún está disponible con mode: "always_inject" (--legacy-context para prepare), sin límite a menos que pases 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 recuerdos almacenados a través de cualquier LLM (Ollama, OpenAI, etc.)

• perseus_vault_embed — genera y almacena vectores densos a través de Ollama o un endpoint /v1/embeddings compatible con OpenAI

• Soporta embedding de una sola entidad y por lotes de categoría

Cifrado

• Cifrado transparente AES-256-GCM para body_json de la entidad

• Habilitado 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 personalizadas

• 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 la búsqueda

Panel web

• Servidor HTTP Axum integrado (perseus-vault serve --web --port 8767)

• Panel de control con tema oscuro con búsqueda, tabla de entidades, gráfico vis.js, línea de tiempo

• Enlace predeterminado: 127.0.0.1 (usa --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/PR por repositorio, consciente del límite de tasa

• Vigilante de archivos — escanea directorios en busca de archivos .md/.txt/.json con deduplicación por hash de contenido

• Configuración de conector basada en YAML a través de --connectors-config

Multi-Transporte

• stdio (predeterminado) — sin configuración, funciona con cualquier host MCP

• SSE — Eventos enviados por el servidor para clientes MCP basados en HTTP

• HTTP — Endpoint MCP de 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 implementación gubernamental desde sus cimientos.

Para compradores federales: Consulta docs/federal-buyers.md para información de contratación, estado de cumplimiento y modelos de implementación (entornos aislados de red, locales, clasificados).

Perseus Computing LLC es una pequeña empresa estadounidense. Registro en SAM.gov en curso. NAICS: 541715, 541511, 541512.

Política de Privacidad

Perseus Vault es un servidor MCP local primero — se ejecuta completamente en tu máquina.

Recopilación de Datos

• Sin recopilación de datos. Perseus Vault no recopila, transmite ni se comunica con el exterior ningún dato de usuario, estadísticas de uso o telemetría.

• Todos los datos permanecen en tu archivo de base de datos SQLite local.

Uso y Almacenamiento de Datos

• Todas las entidades de memoria, entradas del diario y estado se almacenan localmente en una base de datos SQLite en la ruta que especifiques mediante --db.

• El cifrado en reposo AES-256-GCM opcional está disponible — cuando está habilitado, los cuerpos de las entidades se cifran antes del almacenamiento.

• No se comparten datos con Perseus Computing LLC ni con terceros.

Intercambio con Terceros

• Ninguno. 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 utiliza un modelo compilado localmente — no se llama a ninguna API de embedding externa.

Retención de Datos

• Tú controlas la retención con cuatro operaciones distintas del ciclo de vida (consulta docs/specs/data-boundaries-retention-lifecycle.md): eliminación suave (perseus_vault_forget, contenido recuperable), caducidad (perseus_vault_expire, status='expired' basado en tiempo con contenido retenido), redacción (perseus_vault_redact, contenido eliminado 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 las 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 Lanzamiento

Los binarios de lanzamiento se compilan a partir de confirmaciones etiquetadas a través de GitHub Actions. Cada lanzamiento incluye:

Verificar un binario de lanzamiento

# 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.20.2 (v2.20.2-0-gabcdef1)

# 4. Confirm the doctor reports the same identity
./perseus-vault doctor --db /tmp/test.db | head -1
#   perseus-vault doctor — v2.20.2 (v2.20.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 — consulta LICENSE.