fidelis

# Fidelis Memory

<!-- mcp-name: io.github.hermes-labs-ai/fidelis-memory -->

## Local-first, zero-LLM memory for Codex, Claude Code, and AI agents.

**73.0% end-to-end QA on LongMemEval-S (LLM-answered over Fidelis retrieval; the retrieval path is zero-LLM by default, with opt-in LLM tiers used only for pointer selection). 83.2% R@1 retrieval. $0/query.**

Stop re-explaining context to your agent. fidelis returns your original notes verbatim, local-first, fast, about 60 seconds to install. Your agent already calls an LLM to think; it should not need another one just to remember. Designed for developers. The default zero-LLM retrieval path does not send memory content to an LLM. The documented `fidelis init` service configuration also disables mem0 and Chroma telemetry. That can reduce third-party data exposure, but deployments still own their security and compliance assessment.

[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Status: pre-release](https://img.shields.io/badge/status-pre--release-orange)](#known-limitations)
[![CI tests: 368 passing](https://img.shields.io/badge/CI%20tests-368%20passing-brightgreen)](tests/)
[![Official MCP Registry](https://img.shields.io/badge/MCP%20Registry-active-5b5bd6)](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.hermes-labs-ai%2Ffidelis-memory/versions/0.0.97)
[![Made by Hermes Labs](https://img.shields.io/badge/made%20by-Hermes%20Labs-purple)](https://hermes-labs.ai)

```
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
```

What fidelis is:

- **fast** - ~216 ms local retrieval (full benchmark mean; vector-only path is faster)
- **cheap** - $0/query retrieval cost
- **private** - local memory store by default
- **faithful** - original stored passages returned, not paraphrases
- **proven** - benchmarked on LongMemEval-S (470 questions, public benchmark), with raw evidence in [`experiments/zeroLLM-FLAGSHIP-evidence/`](experiments/zeroLLM-FLAGSHIP-evidence/)
- **installable** - Codex or Claude Code via MCP in about 60 seconds

---

## Quickstart

```bash
# 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.0.97"
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.
```

Using Gemini CLI? After the local prerequisites and `fidelis init`, install
the native v0.0.97 extension directly:

```bash
gemini extensions install https://github.com/hermes-labs-ai/fidelis
```

The extension launches the released MCP package through `uvx` and includes the
[`GEMINI.md`](GEMINI.md) context file. [See the Gemini CLI extension details](#gemini-cli-extension).

> **Package-name note:** install Hermes Labs' package as `fidelis-memory`.
> The import name and CLI remain `fidelis`. The separate PyPI project named
> `fidelis` belongs to [NGdust/fidelis](https://github.com/NGdust/fidelis).

Linux users swap `brew install ollama` for the equivalent install from [ollama.com](https://ollama.com). [See Requirements](#requirements).

Fidelis Memory 0.0.97 is also published in the
[official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.hermes-labs-ai%2Ffidelis-memory/versions/0.0.97)
as `io.github.hermes-labs-ai/fidelis-memory`. Registry-aware clients can launch
the same released server directly from PyPI:

```bash
uvx --from "fidelis-memory==0.0.97" fidelis mcp serve
```

This starts the MCP stdio process; run `fidelis init` first when the local
Fidelis service and store have not already been configured. Version 0.0.94
introduced supported Codex MCP installation and context-sensitive orientation;
0.0.96 added the independently discoverable registry release; 0.0.97 is the
first tagged release that carries the Gemini CLI extension manifest.

## What you notice immediately

After the four commands above, the next time you open Codex or Claude Code:

- It stops asking you to repeat context you already wrote down.
- You can ask "what did we decide last week about auth?" - and the answer cites your actual decision, not a generic OAuth lecture.
- Architecture rationale you wrote in a markdown file two months ago surfaces when relevant.
- Your project context carries across sessions instead of resetting at every new conversation.
- Failed migration notes, naming conventions, founder voice memos - all queryable in your agent's normal flow.

Most of fidelis's value is *not* the benchmark; it's not having to explain the same thing twice.

## Most AI memory systems rewrite your notes

Most memory systems rephrase content on the way out. The specific fact gets summarized into something general. fidelis solves this structurally - there is no LLM in the default retrieval path, so the store returns exactly what you put in.

You store:

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

A lossy memory layer may return:

```text
authentication has a configurable timeout
```

fidelis returns:

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

The non-configurable qualifier survives. So does every other detail you wrote down.

## What this enables in Codex, Claude Code, GitHub Copilot CLI, Gemini CLI, and OpenClaw

Once `fidelis mcp install --client codex`, `--client copilot`, `--client gemini`, `--client openclaw`, or the default Claude install is run, ask your agent:

- *"What did we decide about auth?"*
- *"What failed last time we tried this migration?"*
- *"Which billing constraint was non-configurable?"*
- *"What did I say about Sarah's onboarding flow?"*

The MCP `fidelis_recall` tool gives the agent the original passages before it composes an answer, not paraphrased summaries. The answer can stay grounded in what you wrote, with the qualifiers intact.

> **fidelis retrieves memory without an LLM. Your agent still uses its normal LLM to answer using the retrieved context.** "Zero-LLM" applies to the memory hot path, not to your agent.

### GitHub Copilot CLI

Copilot CLI loads MCP servers from `mcp-config.json` in its configuration
directory (`~/.copilot` by default, or `$COPILOT_HOME`). Fidelis writes the
documented stdio entry there atomically, backing up any existing file and
leaving other servers untouched:

```bash
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` to target a different file. The
`copilot` binary is not required at install time; if you prefer the host CLI,
the equivalent registration is
`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 does not currently expose a hook or automatic-recall mechanism to
third-party servers, so recall happens when the agent calls the
`fidelis_recall`, `fidelis_orient`, or `fidelis_health` tools.

### Gemini CLI

Gemini CLI has native MCP management — `gemini mcp add|remove|list`, shipped
in v0.1.19 — and Fidelis registers itself through it rather than editing
`settings.json`. That matters: Gemini reads `settings.json` as
JSON-with-comments and its own writer round-trips your `//` and `/* */`
comments. A rewrite by Fidelis would silently delete them.

```bash
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` targets `./.gemini/settings.json` instead of the default
`--scope user` (`~/.gemini/settings.json`); Fidelis refuses `--scope project`
in your home directory, where Gemini collapses the two to the same file.
Requires Gemini CLI v0.1.19 or newer on `PATH`, and an auth method already
configured — Gemini refuses every `gemini mcp` subcommand until one is.

Because `gemini mcp add` overwrites a same-named entry without asking and
`gemini mcp remove` exits 0 even when the name is absent, Fidelis reads the
targeted `settings.json` back after every run. It refuses to touch a `fidelis`
entry it does not recognize (`--force` overrides), and reports a silent no-op
or an unexpected entry as a failure rather than as success. Unrelated servers,
their `env` secrets, other settings keys, and the file's permission bits are
left as they were.

Recall happens when the agent calls the `fidelis_recall`, `fidelis_orient`, or
`fidelis_health` tools.

### OpenClaw

OpenClaw keeps outbound MCP servers under `mcp.servers` in its JSON5 config
(`~/.openclaw/openclaw.json`, or `$OPENCLAW_CONFIG_PATH`). Because JSON5 allows
comments and trailing commas, Fidelis neither writes that file nor parses it:
it delegates every write to the documented `openclaw mcp add` CLI, and asks
OpenClaw's own read-only surface — `openclaw mcp show fidelis --json`, falling
back to `openclaw mcp list --json` — both before writing and afterwards to
confirm what landed.

```bash
fidelis mcp install --client openclaw    # openclaw mcp add fidelis --command … --arg …
openclaw mcp reload                      # pick up the new server