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

{mempalace_code-1.10.0 → mempalace_code-1.10.2}/.github/workflows/publish.yml

@@ -3,12 +3,18 @@ name: Publish to PyPI
 on:
   push:
     tags: ["v*"]
+  workflow_dispatch:
+  repository_dispatch:
+    types: [publish]
+  release:
+    types: [published]
 
 permissions:
   id-token: write
 
 jobs:
   build:
+    if: github.repository == 'rergards/mempalace-code'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
@@ -23,6 +29,7 @@ jobs:
           path: dist/
 
   publish:
+    if: github.repository == 'rergards/mempalace-code'
     needs: build
     runs-on: ubuntu-latest
     environment: release

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

@@ -1,5 +1,94 @@
 # 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,
+read-only no-embedder paths, and release-check tooling.
+
+### Added
+
+- Disposable `scripts/migrate_storage_smoke.py` release smoke for Chroma -> Lance
+  migration. It generates a tiny legacy Chroma source, runs the real
+  `migrate-storage` CLI, verifies source/destination counts, checks searchable
+  migrated content, and exercises the non-empty destination guard.
+- `mempalace_kg_query`, `mempalace_kg_timeline`, and architecture/KG relationship
+  outputs now expose `source_file` provenance when it is present.
+
+### Fixed
+
+- MCP `delete_drawer` and `delete_wing` now work after read-only MCP calls in a
+  fresh offline home without starting the embedding model or returning a false
+  "No palace found".
+- Read-only CLI/MCP paths (`status`, `health`, `read`, `export`, backup metadata,
+  graph/layer traversal, dry-run maintenance) avoid unnecessary embedder startup.
+- `python -m mempalace_code.cli ...` no longer emits the `runpy` warning caused by
+  eager package-level CLI imports; the `mempalace-code` console entrypoint remains
+  compatible.
+- `export --out -` now routes progress and summary text to stderr, keeping stdout
+  as pure JSONL so it can be piped directly into `import -`.
+- `backup --out FILE create` now writes to the requested archive path instead of
+  falling back to the default backups directory.
+- `search` now prints the full stored source path so it can be copied into `read`.
+  `read` also resolves unique basename and path-suffix matches within a wing.
+- Tiny non-empty source files that produce no chunks are reported separately from
+  already-filed skips, and unchanged tiny files are skipped on later incremental
+  mines via a small per-wing hash sidecar.
+
+### Verified
+
+- Real MCP stdio smoke for delete-after-read and KG provenance.
+- Real CLI smoke for export-to-import piping, backup `--out`, source-path read
+  discovery, tiny-file mining, migrate-storage happy path/boundary/guard, and
+  `python -m mempalace_code.cli` warning removal.
+- Full release gate: 2229 tests passed, 4 deselected.
+
+## 2026-05-23 · UPSTREAM-KG-TEMPORAL-VALIDATION
+
+Validate KG temporal inputs (reject inverted validity windows, enforce ISO-8601 dates) and expose `valid_to` and `source_file` on `mempalace_kg_add`.
+
 Current command/package names: the CLI is `mempalace-code`, the import package is
 `mempalace_code`, and the MCP module is `python -m mempalace_code.mcp_server`.
 Older historical entries may mention legacy `mempalace` names that were valid
@@ -66,7 +155,7 @@ when those changes landed.
 - Pre-optimize backups are bounded by default to the newest 5 managed archives
   unless `backup_retain_count` is explicitly set; manual and scheduled backups
   remain keep-all by default.
-- The collected test suite is now 2025 tests.
+- The release gate collected 2025 tests.
 
 ### Fixed
 
@@ -108,7 +197,7 @@ when those changes landed.
   project mining by default, unless explicitly force-included.
 - `MEMPALACE_BACKUP_MIN_FREE_BYTES` and `backup_min_free_bytes` remain supported
   as compatibility aliases for the newer `backup_disk_min_free_bytes` floor.
-- The collected test suite is now 1769 tests.
+- The release gate collected 1769 tests.
 
 ### Fixed
 

