Fidelis Memory

Memoria local-primero sin LLM para agentes de IA con recuperación BM25, vector denso y fusión de rango recíproco.

Documentación

Fidelis Memory

Memoria local-first, sin LLM para Codex, Claude Code y agentes de IA.

83.2% R@1 en una ejecución de recuperación LongMemEval-S de 470 preguntas verificada en el repositorio. Una ejecución separada verificada respondió correctamente 317 de 434 preguntas calificadas (73.0%, IC 95% de Wilson [68.7%, 77.0%]) con un LLM leyendo la recuperación de Fidelis. La ruta de recuperación predeterminada en sí no realiza ninguna llamada a un LLM.

Deja de reexplicar el contexto a tu agente. fidelis devuelve tus notas originales textualmente a través de un servicio local-first. Tu agente ya llama a un LLM para pensar; no debería necesitar otro solo para recordar. Diseñado para desarrolladores. La ruta de recuperación predeterminada sin LLM no envía contenido de memoria a un LLM. La configuración documentada del servicio fidelis init también desactiva la telemetría de mem0 y Chroma. Esto puede reducir la exposición de datos a terceros, pero los despliegues siguen siendo responsables de su propia evaluación de seguridad y cumplimiento.

your notes / sessions
       ↓
local memory store      (~/.cogito/, fully local)
       ↓
fidelis retrieval       (BM25 + dense + RRF, no LLM)
       ↓
original passages       (verbatim, never rephrased)
       ↓
Codex / Claude Code / your agent

Qué es fidelis:

independiente de la API del modelo por defecto - la ruta de recuperación predeterminada no realiza ninguna llamada a la API del modelo; el cómputo y almacenamiento local aún tienen costos
privado - almacén de memoria local por defecto
fiel - devuelve los pasajes almacenados originales, no paráfrasis
medido - los artefactos de recuperación y QA de LongMemEval-S verificados en el repositorio están enlazados abajo
instalable - rutas MCP documentadas para Codex, Claude Code, GitHub Copilot CLI, Gemini CLI y OpenClaw

Fidelis es deliberadamente más limitado que una plataforma de memoria alojada. Consulta la matriz de ajuste de usuario antes de instalar: nombra los flujos de trabajo que soporta 0.1.0, los requisitos previos que asume y los casos que aún no atiende.

Inicio rápido

# 0. one-time: Ollama + the local embedder (~280 MB)
brew install ollama && ollama serve &
ollama pull nomic-embed-text

# 1. install Fidelis Memory from PyPI
python3 -m pip install "fidelis-memory==0.1.0"
fidelis init                  # background service (launchd / systemd)
fidelis watch ~/notes         # auto-ingests markdown
fidelis mcp install --client codex   # or omit for Claude Code
fidelis mcp serve             # runs the MCP server over stdio
# Restart your agent client. Memory is on.

Verifica la versión instalada y el servicio local antes de configurar un cliente:

python3 -c 'import fidelis; print(fidelis.__version__)'
# expected: 0.1.0
fidelis health
# expected prefix: status: ok  |  memories:

Luego verifica una recuperación real sin depender de un recuento de memoria fijo:

mkdir -p /tmp/fidelis-verify
printf '%s\n' 'Fidelis verification phrase: amber heron.' > /tmp/fidelis-verify/note.md
fidelis watch /tmp/fidelis-verify --once
fidelis query 'amber heron'
# success: the result contains "Fidelis verification phrase: amber heron."

¿Usas Gemini CLI? Después de los requisitos previos locales y fidelis init, instala la extensión nativa v0.1.0 directamente:

gemini extensions install https://github.com/hermes-labs-ai/fidelis --ref=v0.1.0

La extensión lanza el paquete MCP publicado a través de uvx e incluye el archivo de contexto GEMINI.md. Consulta los detalles de la extensión de Gemini CLI.

Nota sobre el nombre del paquete: instala el paquete de Hermes Labs como fidelis-memory. El nombre de importación y la CLI siguen siendo fidelis. El proyecto PyPI separado llamado fidelis pertenece a NGdust/fidelis.

