mempalace-code 1.10.1__tar.gz → 1.10.2__tar.gz

{mempalace_code-1.10.1 → mempalace_code-1.10.2}/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## Unreleased
+
+No changes yet.
+
+## v1.10.2 — 2026-06-04
+
+Patch release for the local-first embedding path.
+
+### Fixed
+
+- `restore` now scopes KG writes to the `--palace` path instead of the global
+  default.
+- `watch` now mines and watches an initialized root directory directly, and
+  emits a clear diagnostic when no projects are found.
+- Cached `search`, `mine`, and MCP search paths now load the sentence-transformers
+  model with local-only resolution first, avoiding Hugging Face metadata requests
+  after the setup download has already populated the cache.
+- Re-running `mempalace-code fetch-model` on an already cached model now verifies
+  the local cache instead of performing an online-capable Hub lookup.
+- Suppressed third-party Hugging Face token warnings and weight-loading progress
+  during cached model resolution; MemPalace keeps only its own concise status
+  output.
+- LanceDB optimize and cleanup now re-open the table and verify a fresh handle
+  after maintenance. This catches missing-fragment failures that only appear for
+  the next process instead of trusting a stale in-memory table handle.
+- LanceDB upserts now retry once with a freshly opened table when Lance reports
+  a missing fragment from a stale handle during merge-insert.
+
+### Added
+
+- `preflight mirror` CLI command and docs warning that delete-mode rsync against
+  palace state can silently remove remote-owned data.
+- Regression tests for cached local model resolution, explicit offline mode,
+  local filesystem model paths, idempotent `fetch-model`, and forced re-download.
+- Backlog item `STORE-HF-CACHED-SEARCH-SUBPROCESS-GUARD` for a future
+  socket-blocked subprocess guard covering CLI stdout/stderr and network calls.
+
+### Verified
+
+- Real CLI smokes for cached `fetch-model`, normal search, explicit-offline
+  search, and palace health.
+- Focused storage and CLI command suites plus the network-marked offline gate.
+
 ## v1.10.1 — 2026-05-24
 
 Patch release after the v1.10.0 publish. Focus: real CLI/MCP smoke fixes,

