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

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

@@ -3,6 +3,56 @@
 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
+- **The MCP client now retries on transient failures instead of failing the
+  first time the API is slow to wake.** The Railway `sdk-api` is a single small
+  instance that intermittently cold-starts or saturates (CPU-bound embedding +
+  pgvector rerank), and the client had a hard 30s budget with **no retry** — the
+  source of the "MCP keeps timing out" reports. Now:
+  - **Idempotent reads** (`mi_ask`, `mi_list`, `mi_explain`, `mi_verify`,
+    `mi_match`, account lookup) retry up to 2× on a read timeout or a transient
+    5xx (502/503/504), with exponential backoff (0.5s, 1.0s).
+  - **Writes** (`mi_capture`, `mi_upload`, `mi_forget`, batch) are **not**
+    read-retried — a timeout after the request body landed could double-apply.
+  - **Connection-level retries** (transport `retries=2`) cover the cold-start
+    `ConnectError` case for *every* verb, since no body is re-sent when the
+    connection never established.
+
+  This is a client-side reliability mitigation. The durable fix is local-vault
+  reads (no network round-trip on recall) — tracked separately.
+
+## [0.1.11] — 2026-06-16
+
+### Added
+- **`mi_upload` is now part of the default tool surface** — file-capture parity
+  with the API. The MCP previously exposed only text capture; `mi_upload` now
+  ships in the visible tool set and its description covers the full capture
+  matrix: structured files (csv/tsv/xlsx/json → typed claims), documents
+  (pdf/docx), images (→ OCR), and audio/video (→ transcription).
+
 ## [0.1.10] — 2026-06-15
 
 ### Changed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memoryintelligence-mcp
-Version: 0.1.10
+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,11 +26,15 @@ 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
 
 # MemoryIntelligence MCP Server
@@ -77,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.10 → 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.10 → memoryintelligence_mcp-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "memoryintelligence-mcp"
-version = "0.1.10"
+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"
@@ -37,16 +37,23 @@ Changelog = "https://github.com/somewhere11/memoryintelligence-mcp/blob/main/CHA
 Documentation = "https://memoryintelligence.io/docs/api-reference"
 
 [project.optional-dependencies]
-# Local vault (Path A): owner-side .umo encryption/decryption + signature verify.
-# Kept out of the base install so the thin server-client stays lightweight.
+# Local vault (Path A): owner-side .umo encryption/decryption + signature verify,
+# plus the local vector index (numpy) for network-free reads. Kept out of the base
+# install so the thin server-client stays lightweight.
 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",
     "pytest-asyncio>=0.24",
     "ruff>=0.4.0",
     "cryptography>=42.0,<46",
+    "numpy>=1.24,<3",
+    "fastembed>=0.3.0,<1.0",
 ]
 
 [project.scripts]

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

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

{memoryintelligence_mcp-0.1.10 → 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.10 → 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``
@@ -31,9 +34,10 @@ import shutil
 import subprocess
 import sys
 import tempfile
+from dataclasses import dataclass
 from pathlib import Path
 
-from . import paths
+from . import __version__, paths
 from .config import load_opt_in_paths
 
 SERVER_KEY = "memoryintelligence"
@@ -323,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
@@ -346,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),
@@ -361,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
@@ -464,6 +496,248 @@ def cmd_memory(argv: list[str]) -> int:
     return 0
 
 