Los usuarios de Linux intercambian brew install ollama por la instalación equivalente desde ollama.com. Consulta Requisitos.

Fidelis Memory 0.1.0 también está publicado en el Registro MCP oficial como io.github.hermes-labs-ai/fidelis-memory. Los clientes compatibles con el registro pueden lanzar el mismo servidor publicado directamente desde PyPI:

uvx --from "fidelis-memory==0.1.0" fidelis mcp serve

Esto inicia el proceso MCP stdio; ejecuta fidelis init primero cuando el servicio y almacén local de Fidelis aún no se hayan configurado. La versión 0.0.94 introdujo la instalación MCP de Codex compatible y la orientación sensible al contexto; 0.0.96 agregó la versión del registro descubrible de forma independiente; 0.0.97 fue la primera versión etiquetada que incluía el manifiesto de la extensión de Gemini CLI; y 0.1.0 promueve el contrato entre clientes probado como la primera versión menor de Fidelis.

Lo que notas de inmediato

Después de los cuatro comandos anteriores, la próxima vez que abras Codex o Claude Code:

Deja de pedirte que repitas el contexto que ya escribiste.
Puedes preguntar "¿qué decidimos la semana pasada sobre autenticación?" - y la respuesta cita tu decisión real, no una lección genérica de OAuth.
La justificación de arquitectura que escribiste en un archivo markdown hace dos meses aparece cuando es relevante.
Tu contexto de proyecto se mantiene entre sesiones en lugar de reiniciarse en cada conversación nueva.
Notas de migraciones fallidas, convenciones de nombres, notas de voz del fundador - todo consultable en el flujo normal de tu agente.

La mayor parte del valor de fidelis no es el benchmark; es no tener que explicar lo mismo dos veces.

La mayoría de los sistemas de memoria de IA reescriben tus notas

La mayoría de los sistemas de memoria reformulan el contenido al devolverlo. El hecho específico se resume en algo general. fidelis resuelve esto estructuralmente - no hay LLM en la ruta de recuperación predeterminada, por lo que el almacén devuelve exactamente lo que pusiste.

Tú almacenas:

auth tokens expire after 3600 seconds.
The 3600s window is non-configurable in our current contract.

Una capa de memoria con pérdida puede devolver:

authentication has a configurable timeout

fidelis devuelve:

auth tokens expire after 3600 seconds.
The 3600s window is non-configurable in our current contract.

El calificador no configurable sobrevive. También sobrevive cada otro detalle que escribiste.

Lo que esto permite en Codex, Claude Code, GitHub Copilot CLI, Gemini CLI y OpenClaw

Una vez que se ejecuta fidelis mcp install --client codex, --client copilot, --client gemini, --client openclaw o la instalación predeterminada de Claude, pregúntale a tu agente:

"¿Qué decidimos sobre autenticación?"
"¿Qué falló la última vez que intentamos esta migración?"
"¿Qué restricción de facturación no era configurable?"
"¿Qué dije sobre el flujo de incorporación de Sarah?"

La herramienta MCP fidelis_recall le da al agente los pasajes originales antes de que componga una respuesta, no resúmenes parafraseados. La respuesta puede mantenerse fundamentada en lo que escribiste, con los calificadores intactos.

fidelis recupera memoria sin un LLM. Tu agente aún usa su LLM normal para responder usando el contexto recuperado. "Sin LLM" se aplica a la ruta crítica de memoria, no a tu agente.

GitHub Copilot CLI

Copilot CLI carga servidores MCP desde mcp-config.json en su directorio de configuración (~/.copilot por defecto, o $COPILOT_HOME). Fidelis escribe la entrada stdio documentada allí atómicamente, respaldando cualquier archivo existente y dejando otros servidores intactos:

fidelis mcp install --client copilot     # writes ~/.copilot/mcp-config.json
copilot                                  # restart, then /mcp list shows "fidelis"
                                         # /mcp show fidelis lists its tools
fidelis mcp uninstall --client copilot   # removes only the fidelis entry