{mempalace_code-1.10.0 → mempalace_code-1.10.2}/CONTRIBUTING.md

@@ -13,12 +13,14 @@ pip install -e ".[dev]"    # pytest, pyright, ruff, watchfiles
 ## Running Tests
 
 ```bash
-pytest tests/ -v
+python -m pytest tests/ -v
+python -m pyright --pythonpath "$(python -c 'import sys; print(sys.executable)')"
+ruff check mempalace_code/ tests/ scripts/
+ruff format --check mempalace_code/ tests/ scripts/
 ```
 
-All tests must pass before submitting a PR. Tests should run without API keys or network
-access. `pyright` is installed with the dev extra for advisory type-checking; the current
-zero-error target is tracked in the backlog.
+All tests and checks must pass before submitting a PR. Tests should run without
+API keys or network access unless they are explicitly marked `needs_network`.
 
 ## Running Benchmarks
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mempalace-code
-Version: 1.10.0
+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
@@ -72,13 +72,13 @@ No cloud service, no API keys, no subscription. After the one-time embedding mod
 <table>
 <tr>
 <td align="center"><strong>Language-Aware Mining</strong><br><sub>AST, regex, and adaptive chunking<br>matched to each file type</sub></td>
-<td align="center"><strong>28 MCP Tools</strong><br><sub>Any MCP-capable agent<br>search, store, traverse · static profiles</sub></td>
+<td align="center"><strong>29 MCP Tools</strong><br><sub>Any MCP-capable agent<br>search, store, traverse · static profiles</sub></td>
 <td align="center"><strong>Temporal Knowledge Graph</strong><br><sub>Facts that change over time<br>with validity windows</sub></td>
 </tr>
 <tr>
 <td align="center"><strong>595x Token Savings</strong><br><sub>measured peak · median 80x<br><a href="docs/BENCH_TOKEN_DELTA.md">scales with project size</a></sub></td>
 <td align="center"><strong>Cross-Project Tunnels</strong><br><sub>Search <code>auth</code> in one project<br>find it everywhere</sub></td>
-<td align="center"><strong>2025 Tests · $0 Cost</strong><br><sub>Every feature acceptance-gated<br>offline after model setup</sub></td>
+<td align="center"><strong>2200+ Tests · $0 Cost</strong><br><sub>Every feature acceptance-gated<br>offline after model setup</sub></td>
 </tr>
 </table>
 
@@ -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
@@ -124,7 +124,7 @@ codex mcp add mempalace-code -- python -m mempalace_code.mcp_server   # connect
 mempalace-code watch ~/projects/           # re-mines on every commit, zero noise
 ```
 
-This makes all 28 tools available to your AI. To expose a reduced subset, add a `--profile` flag (e.g. `-- python -m mempalace_code.mcp_server --profile=minimal`). For proactive search and storage (without you asking), you'll also need to add usage rules to your `CLAUDE.md` (or equivalent agent-instruction file) — copy from [`docs/LLM_USAGE_RULES.md`](docs/LLM_USAGE_RULES.md), or let [`docs/AGENT_INSTALL.md`](docs/AGENT_INSTALL.md) Section 7 inject them for you.
+This makes all 29 tools available to your AI. To expose a reduced subset, add a `--profile` flag (e.g. `-- python -m mempalace_code.mcp_server --profile=minimal`). For proactive search and storage (without you asking), you'll also need to add usage rules to your `CLAUDE.md` (or equivalent agent-instruction file) — copy from [`docs/LLM_USAGE_RULES.md`](docs/LLM_USAGE_RULES.md), or let [`docs/AGENT_INSTALL.md`](docs/AGENT_INSTALL.md) Section 7 inject them for you.
 
 </details>
 
@@ -142,7 +142,7 @@ Evaluate mempalace-code for this repo specifically, not generic memory tooling.
 2. Highest-ROI surfaces: rank code, docs/prose, design notes, conversation/log exports, manual decisions, KG facts, architecture relationships.
 3. Stack support: list supported languages/file types actually indexed; name unsupported extensions that are skipped by default. Distinguish tree-sitter AST, regex structural, Markdown/prose, Kubernetes YAML, and adaptive chunking.
 4. Agent workflow fit: which MCP tools should you use proactively (`mempalace_search`, `mempalace_code_search`, `mempalace_file_context`, KG, tunnels, diary, manual drawers)?
-5. Ops fit: recommend global MCP, project-scoped MCP, or no MCP; cover 28-tool prompt surface and profile subsetting options (`--profile`, `--tools`, `--exclude`), `mine` vs `mine-all`, `watch` cadence, backup/repair, and offline/model constraints.
+5. Ops fit: recommend global MCP, project-scoped MCP, or no MCP; cover 29-tool prompt surface and profile subsetting options (`--profile`, `--tools`, `--exclude`), `mine` vs `mine-all`, `watch` cadence, backup/repair, and offline/model constraints.
 6. Decision: install now, try scoped for a week, wait for a named feature, or skip. Give the first 3 commands you would run.
 7. If waiting: ask me whether to draft a GitHub feature request.
 ```
