mnemo-engine 0.4.0__tar.gz → 0.5.0__tar.gz

{mnemo_engine-0.4.0 → mnemo_engine-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mnemo-engine
-Version: 0.4.0
+Version: 0.5.0
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: Apache Software License
@@ -155,11 +155,26 @@ its own agent.
 | `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) |
+| `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 |
+| `set_embedder(fn, *, name, dimensions, normalize=True)` | 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 upserts) the scaffold manifest's `embedder_name` / `embedder_dimensions` / `embedder_normalize` keys, so swapping embedders between opens fails loudly |
+| `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`) |
+| `recall_text(query, top_k=10, memory_types=None, agent_id=None, track_access=True)` | Embed `query` via the registered embedder and run `recall`. Same return shape as `recall` |
+| `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 |
 | `export_encrypted(dest)` | Copy the (already-encrypted) file elsewhere |
 | `len(db)` | Live memory count |
 
+Plus one module-level function:
+
+| 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 handle must be closed first. Returns `{"before": int, "after": int}` |
+
 `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).
@@ -359,6 +374,61 @@ your embedder's output — `text-embedding-3-small` is 1536-dim,
 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.
+
+```python
+import 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:
+
+```python
+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 persisted on the
+scaffold manifest the first time you `set_embedder`. Reopening with a
+*different* embedder — say you swap MiniLM for BGE on the same file —
+raises `RuntimeError: embedder identity mismatch: database manifest
+records embedder (name="all-MiniLM-L6-v2", …), but this handle was
+passed embedder (name="bge-large-en-v1.5", …). Mixing embedders
+silently corrupts recall quality — open the file with the original
+embedder, or create a fresh database for the new one.`
+
+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.

{mnemo_engine-0.4.0 → mnemo_engine-0.5.0}/README.md

@@ -141,11 +141,26 @@ its own agent.
 | `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) |
+| `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 |
+| `set_embedder(fn, *, name, dimensions, normalize=True)` | 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 upserts) the scaffold manifest's `embedder_name` / `embedder_dimensions` / `embedder_normalize` keys, so swapping embedders between opens fails loudly |
+| `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`) |
+| `recall_text(query, top_k=10, memory_types=None, agent_id=None, track_access=True)` | Embed `query` via the registered embedder and run `recall`. Same return shape as `recall` |
+| `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 |
 | `export_encrypted(dest)` | Copy the (already-encrypted) file elsewhere |
 | `len(db)` | Live memory count |
 
+Plus one module-level function:
+
+| 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 handle must be closed first. Returns `{"before": int, "after": int}` |
+
 `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).
@@ -345,6 +360,61 @@ your embedder's output — `text-embedding-3-small` is 1536-dim,
 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.
+
+```python
+import 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:
+
+```python
+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 persisted on the
+scaffold manifest the first time you `set_embedder`. Reopening with a
+*different* embedder — say you swap MiniLM for BGE on the same file —
+raises `RuntimeError: embedder identity mismatch: database manifest
+records embedder (name="all-MiniLM-L6-v2", …), but this handle was
+passed embedder (name="bge-large-en-v1.5", …). Mixing embedders
+silently corrupts recall quality — open the file with the original
+embedder, or create a fresh database for the new one.`
+
+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.

{mnemo_engine-0.4.0 → mnemo_engine-0.5.0}/mnemo/Cargo.lock

@@ -120,6 +120,21 @@ version = "1.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8c3c1a368f70d6cf7302d78f8f7093da241fb8e8807c05cc9e51a125895a6d5b"
 
+[[package]]
+name = "bit-set"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0700ddab506f33b20a03b13996eccd309a48e5ff77d0d95926aa0210fb4e95f1"
+dependencies = [
+ "bit-vec",
+]
+
+[[package]]
+name = "bit-vec"
+version = "0.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "349f9b6a179ed607305526ca489b34ad0a41aed5f7980fa90eb03160b69598fb"
+
 [[package]]
 name = "bitflags"
 version = "2.11.1"
@@ -293,6 +308,12 @@ version = "2.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6"
 
+[[package]]
+name = "fnv"
+version = "1.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1"
+
 [[package]]
 name = "fs4"
 version = "0.9.1"