Usa --settings /path/to/mcp-config.json para apuntar a un archivo diferente. El binario copilot no se requiere en el momento de la instalación; si prefieres la CLI del host, el registro equivalente es copilot mcp add fidelis -- "$(python3 -c 'import sys;print(sys.executable)')" "$(python3 -c 'import fidelis.mcp_cmd as m;print(m.MCP_SERVER_FILE)')". Copilot actualmente no expone un hook o mecanismo de recuperación automática a servidores de terceros, por lo que la recuperación ocurre cuando el agente llama a las herramientas fidelis_recall, fidelis_orient o fidelis_health.

Gemini CLI

Gemini CLI tiene gestión MCP nativa — gemini mcp add|remove|list, incluida en v0.1.19 — y Fidelis se registra a través de ella en lugar de editar settings.json. Eso importa: Gemini lee settings.json como JSON con comentarios y su propio escritor conserva tus comentarios // y /* */. Una reescritura por Fidelis los eliminaría silenciosamente.

fidelis mcp install --client gemini      # gemini mcp add → ~/.gemini/settings.json
gemini                                   # restart, or run /mcp reload in a live session
gemini mcp list                          # shows "fidelis" and whether it connects
fidelis mcp uninstall --client gemini    # gemini mcp remove, verified

--scope project apunta a ./.gemini/settings.json en lugar del predeterminado --scope user (~/.gemini/settings.json); Fidelis rechaza --scope project en tu directorio de inicio, donde Gemini colapsa ambos al mismo archivo. Requiere Gemini CLI v0.1.19 o más reciente en PATH, y un método de autenticación ya configurado — Gemini rechaza cada subcomando gemini mcp hasta que haya uno.

Debido a que gemini mcp add sobrescribe una entrada con el mismo nombre sin preguntar y gemini mcp remove sale con 0 incluso cuando el nombre está ausente, Fidelis lee el settings.json objetivo de nuevo después de cada ejecución. Se niega a tocar una entrada fidelis que no reconoce (--force anula), y reporta una no-operación silenciosa o una entrada inesperada como un fallo en lugar de como éxito. Los servidores no relacionados, sus secretos env, otras claves de configuración y los bits de permisos del archivo se dejan como estaban.

La recuperación ocurre cuando el agente llama a las herramientas fidelis_recall, fidelis_orient o fidelis_health.

OpenClaw

OpenClaw mantiene servidores MCP salientes bajo mcp.servers en su configuración JSON5 (~/.openclaw/openclaw.json, o $OPENCLAW_CONFIG_PATH). Debido a que JSON5 permite comentarios y comas finales, Fidelis ni escribe ese archivo ni lo analiza: delega cada escritura a la CLI documentada openclaw mcp add, y pregunta a la superficie de solo lectura de OpenClaw — openclaw mcp show fidelis --json, con respaldo a openclaw mcp list --json — tanto antes de escribir como después para confirmar qué se registró.

fidelis mcp install --client openclaw    # openclaw mcp add fidelis --command … --arg …
openclaw mcp reload                      # pick up the new server
openclaw mcp status --verbose            # confirm the saved config
openclaw mcp doctor fidelis --probe      # verify it connects
fidelis mcp uninstall --client openclaw  # removes only the fidelis entry

El binario openclaw sí se requiere aquí, porque es el dueño de la escritura y es el único lector en quien se puede confiar con una configuración JSON5. Usa --settings /path/to/openclaw.json para apuntar a una configuración diferente; Fidelis lo pasa como $OPENCLAW_CONFIG_PATH en cada llamada delegada, lecturas incluidas, por lo que el estado que lee de vuelta es el estado del archivo que OpenClaw acaba de escribir. Si prefieres ejecutar la CLI del host tú mismo, el registro equivalente es openclaw mcp add fidelis --command "$(python3 -c 'import sys;print(sys.executable)')" --arg "$(python3 -c 'import fidelis.mcp_cmd as m;print(m.MCP_SERVER_FILE)')". La instalación y desinstalación se niegan a tocar una entrada mcp.servers.fidelis que no sea nuestra a menos que pases --force, y salen con código distinto de cero en lugar de reclamar éxito cuando la lectura de vuelta no prueba que el cambio se registró — incluso cuando OpenClaw no puede reportar la entrada en absoluto, lo que se trata como desconocido, nunca como "no hay nada allí".