@@ -156,7 +156,7 @@ as a complement, not a replacement. A good trial order is:
 3. **Code mining last** — start with one high-value subproject, then expand if
    agents actually use the results.
 
-Cost caveat: the MCP server defaults to all 28 tools. Use `--profile=minimal` or
+Cost caveat: the MCP server defaults to all 29 tools. Use `--profile=minimal` or
 `--tools=search,add_drawer` at startup to reduce the prompt/tool-surface cost.
 Proactive use also depends on adding the usage-rules block to agent instructions.
 Prefer project-scoped MCP for trials, and keep it only if searches, KG lookups,
@@ -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
@@ -385,7 +388,7 @@ mempalace-code organizes memories into a navigable structure — the same mental
 
 ---
 
-### MCP Server — 28 Tools {#mcp-tool-profiles}
+### MCP Server — 29 Tools {#mcp-tool-profiles}
 
 ```bash
 claude mcp add mempalace-code -- python -m mempalace_code.mcp_server
@@ -395,7 +398,7 @@ The MCP server registration name defaults to `mempalace-code`. The MCP tool
 identifiers remain `mempalace_*` for compatibility with existing agents and
 usage rules.
 
-By default all 28 tools are exposed. Use startup flags to reduce the tool surface
+By default all 29 tools are exposed. Use startup flags to reduce the tool surface
 (GitHub issue #6 — static profiles lower prompt cost while preserving stable
 named-tool trigger patterns in usage rules):
 
@@ -416,7 +419,7 @@ claude mcp add mempalace-code -- python -m mempalace_code.mcp_server --profile=f
 
 | Profile | Tools | Best for |
 |---------|-------|----------|
-| `full` _(default)_ | all 28 | Full capability; no surface reduction |
+| `full` _(default)_ | all 29 | Full capability; no surface reduction |
 | `minimal` | 4 | Search + store only |
 | `kg` | 8 | Minimal + temporal knowledge graph |
 | `code` | 10 | Code archaeology; no drawer-write/diary tools (`mine` included) |
@@ -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,9 +835,9 @@ 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 | 2025 tests, every feature acceptance-gated |
+| ~30% test coverage | 2200+ tests, every feature acceptance-gated |
 | No backup, no recovery | `backup` / `restore` / `export` / `import` |
 | No incremental mining | Content-hash incremental: only changed files re-chunked |
 | No code-search | `code_search` — filter by language, symbol, glob |
@@ -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>
@@ -933,7 +969,7 @@ Code mining is automatic via `mempalace-code watch`. For conversation context (d
 mempalace/
 ├── mempalace_code/
 │   ├── cli.py              ← CLI entry point
-│   ├── mcp_server.py       ← MCP server (28 tools, profiled at startup)
+│   ├── mcp_server.py       ← MCP server (29 tools, profiled at startup)
 │   ├── storage.py          ← LanceDB vector storage
 │   ├── miner.py            ← language-aware code chunking
 │   ├── convo_miner.py      ← conversation ingest
@@ -945,7 +981,7 @@ mempalace/
 ├── benchmarks/             ← reproducible benchmark runners
 ├── hooks/                  ← Claude Code auto-save hooks (legacy, optional)
 ├── examples/               ← usage examples
-└── tests/                  ← 2025 tests
+└── tests/                  ← 2200+ tests
 ```
 
 </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.0-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.0 → mempalace_code-1.10.2}/README.md

