Fidelis Memory

Memória local-first sem LLM para agentes de IA com recuperação BM25, vetor denso e fusão de classificação recíproca.

Documentação

Fidelis Memory

Memória local-first, sem LLM, para Codex, Claude Code e agentes de IA.

83,2% R@1 em uma execução de recuperação LongMemEval-S com 470 perguntas versionada no repositório. Uma execução separada versionada respondeu corretamente a 317 de 434 perguntas avaliadas (73,0%, intervalo de confiança de Wilson de 95% [68,7%, 77,0%]) com um LLM lendo a recuperação do Fidelis. O caminho de recuperação padrão em si não faz nenhuma chamada de LLM.

Pare de reexplicar contexto ao seu agente. O fidelis retorna suas notas originais na íntegra por meio de um serviço local-first. Seu agente já chama um LLM para pensar; ele não deveria precisar de outro apenas para lembrar. Projetado para desenvolvedores. O caminho de recuperação padrão sem LLM não envia conteúdo de memória para um LLM. A configuração documentada do serviço fidelis init também desativa a telemetria do mem0 e do Chroma. Isso pode reduzir a exposição de dados a terceiros, mas as implantações ainda são responsáveis por sua própria avaliação de segurança e conformidade.

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

O que o fidelis é:

independente da API do modelo por padrão - o caminho de recuperação padrão não faz nenhuma chamada de API de modelo; computação e armazenamento locais ainda têm custos
privado - armazenamento de memória local por padrão
fiel - passagens armazenadas originais retornadas, não paráfrases
mensurável - artefatos de recuperação e QA LongMemEval-S versionados estão linkados abaixo
instalável - caminhos MCP documentados para Codex, Claude Code, GitHub Copilot CLI, Gemini CLI e OpenClaw

O Fidelis é deliberadamente mais restrito do que uma plataforma de memória hospedada. Consulte a matriz de adequação ao usuário antes de instalar: ela nomeia os fluxos de trabalho que a versão 0.1.0 suporta, os pré-requisitos que assume e os casos que ainda não atende.

Início 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.

Verifique a versão instalada e o serviço local antes de configurar um cliente:

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

Em seguida, verifique uma recuperação real sem depender de uma contagem fixa de memória:

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."

Usando o Gemini CLI? Após os pré-requisitos locais e o fidelis init, instale a extensão nativa v0.1.0 diretamente:

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

A extensão inicia o pacote MCP publicado por meio do uvx e inclui o arquivo de contexto GEMINI.md. Veja os detalhes da extensão do Gemini CLI.

Nota sobre o nome do pacote: instale o pacote da Hermes Labs como fidelis-memory. O nome de importação e a CLI permanecem fidelis. O projeto PyPI separado chamado fidelis pertence a NGdust/fidelis.

Usuários de Linux trocam brew install ollama pela instalação equivalente de ollama.com. Veja os Requisitos.

O Fidelis Memory 0.1.0 também está publicado no Registro MCP oficial como io.github.hermes-labs-ai/fidelis-memory. Clientes que reconhecem o registro podem iniciar o mesmo servidor publicado diretamente do PyPI:

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

Isso inicia o processo MCP stdio; execute fidelis init primeiro quando o serviço e o armazenamento locais do Fidelis ainda não tiverem sido configurados. A versão 0.0.94 introduziu a instalação MCP suportada do Codex e a orientação sensível ao contexto; a 0.0.96 adicionou a versão do registro descoberta de forma independente; a 0.0.97 foi a primeira versão marcada que trouxe o manifesto da extensão do Gemini CLI; e a 0.1.0 promove o contrato entre clientes testado como a primeira versão menor do Fidelis.

O que você nota imediatamente

Após os quatro comandos acima, na próxima vez que você abrir o Codex ou o Claude Code:

