Skip to main content

memtomem

❖ Communityv0.1.1★ 15

Memory · by memtomem · added

Markdown-first long-term memory shared across your coding agents: a local memtomem MCP server plus six memory skills (index, recall, remember, search, setup, status). Notes live in ~/.memtomem and are searchable from Hermes, Claude Code, Codex CLI and Kimi Code. Runs at user scope.

Open in Hermes Desktop
hermes plugins install memtomem
Repository ↗Reviewed source @ 8fc6275 ↗Documentation ↗

README

From the reviewed commit 8fc6275 ↗; it updates when the author re-pins.

memtomem for Hermes Agent

Markdown-first long-term memory shared across your coding agents. This package starts a local memtomem MCP server and adds six memory workflow skills. Notes saved here are searchable from Claude Code, Codex CLI, Kimi Code and any other client that uses the same ~/.memtomem store.

mcp.json, plugin.json and skills/ are generated by tools/render_plugin_assets.py from packages/memtomem-plugin-assets/; edit the sources there, not the files here.

Requirements

  • Hermes Agent 0.21.5 or later (the version this package was verified against).
  • Git on PATH, for the commit lookup under Install.
  • uv on PATH. The server is started with uvx --python 3.12 --from 'memtomem[onnx]==0.6.6' memtomem-server. Without uv the plugin still installs and enables, and the server fails at start with missing executable 'uvx'.
  • Python 3.12. uv uses a 3.12 it can find; if there is none, it downloads one (about 70 MiB) on first start. If that is not possible — offline, or uv's Python downloads turned off — the server does not start and $HERMES_HOME/logs/mcp-stderr.log (default ~/.hermes/logs/) shows uv's error; run uv python install 3.12 once to fix it.

Install

Install from this repository, pinned to the commit of a memtomem release tag. Hermes (0.21.5) takes a full 40-character commit SHA for --ref and refuses a tag name such as v<version>, so look the commit up first:

git ls-remote --exit-code https://github.com/memtomem/memtomem "refs/tags/v<version>" "refs/tags/v<version>^{}"

<version> is a memtomem release that includes this directory and is listed on PyPI. The command prints one line for a lightweight tag and two for an annotated one; no output and exit status 2 mean there is no such tag. Copy the SHA at the start of the line that ends in ^{} if there is one, otherwise of the only line, and install at it:

hermes plugins install "https://github.com/memtomem/memtomem#packages/memtomem-hermes-plugin" --ref <commit-sha> --enable

At a release commit, mcp.json pins that same memtomem version, so the server installs the release you picked. Hermes marks a direct Git install as a custom (unreviewed) source.

Hermes records that commit as the plugin's pin. To move to a later release, look up its commit the same way and reinstall with --force --ref <new-commit-sha>. A --force reinstall without --ref installs the pinned commit again, and hermes plugins update memtomem refuses to move a pinned plugin.

An install without --ref takes the tip of main, unless Hermes still holds a pin for this source from an earlier install; then it installs that pinned commit, even if the plugin directory was deleted. Use main only for development: right after a version bump is merged, main can pin a memtomem version that is not published yet, and the server then fails to start until it is.

Once memtomem is listed in the Hermes plugin catalog, hermes plugins install memtomem installs the catalog's pinned commit instead.

First run

Start a new Hermes session. No separate setup is needed: on a machine where memtomem has never been configured, the server uses its defaults (SQLite store in ~/.memtomem/memtomem.db, notes in ~/.memtomem/memories, BM25 search). If memtomem is already set up for your other agents through ~/.memtomem/config.json, the server reads that configuration and shares the same store — provided the storage and memory paths in it are absolute or start with ~. A relative path resolves against this server's working directory (the plugin directory), so it would open a different store. Ask Hermes for memtomem status and check the reported DB path before relying on sharing.

Settings from your shell environment do not carry over. Hermes passes only a small allowlist of environment variables to MCP servers (plus any variables supplied by an external secret source you configured in Hermes), so a MEMTOMEM_* variable exported in your shell (for example MEMTOMEM_STORAGE__SQLITE_PATH) does not reach this server, and it opens the store from config.json, a .env file (below), or the defaults instead. If you configure memtomem that way, add your own mcp_servers.memtomem entry with those variables under env: (see "Scope" below; it takes precedence over this package).

memtomem also loads a .env file itself at startup, after Hermes's filtering. python-dotenv searches upward from memtomem's installed location, not from the working directory; with a uvx launch that location is inside uv's cache (normally ~/.cache/uv), so the nearest .env among that cache's ancestor directories is applied — normally ~/.env, unless a nearer one such as ~/.cache/.env exists — while one in the plugin directory or where you start Hermes is not. A MEMTOMEM_* setting in ~/.env therefore does reach this server.

Scope

This package runs memtomem at user scope. The server starts in the plugin directory, so it has no project context: there is no per-project (project_local) memory, and paths given to indexing must be absolute. Notes are shared with your other agents through the user-scope store. The handoff workflow of the other memtomem plugins is not included, because it needs a project.

Indexing a whole project directory also reads any project memory inside it (<project>/.memtomem/memories*). What happens to those files depends on memtomem's configuration, not on this package:

  • Registered project memory (listed in memtomem's project memory directories) keeps its project scope. It is indexed, but user-scope searches from this package do not return it.
  • Unregistered project memory is indexed as ordinary user-scope notes and does show up in searches here and in your other agents.

Search visibility is not the same as not indexing: to keep a directory out of the index entirely, index a narrower path.

If you need project scope, use the manual integration instead: disable this package (hermes plugins disable memtomem — its skills are written for user scope only) and add your own server entry to config.yaml:

mcp_servers:
  memtomem:
    command: uvx
    args: ["--python", "3.12", "--from", "memtomem[onnx]==0.6.6", "memtomem-server"]
    env:
      MEMTOMEM_TOOL_MODE: core
      # copy any MEMTOMEM_* settings you rely on here
    cwd: /path/to/project

Network

Memory is stored locally in ~/.memtomem. The server is downloaded from PyPI on first start, and uv downloads Python 3.12 then too if it cannot find one. With a fresh BM25-only configuration nothing else leaves the machine. An existing memtomem configuration may enable its own network paths: model downloads from Hugging Face (ONNX embedding or local reranker), a remote embedding or LLM provider, Cohere reranking (sends the query and candidate chunks), or search webhooks (send events including the query).

License

Apache-2.0.

← Back to the catalog · catalog built Oct 3, 2026