@@ -23,13 +23,13 @@ No cloud service, no API keys, no subscription. After the one-time embedding mod
 <table>
 <tr>
 <td align="center"><strong>Language-Aware Mining</strong><br><sub>AST, regex, and adaptive chunking<br>matched to each file type</sub></td>
-<td align="center"><strong>28 MCP Tools</strong><br><sub>Any MCP-capable agent<br>search, store, traverse · static profiles</sub></td>
+<td align="center"><strong>29 MCP Tools</strong><br><sub>Any MCP-capable agent<br>search, store, traverse · static profiles</sub></td>
 <td align="center"><strong>Temporal Knowledge Graph</strong><br><sub>Facts that change over time<br>with validity windows</sub></td>
 </tr>
 <tr>
 <td align="center"><strong>595x Token Savings</strong><br><sub>measured peak · median 80x<br><a href="docs/BENCH_TOKEN_DELTA.md">scales with project size</a></sub></td>
 <td align="center"><strong>Cross-Project Tunnels</strong><br><sub>Search <code>auth</code> in one project<br>find it everywhere</sub></td>
-<td align="center"><strong>2025 Tests · $0 Cost</strong><br><sub>Every feature acceptance-gated<br>offline after model setup</sub></td>
+<td align="center"><strong>2200+ Tests · $0 Cost</strong><br><sub>Every feature acceptance-gated<br>offline after model setup</sub></td>
 </tr>
 </table>
 
@@ -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
@@ -75,7 +75,7 @@ codex mcp add mempalace-code -- python -m mempalace_code.mcp_server   # connect
 mempalace-code watch ~/projects/           # re-mines on every commit, zero noise
 ```
 
-This makes all 28 tools available to your AI. To expose a reduced subset, add a `--profile` flag (e.g. `-- python -m mempalace_code.mcp_server --profile=minimal`). For proactive search and storage (without you asking), you'll also need to add usage rules to your `CLAUDE.md` (or equivalent agent-instruction file) — copy from [`docs/LLM_USAGE_RULES.md`](docs/LLM_USAGE_RULES.md), or let [`docs/AGENT_INSTALL.md`](docs/AGENT_INSTALL.md) Section 7 inject them for you.
+This makes all 29 tools available to your AI. To expose a reduced subset, add a `--profile` flag (e.g. `-- python -m mempalace_code.mcp_server --profile=minimal`). For proactive search and storage (without you asking), you'll also need to add usage rules to your `CLAUDE.md` (or equivalent agent-instruction file) — copy from [`docs/LLM_USAGE_RULES.md`](docs/LLM_USAGE_RULES.md), or let [`docs/AGENT_INSTALL.md`](docs/AGENT_INSTALL.md) Section 7 inject them for you.
 
 </details>
 
@@ -93,7 +93,7 @@ Evaluate mempalace-code for this repo specifically, not generic memory tooling.
 2. Highest-ROI surfaces: rank code, docs/prose, design notes, conversation/log exports, manual decisions, KG facts, architecture relationships.
 3. Stack support: list supported languages/file types actually indexed; name unsupported extensions that are skipped by default. Distinguish tree-sitter AST, regex structural, Markdown/prose, Kubernetes YAML, and adaptive chunking.
 4. Agent workflow fit: which MCP tools should you use proactively (`mempalace_search`, `mempalace_code_search`, `mempalace_file_context`, KG, tunnels, diary, manual drawers)?
-5. Ops fit: recommend global MCP, project-scoped MCP, or no MCP; cover 28-tool prompt surface and profile subsetting options (`--profile`, `--tools`, `--exclude`), `mine` vs `mine-all`, `watch` cadence, backup/repair, and offline/model constraints.
+5. Ops fit: recommend global MCP, project-scoped MCP, or no MCP; cover 29-tool prompt surface and profile subsetting options (`--profile`, `--tools`, `--exclude`), `mine` vs `mine-all`, `watch` cadence, backup/repair, and offline/model constraints.
 6. Decision: install now, try scoped for a week, wait for a named feature, or skip. Give the first 3 commands you would run.
 7. If waiting: ask me whether to draft a GitHub feature request.
 ```
