mempalace-code 1.4.0__tar.gz → 1.5.0__tar.gz

mempalace_code-1.5.0/.claude/skills/release-prep/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: release-prep
+description: Pre-release docs sync — diff HEAD against the last v* tag on the publish remote, list feature additions, update README language/tool inventory, draft the CHANGELOG release entry, propose the version bump. Runs before /release. Prevents shipping with stale docs.
+disable-model-invocation: false
+---
+
+# Release Prep Workflow
+
+Prepare docs for a PyPI release. Complements `/release` — this is the **docs sync** step; `/release` is the **cut + publish** step.
+
+## When to Use
+
+- Before running `/release`.
+- After a batch of features has landed on `main` and you need to know "what's new since last publish?"
+- User says: "prepare for release", "what's new since last publish", "update docs before release".
+
+## Golden Rule
+
+**Use the `publish` remote, not local tags.** Local tags can include inherited upstream tags that were never published. PyPI watches the `publish` remote.
+
+## Steps
+
+### Step 1: Resolve last published version
+
+```bash
+# Last v* tag on the publish remote (PyPI source of truth)
+LAST_TAG=$(git ls-remote --tags publish 2>/dev/null \
+  | grep -E 'refs/tags/v[0-9]+\.[0-9]+\.[0-9]+$' \
+  | awk '{print $2}' | sed 's|refs/tags/||' \
+  | sort -V | tail -1)
+echo "Last published: $LAST_TAG"
+```
+
+If `publish` is not a git remote, fall back to asking the user which remote holds releases — do **not** use the latest local tag blindly.
+
+Compare against `pyproject.toml` — if they differ, flag and investigate before continuing.
+
+### Step 2: List commits since last publish
+
+```bash
+git log "$LAST_TAG..HEAD" --oneline
+git log "$LAST_TAG..HEAD" --oneline | wc -l
+```
+
+Group by conventional-commit scope. Ignore noise: `chore: archive completed tasks`, `chore: autopilot housekeeping`, `fix(*): auto-fix verify errors`.
+
+Categorize user-facing changes:
+
+| Category | Signal |
+|----------|--------|
+| New feature | `feat(*)` with description (e.g. `feat(MINE-DART): Dart language support`) |
+| New MCP tool | `feat(MCP-*)` or diff touches `mempalace/mcp_server.py` tool registry |
+| Bug fix | `fix(*)` not tagged `auto-fix verify` |
+| Docs | `docs(*)` |
+| Breaking | Any commit whose body says "BREAKING" or touches storage format / public API |
+
+### Step 3: Detect feature surface changes
+
+Cross-check the commit log against the code to catch anything the commit messages missed.
+
+**New languages in the miner** — diff language dispatch tables:
+
+```bash
+git diff "$LAST_TAG..HEAD" -- mempalace/miner.py \
+  | grep -E '^\+.*(LANG_|_chunks|parse_|tool_|language.*=.*")'
+```
+
+**New MCP tools** — compare tool registries:
+
+```bash
+git show "$LAST_TAG:mempalace/mcp_server.py" 2>/dev/null \
+  | grep -oE '"mempalace_[a-z_]+":' | sort -u > /tmp/mcp_before.txt
+grep -oE '"mempalace_[a-z_]+":' mempalace/mcp_server.py | sort -u > /tmp/mcp_after.txt
+diff /tmp/mcp_before.txt /tmp/mcp_after.txt
+```
+
+**Python version bumps** — scan `pyproject.toml` history for `requires-python` changes.
+
+### Step 4: Check docs for staleness
+
+For each item in Step 3, verify it appears in the right docs file.
+
+| Change | Doc that must update |
+|--------|----------------------|
+| New language | `README.md` — "What gets indexed" bullet + Language-Aware Code Mining table |
+| New MCP tool | `README.md` — MCP tool inventory tables (Read / Write / Graph / Diary groups) |
+| New MCP tool | `docs/LLM_USAGE_RULES.md` — Routing table + any relevant rule section |
+| Python minimum bump | `README.md` Requirements section + `pyproject.toml` `requires-python` |
+| Breaking change | `CHANGELOG.md` under `### Breaking` |
+| Any feature | `CHANGELOG.md` under the release header for this version |
+
+Report each stale location as a to-fix item. Do not assume commit messages already covered it.
+
+### Step 5: Propose version bump
+
+| What changed | Bump |
+|--------------|------|
+| Any breaking change (API / CLI / storage format / MCP tool signatures) | Major (X.0.0) |
+| New languages, new MCP tools, new CLI commands, behavior changes that are backwards-compatible | Minor (0.X.0) |
+| Only bug fixes, docs, CI, internal refactors | Patch (0.0.X) |
+
+State the reasoning. Ask the user to confirm.
+
+### Step 6: Draft the CHANGELOG release entry
+
+Open `CHANGELOG.md`. If scattered per-task entries already exist at the top (pattern: `## YYYY-MM-DD · TASK-SLUG`), **consolidate** them under a single release header:
+
+```markdown
+## vX.Y.Z — YYYY-MM-DD
+
+### Added
+- **N new languages in the code miner:**
+  - **<Lang>** — <symbol types>; <notable features> (<TASK-SLUG>)
+  - …
+- **N new MCP tools:**
+  - `mempalace_<name>` — <one-line purpose> (<TASK-SLUG>)
+  - …
+
+### Changed
+- **<human-friendly summary>** — <what shifted>, <why it matters> (<TASK-SLUG>)
+
+### Fixed
+- <if applicable>
+
+### Breaking
+- <if applicable — otherwise omit the section>
+```
+
+Do **not** leave the per-task entries above the release header; consolidate them into bullets beneath it. One release header per version.
+
+### Step 7: Update README and LLM_USAGE_RULES
+
+Apply the to-fix items from Step 4. Touch `README.md` and `docs/LLM_USAGE_RULES.md` directly. Do not ask the user to paste snippets — just make the edits.
+
+### Step 8: Bump `pyproject.toml`
+
+```bash
+# Replace "<NEW>" with the confirmed version
+grep -E "^version\s*=" pyproject.toml
+```
+
+Edit the file; do not use `sed -i` unless portable (`sed -i '' 's/…/…/'` on macOS, plain `sed -i` on Linux). Prefer the Edit tool.
+
+### Step 9: Commit
+
+```bash
+git add pyproject.toml CHANGELOG.md README.md docs/LLM_USAGE_RULES.md
+git commit -m "chore: prepare release vX.Y.Z"
+```
+
+Do **not** tag or push. That is `/release`'s job.
+
+### Step 10: Hand off
+
+Report:
+
+```
+## Release-prep for vX.Y.Z
+
+Last published: vA.B.C (publish remote)
+Commits since:  <N>
+
+Features added:
+- <language list>
+- <MCP tool list>
+- <other>
+
+Docs updated:
+- README.md: <what>
+- CHANGELOG.md: v<version> release header
+- docs/LLM_USAGE_RULES.md: <if touched>
+- pyproject.toml: <old> → <new>
+
+Next: run /release to cut the tag and push to publish.
+```
+
+## Gotchas
+
+- **`git describe --tags --abbrev=0` is wrong for this use case.** It returns the most recent local tag regardless of origin. Upstream tags pulled into the fork (e.g. v3.0.0 from an inherited upstream) will poison the result. Always use `git ls-remote --tags publish`.
+- **`pyproject.toml` version and the `publish`-remote latest tag should match** after the last release. If `pyproject.toml` is ahead, the previous release was cut but the tag never pushed — investigate before bumping again.
+- **Do not push to `origin` on release.** Per project feedback: releases go to `publish` only. `/release` handles this; this skill does not push.
+- **Skip the per-task changelog headers.** Some autopilot flows write `## YYYY-MM-DD · TASK-SLUG` entries at the top of CHANGELOG as work lands. Before release, consolidate them into a single release header with grouped bullets. Do not leave both forms.
+
+## Output
+
+```
+## Release-prep summary
+
+Last published: <vX.Y.Z>
+Proposed version: <vA.B.C> (<major|minor|patch>)
+Commits:       <N> since <vX.Y.Z>
+Features:      <count> new languages, <count> new MCP tools
+Docs updated:  <list>
+Version file:  bumped
+Committed:     <yes|no>
+
+Hand off to: /release
+```