+# ---------------------------------------------------------------------------
+# backfill — one-time cloud → local-vault migration (dry-run by default)
+# ---------------------------------------------------------------------------
+
+# A <PERSON>/<…> marker in the OWNER export means the content was redacted at
+# INGEST (stored redacted). The owner export keeps person names, so a marker here
+# flags a memory whose raw text was never stored and cannot be recovered locally.
+_REDACTION_MARKERS = (
+    "<PERSON>", "<EMAIL>", "<PHONE>", "<SSN>", "<LOCATION>", "<ORG>",
+    "<CREDIT_CARD>", "[REDACTED]",
+)
+
+
+@dataclass
+class BackfillStats:
+    total: int = 0
+    approx_bytes: int = 0
+    with_raw: int = 0
+    redacted_at_source: int = 0
+    stream_error: str | None = None
+
+
+def _analyze_export(lines) -> BackfillStats:
+    """Tally an NDJSON export stream without writing anything.
+
+    Pure + side-effect-free so it's unit-testable with synthetic lines. Counts
+    UMOs, bytes, how many carry raw_text, and how many were already redacted at
+    ingest (a marker in the owner export = unrecoverable raw text).
+    """
+    st = BackfillStats()
+    for raw in lines:
+        line = raw.strip()
+        if not line:
+            continue
+        st.approx_bytes += len(raw) + 1
+        try:
+            obj = json.loads(line)
+        except (json.JSONDecodeError, TypeError):
+            continue
+        if isinstance(obj, dict) and obj.get("_error"):
+            st.stream_error = str(obj.get("_error"))
+            continue
+        st.total += 1
+        if obj.get("raw_text"):
+            st.with_raw += 1
+        if any(m in line for m in _REDACTION_MARKERS):
+            st.redacted_at_source += 1
+    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",
+        description="One-time migration of your cloud memories into the local .umo vault. "
+                    "Dry-run by default (writes nothing).",
+    )
+    ap.add_argument("--execute", action="store_true",
+                    help="actually write to the local vault (default: dry-run, writes nothing)")
+    ap.add_argument("--since", default=None, metavar="ISO8601",
+                    help="only backfill memories created on/after this timestamp")
+    ap.add_argument("--home", default=os.environ.get("HOME"))
+    args = ap.parse_args(argv)
+    home = Path(args.home)
+
+    key, src = _resolve_key(home)
+    if not key:
+        print("error: no MI_API_KEY resolvable — run `mi-mcp setup` first.", file=sys.stderr)
+        return 2
+    base_url = os.environ.get("MI_BASE_URL", "https://api.memoryintelligence.io").rstrip("/")
+
+    from . import vault
+    vault_dir = vault.vault_path()
+
+    mode = "EXECUTE" if args.execute else "DRY-RUN"
+    print(f"{mode}: backfill cloud → local vault")
+    print(f"  source: {base_url}/v1/memories/export?include_raw=true   (raw owner export · key {src})")
+    print(f"  vault : {vault_dir}")
+    print("  streaming export …")
+
+    import httpx
+    params = {"include_raw": "true"}
+    if args.since:
+        params["since"] = args.since
+    headers = {"Authorization": f"Bearer {key}", "User-Agent": f"mi-mcp/{__version__}"}
+    try:
+        with httpx.stream(
+            "GET", f"{base_url}/v1/memories/export",
+            params=params, headers=headers,
+            timeout=httpx.Timeout(120.0, connect=10.0),
+        ) as resp:
+            if resp.status_code >= 400:
+                resp.read()
+                print(f"error: export HTTP {resp.status_code}: {resp.text[:200]}", file=sys.stderr)
+                return 1
+            # 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")
+    print(f"  carry raw_text      : {stats.with_raw}")
+    print(f"  redacted at ingest  : {stats.redacted_at_source}  (raw never stored — unrecoverable)")
+    if stats.stream_error:
+        print(f"  ⚠ stream interrupted: {stats.stream_error} — counts are partial")
+
+    if not args.execute:
+        print("\n  DRY-RUN — nothing written.")
+        print("  --execute would: re-embed each locally (fastembed bge-small) → encrypt to")
+        print(f"  .umo with your owner key → write to {vault_dir} → build the local index.")
+        return 0
+
+    # ---- 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
+
+
 # ---------------------------------------------------------------------------
 # setup — the one-command front door (store key → wire → opt-in → verify)
 # ---------------------------------------------------------------------------
@@ -627,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
@@ -634,6 +946,8 @@ _COMMANDS = {
     "doctor": cmd_doctor,
     "status": cmd_status,
     "memory": cmd_memory,
+    "backfill": cmd_backfill,
+    "index": cmd_index,
 }