Ele para de pedir que você repita o contexto que já escreveu.
Você pode perguntar "o que decidimos na semana passada sobre autenticação?" - e a resposta cita sua decisão real, não uma palestra genérica sobre OAuth.
A lógica de arquitetura que você escreveu em um arquivo markdown há dois meses aparece quando relevante.
Seu contexto de projeto persiste entre sessões em vez de ser redefinido a cada nova conversa.
Notas de migração com falha, convenções de nomenclatura, memorandos de voz do fundador - tudo pesquisável no fluxo normal do seu agente.

A maior parte do valor do fidelis não é o benchmark; é não ter que explicar a mesma coisa duas vezes.

A maioria dos sistemas de memória de IA reescreve suas notas

A maioria dos sistemas de memória reformula o conteúdo na saída. O fato específico é resumido em algo geral. O fidelis resolve isso estruturalmente - não há LLM no caminho de recuperação padrão, então o armazenamento retorna exatamente o que você colocou.

Você armazena:

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

Uma camada de memória com perdas pode retornar:

authentication has a configurable timeout

O fidelis retorna:

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

O qualificador não configurável sobrevive. Assim como todos os outros detalhes que você escreveu.

O que isso permite no Codex, Claude Code, GitHub Copilot CLI, Gemini CLI e OpenClaw

Depois que fidelis mcp install --client codex, --client copilot, --client gemini, --client openclaw ou a instalação padrão do Claude for executada, pergunte ao seu agente:

"O que decidimos sobre autenticação?"
"O que falhou da última vez que tentamos essa migração?"
"Qual restrição de cobrança não era configurável?"
"O que eu disse sobre o fluxo de integração da Sarah?"

A ferramenta MCP fidelis_recall dá ao agente as passagens originais antes que ele componha uma resposta, não resumos parafraseados. A resposta pode permanecer fundamentada no que você escreveu, com os qualificadores intactos.

O fidelis recupera memória sem um LLM. Seu agente ainda usa seu LLM normal para responder usando o contexto recuperado. "Zero-LLM" se aplica ao caminho quente da memória, não ao seu agente.

GitHub Copilot CLI

O Copilot CLI carrega servidores MCP de mcp-config.json em seu diretório de configuração (~/.copilot por padrão, ou $COPILOT_HOME). O Fidelis escreve a entrada stdio documentada lá atomicamente, fazendo backup de qualquer arquivo existente e deixando outros servidores intocados:

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

Use --settings /path/to/mcp-config.json para apontar para um arquivo diferente. O binário copilot não é necessário no momento da instalação; se você preferir a CLI do host, o registro equivalente é copilot mcp add fidelis -- "$(python3 -c 'import sys;print(sys.executable)')" "$(python3 -c 'import fidelis.mcp_cmd as m;print(m.MCP_SERVER_FILE)')". O Copilot atualmente não expõe um hook ou mecanismo de recall automático para servidores de terceiros, então o recall acontece quando o agente chama as ferramentas fidelis_recall, fidelis_orient ou fidelis_health.

Gemini CLI

O Gemini CLI tem gerenciamento MCP nativo — gemini mcp add|remove|list, incluído na v0.1.19 — e o Fidelis se registra por meio dele em vez de editar settings.json. Isso importa: o Gemini lê settings.json como JSON-com-comentários e seu próprio gravador faz round-trip dos seus comentários // e /* */. Uma reescrita pelo Fidelis os excluiria 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 aponta para ./.gemini/settings.json em vez do padrão --scope user (~/.gemini/settings.json); o Fidelis recusa --scope project no seu diretório inicial, onde o Gemini colapsa os dois no mesmo arquivo. Requer Gemini CLI v0.1.19 ou mais recente em PATH, e um método de autenticação já configurado — o Gemini recusa todos os subcomandos gemini mcp até que um esteja.

Como gemini mcp add sobrescreve uma entrada de mesmo nome sem perguntar e gemini mcp remove sai com 0 mesmo quando o nome está ausente, o Fidelis lê o settings.json alvo de volta após cada execução. Ele recusa tocar em uma entrada fidelis que não reconhece (--force substitui), e relata um no-op silencioso ou uma entrada inesperada como falha em vez de sucesso. Servidores não relacionados, seus segredos env, outras chaves de configuração e os bits de permissão do arquivo são deixados como estavam.