mempalace_code-1.5.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - run: pip install -e ".[dev,treesitter]"
+      - run: python3 -m pytest tests/ -v -m "not needs_network"
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - run: pip install ruff
+      - run: ruff check .
+      - run: ruff format --check .

{mempalace_code-1.4.0 → mempalace_code-1.5.0}/.github/workflows/publish.yml

@@ -11,13 +11,13 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.11"
       - run: pip install build
       - run: python -m build
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v5
         with:
           name: dist
           path: dist/
@@ -29,7 +29,7 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v5
         with:
           name: dist
           path: dist/

{mempalace_code-1.4.0 → mempalace_code-1.5.0}/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## v1.5.0 — 2026-04-21
+
+### Added
+
+- **5 new languages in the code miner:**
+  - **Dart** — classes, mixins, extensions, enums, functions; named/factory constructors, async/await (MINE-DART)
+  - **Scala** — classes, case classes, objects, traits, enums, functions; implicits, type aliases, generics, access modifiers (MINE-SCALA)
+  - **Kubernetes manifests** — Deployments, Services, ConfigMaps, Secrets, Ingresses, CRDs from `.yaml`/`.yml`, indexed by kind, namespace, name, labels (MINE-K8S)
+  - **PHP** — classes, interfaces, traits, enums (PHP 8.1+), functions, methods, namespaces; Laravel / WordPress / Symfony project recognition (MINE-PHP)
+  - **Swift** — classes, structs, enums, protocols, functions, properties, extensions, actors, async/await (MINE-SWIFT)
+- **2 new MCP tools:**
+  - `mempalace_mine` — agents can trigger incremental or full project re-mining without CLI access; returns structured counts of files processed and drawers filed (MCP-MINE-TRIGGER)
+  - `mempalace_file_context` — returns all indexed chunks for a specific source file, ordered by `chunk_index`; useful for reviewing what was mined, handling deleted/renamed files, or getting ordered file context without reading from disk (MCP-FILE-CONTEXT)
+
+### Changed
+
+- **LLM usage rules rewritten as LLM-agnostic** — `docs/LLM_USAGE_RULES.md` now targets any MCP-capable agent (Claude Code, Codex, Cursor, Windsurf, Continue, Zed, Aider, …); routing table maps 16 common tasks to the right specialist tool; `MEMPALACE_AGENT_NAME` env var for diary attribution; extended Never list covering destructive-delete guards, diary non-authoritativeness, and absence-from-search-miss; correction recipe added. `docs/AGENT_INSTALL.md` §7.3 synced. README's misleading "AI learns the protocol automatically" claim replaced with a concrete pointer to the usage rules. (LLM-USAGE-RULES)
+
+## v1.4.1 — 2026-04-20
+
+### Changed
+- **Docs: hooks are legacy** — MCP tools + usage rules are now the recommended approach for all agents (Claude Code, Codex, Cursor); hooks demoted to optional Claude Code-only extra
+- **Docs: unified saving story** — README, AGENT_INSTALL, and hooks README all consistently describe watcher for code mining + MCP for conversation context
+
 ## v1.4.0 — 2026-04-19
 
 ### Added

