Skip to main content

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 (both mnemo and mnemo-db were already taken by unrelated projects). The import name is mnemo_engine starting in v0.7.0, so the full setup is pip install mnemo-engine then import mnemo_engine. The pre-v0.7.0 import mnemo keeps working for the v0.7.x series via a pure-Python shim that emits one DeprecationWarning on import; the shim is removed in v0.8.0. Code that wants to keep its call sites unchanged can import 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-engine directly): set RUSTFLAGS="--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 with mnemo.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, refs=None) v0.17: queue a task, created by set_author's agent; a slug that exists updates it in place. refs (v0.18.1): what it's about, such as a finding's id. 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.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mnemo-engine 0.18.1
File Size Uploaded Provenance Actions
mnemo_engine-0.18.1.tar.gz 774.9 kB With provenance Details for mnemo_engine-0.18.1.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for mnemo-engine 0.18.1
File Actions
mnemo_engine-0.18.1-cp38-abi3-win_amd64.whl CPython 3.8 abi3 Windows x86-64 Details for mnemo_engine-0.18.1-cp38-abi3-win_amd64.whl
mnemo_engine-0.18.1-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.1-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
mnemo_engine-0.18.1-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl CPython 3.8 abi3 Linux glibc 2.17+ ARM64 Details for mnemo_engine-0.18.1-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
mnemo_engine-0.18.1-cp38-abi3-macosx_11_0_arm64.whl CPython 3.8 abi3 macOS 11.0+ ARM64 Details for mnemo_engine-0.18.1-cp38-abi3-macosx_11_0_arm64.whl
mnemo_engine-0.18.1-cp38-abi3-macosx_10_12_x86_64.whl CPython 3.8 abi3 macOS 10.12+ x86-64 Details for mnemo_engine-0.18.1-cp38-abi3-macosx_10_12_x86_64.whl

Total release size: 24.2 MB

Release files / mnemo_engine-0.18.1.tar.gz

Download URL mnemo_engine-0.18.1.tar.gz
Size 774.9 kB
Tags Source
SHA-256 checksum
How to use checksums
d0935b016bda309c62898829414c2797e415a2389cddda308575cb2029a14466
BLAKE2b-256 checksum
How to use checksums
74dd59c4c6a9a81d5a305523fe6fe35deb881192acbdd1e78ddd8197a2c905b0
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 18, 2026.

Transparency log

Release files / mnemo_engine-0.18.1-cp38-abi3-win_amd64.whl

Download URL mnemo_engine-0.18.1-cp38-abi3-win_amd64.whl
Size 4.8 MB
Tags CPython 3.8 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
63b9e3c06f8732528130e5932f150a72579e5bb5134c09f6346dd2156766389d
BLAKE2b-256 checksum
How to use checksums
c7f6752fb40871d8fd5b09522c51db0375807692e5c1d1ac66b211fae97a9209
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 18, 2026.

Transparency log

Release files / mnemo_engine-0.18.1-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL mnemo_engine-0.18.1-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
02ca9a4ec54c4eb081fffce903cd35a7951be45a9822add2a781b97287cf0619
BLAKE2b-256 checksum
How to use checksums
4c169a0a5c6027cbbb746688cc93004a7a377eeeedb3f6780ffe8f5031e8a668
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 18, 2026.

Transparency log

Release files / mnemo_engine-0.18.1-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL mnemo_engine-0.18.1-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
dbb30c61634742580f23c7063e5f04bd067417a463eb4a837c6a576b5485f7bd
BLAKE2b-256 checksum
How to use checksums
c4b3a543cc96e7d6738f75e636e65666622dd9327acc076408f2e8bd3397faaf
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 18, 2026.

Transparency log

Release files / mnemo_engine-0.18.1-cp38-abi3-macosx_11_0_arm64.whl

Download URL mnemo_engine-0.18.1-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
2680083f73b79c85d25e473d76c1de7fbcc514dd572a0f99cebecddbb840bb24
BLAKE2b-256 checksum
How to use checksums
c448ec1378e17b8538fc3797da4c63dd5d3a8243e3f9b652e32826bfb419bf42
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 18, 2026.

Transparency log

Release files / mnemo_engine-0.18.1-cp38-abi3-macosx_10_12_x86_64.whl

Download URL mnemo_engine-0.18.1-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
2e8439f190f7f12d961d2b7bf8553ecf1745288757a7c2cc9d68db498273ca3e
BLAKE2b-256 checksum
How to use checksums
12b2ce5c1292875e73c503b0f284bfb929ecb5640b675416f42fca01b4b6d987
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 18, 2026.

Transparency log

Security for mnemo-engine 0.18.1

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.

Select from 6 files

Attestation for mnemo_engine-0.18.1.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 18, 2026.

Transparency log

A 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.

Release history Release notifications | RSS feed

This release

0.18.1 This release

6 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page