Casos de uso y ROI

Tres razones concretas por las que los equipos eligen fidelis sobre memoria alojada:

Independencia de la API del modelo para la recuperación. La memoria vive en disco y la ruta de recuperación predeterminada no hace ninguna llamada a la API del modelo. Tu agente aún consume su contexto normal y recursos del modelo al responder.
Límite de datos local. La ruta predeterminada sin LLM mantiene notas y recuperación en la máquina local, reduciendo la exposición a procesadores de terceros. Esta arquitectura no confiere por sí misma cumplimiento SOC 2 o HIPAA.
Contexto de equipo. Agentes que recuerdan decisiones históricas, convenciones de nombres, migraciones fallidas y los calificadores de esas decisiones. El detalle no configurable que escribiste hace dos meses aparece cuando es relevante, en la voz del fundador, no parafraseado.

Cómo encaja

El diagrama está arriba. Codex y Claude Code son las rutas más rápidas al valor. El motor de recuperación es agnóstico al agente - combínalo con cualquier cliente LLM. El registro de Codex usa su CLI compatible codex mcp, y la configuración del servidor resultante es compartida por la aplicación de escritorio de Codex, la CLI y la extensión IDE en ese host.

Benchmarks

Observaciones de LongMemEval-S verificadas en el repositorio; estas son mediciones locales del proyecto, no replicaciones independientes.

Métrica	Valor
Recuperación R@1	83.2%
Recuperación R@5	98.3%
Precisión QA de extremo a extremo	73.0% (317/434 preguntas calificadas), IC 95% de Wilson [68.7%, 77.0%]
Llamadas a la API del modelo en tiempo de recuperación	0 en la ruta predeterminada de etapa 1

Evidencia cruda: agregado de recuperación · resumen QA de extremo a extremo

El nivel QA envuelve tu LLM existente con un prompt de sistema de 140–180 tokens - el Fidelis Scaffold. Consulta docs/scaffold.md.

Verifica la afirmación de cero LLM tú mismo

# Unset any LLM API keys for this shell
unset OPENAI_API_KEY ANTHROPIC_API_KEY DASHSCOPE_API_KEY

# Optional: drop your network. Ollama runs on 127.0.0.1:11434 (loopback).

# `recall-hybrid` is the explicit-tier command. zero_llm is the default.
fidelis recall-hybrid "what did the user say about Sarah" --tier zero_llm
tail ~/.fidelis/server.log

El nivel predeterminado zero_llm nunca hace una llamada LLM saliente. Los modos opcionales --tier filter y --tier flagship sí llaman a un LLM, pero solo para seleccionar punteros enteros - el servidor desreferencia esos punteros al texto almacenado original. El LLM no puede reformular el contenido de la memoria.

Orientación sensible al contexto (MCP)

El servidor MCP incluido también expone fidelis_orient. Reconoce cuando un turno invoca trabajo previo—incluso cuando es una declaración como "necesito recordar nuestro trabajo de Fidelis"—y selecciona un carril de evidencia acotado para identidad, mantenimiento, reutilización conceptual, comparación, decisiones, estado histórico o estado actual. La orientación devuelta es un índice derivado; los registros recuperados permanecen como evidencia textual con sus IDs y metadatos existentes. Los turnos no relacionados se abstienen explícitamente sin llamar al servidor de memoria.

Extensión de Gemini CLI

Fidelis también está empaquetado como una extensión nativa de Gemini CLI: el gemini-extension.json en la raíz del repositorio registra el mismo servidor MCP stdio que lanza la entrada del Registro MCP, más un archivo de contexto GEMINI.md que le dice al modelo cuándo llamar a fidelis_orient y fidelis_recall. Necesita uv en PATH y un servidor Fidelis en ejecución (fidelis init, consulta Requisitos), pero no un pip install manual:

gemini extensions install https://github.com/hermes-labs-ai/fidelis
gemini extensions list      # fidelis, with its GEMINI.md and MCP server
gemini extensions uninstall fidelis

