memoryintelligence-mcp 0.1.12__tar.gz → 0.2.0__tar.gz

{memoryintelligence_mcp-0.1.12 → memoryintelligence_mcp-0.2.0}/CHANGELOG.md

@@ -3,6 +3,27 @@
 All notable changes to `memoryintelligence-mcp` are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/); this project uses [Semantic Versioning](https://semver.org/).
 
+## [0.2.0] — 2026-07-04
+
+### Added — the local vault (Path A), previously built on `main` but never released
+The published `0.1.12` shipped as a thin cloud client; the entire local-vault stack
+landed on `main` afterward **under the same version number** and was never cut into a
+release. This release publishes it (release-hygiene fix — no new code, just a version
+bump over what `main` already carried).
+
+- **`backfill --execute` now writes the local vault** (`cli.py`): the cloud → local
+  migration re-embeds each memory locally, encrypts to the owner's key, and writes a
+  signed `.umo`. The prior published build's `--execute` was a dry-run stub.
+- **Offline reads** — `local_index.py` + `localreads.py` + `indexer.py`: a flat-numpy
+  cosine index over the decrypted vault, mirroring the hosted ranking, so `mi_ask` works
+  network-free (needs the `[local]` extra: `cryptography` + `numpy`).
+- **`mi-mcp index {build,stat,path}`** — build/inspect the local vector index.
+- **On-device redaction** (`scrub.py`) applied on the local read path.
+- **`embedder.py`** — local bge-small embeddings for backfill + query.
+- Note (MI#653): `mi-mcp` still defaults its vault to `~/MemoryIntelligence`; the
+  MemorySpace Desktop vault is `~/Somewhere`. Until `wire`/`setup` sets
+  `MI_VAULT=~/Somewhere`, point it there manually so the two surfaces share one vault.
+
 ## [0.1.12] — 2026-06-16
 
 ### Fixed

{memoryintelligence_mcp-0.1.12 → memoryintelligence_mcp-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memoryintelligence-mcp
-Version: 0.1.12
+Version: 0.2.0
 Summary: MCP server for MemoryIntelligence — give Claude a memory you own, set up in one command
 Project-URL: Homepage, https://memoryintelligence.io
 Project-URL: Repository, https://github.com/somewhere11/memoryintelligence-mcp
@@ -26,12 +26,14 @@ Requires-Dist: mcp[cli]<2.0,>=1.0.0
 Requires-Dist: pydantic<3.0,>=2.5.0
 Provides-Extra: dev
 Requires-Dist: cryptography<46,>=42.0; extra == 'dev'
+Requires-Dist: fastembed<1.0,>=0.3.0; extra == 'dev'
 Requires-Dist: numpy<3,>=1.24; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.4.0; extra == 'dev'
 Provides-Extra: local
 Requires-Dist: cryptography<46,>=42.0; extra == 'local'
+Requires-Dist: fastembed<1.0,>=0.3.0; extra == 'local'
 Requires-Dist: numpy<3,>=1.24; extra == 'local'
 Description-Content-Type: text/markdown
 
@@ -79,10 +81,17 @@ API key is ever written into a config file.**
 
 > Prefer no install? `uvx memoryintelligence-mcp --help` runs it via `uv` with
 > nothing to install. (You'll still run `mi-mcp setup` once to store your key + wire.)
+>
+> **Note on `--help`:** the admin subcommands (`setup`, `wire`, `doctor`, `status`)
+> are dispatched before the argument parser, so they're listed in `--help`'s footer
+> rather than as standard subcommands — `mi-mcp setup` is real even though it isn't a
+> `--help` subparser. For persistent use prefer `uv tool install memoryintelligence-mcp`
+> over bare `uvx`: the launcher Claude Desktop spawns resolves the binary from `PATH` /
+> `~/.local/bin`, not `uvx`'s ephemeral cache.
 
 ---
 
-## ✅ What works today (0.1.10)
+## ✅ What works today (0.2.0)
 
 Honest status — this is beta, so here's exactly what's live:
 

{memoryintelligence_mcp-0.1.12 → memoryintelligence_mcp-0.2.0}/README.md

@@ -42,10 +42,17 @@ API key is ever written into a config file.**
 
 > Prefer no install? `uvx memoryintelligence-mcp --help` runs it via `uv` with
 > nothing to install. (You'll still run `mi-mcp setup` once to store your key + wire.)
+>
+> **Note on `--help`:** the admin subcommands (`setup`, `wire`, `doctor`, `status`)
+> are dispatched before the argument parser, so they're listed in `--help`'s footer
+> rather than as standard subcommands — `mi-mcp setup` is real even though it isn't a
+> `--help` subparser. For persistent use prefer `uv tool install memoryintelligence-mcp`
+> over bare `uvx`: the launcher Claude Desktop spawns resolves the binary from `PATH` /
+> `~/.local/bin`, not `uvx`'s ephemeral cache.
 
 ---
 
-## ✅ What works today (0.1.10)
+## ✅ What works today (0.2.0)
 
 Honest status — this is beta, so here's exactly what's live:
 

{memoryintelligence_mcp-0.1.12 → memoryintelligence_mcp-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "memoryintelligence-mcp"
-version = "0.1.12"
+version = "0.2.0"
 description = "MCP server for MemoryIntelligence — give Claude a memory you own, set up in one command"
 readme = "README.md"
 license = "MIT"
@@ -43,6 +43,9 @@ Documentation = "https://memoryintelligence.io/docs/api-reference"
 local = [
     "cryptography>=42.0,<46",
     "numpy>=1.24,<3",
+    # Local-first ONNX embedder (bge-small) for network-free reads. Pulls
+    # onnxruntime — real weight, hence kept out of the thin base install.
+    "fastembed>=0.3.0,<1.0",
 ]
 dev = [
     "pytest>=8.0",
@@ -50,6 +53,7 @@ dev = [
     "ruff>=0.4.0",
     "cryptography>=42.0,<46",
     "numpy>=1.24,<3",
+    "fastembed>=0.3.0,<1.0",
 ]
 
 [project.scripts]

{memoryintelligence_mcp-0.1.12 → memoryintelligence_mcp-0.2.0}/src/mi_mcp/__init__.py

@@ -1,3 +1,3 @@
 """MI MCP Server — MemoryIntelligence tools for Claude."""
 
-__version__ = "0.1.12"
+__version__ = "0.2.0"

{memoryintelligence_mcp-0.1.12 → memoryintelligence_mcp-0.2.0}/src/mi_mcp/__main__.py

@@ -29,13 +29,27 @@ def main():
     # Admin subcommands: `mi-mcp {setup|init|wire|doctor|status|memory}`. Bare
     # `mi-mcp` (no subcommand) runs the server — that's how the MCP host spawns it.
     argv = sys.argv[1:]
-    if argv and argv[0] in ("setup", "init", "wire", "doctor", "status", "memory"):
+    if argv and argv[0] in (
+        "setup", "init", "wire", "doctor", "status", "memory", "backfill", "index",
+    ):
         from .cli import run_admin
         sys.exit(run_admin(argv[0], argv[1:]))
 
     parser = argparse.ArgumentParser(
         prog="mi-mcp",
         description="MemoryIntelligence MCP Server",
+        # Admin subcommands are dispatched before argparse (above), so they don't
+        # appear as subparsers. List them here so `--help` isn't misleading — a new
+        # user checking `--help` for `setup` shouldn't conclude the docs are stale.
+        epilog=(
+            "setup commands (run these first, not shown above):\n"
+            "  mi-mcp setup     store your API key + wire + opt-in + verify (one command)\n"
+            "  mi-mcp wire      wire into Claude Desktop / Code / Cursor\n"
+            "  mi-mcp doctor    verify install, key resolution, and wiring\n"
+            "  mi-mcp status    show wired surfaces + opt-in allowlist\n"
+            "\nGet a key at https://memoryintelligence.io/portal, then run `mi-mcp setup`."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     parser.add_argument(
         "--version",

{memoryintelligence_mcp-0.1.12 → memoryintelligence_mcp-0.2.0}/src/mi_mcp/cli.py

@@ -6,11 +6,14 @@ a wrapper (``~/.memoryintelligence/mcp/run-mi-mcp.sh``) that resolves
 ``MI_API_KEY`` at launch from the macOS Keychain, then the on-disk keyfile,
 else fails. So a leaked config file exposes nothing.
 
-  setup  — one command: store the key, wire hosts, opt in this dir, verify.
-           (alias: ``init``). The frictionless front door for new users.
-  wire   — register the server in Claude config(s); no key in any file.
-  doctor — verify wiring + key resolvability (prints prefix only, never the key).
-  status — show which surfaces are wired + the capture opt-in allowlist.
+  setup    — one command: store the key, wire hosts, opt in this dir, verify.
+             (alias: ``init``). The frictionless front door for new users.
+  wire     — register the server in Claude config(s); no key in any file.
+  doctor   — verify wiring + key resolvability (prints prefix only, never the key).
+  status   — show which surfaces are wired + the capture opt-in allowlist.
+  memory   — inspect the local .umo vault (ls|open|verify|rm|path).
+  backfill — migrate cloud memories into the local .umo vault (re-embed locally).
+  index    — build/inspect the local vector index (build|path|stat).
 
 The key is stored OUTSIDE every config — in the macOS Keychain (``security``)
 or, on Linux/Windows (or by choice), a ``chmod 600 ~/.memoryintelligence/.env``
@@ -324,7 +327,12 @@ def cmd_wire(argv: list[str]) -> int:
     do_wire(home, surfaces, args.dry_run, capture_anywhere=args.capture_anywhere)
     if not args.dry_run:
         print("\nNext steps:")
-        print(f"  1. opt in a project:  echo \"$(pwd)\" >> {paths.mcp_config_dir(home=home) / 'opt-in-paths'}")
+        # "opt in a directory" reads as "put a file in a folder" to a new user — it's
+        # neither. It records a project path in an allowlist; nothing is placed in the
+        # folder. Show it as a concrete cd-then-command so the mental model is right.
+        print("  1. allow captures from a project (no file is placed — it records the path):")
+        print("       cd ~/Projects/my-app")
+        print(f"       mi-mcp setup --opt-in \"$(pwd)\"     # or: echo \"$(pwd)\" >> {paths.mcp_config_dir(home=home) / 'opt-in-paths'}")
         print("  2. restart Claude (MCP servers load at startup)")
         print("  3. mi-mcp doctor   # verify")
     return 0
@@ -347,6 +355,15 @@ def cmd_doctor(argv: list[str]) -> int:
     bin_path = _mi_mcp_bin()
     check("mi-mcp binary", Path(bin_path).exists(), bin_path)
 
+    # PATH self-check — the #1 post-`uv tool install` stall: the shim exists but its
+    # dir isn't on PATH, so `mi-mcp` "isn't found" until the user notices uv's warning.
+    bin_dir = str(Path(bin_path).parent)
+    path_dirs = os.environ.get("PATH", "").split(os.pathsep)
+    on_path = bin_dir in path_dirs
+    check("binary on PATH", on_path,
+          "" if on_path else f'{bin_dir} not on PATH — run `export PATH="{bin_dir}:$PATH"` (or `uv tool update-shell`) and open a new terminal',
+          critical=False)
+
     wrapper = _wrapper_path(home)
     check("wrapper rendered", wrapper.exists(), str(wrapper))
     check("wrapper executable", wrapper.exists() and os.access(wrapper, os.X_OK),
@@ -362,6 +379,20 @@ def cmd_doctor(argv: list[str]) -> int:
           f"{n} entries" if optin.exists() else "absent — all captures will skip",
           critical=False)
 
+    # Vault path — surface where the local vault resolves and whether it matches the
+    # MemorySpace Desktop vault (~/Somewhere). They differ by default (#653): mi-mcp
+    # defaults to ~/MemoryIntelligence; the Desktop reads ~/Somewhere. If MI_VAULT
+    # isn't unifying them, backfilled memories won't appear in the Desktop.
+    from . import vault as _vault
+    vpath = _vault.vault_path()
+    desktop_vault = home / "Somewhere"
+    mi_vault_set = "MI_VAULT" in os.environ
+    matches = vpath.resolve() == desktop_vault.resolve()
+    check("vault path", matches or mi_vault_set,
+          str(vpath) if matches else
+          f"{vpath} — Desktop reads {desktop_vault}; set MI_VAULT={desktop_vault} so both share one vault (#653)",
+          critical=False)
+
     for s, p in _surface_paths(home).items():
         servers = _load_json(p).get(_surface_key(s), {})
         wired = SERVER_KEY in servers
@@ -515,6 +546,77 @@ def _analyze_export(lines) -> BackfillStats:
     return st
 
 
+# --- pure transforms (export row → .umo inputs); unit-testable without I/O -----
+
+def _parse_export_objects(lines) -> list[dict]:
+    """Parse export NDJSON lines into UMO dicts (skip blanks/errors/malformed)."""
+    out: list[dict] = []
+    for raw in lines:
+        line = (raw or "").strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except (json.JSONDecodeError, TypeError):
+            continue
+        if isinstance(obj, dict) and not obj.get("_error"):
+            out.append(obj)
+    return out
+
+
+def _text_for_embedding(row: dict) -> str:
+    """Pick the text to (re-)embed — the normalized text, else raw, else summary.
+
+    The cloud has no exported embedding (`export.py` omits the 384-d vector), so
+    backfill must re-embed locally; this chooses the same text capture embeds.
+    """
+    for k in ("normalized_text", "raw_text", "summary"):
+        v = row.get(k)
+        if v and str(v).strip():
+            return str(v)
+    return ""
+
+
+def _payload_for_umo(row: dict, embedding: list[float]) -> dict:
+    """Build the encrypted ``.umo`` payload for a backfilled cloud UMO."""
+    return {
+        "embedding": embedding,
+        "summary": row.get("summary") or "",
+        "entities": row.get("entities") or [],
+        "topics": row.get("tags") or [],
+        "created_at": row.get("created_at"),
+        "normalized_text": row.get("normalized_text") or "",
+        "raw_text": row.get("raw_text"),
+        "semantic_hash": row.get("semantic_hash"),
+        "quality_score": row.get("quality_score"),
+        "source_type": row.get("source_type"),
+        # Provenance: owner-self-signed, NOT MI-attested (we re-produced it locally).
+        "origin": "backfill",
+    }
+
+
+def _public_metadata_for_umo(row: dict, owner_did: str) -> dict:
+    """Plaintext public metadata for a backfilled ``.umo`` (no PII; vault-readable).
+
+    Emits the same field set the desktop app writes (content_type / format_version /
+    mi_key_id / schema_version / source_count) so the two surfaces share one
+    readable home, plus an ``origin`` provenance label (the desktop ignores extras).
+    """
+    from . import umo_format
+    return {
+        "umo_id": row.get("id"),
+        "created_at": row.get("created_at"),
+        "owner_did": owner_did,
+        "content_type": "text/plain",
+        "format_version": umo_format.FORMAT_VERSION_STR,
+        "mi_key_id": "local",
+        "schema_version": row.get("schema_version") or "1.0",
+        "source_count": 1,
+        # MCP provenance: owner-self-signed backfill, NOT MI-attested (extra field).
+        "origin": "backfill",
+    }
+
+
 def cmd_backfill(argv: list[str]) -> int:
     ap = argparse.ArgumentParser(
         prog="mi-mcp backfill",
@@ -559,11 +661,15 @@ def cmd_backfill(argv: list[str]) -> int:
                 resp.read()
                 print(f"error: export HTTP {resp.status_code}: {resp.text[:200]}", file=sys.stderr)
                 return 1
-            stats = _analyze_export(resp.iter_lines())
+            # Collect the stream once; we need it for both the stats and (on
+            # --execute) the write pass. The migration is a one-shot, so holding
+            # the (embedding-free) export in memory is acceptable.
+            lines = list(resp.iter_lines())
     except httpx.HTTPError as exc:
         print(f"error: export request failed: {exc}", file=sys.stderr)
         return 1
 
+    stats = _analyze_export(lines)
     print()
     print(f"  memories            : {stats.total}")
     print(f"  approx size         : {stats.approx_bytes / 1024:.1f} KB")
@@ -578,8 +684,57 @@ def cmd_backfill(argv: list[str]) -> int:
         print(f"  .umo with your owner key → write to {vault_dir} → build the local index.")
         return 0
 
-    print("\n  NOTE: the --execute write path (re-embed → encrypt → vault.write_umo → index)")
-    print("  is the next increment and is not wired in this build. Dry-run validated the plan.")
+    # ---- EXECUTE: re-embed locally → encrypt to .umo → vault → build index ----
+    objects = _parse_export_objects(lines)
+    embeddable = [(o, t) for o in objects if (t := _text_for_embedding(o)) and o.get("id")]
+    skipped_no_text = sum(1 for o in objects if o.get("id") and not _text_for_embedding(o))
+    if not embeddable:
+        print("\n  nothing to write (no embeddable memories in the export).")
+        return 0
+
+    try:
+        from . import embedder, indexer, keys, umo_format
+        # create=False: NEVER mint a new owner key as a side effect of a migration —
+        # that would encrypt the backfill to a key the owner doesn't hold, and reads
+        # would silently skip every file (review H3). Fail loudly if it's not resolvable.
+        owner_priv = keys.load_master_private_key(create=False)
+        owner_pub = owner_priv.public_key()
+        signing = keys.load_local_signing_key(create=False)
+        # Match the desktop's fixed owner_did so MCP- and desktop-written .umo share
+        # one consistent home (owner_did is a label, not used in decryption).
+        owner_did = umo_format.LOCAL_OWNER_DID
+    except Exception as e:  # missing crypto extra / no Keychain key / etc.
+        print(f"\nerror: cannot resolve owner keys: {e}", file=sys.stderr)
+        print("  (run `mi-mcp setup`/the desktop app first so the owner key exists)", file=sys.stderr)
+        return 2
+
+    # Print the key fingerprint so you can confirm the backfill is encrypted to YOUR key.
+    print(f"\n  owner key: {keys.owner_did(owner_priv)}  (confirm this is yours)")
+    print(f"  embedding {len(embeddable)} memories locally (bge-small)…")
+    try:
+        vectors = embedder.embed([t for _, t in embeddable])
+    except embedder.LocalEmbedderError as e:
+        print(f"\nerror: {e}", file=sys.stderr)
+        return 2
+
+    written = 0
+    for (row, _text), vec in zip(embeddable, vectors):
+        pm = _public_metadata_for_umo(row, owner_did)
+        blob = umo_format.produce_umo_for_owner(
+            _payload_for_umo(row, vec), pm, owner_pub, signing
+        )
+        vault.write_umo(pm["umo_id"], owner_did, blob)
+        written += 1
+
+    print(f"  wrote {written} .umo files → {vault_dir}")
+    if skipped_no_text:
+        print(f"  skipped {skipped_no_text} memories with no embeddable text")
+
+    print("  building local index …")
+    count = indexer.rebuild_and_save(owner_priv=owner_priv)
+    print(f"  ✅ index built: {count} memories rankable locally → {paths.local_index_path()}")
+    print("\n  Local reads are wired: set MI_MCP_LOCAL=1 to serve mi_ask/mi_list from this")
+    print("  vault. `mi-mcp index build` rebuilds the index after vault changes.")
     return 0
 
 
@@ -746,6 +901,44 @@ def cmd_setup(argv: list[str]) -> int:
     return rc
 
 
+def cmd_index(argv: list[str]) -> int:
+    """Build/inspect the local vector index: ``mi-mcp index {build|path|stat}``.
+
+    ``build`` decrypts the vault with your master key (Keychain prompt) and writes
+    the rank sidecar; the server loads that prebuilt sidecar on the read path.
+    """
+    ap = argparse.ArgumentParser(prog="mi-mcp index")
+    sub = ap.add_subparsers(dest="action", required=True)
+    sub.add_parser("build", help="(re)build the index from the vault (needs your master key)")
+    sub.add_parser("path", help="print the index sidecar path")
+    sub.add_parser("stat", help="show how many memories are indexed")
+    args = ap.parse_args(argv)
+
+    from . import indexer
+
+    if args.action == "path":
+        print(paths.local_index_path())
+        return 0
+
+    if args.action == "stat":
+        idx = indexer.load_index()
+        if idx is None:
+            print(f"(no index yet — run `mi-mcp index build`)  [{paths.local_index_path()}]")
+            return 0
+        print(f"{len(idx)} memories indexed  [{paths.local_index_path()}]")
+        return 0
+
+    # build
+    try:
+        count = indexer.rebuild_and_save()
+    except Exception as e:
+        detail = str(e) or type(e).__name__
+        print(f"cannot build index: {detail}", file=sys.stderr)
+        return 1
+    print(f"✅ indexed {count} memories → {paths.local_index_path()}")
+    return 0
+
+
 _COMMANDS = {
     "setup": cmd_setup,
     "init": cmd_setup,   # alias
@@ -754,6 +947,7 @@ _COMMANDS = {
     "status": cmd_status,
     "memory": cmd_memory,
     "backfill": cmd_backfill,
+    "index": cmd_index,
 }
 
 

{memoryintelligence_mcp-0.1.12 → memoryintelligence_mcp-0.2.0}/src/mi_mcp/client.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
+import re
 from typing import Any
 
 import httpx
@@ -61,13 +62,13 @@ class MIClient:
                 # because an LLM must never receive unredacted memories. This is by
                 # design, not a limitation: the owner views raw values in the human dev
                 # portal, never through a model context. Do not change this to an
-                # owner-raw value. See core/security/export_scrub.AGENT_SOURCES.
+                # owner-raw value. It mirrors the server-side agent-surface redaction policy.
                 "X-MI-Source": "mcp",
             },
             timeout=httpx.Timeout(30.0, connect=10.0),
             # Connection-level retries are SAFE for every verb — httpx only retries
             # when the connection never established (ConnectError/ConnectTimeout from
-            # the Railway sdk-api cold-start), so no request body is ever re-sent.
+            # the hosted API's cold-start), so no request body is ever re-sent.
             # Read-timeout / 5xx retries are handled per-request in _request(), gated
             # on idempotency, because re-sending a write after the body landed could
             # double-apply it.
@@ -77,6 +78,19 @@ class MIClient:
     async def close(self):
         await self._http.aclose()
 
+    def set_client_identity(self, name: str) -> None:
+        """Forward the MCP host identity as the X-MI-Client header (#600).
+
+        `name` is the initialize handshake's clientInfo.name (e.g.
+        "claude-code"). The API uses it to resolve the provenance channel's
+        platform slot — agent:claude-code instead of the transport-generic
+        agent:mcp. Normalized to a registry-comparable key; empty names are
+        a no-op, and unregistered ones fall back to agent:mcp server-side.
+        """
+        normalized = re.sub(r"[^a-z0-9._-]+", "-", (name or "").strip().lower()).strip("-")[:40]
+        if normalized:
+            self._http.headers["X-MI-Client"] = normalized
+
     # ----- helpers -----
 
     # Transient HTTP statuses worth a retry on idempotent reads — gateway/
@@ -98,8 +112,8 @@ class MIClient:
         """Make an API request and return the JSON response.
 
         Idempotent reads (ask/list/explain/verify/match/account_info) are retried
-        on a read timeout or a transient 5xx, with exponential backoff. The Railway
-        sdk-api is a single small instance that intermittently cold-starts/saturates
+        on a read timeout or a transient 5xx, with exponential backoff. The hosted
+        API can intermittently cold-start or saturate
         (CPU-bound bge-small embed + pgvector rerank); the MCP previously had a hard
         30s budget with NO retry — the "MCP keeps timing out" report. Writes
         (capture/upload/forget/batch) are NOT read-retried: a timeout after the body

{memoryintelligence_mcp-0.1.12 → memoryintelligence_mcp-0.2.0}/src/mi_mcp/config.py

@@ -37,6 +37,11 @@ class MIConfig:
     # Tool surface — v0 exposes 3 tools by default; MI_MCP_FULL=1 exposes all 10 (#256).
     full_tools: bool = False
 
+    # Local reads (#432 Phase 1): when True AND a built index sidecar exists, route
+    # mi_ask/mi_list to the on-device vault index (network-free) and fall back to
+    # cloud on any error. Opt-in; cloud stays the default. Set MI_MCP_LOCAL=1.
+    local_mode: bool = False
+
     @classmethod
     def from_env(cls) -> MIConfig:
         """Build config from environment variables.
@@ -51,6 +56,8 @@ class MIConfig:
             MI_HOST            — bind host for SSE/HTTP (default: 127.0.0.1, loopback only)
             MI_PORT            — bind port for SSE/HTTP (default: 8100)
             MI_MCP_FULL        — "1" exposes all 10 tools; otherwise only the core set (#256)
+            MI_MCP_LOCAL       — "1" routes mi_ask/mi_list to the local vault index when
+                                 one is built (network-free); falls back to cloud on error
         """
         api_key = os.environ.get("MI_API_KEY", "")
         if not api_key:
@@ -73,6 +80,7 @@ class MIConfig:
             host=os.environ.get("MI_HOST", cls.host),
             port=int(os.environ.get("MI_PORT", str(cls.port))),
             full_tools=os.environ.get("MI_MCP_FULL") == "1",
+            local_mode=os.environ.get("MI_MCP_LOCAL") == "1",
         )
 
 

memoryintelligence_mcp-0.2.0/src/mi_mcp/embedder.py

@@ -0,0 +1,84 @@
+"""Local document/query embedder — bge-small via fastembed (the ``[local]`` extra).
+
+This is the network-free embedder that lets the vault be ranked offline. It MUST
+produce the same model's vectors as capture (``BAAI/bge-small-en-v1.5``, 384-d) or
+local vectors won't compare to anything. fastembed (ONNX) + onnxruntime are real
+weight, so they live in the ``[local]`` extra, NOT the thin base server-client, and
+are imported lazily — merely importing this module never pulls them in.
+
+DISTRIBUTION (decided 2026-06-23): download-on-first-run by default — fastembed
+fetches the ONNX model on first use and caches it (``~/.cache/fastembed`` or
+``$MI_BGE_MODEL_PATH``). ``MI_BGE_MODEL_PATH`` is the drop-in seam for a *vendored*
+model directory: a sealed school appliance / notarized desktop build points it at a
+bundled model so the first run needs no network. Swapping to a fully-vendored wheel
+later is then a packaging change, not a code change.
+
+PARITY NOTE: queries and documents are embedded the SAME way (no asymmetric bge
+retrieval prefix), because backfill embeds the documents here too — both sides share
+this code, so they share a vector space. If capture-side embedding ever diverges,
+reconcile here.
+"""
+
+from __future__ import annotations
+
+import os
+
+MODEL_NAME = "BAAI/bge-small-en-v1.5"
+EMBED_DIM = 384
+
+# Override the model cache / vendored-model location (the offline seam).
+MODEL_PATH_ENV = "MI_BGE_MODEL_PATH"
+
+_MODEL = None  # process-lifetime singleton — load once, reuse (warm).
+
+
+class LocalEmbedderError(Exception):
+    """Raised when the local embedder can't be loaded (missing extra, etc.)."""
+
+
+def _load_model():
+    """Load (once) and return the fastembed model. Lazy + cached."""
+    global _MODEL
+    if _MODEL is not None:
+        return _MODEL
+    try:
+        from fastembed import TextEmbedding
+    except ImportError as e:  # pragma: no cover - depends on install extras
+        raise LocalEmbedderError(
+            "Local embedding needs the 'local' extra (fastembed + onnxruntime).\n"
+            "Install:  pip install 'memoryintelligence-mcp[local]'"
+        ) from e
+
+    kwargs: dict = {}
+    model_path = os.environ.get(MODEL_PATH_ENV)
+    if model_path:
+        # Point fastembed at a vendored / pre-downloaded model dir → no network.
+        kwargs["cache_dir"] = model_path
+    try:
+        _MODEL = TextEmbedding(model_name=MODEL_NAME, **kwargs)
+    except Exception as e:  # network failure, bad vendored path, etc.
+        raise LocalEmbedderError(
+            f"could not load embedding model {MODEL_NAME!r}: {e}. "
+            f"For offline use, set {MODEL_PATH_ENV} to a vendored model directory."
+        ) from e
+    return _MODEL
+
+
+def warm() -> None:
+    """Preload the model so the first real query/backfill doesn't pay the load.
+
+    The cold-start cost of local reads is the model load + first embed, not the
+    cosine search (<1ms/50k). Call this at server start to keep ``mi_ask`` fast.
+    """
+    _load_model()
+
+
+def embed(texts) -> list[list[float]]:
+    """Embed a sequence of texts → list of 384-d float vectors (batched)."""
+    model = _load_model()
+    return [[float(x) for x in vec] for vec in model.embed(list(texts))]
+
+
+def embed_one(text: str) -> list[float]:
+    """Embed a single text → one 384-d float vector."""
+    return embed([text])[0]