@@ -107,7 +107,7 @@ as a complement, not a replacement. A good trial order is:
 3. **Code mining last** — start with one high-value subproject, then expand if
    agents actually use the results.
 
-Cost caveat: the MCP server defaults to all 28 tools. Use `--profile=minimal` or
+Cost caveat: the MCP server defaults to all 29 tools. Use `--profile=minimal` or
 `--tools=search,add_drawer` at startup to reduce the prompt/tool-surface cost.
 Proactive use also depends on adding the usage-rules block to agent instructions.
 Prefer project-scoped MCP for trials, and keep it only if searches, KG lookups,
@@ -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
@@ -336,7 +339,7 @@ mempalace-code organizes memories into a navigable structure — the same mental
 
 ---
 
-### MCP Server — 28 Tools {#mcp-tool-profiles}
+### MCP Server — 29 Tools {#mcp-tool-profiles}
 
 ```bash
 claude mcp add mempalace-code -- python -m mempalace_code.mcp_server
@@ -346,7 +349,7 @@ The MCP server registration name defaults to `mempalace-code`. The MCP tool
 identifiers remain `mempalace_*` for compatibility with existing agents and
 usage rules.
 
-By default all 28 tools are exposed. Use startup flags to reduce the tool surface
+By default all 29 tools are exposed. Use startup flags to reduce the tool surface
 (GitHub issue #6 — static profiles lower prompt cost while preserving stable
 named-tool trigger patterns in usage rules):
 
@@ -367,7 +370,7 @@ claude mcp add mempalace-code -- python -m mempalace_code.mcp_server --profile=f
 
 | Profile | Tools | Best for |
 |---------|-------|----------|
-| `full` _(default)_ | all 28 | Full capability; no surface reduction |
+| `full` _(default)_ | all 29 | Full capability; no surface reduction |
 | `minimal` | 4 | Search + store only |
 | `kg` | 8 | Minimal + temporal knowledge graph |
 | `code` | 10 | Code archaeology; no drawer-write/diary tools (`mine` included) |
@@ -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,9 +786,9 @@ 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 | 2025 tests, every feature acceptance-gated |
+| ~30% test coverage | 2200+ tests, every feature acceptance-gated |
 | No backup, no recovery | `backup` / `restore` / `export` / `import` |
 | No incremental mining | Content-hash incremental: only changed files re-chunked |
 | No code-search | `code_search` — filter by language, symbol, glob |
@@ -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>
@@ -884,7 +920,7 @@ Code mining is automatic via `mempalace-code watch`. For conversation context (d
 mempalace/
 ├── mempalace_code/
 │   ├── cli.py              ← CLI entry point
-│   ├── mcp_server.py       ← MCP server (28 tools, profiled at startup)
+│   ├── mcp_server.py       ← MCP server (29 tools, profiled at startup)
 │   ├── storage.py          ← LanceDB vector storage
 │   ├── miner.py            ← language-aware code chunking
 │   ├── convo_miner.py      ← conversation ingest
@@ -896,7 +932,7 @@ mempalace/
 ├── benchmarks/             ← reproducible benchmark runners
 ├── hooks/                  ← Claude Code auto-save hooks (legacy, optional)
 ├── examples/               ← usage examples
-└── tests/                  ← 2025 tests
+└── tests/                  ← 2200+ tests
 ```
 
 </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.0-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/