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.
curl -sSf https://raw.githubusercontent.com/Perseus-Computing-LLC/perseus-vault/main/scripts/install.sh | shEso es todo. Perseus Vault se instala en ~/.local/bin/perseus-vault. Inícialo:
perseus-vault serve --db ~/.perseus-vault/data/perseus-vault.dbEl cifrado se habilita automáticamente para la instalación predeterminada. La primera ejecución crea
~/.perseus-vault/secret.keycon 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-keysiguen siendo compatibles, y las bases de datos existentes en texto plano se conservan para la migración conperseus-vault init --rekey. Usadoctorpara 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 fuentebootstrap.shfirman 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"
--forcevuelve 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 --rulesEsto 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
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 doctorperseus-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.
# 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.dbPerseus 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.
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 Code / Hermes | ✅ |
|
Cursor | ✅ |
|
Windsurf | ✅ |
|
VS Code + Continue.dev | ✅ |
|
Zed | ✅ |
|
Codex CLI | ✅ |
|
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.
¿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 overrideEl 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.
Perseus Vault es el único motor de memoria que es simultáneamente nativo de MCP, local-primero, sin dependencias Y primero para agentes.
Calidad de recuperación medida en el arnés oficial de LongMemEval, no en un script casero:
Motor de memoria | Precisión QA |
Perseus Vault | 73.8% |
Zep | 63.8% (publicado) |
Mem0 | 49.0% (publicado) |
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) →
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:
Motor | General | Simple | 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 |
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 →
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):
Eje | Pregunta que responde | Comprobaciones | Aciertos |
valid-time ( | "qué era verdad en el mundo en T" | 10 | 10 |
transaction-time ( | "qué creíamos en T" | 1 | 1 |
bi-temporal ( | "según la creencia en T, qué era verdad en V" | 2 | 2 |
Total | 13 | 13 (100%) |
Reproducir con un solo comando (sin clave API, sin red, sin LLM):
cargo build --release
python benchmark/temporal/gauntlet.py --bin target/release/perseus-vaultLos 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 →
Perseus Vault | Mem0 | Letta | Zep | |
Despliegue | Binario único | Nube + autoalojado | Docker/Postgres | Docker/Neo4j |
Dependencias | Ninguna (SQLite integrado) | Python + BD vectorial | Postgres + Python | Neo4j + Go (Graphiti) |
MCP-Nativo | ✅ 157 herramientas canónicas | ❌ No es MCP-nativo | ❌ No es MCP-nativo | ❌ No es MCP-nativo |
Sin conexión/Local | ✅ Completamente local | Dependiente de la nube | Requiere Docker | Requiere Docker |
Cifrado | AES-256-GCM ✅ | ❌ | ❌ | ❌ |
Búsqueda híbrida | BM25 + Dense + 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 | 103 canónicas | 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 →
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.
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 |
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
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):
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 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):
Sistema | Precisión de recuperación | Latencia p50 | Notas |
Perseus Vault (híbrido) | 1.00 | 35.6 ms | binario único autocontenido, en proceso |
Letta (archival / pgvector) | 1.00 | 135.5 ms | servidor + Postgres/pgvector |
Mem0 (vector) | 0.60 | 37.9 ms | Python + BD vectorial |
Zep (Graphiti temporal KG) | 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) 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.
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 |
| implementación de | |
| herramienta de agente | |
| implementación de |
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.
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 heredadosmimir_*/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 heredadosperseus_vault_*yperseus_vault_*siguen siendo completamente invocables — cada prefijo se envía al mismo manejador — simplemente ya no se anuncian entools/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, establecePERSEUS_VAULT_TOOL_ALIASES=all(la variable de entorno heredadaPERSEUS_VAULT_TOOL_ALIASEStambién se respeta;PERSEUS_VAULT_tiene prioridad).Compatibilidad con clientes (#633). Los clientes que se basan en la lista anunciada — verifican
tools/listantes de llamar y omiten las herramientas que no ven — omitirán silenciosamente las llamadas heredadasperseus_vault_*contra un vault 2.x aunque la llamada en sí misma tendría éxito. Caso conocido: la CLIperseus≤ 1.0.22 codifica rígidamenteperseus_vault_recally 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 establecePERSEUS_VAULT_TOOL_ALIASES=allen el vault como puente mientras los clientes antiguos permanezcan desplegados.
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:
Configuración | Superficie anunciada | Recuento |
| todo | 150 |
| superficie de agente + limpieza operativa, mantenimiento, gobernanza, exportación | 140 |
| memoria cotidiana + superficie de coordinación (recall / remember / context / handoffs / state, más las llamadas AAR del lado del agente) | 48 |
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.
Herramienta | Descripción |
| Almacenar/actualizar entidad. Idempotente por (categoría, clave); un cambio de contenido crea una instantánea de la versión anterior en el historial. |
| Búsqueda con modos FTS5/denso/híbrido, filtros, expansión por lematización. Contrato de consulta (#562): |
| Enumeración paginada determinista de una categoría o de todo el almacén (#562): páginas inmutables con clave |
| Informe de higiene de memoria de inicio de solo lectura (#675): puntúa las memorias activas según su "capacidad de acción" (anclas concretas — claves de incidencia, #refs, rutas, URL, decisiones — frente a información vaga/solo fecha/corta) y enumera las peores con razones, para la curación de archivo/consolidación. |
| Recuperación desde una capa biomimética específica (mundo, episódica, semántica). |
| Recuperación proactiva justo a tiempo: mostrar entidades cuyos disparadores |
| Obtener una entidad por ID con |
| Viaje en el tiempo en tiempo de transacción: la versión de un hecho (categoría + clave) creída en un instante pasado. |
| Búsqueda en tiempo válido: la versión realmente cierta en el mundo en un instante, según el conocimiento actual (SQL:2011 APPLICATION_TIME). |
| Consulta bitemporal completa de 2 ejes: "al momento de transacción T, ¿qué creíamos que era cierto en el tiempo válido V?" — la celda de rectángulo exacta. |
| Listar versiones reemplazadas de un hecho (categoría + clave), primero las más recientes — paginado ( |
| Eliminación suave (archivado=1). |
Herramienta | Descripción |
| RAG: recuperar contexto, consultar LLM, devolver respuesta fundamentada con fuentes. |
| Generar vectores densos mediante el modelo incluido, Ollama o un endpoint compatible con OpenAI. |
| Atajo de búsqueda semántica solo densa: encontrar entidades por significado, clasificadas únicamente por similitud de incrustación (sin respaldo de palabras clave). |
| Bloque de markdown preformateado para inyección en sesión. Por defecto, recuperación primero: pasar |
| Activar sincronizaciones de conectores (GitHub, vigilante de archivos); el contenido no modificado se omite mediante repetición de contención (#1050). |
| Red de pérdida de extracción (#1048): retener oraciones que el extractor omitió como intervalos residuales, palabra por palabra con procedencia. |
| Red de pérdida de extracción (#1048): rechazo como señal — re-puntuar intervalos frente a la consulta, devolver una carga útil de reintento, marcar unidades con pérdida. |
| Red de pérdida de extracción (#1048): confirmar un reintento — adjuntar una clave de consulta provisional para que la consulta repetida idéntica sirva de primer paso. |
| Extraer localmente el texto de un documento (texto plano/markdown siempre; DOCX/PDF con la característica |
| Extracción de conocimiento local, determinista y basada en reglas (hechos / preferencias / eventos temporales / episodios) a partir de texto o de una entidad almacenada. Solo lectura. |
| Captura opcional en sesión (#520): destilar una carga útil de transcripción/información (texto, markdown o JSONL) en entidades duraderas (causa raíz / escollo / decisión / patrón / conclusión) en el momento en que se resuelve un problema. Destilador local basado en reglas por defecto, |
| Interfaz de archivo compatible con la herramienta de memoria de Anthropic ( |
📖 docs/retrieval-modes.md — una referencia enumerada para cada modo de recuperación (palabra clave · densa · híbrida · gráfico · GraphRAG · proactiva
recall_when· temporalas_of): mecanismo, cuándo usarlo, invocación y ejemplos.
Herramienta | Descripción |
| Crear enlaces de relación tipados entre entidades. |
| Eliminar enlaces de entidades. |
| Recorrer el grafo de enlaces de entidades hasta una profundidad configurable. |
| Detección de comunidades GraphRAG sobre el grafo de enlaces (propagación de etiquetas determinista o "louvain" de modularidad voraz; Rust puro, sin conexión). |
| Resumen extractivo (opcionalmente pulido por LLM) de una comunidad, materializado como una entidad con enlaces |
| 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. |
| Informe de deriva de solo lectura de grafo/entidades/índices/recibos (#869): aristas no atestiguadas, colgantes, archivadas/objetivo caducado y entre espacios de trabajo, membresías de comunidades obsoletas, deriva de FTS, referencias de diario a entidades faltantes. |
| Sellar el id de entidad del lado origen como ancla de evidencia en aristas heredadas para que sean servibles por los brazos de recuperación del grafo (#869); vista previa en seco (dry-run), registrado en diario. |
Herramienta | Descripción |
| Añadir evento estructurado con atribución de actor. |
| Guardia de déjà vu: verificar una acción contra fallos registrados previamente (entidades de diario + fallo/trampa) antes de reintentarla. Solo lectura. |
| Consultar diario por rango de tiempo con filtros. |
Herramienta | Descripción |
| Establecer estado clave-valor con TTL opcional. |
| Obtener valor de estado. Devuelve null si ha expirado. |
| Eliminar entrada de estado. |
| Listar claves de estado, opcionalmente filtradas por prefijo. |
Herramienta | Descripción |
| Recalcular puntuaciones de decaimiento de Ebbinghaus (transacciones por lotes de 1000 entidades). |
| Archivar en masa por categoría, umbral de decaimiento o antigüedad. |
| Eliminar permanentemente entidades archivadas + VACUUM. Destructivo. |
| Barrido de ciclo de vida basado en tiempo: las entidades cuyo |
| Redacción de contenido: limpiar el cuerpo de una entidad con ámbito de espacio de trabajo a un marcador solo hash, eliminar historial + texto FTS, conservar metadatos (se permite reingestión). Requiere |
| 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 reingestión. Requiere |
| Pasada autónoma de ordenación de coherencia — promover, decaer, enlazar, archivar. |
| Ordenación atómica completa: cohere → decay → compact en una sola pasada (compatible con dry-run). |
| Archivar entidades por debajo del umbral de decaimiento. |
| Reconstruir índice de búsqueda FTS5 desde la tabla de entidades. |
| Fusionar entidades superpuestas/duplicadas en una categoría en observaciones duraderas con seguimiento de evidencia (imagen especular de |
| Consolidación LLM en tiempo de reposo: reflexionar sobre clústeres de recuerdos episódicos relacionados a través del LLM configurado y escribir de vuelta conocimientos semánticos duraderos, vinculados por procedencia a cada fuente. Idempotente (hash del conjunto de evidencia), consciente de contradicciones, acotado; requiere |
Herramienta | Descripción |
| Asignar puntuación de calidad (0.0-1.0). |
| Detectar entidades conflictivas mediante similitud de trigramas; la opción |
| Captura estructurada de correcciones para aprender de errores. |
| Marcar un nuevo hecho como sustituto de uno antiguo (establece la entidad antigua como |
| Registrar si una entidad fue realmente SEGUIDA o PERDIDA — señal de eficacia de tasa de seguimiento que alimenta tanto la puntuación de decaimiento como el ranking de recuperación ponderado por resultado (#681). |
Herramienta | Descripción |
| Crear un Keystone — una regla de política obligatoria que sobrevive a la compactación de contexto (#683). Con ámbito (inquilino/flota/agente), clasificado por peso, encadenado criptográficamente en cada mutación; la creación está controlada por nivel de confianza. |
| Obtener los Keystones fusionados para un ámbito, ordenados por peso (mayor primero) luego por especificidad del ámbito — la contraparte determinista de inicio de sesión para la recuperación. Un renderizador los inyecta antes de todo otro contexto. |
| Registrar/actualizar o buscar un agente en el registro multiagente (#684): identidad + nivel de confianza (0-3) + flota. El nivel de confianza controla operaciones sensibles (p. ej., crear keystones requiere nivel ≥ 2) y impulsa la aplicación de visibilidad en la recuperación. |
Tool | Description |
| Exportar entidades a archivos .md con frontmatter YAML. |
| Importar desde un directorio vault .md (idempotente). |
| Copiar entidades entre espacios de trabajo. Es una exportación local / cambio de nombre de espacio de trabajo / reimportación (basada en archivos, sin peers de red); la ruta predeterminada segura para Windows se rastrea en #704. |
| Compartir una entidad (por categoría + clave) en otro espacio de trabajo, preservando el contenido. |
| Listar todas las categorías de entidades distintas. |
Tool | Description |
| Estadísticas completas de la base de datos en todas las tablas. |
| Verificación de estado del servidor y la base de datos. |
| Seguimiento de benchmarks de rendimiento. |
| Mantenimiento de la base de datos: dedup, detección de huérfanos, VACUUM, reindexación FTS5 (admite dry-run). |
| Síntesis de sesiones LLM: extraer lecciones de transcripciones. |
| Migrar base de datos v0.1.x al esquema actual. |
No es un listado de categorías, sino un listado de trabajos. Elige la fila correspondiente a lo que el agente intenta hacer:
Trabajo | Herramientas |
Recordar un hecho / decisión / corrección duraderos |
|
Recordar antes de planificar |
|
Reconstruir la narrativa de desarrollo (rastro de intención, próximo trabajo) |
|
Decisiones: sustitución y autoridad |
|
Preguntar "¿qué creíamos entonces?" |
|
Corregir el registro / sacar a la luz contradicciones |
|
Política que sobrevive a la compactación |
|
Operaciones, confianza y alcance |
|
# 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.keyperseus-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
entitiesdirectamente consqlite3(unDELETE/UPDATEmanual) 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, ejecutaperseus-vault maintain --db <ruta>(operseus-vault reindex) para reconciliar el índice FTS.
Flag | Description |
| Ruta de la base de datos SQLite (predeterminado: |
| Iniciar panel web |
| Puerto del panel (predeterminado: 8767) |
| Dirección de enlace del panel (predeterminado: 127.0.0.1) |
| Transporte MCP: |
| Token Bearer para autenticación de transporte SSE/HTTP |
| Ruta del archivo de clave AES-256-GCM |
| Punto final de la API LLM para |
| Nombre del modelo LLM (predeterminado: llama3) |
| Clave API para puntos finales LLM (OpenAI, Azure, etc.) |
| Punto final de embeddings compatible con OpenAI |
| Ruta a connectors.yaml |
La ruta canónica de la base de datos es:
~/.perseus-vault/data/perseus-vault.dbPasa 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):
~/.perseus-vault/data/perseus-vault.db — canónica (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 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.
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/ --watchAbre 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).
Herramienta | Cómo |
Obsidian |
|
Logseq | Apunta |
Notion | Ejecuta |
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.
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.
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
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.
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-inperseus_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 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
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
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
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
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: 10Perseus Vault está construido para implementación gubernamental desde sus cimientos.
Capacidad | Estado |
Licencia | MIT — sin copyleft, sin GPL/AGPL |
SBOM | Publicado — elementos mínimos NTIA |
Aislado de red | Completamente fuera de línea — sin telemetría, sin llamadas API, sin red por defecto |
Cifrado en reposo | AES-256-GCM en cuerpos, habilitado por defecto para instalaciones nuevas |
Pista de auditoría | Diario inmutable con cadena de custodia |
Cadena de suministro | Atestación SLSA en curso |
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.
Perseus Vault es un servidor MCP local primero — se ejecuta completamente en tu máquina.
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.
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.
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.
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.
Correo electrónico: privacy@perseus.observer
Los binarios de lanzamiento se compilan a partir de confirmaciones etiquetadas a través de GitHub Actions. Cada lanzamiento incluye:
Artefacto | Descripción | Verificación |
| Compilación completa (embeddings empaquetados, glibc) | Suma de verificación SHA-256 en el archivo lateral |
| Compilación ligera ( | Suma de verificación SHA-256 en el archivo lateral |
Atestación de procedencia SLSA | Procedencia de compilación firmada por Sigstore |
|
# 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)# 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 --versionMIT — consulta LICENSE.
Ask a natural language question and get a grounded answer from stored memories via RAG. Internally recalls top-k entities, assembles context, and queries the configured LLM (Ollama) for an answer with cited sources. Requires --llm-endpoint to be set.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural language question to answer from stored memories | |
| top_k | No | Number of top entities to use as context (max 20) |
| Name | Required | Description |
|---|---|---|
| answer | No | Grounded answer with cited sources |
| sources | No | Cited source entities used in the answer |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the readOnlyHint and destructiveHint annotations by detailing the internal process: recalling top-k entities, assembling context, and querying the configured LLM (Ollama) for an answer with cited sources. It also discloses the dependency on the '--llm-endpoint' configuration, which is critical for the tool's operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sentences. The first sentence clearly states the primary function, and the second adds important internal details and a requirement. No extraneous words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 parameters, full schema coverage, and an output schema (indicated by context), the description covers the key aspects: purpose, internal process (RAG, top-k, LLM), and a configuration requirement. It lacks explicit mention of which memories are queried (e.g., current workspace) but remains sufficiently complete for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full descriptions for both parameters ('query' and 'top_k'), achieving 100% schema coverage. The description mentions 'Internally recalls top-k entities' which adds marginal context to the 'top_k' parameter but does not significantly enhance understanding beyond the schema. Given high schema coverage, the description adequately complements but does not surpass the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: ask a natural language question and get a grounded answer from stored memories via RAG. It uses a specific verb ('ask') and resource ('stored memories'), and the wording distinguishes it from sibling tools like 'mimir_recall' or 'mimir_synthesize' by emphasizing the natural language Q&A nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite ('Requires --llm-endpoint to be set') but does not provide explicit guidance on when to use this tool versus alternatives (e.g., mimir_recall for raw retrieval, mimir_synthesize for generation without memories). The usage context is somewhat implied through the tool's purpose, but lacking explicit when-not-to-use or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bi-temporal time-travel: return the version of a fact (category + key) that Mimir believed at a given past instant. When a fact is overwritten, the prior version is kept in history; this returns whichever version was live at as_of_unix_ms. Use to answer 'what did we believe about X back then?' or to audit how a fact changed. Returns found=false if the fact had not been recorded yet at that time.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Entity key within the category | |
| category | Yes | Entity category | |
| as_of_unix_ms | Yes | Transaction-time instant (unix ms) to travel to |
| Name | Required | Description |
|---|---|---|
| id | No | |
| key | No | |
| found | No | False if the fact had not been recorded by as_of_unix_ms |
| status | No | |
| category | No | |
| body_json | No | The fact's content as it was at as_of_unix_ms |
| entity_type | No | |
| as_of_unix_ms | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds valuable context about history retention ('when a fact is overwritten, the prior version is kept') and the return behavior ('Returns found=false if not recorded yet'). This goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise sentences, each adding value: purpose, history explanation, use cases, return behavior. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown but indicated), the description covers purpose, behavior, and return field ('found'). It lacks mention of error conditions but is sufficiently complete for a time-travel query tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description mentions 'category + key' and 'as_of_unix_ms' but uses similar wording as the schema. It does not add significant new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb ('return the version of a fact') and resource ('category + key') and distinguishes from siblings by highlighting time-travel and history. It also gives concrete use cases like 'what did we believe about X back then?'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use to answer...' providing clear context for when to use this tool. It does not explicitly exclude alternatives but implies that for current versions other tools would be used. This is sufficient for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a full atomic grooming pass: cohere (promote, link, archive), then decay (recalculate Ebbinghaus decay), then compact (archive below threshold). Returns a summary report. Use dry_run=true to preview without changes.
| Name | Required | Description | Default |
|---|---|---|---|
| dry_run | No | If true, preview changes without writing |
| Name | Required | Description |
|---|---|---|
| dry_run | No | |
| decay_updates | No | Entities whose decay score was updated |
| links_created | No | Auto-links created during cohere |
| archived_entities | No | Entities archived (cohere + compact) |
| promoted_entities | No | Entities promoted during cohere |
| db_size_delta_bytes | No | Change in SQLite file size in bytes |
| compact_archived_count | No | Entities archived during compact step |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, and the description elaborates on the specific operations (promote, link, archive, recalculate decay) and the atomicity of the pass. It provides behavior beyond annotations, though it could detail what gets archived or destroyed more precisely.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct sentences: the first states the action and steps, the second provides the dry_run option. No wasted words, front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the composite nature of the tool and the presence of an output schema, the description adequately covers the operation, steps, atomicity, and dry_run feature. It provides sufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers the single dry_run parameter (100% coverage). The description reinforces its purpose but adds little new meaning beyond the schema's description. Baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs a full atomic grooming pass consisting of cohere, decay, and compact steps, and returns a summary report. This distinguishes it from sibling tools that operate individually (e.g., mimir_cohere, mimir_decay, mimir_compact).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It mentions using dry_run=true to preview without changes, offering conditional guidance. However, it does not explicitly state when to use this composite tool versus running the individual steps separately, leaving some ambiguity for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a performance benchmark data point. Tracks task metrics (turns taken, tokens used, success) alongside whether memory recall was used — enabling measurement of Mimir's impact on agent performance. Aggregate with mimir_recall to analyze trends.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Tags for categorization | |
| session_id | No | Session identifier for traceability | |
| tokens_used | Yes | Total tokens consumed by the task | |
| turns_taken | Yes | Number of conversation turns the task took | |
| recall_count | No | How many times memory was recalled during this task | |
| task_success | No | Whether the task completed successfully | |
| task_description | Yes | Description of the task being measured | |
| memory_recall_used | Yes | Whether memory recall (mimir_recall) was used during this task |
| Name | Required | Description |
|---|---|---|
| entity_id | No | Created benchmark entity ID |
| created_at_unix_ms | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states that the tool records a data point, which aligns with the destructiveHint annotation (modifying state). No contradictions; the annotation handles the behavioral trait, and the description adds the context of what is recorded. However, it does not disclose additional side effects like persistence or idempotency, which is acceptable given annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences (40 words), front-loaded with the action verb 'Record', and contains no redundant information. Every sentence adds value: the first states the primary purpose, the second explains the metrics and relation to mimir_recall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 8 parameters (4 required) and an output schema (not shown), the description covers the core purpose and the relationship to sibling tools. It mentions the metrics being tracked but does not elaborate on the output schema or optional parameters like tags and session_id, which are adequately documented in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds collective meaning by mentioning the key metrics (turns, tokens, success, memory recall) but does not provide new details beyond what the schema offers. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Record' and clearly identifies the resource as a 'performance benchmark data point'. It lists the tracked metrics (turns, tokens, success, memory recall) and explicitly distinguishes from sibling mimir_recall by noting aggregation for trend analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for recording benchmark data to measure Mimir's impact and directs users to aggregate with mimir_recall for analysis. While it does not list exclusions or alternatives beyond mimir_recall, the context is sufficient for an agent to decide when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run an autonomous coherence grooming pass over the memory. Promotes buffer entities to working layer, applies decay, auto-links related entities, and archives stale ones below the decay threshold. Use dry_run=true to preview without making changes.
| Name | Required | Description | Default |
|---|---|---|---|
| dry_run | No | If true, count what would be done without making changes | |
| max_links | No | Maximum auto-links to create (default 20, max 100) | |
| archive_threshold | No | Decay score below which entities are auto-archived (default 0.05) | |
| promote_threshold | No | Retrieval count threshold for buffer to working promotion (default 3) |
| Name | Required | Description |
|---|---|---|
| linked | No | Number of auto-links created |
| decayed | No | Number of entities whose decay score was reduced |
| dry_run | No | |
| archived | No | Number of entities archived due to low decay |
| promoted | No | Number of entities promoted from buffer to working |
| entities_examined | No | Total non-archived entities examined |
| completed_at_unix_ms | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool modifies memory (promotions, decay, auto-links, archives), which aligns with the 'destructiveHint: true' annotation. It adds context beyond the annotation by specifying what changes occur, though it could mention potential side-effects more explicitly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first clearly defines purpose and actions, the second adds a practical tip. No extraneous information, highly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and 100% schema description coverage, the description adequately covers the tool's behavior, parameters, and usage. It lacks nothing essential for an autonomous grooming pass.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 4 parameters with descriptions (100% coverage). The description adds only a minor hint about dry_run. Baseline 3 is appropriate since the schema already provides adequate parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Run an autonomous coherence grooming pass over the memory.' It lists specific actions (promotes buffer entities, applies decay, auto-links, archives) that distinguish it from siblings like mimir_compact, mimir_decay, or mimir_prune.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage hint: 'Use dry_run=true to preview without making changes.' It implies the tool is for grooming memory but does not explicitly compare to alternatives or state when not to use it. This is sufficient but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Archive entities whose decay score has fallen below a threshold. Supports dry-run mode to preview without making changes. Run periodically or threshold-triggered to keep the database focused on active, high-value memories.
| Name | Required | Description | Default |
|---|---|---|---|
| dry_run | No | If true, report what would be archived without making changes | |
| min_decay | No | Decay threshold — entities with decay score below this are archived |
| Name | Required | Description |
|---|---|---|
| dry_run | No | Whether this was a dry run |
| entities_archived | No | Number of entities actually archived (0 in dry-run mode) |
| entities_examined | No | Number of entities checked |
| completed_at_unix_ms | No | Completion timestamp |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description confirms destructive behavior via 'archive', aligning with the destructiveHint annotation. It adds the dry-run behavioral trait but does not disclose what archiving entails (e.g., reversibility, data loss). More transparency about consequences would improve this score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states purpose and dry-run support, second suggests usage pattern. No redundant words or fluff; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of output schema (not shown but indicated), the description covers the core action and usage pattern adequately. It could detail consequences of archiving (e.g., recoverability), but overall it is sufficiently complete for a tool with well-documented parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with clear explanations for both parameters ('dry_run' and 'min_decay'). The tool description does not add new meaning beyond reiterating the decay threshold and dry-run mode, so value is marginal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Archive' and the resource 'entities whose decay score has fallen below a threshold'. It specifies the dry-run mode and mentions periodic/threshold-triggered usage, distinguishing it from sibling tools like mimir_prune or mimir_purge.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises to run 'periodically or threshold-triggered' and mentions dry-run mode for previewing. It does not explicitly state when not to use this tool or list alternatives, but the given context is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detect conflicting entities in the same category — pairs with low trigram similarity in their body_json. Flags potential contradictions, duplicate-but-divergent entries, and stale-overwritten facts. Read-only by default. Opt in with resolve=true to actively invalidate the lower-certainty side of clear conflicts (superseding it into history, reversible + time-travelable via mimir_as_of); that path defaults to dry_run=true so you preview first, and never resolves pairs whose certainties are within certainty_margin.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of conflicts to return / resolve | |
| offset | No | Number of entities to skip for pagination | |
| dry_run | No | When resolve=true, only report what would be invalidated unless set false | |
| resolve | No | Opt-in: invalidate the lower-certainty side of clear conflicts instead of only reporting them | |
| category | Yes | Category to scan for conflicts | general |
| threshold | No | Similarity threshold — pairs below this are flagged as conflicts | |
| certainty_margin | No | Minimum certainty gap to auto-resolve; closer pairs are skipped as ambiguous |
| Name | Required | Description |
|---|---|---|
| conflicts | No | Conflict pairs with similarity scores (detection mode) |
| invalidations | No | Winner/loser pairs invalidated or previewed (resolve mode) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Contradiction: description claims 'Read-only by default' but annotations set readOnlyHint=false, indicating the tool may cause side effects. This inconsistency undermines transparency. Otherwise, description explains behavior well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with main purpose upfront, then details on resolve mode. A bit lengthy but each sentence adds value. Could be slightly more concise, but still effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive for a complex tool with 7 parameters and output schema. Covers both detection and resolution, safety mechanisms, and parameter behavior. No gaps for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 7 parameters have descriptions in schema (100% coverage). Description adds value by explaining how parameters interact (e.g., dry_run with resolve, certainty_margin for ambiguity) and the trigram similarity context for threshold.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool detects conflicting entities in the same category using trigram similarity on body_json. It distinguishes itself by offering both read-only detection and optional conflict resolution, specifying the exact purpose and key actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage context: read-only by default, opt-in with resolve=true, dry_run preview, and certainty_margin to avoid ambiguous resolutions. Could explicitly state when not to use, but still strong guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a pre-formatted markdown context block of the most important entities for session injection. The downstream system (Perseus) uses this to pre-load AI agent context with relevant memories before work begins.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of entities to include in the context block | |
| categories | No | Categories to include. Empty array = all categories. |
| Name | Required | Description |
|---|---|---|
| markdown | No | Markdown-formatted context block with entity details |
| total_chars | No | Character count of the markdown content |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds behavioral context by specifying the output is pre-formatted markdown and the downstream use case. It does not contradict annotations and provides useful information beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core purpose, and every word adds value. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of a full input schema (100% coverage), an output schema, and readOnlyHint annotation, the description is sufficient. It explains the output format and use case, but could optionally include details about the structure of the markdown or how 'most important entities' are determined.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for both parameters (limit and categories). The description does not add additional meaning beyond what the schema already provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a pre-formatted markdown context block of important entities for session injection, naming the downstream system Perseus. It is specific about the verb (return) and resource (context block), and the purpose is distinct from sibling tools like mimir_recall.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for pre-loading AI agent context before work begins (session injection). However, it does not explicitly state when to avoid using this tool or mention alternatives among the many sibling mimir tools. The guidance is adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture a user correction to the agent. Stores what went wrong, what the user said, and the lesson learned — as both a 'correction' entity and a journal entry. Use this every time the user corrects your approach. Enables the self-improving feedback loop: the agent learns from mistakes across sessions.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Tags for categorization | |
| category | No | Entity category (default: 'correction') | correction |
| session_id | No | Session identifier for traceability | |
| visibility | No | Visibility: 'private', 'workspace', or 'public' | workspace |
| task_context | Yes | What task was being attempted when the correction occurred | |
| wrong_approach | Yes | What the agent did that was wrong (the mistaken approach) | |
| user_correction | Yes | What the user said to correct the agent (the right way) |
| Name | Required | Description |
|---|---|---|
| key | No | |
| category | No | |
| entity_id | No | Created correction entity ID |
| journal_id | No | Created journal entry ID |
| created_at_unix_ms | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations give destructiveHint: true, which the description aligns with by stating it stores entities. The description adds value beyond annotations by explaining the dual storage (correction entity and journal entry) and the self-improving feedback loop across sessions. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, front-loading the purpose and usage. Every sentence is informative and necessary: first sentence defines the action and storage, second covers when to use and the learning benefit. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters and an output schema (not shown), the description covers the main action, usage, and outcome. It could mention side effects or prerequisites, but the core functionality is well explained for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well documented. The description reinforces the key parameters (wrong_approach, user_correction, task_context) by naming them in prose, adding context that they capture what went wrong and what the user said.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Capture' and the resource 'user correction'. It distinguishes from siblings like mimir_remember and mimir_journal by specifying it stores corrections, not general facts. The phrase 'Use this every time the user corrects your approach' reinforces the specific purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use the tool: 'every time the user corrects your approach'. It does not explicitly list alternatives or when not to use, but the context implies other tools for other purposes, making it clear enough for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recalculate Ebbinghaus decay scores for all entities based on time since last access. Auto-archives entities that have fully decayed (score < 0.05). Run periodically to keep memory fresh — decayed entities surface less often in recall results.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| auto_archived | No | Entities auto-archived because decay fell below 0.05 |
| entities_checked | No | Total entities evaluated |
| entities_updated | No | Entities whose decay score changed |
| completed_at_unix_ms | No | Completion timestamp |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral detail beyond the destructiveHint annotation by explaining auto-archiving of low-score entities and the effect on recall results. There is no contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently front-load the main action and then provide usage and consequence. Every sentence is valuable, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, clear destructive side effect) and the existence of an output schema, the description covers all necessary aspects: what it does, when to use it, and behavioral outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and 100% schema coverage, the description's baseline is 4. It adds no parameter information because none is needed, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it recalculates Ebbinghaus decay scores and auto-archives fully decayed entities, specifying both the verb and resource. This distinguishes it from sibling tools like mimir_forget or mimir_purge by its specific decay recalculation purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises running periodically to keep memory fresh, providing clear usage context. However, it does not explicitly exclude use cases or compare alternatives among siblings, so guidance is good but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate and store dense vector embeddings for entities via Ollama /api/embed. Supports single entity (category+key) or batch mode (batch_category). Requires --llm-endpoint to be set.
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Entity key for single mode | |
| text | No | Text to embed (omit to use entity body_json) | |
| category | No | Entity category for single mode | |
| batch_limit | No | Max entities in batch mode | |
| batch_category | No | Embed all entities in this category lacking embeddings |
| Name | Required | Description |
|---|---|---|
| embedded | No | Number of entities embedded |
| dimensions | No | Vector dimensions |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, so the description's addition of 'Generate and store' and the dependency on Ollama adds some context. But it doesn't detail what gets overwritten or the exact side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that front-load the purpose and then detail modes and requirements. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 optional parameters and an output schema, the description covers operation modes and prerequisites. It doesn't describe return values, but the output schema likely handles that. It's mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description adds minimal value beyond the overview of modes. It reiterates the mode logic but doesn't enhance parameter understanding significantly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it generates and stores dense vector embeddings for entities, distinguishes between single and batch modes, and mentions the Ollama endpoint. This differentiates it from sibling tools like mimir_recall or mimir_remember.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains when to use single mode (category+key) vs batch mode (batch_category) and notes the requirement for --llm-endpoint. However, it lacks explicit exclusions or alternatives, so it's not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract structured knowledge — facts, preferences, temporal events, episodes — from raw text or a stored entity, using a fully local, deterministic rule-based extractor (no cloud LLM, no embedding/API call, no network). Read-only: never writes to the store. Provide text, or category + key to extract from a stored entity.
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Key of a stored entity to extract from (requires category). | |
| text | No | Raw text to extract from. If omitted, category + key of a stored entity are used. | |
| category | No | Category of a stored entity to extract from (requires key). | |
| strategy | No | Extractor strategy: 'rule_based' (local heuristics) or 'none' (no-op). | rule_based |
| Name | Required | Description |
|---|---|---|
| items | No | Extracted items, each an object with `kind` and `text`. |
| total | No | Number of items extracted |
| strategy | No | Extractor strategy used |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=true), description adds 'never writes to the store' and details on deterministic, local, no-network operation. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences, front-loaded with main purpose. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists, description covers inputs, usage, and behavioral traits sufficiently. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 100%, description adds clarification on usage of `text` vs `category`+`key` and explains `strategy` enum values (local heuristics vs no-op). Adds meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'extract' and resource 'structured knowledge' from raw text or stored entity. Distinguishes from siblings by specifying local, deterministic rule-based extractor. No tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains usage options: provide `text` or `category`+`key` directly. Does not explicitly list when not to use or alternatives, but clear context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Federate entities from one workspace to another. Exports entities scoped to from_workspace, remaps their workspace_hash to to_workspace, and imports them — effectively copying or moving knowledge between workspaces. Use this for cross-agent or cross-project knowledge sharing without manual file transfer.
| Name | Required | Description | Default |
|---|---|---|---|
| vault_dir | No | Temporary vault directory for the intermediate .md export files | /tmp/mimir-federate |
| to_workspace | Yes | Target workspace hash to import entities into | |
| from_workspace | Yes | Source workspace hash to export entities from |
| Name | Required | Description |
|---|---|---|
| exported | No | Number of entities exported from the source workspace |
| imported | No | Number of entities imported into the target workspace |
| remapped | No | Number of entities whose workspace_hash was remapped |
| import_errors | No | Any errors encountered during import |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide destructiveHint: true, so description doesn't need to repeat that, but the description says 'copying or moving' without clarifying whether source entities are preserved. No mention of authorization or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: purpose, mechanism, use case. Front-loaded with action verb. No unnecessary words. Efficient and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists and parameter coverage is high. However, the tool involves data transfer and potential destructiveness; the description should clarify what happens to source entities and handling of duplicates. Lacks these details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good parameter descriptions. The tool description reiterates the purpose of each parameter without adding new details beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it federates entities between workspaces via export, remap, import. It distinguishes from manual file transfer but does not explicitly name sibling tools like mimir_vault_export/import or mimir_share, though the usage hint helps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this for cross-agent or cross-project knowledge sharing without manual file transfer', indicating when to use. Lacks explicit when-not-to-use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Soft-delete an entity by setting archived=1. The entity is hidden from queries but recoverable. Use this to clean up stale or incorrect facts without permanent data loss.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Entity key to archive | |
| reason | No | Reason for archiving, logged for audit trail | |
| category | Yes | Entity category to archive |
| Name | Required | Description |
|---|---|---|
| key | No | Entity key |
| found | No | Whether the entity was found and archived |
| category | No | Entity category |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description adds that it is a soft-delete (recoverable) and that the entity becomes hidden from queries. This provides useful behavioral context that annotations alone do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the key action and effect. Every sentence adds value: the first explains what it does, the second when to use it. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, presence of an output schema, and full schema parameter descriptions, the description adequately covers purpose, behavior, and usage context. It is sufficient for an agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already includes descriptions for all three parameters. The description adds no additional meaning beyond what the schema provides, meeting the baseline for this score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('soft-delete an entity'), the mechanism ('setting archived=1'), and the effect ('hidden from queries but recoverable'). It implies a contrast with permanent deletion tools like purging, distinguishing its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use it to 'clean up stale or incorrect facts without permanent data loss,' providing clear context. It does not, however, mention when not to use it or list alternative sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get an entity by ID with its full body_json content. Use after mimir_recall with preview_cap to read the complete body of a truncated result. The drill-down footer embedded in preview-capped results references this tool with the entity ID to use.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Entity ID to retrieve (from recall result id field or preview cap footer) |
| Name | Required | Description |
|---|---|---|
| id | No | |
| key | No | |
| layer | No | |
| status | No | |
| category | No | |
| always_on | No | |
| body_json | No | Full entity body content |
| certainty | No | |
| decay_score | No | |
| entity_type | No | |
| retrieval_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with the readOnlyHint annotation by stating 'Get an entity'. It adds behavioral context that the tool retrieves full body_json content, which is beyond what the annotation provides. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each providing essential information: purpose, usage recommendation, and parameter source. It is efficient with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, output schema present), the description fully covers purpose, usage context, and parameter explanation. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 100%, so baseline is 3. The description adds extra context by explaining that the ID comes from a recall result or preview cap footer, which goes beyond the schema description alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get an entity by ID with its full body_json content', using a specific verb and resource, and distinguishes it from the sibling tool mimir_recall which returns preview-capped results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use after mimir_recall with preview_cap to read the complete body of a truncated result', providing clear context for when to use this tool, though it does not explicitly mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether the Mimir server and its SQLite database are healthy. Returns a simple healthy/unhealthy status. Use this for health checks and monitoring, not for detailed stats (use mimir_stats).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| status | No | Server health status |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. Description adds that it checks server and DB, and returns simple status, which is useful context but doesn't go beyond what's expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words, front-loaded with purpose and usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Fully covers what the tool does, when to use it, and what it returns. Output schema exists, so no need to detail return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; baseline 4 applies as description doesn't need to add parameter info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb (check), resource (Mimir server and its SQLite database), and output (healthy/unhealthy). Distinguishes from sibling mimir_stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use for health checks and monitoring, and not for detailed stats, naming the alternative tool mimir_stats.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sync external data connectors (GitHub issues, file watcher) into Mimir. Call with no arguments to run all enabled connectors, or specify a connector name to run only that one. Use dry_run=true to preview without storing.
| Name | Required | Description | Default |
|---|---|---|---|
| dry_run | No | Preview documents without storing them | |
| connector | No | Specific connector to run (omit for all enabled) |
| Name | Required | Description |
|---|---|---|
| errors | No | Error messages from connectors that failed |
| dry_run | No | Whether this was a dry run |
| ingested | No | Number of documents ingested (or would be ingested in dry run) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint: true, indicating mutation. The description adds context about preview mode (dry_run) and connector selection, but does not detail potential side effects like overwriting or merging behavior, which would be useful. Overall, it adds some value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two sentences), front-loads the main purpose, and avoids any unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With annotations and output schema present, the description adequately covers the tool's purpose, invocation patterns, and preview capability. It does not explain the exact behavior of syncing (e.g., upsert vs replace), but that is likely implied by the tool's name and common patterns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description reiterates the dry_run and connector usage but does not add significant new semantic information beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool syncs external data connectors (GitHub issues, file watcher) into Mimir, distinguishing it from many sibling tools that are about querying, managing, or modifying Mimir data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to call with no arguments (run all enabled connectors) and when to specify a connector, and mentions dry_run for preview. It does not explicitly discuss when not to use it or alternatives, but the context is sufficient for an AI agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ingest a document file into memory by extracting its text LOCALLY (no cloud, no network). Plaintext/markdown/structured-text work in any build; DOCX and PDF require a binary built with --features multimodal (otherwise a clear error is returned). The extracted text is stored as a normal entity (recallable via mimir_recall). category defaults to 'document', key defaults to the file name.
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Entity key (default: the file name) | |
| path | Yes | Path to the document file to ingest | |
| tags | No | Optional tags | |
| category | No | Entity category (default 'document') |
| Name | Required | Description |
|---|---|---|
| id | No | Stored entity id |
| key | No | |
| chars | No | Characters of text extracted |
| action | No | created or updated |
| category | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors beyond the destructiveHint annotation: it is local-only ('no cloud, no network'), describes format support (plaintext/markdown/structured-text work always, DOCX/PDF require a feature flag), and explains that extracted text is stored as a normal entity recallable via mimir_recall. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact (three sentences) and front-loaded with the core action. Every sentence adds essential information: what it does, where it runs, format quirks, defaults, and recall mechanism. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (format-dependent behavior, local processing, default values), the description covers all necessary aspects: processing location, format support with fallback, default values, and integration with recall. The presence of an output schema is noted but not required for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds valuable defaults: key defaults to file name, category defaults to 'document'. This enriches the schema-defined parameters. The description also implies that path is the primary parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool ingests a document file into memory by extracting text locally. It specifies the verb 'Ingest', the resource 'document file', and the scope (local extraction, no cloud/network). It distinguishes from siblings like mimir_ingest (general ingest) by focusing on file-based ingestion with local text extraction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use the tool (ingesting document files) and mentions limitations (DOCX/PDF require --features multimodal, otherwise error). It does not explicitly list when not to use, but the context is sufficient. It implies an alternative (mimir_recall for retrieval) but does not contrast with other ingest tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append a structured decision/observation log entry. Uses evaluated/acted/forward pattern: what was considered, what was done, and what happens next. Essential for audit trails and timeline reconstruction.
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Related entity key for linking | |
| acted | No | What action was taken and why | |
| forward | No | What the plan is going forward | |
| agent_id | No | Agent identity (v1.2.0). Records which agent created this journal event. | |
| category | No | Related entity category for linking | |
| entity_id | No | Related entity ID for linking | |
| evaluated | No | What was evaluated: options considered, context, constraints | |
| event_type | No | Event type: 'decision', 'observation', 'action', 'error' | decision |
| Name | Required | Description |
|---|---|---|
| id | No | Journal event ID |
| event_type | No | Event type recorded |
| created_at_unix_ms | No | Creation timestamp in unix milliseconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint: true, suggesting the tool may have destructive side effects, but the description only says 'Append,' which implies additive behavior. No explanation of why it's destructive, what gets destroyed, or other behavioral traits beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: the first states the purpose, the second explains the pattern. No superfluous content. Front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (not shown but present), the description does not need to explain return values. Parameter count is 8, all described in schema and enriched by pattern explanation. The description is complete for a logging tool with clear audit trail purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 8 parameters. The description adds value by explaining the 'evaluated/acted/forward' pattern, which provides context for how parameters like 'evaluated', 'acted', and 'forward' relate to each other, enriching the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Append a structured decision/observation log entry.' It uses specific verbs ('append', 'log') and names the resource ('decision/observation log entry'). Sibling tools like mimir_recall and mimir_context are differentiated by this logging focus.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'essential for audit trails and timeline reconstruction' but does not explicitly state when to use this tool versus alternatives (e.g., mimir_recall for retrieval, mimir_context for context). No exclusions or alternative suggestions are provided, leaving ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a relationship link from one entity to another. Builds a knowledge graph that mimir_traverse can walk. Use 'depends_on', 'implements', 'extends', 'references', or custom relationships.
| Name | Required | Description | Default |
|---|---|---|---|
| to_id | Yes | Target entity ID (from mimir_remember return value) | |
| from_key | Yes | Source entity key | |
| relationship | No | Relationship type: 'depends_on', 'implements', 'extends', 'references', or custom | related |
| from_category | Yes | Source entity category |
| Name | Required | Description |
|---|---|---|
| to | No | Target entity ID |
| from | No | Source as 'category/key' |
| success | No | |
| relationship | No | Relationship type set |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description confirms the link creation is destructive (as per destructiveHint) but adds no further behavioral context beyond building a graph. Since annotations already flag destructiveness, the description provides marginal added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, front-loading the key action and purpose. Every sentence adds necessary context without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters and an output schema. The description covers the core functionality and relationship types, but omits prerequisites (e.g., entities must exist) and potential side effects. Given the output schema exists, the gap is moderate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already documented. The description mentions relationship types, which are also in the schema's 'relationship' parameter description. Thus, no significant extra meaning is added beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') and resource ('relationship link from one entity to another'), clearly stating the purpose. It distinguishes from sibling tools like mimir_unlink and mimir_traverse by explaining that it builds a knowledge graph for traversal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists allowed relationship types ('depends_on', 'implements', 'extends', 'references', or custom) and connects it to mimir_traverse. While it doesn't state when not to use, the sibling name mimir_unlink implies the complementary operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Database maintenance operations: deduplicate entities with identical (category, key), detect orphan journal entries and links, vacuum (reclaim disk space), reindex FTS5. Set dry_run=true to preview. Use 'all' to run everything.
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | Run all maintenance operations (dedup, orphans, vacuum, reindex) | |
| dedup | No | Find duplicate (category, key) entities and archive the oldest | |
| vacuum | No | Run SQLite VACUUM to reclaim disk space | |
| dry_run | No | If true, preview changes without writing | |
| orphans | No | Detect journal entries and links pointing to non-existent entities | |
| reindex | No | Rebuild the FTS5 search index from entities table |
| Name | Required | Description |
|---|---|---|
| errors | No | Errors encountered during maintenance |
| dry_run | No | |
| dedup_archived | No | Number of duplicate entities archived |
| orphan_links_found | No | Orphan links detected |
| reindex_rows_affected | No | Rows reindexed into FTS5 |
| vacuum_reclaimed_bytes | No | Disk space reclaimed by VACUUM |
| orphan_journal_entries_found | No | Orphan journal entries detected |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that deduplication archives the oldest entity, vacuum reclaims disk space, and reindex rebuilds FTS5. It also mentions dry_run for preview. This adds detail beyond the 'destructiveHint' annotation, though it does not specify whether orphan detection deletes or only lists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first immediately states the tool's purpose and lists operations, the second gives actionable usage tips. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a maintenance tool with 6 boolean parameters and an output schema, the description covers the key operations and gives usage hints. It doesn't mention prerequisites or safety notes, but the destructiveHint annotation and dry_run option partially address that. Overall, it is sufficient for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, each parameter already has a description. The description adds value by showing how to combine parameters (dry_run with all) and the general usage pattern, providing context beyond the schema's individual definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly lists the specific maintenance operations (deduplicate, detect orphans, vacuum, reindex) and states it covers database maintenance. This clearly distinguishes it from sibling tools like mimir_ask or mimir_compact by its domain and actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives basic usage tips (dry_run=true to preview, use 'all' to run everything) but does not explain when to prefer this tool over individual siblings like mimir_prune or mimir_reindex. There is no explicit when-not or alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Migrate a v0.1.x Mimir database to the current v0.5.0 schema. Reads the old database, converts memories to the entity model, and merges into the current database. Use this once per legacy database during upgrade.
| Name | Required | Description | Default |
|---|---|---|---|
| from_path | Yes | Absolute path to the v0.1.x SQLite database file to migrate |
| Name | Required | Description |
|---|---|---|
| errors | No | Any errors encountered during migration |
| entities_created | No | New entities created from old memories |
| entities_updated | No | Existing entities updated during merge |
| total_old_memories | No | Number of memories found in the old database |
| completed_at_unix_ms | No | Completion timestamp |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the process (reads old DB, converts, merges) adding behavioral context beyond the destructiveHint annotation, confirming it modifies the current database.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the main action without any extraneous words, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description covers purpose, process, and usage comprehensively for a one-time migration tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage and only one parameter fully described in the schema, the description adds no additional parameter meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool migrates a v0.1.x Mimir database to v0.5.0 schema, distinguishing it from siblings that perform other operations like ask or forget.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use this once per legacy database during upgrade' provides explicit when-to-use context, but no exclusions or alternatives are mentioned, which is acceptable given the one-time migration nature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bulk archive entities by category, decay threshold, or age. Use dry_run=true to preview without archiving. Useful for cleaning stale or low-quality memories.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max entities to prune (0 = unlimited) | |
| dry_run | No | Preview without archiving | |
| category | No | Archive entities in this category | |
| min_decay | No | Archive entities with decay_score below this threshold | |
| older_than_days | No | Archive entities older than this many days |
| Name | Required | Description |
|---|---|---|
| reason | No | |
| dry_run | No | |
| archived | No | |
| examined | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide destructiveHint=true; description adds that dry_run allows preview and mentions cleaning purpose, but does not detail what 'archive' entails (e.g., reversibility, side effects) or how entities are affected beyond filtering criteria.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states action and criteria, second provides a tip and use case. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters, destructive behavior, and an output schema, the description covers core action and a preview tip but omits behavioral details (e.g., what 'archive' means, error handling, or output format). Output schema exists, so return values need not be explained, but other gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with descriptions for all parameters. Description adds context for dry_run and relates cleaning to decay/age, but this is minimal beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it bulk archives entities by category, decay threshold, or age, with the verb 'archive' and resource 'entities'. It hints at cleaning stale memories but does not explicitly distinguish from siblings like mimir_forget or mimir_purge.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance to use dry_run=true for preview and states it's useful for cleaning stale memories, but lacks explicit when-not-to-use or alternative sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete all archived entities and run VACUUM to reclaim disk space. This is the only operation that actually removes entities — prune/forget only soft-archive. Archived entities are DELETED and NOT RECOVERABLE. Supports dry_run=true to preview first.
| Name | Required | Description | Default |
|---|---|---|---|
| dry_run | No | If true, report what would be deleted without making changes |
| Name | Required | Description |
|---|---|---|
| dry_run | No | Whether this was a dry run |
| bytes_freed | No | Bytes reclaimed after VACUUM (0 in dry-run mode) |
| entities_deleted | No | Number of archived entities permanently deleted |
| completed_at_unix_ms | No | Completion timestamp |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description explicitly states that archived entities are deleted and NOT RECOVERABLE, and that VACUUM is performed. This adds crucial behavioral context not captured by annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences convey the core action, context, sibling differentiation, and parameter hint. No wasted words; front-loaded with the primary function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema covers return values, the description fully addresses what the tool does, side effects (irreversibility), comparison to siblings, and parameter usage. Complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds value by explaining that dry_run=true allows preview without changes, which clarifies the parameter's purpose beyond its schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: permanently delete archived entities and run VACUUM. It distinguishes from sibling tools (prune/forget) by specifying that it is the only operation that actually removes entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that this tool is for permanent deletion versus soft-archive from prune/forget, and mentions dry_run preview. It does not explicitly state prerequisites or when not to use, but the contrast with siblings provides sufficient guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search entities with FTS5 keyword search. Words are OR'd together. Returns entities sorted by relevance with expanded content/summary fields at top level. Use this to find previously stored facts, decisions, or architecture notes. When encryption is enabled, body_json is decrypted transparently.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Search mode: 'fts5' (keyword), 'dense' (vector), or 'hybrid' (fused via RRF) | fts5 |
| type | No | Filter by entity type, e.g. 'insight' or 'reference' | |
| limit | No | Maximum number of results to return (max 1000) | |
| query | Yes | Search query — words are OR'd together for broad recall | |
| offset | No | Number of results to skip for pagination | |
| agent_id | No | Agent identity filter (v1.2.0). When set, only entities with a matching agent_id are returned. Omit for no agent filtering. | |
| category | No | Filter by category, e.g. 'decision' or 'architecture' | |
| expansion | No | Configuration for FTS5 query expansion using Porter stemming | |
| min_decay | No | Minimum decay score threshold 0.0–1.0 — higher values return fresher results | |
| topic_path | No | Filter by topic path prefix, e.g. 'architecture/' | |
| preview_cap | No | If set, truncate body_json at N chars and append drill-down footer. Use mimir_get_entity to read full body. | |
| trust_weight | No | Additive boost for provenance/trust (default 0.15, on by default) — verified sources rank above unverified AI drafts on the same topic. Verified entities get the full boost; unverified ones are scaled by certainty. Set 0 to disable. Never penalizes. | |
| content_weight | No | Additive boost for content witness — rewards entities whose body text literally contains query terms. Damped by body length. Never penalizes. | |
| workspace_hash | No | Workspace scope filter (v1.2.0). When set, only entities with a matching workspace_hash are returned. Omit for no workspace filtering. | |
| include_archived | No | Include archived (soft-deleted) entities in results | |
| diversity_halving | No | Per-keyword diversity quota factor (1.0=disabled). Each distinct matched keyword gets ceil(N x halving^n) slots — first keyword N, second N/2, etc. | |
| recency_half_life_secs | No | Time-aware ranking for mode='hybrid' (default off). When set, each fused result's score is multiplied by 0.5^(age / this), where age is seconds since the memory was created — so a memory this many seconds old keeps half its weight and recent context outranks older but similar hits. Omit for relevance-only ranking. |
| Name | Required | Description |
|---|---|---|
| items | No | Matching entities with expanded body_json fields at top level |
| total | No | Number of results returned |
| variants | No | Number of query variants used when expansion is enabled |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true; description adds valuable behavioral details: OR'ing of words, relevance sorting, expanded fields, and transparent decryption of body_json, which is beyond what annotations offer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with key information, no fluff. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite a complex tool with 17 parameters and output schema, the description omits mention of search modes (fts5, dense, hybrid) and filtering capabilities, leaving gaps for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter already described; the tool description adds no extra meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it searches entities with FTS5 keyword search, but does not explicitly differentiate from sibling tools that may offer alternative search methods like vector or hybrid.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides use cases (find facts, decisions, architecture notes) but lacks explicit guidance on when not to use or when alternatives like mimir_recall_when might be better.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search entities whose recall_when triggers match a given context. Use this for proactive just-in-time memory injection — before writing code, before plans, at session start. Pass the current task description as context and get back memories that declared they should be recalled in similar situations.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum entities to return (default 10, max 100) | |
| context | Yes | The current task or context description to match against recall_when triggers |
| Name | Required | Description |
|---|---|---|
| items | No | |
| total | No | |
| context | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is clear. The description adds behavioral context (proactive, context-matching) but does not detail edge cases (e.g., no match behavior, performance). With annotations covering the main safety aspect, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence defines the function, the second gives concrete usage scenarios. Front-loads key information efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (2 params, output schema present), the description covers purpose, usage, and context. With output schema, return details are not needed. Some might expect a note on default limit, but schema covers that. Score 4 reflects slight gap in explaining the 'recall_when trigger' concept.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are documented. The description adds minimal extra meaning beyond the schema: it reinforces that 'context' is the task description to match triggers. This is marginal improvement, hence baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches entities based on recall_when triggers matching a given context. It uses specific verb and resource ('Search entities whose recall_when triggers match') and distinguishes from sibling tools like mimir_recall by focusing on trigger-based recall.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use: 'for proactive just-in-time memory injection — before writing code, before plans, at session start.' It implies usage context but does not explicitly mention when not to use or name alternatives like mimir_recall.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rebuild the FTS5 search index from the entities table. Repairs index drift — e.g. after a direct SQLite write, an interrupted archive, or a legacy database written before the atomic prune/forget fixes — so archived entities stop surfacing in recall/search. Returns the number of entities reindexed.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| reindexed | No | Number of non-archived entities indexed into FTS5 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true. The description adds the return value (number reindexed) and specific triggers, but does not disclose other behavioral traits like potential locking, idempotency, or performance impact, which would be helpful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence states the action, the second provides context and return. Efficiently front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with destructive hint and output schema, the description covers purpose, triggers, and return. Could mention whether it is safe to run repeatedly, but overall sufficient given low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so no parameter documentation is needed. Baseline is 4 for zero-parameter tools, and the description does not need to add parameter info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool rebuilds the FTS5 search index, with specific triggers like direct SQLite writes or interrupted archives. It distinguishes from siblings by focusing on index drift repair for recall/search, though it could explicitly contrast with other maintenance tools like mimir_compact.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists when to use the tool (after direct SQLite write, interrupted archive, legacy database). It does not provide when-not-to-use or alternatives, but the context is sufficiently clear for the intended use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store or update an entity by (category, key). Idempotent — call as often as you want, same key returns an update. Optional always_on=true injects entity into every mimir_context. Optional certainty (0.0-1.0) is used by mimir_conflicts for typed-entity conflict detection. Use this for saving facts, decisions, architecture notes, and conventions. When encryption is enabled, body_json is encrypted at rest with AES-256-GCM.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Unique key within the category, e.g. 'use-postgres-16' or 'deployment-strategy' | |
| tags | No | Tags for categorization and cross-referencing | |
| type | No | Entity type: 'insight', 'architecture', 'decision', 'reference', 'convention' | insight |
| status | No | Entity status: 'active', 'draft', 'deprecated' | active |
| agent_id | No | Agent identity (v1.2.0). Tracks which agent wrote this entity. Used for agent attribution and context filtering. | |
| category | Yes | Entity category: 'decision', 'architecture', 'convention', 'insight', or custom | |
| body_json | Yes | JSON object with the entity body — store content, summary, and any custom fields here | |
| importance | No | Initial importance 0.0–1.0 — sets the starting decay score | |
| topic_path | No | Hierarchical topic path, e.g. 'architecture/database/postgres' | |
| workspace_hash | No | Workspace scope identifier (v1.2.0). Empty = global. Entities with a workspace_hash are invisible to recall queries scoped to a different workspace. |
| Name | Required | Description |
|---|---|---|
| id | No | Entity ID, e.g. 'mem-a1b2c3d4e5f6' |
| key | No | Entity key |
| action | No | 'created' for new entities, 'updated' for existing ones |
| category | No | Entity category |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral details beyond the annotations: idempotency, encryption at rest (AES-256-GCM) when enabled, and the effect of always_on=true injecting into mimir_context. This complements the destructiveHint annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of four clear sentences. It front-loads the core function and immediately follows with key behaviors and use cases. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (10 parameters, 3 required), the description covers essential aspects: idempotency, encryption, always_on, certainty usage, and appropriate use cases. An output schema exists, so return values need not be described. It could mention behavior on conflict or error, but overall it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so the schema already documents all parameters. The description adds context for key parameters (e.g., key as unique within category, body_json as JSON object) and explains the purpose of optional fields like always_on and certainty. It does not cover every parameter in detail but provides meaningful usage guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Store or update an entity by (category, key)' and lists specific use cases such as saving facts, decisions, architecture notes, and conventions. This distinguishes it from sibling retrieval or deletion tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions when to use the tool ('for saving facts, decisions, architecture notes, and conventions') and describes optional parameters like always_on and certainty. However, it does not explicitly state when not to use it or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Assign a quality score (0.0–1.0) to an entity. Verified entities with high scores resist decay and rank higher in recall results. Use this to mark entities as accurate, verified, or deprecated.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Entity key to score | |
| score | Yes | Quality score 0.0–1.0. 1.0 = verified, 0.5 = neutral, 0.0 = low quality | |
| category | Yes | Entity category to score |
| Name | Required | Description |
|---|---|---|
| key | No | Entity key |
| found | No | Whether the entity was found |
| score | No | Quality score assigned |
| category | No | Entity category |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true. The description adds that high scores resist decay and rank higher, but lacks details on idempotency, reversibility, or required permissions. The behavioral context is sufficient but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the action and followed by consequences. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple scoring tool, the description covers purpose, effect, and usage. It does not explain the output format, but an output schema exists. It could mention prerequisites or error cases, but overall it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%. The description does not add new meaning beyond what the schema provides for the three parameters. The baseline of 3 is appropriate as the schema already documents parameters clearly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Assign', the resource 'entity', and the score range 0.0-1.0. It explains the effect on decay and recall ranking, and lists usage scenarios (mark as accurate, verified, deprecated). This distinguishes it well from the many sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use the tool (to assign quality scores and mark entities) and hints at the consequences. However, it does not explicitly state when not to use it or compare to alternatives, which would further improve clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a state entry by key. Permanent removal — unlike mimir_forget which is a soft-delete. Use this to clean up expired or unused state entries.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | State key to permanently delete |
| Name | Required | Description |
|---|---|---|
| key | No | Key that was deleted |
| found | No | Whether the key existed and was deleted |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, indicating the tool is destructive. The description adds that deletion is permanent and contrasts with soft-delete, providing useful context beyond the annotation. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each serving a distinct purpose: first states the action, second adds usage guidance and sibling differentiation. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with an output schema (present), the description adequately covers purpose, usage, and behavioral nuance. It is complete for the agent to correctly select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes the key parameter as 'State key to permanently delete'. The description mentions 'by key' but does not add substantial meaning beyond the schema, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a state entry by key, using a specific verb and resource. It distinguishes from the sibling tool mimir_forget, which is a soft-delete, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use: 'Use this to clean up expired or unused state entries.' Also clarifies when not to use by contrasting with mimir_forget, providing clear context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a state value by key. Returns null if the key has expired or doesn't exist. Use this instead of mimir_recall for transient session state that doesn't need FTS5 search.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | State key to retrieve |
| Name | Required | Description |
|---|---|---|
| key | No | State key requested |
| found | No | Whether the key exists and hasn't expired |
| value | No | JSON value if found |
| created_at_unix_ms | No | Creation timestamp |
| expires_at_unix_ms | No | Expiration timestamp if TTL was set |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds behavioral detail beyond annotations by stating 'Returns null if the key has expired or doesn't exist,' which informs the agent about return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. The description is front-loaded with the action, then provides return behavior and usage guidance, all in a compact form.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, output schema exists), the description covers purpose, null handling, and when to use, which is adequate. A minor gap is no mention of expiration behavior details, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents the 'key' parameter. The description does not add extra meaning beyond what is in the schema, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a state value by key' with a specific verb and resource. It distinguishes itself from the sibling tool mimir_recall by mentioning transient session state and FTS5 search, ensuring no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Use this instead of mimir_recall for transient session state that doesn't need FTS5 search.' This clearly tells the agent when to use this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all state keys, optionally filtered by a key prefix. Use this to discover what state entries exist without knowing exact keys ahead of time.
| Name | Required | Description | Default |
|---|---|---|---|
| prefix | No | Only return keys that start with this prefix |
| Name | Required | Description |
|---|---|---|
| keys | No | Matching state keys |
| total | No | Number of keys returned |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so description adds value by specifying the listing behavior and prefix filtering, but could mention potential limits or pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct sentences: first defines action, second provides use case. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given presence of an output schema and single optional parameter, description is mostly complete; could explicitly state that it returns a list of keys.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a documented prefix parameter; description restates the parameter briefly but adds no new details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists all state keys with optional prefix filtering, distinguishing it from sibling tools like mimir_state_get, mimir_state_set, and mimir_state_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context about when to use (discover state entries without exact keys) but does not explicitly mention when not to use or contrast with alternatives like mimir_state_get.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set a key-value state entry with optional TTL for auto-expiration. Use this for session state, temporary flags, or configuration values that should expire after a set time.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | State key — unique identifier for this state entry | |
| value_json | Yes | JSON value to store | |
| ttl_seconds | No | Time-to-live in seconds. Entry auto-expires and returns null after this duration. Omit for permanent state. |
| Name | Required | Description |
|---|---|---|
| key | No | State key set |
| ttl_seconds | No | TTL that was set, if any |
| expires_at_unix_ms | No | Expiration timestamp in unix milliseconds, if TTL was set |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark destructiveHint=true. Description adds TTL auto-expiration and permanent state option. Does not explicitly mention overwriting behavior, but that is implied by 'Set' and output schema may cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. First sentence states function, second gives usage context. Perfectly compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple setter with 3 parameters. Covers purpose, use cases, and TTL behavior. Output schema likely handles return values. Missing explicit overwriting note, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%. Description reinforces TTL parameter purpose and connects to use cases, adding marginal semantic value beyond schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Set a key-value state entry' with a specific verb and resource. It distinguishes itself from sibling state tools (get, delete, list) by focusing on creation/update with optional TTL.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use cases: session state, temporary flags, configuration values with TTL. Does not specify when not to use or contrast with alternatives like mimir_remember, but the context is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return comprehensive database statistics: entity counts by category, type, and decay layer; journal event count; state entry count; database file size; and date range of stored data.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| by_type | No | Entity counts grouped by type |
| by_layer | No | Entity counts grouped by decay layer (buffer/working/core) |
| by_category | No | Entity counts grouped by category |
| newest_unix_ms | No | Newest entity creation timestamp |
| oldest_unix_ms | No | Oldest entity creation timestamp |
| total_entities | No | Total entities in the database |
| db_file_size_bytes | No | Database file size on disk in bytes |
| total_state_entries | No | Total state entries (including expired) |
| total_journal_events | No | Total journal events recorded |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, which is consistent with the description. The description adds value by detailing exactly what statistics are returned, which goes beyond the annotation's simple read-only indication. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently enumerates all returned statistics without redundancy. It is front-loaded with the main verb and resource, and every phrase adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema exists (as per context signals), the description is complete. It covers all aspects of the output, and the agent can rely on the output schema for detailed structuring.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so the description doesn't need to explain parameters. However, it compensates by describing the output, which is useful for an agent. Baseline for 0 params is 4, and this description meets that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('Return') and clearly lists the types of statistics (entity counts by category, type, decay layer; journal count; state count; file size; date range). It distinguishes itself from sibling tools like 'mimir_health' which likely focuses on system status, whereas this focuses on database content statistics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly states its purpose (obtaining comprehensive stats), and given there are no parameters or configuration, the use case is clear. It doesn't explicitly state when not to use, but the context of sibling tools provides differentiation. A score of 4 is appropriate as it's clear but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a 'supersedes' relationship from a new fact to an old one, setting the old entity's status to 'deprecated'. Use this when a newer entity makes an older one obsolete.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | Reason for superseding (recorded in archive_reason) | |
| to_key | Yes | Key of the NEW entity that supersedes | |
| from_key | Yes | Key of the OLD entity being superseded | |
| to_category | Yes | Category of the NEW entity that supersedes | |
| relationship | No | Link relationship type (default: 'supersedes') | supersedes |
| from_category | Yes | Category of the OLD entity being superseded |
| Name | Required | Description |
|---|---|---|
| relationship | No | |
| to_entity_id | No | ID of the new (superseding) entity |
| to_entity_key | No | |
| from_entity_id | No | ID of the old (superseded) entity |
| status_updated | No | New status of the old entity (always 'deprecated') |
| from_entity_key | No | |
| to_entity_category | No | |
| from_entity_category | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate destructiveHint=true, but the description adds that the old entity's status becomes 'deprecated', which is valuable behavioral context. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Purpose and usage are front-loaded, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description doesn't need to explain return values. It completely covers purpose, effect, and usage for this focused tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline 3. The description does not add extra meaning beyond the schema; the schema already describes each parameter clearly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it creates a 'supersedes' relationship from new to old fact and sets old entity to 'deprecated'. The verb 'Create' and resource 'supersedes relationship' are specific, distinguishing it from generic linking tools like mimir_link.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this when a newer entity makes an older one obsolete.' Provides clear context for when to use. No exclusions or alternatives mentioned, but the sibling tools list includes many others, so this is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
LLM-driven session synthesis. Reviews a session transcript and extracts structured lessons: what worked (success), what failed (failure), what was corrected (correction), what was abandoned (dead_end), and key decisions made (decision). Each lesson becomes an entity linked to a synthesis journal entry. Requires --llm-endpoint to be configured. This is the Perplexity-Brain-style overnight synthesis loop for agent self-improvement.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Tags applied to all synthesized entities | |
| session_id | No | Session identifier for traceability | |
| visibility | No | Visibility for synthesized entities | workspace |
| session_content | Yes | Full session transcript to synthesize lessons from |
| Name | Required | Description |
|---|---|---|
| dry_run | No | |
| lessons | No | Extracted lessons with type, summary, evidence, and confidence |
| journal_id | No | |
| entities_created | No | Number of lesson entities created |
| completed_at_unix_ms | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true. The description adds that the tool creates entities linked to a journal entry, implying state mutation. But it does not detail the extent of destruction (e.g., whether prior entities are overwritten) or other side effects beyond creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences) and front-loads the core purpose. Every sentence adds value: describing the action, the output structure, a prerequisite, and the broader goal. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 params, output schema exists), the description covers the synthesis process and prerequisite. It does not need to explain return values due to output schema. Minor gap: no mention of error conditions or performance implications.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter having a description. The description adds minimal extra meaning beyond listing the lesson types and mention of tags/session_id/visibility in context, but does not significantly enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs 'session synthesis' and extracts specific structured lessons (success, failure, correction, dead_end, decision). It distinguishes itself from sibling tools like mimir_ask or mimir_ingest by focusing on post-session analysis and entity creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It mentions the prerequisite 'Requires --llm-endpoint to be configured' and positions the tool as an 'overnight synthesis loop for agent self-improvement', implying a use case. However, it lacks explicit when-not-to-use or alternatives, leaving interpretation open.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query journal events by time range with optional filters for event type, category, or entity. Use this to reconstruct the decision history and understand what happened when.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of events to return (max 1000) | |
| to_ms | No | End time boundary in unix milliseconds | |
| offset | No | Number of events to skip for pagination | |
| from_ms | No | Start time boundary in unix milliseconds | |
| category | No | Filter by related entity category | |
| entity_id | No | Filter by related entity ID | |
| event_type | No | Filter by event type: 'decision', 'observation', 'action', 'error' |
| Name | Required | Description |
|---|---|---|
| items | No | Journal events matching the query |
| total | No | Number of events returned |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, and the description's 'Query' aligns with that. The description adds context about reconstructing history but does not disclose additional behavioral traits like rate limits or data retention. With annotations present, the description provides marginal extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences that efficiently convey the tool's purpose and recommended use. No superfluous information; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 optional parameters with defaults) and the availability of an output schema, the description covers the core use case. It does not mention pagination or time format details, but the schema handles those. Slight lack of completeness in explaining how filters combine.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description summarizes optional filtering by event type, category, or entity but does not add deeper semantics or syntax details beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Query' and resource 'journal events' with time range and optional filters. It provides a specific use case ('reconstruct decision history') but does not explicitly differentiate from sibling tools like mimir_journal or mimir_recall.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description suggests using the tool to reconstruct decision history, implying a usage context. However, it does not specify when not to use it or mention alternative tools for related queries, leaving room for ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Walk the entity link graph starting from a given entity up to a configurable depth. Returns a chain of linked entities — useful for exploring dependencies, decision trees, and relationship graphs built via mimir_link.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Starting entity key | |
| category | Yes | Starting entity category | |
| max_depth | No | Maximum traversal depth from the starting entity | |
| max_nodes | No | Maximum total nodes to traverse before stopping |
| Name | Required | Description |
|---|---|---|
| entity | Yes | Root entity with its links |
| traversed | Yes | Linked entities traversed from root |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, indicating no side effects. The description adds that the tool walks the graph to a configurable depth and returns a chain of linked entities, which provides additional behavioral context beyond the annotation. It also mentions stopping conditions (max_depth, max_nodes). No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action and result. Every sentence adds value: first sentence describes what the tool does, second gives use cases. No redundancy or unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters and an output schema exists, the description adequately covers the input (starting entity, configurable limits) and purpose (exploring graphs). It omits details about output format but that's acceptable since an output schema is present. Missing explicit mention of dependency on mimir_link, but it's implied in 'relationship graphs built via mimir_link.'
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with descriptions for all 4 parameters. The overall description adds little beyond the schema: it restates that the traversal starts from a given entity and is configurable. Baseline is 3 due to high schema coverage; the description does not significantly enhance parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Walk the entity link graph') and resource ('starting from a given entity'), clearly distinguishing it from siblings like mimir_link (which creates links) and mimir_get_entity (which retrieves a single entity). It also mentions the configurable depth and return type, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the tool is 'useful for exploring dependencies, decision trees, and relationship graphs,' which gives clear context for when to use it. However, it does not explicitly mention when not to use it or direct alternatives, such as using mimir_get_entity for a single node or mimir_link for building the graph first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a relationship link from one entity to another. Use this to correct outdated or incorrect links in the knowledge graph.
| Name | Required | Description | Default |
|---|---|---|---|
| to_id | Yes | Target entity ID to unlink | |
| from_key | Yes | Source entity key | |
| from_category | Yes | Source entity category |
| Name | Required | Description |
|---|---|---|
| to | No | Target entity ID |
| from | No | Source as 'category/key' |
| success | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide destructiveHint=true, so the destructive nature is already known. Description adds the corrective purpose but no additional behavioral details (e.g., side effects, permissions). No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Purpose is front-loaded, followed by usage guidance. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, destructive tool with three required parameters and output schema present, the description provides purpose and usage context. Could be marginally improved by noting typical use cases, but it's complete for most needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters (100% coverage) with descriptions. Description does not add extra meaning beyond telling which is source and target, which can be inferred from the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Remove a relationship link') and the resource ('from one entity to another'), distinguishing it from siblings like mimir_link that likely create links.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use for 'correcting outdated or incorrect links,' giving clear context. Does not mention when not to use or alternatives beyond the implied opposite (mimir_link), but the guidance is specific and useful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export all non-archived entities to .md files with YAML frontmatter in a vault directory. Files are human-readable, git-trackable, and Obsidian-compatible. Use this for backup, transfer between workspaces, or offline review.
| Name | Required | Description | Default |
|---|---|---|---|
| vault_dir | No | Directory path to write .md files. Created if it doesn't exist. Use ~ for home directory. | ~/.mimir/vault |
| Name | Required | Description |
|---|---|---|
| errors | No | Any errors encountered during export |
| vault_dir | No | Absolute path to the vault directory |
| files_created | No | Number of new .md files created |
| files_updated | No | Number of existing .md files updated |
| completed_at_unix_ms | No | Completion timestamp |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint: true, and the description adds that files are human-readable, git-trackable, and Obsidian-compatible, which complements the annotation. However, it does not clarify whether exporting overwrites existing files, which would be useful for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the main action and output format. Every word adds value, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple single-parameter interface and the presence of an output schema, the description covers the tool's purpose, output format, use cases, and parameter details adequately. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter vault_dir is fully described in the schema with default and path handling. The tool description adds context about writing to the vault directory, reinforcing its purpose beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool exports non-archived entities to .md files with YAML frontmatter, specifying a concrete verb and resource. It differentiates from siblings like mimir_vault_import.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists use cases ('backup, transfer between workspaces, or offline review'), providing clear usage context. It does not mention when not to use or alternatives, but the purpose is specific enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import .md files from a vault directory into the database. Reads YAML frontmatter for metadata and markdown body for content. Idempotent — re-running on the same vault won't duplicate entities. Pair with mimir_vault_export for transfer.
| Name | Required | Description | Default |
|---|---|---|---|
| vault_dir | No | Directory path to read .md files from. Use ~ for home directory. | ~/.mimir/vault |
| Name | Required | Description |
|---|---|---|
| errors | No | Any errors encountered during import |
| vault_dir | No | Absolute path of the vault directory read |
| files_created | No | Number of new entities created from files |
| files_updated | No | Number of existing entities updated |
| completed_at_unix_ms | No | Completion timestamp |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as destructive (destructiveHint: true). The description adds important behavioral context: idempotency (re-running doesn't duplicate) and the specific processing of frontmatter and body. This goes beyond the annotation and provides reassurance and clarity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences, no wasted words. It front-loads the purpose and adds essential details in the second sentence. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, clear operation), the description covers purpose, idempotency, pairing, and what is read. An output schema exists (not shown but present), so return values are covered elsewhere. It is complete enough for the agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a clear description for the only parameter 'vault_dir'. The tool description does not add additional parameter-specific details beyond the schema. Since schema coverage is high, the baseline is 3, and the description does not need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: importing .md files from a vault directory into the database. It specifies the file type (.md), what it reads (YAML frontmatter and markdown body), and distinguishes itself from the sibling mimir_vault_export by naming it. The verb is specific and the resource is well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions idempotency, telling the agent it is safe to re-run. It also pairs the tool with mimir_vault_export for transfer, providing a usage context. However, it does not explicitly state when not to use this tool or list alternatives among the many siblings, but the pairing note is helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all distinct entity categories present in the database. Use this to discover what knowledge domains exist before querying with mimir_recall or mimir_context.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| total | No | Number of categories |
| categories | No | All distinct categories in the database |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, so the description adds value by specifying the scope (distinct entity categories) and usage context. However, it does not disclose any additional behavioral traits (e.g., speed, permissions, or result format).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences: first states the action, second provides usage guidance. No wasted words, perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params, read-only), the description fully covers its purpose and usage context. Output schema exists, so no need to describe return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so the description has no burden. The mention of 'distinct entity categories' clarifies the scope beyond the schema, meeting the baseline for 0 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists distinct entity categories (specific verb+resource) and explains its role in discovering knowledge domains, distinguishing it from siblings like mimir_recall and mimir_context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using this tool before querying with mimir_recall or mimir_context, providing clear context. No when-not or alternatives listed, but for a simple discovery tool it's sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.5.0mimir_conflicts6 fields changedInput schema / properties / certainty_marginAdded value: +{
+ "default": 0.2,
+ "description": "Minimum certainty gap to auto-resolve; closer pairs are skipped as ambiguous",
+ "type": "number"
+}Input schema / properties / dry_runAdded value: +{
+ "default": true,
+ "description": "When resolve=true, only report what would be invalidated unless set false",
+ "type": "boolean"
+}Input schema / properties / limit / descriptionPrevious value: -"Maximum number of conflicts to return"New value: +"Maximum number of conflicts to return / resolve"Input schema / properties / resolveAdded value: +{
+ "default": false,
+ "description": "Opt-in: invalidate the lower-certainty side of clear conflicts instead of only reporting them",
+ "type": "boolean"
+}Output schema / properties / conflicts / descriptionPrevious value: -"Conflict pairs with similarity scores"New value: +"Conflict pairs with similarity scores (detection mode)"Output schema / properties / invalidationsAdded value: +{
+ "description": "Winner/loser pairs invalidated or previewed (resolve mode)",
+ "items": {
+ "type": "object"
+ },
+ "type": "array"
+}v2.4.0mimir_as_ofmimir_ingest_filev2.2.1mimir_extractmimir_recall1 field changedInput schema / properties / recency_half_life_secsAdded value: +{
+ "description": "Time-aware ranking for mode='hybrid' (default off). When set, each fused result's score is multiplied by 0.5^(age / this), where age is seconds since the memory was created — so a memory this many seconds old keeps half its weight and recent context outranks older but similar hits. Omit for relevance-only ranking.",
+ "minimum": 0,
+ "type": "number"
+}v0.1.0mimir_askmimir_autocoheremimir_benchmimir_coheremimir_compactmimir_conflictsmimir_contextmimir_correctmimir_decaymimir_embedmimir_federatemimir_forgetmimir_get_entitymimir_healthmimir_ingestmimir_journalmimir_linkmimir_maintenancemimir_migratemimir_prunemimir_purgemimir_recallmimir_recall_whenmimir_reindexmimir_remembermimir_scoremimir_sharemimir_state_deletemimir_state_getmimir_state_listmimir_state_setmimir_statsmimir_supersedemimir_synthesizemimir_timelinemimir_traversemimir_unlinkmimir_vault_exportmimir_vault_importmimir_workspace_listScored across 43 tools
Many tools have clearly distinct purposes (e.g., mimir_remember vs mimir_state_set), but there are clustered groups with fuzzy boundaries: prune/compact/decay/cohere/autocohere all perform overlapping maintenance, share/federate both transfer between workspaces, and recall/ask/recall_when all retrieve memories. The detailed descriptions help, but an agent could easily misselect among these sets.
All tools share the mimir_ prefix and use snake_case, which creates a strong sense of predictability. Most are verb-first (remember, recall, ingest, traverse) or verb_noun (state_get, vault_export, workspace_list), with only a few noun-only names (context, stats, health) as minor deviations. Overall naming is consistent and readable.
43 tools is well above the 25+ threshold and feels bloated for a memory server, even one that spans storage, retrieval, graph, state, maintenance, import/export, and LLM features. The scope is broad, but many tools could be consolidated (e.g., compaction/grooming operations, sharing/federation), so the count is excessive for the apparent domain.
The tool set covers the full memory lifecycle: create/update (remember, state_set, journal), read/search (recall, get_entity, ask, timeline), soft-delete (forget, prune), hard-delete (purge), graph relations (link, unlink, traverse, supersede), import/export (vault_import/export), sync (ingest), maintenance, health, and even feedback loops (correct, synthesize, bench). No obvious dead ends or missing operations for the stated purpose.
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Persistent memory for AI agents. Semantic search, memory graph, W3C DID identity.
Persistent, portable memory for AI assistants — your private memory graph, from any MCP client.
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
