Verified scope
Verified on 17 November 2026: in a fresh normal Desktop chat,
save_memory without a project argument saved a note in the configured checkout. Project-filtered search and get_observations retrieved a previously saved fact, a search scoped to a second project returned no match, and the turn completed with its final response. The tested model was available to that account; use a model your account supports.
This connection provides on-demand recall and explicit save. It does not enable automatic capture, automatic session-start context, or mirroring of Desktop’s native memory-editor saves. The existing Hermes Agent provider is a separate integration.
Before you connect
- Install Hermes One and its local Hermes Agent backend. Use a separate test profile first.
- Install Claude-Mem and confirm its local worker is available. Locate the absolute Node executable and installed
plugin/scripts/mcp-server.cjsbundle. - Find the backend home and active profile that Desktop actually uses. Edit that profile’s
config.yaml; the Desktop executable directory is not the backend home. Named profiles have their own configuration. Back up the file, including any existingmemory.providerandmcp_servers.claude-mementry. - Choose one absolute checkout directory. Find its Claude-Mem project key in an existing saved observation or the worker’s project list; worktrees and configured overrides can make it differ from the folder name.
npx claude-mem install --ide hermes for this MCP-only setup: that installer also selects the automatic Claude-Mem memory provider. See the separate Hermes Agent guide for its behavior.
Connect with the command
PointHERMES_HOME at the profile home you found above, then run:
mcp_servers.claude-mem (with cwd and CLAUDE_MEM_RUNTIME: worker) and records an ownership receipt. It leaves memory.provider unchanged and installs no provider files. It stops without changes if memory.provider is claude-mem, if --project-cwd is not an existing absolute directory, or if an mcp_servers.claude-mem entry it does not own already exists. Restart the backend afterwards. The manual steps below produce the same entry.
Configure the model
The verified memory workflow used Hermes’s ownopenai-codex OAuth connection and default tool loop. An existing Codex CLI login alone did not initialize the fresh Hermes credential store. Authenticate in the same backend/profile home you selected above:
auto keeps Hermes’s own tool loop. The optional codex_app_server runtime runs the Codex CLI agent instead; a plain chat worked there, but this guide’s memory workflow was verified with the default Hermes runtime. Do not run Codex-runtime migration commands for this setup: they can change Codex’s separate MCP configuration.
Desktop recognizes openai-codex as a keyless model provider. If Desktop requests its separate local backend API key, use its supported key-generation UI; that key authenticates the backend and is not a model-provider API key. Restart the backend and confirm an ordinary chat works before testing memory.
Connect manually
Skip this section if you used the command. Merge this entry into the existingmcp_servers mapping. Replace the three absolute paths. Windows forward slashes avoid backslash escapes in quoted YAML strings.
CLAUDE_MEM_DATA_DIR under this entry’s env. Preserve any existing worker connection settings. A source TypeScript file is not the installed MCP bundle.
If claude-mem already exists, compare and update that entry once; do not create a duplicate YAML key. Preserve its prior contents for disconnect. Keep unrelated MCP entries and settings.
For a fresh profile, omit the external memory.provider key to retain Hermes’s built-in memory. If it selects claude-mem, back up that setting and remove only the provider key for this MCP-only workflow. Preserve the rest of the memory mapping. Another external provider has its own capture behavior; assess that separately before using the profile. Do not delete memory files or records.
Restart the backend and open a fresh Desktop chat. Restarting only the window may leave an old backend or MCP process running. Confirm the discovered Claude-Mem tools include search, timeline, get_observations and save_memory.
The MCP cwd is fixed for that connection’s lifetime. Use one configured profile per checkout, and restart the backend after changing it. Selecting a context folder in chat does not change this MCP directory. The fixed directory supplies default save attribution and exclusion checks; it does not automatically scope every search.
Verify a note across chats
Use harmless content. First ask the agent to search for a duplicate under your exact project key. Then ask it to callsave_memory without a project argument:
search, review its IDs, then use timeline around a selected result:
get_observations:
123 with the saved ID. Confirm the project and fact match. Repeat the search with a different project key; the first project’s note must not appear in that scoped result. Hermes may prefix MCP tool names; use the discovered tools with these schemas.
Privacy and limits
- The local worker can hold memories from several projects and agents. Explicit project filters select results; they are not an account or authorization boundary. Profiles connected to the same store intentionally share access. Unfiltered searches can find other projects.
- Selected memories enter the model conversation and are processed by the configured model provider. Local storage does not make remote model inference local.
save_memorystores the submitted note without an observer inference call. Do not include secrets or rely on automatic-capture private tags to redact an explicit note. Existing cloud sync or export settings can carry saved records elsewhere.- Excluded-checkout checks use the MCP request directory. Keep
cwdcorrect: a project label alone does not change that directory. The Desktop excluded-profile/checkouts matrix was not exercised; verify your exclusion policy before entering private material. - Remote backends, hosted Claude-Mem, other operating systems and an unconfigured-profile isolation test remain unverified. Normal-chat usability during a worker outage was not tested. With the worker stopped, the configured built MCP transport returned an explicit save error in approximately 2.9 seconds; this was a separate transport check.
- The Claude subscription plugin worked through the Desktop backend bridge, but normal onboarding remained blocked by its API-key gate. Local Ollama onboarding worked; the tested 8B model could not complete a memory tool turn within the bounded test on the available machine.
Troubleshooting
Disconnect
If you connected with the command, run it with the sameHERMES_HOME, then restart the backend:
mcp_servers.claude-mem entry you changed, or remove it if this setup created it. Restore the previous memory.provider only if you changed it and it has not since been intentionally changed again. Keep all other settings and entries. Restart the backend and verify the removed connection no longer advertises its tools.
Do not delete Desktop profiles, native memory files, Claude-Mem databases or saved observations. A manual setup has no installer ownership receipt, so hermes uninstall does not own it; roll it back by hand. Manual rollback matched the disposable configuration snapshot, and all four saved test records remained readable afterward.