La extensión fija fidelis-memory==0.1.0; gemini extensions update fidelis sigue los lanzamientos etiquetados del repositorio. El primer lanzamiento permite que uvx descargue la rueda y sus dependencias. Gemini CLI 0.32.1 sondea gemini mcp list con un tiempo de espera fijo de 5 segundos que ignora el timeout de 60 segundos del manifiesto, por lo que ese primer lanzamiento puede mostrar Disconnected; ejecuta uvx --from fidelis-memory==0.1.0 fidelis --help una vez para calentar la caché, después de lo cual la fila mostrará Connected. Si también registras Fidelis con gemini mcp add, la entrada de settings.json tiene prioridad sobre la de la extensión, por lo que ambas no entran en conflicto.

Requisitos

macOS o Linux (Windows aún no compatible)
Python 3.10+

Ollama ejecutándose localmente con nomic-embed-text descargado (~280 MB):

brew install ollama && ollama serve &
ollama pull nomic-embed-text   # ~280 MB, one-time

Una vez que Ollama y el modelo de incrustación estén disponibles, la guía de inicio rápido cubre la ruta completa de inicialización a primer recuerdo. La ruta de recuperación predeterminada no necesita clave de API de memoria.

Referencia rápida

fidelis recall "what did the user say about Sarah"
fidelis query  "Sarah" --limit 5
fidelis add    "raw text to extract into memories"
fidelis health
fidelis seed   ~/memory/   ~/notes/

fidelis add normalmente almacena hechos producidos por el modelo de extracción configurado. Si la extracción no devuelve hechos, Fidelis conserva la entrada original textualmente en lugar de perderla silenciosamente. El comando aún sale con 0 porque la escritura se realizó correctamente, pero stdout informa un estado degradado estable:

status=stored degraded=verbatim-fallback-empty-extraction id=<uuid> count=1

La automatización que requiere una extracción exitosa debe inspeccionar degraded; salir con 0 significa que la memoria se almacenó, no necesariamente que la extracción tuvo éxito. Debido a que mem0 no distingue un fallo de extractor tragado de un resultado legítimo de cero hechos, la alternativa favorece intencionalmente la durabilidad.

Helper de Python para integración directa:

from fidelis.augment import augment
from anthropic import Anthropic

client = Anthropic()
answer = augment(
    question="What did I say about Sarah?",
    qtype="single-session-user",
    llm_call=lambda system, user: client.messages.create(
        model="claude-haiku-4-5",  # any current Claude Messages model works
        system=system,
        messages=[{"role": "user", "content": user}],
        max_tokens=512,
    ).content[0].text,
)

Qué se ejecuta en tu máquina

Después de fidelis init:

Servicio: fidelis-server se ejecuta en http://127.0.0.1:19420 bajo el administrador de servicios de tu sistema operativo (launchd en macOS, systemd en Linux). Se inicia automáticamente al arrancar. Registros en ~/.fidelis/server.log.
Almacenamiento: Chroma + SQLite en ~/.cogito/ (el nombre del directorio se conserva del nombre clave previo al cambio de nombre del proyecto para compatibilidad con v0.0.x; se moverá a ~/.fidelis/ en un futuro incremento mayor). No salen datos de tu máquina en la ruta predeterminada sin LLM.
MCP: después de instalar para tu cliente seleccionado, Codex o Claude Code verán cuatro herramientas: fidelis_recall, fidelis_query, fidelis_health y fidelis_orient.

Para detener: fidelis init --uninstall. Para borrar: rm -rf ~/.cogito ~/.fidelis.

Limitaciones conocidas (v0.1.0)