@@ -399,6 +420,12 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "lazy_static"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
+
 [[package]]
 name = "libc"
 version = "0.2.186"
@@ -415,6 +442,12 @@ dependencies = [
  "windows-link",
 ]
 
+[[package]]
+name = "libm"
+version = "0.2.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981"
+
 [[package]]
 name = "linux-raw-sys"
 version = "0.4.15"
@@ -429,13 +462,14 @@ checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
 
 [[package]]
 name = "mnemo-engine"
-version = "0.4.0"
+version = "0.5.0"
 dependencies = [
  "aes-gcm",
  "argon2",
  "base64ct",
  "clap",
  "fs4",
+ "proptest",
  "rand",
  "rmp",
  "rmp-serde",
@@ -451,7 +485,7 @@ dependencies = [
 
 [[package]]
 name = "mnemo-node"
-version = "0.4.0"
+version = "0.5.0"
 dependencies = [
  "mnemo-engine",
  "napi",
@@ -523,6 +557,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
 dependencies = [
  "autocfg",
+ "libm",
 ]
 
 [[package]]
@@ -596,6 +631,32 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "proptest"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4c2511913b88df1637da85cc8d96ec8e43a3f8bb8ccb71ee1ac240d6f3df58d"
+dependencies = [
+ "bit-set",
+ "bit-vec",
+ "bitflags",
+ "lazy_static",
+ "num-traits",
+ "rand",
+ "rand_chacha",
+ "rand_xorshift",
+ "regex-syntax",
+ "rusty-fork",
+ "tempfile",
+ "unarray",
+]
+
+[[package]]
+name = "quick-error"
+version = "1.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a1d01941d82fa2ab50be1e79e6714289dd7cde78eba4c074bc5a4374f650dfe0"
+
 [[package]]
 name = "quote"
 version = "1.0.45"
@@ -607,9 +668,9 @@ dependencies = [
 
 [[package]]
 name = "rand"
-version = "0.8.5"
+version = "0.8.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404"
+checksum = "5ca0ecfa931c29007047d1bc58e623ab12e5590e8c7cc53200d5202b69266d8a"
 dependencies = [
  "libc",
  "rand_chacha",
@@ -635,6 +696,15 @@ dependencies = [
  "getrandom",
 ]
 
+[[package]]
+name = "rand_xorshift"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d25bf25ec5ae4a3f1b92f929810509a2f53d7dca2f50b794ff57e3face536c8f"
+dependencies = [
+ "rand_core",
+]
+
 [[package]]
 name = "regex"
 version = "1.12.3"
@@ -726,6 +796,18 @@ version = "1.0.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
 
+[[package]]
+name = "rusty-fork"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc6bf79ff24e648f6da1f8d1f011e9cac26491b619e6b9280f2b47f1774e6ee2"
+dependencies = [
+ "fnv",
+ "quick-error",
+ "tempfile",
+ "wait-timeout",
+]
+
 [[package]]
 name = "ryu"
 version = "1.0.23"
@@ -860,6 +942,12 @@ dependencies = [
  "web-time",
 ]
 
+[[package]]
+name = "unarray"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eaea85b334db583fe3274d12b4cd1880032beab409c0d774be044d4480ab9a94"
+
 [[package]]
 name = "unicode-ident"
 version = "1.0.24"
@@ -894,6 +982,15 @@ version = "0.9.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
 
+[[package]]
+name = "wait-timeout"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09ac3b126d3914f9849036f826e054cbabdc8519970b8998ddaf3b5bd3c65f11"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "wasi"
 version = "0.11.1+wasi-snapshot-preview1"

{mnemo_engine-0.4.0 → mnemo_engine-0.5.0}/mnemo/Cargo.toml

@@ -6,7 +6,7 @@
 # below stay `mnemo`, so consumers still write `use mnemo::...` and invoke
 # `mnemo` on the command line after `cargo add mnemo-engine`.
 name = "mnemo-engine"
-version = "0.4.0"
+version = "0.5.0"
 edition = "2021"
 rust-version = "1.75"
 description = "Encrypted, single-file, portable agent memory engine with multi-signal recall, sessions, snapshots, and an IVF+PQ index"
@@ -55,7 +55,14 @@ base64ct = "=1.6.0"
 ulid = { version = "=1.1.3", features = ["serde"] }
 thiserror = "=1.0.64"
 zeroize = "=1.8.1"
-rand = "=0.8.5"
+# Pinned `=0.8.6` (patch bump from 0.8.5) to close RUSTSEC-2026-0097,
+# an unsoundness that only triggers under a very narrow config —
+# custom `log::Log` impl reentrantly calling `rand::rng()` on
+# `ThreadRng` mid-reseed — which mnemo does not do. The engine
+# never touches `log`, and no CLI code paths reach `ThreadRng` from
+# a logger. Upgrading anyway is the least-surprising thing to do
+# and satisfies the `advisories` check without an ignore.
+rand = "=0.8.6"
 clap = { version = "=4.4.18", features = ["derive"] }
 # Used by the `mnemo` CLI binary only — `passphrase()` calls it when stdin
 # is a TTY to read the passphrase without echo. The library never touches
@@ -77,6 +84,19 @@ sha2 = "=0.10.8"
 
 [dev-dependencies]
 tempfile = "=3.10.1"
+# Property-based testing (Phase 1.3). Pinned exactly; `=1.5.0`'s MSRV
+# is Rust 1.65, well under our 1.75 floor. Kept as a dev-dep only —
+# it does not appear in the shipped library dependency set.
+proptest = "=1.5.0"
+
+[features]
+# When enabled, exposes crash-injection hooks used by the Phase 1.3
+# proptest under `mnemo::__failpoints::*`. Always enabled during
+# `cargo test` via `#[cfg(test)]`; the feature is here so an external
+# fault-injection consumer (or a future integration test in a sibling
+# crate) can opt into the same hooks without touching this crate's
+# tests. Not for production use — never enable in a release build.
+failpoints = []
 
 [profile.release]
 lto = true

{mnemo_engine-0.4.0 → mnemo_engine-0.5.0}/mnemo/README.md

@@ -41,10 +41,55 @@ mnemo serve --mcp path/to/agent.mnemo
 
 The passphrase is read from `MNEMO_PASSPHRASE` (never a CLI flag — that
 would leak into shell history and process listings). Tools exposed:
-`about`, `remember`, `recall`, `forget`, `list`, `snapshot_list`, `stats`.
-Every mutation flushes before returning. `remember` and `recall` are
-embedder-agnostic — the caller supplies vectors; text-only variants
-land with Phase 3 of the level-up plan.
+`about`, `remember`, `recall`, `forget`, `list`, `snapshot_list`, `stats`,
+`cache_put`, `cache_get`, `cache_stats`, `cache_put_semantic`,
+`cache_get_semantic`. Every mutation flushes before returning.
+
+#### Text-in via `--embed-cmd` (Phase 3)
+
+`remember`, `recall`, `cache_put_semantic`, and `cache_get_semantic`
+accept **either** a caller-supplied `vector`/`query` **or** a `text`
+string that the server embeds for them. Enable the text path by passing
+an embedder command at serve start:
+
+```sh
+MNEMO_PASSPHRASE=... mnemo serve --mcp agent.mnemo \
+  --embed-cmd "python3 mnemo/examples/embedder_server.py" \
+  --embed-name "sentence-transformers/all-MiniLM-L6-v2"
+```
+
+The embedder is a **persistent child process** spawned once at serve
+start. Protocol: it reads one JSON-encoded string per line from stdin
+and writes one JSON array of floats per line to stdout, flushed after
+every reply. See `mnemo/examples/embedder_server.py` for a 10-line
+reference implementation (sentence-transformers + MiniLM, 384-dim).
+
+> **Stdout is for replies only.** Any line the embedder prints to
+> stdout outside a reply — startup banners, model-load progress,
+> warnings, "model loaded" messages — is a protocol violation and
+> would shift every subsequent reply by one line. EmbedCmd detects
+> it, kills the child, and surfaces a clear error ("stdout is
+> reserved for replies only; log to stderr instead"); the next call
+> respawns the child. **Log to stderr.** Python: `print("...",
+> file=sys.stderr, flush=True)`, or configure `logging` with
+> `stream=sys.stderr`. Stderr is inherited to the parent and is
+> safe for anything you want to see while the server runs.
+
+Per-request timeout defaults to 60 seconds; override with
+`--embed-timeout <secs>` on `serve`, `remember`, and `recall`. Set
+it longer than your slowest cold-start reply (sentence-transformers'
+first `encode()` on CPU can be 3–5s). On timeout — or any other
+protocol error (malformed JSON, wrong dimensionality, zero vector,
+unexpected EOF) — the child is killed and the next call respawns a
+fresh child with the same argv/env/timeout. The guarantee is
+asymmetric and deliberate: **an error is allowed; a mismatched
+vector never is.**
+
+The `--embed-name` string is matched against (and persisted on) the
+scaffold manifest's `metadata.embedder = { name, dimensions, normalize }`
+object. Starting a server with a different `--embed-name` on an existing
+file fails loudly — mixing embedders in one file silently corrupts
+recall quality.
 
 Claude Desktop config snippet (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 
@@ -53,13 +98,39 @@ Claude Desktop config snippet (`~/Library/Application Support/Claude/claude_desk
   "mcpServers": {
     "mnemo": {
       "command": "mnemo",
-      "args": ["serve", "--mcp", "/absolute/path/to/agent.mnemo"],
+      "args": [
+        "serve", "--mcp", "/absolute/path/to/agent.mnemo",
+        "--embed-cmd", "python3 /absolute/path/to/embedder_server.py",
+        "--embed-name", "sentence-transformers/all-MiniLM-L6-v2"
+      ],
       "env": { "MNEMO_PASSPHRASE": "your-passphrase-here" }
     }
   }
 }
 ```
 
+Omit `--embed-cmd`/`--embed-name` to keep the pre-Phase-3
+embedder-agnostic behavior (`vector`/`query` only).
+
+#### CLI text path
+
+The same `--embed-cmd` + `--embed-name` pair works on the one-shot
+CLI commands:
+
+```sh
+mnemo remember agent.mnemo --text "the user prefers tea" \
+  --type semantic --importance 0.8 --agent assistant \
+  --embed-cmd "python3 embedder_server.py" \
+  --embed-name "sentence-transformers/all-MiniLM-L6-v2"
+
+mnemo recall agent.mnemo --text "what drink?" --top-k 5 \
+  --embed-cmd "python3 embedder_server.py" \
+  --embed-name "sentence-transformers/all-MiniLM-L6-v2" \
+  --no-track
+```
+
+`--text` is mutually exclusive with `--query`/`--query-file`.
+
 The server holds an exclusive write lock on the file for its lifetime
 (see [Concurrency](#concurrency--read-only-opens)), so two MCP servers
 on the same file will conflict — one will fail to start with

mnemo_engine-0.5.0/mnemo/deny.toml

@@ -0,0 +1,131 @@
+# cargo-deny configuration (Phase 1.4).
+#
+# Runs in CI on every PR via `cargo deny check` in `mnemo/`. Three
+# checks matter here:
+#   1. `advisories` — cross-references the RustSec advisory DB and
+#      fails on any unpatched vulnerability affecting a dep in the
+#      lockfile.
+#   2. `licenses` — allowlist of OSI-approved licenses compatible
+#      with the Apache-2.0 the mnemo crate itself is published under.
+#      Anything unlisted requires an explicit `exceptions` entry.
+#   3. `bans` — currently informational (`multiple-versions = "warn"`)
+#      to catch transitive duplication without blocking merges while
+#      we enumerate the necessary skip set. Follow-up PR will
+#      tighten to `deny` once CI has surfaced the real exception
+#      list.
+#
+# Run locally with:
+#     cd mnemo && cargo deny check
+#
+# For just one check:
+#     cargo deny check advisories
+#     cargo deny check licenses
+#     cargo deny check bans
+
+# ---------------------------------------------------------------------
+# Graph configuration — what crates the checks apply to.
+# ---------------------------------------------------------------------
+
+[graph]
+# Empty `targets` means "check all crates for all target triples the
+# lockfile references." Since mnemo compiles on Linux/macOS/Windows
+# x86_64+aarch64, restricting to a single target would hide license /
+# advisory hits on platform-specific transitives (e.g. `windows-sys`
+# on Windows only).
+targets = []
+all-features = false
+no-default-features = false
+
+[output]
+# Group violations by feature depth; keeps the diagnostic readable
+# on the multi-page transitive graph typical of a Rust crate.
+feature-depth = 1
+
+# ---------------------------------------------------------------------
+# Advisory DB — RustSec vulnerability + yanked-crate check.
+# ---------------------------------------------------------------------
+
+[advisories]
+version = 2
+db-path = "~/.cargo/advisory-db"
+db-urls = ["https://github.com/rustsec/advisory-db"]
+# `yanked` fires when Cargo.lock pins a version the author later
+# yanked from crates.io. `warn` first so we notice; upgrade to
+# `deny` once we've picked up a clean baseline.
+yanked = "warn"
+# Time-boxed / justified exceptions to the advisory check. Every
+# entry must carry a `reason` — a future worker reading this file
+# should be able to tell why the ignore was granted without leaving
+# the config.
+ignore = [
+    # `paste 1.0.15` — dtolnay archived the repo (RUSTSEC-2024-0436,
+    # "unmaintained"). NOT a vulnerability. It is pulled transitively
+    # by `rmp` / `rmp-serde` (our MessagePack layer) which have no
+    # migration path today. The advisory itself suggests `pastey` as
+    # a drop-in fork; that migration lives in `rmp`, not here. Revisit
+    # when `rmp-serde` ships a release that swaps to `pastey`.
+    { id = "RUSTSEC-2024-0436", reason = "paste (unmaintained) is a transitive dep of rmp-serde; no upstream migration path yet — track via rmp-serde issue tracker" },
+]
+
+# ---------------------------------------------------------------------
+# Licenses — SPDX allowlist. Anything not listed → build fails.
+# ---------------------------------------------------------------------
+
+[licenses]
+version = 2
+# Kept minimal — the mnemo dep graph in practice only ships crates
+# under Apache-2.0, MIT, BSD-3-Clause, and Unicode-3.0 (the newer
+# SPDX variant `unicode-ident` uses). Apache-2.0 WITH LLVM-exception
+# covers the `rustix` family. Adding an unused allow is not a security
+# hole but it's noise — cargo-deny prints an "unmatched license
+# allowance" warning for each, and drift in the allowlist becomes
+# hard to notice. Extend this list only when a new dep actually
+# ships under something not already here.
+allow = [
+    "Apache-2.0",
+    "Apache-2.0 WITH LLVM-exception",
+    "MIT",
+    "BSD-2-Clause",
+    "BSD-3-Clause",
+    "Unicode-3.0",
+]
+# Threshold for guessing a license from a LICENSE file's text when
+# the crate omits SPDX metadata. Default 0.8 is conservative — lower
+# it only if a specific crate needs a `[[licenses.clarify]]` entry.
+confidence-threshold = 0.8
+# Per-crate license overrides go here if a crate ships an unusual
+# LICENSE mix cargo-deny can't parse. Empty at PR 9 landing;
+# expand as CI surfaces cases.
+exceptions = []
+
+# ---------------------------------------------------------------------
+# Bans — duplicate versions, wildcard deps, per-crate allow/deny.
+# ---------------------------------------------------------------------
+
+[bans]
+# `warn` for now: transitive graphs commonly duplicate `syn 1/2`,
+# `regex-syntax 0.6/0.8`, `bitflags 1/2`, `windows-sys 0.4x/0.5x`
+# during migrations. First green CI run will list the actual
+# duplicates; follow-up PR flips to `deny` with the enumerated
+# `skip` entries.
+multiple-versions = "warn"
+wildcards = "allow"
+highlight = "all"
+workspace-default-features = "allow"
+external-default-features = "allow"
+allow = []
+deny = []
+skip = []
+skip-tree = []
+
+# ---------------------------------------------------------------------
+# Sources — where crates may come from.
+# ---------------------------------------------------------------------
+
+[sources]
+unknown-registry = "warn"
+unknown-git = "warn"
+# Only crates.io. No git deps in mnemo (all pinned to `=x.y.z` per
+# AGENTS.md), so this stays tight.
+allow-registry = ["https://github.com/rust-lang/crates.io-index"]
+allow-git = []