O recall acontece quando o agente chama as ferramentas fidelis_recall, fidelis_orient ou fidelis_health.

OpenClaw

O OpenClaw mantém servidores MCP de saída sob mcp.servers em sua configuração JSON5 (~/.openclaw/openclaw.json, ou $OPENCLAW_CONFIG_PATH). Como o JSON5 permite comentários e vírgulas finais, o Fidelis não escreve esse arquivo nem o analisa: ele delega cada escrita à CLI documentada openclaw mcp add, e pergunta à própria superfície somente-leitura do OpenClaw — openclaw mcp show fidelis --json, com fallback para openclaw mcp list --json — tanto antes de escrever quanto depois para confirmar o que foi gravado.

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

O binário openclaw é necessário aqui, porque ele é o dono da escrita e é o único leitor em que se pode confiar com uma configuração JSON5. Use --settings /path/to/openclaw.json para apontar para uma configuração diferente; o Fidelis passa como $OPENCLAW_CONFIG_PATH em cada chamada delegada, leituras incluídas, então o estado que ele lê de volta é o estado do arquivo que o OpenClaw acabou de escrever. Se você preferir executar a CLI do host você mesmo, o registro equivalente é 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)')". A instalação e a desinstalação recusam tocar em uma entrada mcp.servers.fidelis que não seja nossa, a menos que você passe --force, e saem com código não-zero em vez de alegar sucesso sempre que a leitura de volta não prova que a mudança foi aplicada — incluindo quando o OpenClaw não consegue relatar a entrada de forma alguma, o que é tratado como desconhecido, nunca como "nada lá".

Casos de uso e ROI

Três razões concretas pelas quais equipes escolhem o fidelis em vez de memória hospedada:

Independência de API de modelo para recuperação. A memória vive no disco e o caminho de recuperação padrão não faz nenhuma chamada de API de modelo. Seu agente ainda consome seu contexto normal e recursos de modelo ao responder.
Limite de dados local. O caminho padrão sem LLM mantém notas e recuperação na máquina local, reduzindo a exposição a processadores terceiros. Essa arquitetura não confere por si só conformidade com SOC 2 ou HIPAA.
Contexto de equipe. Agentes que lembram decisões históricas, convenções de nomenclatura, migrações com falha e os qualificadores dessas decisões. O detalhe não configurável que você escreveu há dois meses aparece quando relevante, na voz do fundador, não parafraseado.

Como se encaixa

O diagrama está no topo. Codex e Claude Code são os caminhos mais rápidos para valor. O mecanismo de recuperação é agnóstico de agente - combine-o com qualquer cliente LLM. O registro do Codex usa sua CLI codex mcp suportada, e a configuração do servidor resultante é compartilhada pelo aplicativo desktop do Codex, CLI e extensão de IDE nesse host.

Benchmarks

Observações LongMemEval-S versionadas; estas são medições locais do projeto, não replicações independentes.

Métrica	Valor
Recuperação R@1	83,2%
Recuperação R@5	98,3%
Precisão de QA ponta a ponta	73,0% (317/434 perguntas avaliadas), intervalo de confiança de Wilson de 95% [68,7%, 77,0%]
Chamadas de API de modelo no momento da recuperação	0 no caminho padrão do estágio 1

Evidência bruta: agregado de recuperação · resumo de QA ponta a ponta

A camada de QA envolve seu LLM existente com um prompt de sistema de 140–180 tokens - o Fidelis Scaffold. Veja docs/scaffold.md.

Verifique a alegação de zero-LLM você mesmo

# 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

A camada padrão zero_llm nunca faz uma chamada de LLM de saída. Os modos opcionais --tier filter e --tier flagship chamam um LLM, mas apenas para selecionar ponteiros inteiros - o servidor desreferencia esses ponteiros para o texto armazenado original. O LLM não pode reformular o conteúdo da memória.

Orientação sensível ao contexto (MCP)

