zeromem 0.4.1

Memory for Hermes Agent. Every message stays word for word in one SQLite file on your machine. Storing and searching cost zero tokens, and your model only pays to read what comes back.

zeromem is a Rust implementation of Zero-Mem by Xiao et al. (paper, official code).

Install

zeromem is in the Hermes plugin catalog:

hermes plugins install zeromem

Then in ~/.hermes/config.yaml:

memory:
  provider: zeromem

The first run downloads a 130MB embedding model into ~/.hermes/memory/zeromem-models.

Switching from another memory provider? Hermes keeps your conversations in its own session history, so you can bring them all in. It costs no tokens, and running it twice won't duplicate anything:

hermes zeromem import        # preview
hermes zeromem import --yes

The provider syncs turns in the background, prefetches evidence before each turn, and gives your agent zeromem_recall, zeromem_stats and zeromem_forget_session. Recall skips the active session since it's already in context, so "last session" means the one before it.

For Spanish or other non-English conversations, set {"model": "multilingual-e5-small"} in ~/.hermes/memory/zeromem.json.

How it works

Each turn gets indexed three ways: an entity graph, a timeline of turns, windows and episodes, and BM25 plus dense embeddings. A query gets a deterministic profile, routes to a primary view, runs both retrievals, fuses the scores and pulls in linked turns. No step calls an LLM.

Turns are the source of record. The graph, timeline and BM25 rebuild from them on open, so the indexes can't drift from the data.

Benchmarks

LoCoMo evidence recall: how many of the gold evidence turns come back, over 1,536 questions (categories 1 to 4), with one store per conversation.

The official code retrieves whole sessions and zeromem retrieves turns, so matched context is the fair comparison. zeromem leads on temporal questions (0.88 vs 0.84) and multi-hop (0.61 vs 0.60). The official code leads on single-hop and open-domain.

What this doesn't show:

• Answer quality. This measures retrieval only.
• Other memory systems. They haven't been benchmarked.
• A clean-room result. Adding BM25 to the graph view came from reading the official code, and matched-context recall was 0.794 before it.
• Speed. The two use different models: BGE-M3 and spaCy against bge-small and heuristic NER.

Other ways to use it

Python

uv add zeromem

import zeromem
m = zeromem.ZeroMem("mem.db")
m.ingest_turn("s1", "user", "I moved to Jersey City on February 14, 2022.", 1644796800)
m.query("When did I move?")

CLI

zm --db mem.db ingest turns.jsonl     # {"session_id","speaker","text","ts"}
zm --db mem.db query "When did I move?"
zm --db mem.db stats

Claude Code

One shared store across every project, in ~/.zeromem (override with ZEROMEM_HOME).

cargo install --git https://github.com/ptaranat/zeromem zeromem
claude plugin marketplace add ptaranat/zeromem
claude plugin install zeromem@zeromem

Build

just test        # offline, hash embedder
just demo        # ingest examples/dungeon-books.jsonl, run queries
just dev         # maturin develop into .venv
cargo build --release

The fastembed feature (default) pulls onnxruntime and downloads bge-small-en-v1.5 on first use. --no-default-features drops both. Opening a store with a different model re-embeds every turn, so switching needs no migration.

Credits

Method from the Zero-Mem paper and official code by Yilin Xiao, Zhehan Zhu, Yujing Zhang, Jin Chen, Zijin Hong, Luyao Zhuang, Qinggang Zhang, Shengyuan Chen, Xiaocao Ouyang, Lingfei Ren, and Xiao Huang. zeromem started as a clean-room implementation from the paper text, before the authors released their code. The 0.4.0 retrieval fixes came from benchmarking against that code once it was out, so later versions aren't clean-room. Integration shape follows mnemosyne.

MIT licensed.