Summary: This Fidelis Memory MCP server provides local, retrieval-focused memory tools for recalling stored text, querying memories, checking health, and orienting agents to prior work.
fidelis_recall: Retrieve memories from the local Fidelis store with a natural-language query; supports two-stage recall with optional LLM filter, zero-LLM by default, and a configurable result limit (default 20).
fidelis_query: Run a fast vector-only search over Fidelis memories without filtering, with a query and optional result limit (default 5).
fidelis_health: Check the Fidelis server’s health and current memory count; takes no arguments.
fidelis_orient: Get context-sensitive re-entry for prior work when a turn mentions a known project, decision, earlier work, maintenance, comparison, or possible reuse; accepts the current utterance, optional entity, up to four recent turns, and a result limit, returning an evidence-bound orientation packet or explicitly abstaining.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@io.github.hermes-labs-ai/fidelis-memory recall what we decided about auth last week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Your agent can forget a summary. Fidelis brings back the note.
Local memory for Codex, Claude Code, and other agents: save text across sessions and retrieve the original passage when it matters.
by Hermes Labs
PyPI · Connect an agent · Technical reference
A project summary might say “billing migration rolled back.” The original note says why it failed and do not retry until the idempotency fix is verified. When your next session depends on that condition, the missing sentence matters.
Fidelis stores your Markdown and text notes and retrieves their stored wording. Its default retrieval does not ask a generative model to rewrite your memory.
This path supports Python 3.10+, macOS or Ubuntu, and a local Ollama service. Start Ollama if needed (ollama serve in a separate terminal). No model API key is required. The current release is 0.3.0rc1.
ollama pull nomic-embed-text
python3 -m venv ~/.venvs/fidelis
source ~/.venvs/fidelis/bin/activate
python3 -m pip install "fidelis-memory[hybrid]==0.3.0rc1"
fidelis init
demo_dir=$(mktemp -d)
cat > "$demo_dir/atlas.md" <<'NOTE'
Atlas billing migration:
Duplicate charges appeared in staging. Rolled back.
Do not retry until the idempotency fix is verified.
NOTE
fidelis watch "$demo_dir" --once
fidelis recall-hybrid "Atlas billing migration retry condition" --tier zero_llmfidelis watch and fidelis recall-hybrid use the background service started by fidelis init.
Look for both the rollback and the retry condition in the retrieved text. This is retrieval of a saved note, not a generated answer. For your own files, replace "$demo_dir" with a notes directory. If retrieval fails, run fidelis health and confirm Ollama has nomic-embed-text available. Keep the virtual environment after fidelis init; the background service uses it.
What this changes on your machine: fidelis init installs a per-user background service (launchd on macOS, systemd --user on Linux) that starts fidelis-server automatically at login. fidelis watch sends the note to that server, which saves it in the local store at ~/.cogito/store by default, not in the temporary demo directory. The watcher also records ingested files in ~/.fidelis/watched.json. To remove the default service on macOS, run fidelis init --uninstall; it stops the service and deletes the launchd plist only. On Linux, find the installed unit with systemctl --user list-unit-files '*fidelis-server*', then run systemctl --user disable --now <unit>, delete that unit file from ~/.config/systemd/user/, and run systemctl --user daemon-reload. Neither path deletes your data. The store is shared by everything you save with Fidelis, so deleting ~/.cogito/store erases all of it, not just the demo note; do that only on a throwaway install. Also delete the temporary demo directory ($demo_dir), and ~/.fidelis/watched.json if you want its record of the file path gone.
Related MCP server: cc-history
Once the note is retrievable locally, install the MCP connection for your client:
fidelis mcp install --client codex
# Or, for Claude Code:
fidelis mcp installRestart the client and try: “Use Fidelis to find my Atlas billing migration note. What must happen before we retry? Quote the relevant text.”
The client gets tools to recall, store, correct, fetch, and inspect memory. It decides when to call them; installing the connection does not make every turn recall automatically. Other clients and uninstall commands include Cursor, Gemini CLI, Copilot CLI, and OpenClaw. A separate Pi extension provides prompt-time recall.
Original wording. watch, store, and other verbatim write paths keep the text you supplied, so retrieval can return the condition that a summary might omit.
Local retrieval. Fast vector search is the default MCP recall path. Explicit hybrid search combines keyword and vector results without a generative LLM at its zero_llm tier; local embeddings still require Ollama.
Corrections over time. A correction can supersede a prior record without erasing it. Recall can show validity and historical status instead of silently replacing the old note.
Fidelis also has optional extraction and model-assisted routes. Those can transform or filter inputs; use the verbatim path when the original wording is the point. Retrieved text can still be wrong or out of date, and your agent's model provider may see it when answering.
Fidelis 0.3.0rc1 is a single-machine pre-release, not a hosted team memory service. The LongMemEval-S retrieval run measured whether the redesigned default path retrieved material across 470 questions; it did not measure answer accuracy. See the results, user-fit guide, and security policy for deeper detail.
Full reference · Upgrade notes · Contribute · Changelog
Apache-2.0. Hermes Labs builds agentic infrastructure for autonomous systems.
Check the fidelis server's health and memory count.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full behavioral burden. It accurately implies a read-only health-check operation, but it does not disclose output format, what 'memory count' refers to, or any side effects or permissions. This is adequate but minimal.
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, front-loaded sentence with no filler. It states the action and object directly and 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 zero-parameter tool, invocation is trivial, so no parameter guidance is missing. However, with no output schema and no annotations, the description should clarify what 'health and memory count' actually return, such as status values, units, or response shape. The ambiguity leaves the agent without a complete picture.
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 tool has zero parameters and the schema is empty, so the no-parameter baseline of 4 applies. The description adds no parameter-level detail, but none is needed here.
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 ('Check') and names the resource ('fidelis server's health and memory count'), making the tool's role clear. It distinguishes itself from the sibling tools, which sound like data operations (recall, query, orient), though it does not explicitly contrast itself with them.
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?
No guidance is given about when to use this tool versus the sibling tools, nor are there exclusions, prerequisites, or context cues. The usage is only implied by the name and brief description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Context-sensitive re-entry for prior work. Call when a turn mentions a known project, decision, earlier work, maintenance, comparison, or possible reuse—even when the turn is not phrased as a question. Returns an evidence-bound orientation packet or explicitly abstains.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| entity | No | Optional exact known project or concept name | |
| utterance | Yes | Current user turn | |
| recent_turns | No | Up to four recent turns for referent resolution |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It does disclose a meaningful behavioral trait: it returns an evidence-bound orientation packet or explicitly abstains. However, it does not clarify what the packet contains, whether the operation is read-only, or what triggers abstention beyond the listed topics.
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 tightly packed sentences with no filler. The purpose, call conditions, and output/abstention behavior are compactly and effectively ordered; 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?
Without annotations or an output schema, the description gives a clear high-level contract but leaves the orientation packet contents and the role of optional parameters under-specified. It is enough to guide an agent toward the tool, but not enough to fully set expectations about what comes back.
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 75%, so the schema already documents utterance, entity, and recent_turns. The description adds usage context for the utterance but does not clarify the limit parameter or define the evidence-bound packet contents. It neither contradicts nor meaningfully augments the schema, leaving the schema to carry most of the weight.
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 states a specific function: context-sensitive re-entry into prior work, and lists concrete trigger signals (known project, decision, earlier work, maintenance, comparison, reuse). It does not explicitly distinguish itself from sibling tools fidelis_recall, fidelis_query, or fidelis_health, so it falls just short of a 5.
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 gives explicit when-to-call guidance, covering a wide range of trigger phrases and noting that it applies even when the turn is not phrased as a question. It does not name alternatives or state when not to use this tool, so it lacks the explicit exclusion that would make a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fast vector-only query over fidelis memories (no filter).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results | |
| query | Yes | Search query |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It mentions 'fast' and 'vector-only', which conveys performance and method, but it does not state that the operation is read-only or non-destructive, nor any other side effects, authentication needs, or limitations. For a query tool this is a notable omission.
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 with no filler words. It front-loads the core purpose and includes the most critical limitation ('no filter'). Every word contributes meaning, making it highly efficient.
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 2-parameter tool with no output schema, the description covers the essential action and scope. However, given the absence of annotations, it fails to mention that the operation is safe/read-only, and it does not describe the return format. These gaps make it less complete than it could be.
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% — both 'limit' and 'query' have basic descriptions. The description adds context about the overall query behavior ('vector-only', 'no filter') but does not provide additional per-parameter meaning beyond the schema. Baseline 3 applies because the schema already documents the 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 a verb (query) and a resource (fidelis memories), and adds specific qualifiers ('vector-only', 'no filter') that distinguish it from a filtered query. It does not explicitly name sibling tools, but the qualifiers provide enough differentiation for an agent to guess it is a basic, unfiltered search variant.
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 when no filter is needed ('no filter'), which gives a condition, but it does not explicitly mention when to prefer siblings like fidelis_recall or fidelis_orient. The guidance is implicit rather than explicit, so an agent must infer that filtered or more advanced queries belong elsewhere.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve memories from the local fidelis store. Two-stage recall with optional LLM filter; zero-LLM by default.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results | |
| query | Yes | Natural-language query |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral disclosure burden. It does add useful context — 'Two-stage recall with optional LLM filter; zero-LLM by default' — revealing internal mechanics beyond a simple retrieval. However, it omits any clarification of the two stages, possible side effects, or output shape, and the optional LLM filter is not backed by any parameter in the schema.
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 front-loaded sentence that states the action and key behavioral constraints with zero waste. Every clause adds 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?
The tool has no output schema and no annotations, so the description must carry more weight. It fails to explain how the optional LLM filter is toggled (no schema parameter exists for it), what 'two-stage' entails, or how this differs from fidelis_query. This leaves an agent with a meaningful gap in knowing how to invoke and interpret the 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 description coverage is 100%, with both 'query' and 'limit' already documented meaningfully. The description adds no additional parameter-level meaning, so the baseline of 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 uses a specific verb ('Retrieve') and resource ('memories from the local fidelis store'), clearly indicating a read operation. However, it does not explicitly differentiate itself from the sibling tool 'fidelis_query', so an agent may struggle to choose between them without further inspection.
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 no guidance on when to use this tool versus fidelis_query or fidelis_orient. It mentions 'zero-LLM by default' as a behavioral trait, but does not state conditions such as 'use when you need deterministic recall' or 'avoid when...' This leaves selection to inference.
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.
v0.1.0fidelis_healthfidelis_orientfidelis_queryfidelis_recallScored across 4 tools
fidelis_recall and fidelis_query both retrieve memories and are distinguished mainly by filtering/LLM behavior, so an agent could easily choose the wrong one. fidelis_orient adds another retrieval-like path, though fidelis_health is clearly distinct.
All tools share the fidelis_ prefix and use consistent snake_case, making the style predictable. The minor deviation is that fidelis_health is a noun rather than an action verb like recall, query, or orient.
Four tools is a tight, manageable surface for a focused memory-retrieval server. The count is well within the ideal range and each tool has a recognizable role.
The domain is memory, yet the toolset only reads, queries, checks health, and orients. There are no operations to store, update, or delete memories, so agents cannot persist new information or correct stale memories.
Persistent memory for AI agents. Search and store durable facts, preferences and decisions.
Persistent memory for AI agents. Search, store, and recall across sessions.
Universal persistent memory and knowledge retrieval layer for AI agents and LLMs.
Universal memory for AI agents and tools. Save, organize and search context anywhere.
