nanomem

nanomem

An embedded store for facts that change.

A fact your application remembers is not a document. It gets corrected — people move, change jobs, switch phone numbers. A vector store keeps both statements and returns whichever one is worded closer to the question, which is how an assistant ends up confidently repeating an address you left two years ago. nanomem keeps the chain and knows which end of it is current.

Eight months of ordinary chat; the team fact changed once, in passing. Similarity still ranks the *old* one first, because the question is worded like the old job — so nanomem hands it over labelled rather than pretending otherwise. A real run of demo_stale.py against a local Ollama (nomic-embed-text); regenerate it with python3 assets/record_demo.py. The label does not come from the model: run the same demo with no embedding endpoint reachable at all and the SUPERSEDED line is still there, because it is computed from revision order rather than similarity.

[Evidence](https://github.com/OmBansod2/nanomem/blob/main/BENCHMARKS.md) — how it compares to FAISS, sqlite-vec and Chroma (including where it loses), what happens when the process is killed mid-write, and the pytest command that re-runs most of those claims on the copy you just installed.

Quickstart — give your assistant a memory that knows what changed

pip install nanomem

Add this to your MCP client's config. On macOS claude_desktop_config.json lives in ~/Library/Application Support/Claude/:

{

"mcpServers": { "nanomem": { "command": "nanomem-mcp" } } }

That is the whole configuration. The vault defaults to ~/.nanomem/memory.dat; set NANOMEM_VAULT, or pass --vault /some/path.dat, to put it elsewhere.

Restart the client and tell it something that will change later:

*"Remember that I work at Acme Corp."*

*(a week later)* *"Actually I moved — I'm at Globex now."*

*"Where do I work? And where did I work before?"*

It answers Globex, and can tell you it used to be Acme — not because the second sentence was worded closer to the question, but because nanomem kept the chain and knows which end of it is current. Ask it *"what did I believe about this in March?"* and it can answer that too.

Seven tools: nanomem_add, nanomem_search, nanomem_history, nanomem_as_of, nanomem_changes, nanomem_volatility, nanomem_stats — so the assistant can ask what a fact USED to be, what the memory believed at a past moment, what changed last week, and which of its own beliefs have gone stale.

The vault is an ordinary file. Point the CLI or a Python script at the same path to read what the assistant wrote — a write is on disk before its reply is sent, so another process sees it immediately and stopping the server cannot lose it.

Through 0.7.17 that was not true: the server flushed only on a clean exit, and an MCP client stops its servers with SIGTERM. Twenty nanomem_add calls, each answered "Stored …", then SIGTERM, left zero rows in the vault. If you ran an earlier version, anything the assistant "remembered" in a session that was not closed cleanly was never written.

Or use it from Python

pip install nanomem

import time

from nanomem import Vault

DAY, now = 86400, time.time() job = {"entity": "employer"}

v = Vault("memory.dat") v.add("I work at Acme Corp.", metadata=job, timestamp=now - 300*DAY) v.add("I moved jobs, I now work at Initech.", metadata=job, timestamp=now - 155*DAY) v.add("I switched again, I work at Globex now.", metadata=job, timestamp=now - 10*DAY)

print(v.search("where do I work")0)

I switched again, I work at Globex now.

for r in v.history("where do I work"): print(r["revision"], r["superseded"], r["text"])

1 True I work at Acme Corp.

2 True I moved jobs, I now work at Initech.

3 False I switched again, I work at Globex now.

print(v.search("where do I work", as_of=now - 200*DAY)0)

I work at Acme Corp.

f = v.volatility()[0] print(f["entity"], f["n_revisions"], round(f["median_interval"]/DAY))

employer 3 145

One file on disk. One runtime dependency (numpy). No server, no daemon, no index to rebuild. Search is exact — a full cosine scan, not an approximate index — so recall is 100% by construction and every interesting question is about time rather than ranking.

It tells you when the answer is cut short

search returns at most top_k records. It now also tells you what it left behind, which matters most when the caller is a model that cannot look:

r = vault.search("revenue of every company in every year", top_k=3, min_score=0.6)

len(r) # 3 — it is a list; every existing caller is unchanged r.truncated # True r.n_above_floor # 21 — how many cleared your min_score r.explain() # "This answer is incomplete -- showing 3 of 21 records

scoring at or above your min_score of 0.60. ..."

For a multi-part question, the useful number is which parts got nothing at all:

r = vault.search("What is Acme revenue? ... What port does staging use?")

r.unanswered_sub_queries # the clauses that got no slot

explain() returns "" when nothing informative was cut, so it is safe to append unconditionally — and the MCP nanomem_search tool does exactly that.

It only speaks when there is a `min_score`. With the default 0.0 every record clears the floor, so "showing 3 of 101" would be true of every query ever asked, including one whose answer really is a single record. A signal that fires every time carries nothing. The count is still on r.n_above_floor either way.

The counts are free: the scan is exhaustive, so both numbers already existed on the line that applies top_k and were being discarded.

It marks answers that are no longer true

A timestamp says when a record was *written*. It cannot say whether it is still *true* — a fact written ten years ago can be current, and one written last week can already be dead. The difference is whether a later record replaced it, which is what the revision chain knows.

Search for a fact that has changed and you get several of its values, because that is what a chain is. Each one now says where it stands:

for h in vault.search("where do I work", top_k=3):

print(h["superseded"], h["text"])

False I switched again, I work at Globex now.

True I moved, I work at Initech.

True I work at Acme Corp.

ask() puts that in the prompt, so the model is told which facts are dead before it writes; the MCP tool marks them in the text an assistant reads:

[2] (2025-08-17) [SUPERSEDED - replaced 8 months ago; this was true

when written, not now]: I moved, I work at Initech.

A ten-year-old fact that never changed is marked with nothing. superseded is None — not False — for a record in no chain, because there "nothing replaced it" is unknown rather than true.

Tell it what an attribute is

metadata={"entity": "employer"} is doing real work above, and it is worth a paragraph because little else here matters as much.

Name the attribute and nanomem knows those three statements are one fact, so it keeps them as a chain. Leave it out and a lexical tagger guesses from the text — measured, on 100 chains per arm, every member of a chain got the same correct tag in 70 of 100 plainly-worded chains and 0 of 100 on narrative phrasing. In the example above it tags "I moved jobs, I now work at Initech." as location rather than career, because "moved" outweighs "work at", and the chain silently splits in two.

So if your application has attributes of its own, declare them. Everything nanomem does that a vector store does not rests on knowing which statements are about the same thing — and you know that, while the tagger is guessing.

Package 0.8.3 · engine 3.4.6 · container format 3 · arena cache format 4.

Licence: Apache-2.0. Use it commercially, modify it, ship it inside a closed-source product — keep the LICENSE and NOTICE files with any redistribution, say what you changed, and do not use the project's or the author's name to endorse yours. That is the whole obligation.

nanomem was AGPL-3.0-or-later from 0.6.0 through 0.7.22, with a commercial licence alongside it. That combination protected something worth less than the users it was turning away: most companies ban AGPL by policy and many developers skip it without reading it. Copies distributed under the old terms keep them, and both superseded texts still ship — LICENSE.agpl-3.0-or-later.md and LICENSE.preview-v1.0.md. Up to 0.6.0 the wheel metadata said Apache-2.0 while the LICENSE file said All Rights Reserved; that contradiction was resolved in 0.6.0 and has stayed resolved.

Run the demo

cd nanomem_standalone

python3 demo.py # stores, updates, searches, prints real stats() python3 demo_stale.py # the one worth seeing: a fact going stale over 8 months

Add --brief to either one to drop the explanatory prose and keep only the computed lines; that is what the recording at the top of this file shows.

demo_stale.py is eight months of ordinary work sessions where nobody ever announces a change — the team fact arrives twice, both times inside a question about something else. Then the assistant writes a bio, similarity puts the *old* team first because the question is worded like the old job, and nanomem hands it over marked SUPERSEDED - replaced 4 months ago. Every line it prints is computed; edit the sessions at the top and re-run it.

It stores a few facts, updates one of them to show revision handling, searches with citations, and prints the vault's real stats() — document count, file size, the measured active_heap_ram_kb, and whether the file is encrypted (by default it is not).

Run the tests

python3 -m pytest -q

845 tests, no network needed.

There is no test_security.py. Earlier versions of this README told you to run one to "prove that zero plaintext exists on disk"; that file never existed, and the claim was wrong anyway — a vault is a plaintext file unless you give it a passphrase. To check for yourself:

python3 -m nanomem.cli init demo.dat

python3 -m nanomem.cli add "the office wifi password is hunter2" --vault demo.dat strings demo.dat | grep hunter2 # plaintext vault: it is there python3 -m nanomem.cli rekey --vault demo.dat --new-password-stdin strings demo.dat | grep hunter2 # password mode: it is not

Use it from your own script

from nanomem import Vault

with Vault("my_knowledge.dat") as vault: # plaintext by default doc_id = vault.add("Server backup runs daily at 02:00 UTC") vault.add("The staging database is on port 5433")

hits = vault.search("When does the backup run?") print(hits0, hits0)

add() returns the document id, so you can get, update or delete by it later. For an encrypted vault, pass password="…" (or set NANOMEM_PASSWORD).

Embeddings are yours to choose. The default is nomic-embed-text on