{mempalace_code-1.10.1 → mempalace_code-1.10.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mempalace-code
-Version: 1.10.1
+Version: 1.10.2
 Summary: Developer memory tool — mine codebases and conversations into a LanceDB-backed searchable palace. No API key required.
 Project-URL: Homepage, https://github.com/rergards/mempalace-code
 Project-URL: Repository, https://github.com/rergards/mempalace-code
@@ -112,7 +112,7 @@ Then ask your AI to read [`docs/AGENT_INSTALL.md`](docs/AGENT_INSTALL.md) — it
 <summary>Or do it manually</summary>
 
 ```bash
-mempalace-code init ~/projects/myapp       # detect rooms, download embedding model (~80 MB)
+mempalace-code init ~/projects/myapp       # detect rooms, cache embedding model (~80 MB)
 mempalace-code init ~/projects/myapp --detect-entities  # optional people/project detection for notes/convos
 mempalace-code mine ~/projects/myapp       # index your codebase
 claude mcp add mempalace-code -- python -m mempalace_code.mcp_server  # connect Claude Code
@@ -305,11 +305,14 @@ uv tool inject mempalace-code watchfiles  # or: pipx inject mempalace-code watch
 ```
 
 ```bash
-mempalace-code watch ~/projects/                      # watch all projects (on commit, default)
+mempalace-code watch ~/projects/my-app                # watch an initialized project (on commit)
+mempalace-code watch ~/projects/                      # watch all initialized projects in a parent directory
 mempalace-code watch ~/projects/ --on-save            # watch all file saves instead (noisier)
 mempalace-code watch ~/projects/ schedule             # print launchd/cron snippet for daemon
 ```
 
+`watch` accepts either an **initialized project directory** (has `mempalace.yaml`) or a **parent directory** containing immediate initialized project subdirectories. Pointing it at a project root that has project files but no `mempalace.yaml` exits with the correct `mempalace-code init <dir>` command.
+
 **Install as persistent daemon (macOS):**
 
 ```bash
@@ -632,6 +635,8 @@ Or in `~/.mempalace/config.json`: `{"backup_retain_count": 5}`. Retention only a
 After a successful optimize and readability check, MemPalace also runs
 best-effort verified Lance cleanup (`cleanup_stale_fragments` with
 `unsafe_now=false`) so future backups do not keep archiving stale table versions.
+Optimize and cleanup verification re-opens the Lance table, so it checks the
+same fresh-handle path the next CLI, MCP server, or watcher process will use.
 Use the manual `cleanup` command for older installations that already
 accumulated stale versions or for emergency recovery.
 
@@ -676,6 +681,36 @@ Skips compaction entirely. Storage will grow with more fragments but avoids any
 
 Also available: `mempalace-code export --only-manual` for JSONL export of manually-stored drawers.
 
+**Remote mirror risk — backups vs file mirroring:**
+
+Managed backups and Lance cleanup protect **local** palace state. They do not protect against
+delete-mode rsync between independent hosts. `rsync --delete` syncing a whole MemPalace state
+directory removes remote-owned drawers, diary entries, and KG triples that were never synced
+back to the source — even when local backups are healthy.
+
+Use these recommended excludes for any delete-mode state-directory mirror:
+
+```bash
+rsync -a --delete \
+  --exclude=palace/ \
+  --exclude=knowledge_graph.sqlite3 \
+  --exclude=config.json \
+  --exclude=backups/ \
+  ~/.mempalace/ user@host:.mempalace/
+```
+
+Run a preflight check before installing a mirror job (the command is never executed):
+
+```bash
+mempalace-code preflight mirror --command \
+  "rsync -a --delete --exclude=palace/ --exclude=knowledge_graph.sqlite3 \
+   --exclude=config.json --exclude=backups/ ~/.mempalace/ user@host:.mempalace/"
+# OK
+```
+
+See [docs/BACKUP_RESTORE.md](docs/BACKUP_RESTORE.md) for the full mirror-risk guidance and
+the safer export/import alternative for cross-host transfer of non-regenerable content.
+
 ---
 
 ### Scan Excludes
@@ -730,7 +765,7 @@ exclusion rule.
 mempalace-code health              # probe palace for fragment corruption
 mempalace-code health --json       # machine-readable report
 mempalace-code cleanup --older-than-days 7  # reclaim stale Lance versions
-mempalace-code cleanup --unsafe-now         # emergency cleanup; only with no writers active
+mempalace-code cleanup --unsafe-now         # emergency only; stop MemPalace processes first
 
 mempalace-code repair --dry-run    # show what would be recovered
 mempalace-code repair --rollback   # roll back to last working version
@@ -749,9 +784,9 @@ mempalace-code repair --rollback   # roll back to last working version
 Use `--dry-run` first to see how many rows would be lost.
 
 Normal optimize runs already prune verified stale Lance versions after a
-successful compaction. Manual `cleanup` is still useful after older installs,
-large historical accumulations, or emergency disk recovery when no writer is
-active.
+successful compaction and fresh-handle verification. Manual `cleanup` is still
+useful after older installs, large historical accumulations, or emergency disk
+recovery after stopping watchers, miners, maintenance commands, and MCP servers.
 
 ---
 
@@ -800,7 +835,7 @@ This is a code-first fork of [milla-jovovich/mempalace](https://github.com/milla
 | Upstream | This fork |
 |---|---|
 | ChromaDB — [silently deletes data on version bump](https://github.com/milla-jovovich/mempalace/issues/469) | LanceDB — crash-safe Arrow storage, no version-cliff |
-| "No internet after install" — [false](https://github.com/milla-jovovich/mempalace/issues/524) | `mempalace-code init` downloads model explicitly; offline after model setup |
+| "No internet after install" — [false](https://github.com/milla-jovovich/mempalace/issues/524) | `mempalace-code init` downloads the model explicitly once; cached mining/search use local-only model resolution first |
 | "100% R@5" — [unverifiable](https://github.com/milla-jovovich/mempalace/issues/27) | Number removed. Methodology caveats documented |
 | ~30% test coverage | 2200+ tests, every feature acceptance-gated |
 | No backup, no recovery | `backup` / `restore` / `export` / `import` |
@@ -860,7 +895,7 @@ pip install "mempalace-code[spellcheck]"  # autocorrect for room/wing names
 pip install "mempalace-code[dev]"         # pytest + ruff + pyright
 ```
 
-**Requirements:** Python 3.11+. ~80 MB embedding model downloaded once during `mempalace-code init`.
+**Requirements:** Python 3.11+. ~80 MB embedding model cached once during `mempalace-code init` or `mempalace-code fetch-model`; repeated cached runs resolve the model locally.
 
 </details>
 
@@ -881,8 +916,9 @@ mempalace-code mine <dir> --watch                      # auto-incremental on fil
 mempalace-code mine-all <parent-dir>                   # sync all projects incrementally (one wing per project)
 mempalace-code mine-all <parent-dir> --new-only        # only mine projects not yet in the palace
 
-# Watch (multi-project auto-sync)
-mempalace-code watch <parent-dir>                      # watch all initialized projects
+# Watch (project auto-sync)
+mempalace-code watch <initialized-project>             # watch a single initialized project
+mempalace-code watch <parent-dir>                      # watch all initialized projects in a parent directory
 mempalace-code watch <parent-dir> schedule             # print launchd/cron daemon snippet
 mempalace-code watch <parent-dir> status               # disk-budget + launchd state
 
@@ -908,7 +944,7 @@ mempalace-code wake-up --wing myapp                    # project-scoped
 mempalace-code status                                  # palace overview
 
 # Model
-mempalace-code fetch-model                             # pre-download for offline use
+mempalace-code fetch-model                             # cache or verify model for offline use
 ```
 
 </details>
@@ -966,7 +1002,7 @@ python -m pyright --pythonpath "$(python -c 'import sys; print(sys.executable)')
 Apache 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).
 
 <!-- Link Definitions -->
-[version-shield]: https://img.shields.io/badge/version-1.10.1-4dc9f6?style=flat-square&labelColor=0a0e14
+[version-shield]: https://img.shields.io/badge/version-1.10.2-4dc9f6?style=flat-square&labelColor=0a0e14
 [release-link]: https://github.com/rergards/mempalace-code/releases
 [python-shield]: https://img.shields.io/badge/python-3.11+-7dd8f8?style=flat-square&labelColor=0a0e14&logo=python&logoColor=7dd8f8
 [python-link]: https://www.python.org/

{mempalace_code-1.10.1 → mempalace_code-1.10.2}/README.md

@@ -63,7 +63,7 @@ Then ask your AI to read [`docs/AGENT_INSTALL.md`](docs/AGENT_INSTALL.md) — it
 <summary>Or do it manually</summary>
 
 ```bash
-mempalace-code init ~/projects/myapp       # detect rooms, download embedding model (~80 MB)
+mempalace-code init ~/projects/myapp       # detect rooms, cache embedding model (~80 MB)
 mempalace-code init ~/projects/myapp --detect-entities  # optional people/project detection for notes/convos
 mempalace-code mine ~/projects/myapp       # index your codebase
 claude mcp add mempalace-code -- python -m mempalace_code.mcp_server  # connect Claude Code
@@ -256,11 +256,14 @@ uv tool inject mempalace-code watchfiles  # or: pipx inject mempalace-code watch
 ```
 
 ```bash
-mempalace-code watch ~/projects/                      # watch all projects (on commit, default)
+mempalace-code watch ~/projects/my-app                # watch an initialized project (on commit)
+mempalace-code watch ~/projects/                      # watch all initialized projects in a parent directory
 mempalace-code watch ~/projects/ --on-save            # watch all file saves instead (noisier)
 mempalace-code watch ~/projects/ schedule             # print launchd/cron snippet for daemon
 ```
 
+`watch` accepts either an **initialized project directory** (has `mempalace.yaml`) or a **parent directory** containing immediate initialized project subdirectories. Pointing it at a project root that has project files but no `mempalace.yaml` exits with the correct `mempalace-code init <dir>` command.
+
 **Install as persistent daemon (macOS):**
 
 ```bash
@@ -583,6 +586,8 @@ Or in `~/.mempalace/config.json`: `{"backup_retain_count": 5}`. Retention only a
 After a successful optimize and readability check, MemPalace also runs
 best-effort verified Lance cleanup (`cleanup_stale_fragments` with
 `unsafe_now=false`) so future backups do not keep archiving stale table versions.
+Optimize and cleanup verification re-opens the Lance table, so it checks the
+same fresh-handle path the next CLI, MCP server, or watcher process will use.
 Use the manual `cleanup` command for older installations that already
 accumulated stale versions or for emergency recovery.
 
@@ -627,6 +632,36 @@ Skips compaction entirely. Storage will grow with more fragments but avoids any
 
 Also available: `mempalace-code export --only-manual` for JSONL export of manually-stored drawers.
 
+**Remote mirror risk — backups vs file mirroring:**
+
+Managed backups and Lance cleanup protect **local** palace state. They do not protect against
+delete-mode rsync between independent hosts. `rsync --delete` syncing a whole MemPalace state
+directory removes remote-owned drawers, diary entries, and KG triples that were never synced
+back to the source — even when local backups are healthy.
+
+Use these recommended excludes for any delete-mode state-directory mirror:
+
+```bash
+rsync -a --delete \
+  --exclude=palace/ \
+  --exclude=knowledge_graph.sqlite3 \
+  --exclude=config.json \
+  --exclude=backups/ \
+  ~/.mempalace/ user@host:.mempalace/
+```
+
+Run a preflight check before installing a mirror job (the command is never executed):
+
+```bash
+mempalace-code preflight mirror --command \
+  "rsync -a --delete --exclude=palace/ --exclude=knowledge_graph.sqlite3 \
+   --exclude=config.json --exclude=backups/ ~/.mempalace/ user@host:.mempalace/"
+# OK
+```
+
+See [docs/BACKUP_RESTORE.md](docs/BACKUP_RESTORE.md) for the full mirror-risk guidance and
+the safer export/import alternative for cross-host transfer of non-regenerable content.
+
 ---
 
 ### Scan Excludes
@@ -681,7 +716,7 @@ exclusion rule.
 mempalace-code health              # probe palace for fragment corruption
 mempalace-code health --json       # machine-readable report
 mempalace-code cleanup --older-than-days 7  # reclaim stale Lance versions
-mempalace-code cleanup --unsafe-now         # emergency cleanup; only with no writers active
+mempalace-code cleanup --unsafe-now         # emergency only; stop MemPalace processes first
 
 mempalace-code repair --dry-run    # show what would be recovered
 mempalace-code repair --rollback   # roll back to last working version
@@ -700,9 +735,9 @@ mempalace-code repair --rollback   # roll back to last working version
 Use `--dry-run` first to see how many rows would be lost.
 
 Normal optimize runs already prune verified stale Lance versions after a
-successful compaction. Manual `cleanup` is still useful after older installs,
-large historical accumulations, or emergency disk recovery when no writer is
-active.
+successful compaction and fresh-handle verification. Manual `cleanup` is still
+useful after older installs, large historical accumulations, or emergency disk
+recovery after stopping watchers, miners, maintenance commands, and MCP servers.
 
 ---
 
@@ -751,7 +786,7 @@ This is a code-first fork of [milla-jovovich/mempalace](https://github.com/milla
 | Upstream | This fork |
 |---|---|
 | ChromaDB — [silently deletes data on version bump](https://github.com/milla-jovovich/mempalace/issues/469) | LanceDB — crash-safe Arrow storage, no version-cliff |
-| "No internet after install" — [false](https://github.com/milla-jovovich/mempalace/issues/524) | `mempalace-code init` downloads model explicitly; offline after model setup |
+| "No internet after install" — [false](https://github.com/milla-jovovich/mempalace/issues/524) | `mempalace-code init` downloads the model explicitly once; cached mining/search use local-only model resolution first |
 | "100% R@5" — [unverifiable](https://github.com/milla-jovovich/mempalace/issues/27) | Number removed. Methodology caveats documented |
 | ~30% test coverage | 2200+ tests, every feature acceptance-gated |
 | No backup, no recovery | `backup` / `restore` / `export` / `import` |
@@ -811,7 +846,7 @@ pip install "mempalace-code[spellcheck]"  # autocorrect for room/wing names
 pip install "mempalace-code[dev]"         # pytest + ruff + pyright
 ```
 
-**Requirements:** Python 3.11+. ~80 MB embedding model downloaded once during `mempalace-code init`.
+**Requirements:** Python 3.11+. ~80 MB embedding model cached once during `mempalace-code init` or `mempalace-code fetch-model`; repeated cached runs resolve the model locally.
 
 </details>
 
@@ -832,8 +867,9 @@ mempalace-code mine <dir> --watch                      # auto-incremental on fil
 mempalace-code mine-all <parent-dir>                   # sync all projects incrementally (one wing per project)
 mempalace-code mine-all <parent-dir> --new-only        # only mine projects not yet in the palace
 
-# Watch (multi-project auto-sync)
-mempalace-code watch <parent-dir>                      # watch all initialized projects
+# Watch (project auto-sync)
+mempalace-code watch <initialized-project>             # watch a single initialized project
+mempalace-code watch <parent-dir>                      # watch all initialized projects in a parent directory
 mempalace-code watch <parent-dir> schedule             # print launchd/cron daemon snippet
 mempalace-code watch <parent-dir> status               # disk-budget + launchd state
 
@@ -859,7 +895,7 @@ mempalace-code wake-up --wing myapp                    # project-scoped
 mempalace-code status                                  # palace overview
 
 # Model
-mempalace-code fetch-model                             # pre-download for offline use
+mempalace-code fetch-model                             # cache or verify model for offline use
 ```
 
 </details>
@@ -917,7 +953,7 @@ python -m pyright --pythonpath "$(python -c 'import sys; print(sys.executable)')
 Apache 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).
 
 <!-- Link Definitions -->
-[version-shield]: https://img.shields.io/badge/version-1.10.1-4dc9f6?style=flat-square&labelColor=0a0e14
+[version-shield]: https://img.shields.io/badge/version-1.10.2-4dc9f6?style=flat-square&labelColor=0a0e14
 [release-link]: https://github.com/rergards/mempalace-code/releases
 [python-shield]: https://img.shields.io/badge/python-3.11+-7dd8f8?style=flat-square&labelColor=0a0e14&logo=python&logoColor=7dd8f8
 [python-link]: https://www.python.org/

{mempalace_code-1.10.1 → mempalace_code-1.10.2}/docs/AGENT_INSTALL.md

@@ -22,7 +22,7 @@ feature checklist, not an install step.
 | Code/docs mining | `mempalace-code mine <dir>` indexes supported source, docs, prose, config, and data files into LanceDB |
 | Conversation/log ingest | `mempalace-code mine <dir> --mode convos` ingests Claude Code JSONL, Codex CLI JSONL, Gemini CLI JSONL, Claude.ai JSON, ChatGPT JSON, Slack JSON, and plain text transcripts |
 | Multi-project sync | `mempalace-code mine-all <parent>` assigns one wing per initialized project; `--new-only` skips already-known wings |
-| Auto-watch | `mempalace-code watch <parent>` re-mines initialized projects on commit by default; `--on-save` is available but noisier |
+| Auto-watch | `mempalace-code watch <initialized-project>` watches one project directly; `mempalace-code watch <parent>` watches all initialized projects in a parent directory; re-mines on commit by default; `--on-save` is available but noisier |
 | MCP tools | 29 tools (default `full` profile): semantic search, code search, file context/read, manual drawers, KG, architecture retrieval, graph tunnels, diary, re-mine; named profiles (`minimal`, `kg`, `code`, `notes`) reduce the exposed subset at startup |
 | KG / architecture | Temporal facts plus .NET/Python architecture extraction; .NET project/type graph tools require pre-mined symbols |
 | Local-model fallback | `mempalace-code wake-up` emits memory layers for agents without MCP support |
@@ -177,7 +177,7 @@ Ask all five questions before acting. Record answers; they parameterize Sections
 
 ### Q3 — Model download consent
 
-**ASK HUMAN:** "mempalace-code uses a local embedding model (~80 MB) downloaded once from HuggingFace. This requires internet access during setup; after that everything runs offline. Reply `yes` to download now, `no` to skip (you can run `mempalace-code fetch-model` later), or `offline` if this machine has no internet access."
+**ASK HUMAN:** "mempalace-code uses a local embedding model (~80 MB) cached once from HuggingFace. This requires internet access only if the model is not already cached; after that everything runs offline. Reply `yes` to cache/verify now, `no` to skip (you can run `mempalace-code fetch-model` later), or `offline` if this machine has no internet access."
 
 **Parse response:**
 - `yes` → Set `DOWNLOAD_MODEL=yes`.
@@ -427,7 +427,7 @@ Do not add the flag just because a directory is a source repo; code symbols are
 
 ---
 
-### Step 4c: Download embedding model
+### Step 4c: Cache or verify embedding model
 
 **Condition:** `DOWNLOAD_MODEL=yes`
 
@@ -436,11 +436,11 @@ Run:
 mempalace-code fetch-model
 ```
 
-`fetch-model` is idempotent — if the model is already cached it loads instantly from disk (no network call). Expected output ends with `Done — embedding model is ready for offline use.`
+`fetch-model` is idempotent — if the model is already cached it verifies local-only model resolution from disk (no network call). Expected output ends with `Done — embedding model is ready for offline use.`
 
 Exit code 0 = success. Set `MODEL_READY=true`. Continue to Step 4d.
 
-**Fail →** Retry once. If still failing, **ASK HUMAN:** "Model download failed (network error or HuggingFace unavailable). The palace will work without the model, but search quality will degrade until it is available. Reply `retry` to try again, or `continue` to proceed without the model (run `mempalace-code fetch-model` later)."
+**Fail →** Retry once. If still failing, **ASK HUMAN:** "Model cache/verify failed (missing cache, network error, or HuggingFace unavailable). The palace will work without the model, but search quality will degrade until it is available. Reply `retry` to try again, or `continue` to proceed without the model (run `mempalace-code fetch-model` later)."
 
 **Condition:** `DOWNLOAD_MODEL=no` → Set `MODEL_READY=false`. Note to human: run `mempalace-code fetch-model` before first search.
 

{mempalace_code-1.10.1 → mempalace_code-1.10.2}/docs/BACKLOG-archived.yaml

@@ -926,3 +926,38 @@ items:
       resolution: '2026-05-24: completed in pipeline run (commit=b4d31bb, 9 files changed, 136 insertions(+), 1 deletion(-))'
       archived_date: "2026-05-24"
       done_summary: completed in pipeline run (commit=b4d31bb, 9 files changed, 136 insertions(+), 1 deletion(-))
+    - key: WATCH-LANCE-MISSING-FRAGMENT-ROLLBACK
+      summary: Make watch initial mine fail closed and recover from Lance missing-fragment write errors
+      resolution: '2026-05-29: Restored watcher rollback safety and fixed managed backup filename collisions; full test suite passed after manual provider repair.'
+      archived_date: "2026-05-29"
+      done_summary: Restored watcher rollback safety and fixed managed backup filename collisions; full test suite passed after manual provider repair.
+    - key: RESTORE-KG-PATH-SCOPING
+      summary: Avoid surprising global KG overwrite when restoring to an explicit palace path
+      resolution: '2026-05-29: completed in pipeline run (commit=98a7244, 17 files changed, 634 insertions(+), 2 deletions(-))'
+      archived_date: "2026-05-29"
+      done_summary: completed in pipeline run (commit=98a7244, 17 files changed, 634 insertions(+), 2 deletions(-))
+    - key: WATCH-INITIALIZED-ROOT-UX
+      summary: Clarify or support watch on a directory that is itself an initialized project
+      resolution: '2026-05-29: completed in pipeline run (commit=5fe84f9, 18 files changed, 755 insertions(+), 38 deletions(-))'
+      archived_date: "2026-05-29"
+      done_summary: completed in pipeline run (commit=5fe84f9, 18 files changed, 755 insertions(+), 38 deletions(-))
+    - key: WATCH-STALE-SWEEP-BULK-DELETE
+      summary: Make watch initial stale-file sweep delete in bulk instead of one Lance version per stale file
+      resolution: '2026-05-29: completed in pipeline run (commit=f6f3fa1, 14 files changed, 646 insertions(+), 1 deletion(-))'
+      archived_date: "2026-05-29"
+      done_summary: completed in pipeline run (commit=f6f3fa1, 14 files changed, 646 insertions(+), 1 deletion(-))
+    - key: REMOTE-MIRROR-SAFE-GUARDS
+      summary: Add safeguards and docs for remote mirror jobs that can delete live palace data
+      resolution: '2026-05-29: completed in pipeline run (commit=e7f524b, 22 files changed, 1654 insertions(+))'
+      archived_date: "2026-05-29"
+      done_summary: completed in pipeline run (commit=e7f524b, 22 files changed, 1654 insertions(+))
+    - key: MIRROR-PREFLIGHT-WRAPPER-DETECTION
+      summary: Detect wrapped destructive mirror commands in preflight mirror
+      resolution: '2026-05-29: completed in pipeline run (commit=867ef57, 12 files changed, 732 insertions(+), 9 deletions(-))'
+      archived_date: "2026-05-29"
+      done_summary: completed in pipeline run (commit=867ef57, 12 files changed, 732 insertions(+), 9 deletions(-))
+    - key: MIRROR-PREFLIGHT-SUDO-COMBINED-OPTS
+      summary: Detect sudo combined-option mirror wrapper forms
+      resolution: '2026-05-29: completed in pipeline run (commit=7588660, 9 files changed, 213 insertions(+), 1 deletion(-))'
+      archived_date: "2026-05-29"
+      done_summary: completed in pipeline run (commit=7588660, 9 files changed, 213 insertions(+), 1 deletion(-))

{mempalace_code-1.10.1 → mempalace_code-1.10.2}/docs/BACKLOG.yaml

@@ -42,4 +42,14 @@ sections:
 # ============================================================
 # OPEN ITEMS
 # ============================================================
-items: []
+items:
+  - key: STORE-HF-CACHED-SEARCH-SUBPROCESS-GUARD
+    section: quality
+    status: open
+    priority: P2
+    summary: Add subprocess-level guard that cached model search/fetch never emits HuggingFace token warnings or performs network metadata calls after setup.
+    acceptance:
+      - Run a real CLI subprocess with a preseeded HuggingFace cache and network/socket access blocked or mocked.
+      - Assert `mempalace-code search` exits successfully without `HF_TOKEN`, `unauthenticated`, `huggingface.co`, or retry noise on stdout/stderr.
+      - Assert repeated `mempalace-code fetch-model` on a cached model uses local-only resolution and does not perform Hub metadata requests.
+      - Keep the existing network-marked download tests separate from this no-network regression guard.

{mempalace_code-1.10.1 → mempalace_code-1.10.2}/docs/BACKUP_RESTORE.md

@@ -157,6 +157,40 @@ mempalace-code restore ~/safe.tar.gz            # restore (prompts before overwr
 mempalace-code restore ~/safe.tar.gz --force    # overwrite without prompt
 ```
 
+### Tarball Restore — KG Destination
+
+When a tarball archive includes `knowledge_graph.sqlite3`, the restore command decides
+where to write it based on your invocation:
+
+| Invocation | KG written to |
+|------------|---------------|
+| `mempalace-code restore FILE` | `~/.mempalace/knowledge_graph.sqlite3` (global default) |
+| `mempalace-code --palace <dir> restore FILE` | `<dir>/knowledge_graph.sqlite3` (palace-scoped) |
+| `mempalace-code --palace <dir> restore FILE --kg-path <path>` | `<path>` (explicit override) |
+| `mempalace-code restore FILE --kg-path <path>` | `<path>` (explicit override) |
+
+**Important:** When you restore to an explicit `--palace <dir>`, the archived KG data
+is written to `<dir>/knowledge_graph.sqlite3` — not to the global default — to avoid
+silently overwriting an unrelated knowledge graph.
+
+Use `--kg-path` to direct the KG to any arbitrary destination, including the global
+default path, a shared location, or a testing path:
+
+```bash
+# Restore Lance data to a custom palace, KG to the custom palace (default scoping)
+mempalace-code --palace ~/my_palace restore ~/backup.tar.gz
+
+# Override the KG destination explicitly
+mempalace-code --palace ~/my_palace restore ~/backup.tar.gz --kg-path ~/shared_kg.sqlite3
+
+# Restore without --palace: KG goes to the global default (backward-compatible)
+mempalace-code restore ~/backup.tar.gz
+```
+
+> **Note:** This tarball restore behavior is separate from JSONL import/export KG
+> handling. The `--skip-kg` and `--with-kg` flags documented in the [Restore
+> Procedure](#restore-procedure) section above apply to JSONL imports only.
+
 ### Scheduled Backups
 
 ```bash
@@ -174,6 +208,44 @@ Each backup has a kind that controls its filename prefix and per-kind retention:
 | `manual` | `mempalace_backup_` | `backup create` (default) |
 | `scheduled` | `scheduled_` | `backup create --kind scheduled` / cron |
 | `pre_optimize` | `pre_optimize_` | Auto-backup before optimize |
+| `pre_watch` | `pre_watch_` | Auto-backup before watcher initial mine |
+
+### Watch Pre-Run Backups
+
+When an existing palace is detected on watcher startup, `mempalace-code watch` (and
+`mempalace-code mine --watch`) creates a `pre_watch` archive **before** the initial
+incremental mine.  The archive path is printed to stdout:
+
+```
+  Pre-watch backup: /path/to/.mempalace/backups/pre_watch_20260101_120000.tar.gz
+```
+
+If the archive cannot be created (e.g. disk budget too low), the watcher **exits
+immediately** — the initial mine is never run and the palace is not mutated.
+
+### Degraded Startup Recovery
+
+If the initial mine fails with a Lance missing-fragment error (a symptom of prior
+cleanup/restore history leaving stale fragment references), the watcher:
+
+1. Prints `DEGRADED` and the error context.
+2. Attempts an automatic Lance version rollback to the most recent healthy version
+   (`repair --rollback`).
+3. If rollback succeeds, retries the initial mine once.  The watcher enters the
+   normal watch loop only after the retry succeeds.
+4. If rollback finds no healthy candidate, or the retry still fails, the watcher
+   exits **before watching** and prints operator-safe recovery commands:
+
+```
+  To diagnose and recover, run:
+    mempalace-code --palace /path/palace health
+    mempalace-code --palace /path/palace repair --rollback --dry-run
+    mempalace-code --palace /path/palace restore /path/pre_watch_20260101_120000.tar.gz --force
+```
+
+The `restore --force` command falls back to the `pre_watch` tarball when Lance
+version rollback cannot recover.  Manual review is required before running it (the
+restore command overwrites the palace `lance/` directory).
 
 ### Auto-Backup Before Optimize
 
@@ -216,7 +288,9 @@ Archives written with explicit `--out` paths are never pruned.
 
 After a successful optimize and readability check, MemPalace also runs
 best-effort verified Lance cleanup so future backups do not keep archiving stale
-table versions. Manual `cleanup` remains the recovery tool for older
+table versions. Optimize and cleanup verification re-opens the Lance table, so
+it checks the same fresh-handle path the next CLI, MCP server, or watcher
+process will use. Manual `cleanup` remains the recovery tool for older
 installations that already accumulated stale versions or for emergency disk
 recovery.
 
@@ -248,11 +322,12 @@ and managed `scheduled` backups keep the newest 14; `manual` backups stay
 unbounded unless you set an explicit retain count.
 
 If LanceDB stale versions/fragments are the problem rather than backup archives,
-run storage cleanup after confirming no writer process is active:
+run storage cleanup only after stopping MemPalace watchers, miners, maintenance
+commands, and MCP servers:
 
 ```bash
 mempalace-code cleanup --older-than-days 7
-mempalace-code cleanup --unsafe-now  # emergency only; no watcher/miner may be running
+mempalace-code cleanup --unsafe-now  # emergency only; no MemPalace process may be running
 ```
 
 ---
@@ -377,8 +452,8 @@ written.
    mempalace-code fetch-model
    ```
 
-   On an already-prefetched host, you can also force offline model resolution and
-   avoid Hugging Face metadata checks during the smoke:
+   On an already-prefetched host, you can also force offline model resolution to
+   verify the smoke does not need network access:
 
    ```bash
    HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 python scripts/migrate_storage_smoke.py --rows 3
@@ -441,6 +516,81 @@ regardless of exceptions. No files are written inside the repository.
 
 ---
 
+## Remote Mirror Risk
+
+Managed backups and Lance cleanup protect **local** palace state. They do not protect
+against a separate class of operator risk: delete-mode file mirroring between independent
+hosts (`rsync --delete`).
+
+When `rsync --delete` syncs a whole MemPalace state directory from one host to another,
+it removes files on the destination that are absent on the source. If the destination host
+holds **remote-owned** drawers, diary entries, or KG triples that were never synced back
+to the source, those are permanently deleted — even though local backups and Lance cleanup
+are healthy.
+
+### Why managed backups do not protect against this
+
+- Backups archive the **source** palace. A delete-mode mirror of the source removes content
+  from the **destination** that the source never knew about.
+- Backup retention and Lance cleanup run on the source; they have no visibility into remote
+  state or what `rsync --delete` will remove on the destination.
+
+### Safe rsync with recommended excludes
+
+If you must mirror the palace state directory between hosts, exclude the live palace data,
+KG database, config, and managed backups directory so a delete sweep cannot remove
+remote-owned content:
+
+```bash
+rsync -a --delete \
+  --exclude=palace/ \
+  --exclude=knowledge_graph.sqlite3 \
+  --exclude=config.json \
+  --exclude=backups/ \
+  ~/.mempalace/ user@host:.mempalace/
+```
+
+Add `--exclude='*.log'` if you route MemPalace watch logs into the state directory
+(by default, logs go to `/tmp/mempalace-watch.log` and do not need excluding).
+
+### Preflight check before installing a mirror job
+
+Before installing a launchd or cron mirror job, run the preflight command to verify your
+rsync invocation is safe (the command is inspected only — it is never executed):
+
+```bash
+mempalace-code preflight mirror --command \
+  "rsync -a --delete --exclude=palace/ --exclude=knowledge_graph.sqlite3 \
+   --exclude=config.json --exclude=backups/ ~/.mempalace/ user@host:.mempalace/"
+# OK
+
+mempalace-code preflight mirror --command "rsync -a --delete ~/.mempalace/ user@host:.mempalace/"
+# BLOCKED [delete-mode-state-mirror-missing-excludes]
+#   missing exclude: palace
+#   missing exclude: kg
+#   missing exclude: config
+#   missing exclude: backups
+```
+
+Use `--json` for automation scripts that parse the result.
+
+### Recommended alternative: export/import instead of whole-state mirrors
+
+Whole-state mirrors transfer regenerable code-chunked drawers along with the irreplaceable
+manual content. A safer cross-host transfer uses the export/import flow:
+
+```bash
+# On source host: export only manual drawers and KG (non-regenerable content)
+mempalace-code export --only-manual --with-kg --out ~/transfer.jsonl
+
+# Copy the JSONL to the destination host, then import
+mempalace-code import ~/transfer.jsonl
+```
+
+This preserves remote-owned content on both sides and avoids delete-sweep risk entirely.
+
+---
+
 ## Related
 
 - Upstream data loss context: issue #469 in the original ChromaDB-based fork