Memory Nemo (MNemo) — Python bindings
Repository overview: root README · landing page: index.html.
Python bindings for Memory Nemo (MNemo), the encrypted single-file
agent-memory engine. The package is a thin PyO3 wrapper
over the Rust core in the
sibling mnemo/ crate — the storage engine, AES-256-GCM encryption, the
write-ahead log, the IVF+PQ index, snapshots, and the agent-memory model all
run as compiled Rust; Python only sees a small, ergonomic surface.
Distribution name on PyPI:
mnemo-engine(bothmnemoandmnemo-dbwere already taken by unrelated projects). The import name ismnemo_enginestarting in v0.7.0, so the full setup ispip install mnemo-enginethenimport mnemo_engine. The pre-v0.7.0import mnemokeeps working for the v0.7.x series via a pure-Python shim that emits oneDeprecationWarningon import; the shim is removed in v0.8.0. Code that wants to keep its call sites unchanged canimport mnemo_engine as mnemo— same objects, no warning. See the "Breaking: import name" section in the CHANGELOG for the full migration.
For AI agents
An agent that's been handed a .mnemo file and its passphrase can become
productive in two calls — no external documentation required:
import mnemo_engine as mnemo, os
db = mnemo.open("agent.mnemo", os.environ["MNEMO_PASSPHRASE"])
# The file introduces itself: returns memories tagged metadata.area="onboarding",
# manifest first. Each entry tells you the embedder, agent_id convention,
# project metadata, and any other context the file's author recorded.
for entry in db.about():
print(entry["content"])
Creating a new database? It's self-describing from creation:
db = mnemo.open("new.mnemo", "passphrase", dimensions=384)
db.insert_default_manifest() # same scaffold that `mnemo init` adds
db.flush()
The scaffold tells the next agent what to do: replace it with one that records your real embedder and conventions. See the main README for the full pattern.
Agents working together (v0.17)
A brain is also shared memory and coordination for several agents: a
task queue, an inbox and claims. Name the handle's agent with
set_author, then:
db.set_author("planner-a")
db.task_add("Fix the flaky upload test", role="worker")
db.post("role:worker", "CI is green again")
db.set_author("worker-a")
taken = db.task_next("worker") # {"task": ..., "token": ..., ...}
for m in db.inbox("worker-a", "worker"):
print(m["from"], m["subject"])
db.task_update(taken["task"]["slug"], "ready", token=taken["token"])
The guide (mnemo onboard --guide, section 6) has the rules and the
rest, and the API table lists every method.
Install
The published wheel is the normal install path — nothing to build:
pip install mnemo-engine
Prebuilt wheels ship for CPython 3.8+ on macOS x86_64 + arm64, Linux
x86_64 + aarch64 (manylinux), and Windows x86_64. If none fits (e.g. a
BSD, aarch64 musl, or any other platform mnemo doesn't ship a wheel
for), pip falls back to the sdist and compiles from source — that path
needs a working Rust toolchain (rustup) and will take a few minutes.
ARM users building from source (sdist, or
cargo install mnemo-enginedirectly): setRUSTFLAGS="--cfg aes_armv8 --cfg polyval_armv8"before install to enable hardware AES. The prebuilt wheels have this baked in; your sdist build doesn't see our repo's.cargo/config.toml. Verify afterwards withmnemo.build_info()['aes_backend'], which should read"armv8 hardware"(not"armv8 software").
From source (contributors)
pip install maturin
cd mnemo-python
maturin build --release # produces a wheel in target/wheels/
pip install target/wheels/mnemo-*.whl
maturin develop installs straight into the active virtualenv during
development. The extension is built against the stable ABI (abi3-py38), so a
single wheel works on CPython 3.8 and newer.
Usage
import mnemo_engine as mnemo
# Open an existing database, or create one (dimensions required to create).
db = mnemo.open("agent.mnemo", "passphrase", dimensions=4)
# Store typed memories. memory_type is one of:
# "episodic", "semantic", "procedural", "working".
db.remember(
"the user prefers concise answers",
"procedural",
[0.1, 0.2, 0.3, 0.4],
importance=0.8,
agent_id="assistant",
metadata={"source": "onboarding"},
)
# Multi-signal recall — similarity blended with recency, importance, frequency.
for hit in db.recall([0.1, 0.2, 0.3, 0.4], top_k=5):
print(hit["score"], hit["content"])
db.flush()
db.close()
mnemo.open returns a Mnemo object that is also a context manager —
with mnemo.open(...) as db: flushes automatically on exit.
Sessions
A Session wraps the database for one conversation: it records each turn as
working memory and, when closed, consolidates those turns into durable
episodic memory.
db = mnemo.open("agent.mnemo", "passphrase", dimensions=4)
with db.session("assistant") as chat:
chat.add_turn(mnemo.Turn.user("my flight is Friday", [1.0, 0.0, 0.0, 0.0]))
chat.add_turn(mnemo.Turn.assistant("noted", [0.9, 0.1, 0.0, 0.0]))
context = chat.recall([1.0, 0.0, 0.0, 0.0], top_k=5)
# leaving the block consolidates the turns into episodic memory
# or, explicitly:
chat = db.session("assistant")
chat.add_turn(mnemo.Turn("system", "be concise", [0.0, 0.0, 0.0, 1.0]))
chat.close() # consolidate working -> episodic
# chat.discard() # alternative: throw the turns away
mnemo.Turn has Turn.user(...), Turn.assistant(...), Turn.system(...),
and Turn(role, content, vector). A Session's recall is always scoped to
its own agent.
API
mnemo.open(path, passphrase=None, dimensions=None, read_only=False, *, shared=False, wait=10.0, allow_network_fs=False, cancel=None) -> Mnemo
No passphrase (v0.15, 12.3): mnemo.open(path) opens an existing file
through the key-source chain, by the file's kind. A key comes from
MNEMO_KEY, MNEMO_KEY_FILE, MNEMO_KEY_COMMAND or the OS keychain (a
brain made by mnemo init, or kept there by mnemo unlock); a passphrase
from MNEMO_PASSPHRASE or the keychain. It never prompts. A missing file
raises ValueError (create one with mnemo init), and so does a file no
source has a secret for. It works with read_only=True and shared=True,
and one process can hold a keychain brain and a MNEMO_PASSPHRASE brain at
once. The released wheels carry the keychain; a wheel built from source
needs --features keychain.
Shared mode (v0.14, shared=True): several processes and sessions use
one file at once. The handle takes the file's lock for each call and holds
nothing between calls; every method below is one read or one write, and
each write commits before it returns (flush() does nothing). wait is how
long one call may wait for the lock, in seconds, before LockedError. The
file must already exist, and shared=True can't be combined with
read_only=True. Network and synced folders are refused unless
allow_network_fs=True. The handle keeps its passphrase in memory until it
closes. File-wide settings (set_max_snapshots, set_cache_budget,
set_cache_flush_policy, set_turn_compress_after) raise
UnsupportedError. Update every mnemo-engine that opens the file first.
See docs/shared-mode.md in the repository.
db = mnemo.open("team.mnemo", passphrase, shared=True) # in each process
db.remember("we ship on Fridays", "semantic", vector) # committed on return
db.notices() # what the handle warns about (also raised as UserWarning at open)
Mnemo methods:
| Method | Purpose |
|---|---|
remember(content, memory_type, vector, *, agent_id, importance, session_id, ttl_secs, shared, metadata, key, supersedes, visibility, review_by, as_of) |
Store a memory; returns its id. v0.17: visibility ("public", "team", "private"), review_by and as_of (unix seconds), also on remember_text, update and update_text. With key, a keyed write that supersedes the key's live record (returns {"id", "outcome"}). supersedes (v0.15, with key): the id of a memory written without a key, which becomes the key's first version and is superseded; matching content adopts it as is ("updated") |
recall(query, top_k=10, memory_types=None, agent_id=None, track_access=True, n_probe=None, n_rerank=None, …, visibility=None) |
Multi-signal ranked retrieval. track_access=False skips access-stat updates (fully read-only recall). n_probe / n_rerank (PR ANN-1): per-query ANN tuning — None uses the index's build-time defaults (ANN-1 auto-formulas: (partitions+1)/2 and 500) |
search(query, top_k=10) |
Exact nearest-neighbour search |
get(id) / delete(id) |
Fetch / soft-delete by id |
about(*, visibility=None) |
Self-describing onboarding briefing — memories tagged metadata.area="onboarding", manifest first. v0.17: private entries only when visibility asks (["private"], ["all"]) |
stale(*, visibility=None), kind_counts() |
v0.17: the stale records (id, what, since, text, whose, visibility), oldest first, private ones only when visibility asks; the live records by kind (facts, turns, essence, coordination) |
recent(n=20) |
The n most recently written live memories, newest first: facts only (no thread turns, essence items or onboarding records), nothing superseded or expired; not counted as an access (v0.16) |
about_essence() |
The project essence render for the briefing (markdown), or None when the file has none |
insert_default_manifest() |
Insert the canonical scaffold manifest (same one mnemo init adds); returns its id |
session(agent_id) |
Begin a conversation Session |
flush() / close() |
Persist pending changes |
verify() |
Decrypt and re-validate every record |
build_index() / drop_index() / has_index() |
Approximate index control |
snapshots() / restore_to(txn_id) / restore_to_time(unix_secs) |
Point-in-time recovery |
set_cache_capacity(pages) / page_cache_stats() |
Page-cache tuning (renamed from cache_stats in v0.4.0 — that name now belongs to the result cache below) |
cache_put(namespace, key, value, content_type="text", ttl_secs=None) |
Exact-key result cache put (Phase 10.1). value accepts str or bytes |
cache_get(namespace, key) |
Exact-key cache get — returns dict on hit (value is bytes) or None |
cache_delete(namespace, key) / cache_purge(namespace=None, expired_only=False) |
Tombstone by key or in bulk |
cache_stats(namespace=None) |
Result-cache stats: {entries, bytes, hits, misses, hit_rate, evictions} |
cache_put_semantic(namespace, key, vector, value, model, content_type="text", ttl_secs=None) |
Semantic cache put (Phase 10.2) — vector must match db dimensions |
cache_get_semantic(namespace, query, model, threshold=0.97) |
Top-1 cosine over the namespace's vectored entries whose model matches |
set_cache_flush_policy(policy, max_dirty=None, max_age_secs=None) |
policy="strict" (default; every put durable on return) or "batched" (engine auto-flushes at max_dirty puts or max_age_secs seconds). Under batched, cache_put and friends no longer force an eager flush — call db.flush() yourself if you need it before a specific boundary |
set_cache_budget(namespace, max_entries, max_bytes) |
Per-namespace LRU cap (defaults 10 000 entries / 64 MiB). On the next cache_put the LRU is evicted until both limits are satisfied |
set_max_snapshots(max) |
Override the snapshot-manifest retention cap (default 256; 0 disables) |
set_vector_cache_budget(bytes) |
v9 files: keep the fp16 vector column in memory while it takes at most bytes (default 96 MiB, about 125K vectors at 384 dims); above it recall reads vectors through the page cache (less memory, slower recall). This handle only |
set_author(name) |
v0.17: stamp _mnemo.author = name on each new record this handle writes (None stops it). This handle only |
post(to, subject, body="", *, refs=None, conversation=None, sender=None, role=None) |
v0.17: post a message to an agent id, role:<role> or all, from sender (else set_author's). Returns a dict (id, to, from, subject, body, refs, conversation, hops, status, delivery, created_at, acked_at) |
inbox(agent=None, role=None, *, unread_only=True, visibility=None) |
v0.17: the messages for agent, its role or everyone, oldest first, never its own; a list of the same dicts. It only reads: mark_seen(ids) records that they were shown |
ack(id, note=None, *, by=None), prune_messages(days=30) |
v0.17: ack a message ("acked" or "unchanged"); delete those acked more than days ago (returns how many) |
task_add(title, body="", *, role=None, after=None, pre_approved=False, slug=None) |
v0.17: queue a task, created by set_author's agent; a slug that exists updates it in place. Returns {"slug", "status", "outcome"} |
task_next(role=None) |
v0.17: take the oldest task for role whose after tasks are done, or one whose owner's claim lapsed: {"task", "token", "expires_at", "reclaimed_from"}, or None |
task_update(slug, status=None, note=None, *, token=None) |
v0.17: move a task along or add a note: {"outcome": "updated", "task"}, with token, expires_at and retaken while the owner holds the claim; or {"outcome": "lost", "reason": "taken_back" | "other_token"} |
tasks(status=None, role=None), task_get(slug) |
v0.17: the tasks as dicts (slug, title, body, role, status, owner, creator, after, pre_approved, created_at, history), oldest first; one, or None |
claim(topic, ttl=None) |
v0.17: claim a topic for set_author's agent for ttl seconds (900 by default, 30 to 86400): {"status": "claimed", "token", "expires_at"} or {"status": "held_by", "agent", "expires_at"}. Advisory: a record, not a lock |
renew(topic, token, ttl=None), release(topic, token), check_claim(topic, token) |
v0.17: {"status": "held", "expires_at"}, {"status": "released"}, or {"status": "lost"} when the claim lapsed or another agent holds it (check before anything irreversible) |
claims(), who(), touch_presence(role=None, tool=None) |
v0.17: the live claims (topic, holder, expires_at, lease); the agents (agent, role, tool, last_active, alive: True, False or None for unknown, claims); record this agent as active (at most once a minute; returns whether it wrote) |
finding_add(id, category, priority, title, body="", *, refs=None), finding_triage(id, status, text), finding_verify(id, ref), findings(status=None, batch=None, category=None, priority=None), finding_get(id) |
v0.18: review findings as dicts (id, batch, category, priority, title, body, refs, author, status, triage, triaged_by, verified_ref, verified_by, created_at, history); an id is unique, and only the allowed transitions are accepted |
default_agent(), set_default_agent(agent) |
v0.17: the agent the manifest names for a write that names none (_mnemo.default_agent), or None; set it, or clear it with None (returns "updated" or "unchanged") |
set_turn_compress_after(secs) |
v9 files: compress thread turns once they're older than secs (default 7 days; 0 compresses at write). This handle only |
memories() |
Enumerate every live (non-deleted, non-expired) memory as a list of dicts |
dimensions() |
Embedding dimensionality this database was created with (also on stats()["dimensions"]) |
rekey(new_passphrase, fast=False) |
Change the passphrase. Re-derives the KEK and re-wraps the DEK; encrypted pages are not rewritten (O(1) in db size). fast=True uses the cheap-Argon2 test params — omit for production. Without it the new passphrase keeps the file's KDF parameters and never gets less than KdfParams::secure(), even on a file made with open_with_key (v0.15). If it raises, the old passphrase is still in force (the one exception is an error that says the file may open with either). If it returns but couldn't scrub every copy of the old key wrap, it emits a RuntimeWarning: the call succeeded and the new passphrase is in force (where warnings are errors, it goes to sys.unraisablehook and the call still returns) |
rekey_cleanup_error() |
After a successful rekey / rekey_with_key: what couldn't be scrubbed of the old key wrap, or None. The same report as the RuntimeWarning, for code that filters warnings. Compact the file to be sure the old secret opens nothing |
use_builtin_embedder(*, model_dir=None) |
v0.15: register the built-in embedder (snowflake-arctic-embed-xs on candle, 384 dimensions) instead of a callable. Its model (91.0 MB) is fetched into the cache directory on first use, said on stderr, and each file's SHA-256 is checked before it loads; model_dir loads the three files from a directory of your own and never downloads. With it, recall_text is identifier-aware: the question's plain words aren't matched by keyword and its identifiers (snapshot_list, store.rs, --features) are, unless you pass keywords. Raises RuntimeError offline or in a build without it |
set_embedder(fn, *, name, dimensions, normalize=True, query_fn=None, query_convention=None) |
Register a Python callable embed(texts: list[str]) -> list[list[float]] as this handle's text embedder (Phase 3). Dimension-checks against the database's width; identity-checks against (and on first use records) the file's embedder identity, so swapping embedders between opens fails loudly. query_fn and query_convention (v0.15), both or neither: a callable of fn's shape that embeds recall_text's queries, for a model that embeds queries differently, and a short name for the difference ("bge-query-instruction"), which becomes part of the identity |
remember_text(content, memory_type, **kwargs) |
Embed content via the registered embedder and remember the result. Accepts the same per-memory kwargs as remember (agent_id, importance, session_id, ttl_secs, shared, metadata, key, supersedes) |
recall_text(query, top_k=10, memory_types=None, agent_id=None, track_access=True, n_probe=None, n_rerank=None, filter=None, max_bytes=None, keywords=None, keyword_weight=None) |
Embed query via the registered embedder and run recall. Same return shape and kwargs as recall. Hybrid by default since v0.15 (v9 files): query itself is also matched by keyword (BM25) with weight 0.25. keywords: identifiers or exact terms the question doesn't contain (a version, a PR number, a function name), which replace the query for that score, with weight 0.5; keyword_weight sets either. keywords="" is vector-only. The query goes through query_fn when set_embedder was given one |
cache_get_semantic_text(namespace, text, threshold=0.97) |
Text-side semantic cache lookup; uses the embedder's name as the semantic cache's model component |
stats() |
Summary statistics — includes fsyncs_last_flush (count of sync_all the most recent flush() on this handle issued; 0 on a fresh handle before any flush — Phase 6 instrumentation) and recall_mode ("exact_resident": the live facts' vectors fit the vector cache budget and recall scans them in memory; "exact_paged": over the budget, or a v8 file, so recall reads them from the file; "indexed": an IVF+PQ index shortlists). Since v0.13 also snapshots_retained, oldest_restorable_at (unix seconds, or None) and snapshot_pinned_bytes: what a restore can reach now, which under churn can be far less than the retention policy. Since v0.15 keyword_tokenizer: "2" (whole words and their parts, a file v0.15 made or rebuilt), "1" (whole words, an older file until mnemo compact), "mixed" (a build before v0.15 wrote to it), or None on v8 |
export_encrypted(dest) |
Copy the (already-encrypted) file elsewhere |
len(db) |
Live memory count |
shared |
True for a handle opened with shared=True |
notices() |
What the handle warns about once; each is also raised as a UserWarning at open. Shared mode: a sidecar directory it can't use, a synced folder, an allowed network filesystem. Any handle (v0.15): a passphrase on raw-key KDF parameters, with the fix (mnemo rekey or mnemo compact) |
set_cancel(token) |
Shared mode: give the handle a new CancelToken (or None) for its later calls, after a cancel |
Plus two module-level functions:
| Function | Purpose |
|---|---|
mnemo.compact_file(path, passphrase) |
Rewrite the file out-of-place, dropping tombstoned and expired memories and reclaiming stale pages. Caller's own plain handle must be closed first; since v0.14 it waits up to 10 s for shared handles' calls. Returns {"before": int, "after": int} |
mnemo.compact_file_with_key(path, key) |
The same for a raw-key file (key: 32 bytes, as from generate_key()), under the same key; converts a v8 file to v9 (since v0.13.1) |
mnemo.CancelToken() |
Shared mode: token.cancel() from another thread cancels a call that is waiting for the file's lock (CancelledError; nothing changes). Pass it as open(..., cancel=token). A cancelled token stays cancelled |
mnemo.install_builtin_embedder() |
v0.15: fetch the built-in embedder's model (91.0 MB) into the cache directory, checking each file's SHA-256, and return the directory; nothing is fetched when it's there. The size and the place are said on stderr first. MNEMO_CACHE_DIR moves the cache, MNEMO_MODEL_URL points at a mirror |
mnemo.builtin_embedder_info() |
v0.15: {"available": bool}, and when the wheel has the built-in embedder, model, revision, identity, dimensions, cache_dir, installed and download_bytes |
mnemo.build_info() |
Returns {"version", "target", "aes_backend", "polyval_backend"} for the installed wheel. Lets you verify an ARM wheel picked up the hardware AES path — aes_backend should read "armv8 hardware" on Apple Silicon / Graviton (anything else, like "armv8 software (constant-time fallback)", means the compile missed the fix). PR 11.0, v0.5.1+ |
Session methods: add_turn(turn), recall(query, top_k=10, memory_types=None),
close(), discard(), id(), agent(), turn_ids(), turn_count(); also a
context manager (exiting consolidates).
Memories and results are returned as plain dicts; metadata round-trips as a
nested dict.
Errors
Since v0.13.1 every engine error is an mnemo_engine.MnemoError, which
subclasses RuntimeError, so except RuntimeError keeps working. The
subclasses tell the cases apart (argument errors the binding catches itself,
before the engine sees them, are still ValueError):
| Exception | What happened | What to do |
|---|---|---|
FormatTooOldError |
the file predates v9: a v8 file opens only with read_only=True, v4–v7 not at all |
run mnemo compact <file> once (--key-file for a raw-key file, or compact_file_with_key); it keeps every live memory |
NeedsWriteOpenError |
the file has pending work (a committed write to finish, a torn header to repair) | open it read-write once; on a pre-v9 file the message says to run mnemo compact instead |
EmbedderMismatchError |
the embedder given isn't the one the file's vectors came from | use the original embedder, or create a new file for the new model |
WrongPassphraseError |
the passphrase or key doesn't open this file | check the secret |
LockedError |
another handle (another process, or one not yet closed) has the file | close it, or open read-only alongside a reader |
ReadOnlyError |
a write on a read_only=True handle |
reopen read-write |
DimensionMismatchError |
a vector of the wrong width | embed with the file's model |
InvalidArgumentError |
a bad argument the engine refused (an all-zero vector, say) | fix the call |
NotFoundError |
the id isn't in the file | |
UnsupportedVersionError |
a file from a newer engine | upgrade mnemo-engine |
NotAMnemoFileError |
not a .mnemo file |
check the path |
CorruptError |
a page or the header failed its integrity check: corrupt or tampered | restore from a backup or an export |
CancelledError |
shared mode: the call was cancelled while it waited for the lock; nothing changed | |
UnsupportedError |
shared mode isn't available here (a network or synced folder, an old Windows build), or a file-wide setting on a shared handle | pass allow_network_fs=True if you know the lock works there; drop the setting |
MaybeStoredError |
shared mode: a write failed after its commit point; it may be in the file | check whether it's there before retrying |
ReplacedDuringWriteError |
shared mode: another file was renamed over the path during the write (an older mnemo compact); the write isn't in the file at the path now |
update every mnemo that opens the file, then write again |
ReplacedError |
the file at the path is no longer the one the handle opened: another file was renamed over it, or it was moved or removed; nothing was written. shared is True in a shared-mode write (an older mnemo compact renamed over the path just before the commit) |
shared true: call again, and the call follows the new file. Otherwise reopen the path, or move a moved brain back |
MnemoError (only) |
I/O, cryptography, key derivation or serialization | the message says which |
import mnemo_engine as mnemo
try:
db = mnemo.open(path, passphrase)
except mnemo.FormatTooOldError:
db = mnemo.open(path, passphrase, read_only=True) # a v8 file; compact it later
Each message is the engine's own, unchanged from before, so code that matched on a message's start keeps working too.
Result caching
MNemo doubles as a durable result cache — memoize LLM tool-call outputs, prompt→completion pairs, HTTP responses, anything reconstructible on miss — in the same encrypted single file that holds your agent memory. See the core README's Result caching section for the concepts (namespaces, budgets, TTL, Strict vs Batched flush policy).
Recipe: @db.cached(...) decorator (~90 lines, pure Python)
Copy this into your project as mnemo_cached.py or paste inline. It
wraps any function whose arguments serialize to JSON, keying the cache
on f"{namespace}:{fn_name}:{json_args}". When embed is supplied it
switches to semantic mode; otherwise it's an exact-key cache.
"""@db.cached — pure-Python helper on top of mnemo.Mnemo's cache API.
Usage:
import mnemo_engine as mnemo, json, os
from mnemo_cached import cached
db = mnemo.open("agent.mnemo", os.environ["MNEMO_PASSPHRASE"])
@cached(db, namespace="llm", ttl=3600)
def call_llm(prompt: str) -> str:
return openai.chat.completions.create(...).choices[0].message.content
# Second call with the same prompt is a cache hit.
answer = call_llm("summarize this doc")
"""
from __future__ import annotations
import functools
import hashlib
import json
from typing import Any, Callable, Optional
def cached(
db,
*,
namespace: str,
ttl: Optional[int] = None,
embed: Optional[Callable[[str], list[float]]] = None,
model: Optional[str] = None,
threshold: float = 0.97,
key_fn: Optional[Callable[..., str]] = None,
):
"""Memoize a function's results into a mnemo.Mnemo cache.
- Exact-key mode (default): key is JSON(args, kwargs) plus fn name.
- Semantic mode: pass `embed=my_embedder` and `model="..."`; the key
is embedded and semantic recall is tried before falling back.
- Custom `key_fn(*args, **kwargs) -> str` overrides the default key.
"""
if embed is not None and model is None:
raise ValueError("semantic mode requires `model=`")
def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
@functools.wraps(fn)
def wrapper(*args, **kwargs):
key = key_fn(*args, **kwargs) if key_fn else _default_key(fn, args, kwargs)
# Try semantic hit first (if configured); otherwise exact-key.
if embed is not None:
vec = embed(key)
hit = db.cache_get_semantic(namespace, vec, model, threshold)
if hit is not None:
return _decode(hit["value"])
# Miss — compute the real result.
result = fn(*args, **kwargs)
encoded = _encode(result)
db.cache_put_semantic(namespace, key, vec, encoded, model, ttl_secs=ttl)
return result
hit = db.cache_get(namespace, key)
if hit is not None:
return _decode(hit["value"])
result = fn(*args, **kwargs)
encoded = _encode(result)
db.cache_put(namespace, key, encoded, ttl_secs=ttl)
return result
return wrapper
return decorator
def _default_key(fn, args, kwargs) -> str:
payload = json.dumps(
{"fn": fn.__qualname__, "args": args, "kwargs": kwargs},
default=str, sort_keys=True,
)
return hashlib.sha256(payload.encode()).hexdigest()
def _encode(v: Any) -> bytes:
if isinstance(v, (bytes, bytearray)):
return bytes(v)
if isinstance(v, str):
return v.encode()
return json.dumps(v, default=str).encode()
def _decode(b: bytes) -> Any:
# Best-effort round-trip: try JSON first, fall back to str, then bytes.
try:
return json.loads(b)
except (json.JSONDecodeError, UnicodeDecodeError):
try:
return b.decode()
except UnicodeDecodeError:
return b
Recipe: OpenAI/Anthropic call wrapped end-to-end
import os, mnemo
from openai import OpenAI
from mnemo_cached import cached
db = mnemo.open("agent.mnemo", os.environ["MNEMO_PASSPHRASE"])
client = OpenAI()
@cached(db, namespace="openai-gpt-4o-mini", ttl=86_400)
def chat(prompt: str) -> str:
r = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": prompt}],
)
return r.choices[0].message.content
# First call → hits the model, caches the response.
# Second identical call → hits the cache, no OpenAI request.
print(chat("Give me a haiku about SQLite."))
print(chat("Give me a haiku about SQLite."))
print("cache stats:", db.cache_stats("openai-gpt-4o-mini"))
Anthropic swap-in — same shape, different client:
import anthropic
from mnemo_cached import cached
client = anthropic.Anthropic()
@cached(db, namespace="claude-3-5-sonnet", ttl=86_400)
def chat(prompt: str) -> str:
r = client.messages.create(
model="claude-3-5-sonnet-latest",
max_tokens=1024,
messages=[{"role": "user", "content": prompt}],
)
return r.content[0].text
Recipe: semantic cache with an embedder
from openai import OpenAI
from mnemo_cached import cached
client = OpenAI()
def embed(text: str) -> list[float]:
return client.embeddings.create(
model="text-embedding-3-small", input=text,
).data[0].embedding
# Semantic mode: prompts that differ in wording but mean the same
# thing hit the same cache entry.
@cached(db, namespace="llm-semantic", ttl=86_400,
embed=embed, model="text-embedding-3-small", threshold=0.97)
def chat(prompt: str) -> str:
return client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": prompt}],
).choices[0].message.content
Note: the database must have been created with dimensions matching
your embedder's output — text-embedding-3-small is 1536-dim,
bge-large-en-v1.5 is 1024-dim, etc. Set at
mnemo.open(path, pw, dimensions=1536) on first creation.
Don't use this for: multi-node fleets where the cache must be consistent across hosts (use Redis / DynamoDB DAX). MNemo's cache is optimized for a single-host agent that owns its cache file.
Recipe: set_embedder + text-only remember / recall
Phase 3 ships a per-handle embedder hook so callers never have to
pass vectors by hand. Register once at open time; every subsequent
remember_text / recall_text / cache_get_semantic_text call on
the handle uses it.
import mnemo_engine as mnemo
from sentence_transformers import SentenceTransformer
model = SentenceTransformer("all-MiniLM-L6-v2") # 384-dim, normalized
def embed(texts: list[str]) -> list[list[float]]:
return model.encode(texts, normalize_embeddings=True).tolist()
db = mnemo.open("agent.mnemo", "pw", dimensions=384)
db.set_embedder(embed, name="all-MiniLM-L6-v2",
dimensions=384, normalize=True)
db.remember_text("the user prefers tea", "semantic",
importance=0.8, agent_id="assistant")
hits = db.recall_text("how does the user like their drinks?", top_k=5)
for h in hits:
print(h["score"], h["content"])
Or with OpenAI's hosted embeddings:
from openai import OpenAI
client = OpenAI()
def embed(texts: list[str]) -> list[list[float]]:
r = client.embeddings.create(model="text-embedding-3-small", input=texts)
return [item.embedding for item in r.data]
db = mnemo.open("agent.mnemo", "pw", dimensions=1536)
db.set_embedder(embed, name="text-embedding-3-small",
dimensions=1536, normalize=False)
The identity (name, dimensions, normalize) is recorded in the file
the first time you set_embedder (since v0.13 on every file, with or
without a manifest; a file with a manifest also keeps it there).
Reopening with a different embedder — say you swap MiniLM for BGE on
the same file — raises RuntimeError: embedder identity mismatch: this file's vectors come from embedder (name="all-MiniLM-L6-v2", …), but the embedder given is (name="bge-large-en-v1.5", …). Open the file with its original embedder, or create a new store for the new model. A file from
before v0.13 records the first embedder attached after the upgrade.
Mnemo also now refuses any remember call with an all-zero vector,
so a mis-wired embedder (returning [0.0] * dims) fails loudly on
the first write instead of polluting recall silently.
License
Apache-2.0.
Metadata
Release files for mnemo-engine 0.18.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mnemo_engine-0.18.0.tar.gz | 769.5 kB | With provenance | Details for mnemo_engine-0.18.0.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| mnemo_engine-0.18.0-cp38-abi3-win_amd64.whl | CPython 3.8 | abi3 | Windows x86-64 | Details for mnemo_engine-0.18.0-cp38-abi3-win_amd64.whl |
| mnemo_engine-0.18.0-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl | CPython 3.8 | abi3 | Linux glibc 2.17+ x86-64 | Details for mnemo_engine-0.18.0-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
| mnemo_engine-0.18.0-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl | CPython 3.8 | abi3 | Linux glibc 2.17+ ARM64 | Details for mnemo_engine-0.18.0-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl |
| mnemo_engine-0.18.0-cp38-abi3-macosx_11_0_arm64.whl | CPython 3.8 | abi3 | macOS 11.0+ ARM64 | Details for mnemo_engine-0.18.0-cp38-abi3-macosx_11_0_arm64.whl |
| mnemo_engine-0.18.0-cp38-abi3-macosx_10_12_x86_64.whl | CPython 3.8 | abi3 | macOS 10.12+ x86-64 | Details for mnemo_engine-0.18.0-cp38-abi3-macosx_10_12_x86_64.whl |
Total release size: 24.1 MB
Release files / mnemo_engine-0.18.0.tar.gz
| Download URL | mnemo_engine-0.18.0.tar.gz |
|---|---|
| Size | 769.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
aace69817720bdf300232046fb5e56fa09afe392264ac0f3361b5b022fec3465
|
|
BLAKE2b-256 checksum How to use checksums |
4fd545b55eb71690176174a59587afaacf282ba4689a9f20e0c7ca451ea9df8c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logRelease files / mnemo_engine-0.18.0-cp38-abi3-win_amd64.whl
| Download URL | mnemo_engine-0.18.0-cp38-abi3-win_amd64.whl |
|---|---|
| Size | 4.8 MB |
| Tags | CPython 3.8 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
6801afbee1879bf083862fb23899e29e0b123cbb71bfed98aa7d02d39bd9d31b
|
|
BLAKE2b-256 checksum How to use checksums |
64f0b83509e20d16447f8669f1c84ca9004208374fc0e0cb158780d1324ee950
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logRelease files / mnemo_engine-0.18.0-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
| Download URL | mnemo_engine-0.18.0-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
|---|---|
| Size | 5.1 MB |
| Tags | CPython 3.8 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
37e1f82ff6f6bf33ca2b40f0a028a0f51a9bdf0d54ab739c423f727a44a1e5ee
|
|
BLAKE2b-256 checksum How to use checksums |
211f65b68625139c0deed1d8cb08549f262a4501f27610e1923b1826bfc90745
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logRelease files / mnemo_engine-0.18.0-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
| Download URL | mnemo_engine-0.18.0-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl |
|---|---|
| Size | 4.8 MB |
| Tags | CPython 3.8 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
08af878718fb79c74fa0f9b073eb5bb8e9b9043f67ab8782f4452fbabeca62d5
|
|
BLAKE2b-256 checksum How to use checksums |
63a371f0511f22e24542b258ae85c59a69fc54f2337f3e462583e1aec2d66ba5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logRelease files / mnemo_engine-0.18.0-cp38-abi3-macosx_11_0_arm64.whl
| Download URL | mnemo_engine-0.18.0-cp38-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 4.1 MB |
| Tags | CPython 3.8 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
ad747441167292ab0c977107f38c3e86cbb9e6a3b527bd2e049c33f2e2c5e52a
|
|
BLAKE2b-256 checksum How to use checksums |
972e40bc345df082b176ea7aecb20a516d0bdc7bbcb9a3b05192045dbd235c86
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logRelease files / mnemo_engine-0.18.0-cp38-abi3-macosx_10_12_x86_64.whl
| Download URL | mnemo_engine-0.18.0-cp38-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 4.6 MB |
| Tags | CPython 3.8 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
53cd7dc30a1fcd4f0d33a448d96085e1cbeaad1deaad0e119452a88791723326
|
|
BLAKE2b-256 checksum How to use checksums |
88c0726877241e90277099f49f510a1cc74223ae846726c129d06437a8a43aca
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logSecurity for mnemo-engine 0.18.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 6 files in this release have been uploaded with provenance metadata.
Attestation for mnemo_engine-0.18.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.