O servidor MCP incluído também expõe fidelis_orient. Ele reconhece quando um turno invoca trabalho anterior—mesmo quando é uma declaração como "preciso lembrar do nosso trabalho com o Fidelis"—e seleciona uma trilha de evidência limitada para identidade, manutenção, reuso conceitual, comparação, decisões, estado histórico ou estado atual. A orientação retornada é um índice derivado; os registros recuperados permanecem evidência verbatim com seus IDs e metadados existentes. Turnos não relacionados se abstêm explicitamente sem chamar o servidor de memória.

Extensão do Gemini CLI

O Fidelis também é empacotado como uma extensão nativa do Gemini CLI: o gemini-extension.json na raiz do repositório registra o mesmo servidor MCP stdio que a entrada do Registro MCP inicia, além de um arquivo de contexto GEMINI.md que diz ao modelo quando chamar fidelis_orient e fidelis_recall. Ele precisa de uv em PATH e de um servidor Fidelis em execução (fidelis init, veja Requisitos), mas não de um 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

A extensão fixa fidelis-memory==0.1.0; gemini extensions update fidelis segue os lançamentos de tags do repositório. O primeiro lançamento permite que uvx baixe a wheel e suas dependências. O Gemini CLI 0.32.1 testa gemini mcp list com um timeout fixo de 5 segundos que ignora o timeout de 60 segundos do manifesto, então esse primeiro lançamento pode exibir Disconnected; execute uvx --from fidelis-memory==0.1.0 fidelis --help uma vez para aquecer o cache, após o qual a linha exibirá Connected. Se você também registrar o Fidelis com gemini mcp add, a entrada settings.json terá precedência sobre a da extensão, então as duas não entram em conflito.

Requisitos

macOS ou Linux (Windows ainda não suportado)
Python 3.10+

Ollama rodando localmente com nomic-embed-text baixado (~280 MB):

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

Assim que o Ollama e o modelo de embeddings estiverem disponíveis, o quickstart cobre o caminho completo de inicialização até a primeira recuperação. O caminho de recuperação padrão não precisa de chave de API de memória.

Referência 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 armazena fatos produzidos pelo modelo de extração configurado. Se a extração não retornar fatos, o Fidelis preserva a entrada original verbatim em vez de perdê-la silenciosamente. O comando ainda sai com código 0 porque a gravação foi bem-sucedida, mas o stdout relata um status degradado estável:

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

Automação que exige extração bem-sucedida deve inspecionar degraded; saída com código 0 significa que a memória foi armazenada, não necessariamente que a extração foi bem-sucedida. Como o mem0 não distingue uma falha de extração engolida de um resultado legítimo de zero fatos, o fallback favorece intencionalmente a durabilidade.

Helper Python para integração direta:

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

O que está rodando na sua máquina

Após fidelis init:

Serviço: fidelis-server roda em http://127.0.0.1:19420 sob o gerenciador de serviços do seu SO (launchd no macOS, systemd no Linux). Inicia automaticamente na inicialização. Logs em ~/.fidelis/server.log.
Armazenamento: Chroma + SQLite em ~/.cogito/ (o nome do diretório é preservado do codinome pré-rename do projeto para compatibilidade com v0.0.x — será movido para ~/.fidelis/ em um bump major posterior). Nenhum dado sai da sua máquina no caminho padrão zero-LLM.
MCP: após instalar para o cliente selecionado, o Codex ou o Claude Code vê quatro ferramentas: fidelis_recall, fidelis_query, fidelis_health e fidelis_orient.

Para parar: fidelis init --uninstall. Para apagar: rm -rf ~/.cogito ~/.fidelis.

Limitações conhecidas (v0.1.0)