Pre-lanzamiento. Los nombres de funciones de Python y los comandos CLI pueden cambiar. Fija la versión si construyes sobre ella.
Mejor en macOS Sequoia / Ubuntu 24.04 LTS. Otros sistemas operativos probablemente funcionen, pero no están probados en la puerta.
Los lanzamientos directos del servidor deshabilitan la telemetría de mem0 por defecto. Esto coincide con el servicio instalado por fidelis init y evita que los manejadores de salida de telemetría retrasen el apagado ordenado. Un MEM0_TELEMETRY=True explícito aún opta por participar. Para el mismo límite en Chroma, establece ANONYMIZED_TELEMETRY=False y CHROMA_TELEMETRY_DISABLED=True antes de un lanzamiento directo; fidelis init incluye los tres ajustes automáticamente.
Las preguntas de razonamiento temporal y preferencias son los tipos de pregunta más débiles en el andamiaje de QA (TR ~58%, Pref ~37% en la evaluación completa). Los tipos de pregunta de sesión única y actualización de conocimiento son sólidos (95–100%).
El nivel LLM opcional (modo "flagship") actualmente escala ~80% de las consultas en lugar del ~10% previsto — un error de costo 8× del que somos transparentes. El nivel predeterminado sin LLM no se ve afectado.
qwen3.5:9b en modo de pensamiento no sigue de manera confiable la instrucción literal de cobertura en el Andamiaje Fidelis. Usa Claude, una API de formato OpenAI o modelos locales sin modo de pensamiento para una cobertura confiable.

En qué se convierte esto con el tiempo

Día 1: guarda notas en ~/notes, ejecuta los cuatro comandos. Día 2: pregunta a tu agente sobre la decisión de ayer — la respuesta cita tu pasaje original. Día 7: tu agente comienza a llevar el contexto del proyecto entre sesiones; dejas de reexplicar.

Útil para constructores individuales hoy; relevante para equipos que necesitan memoria local mañana.

Fidelis Memory para equipos

fidelis es de código abierto bajo MIT y gratuito para cualquier uso, incluido el comercial. Si tu equipo tiene requisitos de implementación que la ruta OSS aún no cubre (memoria centralizada, aislamiento multi-namespace, autenticación personalizada), escribe a founders@hermes-labs.ai.

Para usuarios técnicos

docs/user-fit.md — usuarios compatibles, requisitos previos y no-ajustes explícitos
docs/releases/0.1.0.md — alcance del lanzamiento 0.1.0 y evidencia de aceptación
ROADMAP.md — puertas de resultados para 0.2.0
docs/full-reference.md — arquitectura completa, niveles de recuperación híbridos, endpoints del servidor local, solución de problemas
docs/scaffold.md — contrato del Andamiaje Fidelis + marcadores de detección de deriva
experiments/zeroLLM-FLAGSHIP-evidence/ — JSONs de evaluación sin procesar + SUMMARY legible por máquina (desgloses por tipo de pregunta, IC de Wilson, líneas base F1/F1B)

Licencia

MIT. Construido por Hermes Labs (Roli Bosch). Issues + PRs bienvenidos.

Acerca de Hermes Labs

Hermes Labs desarrolla herramientas de código abierto de confiabilidad, evaluación, memoria y guardias de tiempo de ejecución para agentes de IA. Fidelis es su proyecto de memoria local primero. Otro software público se lista en github.com/hermes-labs-ai, con artefactos de investigación publicados por separado en Zenodo.

Para implementaciones empresariales y compromisos de confiabilidad de IA: roli@hermes-labs.ai · hermes-labs.ai

Sobre el nombre. Hermes Labs lleva el nombre de Hermes, el dios mensajero griego — patrón de la comunicación y la interpretación, el heraldo que lleva significado entre mundos. El hilo con el trabajo: la hermenéutica, la teoría de la interpretación que toma su nombre de Hermes, es el ancla filosófica para un estudio de ingeniería de confiabilidad de IA cuyo sustrato es lingüístico. No está afiliado con la línea de LLM Hermes de NousResearch ni con su marco hermes-agent — empresas diferentes, trabajo diferente.

Fundador: Rolando (Roli) Bosch. Sitio: hermes-labs.ai Citación: Bosch, R. (2026). Hermes Labs: Infraestructura de confiabilidad de IA para agentes autónomos. https://hermes-labs.ai

Fuente cuantitativa para las afirmaciones de Fidelis anteriores: el agregado de 470 preguntas LongMemEval-S y el intervalo de Wilson en experiments/zeroLLM-FLAGSHIP-evidence/, evaluado el 2026-04-24.