{mempalace_code-1.4.0 → mempalace_code-1.5.0}/CLAUDE.md

@@ -2,7 +2,7 @@
 
 ## Stack
 
-- **Python** 3.9+ (supports 3.9–3.12)
+- **Python** 3.11+ (supports 3.11–3.14)
 - **Storage**: LanceDB (core, crash-safe vector DB — no server required)
 - **Embeddings**: sentence-transformers (local, no API key)
 - **Config**: PyYAML

{mempalace_code-1.4.0 → mempalace_code-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mempalace-code
-Version: 1.4.0
+Version: 1.5.0
 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
@@ -16,7 +16,6 @@ Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -24,7 +23,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Utilities
-Requires-Python: >=3.9
+Requires-Python: >=3.11
 Requires-Dist: lancedb>=0.17
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: sentence-transformers>=2.2
@@ -33,15 +32,15 @@ Requires-Dist: chromadb<2,>=0.5.0; extra == 'chroma'
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == 'dev'
 Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Requires-Dist: watchfiles>=1.0; extra == 'dev'
 Provides-Extra: spellcheck
 Requires-Dist: autocorrect>=2.0; extra == 'spellcheck'
 Provides-Extra: treesitter
 Requires-Dist: tree-sitter-go<0.26,>=0.23; extra == 'treesitter'
-Requires-Dist: tree-sitter-python<0.26,>=0.23; (python_version >= '3.10') and extra == 'treesitter'
+Requires-Dist: tree-sitter-python<0.26,>=0.23; extra == 'treesitter'
 Requires-Dist: tree-sitter-rust<0.26,>=0.23; extra == 'treesitter'
 Requires-Dist: tree-sitter-typescript<0.26,>=0.23; extra == 'treesitter'
-Requires-Dist: tree-sitter<0.24,>=0.22; (python_version < '3.10') and extra == 'treesitter'
-Requires-Dist: tree-sitter<0.26,>=0.22; (python_version >= '3.10') and extra == 'treesitter'
+Requires-Dist: tree-sitter<0.26,>=0.22; extra == 'treesitter'
 Provides-Extra: watch
 Requires-Dist: watchfiles>=1.0; extra == 'watch'
 Description-Content-Type: text/markdown
@@ -88,7 +87,13 @@ No cloud. No API keys. No subscription. Nothing leaves your machine.
 ## Quick Start
 
 ```bash
-pip install mempalace-code
+uv tool install mempalace-code        # recommended (fast, Rust-based)
+# or
+pipx install mempalace-code           # alternative
+# or
+pip install mempalace-code            # into current environment
+# or
+uvx --from mempalace-code mempalace --help  # try without installing
 ```
 
 Then ask your AI to read [`docs/AGENT_INSTALL.md`](docs/AGENT_INSTALL.md) — it will handle setup, MCP wiring, prompt injection, and verification automatically.
@@ -102,7 +107,12 @@ mempalace mine ~/projects/myapp       # index your codebase
 claude mcp add mempalace -- python -m mempalace.mcp_server  # connect to Claude Code
 ```
 
-This makes the 27 tools available to your AI. For proactive search and storage (without you asking), you'll also need to add usage rules to your `CLAUDE.md` — see [`docs/AGENT_INSTALL.md`](docs/AGENT_INSTALL.md) Section 7.
+**Optional: auto-sync on commit** (requires `[watch]` extra — see [Auto-Watch](#auto-watch)):
+```bash
+mempalace watch ~/projects/           # re-mines on every commit, zero noise
+```
+
+This makes the 27 tools available to your AI. 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>
 
@@ -139,7 +149,7 @@ You write code. You make decisions. You debug things. Between sessions, all that
 mempalace-code **indexes it once** into a local vector store, then your AI finds it in milliseconds — using [595x fewer tokens](docs/BENCH_TOKEN_DELTA.md) than grep + read at measured peak (median 80x on a 19k-chunk project, and it keeps scaling). Think of it as `git log` for everything that *isn't* in the code: the *why*, the discussions, the dead ends, the decisions.
 
 **What gets indexed:**
-- Code files — functions, classes, modules (Python, TypeScript/JS, Go, Rust, C/C++, C#, F#, VB.NET, XAML, Java, Kotlin, Markdown)
+- Code files — functions, classes, modules (Python, TypeScript/JS, Go, Rust, C/C++, C#, F#, VB.NET, XAML, Java, Kotlin, Scala, Swift, Dart, PHP, Markdown) plus Kubernetes manifests
 - .NET solutions — `.sln`/`.csproj` project graphs, cross-project symbol relationships, interface implementations
 - Conversation exports — Claude, ChatGPT, Slack
 - Architecture notes, decisions, anything you store manually
@@ -162,10 +172,15 @@ mempalace-code **indexes it once** into a local vector store, then your AI finds
 | Rust | Functions, structs, enums, traits, impls | Tree-sitter |
 | Java | Classes, interfaces, methods, annotations | Regex |
 | Kotlin | Classes, objects, functions, extensions | Regex |
+| Scala | Classes, case classes, objects, traits, enums, functions, implicits, type aliases, generics | Regex |
+| Swift | Classes, structs, enums, protocols, functions, properties, extensions, actors, async/await | Regex |
+| Dart | Classes, mixins, extensions, enums, functions, named/factory constructors, async/await | Regex |
+| PHP | Classes, interfaces, traits, enums (8.1+), functions, methods, namespaces (Laravel/WP/Symfony aware) | Regex |
 | C# | Classes, interfaces, records, methods, properties | Regex |
 | F# / VB.NET | Modules, types, functions | Regex |
 | XAML | Controls, resources, code-behind linking | Regex |
 | C / C++ | Functions, structs, enums, classes | Regex |
+| Kubernetes manifests | Deployments, Services, ConfigMaps, Secrets, Ingresses, CRDs (indexed by kind/namespace/labels) | YAML-aware |
 | Markdown / plain text | Heading sections, paragraphs | — |
 | YAML / JSON / TOML | Adaptive line-count | — |
 
@@ -184,6 +199,16 @@ Mining is **incremental** by default — content-hash based, only changed files
 
 Keep your palace in sync automatically. By default, watches `.git/refs/heads/` and re-mines only on **commit** — no noise from work-in-progress saves. Handles multiple branches and worktrees.
 
+Requires the `watch` extra:
+```bash
+uv tool install "mempalace-code[watch]"   # or: pipx install "mempalace-code[watch]"
+```
+
+Already installed without it? Add watchfiles:
+```bash
+uv tool inject mempalace-code watchfiles  # or: pipx inject mempalace-code watchfiles
+```
+
 ```bash
 mempalace watch ~/projects/                      # watch all projects (on commit, default)
 mempalace watch ~/projects/ --on-save            # watch all file saves instead (noisier)
@@ -252,6 +277,7 @@ claude mcp add mempalace -- python -m mempalace.mcp_server
 | `mempalace_get_taxonomy` | Full wing → room → count tree |
 | `mempalace_search` | Semantic search with optional wing/room filters |
 | `mempalace_code_search` | Filter by language, symbol name/type, file glob |
+| `mempalace_file_context` | All indexed chunks for a source file, ordered by chunk_index |
 | `mempalace_check_duplicate` | Similarity check before filing (0.9 threshold) |
 
 </details>
@@ -264,6 +290,7 @@ claude mcp add mempalace -- python -m mempalace.mcp_server
 | `mempalace_add_drawer` | File verbatim content into a wing/room |
 | `mempalace_delete_drawer` | Remove a drawer by ID |
 | `mempalace_delete_wing` | Delete all drawers in a wing |
+| `mempalace_mine` | Trigger re-mining of a project directory (incremental or full) |
 
 </details>
 
@@ -307,7 +334,7 @@ claude mcp add mempalace -- python -m mempalace.mcp_server
 
 </details>
 
-The AI learns the memory protocol automatically from the `mempalace_status` response. No manual configuration.
+MCP tools are discoverable by any MCP-capable client automatically. To teach the AI *when* and *how* to use them, paste the usage rules from [`docs/LLM_USAGE_RULES.md`](docs/LLM_USAGE_RULES.md) into your agent's instructions (CLAUDE.md, AGENTS.md, `.cursorrules`, etc.) — otherwise the tools are available but the assistant will not know the protocol.
 
 ---
 
@@ -491,13 +518,13 @@ curl -fsSL https://raw.githubusercontent.com/rergards/mempalace-code/main/script
 **Optional extras:**
 
 ```bash
-pip install "mempalace-code[treesitter]"  # AST parsing (Python 3.10+; TS/JS on 3.9+)
+pip install "mempalace-code[treesitter]"  # AST parsing
 pip install "mempalace-code[chroma]"      # ChromaDB legacy backend (deprecated)
 pip install "mempalace-code[spellcheck]"  # autocorrect for room/wing names
 pip install "mempalace-code[dev]"         # pytest + ruff
 ```
 
-**Requirements:** Python 3.9+. ~80 MB embedding model downloaded once during `mempalace init`.
+**Requirements:** Python 3.11+. ~80 MB embedding model downloaded once during `mempalace init`.
 
 </details>
 
@@ -547,21 +574,15 @@ mempalace fetch-model                             # pre-download for offline use
 </details>
 
 <details>
-<summary><strong>Auto-Save Hooks</strong></summary>
+<summary><strong>Saving Conversation Context</strong></summary>
 
-Two Claude Code hooks for automatic memory saving:
+Code mining is automatic via `mempalace watch-all`. For conversation context (decisions, discussions, debugging notes), the AI uses MCP tools directly — works with **any agent** (Claude Code, Codex, Cursor, etc.):
 
-- **Stop Hook** — after each response, saves topics, decisions, and code changes
-- **PreCompact Hook** — emergency save before context compression
+1. Wire the MCP server (see [install docs](docs/AGENT_INSTALL.md))
+2. Add usage rules to your agent's instructions (CLAUDE.md, system prompt, etc.)
+3. The agent calls `mempalace_add_drawer` and `mempalace_diary_write` during sessions
 
-```json
-{
-  "hooks": {
-    "Stop": [{"matcher": "", "hooks": [{"type": "command", "command": "/path/to/mempalace/hooks/mempal_save_hook.sh"}]}],
-    "PreCompact": [{"matcher": "", "hooks": [{"type": "command", "command": "/path/to/mempalace/hooks/mempal_precompact_hook.sh"}]}]
-  }
-}
-```
+> **Legacy:** Claude Code also supports optional [auto-save hooks](hooks/README.md) that remind the AI to save at fixed intervals. These are redundant if MCP + usage rules are set up.
 
 </details>
 
@@ -581,7 +602,7 @@ mempalace/
 │   ├── palace_graph.py     ← room navigation graph
 │   └── layers.py           ← 4-layer memory stack
 ├── benchmarks/             ← reproducible benchmark runners
-├── hooks/                  ← Claude Code auto-save hooks
+├── hooks/                  ← Claude Code auto-save hooks (legacy, optional)
 ├── examples/               ← usage examples
 └── tests/                  ← 1008 tests
 ```

{mempalace_code-1.4.0 → mempalace_code-1.5.0}/README.md

@@ -40,7 +40,13 @@ No cloud. No API keys. No subscription. Nothing leaves your machine.
 ## Quick Start
 
 ```bash
-pip install mempalace-code
+uv tool install mempalace-code        # recommended (fast, Rust-based)
+# or
+pipx install mempalace-code           # alternative
+# or
+pip install mempalace-code            # into current environment
+# or
+uvx --from mempalace-code mempalace --help  # try without installing
 ```
 
 Then ask your AI to read [`docs/AGENT_INSTALL.md`](docs/AGENT_INSTALL.md) — it will handle setup, MCP wiring, prompt injection, and verification automatically.
@@ -54,7 +60,12 @@ mempalace mine ~/projects/myapp       # index your codebase
 claude mcp add mempalace -- python -m mempalace.mcp_server  # connect to Claude Code
 ```
 
-This makes the 27 tools available to your AI. For proactive search and storage (without you asking), you'll also need to add usage rules to your `CLAUDE.md` — see [`docs/AGENT_INSTALL.md`](docs/AGENT_INSTALL.md) Section 7.
+**Optional: auto-sync on commit** (requires `[watch]` extra — see [Auto-Watch](#auto-watch)):
+```bash
+mempalace watch ~/projects/           # re-mines on every commit, zero noise
+```
+
+This makes the 27 tools available to your AI. 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>
 
@@ -91,7 +102,7 @@ You write code. You make decisions. You debug things. Between sessions, all that
 mempalace-code **indexes it once** into a local vector store, then your AI finds it in milliseconds — using [595x fewer tokens](docs/BENCH_TOKEN_DELTA.md) than grep + read at measured peak (median 80x on a 19k-chunk project, and it keeps scaling). Think of it as `git log` for everything that *isn't* in the code: the *why*, the discussions, the dead ends, the decisions.
 
 **What gets indexed:**
-- Code files — functions, classes, modules (Python, TypeScript/JS, Go, Rust, C/C++, C#, F#, VB.NET, XAML, Java, Kotlin, Markdown)
+- Code files — functions, classes, modules (Python, TypeScript/JS, Go, Rust, C/C++, C#, F#, VB.NET, XAML, Java, Kotlin, Scala, Swift, Dart, PHP, Markdown) plus Kubernetes manifests
 - .NET solutions — `.sln`/`.csproj` project graphs, cross-project symbol relationships, interface implementations
 - Conversation exports — Claude, ChatGPT, Slack
 - Architecture notes, decisions, anything you store manually
@@ -114,10 +125,15 @@ mempalace-code **indexes it once** into a local vector store, then your AI finds
 | Rust | Functions, structs, enums, traits, impls | Tree-sitter |
 | Java | Classes, interfaces, methods, annotations | Regex |
 | Kotlin | Classes, objects, functions, extensions | Regex |
+| Scala | Classes, case classes, objects, traits, enums, functions, implicits, type aliases, generics | Regex |
+| Swift | Classes, structs, enums, protocols, functions, properties, extensions, actors, async/await | Regex |
+| Dart | Classes, mixins, extensions, enums, functions, named/factory constructors, async/await | Regex |
+| PHP | Classes, interfaces, traits, enums (8.1+), functions, methods, namespaces (Laravel/WP/Symfony aware) | Regex |
 | C# | Classes, interfaces, records, methods, properties | Regex |
 | F# / VB.NET | Modules, types, functions | Regex |
 | XAML | Controls, resources, code-behind linking | Regex |
 | C / C++ | Functions, structs, enums, classes | Regex |
+| Kubernetes manifests | Deployments, Services, ConfigMaps, Secrets, Ingresses, CRDs (indexed by kind/namespace/labels) | YAML-aware |
 | Markdown / plain text | Heading sections, paragraphs | — |
 | YAML / JSON / TOML | Adaptive line-count | — |
 
@@ -136,6 +152,16 @@ Mining is **incremental** by default — content-hash based, only changed files
 
 Keep your palace in sync automatically. By default, watches `.git/refs/heads/` and re-mines only on **commit** — no noise from work-in-progress saves. Handles multiple branches and worktrees.
 
+Requires the `watch` extra:
+```bash
+uv tool install "mempalace-code[watch]"   # or: pipx install "mempalace-code[watch]"
+```
+
+Already installed without it? Add watchfiles:
+```bash
+uv tool inject mempalace-code watchfiles  # or: pipx inject mempalace-code watchfiles
+```
+
 ```bash
 mempalace watch ~/projects/                      # watch all projects (on commit, default)
 mempalace watch ~/projects/ --on-save            # watch all file saves instead (noisier)
@@ -204,6 +230,7 @@ claude mcp add mempalace -- python -m mempalace.mcp_server
 | `mempalace_get_taxonomy` | Full wing → room → count tree |
 | `mempalace_search` | Semantic search with optional wing/room filters |
 | `mempalace_code_search` | Filter by language, symbol name/type, file glob |
+| `mempalace_file_context` | All indexed chunks for a source file, ordered by chunk_index |
 | `mempalace_check_duplicate` | Similarity check before filing (0.9 threshold) |
 
 </details>
@@ -216,6 +243,7 @@ claude mcp add mempalace -- python -m mempalace.mcp_server
 | `mempalace_add_drawer` | File verbatim content into a wing/room |
 | `mempalace_delete_drawer` | Remove a drawer by ID |
 | `mempalace_delete_wing` | Delete all drawers in a wing |
+| `mempalace_mine` | Trigger re-mining of a project directory (incremental or full) |
 
 </details>
 
@@ -259,7 +287,7 @@ claude mcp add mempalace -- python -m mempalace.mcp_server
 
 </details>
 
-The AI learns the memory protocol automatically from the `mempalace_status` response. No manual configuration.
+MCP tools are discoverable by any MCP-capable client automatically. To teach the AI *when* and *how* to use them, paste the usage rules from [`docs/LLM_USAGE_RULES.md`](docs/LLM_USAGE_RULES.md) into your agent's instructions (CLAUDE.md, AGENTS.md, `.cursorrules`, etc.) — otherwise the tools are available but the assistant will not know the protocol.
 
 ---
 
@@ -443,13 +471,13 @@ curl -fsSL https://raw.githubusercontent.com/rergards/mempalace-code/main/script
 **Optional extras:**
 
 ```bash
-pip install "mempalace-code[treesitter]"  # AST parsing (Python 3.10+; TS/JS on 3.9+)
+pip install "mempalace-code[treesitter]"  # AST parsing
 pip install "mempalace-code[chroma]"      # ChromaDB legacy backend (deprecated)
 pip install "mempalace-code[spellcheck]"  # autocorrect for room/wing names
 pip install "mempalace-code[dev]"         # pytest + ruff
 ```
 
-**Requirements:** Python 3.9+. ~80 MB embedding model downloaded once during `mempalace init`.
+**Requirements:** Python 3.11+. ~80 MB embedding model downloaded once during `mempalace init`.
 
 </details>
 
@@ -499,21 +527,15 @@ mempalace fetch-model                             # pre-download for offline use
 </details>
 
 <details>
-<summary><strong>Auto-Save Hooks</strong></summary>
+<summary><strong>Saving Conversation Context</strong></summary>
 
-Two Claude Code hooks for automatic memory saving:
+Code mining is automatic via `mempalace watch-all`. For conversation context (decisions, discussions, debugging notes), the AI uses MCP tools directly — works with **any agent** (Claude Code, Codex, Cursor, etc.):
 
-- **Stop Hook** — after each response, saves topics, decisions, and code changes
-- **PreCompact Hook** — emergency save before context compression
+1. Wire the MCP server (see [install docs](docs/AGENT_INSTALL.md))
+2. Add usage rules to your agent's instructions (CLAUDE.md, system prompt, etc.)
+3. The agent calls `mempalace_add_drawer` and `mempalace_diary_write` during sessions
 
-```json
-{
-  "hooks": {
-    "Stop": [{"matcher": "", "hooks": [{"type": "command", "command": "/path/to/mempalace/hooks/mempal_save_hook.sh"}]}],
-    "PreCompact": [{"matcher": "", "hooks": [{"type": "command", "command": "/path/to/mempalace/hooks/mempal_precompact_hook.sh"}]}]
-  }
-}
-```
+> **Legacy:** Claude Code also supports optional [auto-save hooks](hooks/README.md) that remind the AI to save at fixed intervals. These are redundant if MCP + usage rules are set up.
 
 </details>
 
@@ -533,7 +555,7 @@ mempalace/
 │   ├── palace_graph.py     ← room navigation graph
 │   └── layers.py           ← 4-layer memory stack
 ├── benchmarks/             ← reproducible benchmark runners
-├── hooks/                  ← Claude Code auto-save hooks
+├── hooks/                  ← Claude Code auto-save hooks (legacy, optional)
 ├── examples/               ← usage examples
 └── tests/                  ← 1008 tests
 ```