Pré-lançamento. Nomes de funções Python e comandos CLI podem mudar. Fixe a versão se você construir sobre ela.
Melhor no macOS Sequoia / Ubuntu 24.04 LTS. Outros SOs provavelmente funcionam, mas não são testados no gate.
Lançamentos diretos do servidor desabilitam a telemetria do mem0 por padrão. Isso corresponde ao serviço instalado por fidelis init e evita que handlers de saída de telemetria atrasem o desligamento gracioso. Um MEM0_TELEMETRY=True explícito ainda opta por participar. Para o mesmo limite no Chroma, defina ANONYMIZED_TELEMETRY=False e CHROMA_TELEMETRY_DISABLED=True antes de um lançamento direto; fidelis init inclui todas as três configurações automaticamente.
Perguntas de raciocínio temporal e preferência são os qtypes mais fracos no scaffold de QA (TR ~58%, Pref ~37% na avaliação completa). Qtypes de sessão única e atualização de conhecimento são fortes (95–100%).
O nível LLM opcional (modo "flagship") atualmente escala ~80% das consultas em vez dos ~10% pretendidos — um erro de custo de 8× sobre o qual somos transparentes. O nível padrão zero-LLM não é afetado.
qwen3.5:9b em modo de pensamento não segue de forma confiável a instrução literal de hedge no Fidelis Scaffold. Use Claude, uma API no formato OpenAI ou modelos locais sem modo de pensamento para hedging confiável.

No que isso se transforma ao longo do tempo

Dia 1: coloque notas em ~/notes, execute os quatro comandos. Dia 2: pergunte ao seu agente sobre a decisão de ontem — a resposta cita sua passagem original. Dia 7: seu agente começa a carregar contexto do projeto entre sessões; você para de reexplicar.

Útil para builders solo hoje; relevante para equipes que precisam de memória local amanhã.

Fidelis Memory para equipes

fidelis é open-source sob MIT e gratuito para qualquer uso, incluindo comercial. Se sua equipe tem requisitos de implantação que o caminho OSS ainda não cobre (memória centralizada, isolamento multi-namespace, autenticação personalizada), escreva para founders@hermes-labs.ai.

Para usuários técnicos

docs/user-fit.md — usuários suportados, pré-requisitos e não-adequações explícitas
docs/releases/0.1.0.md — escopo do lançamento 0.1.0 e evidências de aceitação
ROADMAP.md — gates de resultado para 0.2.0
docs/full-reference.md — arquitetura completa, níveis de recuperação híbrida, endpoints do servidor local, solução de problemas
docs/scaffold.md — contrato do Fidelis Scaffold + marcadores de detecção de drift
experiments/zeroLLM-FLAGSHIP-evidence/ — JSONs de avaliação brutos + SUMMARY legível por máquina (detalhamentos por qtype, Wilson CI, baselines F1/F1B)

Licença

MIT. Construído por Hermes Labs (Roli Bosch). Issues + PRs são bem-vindos.

Sobre a Hermes Labs

A Hermes Labs desenvolve ferramentas open-source de confiabilidade, avaliação, memória e guardas de runtime para agentes de IA. Fidelis é seu projeto de memória local-first. Outros softwares públicos estão listados em github.com/hermes-labs-ai, com artefatos de pesquisa publicados separadamente no Zenodo.

Para implantações empresariais e engajamentos de confiabilidade de IA: roli@hermes-labs.ai · hermes-labs.ai

Sobre o nome. Hermes Labs é nomeada em homenagem a Hermes, o deus mensageiro grego — patrono da comunicação e interpretação, o arauto que carrega significado entre mundos. O fio condutor com o trabalho: hermenêutica, a teoria da interpretação que recebe seu nome de Hermes, é a âncora filosófica para um estúdio de engenharia de confiabilidade de IA cujo substrato é linguístico. Não afiliado à linha de LLMs Hermes da NousResearch ou ao framework hermes-agent deles — empresas diferentes, trabalhos diferentes.

Fundador: Rolando (Roli) Bosch. Site: hermes-labs.ai Citação: Bosch, R. (2026). Hermes Labs: AI reliability infrastructure for autonomous agents. https://hermes-labs.ai

Fonte quantitativa para as afirmações do Fidelis acima: o agregado LongMemEval-S de 470 perguntas e o intervalo de Wilson em experiments/zeroLLM-FLAGSHIP-evidence/, avaliado em 2026-04-24.