Merge pull request #1159 from MemPalace/develop

release: v3.3.3 — sync develop → main for tag cut

.claude-plugin/.mcp.json

@@ -1,9 +1,5 @@
 {
   "mempalace": {
-    "command": "python3",
-    "args": [
-      "-m",
-      "mempalace.mcp_server"
-    ]
+    "command": "mempalace-mcp"
   }
 }

.claude-plugin/hooks/mempal-precompact-hook.sh

@@ -1,5 +1,24 @@
 #!/bin/bash
 # MemPalace PreCompact Hook — thin wrapper calling Python CLI
 # All logic lives in mempalace.hooks_cli for cross-harness extensibility
-INPUT=$(cat)
-echo "$INPUT" | python3 -m mempalace hook run --hook precompact --harness claude-code
+run_mempalace_hook() {
+  if command -v mempalace >/dev/null 2>&1; then
+    mempalace hook run "$@"
+    return $?
+  fi
+
+  if command -v python3 >/dev/null 2>&1 && python3 -c "import mempalace" >/dev/null 2>&1; then
+    python3 -m mempalace hook run "$@"
+    return $?
+  fi
+
+  if command -v python >/dev/null 2>&1 && python -c "import mempalace" >/dev/null 2>&1; then
+    python -m mempalace hook run "$@"
+    return $?
+  fi
+
+  echo "MemPalace hook error: could not find a runnable mempalace command or module" >&2
+  return 1
+}
+
+run_mempalace_hook --hook precompact --harness claude-code

.claude-plugin/hooks/mempal-stop-hook.sh

@@ -1,5 +1,24 @@
 #!/bin/bash
 # MemPalace Stop Hook — thin wrapper calling Python CLI
 # All logic lives in mempalace.hooks_cli for cross-harness extensibility
-INPUT=$(cat)
-echo "$INPUT" | python3 -m mempalace hook run --hook stop --harness claude-code
+run_mempalace_hook() {
+  if command -v mempalace >/dev/null 2>&1; then
+    mempalace hook run "$@"
+    return $?
+  fi
+
+  if command -v python3 >/dev/null 2>&1 && python3 -c "import mempalace" >/dev/null 2>&1; then
+    python3 -m mempalace hook run "$@"
+    return $?
+  fi
+
+  if command -v python >/dev/null 2>&1 && python -c "import mempalace" >/dev/null 2>&1; then
+    python -m mempalace hook run "$@"
+    return $?
+  fi
+
+  echo "MemPalace hook error: could not find a runnable mempalace command or module" >&2
+  return 1
+}
+
+run_mempalace_hook --hook stop --harness claude-code

.claude-plugin/marketplace.json

@@ -2,14 +2,14 @@
   "name": "mempalace",
   "owner": {
     "name": "milla-jovovich",
-    "url": "https://github.com/milla-jovovich"
+    "url": "https://github.com/MemPalace"
   },
   "plugins": [
     {
       "name": "mempalace",
       "source": "./.claude-plugin",
       "description": "AI memory system — mine projects and conversations into a searchable palace. 19 MCP tools, auto-save hooks, guided setup.",
-      "version": "3.0.14",
+      "version": "3.3.3",
       "author": {
         "name": "milla-jovovich"
       }

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mempalace",
-  "version": "3.0.14",
+  "version": "3.3.3",
   "description": "Give your AI a memory — mine projects and conversations into a searchable palace. 19 MCP tools, auto-save hooks, and guided setup.",
   "author": {
     "name": "milla-jovovich"
@@ -9,11 +9,7 @@
   "commands": [],
   "mcpServers": {
     "mempalace": {
-      "command": "python3",
-      "args": [
-        "-m",
-        "mempalace.mcp_server"
-      ]
+      "command": "mempalace-mcp"
     }
   },
   "keywords": [

.codex-plugin/hooks/mempal-hook.sh

@@ -3,7 +3,7 @@ set -euo pipefail
 HOOK_NAME="${1:?Usage: mempal-hook.sh <hook-name>}"
 INPUT_FILE=$(mktemp) || { echo "Failed to create temp file" >&2; exit 1; }
 cat > "$INPUT_FILE"
-cat "$INPUT_FILE" | python3 -m mempalace hook run --hook "$HOOK_NAME" --harness codex
+cat "$INPUT_FILE" | mempalace hook run --hook "$HOOK_NAME" --harness codex
 EXIT_CODE=$?
 rm -f "$INPUT_FILE" 2>/dev/null
 exit $EXIT_CODE

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mempalace",
-  "version": "3.0.14",
+  "version": "3.3.3",
   "description": "Give your AI a memory — mine projects and conversations into a searchable palace. 19 MCP tools, auto-save hooks, and guided setup.",
   "author": {
     "name": "milla-jovovich"
@@ -21,11 +21,7 @@
   "hooks": "./hooks.json",
   "mcpServers": {
     "mempalace": {
-      "command": "python3",
-      "args": [
-        "-m",
-        "mempalace.mcp_server"
-      ]
+      "command": "mempalace-mcp"
     }
   },
   "interface": {

.devcontainer/devcontainer.json

@@ -0,0 +1,25 @@
+{
+  "name": "MemPalace",
+  "image": "mcr.microsoft.com/devcontainers/python:3.11",
+  "features": {
+    "ghcr.io/devcontainers/features/github-cli:1": {}
+  },
+  "postCreateCommand": "bash .devcontainer/post-create.sh",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "ms-python.debugpy",
+        "charliermarsh.ruff"
+      ],
+      "settings": {
+        "python.defaultInterpreterPath": "/usr/local/bin/python",
+        "python.testing.pytestEnabled": true,
+        "python.testing.pytestArgs": ["tests/", "-v", "--ignore=tests/benchmarks"],
+        "ruff.importStrategy": "fromEnvironment",
+        "editor.formatOnSave": true,
+        "editor.defaultFormatter": "charliermarsh.ruff"
+      }
+    }
+  }
+}

.devcontainer/post-create.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "=== MemPalace Dev Container Setup ==="
+
+pip install -e ".[dev]"
+
+# Match CI's ruff pin (pyproject only sets a floor; without this contributors
+# get a newer ruff locally than CI runs, causing phantom lint failures).
+pip install "ruff>=0.4.0,<0.5"
+
+pip install pre-commit
+pre-commit install
+
+echo ""
+echo "=== Verification ==="
+echo "python: $(python --version)"
+echo "pytest: $(python -m pytest --version 2>&1 | head -1)"
+echo "ruff:   $(python -m ruff --version 2>&1 | head -1)"
+echo ""
+echo "Ready. Run: pytest tests/ -v --ignore=tests/benchmarks"

.github/workflows/deploy-docs.yml

@@ -2,7 +2,7 @@ name: Deploy Docs
 
 on:
   push:
-    branches: [main, develop]
+    branches: [develop]
     paths:
       - ".github/workflows/deploy-docs.yml"
       - "website/**"
@@ -51,7 +51,7 @@ jobs:
           path: website/.vitepress/dist
 
   deploy:
-    if: github.ref_name == 'main' || github.ref_name == 'develop'
+    if: github.ref_name == 'develop'
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}

.github/workflows/version-guard.yml

@@ -0,0 +1,101 @@
+name: Version Guard
+
+on:
+  push:
+    tags: ['v*']
+  pull_request:
+    paths:
+      - 'pyproject.toml'
+      - 'mempalace/version.py'
+      - '.claude-plugin/marketplace.json'
+      - '.claude-plugin/plugin.json'
+      - '.codex-plugin/plugin.json'
+      - '.github/workflows/version-guard.yml'
+
+jobs:
+  check-versions:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Extract versions from all sources
+        id: versions
+        run: |
+          set -euo pipefail
+          py_version=$(grep -E '^__version__' mempalace/version.py | cut -d'"' -f2)
+          pyproject_version=$(grep -E '^version' pyproject.toml | head -1 | cut -d'"' -f2)
+          marketplace_version=$(jq -r '.plugins[0].version' .claude-plugin/marketplace.json)
+          plugin_version=$(jq -r '.version' .claude-plugin/plugin.json)
+          codex_version=$(jq -r '.version' .codex-plugin/plugin.json)
+
+          echo "py_version=$py_version" >> "$GITHUB_OUTPUT"
+          echo "pyproject_version=$pyproject_version" >> "$GITHUB_OUTPUT"
+          echo "marketplace_version=$marketplace_version" >> "$GITHUB_OUTPUT"
+          echo "plugin_version=$plugin_version" >> "$GITHUB_OUTPUT"
+          echo "codex_version=$codex_version" >> "$GITHUB_OUTPUT"
+
+          {
+            echo "## Detected versions"
+            echo ""
+            echo "| Source | Version |"
+            echo "| --- | --- |"
+            echo "| mempalace/version.py | \`$py_version\` |"
+            echo "| pyproject.toml | \`$pyproject_version\` |"
+            echo "| .claude-plugin/marketplace.json | \`$marketplace_version\` |"
+            echo "| .claude-plugin/plugin.json | \`$plugin_version\` |"
+            echo "| .codex-plugin/plugin.json | \`$codex_version\` |"
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Verify all sources agree
+        env:
+          PY: ${{ steps.versions.outputs.py_version }}
+          PYPROJECT: ${{ steps.versions.outputs.pyproject_version }}
+          MARKETPLACE: ${{ steps.versions.outputs.marketplace_version }}
+          PLUGIN: ${{ steps.versions.outputs.plugin_version }}
+          CODEX: ${{ steps.versions.outputs.codex_version }}
+        run: |
+          set -euo pipefail
+          fail=0
+          check() {
+            local name="$1" value="$2" expected="$3"
+            if [[ "$value" != "$expected" ]]; then
+              echo "::error file=$name::version mismatch — expected $expected, got $value"
+              fail=1
+            fi
+          }
+          # All five must agree with each other (use version.py as the reference, per CLAUDE.md)
+          check "pyproject.toml" "$PYPROJECT" "$PY"
+          check ".claude-plugin/marketplace.json" "$MARKETPLACE" "$PY"
+          check ".claude-plugin/plugin.json" "$PLUGIN" "$PY"
+          check ".codex-plugin/plugin.json" "$CODEX" "$PY"
+          exit $fail
+
+      - name: Verify tag matches manifest (tag pushes only)
+        if: startsWith(github.ref, 'refs/tags/v')
+        env:
+          PY: ${{ steps.versions.outputs.py_version }}
+        run: |
+          set -euo pipefail
+          tag_version="${GITHUB_REF_NAME#v}"
+
+          # Semver pre-release tags (v3.4.0-rc1, v1.0.0-beta.2, ...) are treated
+          # as internal/staging and are not validated against the manifest. They
+          # do not flow to end users via `/plugin update`, which reads the
+          # manifest on the default branch.
+          if [[ "$tag_version" == *-* ]]; then
+            echo "Pre-release tag $GITHUB_REF_NAME — skipping strict manifest match."
+            {
+              echo ""
+              echo "> Pre-release tag detected: \`$GITHUB_REF_NAME\`."
+              echo "> Manifest ($PY) is not required to match. Pre-releases are not published via \`/plugin update\`."
+            } >> "$GITHUB_STEP_SUMMARY"
+            exit 0
+          fi
+
+          if [[ "$tag_version" != "$PY" ]]; then
+            echo "::error::tag $GITHUB_REF_NAME does not match manifest version $PY"
+            echo "Bump mempalace/version.py, pyproject.toml, and all plugin manifests before tagging a stable release."
+            echo "For an internal/staging tag, use a semver pre-release suffix (e.g. v${PY}-rc1)."
+            exit 1
+          fi
+          echo "Tag $GITHUB_REF_NAME matches manifest version $PY"

.pre-commit-config.yaml

@@ -1,6 +1,9 @@
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.9.0
+    # Keep in lock-step with the ruff version pinned in .github/workflows/ci.yml
+    # (>=0.4.0,<0.5). Using a newer rev here produces a different formatter
+    # output than CI and breaks `ruff format --check` in the lint job.
+    rev: v0.4.10
     hooks:
       - id: ruff
         args: [--fix]

CHANGELOG.md

@@ -6,7 +6,144 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ---
 
-## [Unreleased] — v3.3.0 (on develop)
+## [3.3.3] — 2026-04-23
+
+### Bug Fixes
+
+- **Install regression** — `mempalace-mcp` console script is now declared in `pyproject.toml` alongside `.claude-plugin/plugin.json`'s reference to it. In v3.3.2 the two drifted apart (plugin.json shipped the new `"command": "mempalace-mcp"` form before the matching entry point landed), so every fresh `pip install mempalace==3.3.2` produced a Claude Code plugin config pointing at a binary that wasn't installed. (#1093, #340)
+- Restore silent-save visibility after the Claude Code 2.1.114 client regression — production transcript saves were failing silently until this PR. (#1021)
+- Paginate `status`-path metadata fetches so large palaces don't trip SQLite variable limits. (#851)
+- Resolve the Claude plugin hook runner across platform / plugin-dir variations; previously broke on Windows and some macOS layouts. (#942)
+- Real `python3` resolution for `.sh` hooks with a `MEMPAL_PYTHON` override path. (#833)
+- Add optional `wing` parameter to `tool_diary_write` / `tool_diary_read` and derive per-project wing from the Claude Code transcript path when writing from the stop hook — diary entries from different projects no longer collapse into a shared default wing. (#659)
+- Treat empty string as "no filter" in `mempalace_search` `wing`/`room`; LLM agents that default to filling every optional parameter with `""` no longer get bounced with `must be a non-empty string`. (#1097, #1084)
+- Broaden `_wing_from_transcript_path` to handle Claude Code project folders without a `-Projects-` segment (e.g. `~/dev/<parent>/<project>`, `~/code/<project>`). The project name is now derived from the final dash-separated token of the encoded folder, so Linux users with code outside `~/Projects/` get per-project diary scoping instead of falling through to `wing_sessions`. (#1145, follow-up to #659)
+- `mempalace_diary_read(wing="")` now returns diary entries from every wing this agent has written to, matching the #1097 "empty-string as no filter" pattern. Previously defaulted to `wing_<agent>`, siloing entries that hooks wrote to project-derived wings. (#1145)
+- `mempalace mine` now skips the generated `entities.json` file so its contents aren't re-ingested as project content. (#1175)
+
+### Improvements
+
+- **Deterministic hook saves.** Save hook now uses a silent Python API path, so successive hook invocations produce reproducible results and zero data loss on the hot path. (#673)
+- **Graph cache with write-invalidation** inside `build_graph()` — warm-path calls no longer rebuild the palace-graph per request. (#661)
+- **`mempalace init` entity detection overhaul.** Canonical project names now come from package manifests (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`) and real people come from git commit authors, rather than being inferred from prose. Includes union-find dedup across name/email aliases, bot filtering that keeps `@users.noreply.github.com` humans, and automatic "mine" flagging by contribution share. (#1148)
+- **Regex detector accuracy.** CamelCase extraction so `MemPalace`, `ChromaDB`, `OpenAI` aren't fragmented; tighter versioned/hyphenated pattern kills `context-manager` / `multi-word` false positives; dialogue `^NAME:\s` requires ≥2 hits so `Created: <date>` metadata stops classifying field names as people; expanded stopwords for common English participles and descriptors; high-pronoun signal classifies as person rather than dumping to uncertain. (#1148)
+- **Init → miner wire-up.** Confirmed entities merge into `~/.mempalace/known_entities.json` on init, which the miner reads to tag drawer metadata for entity-filtered search. Previously init's output was not consumed by the miner; the per-project `entities.json` is kept as an audit trail. (#1157)
+- **Case-insensitive project dedup** across manifest, git, and convo sources so casing variants of the same project name collapse into one review entry. (#1175)
+
+### Added
+
+- i18n: Belarusian translation. (#1051)
+- i18n: entity detection for German, Spanish, and French locales. (#1001)
+- i18n: Traditional + Simplified Chinese entity detection. (#945)
+- **`mempalace init --llm`**: optional LLM-assisted entity classification. Defaults to local Ollama (zero-API); also supports any OpenAI-compatible endpoint (LM Studio, llama.cpp server, vLLM, OpenRouter, etc.) and the Anthropic Messages API. Runs interactively with a progress indicator; Ctrl-C cancels cleanly and returns partial results. Useful for prose-heavy folders where the regex detector struggles (diaries, transcripts, research notes). Opt-in only — default init path remains zero-API. (#1150)
+- **Claude Code conversation scanner.** `~/.claude/projects/<slug>/` directories now contribute project entities using each session's authoritative `cwd` metadata, avoiding slug-decoding ambiguity. (#1150)
+
+### Known — deferred to v3.3.4
+
+- HNSW parallel-insert SIGSEGV when `hnsw:num_threads` is unset on collection creation (#974) — fix in-flight as #976, awaiting rebase against develop.
+
+---
+
+## [3.3.2] — 2026-04-19
+
+### Bug Fixes
+
+- Fix silent drop of `.jsonl` files in project miner; raise `MAX_FILE_SIZE` cap from 10 MB to 500 MB so large transcripts no longer fall through unnoticed. Adds a tandem **sweeper** — a message-level, timestamp-coordinated, idempotent safety net that catches anything the primary miner missed. (#998)
+- `mempalace sweep <target>` CLI to run the sweeper on demand against a transcript file or a directory. (#998)
+- Guard `Layer3.search_raw` against `None` doc/meta rows returned by ChromaDB — prevents `AttributeError` crashes on mixed-schema palaces. (#1011, #1013)
+- Guard searcher API path, closet loop, and miner status histogram against `None` metadata; matching guards added to `tool_status` / `list_wings` / `list_rooms` / `get_taxonomy` in the MCP server. (#999)
+- Upgrade `chromadb` floor to `>=1.5.4` for Python 3.13 / 3.14 compatibility and pin upper bound to `<2` so future breaking majors don't silently install. (#1010)
+- Fix Unicode checkmark rendering on Windows terminals that can't encode the `✓` glyph — avoids `UnicodeEncodeError` crashes on first-run output. (#681)
+- **`quarantine_stale_hnsw`** — on open, detect HNSW segment directories whose `data_level0.bin` is significantly older than `chroma.sqlite3` and rename them out of the way. Recovers cleanly from HNSW/sqlite drift that otherwise causes SIGSEGV on `count()` / `query(...)` (the chroma-core/chroma#2594 failure mode). Rebuilds the index lazily on next use. (#1000)
+- **PID file guard** — `mine` writes a per-source-directory PID file and refuses to start if an existing mine is still running, preventing process stacking that bloats HNSW and wedges concurrent writes. Includes cross-platform PID liveness check (`os.kill(pid, 0)` terminates on Windows, so the guard falls back to a platform-aware probe). (#1023)
+
+### Improvements
+
+- **RFC 001 §10 — typed backend contracts.** `BaseBackend` now returns typed `QueryResult` / `GetResult` dataclasses and `PalaceRef` for palace identity; registry-based backend discovery. Internal refactor; no user-facing API change. (#995)
+- **RFC 002 §9 — source adapter scaffolding.** Introduces `BaseSourceAdapter`, adapter registry, and `PalaceContext` — the plumbing that future pluggable ingest sources will target. Internal refactor; no user-facing API change yet. (#1014)
+
+### Documentation
+
+- **RFC 002** — full specification for the source adapter plugin system (future pluggable ingest). (#990)
+- First-run help text and `README` now reference the real `~/.claude/projects/<project>/` path shape instead of the placeholder `/path/to/transcripts`. (#996, #1012)
+
+### Internal
+
+- Harden sweeper for production: verbatim tool blocks, full `session_id`, logged failures.
+- Address Copilot review on #995: cursor tie-break, honest metrics, accurate comments.
+- Test hygiene: avoid ONNX network download in update-length validation tests; dedup update-length-validation tests; fix Windows file-lock in cache-invalidation test.
+
+---
+
+## [3.3.1] — 2026-04-16
+
+### New Features
+
+**Multi-language entity detection** — lexical patterns (person verbs, pronouns, dialogue markers, project verbs, stopwords, candidate character classes) now live in the optional `entity` section of each locale JSON under `mempalace/i18n/<lang>.json`. Every public function in `entity_detector` accepts a `languages=` tuple and unions patterns across enabled locales. Default stays `("en",)` so existing English-only callers are unchanged. (#911)
+
+- **Five new fully-supported locales** with CLI strings, AAAK compression instructions, and entity-detection patterns:
+  - Brazilian Portuguese `pt-br` (#156)
+  - Russian `ru` (#760)
+  - Italian `it` (#907)
+  - Hindi `hi` (#773)
+  - Indonesian `id` (#778)
+- **`MempalaceConfig.entity_languages`** — persistent palace-level language selection; `MEMPALACE_ENTITY_LANGUAGES` env override; `mempalace init --lang en,pt-br` flag that saves to `~/.mempalace/config.json` (#911)
+- **Per-language `candidate_pattern`** — non-Latin scripts register their own character class, so names like `João`, `Инна`, `राज` are no longer silently dropped by the ASCII-only default (#911)
+- **VSCode devcontainer** matching the CI environment (#881)
+- `MEMPAL_VERBOSE` env toggle — developers see diaries surfaced in chat while the default remains silent (#871)
+- `created_at` timestamps included in search results (#846)
+
+### Bug Fixes
+
+**i18n / Unicode**
+
+- Script-aware word boundaries for combining-mark scripts — Python's `\b` fails on Devanagari vowel signs (`ा ी ु`), Arabic, Hebrew, Thai, Tamil, Khmer etc., truncating names like `अनीता` → `अनीत` and making person-verb patterns never fire. Locales now declare an optional `boundary_chars` field and the i18n loader expands `\b` into a script-aware lookaround boundary (#932)
+- Case-insensitive BCP 47 language code resolution — `--lang PT-BR`, `zh-cn`, `Pt-Br` previously fell through to English silently; now resolve to the canonical locale file via lowercase matching, with the entity-pattern cache keyed on the canonical form so casing variations share one cache entry (#928)
+- Wire i18n candidate patterns into `miner._extract_entities_for_metadata()`, `palace.build_closet_lines()`, and `entity_registry.extract_unknown_candidates()` — three code paths that still hardcoded ASCII-only `[A-Z][a-z]{2,}` and silently missed Cyrillic, accented Latin, and non-Latin entity metadata tags (#931)
+- Explicit `encoding="utf-8"` on `Path.read_text()` calls across entity_registry, instructions_cli, split_mega_files, and onboarding tests — prevents Windows GBK (and other non-UTF-8) locales from corrupting UTF-8 files (#946, #776)
+- `ko.json` `status_drawers` used `{drawers}` instead of `{count}`, showing the raw template string instead of the number (#758)
+- Move `test_i18n.py` from inside the installed package into `tests/` so pytest actually collects it; remove the `sys.path.insert` hack (#758)
+- `Dialect.from_config()` defaulted to `current_lang()` (module-global) when config had no `lang` key — replaced with explicit `"en"` fallback for determinism (#758)
+
+**Other**
+
+- Guard `KnowledgeGraph.close()` and `query_relationship`/`timeline`/`stats` methods with the instance lock to prevent concurrent-access corruption (#887, #884)
+- Replace invalid `{"decision": "allow"}` with `{}` in hook responses — the string wasn't a valid decision value and triggered schema warnings (#885)
+- `entity_registry.research()` defaults to local-only — previously made outbound Wikipedia HTTPS requests without explicit user opt-in; callers now must pass `allow_network=True` (#811)
+- Precompact hook no longer blocks compaction when it fails or takes too long (#856, #858, #863)
+- Redirect stdout to stderr during MCP server import so library logging can't corrupt the JSON-RPC channel (#225, #864)
+- `mempalace init` auto-adds per-project files to `.gitignore` in git repositories so users don't accidentally commit `mempalace.yaml` / `entities.json` (#185, #866)
+- Searcher guards against empty ChromaDB query results that previously raised on edge-case corpora (#195, #865)
+- Return empty status instead of an error on a cold-start palace with no drawers yet (#830, #831)
+- Restrict file permissions on sensitive palace data (#814)
+- Slack transcript importer writes a provenance header and preserves speaker IDs (#815)
+- Allow `mempalace mine` to run in directories without a local `mempalace.yaml` and surface the missing-yaml warning on stderr (#604)
+- Security hook injection fix (#812)
+- Save hook auto-mines transcripts even when `MEMPAL_DIR` is unset (#840)
+- Pin the Pages custom domain via a shipped `CNAME` in the deploy artifact (#877)
+- Version drift safeguard — sync pyproject + `version.py` + README badge in one place (#876)
+- Deploy docs workflow now runs on `develop` only, preventing accidental main-branch deploys (#845)
+
+### Improvements
+
+- Regex compilation optimization for entity extraction — pre-compile per-entity pattern sets once and cache by `(name, languages)` tuple, so multi-language callers don't thrash the cache (#880)
+- Knowledge-graph value sanitization now preserves natural punctuation (commas, colons, parentheses) that commonly appears in KG subject/object values (#873)
+
+### Documentation
+
+- Clarify that `mempalace init` requires a `<dir>` argument in CLI help text (#210, #862)
+- Domain name and specific impostor sites called out in the scam-alert section (#869)
+- Tightened `SECURITY.md` with a real version-support policy and the GHPVR-only reporting channel (#810)
+- Fixed stale `pyproject.toml` URLs (#853)
+- v4 planning prep (#852)
+
+### Internal
+
+- `palace_graph` tunnel helper test coverage (#908)
+
+---
+
+## [3.3.0] — 2026-04-13
 
 ### New Features
 - Closet layer — a compact searchable index of pointers to verbatim drawers, enabling fast topical lookup without reading all content (#788)
@@ -41,6 +178,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - Add `docs/CLOSETS.md` — closet layer overview
 - Fix stale `milla-jovovich/*` org URLs in website and plugin manifests (#787)
 - Fix remaining stale org URLs in contributor docs (#808)
+- Rewrite `README.md` and `mempalaceofficial.com` benchmark pages to remove category-error cross-system comparisons (R@5 retrieval recall had been listed next to competitor QA accuracy under one column), remove the retracted "+34% palace boost" claim from the surfaces where it had remained, replace the `100%` Haiku-rerank headline with the honest held-out `98.4%` R@5, drop the LoCoMo `100%` top-50 row (retrieval-bypass artefact), and fix the broken `aya-thekeeper/mempal` reproduction URL (#875)
+- Add `docs/HISTORY.md` as the canonical home for corrections, retractions, and public notices; move the 2026-04-07 "Note from Milla & Ben" and the 2026-04-11 impostor-domain notice out of `README.md`
+- Add v3.3.0 reproduction result JSONLs and the deterministic `seed=42` 50/450 LongMemEval split under `benchmarks/` — every BENCHMARKS.md claim reproduces exactly
 
 ### Internal
 - Add test coverage for `mine_lock`, closets, entity metadata, BM25, and diary

CONTRIBUTING.md

@@ -82,7 +82,7 @@ If you're planning a significant change, open an issue first to discuss the appr
 - **Verbatim first**: Never summarize user content. Store exact words.
 - **Local first**: Everything runs on the user's machine. No cloud dependencies.
 - **Zero API by default**: Core features must work without any API key.
-- **Palace structure matters**: Wings, halls, and rooms aren't cosmetic — they drive a 34% retrieval improvement. Respect the hierarchy.
+- **Palace structure is scoping, not magic**: Wings, halls, and rooms act as metadata filters in the underlying vector store. They keep retrieval predictable when a palace holds many unrelated projects or people. Respect the hierarchy — but don't present it as a novel retrieval mechanism.
 
 ## Community
 

README.md

@@ -1,752 +1,187 @@
+> [!CAUTION]
+> **Scam alert.** The only official sources for MemPalace are this
+> [GitHub repository](https://github.com/MemPalace/mempalace), the
+> [PyPI package](https://pypi.org/project/mempalace/), and the docs site at
+> **[mempalaceofficial.com](https://mempalaceofficial.com)**. Any other
+> domain — including `mempalace.tech` — is an impostor and may distribute
+> malware. Details and timeline: [docs/HISTORY.md](docs/HISTORY.md).
+
 <div align="center">
 
-<img src="assets/mempalace_logo.png" alt="MemPalace" width="280">
+<img src="assets/mempalace_logo.png" alt="MemPalace" width="240">
 
 # MemPalace
 
-### The highest-scoring AI memory system ever benchmarked. And it's free.
-
-<br>
-
-Every conversation you have with an AI — every decision, every debugging session, every architecture debate — disappears when the session ends. Six months of work, gone. You start over every time.
-
-Other memory systems try to fix this by letting AI decide what's worth remembering. It extracts "user prefers Postgres" and throws away the conversation where you explained *why*. MemPalace takes a different approach: **store everything, then make it findable.**
-
-**The Palace** — Ancient Greek orators memorized entire speeches by placing ideas in rooms of an imaginary building. Walk through the building, find the idea. MemPalace applies the same principle to AI memory: your conversations are organized into wings (people and projects), halls (types of memory), and rooms (specific ideas). No AI decides what matters — you keep every word, and the structure gives you a navigable map instead of a flat search index.
-
-**Raw verbatim storage** — MemPalace stores your actual exchanges in ChromaDB without summarization or extraction. The 96.6% LongMemEval result comes from this raw mode. We don't burn an LLM to decide what's "worth remembering" — we keep everything and let semantic search find it.
-
-**AAAK (experimental)** — A lossy abbreviation dialect for packing repeated entities into fewer tokens at scale. Readable by any LLM that reads text — Claude, GPT, Gemini, Llama, Mistral — no decoder needed. **AAAK is a separate compression layer, not the storage default**, and on the LongMemEval benchmark it currently regresses vs raw mode (84.2% vs 96.6%). We're iterating. See the [note above](#a-note-from-milla--ben--april-7-2026) for the honest status.
-
-**Local, open, adaptable** — MemPalace runs entirely on your machine, on any data you have locally, without using any external API or services. It has been tested on conversations — but it can be adapted for different types of datastores. This is why we're open-sourcing it.
-
-<br>
+Local-first AI memory. Verbatim storage, pluggable backend, 96.6% R@5 raw on LongMemEval — zero API calls.
 
 [![][version-shield]][release-link]
 [![][python-shield]][python-link]
 [![][license-shield]][license-link]
 [![][discord-shield]][discord-link]
 
-<br>
-
-[Quick Start](#quick-start) · [The Palace](#the-palace) · [AAAK Dialect](#aaak-dialect-experimental) · [Benchmarks](#benchmarks) · [MCP Tools](#mcp-server)
-
-<br>
-
-### Highest LongMemEval score ever published — free or paid.
-
-<table>
-<tr>
-<td align="center"><strong>96.6%</strong><br><sub>LongMemEval R@5<br><b>raw mode</b>, zero API calls</sub></td>
-<td align="center"><strong>500/500</strong><br><sub>questions tested<br>independently reproduced</sub></td>
-<td align="center"><strong>$0</strong><br><sub>No subscription<br>No cloud. Local only.</sub></td>
-</tr>
-</table>
-
-<sub>Reproducible — runners in <a href="benchmarks/">benchmarks/</a>. <a href="benchmarks/BENCHMARKS.md">Full results</a>. The 96.6% is from <b>raw verbatim mode</b>, not AAAK or rooms mode (those score lower — see <a href="#a-note-from-milla--ben--april-7-2026">note above</a>).</sub>
-
 </div>
 
 ---
 
-## A Note from Milla & Ben — April 7, 2026
+## What it is
 
-> The community caught real problems in this README within hours of launch and we want to address them directly.
->
-> **What we got wrong:**
->
-> - **The AAAK token example was incorrect.** We used a rough heuristic (`len(text)//3`) for token counts instead of an actual tokenizer. Real counts via OpenAI's tokenizer: the English example is 66 tokens, the AAAK example is 73. AAAK does not save tokens at small scales — it's designed for *repeated entities at scale*, and the README example was a bad demonstration of that. We're rewriting it.
->
-> - **"30x lossless compression" was overstated.** AAAK is a lossy abbreviation system (entity codes, sentence truncation). Independent benchmarks show AAAK mode scores **84.2% R@5 vs raw mode's 96.6%** on LongMemEval — a 12.4 point regression. The honest framing is: AAAK is an experimental compression layer that trades fidelity for token density, and **the 96.6% headline number is from RAW mode, not AAAK**.
->
-> - **"+34% palace boost" was misleading.** That number compares unfiltered search to wing+room metadata filtering. Metadata filtering is a standard ChromaDB feature, not a novel retrieval mechanism. Real and useful, but not a moat.
->
-> - **"Contradiction detection"** exists as a separate utility (`fact_checker.py`) but is not currently wired into the knowledge graph operations as the README implied.
->
-> - **"100% with Haiku rerank"** is real (we have the result files) but the rerank pipeline is not in the public benchmark scripts. We're adding it.
->
-> **What's still true and reproducible:**
->
-> - **96.6% R@5 on LongMemEval in raw mode**, on 500 questions, zero API calls — independently reproduced on M2 Ultra in under 5 minutes by [@gizmax](https://github.com/milla-jovovich/mempalace/issues/39).
-> - Local, free, no subscription, no cloud, no data leaving your machine.
-> - The architecture (wings, rooms, closets, drawers) is real and useful, even if it's not a magical retrieval boost.
->
-> **What we're doing:**
->
-> 1. Rewriting the AAAK example with real tokenizer counts and a scenario where AAAK actually demonstrates compression
-> 2. Adding `mode raw / aaak / rooms` clearly to the benchmark documentation so the trade-offs are visible
-> 3. Wiring `fact_checker.py` into the KG ops so the contradiction detection claim becomes true
-> 4. Pinning ChromaDB to a tested range (Issue #100), fixing the shell injection in hooks (#110), and addressing the macOS ARM64 segfault (#74)
->
-> **Thank you to everyone who poked holes in this.** Brutal honest criticism is exactly what makes open source work, and it's what we asked for. Special thanks to [@panuhorsmalahti](https://github.com/milla-jovovich/mempalace/issues/43), [@lhl](https://github.com/milla-jovovich/mempalace/issues/27), [@gizmax](https://github.com/milla-jovovich/mempalace/issues/39), and everyone who filed an issue or a PR in the first 48 hours. We're listening, we're fixing, and we'd rather be right than impressive.
->
-> — *Milla Jovovich & Ben Sigman*
+MemPalace stores your conversation history as verbatim text and retrieves
+it with semantic search. It does not summarize, extract, or paraphrase.
+The index is structured — people and projects become *wings*, topics
+become *rooms*, and original content lives in *drawers* — so searches
+can be scoped rather than run against a flat corpus.
+
+The retrieval layer is pluggable. The current default is ChromaDB; the
+interface is defined in [`mempalace/backends/base.py`](mempalace/backends/base.py)
+and alternative backends can be dropped in without touching the rest of
+the system.
+
+Nothing leaves your machine unless you opt in.
+
+Architecture, concepts, and mining flows:
+[mempalaceofficial.com/concepts/the-palace](https://mempalaceofficial.com/concepts/the-palace.html).
 
 ---
 
-## An important follow up note regarding fake MemPalace websites - April 11, 2026
-
-Several Community Members (#267, #326, #506) have pointed out there are fake MemPalace websites popping up, including ones with Malware.
-
-To be super clear, MemPalace *has no website* (at least for now), so anything claiming to be one is false.
-
-Thanks to our Community Members for letting us know about the problem.
-
-Stay safe out there.
-
----
-
-## Quick Start
+## Install
 
 ```bash
 pip install mempalace
-
-# Set up your world — who you work with, what your projects are
 mempalace init ~/projects/myapp
+```
 
-# Mine your data
-mempalace mine ~/projects/myapp                    # projects — code, docs, notes
-mempalace mine ~/chats/ --mode convos              # convos — Claude, ChatGPT, Slack exports
-mempalace mine ~/chats/ --mode convos --extract general  # general — classifies into decisions, milestones, problems
+## Quickstart
 
-# Search anything you've ever discussed
+```bash
+# Mine content into the palace
+mempalace mine ~/projects/myapp                    # project files
+mempalace mine ~/.claude/projects/ --mode convos   # Claude Code sessions (scope with --wing per project)
+
+# Search
 mempalace search "why did we switch to GraphQL"
 
-# Your AI remembers
-mempalace status
+# Load context for a new session
+mempalace wake-up
 ```
 
-Three mining modes: **projects** (code and docs), **convos** (conversation exports), and **general** (auto-classifies into decisions, preferences, milestones, problems, and emotional context). Everything stays on your machine.
-
----
-
-## How You Actually Use It
-
-After the one-time setup (install → init → mine), you don't run MemPalace commands manually. Your AI uses it for you. There are two ways, depending on which AI you use.
-
-### With Claude Code (recommended)
-
-Native marketplace install:
-
-```bash
-claude plugin marketplace add milla-jovovich/mempalace
-claude plugin install --scope user mempalace
-```
-
-Restart Claude Code, then type `/skills` to verify "mempalace" appears.
-
-### With Claude, ChatGPT, Cursor, Gemini (MCP-compatible tools)
-
-```bash
-# Connect MemPalace once
-claude mcp add mempalace -- python -m mempalace.mcp_server
-```
-
-Now your AI has 29 tools available through MCP. Ask it anything:
-
-> *"What did we decide about auth last month?"*
-
-Claude calls `mempalace_search` automatically, gets verbatim results, and answers you. You never type `mempalace search` again. The AI handles it.
-
-MemPalace also works natively with **Gemini CLI** (which handles the server and save hooks automatically) — see the [Gemini CLI Integration Guide](examples/gemini_cli_setup.md).
-
-### With local models (Llama, Mistral, or any offline LLM)
-
-Local models generally don't speak MCP yet. Two approaches:
-
-**1. Wake-up command** — load your world into the model's context:
-
-```bash
-mempalace wake-up > context.txt
-# Paste context.txt into your local model's system prompt
-```
-
-This gives your local model ~600-900 tokens of critical facts (in AAAK if you prefer) before you ask a single question.
-
-**2. CLI search** — query on demand, feed results into your prompt:
-
-```bash
-mempalace search "auth decisions" > results.txt
-# Include results.txt in your prompt
-```
-
-Or use the Python API:
-
-```python
-from mempalace.searcher import search_memories
-results = search_memories("auth decisions", palace_path="~/.mempalace/palace")
-# Inject into your local model's context
-```
-
-Either way — your entire memory stack runs offline. ChromaDB on your machine, Llama on your machine, AAAK for compression, zero cloud calls.
-
----
-
-## The Problem
-
-Decisions happen in conversations now. Not in docs. Not in Jira. In conversations with Claude, ChatGPT, Copilot. The reasoning, the tradeoffs, the "we tried X and it failed because Y" — all trapped in chat windows that evaporate when the session ends.
-
-**Six months of daily AI use = 19.5 million tokens.** That's every decision, every debugging session, every architecture debate. Gone.
-
-| Approach | Tokens loaded | Annual cost |
-|----------|--------------|-------------|
-| Paste everything | 19.5M — doesn't fit any context window | Impossible |
-| LLM summaries | ~650K | ~$507/yr |
-| **MemPalace wake-up** | **~600-900 tokens** | **~$0.70/yr** |
-| **MemPalace + 5 searches** | **~13,500 tokens** | **~$10/yr** |
-
-MemPalace loads ~600-900 tokens of critical facts on wake-up — your team, your projects, your preferences. Then searches only when needed. $10/year to remember everything vs $507/year for summaries that lose context.
-
----
-
-## How It Works
-
-### The Palace
-
-The layout is fairly simple, though it took a long time to get there.
-
-It starts with a **wing**. Every project, person, or topic you're filing gets its own wing in the palace.
-
-Each wing has **rooms** connected to it, where information is divided into subjects that relate to that wing — so every room is a different element of what your project contains. Project ideas could be one room, employees could be another, financial statements another. There can be an endless number of rooms that split the wing into sections. The MemPalace install detects these for you automatically, and of course you can personalize it any way you feel is right.
-
-Every room has a **closet** connected to it, and here's where things get interesting. We've developed an AI language called **AAAK**. Don't ask — it's a whole story of its own. Your agent learns the AAAK shorthand every time it wakes up. Because AAAK is essentially English, but a very truncated version, your agent understands how to use it in seconds. It comes as part of the install, built into the MemPalace code. In our next update, we'll add AAAK directly to the closets, which will be a real game changer — the amount of info in the closets will be much bigger, but it will take up far less space and far less reading time for your agent.
-
-Inside those closets are **drawers**, and those drawers are where your original files live. In this first version, we haven't used AAAK as a closet tool, but even so, the summaries have shown **96.6% recall** in all the benchmarks we've done across multiple benchmarking platforms. Once the closets use AAAK, searches will be even faster while keeping every word exact. But even now, the closet approach has been a huge boon to how much info is stored in a small space — it's used to easily point your AI agent to the drawer where your original file lives. You never lose anything, and all this happens in seconds.
-
-There are also **halls**, which connect rooms within a wing, and **tunnels**, which connect rooms from different wings to one another. So finding things becomes truly effortless — we've given the AI a clean and organized way to know where to start searching, without having to look through every keyword in huge folders.
-
-You say what you're looking for and boom, it already knows which wing to go to. Just *that* in itself would have made a big difference. But this is beautiful, elegant, organic, and most importantly, efficient.
-
-```
-  +------------------------------------------------------------+
-  ¦  WING: Person                                              ¦
-  ¦                                                            ¦
-  ¦    +----------+            +----------+                    ¦
-  ¦    ¦  Room A  ¦  --hall--  ¦  Room B  ¦                    ¦
-  ¦    +----------+            +----------+                    ¦
-  ¦         ¦                                                  ¦
-  ¦         v                                                  ¦
-  ¦    +----------+      +----------+                          ¦
-  ¦    ¦  Closet  ¦ ---> ¦  Drawer  ¦                          ¦
-  ¦    +----------+      +----------+                          ¦
-  +---------+--------------------------------------------------+
-            ¦
-          tunnel
-            ¦
-  +---------+--------------------------------------------------+
-  ¦  WING: Project                                             ¦
-  ¦         ¦                                                  ¦
-  ¦    +----------+            +----------+                    ¦
-  ¦    ¦  Room A  ¦  --hall--  ¦  Room C  ¦                    ¦
-  ¦    +----------+            +----------+                    ¦
-  ¦         ¦                                                  ¦
-  ¦         v                                                  ¦
-  ¦    +----------+      +----------+                          ¦
-  ¦    ¦  Closet  ¦ ---> ¦  Drawer  ¦                          ¦
-  ¦    +----------+      +----------+                          ¦
-  +------------------------------------------------------------+
-```
-
-**Wings** — a person or project. As many as you need.
-**Rooms** — specific topics within a wing. Auth, billing, deploy — endless rooms.
-**Halls** — connections between related rooms *within* the same wing. If Room A (auth) and Room B (security) are related, a hall links them.
-**Tunnels** — connections *between* wings. When Person A and a Project both have a room about "auth," a tunnel cross-references them automatically.
-**Closets** — summaries that point to the original content. (In v3.0.0 these are plain-text summaries; AAAK-encoded closets are coming in a future update — see [Task #30](https://github.com/milla-jovovich/mempalace/issues/30).)
-**Drawers** — the original verbatim files. The exact words, never summarized.
-
-**Halls** are memory types — the same in every wing, acting as corridors:
-- `hall_facts` — decisions made, choices locked in
-- `hall_events` — sessions, milestones, debugging
-- `hall_discoveries` — breakthroughs, new insights
-- `hall_preferences` — habits, likes, opinions
-- `hall_advice` — recommendations and solutions
-
-**Rooms** are named ideas — `auth-migration`, `graphql-switch`, `ci-pipeline`. When the same room appears in different wings, it creates a **tunnel** — connecting the same topic across domains:
-
-```
-wing_kai       / hall_events / auth-migration  → "Kai debugged the OAuth token refresh"
-wing_driftwood / hall_facts  / auth-migration  → "team decided to migrate auth to Clerk"
-wing_priya     / hall_advice / auth-migration  → "Priya approved Clerk over Auth0"
-```
-
-Same room. Three wings. The tunnel connects them.
-
-### Why Structure Matters
-
-Tested on 22,000+ real conversation memories:
-
-```
-Search all closets:          60.9%  R@10
-Search within wing:          73.1%  (+12%)
-Search wing + hall:          84.8%  (+24%)
-Search wing + room:          94.8%  (+34%)
-```
-
-Wings and rooms aren't cosmetic. They're a **34% retrieval improvement**. The palace structure is the product.
-
-### The Memory Stack
-
-| Layer | What | Size | When |
-|-------|------|------|------|
-| **L0** | Identity — who is this AI? | ~50 tokens | Always loaded |
-| **L1** | Critical facts — team, projects, preferences | ~120 tokens (AAAK) | Always loaded |
-| **L2** | Room recall — recent sessions, current project | On demand | When topic comes up |
-| **L3** | Deep search — semantic query across all closets | On demand | When explicitly asked |
-
-Your AI wakes up with L0 + L1 (~600-900 tokens) and knows your world. Searches only fire when needed.
-
-### AAAK Dialect (experimental)
-
-AAAK is a lossy abbreviation system — entity codes, structural markers, and sentence truncation — designed to pack repeated entities and relationships into fewer tokens at scale. It is **readable by any LLM that reads text** (Claude, GPT, Gemini, Llama, Mistral) without a decoder, so a local model can use it without any cloud dependency.
-
-**Honest status (April 2026):**
-
-- **AAAK is lossy, not lossless.** It uses regex-based abbreviation, not reversible compression.
-- **It does not save tokens at small scales.** Short text already tokenizes efficiently. AAAK overhead (codes, separators) costs more than it saves on a few sentences.
-- **It can save tokens at scale** — in scenarios with many repeated entities (a team mentioned hundreds of times, the same project across thousands of sessions), the entity codes amortize.
-- **AAAK currently regresses LongMemEval** vs raw verbatim retrieval (84.2% R@5 vs 96.6%). The 96.6% headline number is from **raw mode**, not AAAK mode.
-- **The MemPalace storage default is raw verbatim text in ChromaDB** — that's where the benchmark wins come from. AAAK is a separate compression layer for context loading, not the storage format.
-
-We're iterating on the dialect spec, adding a real tokenizer for stats, and exploring better break points for when to use it. Track progress in [Issue #43](https://github.com/milla-jovovich/mempalace/issues/43) and [#27](https://github.com/milla-jovovich/mempalace/issues/27).
-
-### Contradiction Detection (experimental, not yet wired into KG)
-
-A separate utility (`fact_checker.py`) can check assertions against entity facts. It's not currently called automatically by the knowledge graph operations — this is being fixed (track in [Issue #27](https://github.com/milla-jovovich/mempalace/issues/27)). When enabled it catches things like:
-
-```
-Input:  "Soren finished the auth migration"
-Output: 🔴 AUTH-MIGRATION: attribution conflict — Maya was assigned, not Soren
-
-Input:  "Kai has been here 2 years"
-Output: 🟡 KAI: wrong_tenure — records show 3 years (started 2023-04)
-
-Input:  "The sprint ends Friday"
-Output: 🟡 SPRINT: stale_date — current sprint ends Thursday (updated 2 days ago)
-```
-
-Facts checked against the knowledge graph. Ages, dates, and tenures calculated dynamically — not hardcoded.
-
----
-
-## Real-World Examples
-
-### Solo developer across multiple projects
-
-```bash
-# Mine each project's conversations
-mempalace mine ~/chats/orion/  --mode convos --wing orion
-mempalace mine ~/chats/nova/   --mode convos --wing nova
-mempalace mine ~/chats/helios/ --mode convos --wing helios
-
-# Six months later: "why did I use Postgres here?"
-mempalace search "database decision" --wing orion
-# → "Chose Postgres over SQLite because Orion needs concurrent writes
-#    and the dataset will exceed 10GB. Decided 2025-11-03."
-
-# Cross-project search
-mempalace search "rate limiting approach"
-# → finds your approach in Orion AND Nova, shows the differences
-```
-
-### Team lead managing a product
-
-```bash
-# Mine Slack exports and AI conversations
-mempalace mine ~/exports/slack/ --mode convos --wing driftwood
-mempalace mine ~/.claude/projects/ --mode convos
-
-# "What did Soren work on last sprint?"
-mempalace search "Soren sprint" --wing driftwood
-# → 14 closets: OAuth refactor, dark mode, component library migration
-
-# "Who decided to use Clerk?"
-mempalace search "Clerk decision" --wing driftwood
-# → "Kai recommended Clerk over Auth0 — pricing + developer experience.
-#    Team agreed 2026-01-15. Maya handling the migration."
-```
-
-### Before mining: split mega-files
-
-Some transcript exports concatenate multiple sessions into one huge file:
-
-```bash
-mempalace split ~/chats/                      # split into per-session files
-mempalace split ~/chats/ --dry-run            # preview first
-mempalace split ~/chats/ --min-sessions 3     # only split files with 3+ sessions
-```
-
----
-
-## Knowledge Graph
-
-Temporal entity-relationship triples — like Zep's Graphiti, but SQLite instead of Neo4j. Local and free.
-
-```python
-from mempalace.knowledge_graph import KnowledgeGraph
-
-kg = KnowledgeGraph()
-kg.add_triple("Kai", "works_on", "Orion", valid_from="2025-06-01")
-kg.add_triple("Maya", "assigned_to", "auth-migration", valid_from="2026-01-15")
-kg.add_triple("Maya", "completed", "auth-migration", valid_from="2026-02-01")
-
-# What's Kai working on?
-kg.query_entity("Kai")
-# → [Kai → works_on → Orion (current), Kai → recommended → Clerk (2026-01)]
-
-# What was true in January?
-kg.query_entity("Maya", as_of="2026-01-20")
-# → [Maya → assigned_to → auth-migration (active)]
-
-# Timeline
-kg.timeline("Orion")
-# → chronological story of the project
-```
-
-Facts have validity windows. When something stops being true, invalidate it:
-
-```python
-kg.invalidate("Kai", "works_on", "Orion", ended="2026-03-01")
-```
-
-Now queries for Kai's current work won't return Orion. Historical queries still will.
-
-| Feature | MemPalace | Zep (Graphiti) |
-|---------|-----------|----------------|
-| Storage | SQLite (local) | Neo4j (cloud) |
-| Cost | Free | $25/mo+ |
-| Temporal validity | Yes | Yes |
-| Self-hosted | Always | Enterprise only |
-| Privacy | Everything local | SOC 2, HIPAA |
-
----
-
-## Specialist Agents
-
-Create agents that focus on specific areas. Each agent gets its own wing and diary in the palace — not in your CLAUDE.md. Add 50 agents, your config stays the same size.
-
-```
-~/.mempalace/agents/
-  ├── reviewer.json       # code quality, patterns, bugs
-  ├── architect.json      # design decisions, tradeoffs
-  └── ops.json            # deploys, incidents, infra
-```
-
-Your CLAUDE.md just needs one line:
-
-```
-You have MemPalace agents. Run mempalace_list_agents to see them.
-```
-
-The AI discovers its agents from the palace at runtime. Each agent:
-
-- **Has a focus** — what it pays attention to
-- **Keeps a diary** — written in AAAK, persists across sessions
-- **Builds expertise** — reads its own history to stay sharp in its domain
-
-```
-# Agent writes to its diary after a code review
-mempalace_diary_write("reviewer",
-    "PR#42|auth.bypass.found|missing.middleware.check|pattern:3rd.time.this.quarter|★★★★")
-
-# Agent reads back its history
-mempalace_diary_read("reviewer", last_n=10)
-# → last 10 findings, compressed in AAAK
-```
-
-Each agent is a specialist lens on your data. The reviewer remembers every bug pattern it's seen. The architect remembers every design decision. The ops agent remembers every incident. They don't share a scratchpad — they each maintain their own memory.
-
-Letta charges $20–200/mo for agent-managed memory. MemPalace does it with a wing.
-
----
-
-## MCP Server
-
-```bash
-# Via plugin (recommended)
-claude plugin marketplace add milla-jovovich/mempalace
-claude plugin install --scope user mempalace
-
-# Or manually
-claude mcp add mempalace -- python -m mempalace.mcp_server
-```
-
-### 29 Tools
-
-**Palace (read)**
-
-| Tool | What |
-|------|------|
-| `mempalace_status` | Palace overview + AAAK spec + memory protocol |
-| `mempalace_list_wings` | Wings with counts |
-| `mempalace_list_rooms` | Rooms within a wing |
-| `mempalace_get_taxonomy` | Full wing → room → count tree |
-| `mempalace_search` | Semantic search with wing/room filters |
-| `mempalace_check_duplicate` | Check before filing |
-| `mempalace_get_aaak_spec` | AAAK dialect reference |
-
-**Palace (write)**
-
-| Tool | What |
-|------|------|
-| `mempalace_add_drawer` | File verbatim content |
-| `mempalace_delete_drawer` | Remove by ID |
-
-**Knowledge Graph**
-
-| Tool | What |
-|------|------|
-| `mempalace_kg_query` | Entity relationships with time filtering |
-| `mempalace_kg_add` | Add facts |
-| `mempalace_kg_invalidate` | Mark facts as ended |
-| `mempalace_kg_timeline` | Chronological entity story |
-| `mempalace_kg_stats` | Graph overview |
-
-**Navigation**
-
-| Tool | What |
-|------|------|
-| `mempalace_traverse` | Walk the graph from a room across wings |
-| `mempalace_find_tunnels` | Find rooms bridging two wings |
-| `mempalace_graph_stats` | Graph connectivity overview |
-| `mempalace_create_tunnel` | Create explicit cross-wing link between two rooms |
-| `mempalace_list_tunnels` | List all explicit tunnels, filter by wing |
-| `mempalace_delete_tunnel` | Remove a tunnel by ID |
-| `mempalace_follow_tunnels` | Follow tunnels from a room to connected rooms in other wings |
-
-**Drawer Management**
-
-| Tool | What |
-|------|------|
-| `mempalace_get_drawer` | Fetch a single drawer by ID |
-| `mempalace_list_drawers` | Paginated drawer listing |
-| `mempalace_update_drawer` | Update drawer content or metadata |
-
-**Agent Diary**
-
-| Tool | What |
-|------|------|
-| `mempalace_diary_write` | Write AAAK diary entry |
-| `mempalace_diary_read` | Read recent diary entries |
-
-**System**
-
-| Tool | What |
-|------|------|
-| `mempalace_hook_settings` | Get/set hook behavior (silent save, toast) |
-| `mempalace_memories_filed_away` | Check if recent checkpoint was saved |
-| `mempalace_reconnect` | Force DB reconnect after external writes |
-
-The AI learns AAAK and the memory protocol automatically from the `mempalace_status` response. No manual configuration.
-
----
-
-## Auto-Save Hooks
-
-Two hooks for Claude Code that automatically save memories during work:
-
-**Save Hook** — every 15 messages, triggers a structured save. Topics, decisions, quotes, code changes. Also regenerates the critical facts layer.
-
-**PreCompact Hook** — fires before context compression. Emergency save before the window shrinks.
-
-```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"}]}]
-  }
-}
-```
-
-**Optional auto-ingest:** Set the `MEMPAL_DIR` environment variable to a directory path and the hooks will automatically run `mempalace mine` on that directory during each save trigger (background on stop, synchronous on precompact).
+For Claude Code, Gemini CLI, MCP-compatible tools, and local models, see
+[mempalaceofficial.com/guide/getting-started](https://mempalaceofficial.com/guide/getting-started.html).
 
 ---
 
 ## Benchmarks
 
-Tested on standard academic benchmarks — reproducible, published datasets.
+All numbers below are reproducible from this repository with the commands
+in [`benchmarks/BENCHMARKS.md`](benchmarks/BENCHMARKS.md). Full
+per-question result files are committed under `benchmarks/results_*`.
 
-| Benchmark | Mode | Score | API Calls |
-|-----------|------|-------|-----------|
-| **LongMemEval R@5** | Raw (ChromaDB only) | **96.6%** | Zero |
-| **LongMemEval R@5** | Hybrid + Haiku rerank | **100%** (500/500) | ~500 |
-| **LoCoMo R@10** | Raw, session level | **60.3%** | Zero |
-| **Personal palace R@10** | Heuristic bench | **85%** | Zero |
-| **Palace structure impact** | Wing+room filtering | **+34%** R@10 | Zero |
+**LongMemEval — retrieval recall (R@5, 500 questions):**
 
-The 96.6% raw score is the highest published LongMemEval result requiring no API key, no cloud, and no LLM at any stage.
+| Mode | R@5 | LLM required |
+|---|---|---|
+| Raw (semantic search, no heuristics, no LLM) | **96.6%** | None |
+| Hybrid v4, held-out 450q (tuned on 50 dev, not seen during training) | **98.4%** | None |
+| Hybrid v4 + LLM rerank (full 500) | ≥99% | Any capable model |
 
-### vs Published Systems
+The raw 96.6% requires no API key, no cloud, and no LLM at any stage. The
+hybrid pipeline adds keyword boosting, temporal-proximity boosting, and
+preference-pattern extraction; the held-out 98.4% is the honest
+generalisable figure.
 
-| System | LongMemEval R@5 | API Required | Cost |
-|--------|----------------|--------------|------|
-| **MemPalace (hybrid)** | **100%** | Optional | Free |
-| Supermemory ASMR | ~99% | Yes | — |
-| **MemPalace (raw)** | **96.6%** | **None** | **Free** |
-| Mastra | 94.87% | Yes (GPT) | API costs |
-| Mem0 | ~85% | Yes | $19–249/mo |
-| Zep | ~85% | Yes | $25/mo+ |
+The rerank pipeline promotes the best candidate out of the top-20
+retrieved sessions using an LLM reader. It works with any reasonably
+capable model — we have reproduced it with Claude Haiku, Claude Sonnet,
+and minimax-m2.7 via Ollama Cloud (no Anthropic dependency). The gap
+between raw and reranked is model-agnostic; we do not headline a "100%"
+number because the last 0.6% was reached by inspecting specific wrong
+answers, which `benchmarks/BENCHMARKS.md` flags as teaching to the test.
 
----
+**Other benchmarks (full results in [`benchmarks/BENCHMARKS.md`](benchmarks/BENCHMARKS.md)):**
 
-## All Commands
+| Benchmark | Metric | Score | Notes |
+|---|---|---|---|
+| LoCoMo (session, top-10, no rerank) | R@10 | 60.3% | 1,986 questions |
+| LoCoMo (hybrid v5, top-10, no rerank) | R@10 | 88.9% | Same set |
+| ConvoMem (all categories, 250 items) | Avg recall | 92.9% | 50 per category |
+| MemBench (ACL 2025, 8,500 items) | R@5 | 80.3% | All categories |
+
+We deliberately do not include a side-by-side comparison against Mem0,
+Mastra, Hindsight, Supermemory, or Zep. Those projects publish different
+metrics on different splits, and placing retrieval recall next to
+end-to-end QA accuracy is not an honest comparison. See each project's
+own research page for their published numbers.
+
+**Reproducing every result:**
 
 ```bash
-# Setup
-mempalace init <dir>                              # guided onboarding + AAAK bootstrap
-
-# Mining
-mempalace mine <dir>                              # mine project files
-mempalace mine <dir> --mode convos                # mine conversation exports
-mempalace mine <dir> --mode convos --wing myapp   # tag with a wing name
-
-# Splitting
-mempalace split <dir>                             # split concatenated transcripts
-mempalace split <dir> --dry-run                   # preview
-
-# Search
-mempalace search "query"                          # search everything
-mempalace search "query" --wing myapp             # within a wing
-mempalace search "query" --room auth-migration    # within a room
-
-# Memory stack
-mempalace wake-up                                 # load L0 + L1 context
-mempalace wake-up --wing driftwood                # project-specific
-
-# Compression
-mempalace compress --wing myapp                   # AAAK compress
-
-# Status
-mempalace status                                  # palace overview
-
-# MCP
-mempalace mcp                                     # show MCP setup command
+git clone https://github.com/MemPalace/mempalace.git
+cd mempalace
+pip install -e ".[dev]"
+# see benchmarks/README.md for dataset download commands
+python benchmarks/longmemeval_bench.py /path/to/longmemeval_s_cleaned.json
 ```
 
-All commands accept `--palace <path>` to override the default location.
-
 ---
 
-## Configuration
+## Knowledge graph
 
-### Global (`~/.mempalace/config.json`)
+MemPalace includes a temporal entity-relationship graph with validity
+windows — add, query, invalidate, timeline — backed by local SQLite.
+Usage and tool reference:
+[mempalaceofficial.com/concepts/knowledge-graph](https://mempalaceofficial.com/concepts/knowledge-graph.html).
 
-```json
-{
-  "palace_path": "/custom/path/to/palace",
-  "collection_name": "mempalace_drawers",
-  "people_map": {"Kai": "KAI", "Priya": "PRI"}
-}
-```
+## MCP server
 
-### Wing config (`~/.mempalace/wing_config.json`)
+29 MCP tools cover palace reads/writes, knowledge-graph operations,
+cross-wing navigation, drawer management, and agent diaries. Installation
+and the full tool list:
+[mempalaceofficial.com/reference/mcp-tools](https://mempalaceofficial.com/reference/mcp-tools.html).
 
-Generated by `mempalace init`. Maps your people and projects to wings:
+## Agents
 
-```json
-{
-  "default_wing": "wing_general",
-  "wings": {
-    "wing_kai": {"type": "person", "keywords": ["kai", "kai's"]},
-    "wing_driftwood": {"type": "project", "keywords": ["driftwood", "analytics", "saas"]}
-  }
-}
-```
+Each specialist agent gets its own wing and diary in the palace.
+Discoverable at runtime via `mempalace_list_agents` — no bloat in your
+system prompt:
+[mempalaceofficial.com/concepts/agents](https://mempalaceofficial.com/concepts/agents.html).
 
-### Identity (`~/.mempalace/identity.txt`)
+## Auto-save hooks
 
-Plain text. Becomes Layer 0 — loaded every session.
-
----
-
-## File Reference
-
-| File | What |
-|------|------|
-| `cli.py` | CLI entry point |
-| `config.py` | Configuration loading and defaults |
-| `normalize.py` | Converts 5 chat formats to standard transcript |
-| `mcp_server.py` | MCP server — 29 tools, AAAK auto-teach, memory protocol |
-| `miner.py` | Project file ingest |
-| `convo_miner.py` | Conversation ingest — chunks by exchange pair |
-| `searcher.py` | Semantic search via ChromaDB |
-| `layers.py` | 4-layer memory stack |
-| `dialect.py` | AAAK index format for closet pointers |
-| `knowledge_graph.py` | Temporal entity-relationship graph (SQLite) |
-| `palace_graph.py` | Room-based navigation graph |
-| `onboarding.py` | Guided setup — generates AAAK bootstrap + wing config |
-| `entity_registry.py` | Entity code registry |
-| `entity_detector.py` | Auto-detect people and projects from content |
-| `split_mega_files.py` | Split concatenated transcripts into per-session files |
-| `hooks/mempal_save_hook.sh` | Auto-save every N messages |
-| `hooks/mempal_precompact_hook.sh` | Emergency save before compaction |
-
----
-
-## Project Structure
-
-```
-mempalace/
-├── README.md                  ← you are here
-├── mempalace/                 ← core package (README)
-│   ├── cli.py                 ← CLI entry point
-│   ├── mcp_server.py          ← MCP server (29 tools)
-│   ├── knowledge_graph.py     ← temporal entity graph
-│   ├── palace_graph.py        ← room navigation graph
-│   ├── dialect.py             ← AAAK compression
-│   ├── miner.py               ← project file ingest
-│   ├── convo_miner.py         ← conversation ingest
-│   ├── searcher.py            ← semantic search
-│   ├── onboarding.py          ← guided setup
-│   └── ...                    ← see mempalace/README.md
-├── benchmarks/                ← reproducible benchmark runners
-│   ├── README.md              ← reproduction guide
-│   ├── BENCHMARKS.md          ← full results + methodology
-│   ├── longmemeval_bench.py   ← LongMemEval runner
-│   ├── locomo_bench.py        ← LoCoMo runner
-│   └── membench_bench.py      ← MemBench runner
-├── hooks/                     ← Claude Code auto-save hooks
-│   ├── README.md              ← hook setup guide
-│   ├── mempal_save_hook.sh    ← save every N messages
-│   └── mempal_precompact_hook.sh ← emergency save
-├── examples/                  ← usage examples
-│   ├── basic_mining.py
-│   ├── convo_import.py
-│   └── mcp_setup.md
-├── tests/                     ← test suite (README)
-├── assets/                    ← logo + brand assets
-└── pyproject.toml             ← package config (v3.3.0)
-```
+Two Claude Code hooks save periodically and before context compression:
+[mempalaceofficial.com/guide/hooks](https://mempalaceofficial.com/guide/hooks.html).
 
 ---
 
 ## Requirements
 
 - Python 3.9+
-- `chromadb>=0.4.0`
-- `pyyaml>=6.0`
+- A vector-store backend (ChromaDB by default)
+- ~300 MB disk for the default embedding model
 
-No API key. No internet after install. Everything local.
+No API key is required for the core benchmark path.
 
-```bash
-pip install mempalace
-```
+## Docs
 
----
+- Getting started → [mempalaceofficial.com/guide/getting-started](https://mempalaceofficial.com/guide/getting-started.html)
+- CLI reference → [mempalaceofficial.com/reference/cli](https://mempalaceofficial.com/reference/cli.html)
+- Python API → [mempalaceofficial.com/reference/python-api](https://mempalaceofficial.com/reference/python-api.html)
+- Full benchmark methodology → [benchmarks/BENCHMARKS.md](benchmarks/BENCHMARKS.md)
+- Release notes → [CHANGELOG.md](CHANGELOG.md)
+- Corrections and public notices → [docs/HISTORY.md](docs/HISTORY.md)
 
 ## Contributing
 
-PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and guidelines.
+PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 
 MIT — see [LICENSE](LICENSE).
 
 <!-- Link Definitions -->
-[version-shield]: https://img.shields.io/badge/version-3.3.0-4dc9f6?style=flat-square&labelColor=0a0e14
-[release-link]: https://github.com/milla-jovovich/mempalace/releases
+[version-shield]: https://img.shields.io/badge/version-3.3.3-4dc9f6?style=flat-square&labelColor=0a0e14
+[release-link]: https://github.com/MemPalace/mempalace/releases
 [python-shield]: https://img.shields.io/badge/python-3.9+-7dd8f8?style=flat-square&labelColor=0a0e14&logo=python&logoColor=7dd8f8
 [python-link]: https://www.python.org/
 [license-shield]: https://img.shields.io/badge/license-MIT-b0e8ff?style=flat-square&labelColor=0a0e14
-[license-link]: https://github.com/milla-jovovich/mempalace/blob/main/LICENSE
+[license-link]: https://github.com/MemPalace/mempalace/blob/main/LICENSE
 [discord-shield]: https://img.shields.io/badge/discord-join-5865F2?style=flat-square&labelColor=0a0e14&logo=discord&logoColor=5865F2
 [discord-link]: https://discord.com/invite/ycTQQCu6kn

SECURITY.md

@@ -0,0 +1,33 @@
+# Security Policy
+
+## Supported Versions
+
+MemPalace follows semantic versioning. Security fixes land on the current major version line.
+
+| Version            | Supported |
+| ------------------ | --------- |
+| 3.x (current)      | Yes       |
+| 2.x and earlier    | No        |
+
+## Reporting a Vulnerability
+
+**Please do not report security vulnerabilities through public GitHub issues.**
+
+We take the security of MemPalace seriously. If you believe you have found a security vulnerability, please report it privately using **GitHub Private Vulnerability Reporting**:
+
+1. Open the [Security tab](https://github.com/MemPalace/mempalace/security) of this repository.
+2. Click **Advisories** → **Report a vulnerability**.
+3. Fill in the form with the details below.
+
+### What to include in your report
+
+- A descriptive summary of the vulnerability.
+- Detailed steps to reproduce the issue (including any proof-of-concept scripts or specific file paths).
+- The affected version(s) and platform(s).
+- The potential impact and severity.
+
+### What to expect
+
+- We aim to acknowledge receipt within 48 hours.
+- We will triage the issue and keep you updated on progress toward a patch.
+- Once the vulnerability is resolved and an update is released, we will publish a security advisory and credit you for the discovery (if you wish to be credited).

benchmarks/BENCHMARKS.md

@@ -41,23 +41,57 @@ Both are real. Both are reproducible. Neither is the whole picture alone.
 
 ## Comparison vs Published Systems (LongMemEval)
 
-| # | System | R@5 | LLM Required | Which LLM | Notes |
+> **Important caveat — read before quoting this table.**
+> MemPal's `R@5` in this table is **retrieval recall**: is the labelled
+> session for this question inside the top-5 retrieved candidates?
+>
+> Several of the other systems below publish **end-to-end QA accuracy** —
+> a different metric that scores whether the system's generated answer
+> is correct. Retrieval recall and QA accuracy are not comparable; a
+> system can have 100% retrieval recall and 40% QA accuracy, and vice
+> versa.
+>
+> - **Mastra's 94.87%** is binary QA accuracy with GPT-5-mini, per
+>   [mastra.ai/research/observational-memory](https://mastra.ai/research/observational-memory).
+> - **Supermemory ASMR's ~99%** is QA accuracy with an 8-/12-agent
+>   ensemble, and the authors explicitly frame it as an experimental
+>   proof-of-concept, not production, per
+>   [their ASMR post](https://supermemory.ai/blog/we-broke-the-frontier-in-agent-memory-introducing-99-sota-memory-system/).
+> - **Mem0** does not publish a LongMemEval number; their published
+>   metric is LoCoMo QA accuracy (~66.9%), per
+>   [mem0.ai/research](https://mem0.ai/research).
+>
+> The table is kept here as a historical record of how the comparison
+> was originally framed. Public-facing pages (`README.md`,
+> `mempalaceofficial.com`) no longer present this table, per issue
+> [#875](https://github.com/MemPalace/mempalace/issues/875). For a fair
+> head-to-head, run the same metric on the same split.
+
+| # | System | R@5 (retrieval recall, unless noted) | LLM Required | Which LLM | Notes |
 |---|---|---|---|---|---|
-| 1 | **MemPal (hybrid v4 + rerank)** | **100%** | Optional | Haiku | Reproducible, 500/500 |
-| 2 | Supermemory ASMR | ~99% | Yes | Undisclosed | Research only, not in production |
+| 1 | **MemPal (hybrid v4 + Haiku rerank)** | **100%** | Optional | Haiku | 500/500 — but the 99.4%→100% step tuned on 3 specific wrong answers (see "Benchmark Integrity" below). Held-out 450q is 98.4%. |
+| 2 | Supermemory ASMR | ~99% *(QA accuracy, not R@5)* | Yes | Ensemble of Gemini 2.0 Flash / GPT-4o-mini | Experimental, not production, per authors |
 | 3 | MemPal (hybrid v3 + rerank) | 99.4% | Optional | Haiku | Reproducible |
 | 3 | MemPal (palace + rerank) | 99.4% | Optional | Haiku | Independent architecture |
-| 4 | Mastra | 94.87% | Yes | GPT-5-mini | — |
-| 5 | **MemPal (raw, no LLM)** | **96.6%** | **None** | **None** | **Highest zero-API score published** |
-| 6 | Hindsight | 91.4% | Yes | Gemini-3 | — |
-| 7 | Supermemory (production) | ~85% | Yes | Undisclosed | — |
-| 8 | Stella (dense retriever) | ~85% | None | None | Academic baseline |
-| 9 | Contriever | ~78% | None | None | Academic baseline |
+| 4 | Mastra | 94.87% *(QA accuracy, not R@5)* | Yes | GPT-5-mini | Different metric — not directly comparable to R@5 |
+| 5 | **MemPal (raw, no LLM)** | **96.6%** | **None** | **None** | **Reproducible, 500/500** |
+| 6 | MemPal hybrid v4 held-out 450 | 98.4% | None | None | Honest generalisable hybrid-pipeline figure |
+| 7 | Hindsight | 91.4% *(per their release, metric unverified)* | Yes | Gemini-3 | Check their published methodology |
+| 8 | Stella (dense retriever) | ~85% | None | None | Academic retrieval baseline |
+| 9 | Contriever | ~78% | None | None | Academic retrieval baseline |
 | 10 | BM25 (sparse) | ~70% | None | None | Keyword baseline |
 
-**MemPal raw (96.6%) is the highest published LongMemEval score that requires no API key, no cloud, and no LLM at any stage.**
+The MemPal raw 96.6% is the headline we ship on public surfaces: it's
+retrieval recall, it requires no API key, and it reproduces.
 
-**MemPal hybrid v4 + Haiku rerank (100%) is the first perfect score on LongMemEval — 500/500 questions, all 6 question types at 100%.**
+The MemPal hybrid v4 + Haiku rerank 100% remains an internal
+result — reproducible with `--mode hybrid_v4 --llm-rerank` — but we
+don't quote it on public pages because the final 0.6% was reached by
+inspecting three specific wrong answers (see "Benchmark Integrity"
+below), which is teaching to the test. The honest generalisable figure
+when an LLM is in the loop is the held-out 98.4% R@5 on 450 unseen
+questions, or the model-agnostic 99.2% R@5 / 100% R@10 we reproduced
+with minimax-m2.7 on the full 500.
 
 ---
 
@@ -308,9 +342,9 @@ The palace classifies each question into one of 5 halls. Pass 1 searches only wi
 ### Setup
 
 ```bash
-git clone -b ben/benchmarking https://github.com/aya-thekeeper/mempal.git
-cd mempal
-pip install chromadb pyyaml
+git clone https://github.com/MemPalace/mempalace.git
+cd mempalace
+pip install -e ".[dev]"
 mkdir -p /tmp/longmemeval-data
 curl -fsSL -o /tmp/longmemeval-data/longmemeval_s_cleaned.json \
   https://huggingface.co/datasets/xiaowu0162/longmemeval-cleaned/resolve/main/longmemeval_s_cleaned.json

benchmarks/HYBRID_MODE.md

@@ -196,9 +196,9 @@ python benchmarks/longmemeval_bench.py data/longmemeval_s_cleaned.json --mode hy
 
 ```bash
 # Setup
-git clone -b ben/benchmarking https://github.com/aya-thekeeper/mempal.git
-cd mempal
-pip install chromadb
+git clone https://github.com/MemPalace/mempalace.git
+cd mempalace
+pip install -e ".[dev]"
 
 # Download data
 mkdir -p /tmp/longmemeval-data

benchmarks/README.md

@@ -1,13 +1,13 @@
-# MemPal Benchmarks — Reproduction Guide
+# MemPalace Benchmarks — Reproduction Guide
 
 Run the exact same benchmarks we report. Clone, install, run.
 
 ## Setup
 
 ```bash
-git clone -b ben/benchmarking https://github.com/aya-thekeeper/mempal.git
-cd mempal
-pip install chromadb pyyaml
+git clone https://github.com/MemPalace/mempalace.git
+cd mempalace
+pip install -e ".[dev]"
 ```
 
 ## Benchmark 1: LongMemEval (500 questions)

benchmarks/lme_split_50_450.json

@@ -0,0 +1,508 @@
+{
+  "dev": [
+    "cc06de0d",
+    "f9e8c073",
+    "b320f3f8",
+    "a89d7624",
+    "311778f1",
+    "gpt4_59c863d7",
+    "bbf86515",
+    "099778bb",
+    "e831120c",
+    "dcfa8644",
+    "8fb83627",
+    "e66b632c",
+    "gpt4_7fce9456",
+    "55241a1f",
+    "352ab8bd",
+    "f4f1d8a4",
+    "830ce83f",
+    "2311e44b",
+    "09ba9854",
+    "gpt4_a1b77f9c",
+    "07741c45",
+    "gpt4_70e84552",
+    "b46e15ee",
+    "6071bd76",
+    "6f9b354f",
+    "1d4da289",
+    "gpt4_8279ba02",
+    "6456829e_abs",
+    "0db4c65d",
+    "d6062bb9",
+    "60bf93ed_abs",
+    "d3ab962e",
+    "87f22b4a",
+    "e01b8e2f",
+    "gpt4_7ddcf75f",
+    "8ebdbe50",
+    "26bdc477",
+    "29f2956b_abs",
+    "2311e44b_abs",
+    "75f70248",
+    "852ce960",
+    "f0e564bc",
+    "fca70973",
+    "3c1045c8",
+    "18bc8abd",
+    "afdc33df",
+    "54026fce",
+    "b9cfe692",
+    "6456829e",
+    "e6041065"
+  ],
+  "held_out": [
+    "gpt4_15e38248",
+    "gpt4_2ba83207",
+    "2133c1b5_abs",
+    "gpt4_8279ba03",
+    "76d63226",
+    "1192316e",
+    "gpt4_fa19884d",
+    "gpt4_372c3eed_abs",
+    "1a8a66a6",
+    "gpt4_fe651585",
+    "e25c3b8d",
+    "945e3d21",
+    "86b68151",
+    "1c0ddc50",
+    "1e043500",
+    "d682f1a2",
+    "gpt4_b5700ca0",
+    "91b15a6e",
+    "ce6d2d27",
+    "f523d9fe",
+    "7024f17c",
+    "8752c811",
+    "gpt4_f420262d",
+    "d01c6aa8",
+    "4b24c848",
+    "7e974930",
+    "3fdac837",
+    "gpt4_b4a80587",
+    "c18a7dc8",
+    "80ec1f4f_abs",
+    "7527f7e2",
+    "6ade9755",
+    "89941a94",
+    "gpt4_1d80365e",
+    "2133c1b5",
+    "06db6396",
+    "gpt4_88806d6e",
+    "88432d0a",
+    "3ba21379",
+    "0862e8bf",
+    "aae3761f",
+    "5025383b",
+    "gpt4_e061b84f",
+    "73d42213",
+    "4bc144e2",
+    "gpt4_5501fe77",
+    "00ca467f",
+    "dfde3500",
+    "01493427",
+    "b6025781",
+    "a96c20ee_abs",
+    "982b5123_abs",
+    "gpt4_fa19884c",
+    "gpt4_1a1dc16d",
+    "28dc39ac",
+    "gpt4_2d58bcd6",
+    "51c32626",
+    "c4ea545c",
+    "1da05512",
+    "gpt4_385a5000",
+    "577d4d32",
+    "72e3ee87",
+    "f4f1d8a4_abs",
+    "9d25d4e0",
+    "b29f3365",
+    "b759caee",
+    "10e09553",
+    "1d4e3b97",
+    "d52b4f67",
+    "gpt4_e072b769",
+    "58ef2f1c",
+    "6e984301",
+    "41275add",
+    "gpt4_59149c77",
+    "2ebe6c90",
+    "1cea1afa",
+    "gpt4_1e4a8aec",
+    "6c49646a",
+    "8a2466db",
+    "gpt4_65aabe59",
+    "gpt4_93159ced",
+    "51a45a95",
+    "af8d2e46",
+    "561fabcd",
+    "370a8ff4",
+    "gpt4_d84a3211",
+    "gpt4_7a0daae1",
+    "2a1811e2",
+    "gpt4_78cf46a3",
+    "1568498a",
+    "6b7dfb22",
+    "6ae235be",
+    "bc8a6e93_abs",
+    "681a1674",
+    "06878be2",
+    "1a1907b4",
+    "0e4e4c46",
+    "gpt4_85da3956",
+    "gpt4_f420262c",
+    "2bf43736",
+    "bc149d6b",
+    "09d032c9",
+    "5c40ec5b",
+    "eac54adc",
+    "993da5e2",
+    "71a3fd6b",
+    "gpt4_0b2f1d21",
+    "ad7109d1",
+    "4c36ccef",
+    "c8c3f81d",
+    "edced276_abs",
+    "0bc8ad92",
+    "gpt4_468eb064",
+    "2ebe6c92",
+    "cc6d1ec1",
+    "4dfccbf8",
+    "95228167",
+    "ba358f49",
+    "45dc21b6",
+    "db467c8c",
+    "720133ac",
+    "67e0d0f2",
+    "cc5ded98",
+    "726462e0",
+    "4100d0a0",
+    "3a704032",
+    "gpt4_7ca326fa",
+    "ec81a493",
+    "618f13b2",
+    "58470ed2",
+    "gpt4_4fc4f797",
+    "60036106",
+    "157a136e",
+    "6222b6eb",
+    "69fee5aa",
+    "19b5f2b3_abs",
+    "gpt4_d12ceb0e",
+    "51b23612",
+    "2318644b",
+    "3fe836c9",
+    "gpt4_7de946e7",
+    "71017277",
+    "f0853d11",
+    "dc439ea3",
+    "gpt4_2f91af09",
+    "9a707b81",
+    "bc8a6e93",
+    "c14c00dd",
+    "8979f9ec",
+    "cf22b7bf",
+    "gpt4_ec93e27f",
+    "gpt4_468eb063",
+    "41698283",
+    "1de5cff2",
+    "21d02d0d",
+    "c7cf7dfd",
+    "gpt4_ab202e7f",
+    "dccbc061",
+    "078150f1",
+    "e3038f8c",
+    "gpt4_c27434e8_abs",
+    "2698e78f",
+    "031748ae_abs",
+    "gpt4_59149c78",
+    "c8f1aeed",
+    "184da446",
+    "gpt4_b5700ca9",
+    "89527b6b",
+    "0977f2af",
+    "853b0a1d",
+    "a346bb18",
+    "3249768e",
+    "gpt4_2f8be40d",
+    "gpt4_93159ced_abs",
+    "eeda8a6d",
+    "7a8d0b71",
+    "95bcc1c8",
+    "gpt4_2487a7cb",
+    "85fa3a3f",
+    "7e00a6cb",
+    "e3fc4d6e",
+    "59524333",
+    "37f165cf",
+    "0ddfec37",
+    "60bf93ed",
+    "d7c942c3",
+    "80ec1f4f",
+    "ceb54acb",
+    "9aaed6a3",
+    "gpt4_4929293a",
+    "ed4ddc30",
+    "545bd2b5",
+    "2788b940",
+    "ef9cf60a",
+    "gpt4_7f6b06db",
+    "0ea62687",
+    "3d86fd0a",
+    "3e321797",
+    "d24813b1",
+    "38146c39",
+    "efc3f7c2",
+    "7401057b",
+    "5809eb10",
+    "28bcfaac",
+    "1903aded",
+    "gpt4_194be4b3",
+    "gpt4_e414231f",
+    "0ddfec37_abs",
+    "c2ac3c61",
+    "gpt4_4ef30696",
+    "1f2b8d4f",
+    "0f05491a",
+    "8550ddae",
+    "8077ef71",
+    "b86304ba",
+    "e61a7584",
+    "8cf51dda",
+    "gpt4_2f584639",
+    "08e075c7",
+    "5d3d2817",
+    "7405e8b1",
+    "a3045048",
+    "gpt4_731e37d7",
+    "c8090214_abs",
+    "36580ce8",
+    "ba358f49_abs",
+    "gpt4_d6585ce8",
+    "e56a43b9",
+    "2c63a862",
+    "gpt4_5438fa52",
+    "07b6f563",
+    "gpt4_31ff4165",
+    "0bb5a684",
+    "71315a70",
+    "gpt4_cd90e484",
+    "gpt4_8c8961ae",
+    "gpt4_fe651585_abs",
+    "36b9f61e",
+    "gpt4_b0863698",
+    "gpt4_1d4ab0c9",
+    "15745da0_abs",
+    "0862e8bf_abs",
+    "bcbe585f",
+    "a2f3aa27",
+    "gpt4_6dc9b45b",
+    "ccb36322",
+    "f685340e",
+    "9ea5eabc",
+    "gpt4_372c3eed",
+    "37d43f65",
+    "bf659f65",
+    "b0479f84",
+    "gpt4_213fd887",
+    "e4e14d04",
+    "f8c5f88b",
+    "gpt4_18c2b244",
+    "a11281a2",
+    "gpt4_2655b836",
+    "e47becba",
+    "gpt4_74aed68e",
+    "gpt4_af6db32f",
+    "6cb6f249",
+    "77eafa52",
+    "gpt4_93f6379c",
+    "e8a79c70",
+    "7a87bd0c",
+    "gpt4_6ed717ea",
+    "d6233ab6",
+    "c19f7a0b",
+    "gpt4_61e13b3c",
+    "d23cf73b",
+    "gpt4_1e4a8aeb",
+    "ba61f0b9",
+    "118b2229",
+    "488d3006",
+    "c4a1ceb8",
+    "8e91e7d9",
+    "42ec0761",
+    "65240037",
+    "fea54f57",
+    "c8090214",
+    "b01defab",
+    "6aeb4375_abs",
+    "faba32e5",
+    "c5e8278d",
+    "gpt4_e414231e",
+    "eeda8a6d_abs",
+    "gpt4_8e165409",
+    "af082822",
+    "22d2cb42",
+    "92a0aa75",
+    "1c549ce4",
+    "25e5aa4f",
+    "gpt4_68e94288",
+    "4baee567",
+    "18dcd5a5",
+    "dad224aa",
+    "gpt4_f2262a51",
+    "29f2956b",
+    "21436231",
+    "19b5f2b3",
+    "gpt4_1916e0ea",
+    "gpt4_45189cb4",
+    "0a995998",
+    "b6019101",
+    "9bbe84a2",
+    "61f8c8f8",
+    "9a707b82",
+    "8cf4d046",
+    "eac54add",
+    "75832dbd",
+    "gpt4_98f46fc6",
+    "d596882b",
+    "88432d0a_abs",
+    "16c90bf4",
+    "f685340e_abs",
+    "b5ef892d",
+    "gpt4_f49edff3",
+    "gpt4_483dd43c",
+    "bb7c3b45",
+    "gpt4_7abb270c",
+    "gpt4_9a159967",
+    "07741c44",
+    "4d6b87c8",
+    "6aeb4375",
+    "gpt4_d6585ce9",
+    "60472f9c",
+    "caf9ead2",
+    "32260d93",
+    "60159905",
+    "0a34ad58",
+    "a40e080f",
+    "10d9b85a",
+    "a06e4cfe",
+    "4f54b7c9",
+    "6613b389",
+    "70b3e69b",
+    "gpt4_7bc6cf22",
+    "gpt4_0a05b494",
+    "778164c6",
+    "195a1a1b",
+    "8464fc84",
+    "b46e15ed",
+    "603deb26",
+    "eaca4986",
+    "2698e78f_abs",
+    "gpt4_21adecb5",
+    "2e6d26dc",
+    "5831f84d",
+    "08f4fc43",
+    "3f1e9474",
+    "c9f37c46",
+    "gpt4_2f56ae70",
+    "1b9b7252",
+    "35a27287",
+    "gpt4_d31cdae3",
+    "129d1232",
+    "4adc0475",
+    "27016adc",
+    "46a3abf7",
+    "9ee3ecd6",
+    "982b5123",
+    "09ba9854_abs",
+    "0e5e2d1a",
+    "e9327a54",
+    "86f00804",
+    "e982271f",
+    "7161e7e2",
+    "57f827a0",
+    "6a27ffc2",
+    "edced276",
+    "gpt4_d9af6064",
+    "75499fd8",
+    "60d45044",
+    "gpt4_70e84552_abs",
+    "2ce6a0f2",
+    "gpt4_4929293b",
+    "a1cc6108",
+    "gpt4_5dcc0aab",
+    "a3838d2b",
+    "c7dc5443",
+    "505af2f5",
+    "gpt4_68e94287",
+    "15745da0",
+    "0100672e",
+    "a82c026e",
+    "5e1b23de",
+    "71017276",
+    "89941a93",
+    "6b168ec8",
+    "affe2881",
+    "0edc2aef",
+    "gpt4_2312f94c",
+    "a4996e51",
+    "c6853660",
+    "ef66a6e5",
+    "8a137a7f",
+    "a96c20ee",
+    "fca762bc",
+    "ac031881",
+    "d905b33f",
+    "e493bb7c",
+    "a9f6b44c",
+    "dd2973ad",
+    "8aef76bc",
+    "f35224e0",
+    "8b9d4367",
+    "gpt4_c27434e8",
+    "gpt4_a56e767c",
+    "eace081b",
+    "5a4f22c0",
+    "58bf7951",
+    "c4f10528",
+    "50635ada",
+    "06f04340",
+    "0bc8ad93",
+    "e5ba910e_abs",
+    "5a7937c8",
+    "a3332713",
+    "4388e9dd",
+    "8c18457d",
+    "gpt4_2c50253f",
+    "6a1eabeb",
+    "b3c15d39",
+    "gpt4_e061b84g",
+    "3b6f954b",
+    "gpt4_76048e76",
+    "4dfccbf7",
+    "2b8f3739",
+    "d851d5ba",
+    "4fd1909e",
+    "94f70d80",
+    "66f24dbb",
+    "a08a253f",
+    "6e984302",
+    "001be529",
+    "gpt4_a2d1d1f6",
+    "cc539528",
+    "e48988bc",
+    "gpt4_4cd9eba1",
+    "8e9d538c",
+    "a1eacc2a",
+    "6d550036",
+    "gpt4_e05b82a6",
+    "81507db6",
+    "caf03d32",
+    "031748ae",
+    "c960da58",
+    "1faac195",
+    "gpt4_4edbafa2"
+  ],
+  "seed": 42,
+  "dev_size": 50
+}

benchmarks/locomo_bench.py

@@ -510,11 +510,20 @@ def palace_assign_rooms(sessions, sample_id, api_key, cache, model="claude-haiku
 
 
 def llm_rerank_locomo(
-    question, retrieved_ids, retrieved_docs, api_key, top_k=10, model="claude-sonnet-4-6"
+    question,
+    retrieved_ids,
+    retrieved_docs,
+    api_key,
+    top_k=10,
+    model="claude-sonnet-4-6",
+    backend="anthropic",
+    base_url="",
 ):
     """
     Ask LLM to pick the single most relevant document for this question.
     Returns reordered retrieved_ids with the best candidate first.
+
+    Supports backend="anthropic" (default) or "ollama" (OpenAI-compat endpoint).
     """
     candidates = retrieved_ids[:top_k]
     candidate_docs = retrieved_docs[:top_k]
@@ -522,7 +531,6 @@ def llm_rerank_locomo(
     if len(candidates) <= 1:
         return retrieved_ids
 
-    # Build numbered list of candidates
     lines = []
     for i, (cid, doc) in enumerate(zip(candidates, candidate_docs), 1):
         snippet = doc[:300].replace("\n", " ")
@@ -534,35 +542,51 @@ def llm_rerank_locomo(
         f"Reply with just the number (1-{len(candidates)}).\n\n" + "\n".join(lines)
     )
 
-    payload = json.dumps(
-        {
-            "model": model,
-            "max_tokens": 8,
-            "messages": [{"role": "user", "content": prompt}],
-        }
-    ).encode("utf-8")
-
-    req = urllib.request.Request(
-        "https://api.anthropic.com/v1/messages",
-        data=payload,
-        headers={
+    if backend == "ollama":
+        url = (base_url or "http://localhost:11434").rstrip("/") + "/v1/chat/completions"
+        payload = json.dumps(
+            {
+                "model": model,
+                "messages": [{"role": "user", "content": prompt}],
+                "max_tokens": 1024,
+                "temperature": 0.0,
+            }
+        ).encode("utf-8")
+        headers = {"content-type": "application/json"}
+        if api_key:
+            headers["authorization"] = f"Bearer {api_key}"
+    else:
+        url = "https://api.anthropic.com/v1/messages"
+        payload = json.dumps(
+            {
+                "model": model,
+                "max_tokens": 8,
+                "messages": [{"role": "user", "content": prompt}],
+            }
+        ).encode("utf-8")
+        headers = {
             "x-api-key": api_key,
             "anthropic-version": "2023-06-01",
             "content-type": "application/json",
-        },
-        method="POST",
-    )
+        }
+
+    req = urllib.request.Request(url, data=payload, headers=headers, method="POST")
 
     import socket as _socket
 
     for _attempt in range(3):
         try:
-            with urllib.request.urlopen(req, timeout=30) as resp:
+            with urllib.request.urlopen(req, timeout=120 if backend == "ollama" else 30) as resp:
                 result = json.loads(resp.read())
-            raw = result["content"][0]["text"].strip()
-            m = re.search(r"\b(\d+)\b", raw)
+            if backend == "ollama":
+                msg = result["choices"][0]["message"]
+                raw = (msg.get("content") or "").strip() or (msg.get("reasoning") or "").strip()
+            else:
+                raw = result["content"][0]["text"].strip()
+            # Take LAST integer — reasoning models often count candidates first
+            m = re.search(r"\b(\d+)\b", raw[::-1])
             if m:
-                pick = int(m.group(1))
+                pick = int(m.group(1)[::-1])
                 if 1 <= pick <= len(candidates):
                     chosen_id = candidates[pick - 1]
                     reordered = [chosen_id] + [cid for cid in retrieved_ids if cid != chosen_id]
@@ -608,6 +632,8 @@ def run_benchmark(
     palace_cache_file=None,
     palace_model="claude-haiku-4-5-20251001",
     embed_model="default",
+    llm_backend="anthropic",
+    llm_base_url="",
 ):
     """Run LoCoMo retrieval benchmark."""
     with open(data_file) as f:
@@ -619,8 +645,12 @@ def run_benchmark(
     api_key = ""
     if llm_rerank_enabled or mode == "palace":
         api_key = _load_api_key(llm_key)
-        if not api_key:
-            print(f"ERROR: --mode {mode} requires an API key (--llm-key or ANTHROPIC_API_KEY).")
+        # Ollama backend doesn't require an Anthropic key. Palace mode still does
+        # (it uses Anthropic for room-assignment indexing) — so only relax the
+        # requirement when rerank is the ONLY llm use and backend is ollama.
+        needs_key = mode == "palace" or (llm_rerank_enabled and llm_backend == "anthropic")
+        if needs_key and not api_key:
+            print(f"ERROR: --mode {mode} / --llm-rerank (anthropic) requires an API key.")
             sys.exit(1)
 
     # Palace mode: load or create room assignment cache
@@ -888,6 +918,8 @@ def run_benchmark(
                         api_key,
                         top_k=rerank_pool,
                         model=llm_model,
+                        backend=llm_backend,
+                        base_url=llm_base_url,
                     )
 
                 # Compute recall
@@ -1013,6 +1045,18 @@ if __name__ == "__main__":
         help="Model for LLM rerank (default: claude-sonnet-4-6)",
     )
     parser.add_argument("--llm-key", default="", help="API key (or set ANTHROPIC_API_KEY env var)")
+    parser.add_argument(
+        "--llm-backend",
+        choices=["anthropic", "ollama"],
+        default="anthropic",
+        help="Which API for --llm-rerank. 'anthropic' (default) or 'ollama' "
+        "(OpenAI-compat /v1/chat/completions — works for local + Ollama Cloud).",
+    )
+    parser.add_argument(
+        "--llm-base-url",
+        default="",
+        help="Override base URL for --llm-backend ollama. Default: http://localhost:11434.",
+    )
     parser.add_argument(
         "--hybrid-weight",
         type=float,
@@ -1049,4 +1093,6 @@ if __name__ == "__main__":
         palace_cache_file=args.palace_cache,
         palace_model=args.palace_model,
         embed_model=args.embed_model,
+        llm_backend=args.llm_backend,
+        llm_base_url=args.llm_base_url,
     )

benchmarks/longmemeval_bench.py

@@ -2763,7 +2763,15 @@ def build_palace_and_retrieve_diary(
 
 
 def llm_rerank(
-    question, rankings, corpus, corpus_ids, api_key, top_k=10, model="claude-haiku-4-5-20251001"
+    question,
+    rankings,
+    corpus,
+    corpus_ids,
+    api_key,
+    top_k=10,
+    model="claude-haiku-4-5-20251001",
+    backend="anthropic",
+    base_url="",
 ):
     """
     Use an LLM to re-rank the top-k retrieved sessions.
@@ -2772,19 +2780,22 @@ def llm_rerank(
     which single session is most relevant to the question. That session
     is promoted to rank 1; the rest stay in their existing order.
 
-    This closes the gap for "preference" and jargon-dense "assistant"
-    failures where the right session is in top-10 semantically but not
-    top-5 — because the semantic gap (battery life ↔ phone hardware) is
-    too large for embeddings to bridge.
+    Supports two backends:
+      - "anthropic": hits https://api.anthropic.com/v1/messages with x-api-key.
+      - "ollama":    hits {base_url}/v1/chat/completions (OpenAI-compat) —
+                     works for local Ollama (default http://localhost:11434)
+                     and Ollama Cloud (:cloud model tags).
 
     Args:
-        question:    The benchmark question string
-        rankings:    Current ranked list of corpus indices (from any mode)
-        corpus:      List of document strings
-        corpus_ids:  List of corpus IDs (parallel to corpus)
-        api_key:     Anthropic API key string
-        top_k:       How many top sessions to send to LLM (default: 10)
-        model:       Claude model ID for reranking (default: haiku)
+        question:   The benchmark question string
+        rankings:   Current ranked list of corpus indices (from any mode)
+        corpus:     List of document strings
+        corpus_ids: List of corpus IDs (parallel to corpus)
+        api_key:    Anthropic API key (only required for backend="anthropic")
+        top_k:      How many top sessions to send to LLM (default: 10)
+        model:      Model id (Claude model for anthropic, e.g. "minimax-m2.7:cloud" for ollama)
+        backend:    "anthropic" or "ollama"
+        base_url:   Override base URL (ollama default: http://localhost:11434)
 
     Returns:
         Reordered rankings list with LLM's best pick promoted to rank 1.
@@ -2796,7 +2807,6 @@ def llm_rerank(
     if not candidates:
         return rankings
 
-    # Format sessions for the prompt — first 500 chars each, labelled 1..N
     session_blocks = []
     for rank, idx in enumerate(candidates):
         text = corpus[idx][:500].replace("\n", " ").strip()
@@ -2813,49 +2823,68 @@ def llm_rerank(
         f"Most relevant session number:"
     )
 
-    payload = json.dumps(
-        {
-            "model": model,
-            "max_tokens": 8,
-            "messages": [{"role": "user", "content": prompt}],
-        }
-    ).encode("utf-8")
-
-    req = urllib.request.Request(
-        "https://api.anthropic.com/v1/messages",
-        data=payload,
-        headers={
+    if backend == "ollama":
+        url = (base_url or "http://localhost:11434").rstrip("/") + "/v1/chat/completions"
+        payload = json.dumps(
+            {
+                "model": model,
+                "messages": [{"role": "user", "content": prompt}],
+                "max_tokens": 1024,
+                "temperature": 0.0,
+            }
+        ).encode("utf-8")
+        headers = {"content-type": "application/json"}
+        if api_key:
+            headers["authorization"] = f"Bearer {api_key}"
+    else:
+        url = "https://api.anthropic.com/v1/messages"
+        payload = json.dumps(
+            {
+                "model": model,
+                "max_tokens": 8,
+                "messages": [{"role": "user", "content": prompt}],
+            }
+        ).encode("utf-8")
+        headers = {
             "x-api-key": api_key,
             "anthropic-version": "2023-06-01",
             "content-type": "application/json",
-        },
-        method="POST",
-    )
+        }
+
+    req = urllib.request.Request(url, data=payload, headers=headers, method="POST")
 
     import socket as _socket
 
     for _attempt in range(3):
         try:
-            with urllib.request.urlopen(req, timeout=20) as resp:
+            with urllib.request.urlopen(req, timeout=120 if backend == "ollama" else 20) as resp:
                 result = json.loads(resp.read())
-            raw = result["content"][0]["text"].strip()
-            # Parse just the first integer from Haiku's response
-            m = re.search(r"\b(\d+)\b", raw)
+            if backend == "ollama":
+                msg = result["choices"][0]["message"]
+                # Reasoning models (e.g. minimax-m2.7) may emit final answer in "content"
+                # or embed it in "reasoning". Try content first, fall back to reasoning.
+                raw = (msg.get("content") or "").strip()
+                if not raw:
+                    raw = (msg.get("reasoning") or "").strip()
+            else:
+                raw = result["content"][0]["text"].strip()
+            m = re.search(
+                r"\b(\d+)\b", raw[::-1]
+            )  # take LAST integer (rerank models often reason first)
             if m:
-                pick = int(m.group(1))
+                pick = int(m.group(1)[::-1])
                 if 1 <= pick <= len(candidates):
                     chosen_idx = candidates[pick - 1]
                     reordered = [chosen_idx] + [i for i in rankings if i != chosen_idx]
                     return reordered
-            break  # Got a response, even if unparseable — don't retry
+            break
         except (_socket.timeout, TimeoutError):
             if _attempt < 2:
                 import time as _time
 
-                _time.sleep(3)  # brief pause then retry
-            # else fall through to return rankings
+                _time.sleep(3)
         except (urllib.error.URLError, KeyError, ValueError, IndexError, OSError):
-            break  # Non-timeout error — fall back immediately
+            break
 
     return rankings
 
@@ -2919,6 +2948,8 @@ def run_benchmark(
     skip_precompute=False,
     split_file=None,
     split_subset=None,
+    llm_backend="anthropic",
+    llm_base_url="",
 ):
     """Run the full benchmark.
 
@@ -2947,10 +2978,14 @@ def run_benchmark(
     api_key = ""
     if llm_rerank_enabled or mode == "diary":
         api_key = _load_api_key(llm_key)
-        if not api_key:
+        # Ollama backend doesn't require an Anthropic API key; a local/cloud Ollama
+        # daemon with the requested model pulled is enough. Diary mode is always anthropic.
+        needs_key = (llm_backend == "anthropic") or (mode == "diary")
+        if needs_key and not api_key:
             print(
-                "ERROR: --llm-rerank / --mode diary requires an API key. "
-                "Set ANTHROPIC_API_KEY or use --llm-key."
+                "ERROR: --llm-rerank (anthropic backend) / --mode diary requires an API key. "
+                "Set ANTHROPIC_API_KEY or use --llm-key. For ollama backend, pass "
+                "--llm-backend ollama."
             )
             sys.exit(1)
 
@@ -3100,7 +3135,15 @@ def run_benchmark(
         if llm_rerank_enabled:
             rerank_pool = 20 if mode in ("hybrid_v3", "hybrid_v4", "palace") else 10
             rankings = llm_rerank(
-                question, rankings, corpus, corpus_ids, api_key, top_k=rerank_pool, model=llm_model
+                question,
+                rankings,
+                corpus,
+                corpus_ids,
+                api_key,
+                top_k=rerank_pool,
+                model=llm_model,
+                backend=llm_backend,
+                base_url=llm_base_url,
             )
 
         # Evaluate at session level
@@ -3276,7 +3319,21 @@ if __name__ == "__main__":
         default="claude-haiku-4-5-20251001",
         help="Model for LLM re-ranking and diary ingest "
         "(default: claude-haiku-4-5-20251001). "
-        "Use 'claude-sonnet-4-6' for Sonnet comparison.",
+        "Use 'claude-sonnet-4-6' for Sonnet comparison. "
+        "With --llm-backend ollama, use an Ollama model tag like 'minimax-m2.7:cloud'.",
+    )
+    parser.add_argument(
+        "--llm-backend",
+        choices=["anthropic", "ollama"],
+        default="anthropic",
+        help="Which API to hit for --llm-rerank. 'anthropic' (default) uses Anthropic's "
+        "/v1/messages endpoint. 'ollama' uses Ollama's OpenAI-compatible "
+        "/v1/chat/completions endpoint (works with local Ollama and Ollama Cloud).",
+    )
+    parser.add_argument(
+        "--llm-base-url",
+        default="",
+        help="Override base URL for --llm-backend ollama. Defaults to http://localhost:11434.",
     )
     parser.add_argument(
         "--diary-cache",
@@ -3380,4 +3437,6 @@ if __name__ == "__main__":
         args.skip_precompute,
         split_file=args.split_file,
         split_subset=split_subset,
+        llm_backend=args.llm_backend,
+        llm_base_url=args.llm_base_url,
     )

docs/HISTORY.md

@@ -0,0 +1,144 @@
+# MemPalace — History, Corrections, and Public Notices
+
+This file is the canonical record of post-launch corrections, public notices,
+and retractions that affect MemPalace's public claims. Newest first.
+
+---
+
+## 2026-04-14 — Benchmark table rewrite (issue [#875](https://github.com/MemPalace/mempalace/issues/875))
+
+A community audit identified a category error in the public benchmark tables
+on `README.md` and `mempalaceofficial.com`: MemPalace's retrieval recall
+numbers (R@5, R@10) were listed in the same columns as competitors'
+end-to-end QA accuracy numbers. They are different metrics and are not
+comparable — a system can have 100% retrieval recall and 40% QA accuracy.
+
+The audit also found that the retracted "+34% palace boost" claim (see the
+April 7 note below) was still present in multiple surfaces despite that
+retraction, and that two competitor numbers (`Mem0 ~85%`, `Zep ~85%`) had no
+published source and did not match the metrics those projects actually
+publish.
+
+What changed in this PR:
+
+- The headline number on all surfaces is now **96.6% R@5 on LongMemEval in
+  raw mode**, independently reproduced on Linux x86_64 against the tagged
+  v3.3.0 release on 2026-04-14. Result JSONLs are committed under
+  `benchmarks/results_*.jsonl` (see PR description for the scorecard).
+- The **"100% with Haiku rerank"** claim has been removed from all public
+  comparison tables. It reproduces on our machines and with a different LLM
+  family (minimax-m2.7 via Ollama Cloud: 99.2% R@5 / 100.0% R@10 on the full
+  500-question LongMemEval set) — but the 99.4% → 100% step was developed
+  by inspecting three specific wrong answers (`benchmarks/BENCHMARKS.md` has
+  called this "teaching to the test" since February). It belongs in the
+  methodology document, not in a headline.
+- The **honest held-out number** for the hybrid pipeline — 98.4% R@5 on 450
+  questions that `hybrid_v4` was never tuned on, deterministic seed — is now
+  the comparable figure when an LLM rerank is involved.
+- The **retracted "+34% palace boost"** has been removed from
+  `README.md`, `website/concepts/the-palace.md`,
+  `website/guide/searching.md`, and `website/reference/contributing.md`.
+  Wing and room filters remain useful — they're standard metadata filters —
+  but they are not presented as a novel retrieval improvement.
+- **Competitor comparison tables** mixing retrieval recall with QA accuracy
+  have been removed from `README.md` and `website/reference/benchmarks.md`.
+  Where MemPalace can be fairly compared on the same metric, we link to the
+  cited source. Otherwise we report our own numbers and let readers draw
+  their own conclusions.
+- **Reproduction instructions** in `benchmarks/BENCHMARKS.md` and
+  `benchmarks/README.md` were pointing at a defunct branch
+  (`aya-thekeeper/mempal`); they now point at `MemPalace/mempalace`.
+- The **LoCoMo 100% R@10 with top-50 rerank** row has been removed from
+  public comparison surfaces. With per-conversation session counts of 19–32
+  and `top_k=50`, the retrieval stage returns every session in the
+  conversation by construction, so the number measures an LLM's
+  reading comprehension over the whole conversation, not retrieval.
+
+Thanks to [@dial481](https://github.com/MemPalace/mempalace/issues/875) for
+the detailed audit and to [@rohitg00](https://github.com/rohitg00) for the
+parallel write-up in Discussion #747.
+
+---
+
+## 2026-04-11 — Impostor domains and malware
+
+Several community members (issues #267, #326, #506) reported fake MemPalace
+websites distributing malware. The only official surfaces for this project
+are:
+
+- This GitHub repository: [github.com/MemPalace/mempalace](https://github.com/MemPalace/mempalace)
+- The PyPI package: [pypi.org/project/mempalace](https://pypi.org/project/mempalace/)
+- The docs site: [mempalaceofficial.com](https://mempalaceofficial.com)
+
+Any other domain — `mempalace.tech` being the one most commonly reported —
+is not ours. Never run install scripts from unofficial sites.
+
+Thanks to our community members for flagging the problem.
+
+---
+
+## 2026-04-07 — A Note from Milla & Ben
+
+> The community caught real problems in this README within hours of launch
+> and we want to address them directly.
+>
+> **What we got wrong:**
+>
+> - **The AAAK token example was incorrect.** We used a rough heuristic
+>   (`len(text)//3`) for token counts instead of an actual tokenizer. Real
+>   counts via OpenAI's tokenizer: the English example is 66 tokens, the
+>   AAAK example is 73. AAAK does not save tokens at small scales — it's
+>   designed for *repeated entities at scale*, and the README example was a
+>   bad demonstration of that. We're rewriting it.
+>
+> - **"30x lossless compression" was overstated.** AAAK is a lossy
+>   abbreviation system (entity codes, sentence truncation). Independent
+>   benchmarks show AAAK mode scores **84.2% R@5 vs raw mode's 96.6%** on
+>   LongMemEval — a 12.4 point regression. The honest framing is: AAAK is
+>   an experimental compression layer that trades fidelity for token
+>   density, and **the 96.6% headline number is from RAW mode, not AAAK**.
+>
+> - **"+34% palace boost" was misleading.** That number compares unfiltered
+>   search to wing+room metadata filtering. Metadata filtering is a
+>   standard feature of the underlying vector store, not a novel retrieval
+>   mechanism. Real and useful, but not a moat.
+>
+> - **"Contradiction detection"** exists as a separate utility
+>   (`fact_checker.py`) but is not currently wired into the knowledge graph
+>   operations as the README implied.
+>
+> - **"100% with Haiku rerank"** is real (we have the result files) but
+>   the rerank pipeline is not in the public benchmark scripts. We're
+>   adding it.
+>
+> **What's still true and reproducible:**
+>
+> - **96.6% R@5 on LongMemEval in raw mode**, on 500 questions, zero API
+>   calls — independently reproduced on M2 Ultra in under 5 minutes by
+>   [@gizmax](https://github.com/MemPalace/mempalace/issues/39).
+> - Local, free, no subscription, no cloud, no data leaving your machine.
+> - The architecture (wings, rooms, closets, drawers) is real and useful,
+>   even if it's not a magical retrieval boost.
+>
+> **What we're doing:**
+>
+> 1. Rewriting the AAAK example with real tokenizer counts and a scenario
+>    where AAAK actually demonstrates compression
+> 2. Adding `mode raw / aaak / rooms` clearly to the benchmark
+>    documentation so the trade-offs are visible
+> 3. Wiring `fact_checker.py` into the KG ops so the contradiction
+>    detection claim becomes true
+> 4. Pinning the vector store dependency to a tested range (issue #100),
+>    fixing the shell injection in hooks (#110), and addressing the macOS
+>    ARM64 segfault (#74)
+>
+> **Thank you to everyone who poked holes in this.** Brutal honest
+> criticism is exactly what makes open source work, and it's what we asked
+> for. Special thanks to
+> [@panuhorsmalahti](https://github.com/MemPalace/mempalace/issues/43),
+> [@lhl](https://github.com/MemPalace/mempalace/issues/27),
+> [@gizmax](https://github.com/MemPalace/mempalace/issues/39), and everyone
+> who filed an issue or a PR in the first 48 hours. We're listening, we're
+> fixing, and we'd rather be right than impressive.
+>
+> — *Milla Jovovich & Ben Sigman*

docs/rfcs/002-source-adapter-plugin-spec.md

@@ -0,0 +1,768 @@
+# RFC 002 — Source Adapter Plugin Specification
+
+- **Status:** Draft
+- **Tracking issue:** [#989](https://github.com/MemPalace/mempalace/issues/989)
+- **Related:** [#274](https://github.com/MemPalace/mempalace/issues/274), [#23](https://github.com/MemPalace/mempalace/pull/23), [#169](https://github.com/MemPalace/mempalace/pull/169), [#232](https://github.com/MemPalace/mempalace/pull/232), [#567](https://github.com/MemPalace/mempalace/pull/567), [#98](https://github.com/MemPalace/mempalace/pull/98), [#591](https://github.com/MemPalace/mempalace/pull/591), [#592](https://github.com/MemPalace/mempalace/pull/592), [#702](https://github.com/MemPalace/mempalace/pull/702), [#981](https://github.com/MemPalace/mempalace/issues/981), [#244](https://github.com/MemPalace/mempalace/pull/244), [#419](https://github.com/MemPalace/mempalace/pull/419), [#300](https://github.com/MemPalace/mempalace/pull/300), [#952](https://github.com/MemPalace/mempalace/pull/952), [#389](https://github.com/MemPalace/mempalace/pull/389), [#434](https://github.com/MemPalace/mempalace/pull/434)
+- **Sibling spec:** [RFC 001 — Storage Backend Plugin Specification](001-storage-backend-plugin-spec.md)
+- **Spec version:** `1.0`
+
+## Summary
+
+A formal contract for MemPalace source adapters so third parties can ship `pip install mempalace-source-<name>` packages (Cursor, OpenCode, git, Slack, Notion, email, calendar, Whisper transcripts, …) that drop into `mempalace mine` without patching core. The spec defines the adapter interface, record shape, metadata schema contract, privacy class, entry-point registration, incremental-ingest semantics, closet integration, a declared-transformation model that replaces the informal "verbatim" promise with a verifiable one, conformance tests, and the refactor of the existing file and conversation miners into first-party adapters on the same contract.
+
+RFC 001 formalized the write side (where drawers are stored). This RFC formalizes the read side (where content comes from). Both are required for MemPalace to function as a durable daemon managing heterogeneous palaces across many source types.
+
+## Motivation
+
+Six source ingesters are currently in flight, each solving the same problem a different way:
+
+| PR / Issue | Source | Mechanism |
+|---|---|---|
+| [#274](https://github.com/MemPalace/mempalace/issues/274) | Cursor | `workspaceStorage/*.vscdb` SQLite extraction |
+| [#23](https://github.com/MemPalace/mempalace/pull/23) | OpenCode | SQLite session database |
+| [#169](https://github.com/MemPalace/mempalace/pull/169) | Pi agent | JSONL session normalizer |
+| [#232](https://github.com/MemPalace/mempalace/pull/232) | Cursor (JSONL variant) | JSONL normalizer |
+| [#567](https://github.com/MemPalace/mempalace/pull/567), [#98](https://github.com/MemPalace/mempalace/pull/98) | Git | `git log` + `gh pr view` with structured diff summary |
+| [#591](https://github.com/MemPalace/mempalace/pull/591), [#592](https://github.com/MemPalace/mempalace/pull/592) | Delphi Oracle | Real-time intelligence signals |
+| [#702](https://github.com/MemPalace/mempalace/pull/702) | Cursor + factory.ai | Combined session miners |
+
+Plus three ingesters already grafted into core:
+
+- `mempalace/miner.py` — filesystem project miner, fixed char-window chunking, keyword hall routing
+- `mempalace/convo_miner.py` — chat transcript miner with exchange-pair chunking
+- `mempalace/normalize.py` — format detection for four chat-export shapes (Claude Code JSONL, Codex JSONL, Claude.ai / ChatGPT / Slack JSON)
+
+Plus one open proposal for a different ingest semantic:
+
+- [#981](https://github.com/MemPalace/mempalace/issues/981) — path-level descriptions: mine metadata-as-content instead of raw bytes for matched paths. This is a legitimate third ingest mode (alongside chunked-content and whole-record) that the current architecture has no home for.
+
+Each contributor has reinvented source discovery, source-item identity, incremental-ingest bookkeeping, metadata shape, and chunking strategy. Format detection for new chat exports lands in `normalize.py` as one more branch in an `if` chain. There is no shared abstraction, no conformance suite, and no contract new adapter authors can build against.
+
+This is the same situation RFC 001 addresses for storage backends: a pattern that emerged organically, now needs a specification so the community can contribute cleanly and enterprises can build against a stable surface.
+
+### Why this matters beyond developer tooling
+
+The adapter pattern is source-agnostic. What has so far shown up as "Cursor transcripts" and "git commits" generalizes to:
+
+- **Knowledge work** — Notion, Obsidian, Logseq, Google Docs, iA Writer, Zettlr
+- **Communications** — Slack, Discord, Teams, Signal backups, mbox/eml email, iMessage
+- **Research** — arXiv PDFs, Zotero libraries, bookmarked articles, Kindle highlights, web archives
+- **Creator workflows** — YouTube captions, podcast transcripts (Whisper/Deepgram), Descript projects
+- **Regulated domains** — medical records, legal filings, financial statements (all gated on §6 privacy class)
+
+Enterprises key on their own domain metadata — `repo/PR/SHA` for engineering, `patient/encounter/CPT` for healthcare, `case/docket/jurisdiction` for legal. The schema lives in the adapter; the content lives in the drawer. This is how structured-data use cases are served without violating the byte-preservation commitments adapters make.
+
+## Goals
+
+1. A source adapter ships as a standalone Python package; `pip install mempalace-source-<name>` is sufficient to use it.
+2. `mempalace mine` and the MCP mine tool are source-agnostic — all extraction goes through registered adapters. No `if source_type == 'foo'` branches in core.
+3. Content transformations are **declared** (§1.4): each adapter advertises the set of transformations it applies to source bytes. Byte-preserving adapters declare the empty set. Consumers can programmatically determine what happened to their data.
+4. Incremental ingest is cheap and correct: re-running mine only touches items whose source-side version changed, using the palace itself as the cursor (no sidecar).
+5. Each adapter declares a structured metadata schema. Enterprises index and filter on that schema. Core is schema-agnostic beyond the universal fields in §5.1.
+6. The existing `miner.py` and `convo_miner.py` become the first two first-party adapters on the new contract. Drawer metadata fields and field names are preserved — the spec adds fields, does not rename them.
+7. A privacy class is declarable at the adapter boundary so sensitive sources (medical, financial, personal comms) are handled with explicit policy rather than implicit trust.
+
+## Non-goals
+
+- Defining chunking. Each adapter owns its chunking strategy — tree-sitter for code, exchange-pair for chat, whole-record for a PR. Core does not impose a chunk size.
+- Defining live-stream / webhook shapes (the Delphi Oracle pattern of continuous signal ingestion). That is a separate future RFC; v1 is pull-mode.
+- Defining LLM-based structured extraction. Adapters MAY use an LLM; the spec does not mandate or standardize this.
+- Defining cross-adapter dedup. When the same content appears via two adapters (e.g., a PR body mined via `git` and as a conversation quote mined via `claude-code`), both drawers land. Deduplication policy is a separate concern handled at query time by `searcher.py`.
+- Defining closet construction. Core continues to build closets from adapter-yielded drawers (§1.7); the closet-building algorithm itself is not part of this spec.
+
+---
+
+## 1. Source adapter contract
+
+### 1.1 Required method
+
+All adapters implement `BaseSourceAdapter` with a single kwargs-only ingest method:
+
+```python
+class BaseSourceAdapter(ABC):
+    @abstractmethod
+    def ingest(
+        self,
+        *,
+        source: SourceRef,
+        palace: PalaceContext,
+    ) -> Iterator[IngestResult]:
+        """Enumerate and extract content from a source.
+
+        Yields a stream of IngestResult values. Lazy adapters yield
+        `SourceItemMetadata` ahead of the drawers for that item, so core
+        can report progress and check `is_current` before the adapter
+        commits to the fetch. Adapters with no lazy-fetch benefit may
+        interleave `SourceItemMetadata` and `DrawerRecord` items freely.
+        """
+
+    @abstractmethod
+    def describe_schema(self) -> AdapterSchema:
+        """Declare the structured metadata this adapter attaches.
+
+        Returned value is stable for a given adapter version. Enterprises
+        index on this schema; core uses it to validate adapter output.
+        """
+```
+
+The single-method `ingest()` contract was chosen over a `discover` / `extract` split. Most current ingesters have no meaningful laziness benefit (filesystem walking is cheap, transcript normalizing is cheap). Adapters that do (git-mine's `gh pr list` vs `gh pr view`; hypothetical Slack/Notion API) express laziness by yielding `SourceItemMetadata` first and deferring fetch until core confirms staleness via `is_current()`.
+
+### 1.2 Optional methods (default implementations on the ABC)
+
+```python
+def is_current(
+    self,
+    *,
+    item: SourceItemMetadata,
+    existing_metadata: dict | None,
+) -> bool:
+    """Return True if the palace already has an up-to-date copy.
+
+    Called by core after querying the palace for existing drawers with
+    matching source_file. The adapter compares its version token against
+    the stored metadata and returns True to skip extraction.
+
+    Default implementation: returns False (always re-extract). Adapters
+    advertising `supports_incremental` override this.
+    """
+    return False
+
+def source_summary(self, *, source: SourceRef) -> SourceSummary:
+    """Describe a source without extracting (e.g., 'git repo mempalace,
+    847 commits, 132 PRs'). Default: returns empty summary."""
+    return SourceSummary(description=self.name)
+
+def close(self) -> None:
+    return None
+```
+
+Core's incremental loop (pseudocode):
+
+```python
+for result in adapter.ingest(source=source, palace=ctx):
+    if isinstance(result, SourceItemMetadata):
+        existing = ctx.collection.get(where={"source_file": result.source_file}, limit=1)
+        if adapter.is_current(item=result, existing_metadata=existing):
+            ctx.skip_current_item()   # adapter stops yielding drawers for this item
+    elif isinstance(result, DrawerRecord):
+        ctx.upsert_drawer(result)
+```
+
+### 1.3 Typed records
+
+```python
+@dataclass(frozen=True)
+class SourceRef:
+    """A handle to the source a user wants to ingest.
+
+    local_path is for filesystem-rooted sources (project dir, mbox file).
+    uri is for URL-like references (github.com/org/repo, slack://workspace/channel).
+    options carries adapter-specific config (non-secret values only; §M2).
+    """
+    local_path: str | None = None
+    uri: str | None = None
+    options: dict = field(default_factory=dict)
+
+@dataclass(frozen=True)
+class SourceItemMetadata:
+    """Lightweight pointer yielded before drawers for lazy-fetch adapters."""
+    source_file: str                 # Logical identity — filesystem path, PR URI, etc.
+    version: str                     # Source-side version token (mtime, commit SHA, ETag, rev id).
+    size_hint: int | None = None     # Bytes, if known. Used for progress reporting.
+    route_hint: RouteHint | None = None
+
+@dataclass(frozen=True)
+class DrawerRecord:
+    """One drawer's worth of content plus metadata."""
+    content: str                     # Subject to §1.4 declared transformations.
+    source_file: str                 # Foreign key to SourceItemMetadata.source_file.
+    chunk_index: int = 0             # 0 for single-drawer items; 0..N-1 for chunked items.
+    metadata: dict = field(default_factory=dict)  # Flat: str/int/float/bool only. Must conform to adapter schema.
+    route_hint: RouteHint | None = None
+
+@dataclass(frozen=True)
+class RouteHint:
+    wing: str | None = None
+    room: str | None = None
+    hall: str | None = None
+
+@dataclass(frozen=True)
+class SourceSummary:
+    description: str
+    item_count: int | None = None
+
+# IngestResult is the union type adapters yield.
+IngestResult = SourceItemMetadata | DrawerRecord
+
+# PalaceContext carries collection handles, palace config, and progress hooks
+# into the adapter. Full definition in §9 (cleanup prerequisite).
+```
+
+### 1.4 Declared transformations
+
+Adapters cannot silently alter content. Every adapter declares the set of transformations it applies:
+
+```python
+class BaseSourceAdapter(ABC):
+    declared_transformations: ClassVar[frozenset[str]] = frozenset()
+```
+
+The invariant: **no transformation is applied that is not declared in this set**. Adapters declaring `frozenset()` are byte-preserving end-to-end (modulo the read, which may itself involve `utf8_replace_invalid` — see below).
+
+Reserved transformation names (v1):
+
+| Name | Meaning |
+|---|---|
+| `utf8_replace_invalid` | Undecodable bytes replaced with U+FFFD on read (equivalent to `open(..., errors="replace")`). |
+| `newline_normalize` | CRLF / CR converted to LF. |
+| `whitespace_trim` | Leading / trailing whitespace stripped at a record boundary. |
+| `whitespace_collapse_internal` | Runs of three or more blank lines collapsed to two. |
+| `line_trim` | Each line individually stripped of leading / trailing whitespace. |
+| `line_join_spaces` | Adjacent lines joined with single spaces, newlines discarded. |
+| `blank_line_drop` | Empty lines between non-empty lines dropped. |
+| `strip_tool_chrome` | System tags, hook output, tool UI chrome removed (see `normalize.strip_noise`). |
+| `tool_result_truncate` | Tool output heads/tails kept; middle replaced with a marker string. |
+| `spellcheck_user` | User turns rewritten by spellcheck. |
+| `synthesized_marker` | Adapter inserts its own strings (e.g., `[N lines omitted]`, `[registry] …`, Slack provenance footer). |
+| `speaker_role_assignment` | Multi-party speakers alternately assigned `user` / `assistant` roles (Slack). |
+| `tool_result_omitted` | Some tool outputs fully omitted from transcript (e.g., Read/Edit/Write results in `normalize._format_tool_result`). |
+
+Adapters MAY define their own transformation names for behaviors the reserved list does not cover. Third-party names SHOULD be prefixed with the adapter name to avoid collisions (e.g., `cursor.composer_ordering`).
+
+**Capability derivation:**
+- `byte_preserving` — declared_transformations is empty AND output bytes equal input bytes for any source the adapter can read. Advertised via the `byte_preserving` capability (§2.1). MUST be verified by §7.2 round-trip test.
+- `declared_lossy` — declared_transformations is non-empty. The adapter's output is reproducible from source by applying *only* the declared transformations. MUST be verified by §7.3 declared-transformation test.
+
+**Existing code mapping (for the cleanup PR):**
+
+| Module | Declared transformations |
+|---|---|
+| `filesystem` (current `miner.py`) | `utf8_replace_invalid`, `whitespace_trim` |
+| `conversations` (current `convo_miner.py` + `normalize.py`) | `utf8_replace_invalid`, `newline_normalize`, `line_trim`, `line_join_spaces`, `blank_line_drop`, `whitespace_collapse_internal`, `strip_tool_chrome`, `tool_result_truncate`, `tool_result_omitted`, `spellcheck_user`, `synthesized_marker`, `speaker_role_assignment` |
+
+The filesystem adapter is nearly byte-preserving today; the conversations adapter is extensively transformed. Both are honest after this spec lands because both are fully declared.
+
+This replaces the MISSION.md promise of "verbatim always" with a stronger one: every adapter publishes what it does to your data, and the conformance suite verifies it hasn't lied. "Verbatim" becomes a capability some adapters hold (byte_preserving), not a global claim about a lossy pipeline.
+
+### 1.5 Three ingest modes
+
+A single adapter declares one or more of three modes via a class attribute:
+
+```python
+class BaseSourceAdapter(ABC):
+    supported_modes: ClassVar[frozenset[Literal["chunked_content", "whole_record", "metadata_only"]]]
+```
+
+| Mode | Content origin |
+|---|---|
+| `chunked_content` | Source bytes, split into chunks the adapter chooses (current filesystem behavior). |
+| `whole_record` | Source bytes, one drawer per source item (e.g., PR → 1 drawer). |
+| `metadata_only` | Synthesized description of a source item (absorbs #981). The description bytes are authored by the user or adapter, not the source. Declared transformations (§1.4) do not apply — content is not derived from source bytes. |
+
+`metadata_only` resolves #981: description-mode matches a path pattern and produces one drawer whose content is the user-authored description rather than the file contents. Conformance tests (§7.2, §7.3) skip `metadata_only` records.
+
+An adapter MAY support multiple modes and select per-item; the per-item mode is recorded in `metadata["ingest_mode"]` (§5.1). This field already exists on conversation drawers (`convo_miner.py:346`) and is the only existing field whose semantics this spec extends rather than preserves.
+
+### 1.6 Chunking delegation
+
+Core does not impose chunking. `miner.py`'s 800-character sliding window is the filesystem adapter's default for unknown file types — not a contract. Adapter authors choose what makes sense:
+
+- Code files → tree-sitter function/class boundaries (future enhancement to the filesystem adapter).
+- Chat transcripts → exchange pairs (current `convo_miner.py` behavior).
+- PRs → whole-record (current `git-mine` behavior in #567).
+- PDFs → page or section.
+- Voice transcripts → speaker turn.
+
+The sole cross-adapter requirement for `chunked_content` mode: chunks for a given `source_file`, re-assembled in `chunk_index` order and accounting for declared transformations in §1.4, reproduce the adapter's internal representation of the source. The conformance suite verifies this.
+
+### 1.7 Closet integration
+
+Closets are the AAAK-compressed index layer (`palace.build_closet_lines`, `upsert_closet_lines`) that points to drawer content and enables LLM-scale scanning without reading every drawer. Closet-building is not an adapter concern:
+
+- **Core builds closets** from adapter-yielded drawers as a post-step, via the existing `palace.py` helpers. Adapters do not call these APIs.
+- **Adapters MAY emit closet hints** in drawer metadata via a flat `;`-joined string:
+  ```python
+  metadata["closet_hints"] = "decided GraphQL; migrated to Postgres; fixed PR-567"
+  ```
+  Core splits on `;` and feeds these as candidate topics alongside the content-scanned ones in `build_closet_lines`. The git adapter can hint decision-signal quotes that raw content-scanning would miss; the conversations adapter can hint section headers; the filesystem adapter has no need and omits the field.
+- **metadata_only drawers get closets too.** Core builds them from the synthesized description content the same way it builds closets for any other drawer. This is how #981's path-level descriptions become searchable.
+- **Closet purging** remains keyed on `source_file` (`purge_file_closets` in `palace.py:221`). Adapters' source_file values must be stable so purge is correct on re-ingest.
+
+Current `convo_miner.py` does not build closets for conversation drawers — an existing gap. The cleanup PR (§9) routes the conversations adapter through the same post-step closet builder as filesystem, closing the gap as a side effect.
+
+---
+
+## 2. Adapter contract
+
+### 2.1 Identity and capabilities
+
+```python
+class BaseSourceAdapter(ABC):
+    name: ClassVar[str]                    # "filesystem", "cursor", "git", "slack", ...
+    spec_version: ClassVar[str] = "1.0"
+    adapter_version: ClassVar[str]         # Independent of spec_version; recorded on every drawer.
+    capabilities: ClassVar[frozenset[str]]
+    supported_modes: ClassVar[frozenset[str]]             # Per §1.5.
+    declared_transformations: ClassVar[frozenset[str]]    # Per §1.4.
+    default_privacy_class: ClassVar[str]                  # Per §6.
+```
+
+Defined capability tokens (v1):
+
+| Token | Meaning |
+|---|---|
+| `byte_preserving` | `declared_transformations` is empty AND extracted content equals source bytes. |
+| `supports_incremental` | Implements `is_current()` meaningfully; `ingest()` respects `ctx.skip_current_item()`. |
+| `supports_structured_metadata` | Attaches fields beyond §5.1 universals. |
+| `supports_entity_hints` | Emits entity hints via `metadata["entity_hints_json"]` (§5.4). |
+| `supports_kg_triples` | Writes knowledge-graph triples directly to the SQLite KG (§5.5). |
+| `supports_closet_hints` | Emits `metadata["closet_hints"]` (§1.7). |
+| `requires_auth` | Needs credentials at runtime (env vars — §4.2). |
+| `requires_external_service` | Needs a running service (Slack API, email server). |
+| `requires_local_tool` | Needs a local binary (`gh`, `rg`, `whisper`). |
+| `adapter_owns_routing` | Returns authoritative `RouteHint` values from `ingest()` that core uses as-is (§G3 / §2.5). |
+| `respects_privacy_class` | Honors §6 privacy-class filtering. |
+
+Capability tokens are free-form strings; third-party adapters MAY declare novel tokens for their ecosystem. Core only inspects the above.
+
+### 2.2 Source references
+
+See `SourceRef` in §1.3. The shape is deliberately open — adapters parse `uri` and `options` as they see fit. Core does not canonicalize URIs.
+
+**Secrets in `SourceRef.options`:** credentials MUST NOT be placed in `options`. The spec reserves `options` for non-secret values (paths, filters, date ranges). Secrets come from env vars per §4.2. An adapter that reads a credential from `options` violates the spec and MUST be rejected by the conformance suite.
+
+### 2.3 Lifecycle
+
+1. `__init__`: lightweight. No I/O, no network, no credential fetch.
+2. First call to `ingest`: may open resources. All I/O is lazy.
+3. `close()`: releases all resources. After `close()`, further calls MUST raise `AdapterClosedError`.
+
+### 2.4 Concurrency
+
+An adapter instance is long-lived and serves many mine operations. Adapters MUST be thread-safe for concurrent `ingest` calls across different `SourceRef` values. MemPalace core serializes calls within a single `SourceRef` unless an adapter advertises `supports_parallel_ingest` (not in v1 — reserved for v1.1).
+
+### 2.5 Routing
+
+Routing is the adapter's responsibility. The filesystem adapter reads `mempalace.yaml` (hall keywords, rooms list) via `MempalaceConfig()` and returns `RouteHint(wing=..., room=..., hall=...)` on each drawer. This relocates `detect_room()` and `detect_hall()` (currently in `miner.py` and `convo_miner.py`) into their respective adapters.
+
+Order of precedence for routing:
+1. Explicit `--wing` / `--room` CLI flags → passed through `SourceRef.options` → adapter honors verbatim.
+2. Palace config match (`mempalace.yaml` hall keywords, room keywords) → adapter computes.
+3. Adapter-internal fallback (e.g., filesystem adapter falls back to `"general"` room).
+
+Adapters advertising `adapter_owns_routing` return the final answer; core uses it verbatim. Adapters not advertising it return None and core applies a generic fallback router (writing to wing `default`, room `general`, hall `general`). Absent any adapter, this is how `mempalace mine` behaves today.
+
+### 2.6 Incremental ingest
+
+`is_current()` is the incremental-ingest primitive. The palace itself is the cursor — no separate persisted state. Correctness requirements:
+
+- The adapter's `SourceItemMetadata.source_file` MUST be stable across re-ingests of the same logical item. Filesystem adapter uses the absolute path (as today). Git adapter uses a URI shape like `github.com/org/repo#pr=567` or `github.com/org/repo#commit=abc123`.
+- `is_current()` returns True when the stored metadata matches the adapter's current version token. The default implementation returns False (always re-extract) — adapters advertising `supports_incremental` override.
+- Deletion tombstones: an adapter MAY yield a `SourceItemMetadata(source_file=..., version="__deleted__")` entry — core purges drawers with matching `source_file` and builds no new drawers for that item. Advertised via `supports_deletion_tombstones`.
+- Adapters without `supports_incremental` ignore `is_current()` and fully re-extract. Core logs a warning.
+
+### 2.7 Errors
+
+- `SourceNotFoundError` — the `SourceRef` does not resolve.
+- `AuthRequiredError` — adapter needs credentials; raises with a message describing which env vars to set.
+- `AdapterClosedError` — method called after `close()`.
+- `TransformationViolationError` — conformance suite raises this when the content round-trip requires an undeclared transformation.
+- `SchemaConformanceError` — a `DrawerRecord.metadata` is missing required fields declared in `describe_schema()` or violates declared types.
+
+---
+
+## 3. Registration and discovery
+
+### 3.1 Entry points (primary mechanism)
+
+Third-party adapters ship as installable packages:
+
+```toml
+# pyproject.toml of mempalace-source-cursor
+[project.entry-points."mempalace.sources"]
+cursor = "mempalace_source_cursor:CursorAdapter"
+```
+
+MemPalace discovers adapters at process start via `importlib.metadata.entry_points(group="mempalace.sources")`.
+
+### 3.2 In-tree registry (secondary)
+
+```python
+from mempalace.sources.registry import register
+
+register("my-experimental-adapter", MyAdapter)
+```
+
+Entry-point discovery and explicit `register()` populate the same registry. Explicit registration wins on name conflict.
+
+### 3.3 Selection (explicit only — no auto-detect)
+
+Unlike storage backends (RFC 001 §3.3), source adapters are never auto-detected. The user selects the adapter explicitly:
+
+```bash
+mempalace mine --source cursor ~/                      # explicit adapter
+mempalace mine --source git /path/to/repo              # explicit adapter
+mempalace mine --source filesystem /path/to/project    # explicit adapter
+mempalace mine /path/to/project                        # implicit: filesystem (default)
+```
+
+The default when no `--source` is given is `filesystem`, preserving current `mempalace mine <path>` behavior.
+
+**Backwards compatibility with `--mode`.** Current `cli.py:517-519` exposes `--mode {projects,convos}`. This spec maps:
+- `--mode projects` → `--source filesystem` (the new default)
+- `--mode convos` → `--source conversations`
+
+`--mode` stays as a deprecated alias through v4.x with a deprecation warning on use; removed in v5.0.
+
+Auto-detection would be hostile — a directory containing a `.git` folder, a `workspaceStorage/` subdir, and an `mbox` file is not a signal of user intent.
+
+---
+
+## 4. Configuration
+
+### 4.1 Shape
+
+```json
+{
+  "sources": {
+    "my-cursor": {
+      "type": "cursor",
+      "workspace_storage": "~/Library/Application Support/Cursor/User/workspaceStorage"
+    },
+    "my-git": {
+      "type": "git",
+      "repos": ["/projects/mempalace", "/projects/site"]
+    }
+  },
+  "palaces": {
+    "work": {
+      "sources": ["my-git"],
+      "privacy_floor": "internal"
+    },
+    "personal": {
+      "sources": ["my-cursor"]
+    }
+  }
+}
+```
+
+Single-user local mode: config is optional. `mempalace mine <path>` with no config uses the `filesystem` adapter and defaults.
+
+### 4.2 Environment variables
+
+- `MEMPALACE_SOURCE_<NAME>_*` — per-adapter secrets and connection info. Examples: `MEMPALACE_SOURCE_SLACK_TOKEN`, `MEMPALACE_SOURCE_NOTION_API_KEY`, `MEMPALACE_SOURCE_GIT_GITHUB_TOKEN`.
+- Secrets MUST be readable from env vars; config files carry structure, env vars carry credentials. Same rule as RFC 001 §4.2.
+
+### 4.3 Adapter-specific options
+
+`SourceRef.options` is a free-form dict of non-secret values (§2.2). Each adapter documents its accepted keys. Unknown keys MUST be ignored (forward compatibility); the adapter MAY log a warning.
+
+---
+
+## 5. Metadata schema contract
+
+### 5.1 Universal fields
+
+Existing drawer metadata fields are preserved — the spec adds the following:
+
+| New field | Type | Added by | Purpose |
+|---|---|---|---|
+| `adapter_name` | `str` | core, from `BaseSourceAdapter.name` | Which registered source produced this drawer. |
+| `adapter_version` | `str` | adapter | Adapter's own version (distinct from palace `normalize_version`). Enables re-extract workflows targeted at drawers from a known-buggy adapter version. |
+| `privacy_class` | `str` | adapter default, config override | Per §6. |
+
+Existing fields retain their current semantics (verified against `miner.py:542-561` and `convo_miner.py:338-350`):
+
+| Existing field | Role in the spec |
+|---|---|
+| `source_file` | Functions as the adapter's source-item identifier. Adapter defines the shape — a filesystem path for filesystem, a URI like `github.com/org/repo#pr=123` for git. MUST be stable across re-ingests of the same logical item. |
+| `source_mtime` | Functions as the source-item version for filesystem. Adapters without mtime semantics MAY omit this field and use a different version discriminator (e.g., commit SHA in a separate `metadata["commit_sha"]` field); the spec only requires that `is_current()` can decide staleness from the stored metadata. |
+| `filed_at` | When the record was written. ISO-8601 string. |
+| `added_by` | Agent name (e.g., `lumi`, `claude-code`). Orthogonal to `adapter_name` — the agent is *who* triggered mining; the adapter is *how* data was extracted. |
+| `wing`, `room`, `hall` | Palace routing. Populated by adapter per §2.5. |
+| `chunk_index` | Per §1.6. Always 0 for `whole_record` / `metadata_only`. |
+| `normalize_version` | Palace-wide schema version (currently `palace.py:50`). Unchanged. Separate from `adapter_version`. |
+| `entities` | Semicolon-joined candidate entity names. Already flat; kept flat (§5.4 replacement). |
+| `ingest_mode` | Per §1.5. Already on conversation drawers; added to filesystem drawers by the cleanup PR. |
+| `extract_mode` | Conversation-adapter-specific (`exchange` vs `general`). Moves into the conversations adapter's declared schema per §5.2. |
+
+**Nothing is renamed. Nothing is removed.** The spec formalizes the shape ingesters already converge on. Existing `where={"source_file": ...}` queries in `searcher.py`, `palace.py`, and callers keep working.
+
+**Chroma metadata constraint:** all metadata values MUST be `str | int | float | bool`. No lists, no nested dicts. This matches RFC 001 §1.4 and the underlying ChromaDB contract. Structured side-data goes to the SQLite knowledge graph (§5.5) or to a declared flat JSON-encoded string field (§5.4).
+
+### 5.2 Adapter schemas
+
+Each adapter returns an `AdapterSchema` from `describe_schema()`:
+
+```python
+@dataclass(frozen=True)
+class AdapterSchema:
+    fields: dict[str, FieldSpec]   # Keyed by metadata key.
+    version: str
+
+@dataclass(frozen=True)
+class FieldSpec:
+    type: Literal["string", "int", "float", "bool", "delimiter_joined_string", "json_string"]
+    required: bool
+    description: str
+    indexed: bool = False           # Hint to backends that can build indexes (RFC 001 §2.1).
+    # delimiter_joined_string: the delimiter character (default ";").
+    delimiter: str = ";"
+    # json_string: the JSON schema of the encoded object (informational only).
+    json_schema: dict | None = None
+```
+
+`delimiter_joined_string` covers the `entities` shape (current `;`-joined list of names). `json_string` is the escape hatch for adapters needing to pack nested data — the value stored is still a single flat `str` from Chroma's perspective, but the adapter is allowed to document its parsed shape.
+
+Example for a hypothetical `slack` adapter:
+
+```python
+AdapterSchema(
+    version="1.0",
+    fields={
+        "channel_name": FieldSpec(type="string", required=True, description="Slack channel name", indexed=True),
+        "channel_id": FieldSpec(type="string", required=True, description="Slack channel ID"),
+        "thread_ts": FieldSpec(type="string", required=False, description="Thread root timestamp"),
+        "author_id": FieldSpec(type="string", required=True, description="Slack user ID", indexed=True),
+        "author_name": FieldSpec(type="string", required=True, description="Display name at extraction time"),
+        "reactions": FieldSpec(type="delimiter_joined_string", required=False, description="Emoji shortcodes"),
+    },
+)
+```
+
+### 5.3 Enterprise keying
+
+The adapter schema is the stable surface enterprises filter on. A support team querying the palace for `channel_id = "C01234"` does not care about ChromaDB's internal representation. The schema field is declared by the adapter, indexed by the backend (RFC 001 §2.1 `supports_metadata_filters`), and exposed through the existing `where=` clause.
+
+This is how "structured data" serves company use cases without breaking transformation guarantees: declared-transformation content in the drawer, structured fields in the metadata, schema declared by the adapter, filtering done by the backend.
+
+### 5.4 Entity hints (optional)
+
+Adapters with `supports_entity_hints` MAY include:
+
+```python
+metadata["entity_hints_json"] = '[{"type":"person","name":"Milla Jovovich","confidence":0.95,"offset":120},{"type":"project","name":"MemPalace","confidence":1.0,"offset":0}]'
+```
+
+The value is a JSON-encoded string (type `json_string` in the adapter schema). Core parses on read and feeds into `mempalace/entity_detector.py` as a prior: hints with `confidence >= 0.9` bypass the heuristic detector; lower-confidence hints feed into it as candidates.
+
+This is additive to the existing flat `entities` field — entity_hints carries structure (type, confidence, offset); `entities` remains the Chroma-indexable flat string. An adapter that produces entity_hints MUST also populate `entities` as the flat name-only projection, so existing filter queries keep working.
+
+### 5.5 Knowledge-graph triples (optional)
+
+Adapters with `supports_kg_triples` write directly to the SQLite knowledge graph via `mempalace/knowledge_graph.py` — **not** to drawer metadata. Chroma cannot store structured triples; the KG already exists for this purpose.
+
+The adapter calls the existing `KnowledgeGraph.add_triple()` (signature verified against `mempalace/knowledge_graph.py:130`):
+
+```python
+palace.kg.add_triple(
+    subject="Ben",
+    predicate="committed",
+    obj="PR-567",                    # `object` is a Python builtin — the API uses `obj`.
+    valid_from="2026-03-12",
+    confidence=1.0,
+    source_file=drawer.source_file,  # Existing provenance parameter.
+)
+```
+
+Drawer metadata includes a flat counter — `metadata["kg_triples_count"]: int` — so search consumers can see at a glance that KG side-data exists for a drawer without hitting SQLite.
+
+The existing API has `source_closet` and `source_file` provenance parameters but no `source_drawer_id` or `adapter_name`. The cleanup PR (§9) should add these two optional parameters to `add_triple()` so adapter-written triples can be traced back to (a) the specific drawer that produced them and (b) the adapter that authored them — necessary for re-extraction workflows. Until that lands, adapters use `source_file` as the provenance key and record adapter authorship via a separate table or a predicate naming convention (e.g., `adapter:git:committed`).
+
+This aligns with the existing architecture in `CLAUDE.md` ("Knowledge Graph: ENTITY → PREDICATE → ENTITY with valid_from / valid_to dates") — the RFC formalizes the adapter-side write path.
+
+### 5.6 Source encoding and newline
+
+Current ingesters handle encoding lossily (`errors="replace"` in `miner.py:595` and `normalize.py:124`) and do not record original encoding. The spec does **not** require per-drawer `source_encoding` / `source_newline` — most runs are uniform UTF-8 / LF, and storing the same value on every drawer wastes bytes.
+
+Instead: adapters that handle non-UTF-8 or non-LF sources record the values once on the adapter's `SourceSummary` and per-drawer only when a specific drawer diverges from the adapter default. The `utf8_replace_invalid` declared transformation (§1.4) already communicates that lossy decoding happened; specific drawer-level provenance is opt-in.
+
+---
+
+## 6. Privacy class
+
+### 6.1 Defined levels
+
+| Level | Meaning | Example sources |
+|---|---|---|
+| `public` | Content intended for public consumption. | arXiv papers, public GitHub repos, published blogs. |
+| `internal` | Organizational content, not for public disclosure. | Corporate Slack, internal Notion, private git repos. |
+| `pii_potential` | May contain personally identifiable information. | Email, iMessage, Claude/ChatGPT transcripts. |
+| `sensitive` | Known to contain PII, financial, or health data. | Medical records, financial statements, legal filings. |
+| `secrets_possible` | May contain credentials or secrets. | Git history, environment dumps, CI logs. |
+
+An adapter declares a default on `BaseSourceAdapter.default_privacy_class`. Users MAY override per-source in config.
+
+### 6.2 Enforcement
+
+- Each palace declares a `privacy_floor`. Drawers above the floor (equal to or laxer) are admitted; drawers below are rejected at write time and surfaced in a `rejected` list on the CLI and MCP tool.
+- **Default floor: none** — v1 accepts all levels unless the palace explicitly configures a floor. This keeps the single-user local default low-friction (users who run `mempalace mine` on a git repo expect `secrets_possible` drawers to land). Enterprise deployments MUST set a floor; docs for regulated-domain setup will recommend starting strict and relaxing as needed.
+- Search results surface `privacy_class` in result metadata. MCP tool wrappers MAY redact results above a caller-declared ceiling.
+- `secrets_possible` drawers SHOULD pass through a secrets-scan pre-index hook when one is available. PR #389 (sensitive content scanner) is the expected enforcement mechanism for v1; until it lands, `secrets_possible` is a label without automated scanning. The label is still useful — it enables floor-based rejection and alerts downstream consumers.
+- The privacy class is recorded in drawer metadata and cannot be downgraded without a migration log entry, matching RFC 001's embedder-identity pattern.
+
+Privacy class is how a regulated-domain deployment (medical, legal, financial) can use MemPalace safely. Without it, flexible ingest becomes a liability; with it, ingest is scoped by policy.
+
+---
+
+## 7. Testing contract
+
+### 7.1 The abstract suite
+
+MemPalace ships `mempalace.sources.testing.AbstractSourceAdapterContractSuite` — a pytest mixin. Every adapter package ships a concrete subclass:
+
+```python
+from mempalace.sources.testing import AbstractSourceAdapterContractSuite
+
+class TestCursorAdapter(AbstractSourceAdapterContractSuite):
+    @pytest.fixture
+    def adapter(self):
+        return CursorAdapter()
+
+    @pytest.fixture
+    def fixture_source(self, tmp_path):
+        """Build a minimal Cursor workspaceStorage fixture."""
+        ...
+        return SourceRef(local_path=str(tmp_path))
+
+    @pytest.fixture
+    def canonical_source_bytes(self, fixture_source):
+        """Return a mapping of source_file -> authoritative bytes.
+
+        For filesystem sources: the file's raw bytes.
+        For SQLite sources: the extracted value column bytes for each row.
+        For API sources: the canonical HTTP response body bytes.
+
+        Adapter-defined — the adapter knows what its 'source bytes' are.
+        """
+        ...
+```
+
+The suite covers:
+
+- `ingest` yields items with stable `source_file` and well-formed `version`.
+- `is_current()` returns True when metadata matches, False when it differs.
+- `close()` releases resources; subsequent calls raise `AdapterClosedError`.
+- Unicode content and unicode identifiers are preserved end-to-end.
+- Large-source handling: 10k+ items ingest without loading all into memory.
+- Error paths: `SourceNotFoundError`, `AuthRequiredError` raise with correct types.
+- `SourceRef.options` MUST NOT contain secrets — the adapter raises if it detects a value matching a common-secret pattern (GitHub token prefix, Slack token prefix, etc.). Advisory test, not blocking.
+
+### 7.2 Byte-preserving round-trip (for `byte_preserving` adapters only)
+
+Required for adapters advertising `byte_preserving`:
+
+```python
+def test_byte_preserving_round_trip(self, adapter, fixture_source, canonical_source_bytes):
+    """Concatenated chunks must equal the canonical source bytes.
+
+    For each source_file in the fixture:
+      1. Read canonical_source_bytes[source_file].
+      2. Collect all DrawerRecords for that source_file from adapter.ingest(...).
+         Skip metadata_only drawers (§1.5).
+      3. Sort by chunk_index.
+      4. Concatenate record.content values.
+      5. Assert equality with the canonical bytes (UTF-8 decoded).
+    """
+```
+
+Failure raises `TransformationViolationError`.
+
+### 7.3 Declared-transformation round-trip (for `declared_lossy` adapters)
+
+Required for adapters with non-empty `declared_transformations`:
+
+```python
+def test_declared_transformation_round_trip(self, adapter, fixture_source, canonical_source_bytes):
+    """Adapter output must be reproducible by applying ONLY declared transformations.
+
+    1. For each source_file, read canonical_source_bytes.
+    2. Apply each declared transformation in declared_transformations to the bytes,
+       in the order declared by the adapter, using the reference implementations
+       in mempalace.sources.transforms.
+    3. Compare the result to the concatenated record.content values.
+    4. If they differ, the adapter has applied a transformation it did not declare.
+       Raise TransformationViolationError.
+    """
+```
+
+For transformations not in the reserved list (§1.4) — adapter-custom names — the adapter MUST provide a reference implementation callable under `mempalace.sources.transforms.<adapter_name>_<transform_name>`. The conformance suite imports and applies it. Undiscoverable custom transforms fail the test.
+
+### 7.4 Schema conformance
+
+A generator-based property test validates that every record yielded by `ingest` across the fixture source has metadata matching `describe_schema()`. Missing required fields, wrong types, or (in strict mode) undeclared fields fail the test.
+
+### 7.5 Note on current corpus
+
+No existing test in `tests/` asserts byte-preservation or declared-transformation correctness (verified via grep of `tests/` for `verbatim|byte.?preserv|round.?trip`). This RFC's conformance suite introduces the first such coverage. The existing MISSION.md claim of "verbatim always" is a social contract until this lands; afterward it becomes a machine-verified property of adapters that declare `byte_preserving`.
+
+---
+
+## 8. Versioning and compatibility
+
+- `BaseSourceAdapter.spec_version` declares which spec version an adapter implements.
+- MemPalace refuses to load an adapter declaring a different major spec version.
+- Minor spec versions are additive: new optional methods, new capability tokens, new reserved transformation names, new universal metadata fields with sensible defaults.
+- Adapters MAY declare their own `adapter_version` independent of the spec version; this is recorded on every drawer (§5.1) and enables "this drawer was extracted by cursor-adapter 0.3; 0.4 fixed a parsing bug; re-extract affected drawers" workflows.
+- This is spec v1.0.
+
+---
+
+## 9. Cleanup prerequisite (not in this spec, but gating)
+
+The existing in-tree ingesters are not adapter-shaped. Before RFC 002 can be enforced, the following refactor lands in a separate PR:
+
+- Introduce `mempalace/sources/base.py` defining `BaseSourceAdapter`, the typed records, and the registry.
+- Introduce `mempalace/sources/transforms.py` with reference implementations of every reserved transformation in §1.4. Adapters and the conformance suite both consume these.
+- `mempalace/miner.py` → `mempalace/sources/filesystem.py` implementing `BaseSourceAdapter`. Current behavior preserved: 800-char chunking becomes the adapter's default; `READABLE_EXTENSIONS` moves to the adapter; `detect_room()` and `detect_hall()` move to the adapter per §2.5. `declared_transformations = frozenset({"utf8_replace_invalid", "whitespace_trim"})`.
+- `mempalace/convo_miner.py` → `mempalace/sources/conversations.py`. Exchange-pair chunking stays. The format-detection logic in `normalize.py` becomes per-format plugins the conversations adapter composes (one for Claude Code JSONL, one for Codex JSONL, one for ChatGPT mapping trees, one for Claude.ai JSON, one for Slack JSON) — each small and independently testable, eliminating the `if source_type` chain. `declared_transformations` enumerates every transformation `normalize.py` and `convo_miner._chunk_by_exchange` actually perform (see §1.4 "Existing code mapping").
+- Closet-building wired into the conversations adapter's post-step (currently missing, per §1.7) — side effect of routing through the unified core post-step.
+- `mempalace/cli.py` subcommand `mine` routes through the `mempalace.sources` registry. `--mode {projects,convos}` becomes a deprecated alias for `--source {filesystem,conversations}`.
+- `mempalace/mcp_server.py` `mempalace_mine` tool accepts a `source` parameter.
+- `mempalace/palace.py` exposes `PalaceContext` — a per-mine-invocation facade that bundles the drawer collection, closet collection, knowledge graph, palace config, and progress hooks. Adapters receive this; they do not import `palace.py` directly.
+- `NORMALIZE_VERSION` (currently a module-level constant in `palace.py:50`) stays. It is the palace-wide schema version, orthogonal to per-adapter `adapter_version`.
+- `KnowledgeGraph.add_triple()` (`knowledge_graph.py:130`) gains two optional parameters: `source_drawer_id: str = None` and `adapter_name: str = None`. Existing callers are unaffected; adapters advertising `supports_kg_triples` (§5.5) populate both. Backwards-compatible change.
+
+This cleanup is substantial — comparable to RFC 001 §10's chroma-import removal — and should land before any new third-party adapter PR merges. Each new adapter is easier after the cleanup, not harder.
+
+---
+
+## 10. Impact on in-flight PRs
+
+| PR / Issue | Effort to align |
+|---|---|
+| [#274](https://github.com/MemPalace/mempalace/issues/274) Cursor SQLite | Becomes `mempalace-source-cursor` third-party package. Author has a working prototype on Windows; needs `describe_schema()`, `declared_transformations`, and the conformance suite. Prior #287 (closed unmerged) is predecessor work. |
+| [#23](https://github.com/MemPalace/mempalace/pull/23) OpenCode SQLite | Becomes `mempalace-source-opencode`. Same shape as Cursor. |
+| [#169](https://github.com/MemPalace/mempalace/pull/169) Pi agent | Becomes `mempalace-source-pi` or a format plugin under the conversations adapter (depending on format similarity). |
+| [#232](https://github.com/MemPalace/mempalace/pull/232) Cursor JSONL | Deprecated in favor of #274's SQLite path; or a second mode of `mempalace-source-cursor`. |
+| [#567](https://github.com/MemPalace/mempalace/pull/567), [#98](https://github.com/MemPalace/mempalace/pull/98) git-mine | Closest existing work to what the spec envisions. Becomes first-party `mempalace/sources/git.py`. Exercises `whole_record` mode, `supports_structured_metadata`, `supports_closet_hints` (decision-signal quotes), `supports_kg_triples` (commit authorship, PR review relationships). |
+| [#591](https://github.com/MemPalace/mempalace/pull/591), [#592](https://github.com/MemPalace/mempalace/pull/592) Delphi Oracle | Deferred. The live-stream pattern is out of scope for v1 (§Non-goals). A v1.1 addition will specify webhook/stream adapters. |
+| [#702](https://github.com/MemPalace/mempalace/pull/702) Cursor + factory.ai | Splits into two adapter packages. |
+| [#981](https://github.com/MemPalace/mempalace/issues/981) path-level descriptions | Absorbed by §1.5 `metadata_only` mode + §5.1 `ingest_mode`. A new first-party `descriptions` adapter or a second mode on `filesystem`. |
+| [#244](https://github.com/MemPalace/mempalace/pull/244) Cursor memory-first MCP workflow docs | Points at `mempalace-source-cursor` once the adapter lands. |
+| [#419](https://github.com/MemPalace/mempalace/pull/419), [#300](https://github.com/MemPalace/mempalace/pull/300), [#952](https://github.com/MemPalace/mempalace/pull/952) language-extension additions to `READABLE_EXTENSIONS` | Becomes per-language config on the filesystem adapter. Contributors can publish domain-specific adapters without touching core. |
+| [#389](https://github.com/MemPalace/mempalace/pull/389) sensitive content scanner | Expected enforcement mechanism for the `secrets_possible` privacy class (§6.2). Not a blocker for this spec, but a natural consumer. |
+| [#434](https://github.com/MemPalace/mempalace/pull/434) auto-populate KG from drawers | Complementary: post-hoc derivation of KG triples from drawer content. Adapters with `supports_kg_triples` provide the up-front path; #434 handles everything else. |
+
+---
+
+## 11. Open questions
+
+1. **Cross-adapter dedup.** When a PR body is mined via `git` AND shows up as a conversation quote mined via `claude-code`, both drawers land. Is query-time dedup in `searcher.py` sufficient, or should core maintain a content-hash index across adapters? Declared non-goal in v1 but worth revisiting if user feedback demands it.
+2. **Live-stream pattern.** Delphi Oracle (#591/592) and potentially Slack/Discord real-time ingestion need a push-mode contract. This is a v1.1 addition (streaming adapter trait + webhook surface), not blocking.
+3. **LLM-assisted structured extraction.** Some adapters will want to call an LLM to extract structured fields. The spec does not standardize this — should it? Argument for: conformance test for LLM-driven fields, consistent caching. Argument against: local-first / zero-API is a core promise; LLM dependencies are opt-in per adapter.
+4. **Adapter-vs-format split for conversations.** §9 proposes format plugins composed under a single conversations adapter. Alternative: one adapter per format (claude-code, chatgpt, codex, cursor-jsonl, slack). The trade-off is discoverability (one adapter is easier to find) vs. encapsulation (format plugins are simpler to test). Preference leans toward the single-adapter + plugin model; open to counter-argument.
+5. **Default `privacy_floor`.** v1 defaults to none (§6.2) so single-user local mining is frictionless. An argument exists for defaulting to `pii_potential` — forces regulated-domain users to opt in to sensitive levels rather than opt out. Open to changing the default before v1 ships.
+6. **`canonical_source_bytes` for API-backed adapters.** §7.1 defines this as adapter-declared. For API-backed adapters (Slack, Notion), what constitutes "canonical bytes" in a conformance test — the fixture's captured HTTP response? A serialized representation of the parsed object? Leaves to the adapter; may need a follow-up spec for common conventions.
+7. **`adapter_version` bump semantics.** When does an adapter bump `adapter_version`? On any behavior change? On declared-transformation changes only? Suggests a follow-up doc on adapter SemVer conventions for the community to agree on.
+
+---
+
+## 12. Rollout
+
+1. Land the cleanup PR (§9): introduce `mempalace/sources/`, refactor `miner.py` → filesystem adapter, `convo_miner.py` → conversations adapter, route CLI and MCP through the sources registry. Behavior preserved end-to-end. Closets get built for conversation drawers as a side effect.
+2. Land this spec as-is. Add `AbstractSourceAdapterContractSuite`, entry-point discovery, `AdapterSchema` validation, privacy-class enforcement (floor-gated writes), declared-transformation reference implementations in `mempalace/sources/transforms.py`.
+3. Land `mempalace/sources/git.py` as the first-party adapter absorbing #567. Exercises `whole_record`, `supports_structured_metadata`, `supports_closet_hints`, `supports_kg_triples` together.
+4. Encourage the Cursor (#274), OpenCode (#23), and Pi (#169) authors to publish as third-party packages under `mempalace-source-*`. Offer review help against the spec.
+5. Publish adapter-authoring docs at [mempalaceofficial.com/guide/authoring-sources](https://mempalaceofficial.com/guide/authoring-sources.html).
+6. Update [ROADMAP.md](../../ROADMAP.md) with spec v1.0 adoption under v4.0.0-alpha.

examples/HOOKS_TUTORIAL.md

@@ -25,4 +25,27 @@ Add this to your configuration file to enable automatic background saving:
       }
     ]
   }
-}
+}
+```
+
+### 3. What changed (v3.1.0+)
+
+Both hooks now have **two-layer capture**:
+
+1. **Auto-mine**: Before blocking the AI, the hook runs the normalizer on the JSONL transcript and upserts chunks directly into the palace. This captures raw tool output (Bash results, search findings, build errors) that the AI would otherwise summarize away.
+
+2. **Updated reason messages**: The block reason now explicitly tells the AI to save tool output verbatim — not just topics and decisions.
+
+### 4. Backfill past conversations (one-time)
+
+The hooks capture conversations going forward, but you probably have months of past sessions. Run this once to mine them all:
+
+```bash
+mempalace mine ~/.claude/projects/ --mode convos
+```
+
+### 5. Configuration
+
+- **`SAVE_INTERVAL=15`** — How many human messages between saves
+- **`MEMPALACE_PYTHON`** — Python interpreter with mempalace + chromadb. Auto-detects: env var → repo venv → system python3
+- **`MEMPAL_DIR`** — Optional directory for auto-ingest via `mempalace mine`

examples/mcp_setup.md

@@ -5,13 +5,13 @@
 Run the MCP server:
 
 ```bash
-python -m mempalace.mcp_server
+mempalace-mcp
 ```
 
 Or add it to Claude Code:
 
 ```bash
-claude mcp add mempalace -- python -m mempalace.mcp_server
+claude mcp add mempalace -- mempalace-mcp
 ```
 
 ## Available Tools

hooks/README.md

@@ -6,10 +6,10 @@ These hook scripts make MemPalace save automatically. No manual "save" commands
 
 | Hook | When It Fires | What Happens |
 |------|--------------|-------------|
-| **Save Hook** | Every 15 human messages | Blocks the AI, tells it to save key topics/decisions/quotes to the palace |
-| **PreCompact Hook** | Right before context compaction | Emergency save — forces the AI to save EVERYTHING before losing context |
+| **Save Hook** | Every 15 human messages | Auto-mines transcript (tool output included), then blocks the AI to save topics/decisions/quotes |
+| **PreCompact Hook** | Right before context compaction | Auto-mines transcript, then emergency save — forces the AI to save EVERYTHING before losing context |
 
-The AI does the actual filing — it knows the conversation context, so it classifies memories into the right wings/halls/closets. The hooks just tell it WHEN to save.
+**Two-layer capture:** Hooks auto-mine the JSONL transcript directly into the palace (capturing raw tool output — Bash results, search findings, build errors). They also block the AI with a reason message telling it to save verbatim tool output and key context. Belt and suspenders — tool output gets stored even if the AI summarizes instead of quoting.
 
 ## Install — Claude Code
 
@@ -68,6 +68,7 @@ Edit `mempal_save_hook.sh` to change:
 - **`SAVE_INTERVAL=15`** — How many human messages between saves. Lower = more frequent saves, higher = less interruption.
 - **`STATE_DIR`** — Where hook state is stored (defaults to `~/.mempalace/hook_state/`)
 - **`MEMPAL_DIR`** — Optional. Set to a conversations directory to auto-run `mempalace mine <dir>` on each save trigger. Leave blank (default) to let the AI handle saving via the block reason message.
+- **`MEMPALACE_PYTHON`** — Optional env var. Python interpreter with mempalace + chromadb installed. Auto-detects: `MEMPALACE_PYTHON` env var → repo `venv/bin/python3` → system `python3`. Set this if your venv is in a non-standard location.
 
 ### mempalace CLI
 
@@ -91,15 +92,19 @@ User sends message → AI responds → Claude Code fires Stop hook
                                             ↓
                               ┌─── < 15 since last save ──→ echo "{}" (let AI stop)
                               │
-                              └─── ≥ 15 since last save ──→ {"decision": "block", "reason": "save..."}
-                                                                    ↓
-                                                            AI saves to palace
-                                                                    ↓
-                                                            AI tries to stop again
-                                                                    ↓
-                                                            stop_hook_active = true
-                                                                    ↓
-                                                            Hook sees flag → echo "{}" (let it through)
+                              └─── ≥ 15 since last save
+                                            ↓
+                                    Auto-mine transcript → palace (tool output captured)
+                                            ↓
+                                    {"decision": "block", "reason": "save tool output verbatim..."}
+                                            ↓
+                                    AI saves to palace (topics, decisions, quotes)
+                                            ↓
+                                    AI tries to stop again
+                                            ↓
+                                    stop_hook_active = true
+                                            ↓
+                                    Hook sees flag → echo "{}" (let it through)
 ```
 
 The `stop_hook_active` flag prevents infinite loops: block once → AI saves → tries to stop → flag is true → we let it through.
@@ -109,14 +114,18 @@ The `stop_hook_active` flag prevents infinite loops: block once → AI saves →
 ```
 Context window getting full → Claude Code fires PreCompact
                                         ↓
-                                Hook ALWAYS blocks
+                                Find transcript (from input or session_id lookup)
+                                        ↓
+                                Auto-mine transcript → palace (tool output captured)
+                                        ↓
+                                {"decision": "block", "reason": "save tool output verbatim..."}
                                         ↓
                                 AI saves everything
                                         ↓
                                 Compaction proceeds
 ```
 
-No counting needed — compaction always warrants a save.
+No counting needed — compaction always warrants a save. The auto-mine captures raw tool output before the AI gets a chance to summarize it away.
 
 ## Debugging
 
@@ -137,6 +146,36 @@ Example output:
 
 **Hooks require session restart after install.** Claude Code loads hooks from `settings.json` at session start only. If you run `mempalace init` or manually edit hook config mid-session, the hooks won't fire until you restart Claude Code. This is a Claude Code limitation.
 
+**`MEMPAL_PYTHON` override for the hook's internal Python calls.** The save hook parses its JSON input and counts transcript messages with `python3`. When the harness is launched from a GUI on macOS — `open -a`, Spotlight, the dock — its `PATH` is the minimal `/usr/bin:/bin:/usr/sbin:/sbin` inherited from `launchd`, not your shell PATH. If `python3` isn't on that PATH, those internal calls fail and the hook can't count exchanges.
+
+Point the hook at any Python 3 interpreter to fix it:
+
+```bash
+export MEMPAL_PYTHON="/usr/bin/python3"                   # system Python is fine
+export MEMPAL_PYTHON="$HOME/.venvs/mempalace/bin/python"  # or your venv
+```
+
+Resolution priority: `$MEMPAL_PYTHON` (if set and executable) → `$(command -v python3)` → bare `python3`. The interpreter only needs `json` and `sys` from the standard library — `mempalace` itself does not need to be installed in it.
+
+Note: the `mempalace mine` auto-ingest runs via the `mempalace` CLI, so that command also needs to be on the hook's `PATH`. Installing with `pipx install mempalace` or `uv tool install mempalace` puts it on a stable global location; otherwise extend the hook environment's `PATH` to include your venv's `bin/`.
+
+## Backfill Past Conversations
+
+The hooks only capture conversations going forward. To mine **past** Claude Code sessions into your palace, run a one-time backfill:
+
+```bash
+mempalace mine ~/.claude/projects/ --mode convos
+```
+
+This scans all JSONL transcripts from previous sessions and files them into the `conversations` wing. On a typical developer machine with months of history, this can yield 50K–200K drawers.
+
+For Codex CLI sessions:
+```bash
+mempalace mine ~/.codex/sessions/ --mode convos
+```
+
+This only needs to be done once — after that, the hooks auto-mine each session as you go.
+
 ## Cost
 
 **Zero extra tokens.** The hooks notify the AI that saves happened in the background — the AI doesn't need to write anything in the chat. All filing is handled automatically. Previous versions asked the AI to write diary entries and drawer content in the chat window, which cost ~$1/session in retransmitted tokens.

hooks/mempal_precompact_hook.sh

@@ -54,10 +54,17 @@ mkdir -p "$STATE_DIR"
 # Leave empty to skip auto-ingest (AI handles saving via the block reason).
 MEMPAL_DIR=""
 
+# Resolve the Python interpreter. Same contract as mempal_save_hook.sh:
+# MEMPAL_PYTHON (explicit override) → $(command -v python3) → bare python3.
+MEMPAL_PYTHON_BIN="${MEMPAL_PYTHON:-}"
+if [ -z "$MEMPAL_PYTHON_BIN" ] || [ ! -x "$MEMPAL_PYTHON_BIN" ]; then
+    MEMPAL_PYTHON_BIN="$(command -v python3 2>/dev/null || echo python3)"
+fi
+
 # Read JSON input from stdin
 INPUT=$(cat)
 
-SESSION_ID=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('session_id','unknown'))" 2>/dev/null)
+SESSION_ID=$(echo "$INPUT" | "$MEMPAL_PYTHON_BIN" -c "import sys,json; print(json.load(sys.stdin).get('session_id','unknown'))" 2>/dev/null)
 
 echo "[$(date '+%H:%M:%S')] PRE-COMPACT triggered for session $SESSION_ID" >> "$STATE_DIR/hook.log"
 
@@ -65,13 +72,9 @@ echo "[$(date '+%H:%M:%S')] PRE-COMPACT triggered for session $SESSION_ID" >> "$
 if [ -n "$MEMPAL_DIR" ] && [ -d "$MEMPAL_DIR" ]; then
     SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
     REPO_DIR="$(dirname "$SCRIPT_DIR")"
-    python3 -m mempalace mine "$MEMPAL_DIR" >> "$STATE_DIR/hook.log" 2>&1
+    mempalace mine "$MEMPAL_DIR" >> "$STATE_DIR/hook.log" 2>&1
 fi
 
-# Notify — compaction is about to happen but filing is handled in background
-cat << 'HOOKJSON'
-{
-  "decision": "allow",
-  "reason": "MemPalace pre-compaction save. Your full conversation has been saved verbatim in the background — no action needed. Compaction can proceed safely."
-}
-HOOKJSON
+# Silent: return empty JSON to not block. "decision": "allow" is invalid —
+# only "block" or {} are recognized.
+echo '{}'

hooks/mempal_save_hook.sh

@@ -61,19 +61,39 @@ mkdir -p "$STATE_DIR"
 # Leave empty to skip auto-ingest (AI handles saving via the block reason).
 MEMPAL_DIR=""
 
+# Resolve the Python interpreter the hook should use.
+#
+# Why this is nontrivial: GUI-launched Claude Code on macOS (or any harness
+# that doesn't inherit the user's shell PATH) may find a `python3` on PATH
+# that lacks mempalace — e.g. /usr/bin/python3 while the user installed
+# mempalace into a venv or pyenv. Users in that situation can point the
+# hook at the right interpreter by exporting MEMPAL_PYTHON.
+#
+# Resolution order (first hit wins):
+#   1. $MEMPAL_PYTHON          — explicit user override (absolute path)
+#   2. $(command -v python3)   — first python3 on the hook's PATH
+#   3. bare "python3"          — last-resort fallback (hope the PATH has it)
+MEMPAL_PYTHON_BIN="${MEMPAL_PYTHON:-}"
+if [ -z "$MEMPAL_PYTHON_BIN" ] || [ ! -x "$MEMPAL_PYTHON_BIN" ]; then
+    MEMPAL_PYTHON_BIN="$(command -v python3 2>/dev/null || echo python3)"
+fi
+
 # Read JSON input from stdin
 INPUT=$(cat)
 
 # Parse all fields in a single Python call (3x faster than separate invocations)
-eval $(echo "$INPUT" | python3 -c "
-import sys, json
+# SECURITY: All values are sanitized before being interpolated into shell assignments.
+# stop_hook_active is coerced to a strict True/False to prevent command injection via eval.
+eval $(echo "$INPUT" | "$MEMPAL_PYTHON_BIN" -c "
+import sys, json, re
 data = json.load(sys.stdin)
 sid = data.get('session_id', 'unknown')
-sha = data.get('stop_hook_active', False)
+sha_raw = data.get('stop_hook_active', False)
 tp = data.get('transcript_path', '')
 # Shell-safe output — only allow alphanumeric, underscore, hyphen, slash, dot, tilde
-import re
 safe = lambda s: re.sub(r'[^a-zA-Z0-9_/.\-~]', '', str(s))
+# Coerce stop_hook_active to strict boolean string
+sha = 'True' if sha_raw is True or str(sha_raw).lower() in ('true', '1', 'yes') else 'False'
 print(f'SESSION_ID=\"{safe(sid)}\"')
 print(f'STOP_HOOK_ACTIVE=\"{sha}\"')
 print(f'TRANSCRIPT_PATH=\"{safe(tp)}\"')
@@ -92,7 +112,7 @@ fi
 # Count human messages in the JSONL transcript
 # SECURITY: Pass transcript path as sys.argv to avoid shell injection via crafted paths
 if [ -f "$TRANSCRIPT_PATH" ]; then
-    EXCHANGE_COUNT=$(python3 - "$TRANSCRIPT_PATH" <<'PYEOF'
+    EXCHANGE_COUNT=$("$MEMPAL_PYTHON_BIN" - "$TRANSCRIPT_PATH" <<'PYEOF'
 import json, sys
 count = 0
 with open(sys.argv[1]) as f:
@@ -118,7 +138,11 @@ fi
 LAST_SAVE_FILE="$STATE_DIR/${SESSION_ID}_last_save"
 LAST_SAVE=0
 if [ -f "$LAST_SAVE_FILE" ]; then
-    LAST_SAVE=$(cat "$LAST_SAVE_FILE")
+    LAST_SAVE_RAW=$(cat "$LAST_SAVE_FILE")
+    # SECURITY: Validate as plain integer before arithmetic to prevent command injection
+    if [[ "$LAST_SAVE_RAW" =~ ^[0-9]+$ ]]; then
+        LAST_SAVE="$LAST_SAVE_RAW"
+    fi
 fi
 
 SINCE_LAST=$((EXCHANGE_COUNT - LAST_SAVE))
@@ -133,24 +157,37 @@ if [ "$SINCE_LAST" -ge "$SAVE_INTERVAL" ] && [ "$EXCHANGE_COUNT" -gt 0 ]; then
 
     echo "[$(date '+%H:%M:%S')] TRIGGERING SAVE at exchange $EXCHANGE_COUNT" >> "$STATE_DIR/hook.log"
 
-    # Optional: run mempalace ingest in background if MEMPAL_DIR is set
+    # Auto-mine the transcript. Two paths:
+    # 1. TRANSCRIPT_PATH (from Claude Code) — mine the directory it lives in
+    # 2. MEMPAL_DIR (user-configured) — mine that directory
+    # At least one should work. If neither is set, nothing mines.
+    MINE_DIR=""
+    if [ -n "$TRANSCRIPT_PATH" ] && [ -f "$TRANSCRIPT_PATH" ]; then
+        MINE_DIR="$(dirname "$TRANSCRIPT_PATH")"
+    fi
     if [ -n "$MEMPAL_DIR" ] && [ -d "$MEMPAL_DIR" ]; then
-        SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-        REPO_DIR="$(dirname "$SCRIPT_DIR")"
-        python3 -m mempalace mine "$MEMPAL_DIR" >> "$STATE_DIR/hook.log" 2>&1 &
+        MINE_DIR="$MEMPAL_DIR"
+    fi
+    if [ -n "$MINE_DIR" ]; then
+        mempalace mine "$MINE_DIR" >> "$STATE_DIR/hook.log" 2>&1 &
     fi
 
-    # Notify the AI that a checkpoint happened — but do NOT ask it to write
-    # anything in chat. All filing happens in the background via the pipeline.
-    # The old version asked the agent to write diary entries, add drawers, and
-    # add KG triples in the chat window — that cost ~$1/session in retransmitted
-    # tokens and cluttered the conversation.
-    cat << 'HOOKJSON'
+    # MEMPAL_VERBOSE toggle:
+    #   true  = developer mode — block and show diaries/code in chat
+    #   false = silent mode (default) — save in background, no chat clutter
+    # Set via: export MEMPAL_VERBOSE=true
+    if [ "$MEMPAL_VERBOSE" = "true" ] || [ "$MEMPAL_VERBOSE" = "1" ]; then
+        cat << 'HOOKJSON'
 {
-  "decision": "allow",
-  "reason": "MemPalace auto-save checkpoint. Your conversation is being saved verbatim in the background — no action needed from you. Continue working."
+  "decision": "block",
+  "reason": "MemPalace save checkpoint. Write a brief session diary entry covering key topics, decisions, and code changes since the last save. Use verbatim quotes where possible. Continue after saving."
 }
 HOOKJSON
+    else
+        # Silent mode: return empty JSON to not block. "decision": "allow" is
+        # not a valid value — only "block" or {} are recognized.
+        echo '{}'
+    fi
 else
     # Not time yet — let the AI stop normally
     echo "{}"

mempalace/__init__.py

@@ -4,10 +4,10 @@ import logging
 
 from .version import __version__  # noqa: E402
 
-# ChromaDB 0.6.x ships a Posthog telemetry client whose capture() signature is
-# incompatible with the bundled posthog library, producing noisy stderr warnings
-# on every client operation ("Failed to send telemetry event … capture() takes
-# 1 positional argument but 3 were given").  Silence just that logger.
+# chromadb telemetry: posthog capture() was broken in 0.6.x causing noisy stderr
+# warnings ("capture() takes 1 positional argument but 3 were given"). In 1.x the
+# posthog client is a no-op stub, so this is now harmless — kept as a guard in
+# case future chromadb versions re-introduce real telemetry calls.
 logging.getLogger("chromadb.telemetry.product.posthog").setLevel(logging.CRITICAL)
 
 # NOTE: the previous block set ``ORT_DISABLE_COREML=1`` on macOS arm64 as a

mempalace/backends/__init__.py

@@ -1,6 +1,64 @@
-"""Storage backend implementations for MemPalace."""
+"""Storage backend implementations for MemPalace (RFC 001).
 
-from .base import BaseCollection
+Public surface:
+
+* :class:`BaseCollection` — per-collection read/write contract.
+* :class:`BaseBackend` — per-palace factory contract.
+* :class:`PalaceRef` — value object identifying a palace for a backend.
+* :class:`QueryResult` / :class:`GetResult` — typed read returns.
+* Error classes: :class:`PalaceNotFoundError`, :class:`BackendClosedError`,
+  :class:`UnsupportedFilterError`, :class:`DimensionMismatchError`,
+  :class:`EmbedderIdentityMismatchError`.
+* Registry: :func:`get_backend`, :func:`register`, :func:`available_backends`,
+  :func:`resolve_backend_for_palace`.
+* In-tree Chroma default: :class:`ChromaBackend`, :class:`ChromaCollection`.
+"""
+
+from .base import (
+    BackendClosedError,
+    BackendError,
+    BaseBackend,
+    BaseCollection,
+    DimensionMismatchError,
+    EmbedderIdentityMismatchError,
+    GetResult,
+    HealthStatus,
+    PalaceNotFoundError,
+    PalaceRef,
+    QueryResult,
+    UnsupportedFilterError,
+)
 from .chroma import ChromaBackend, ChromaCollection
+from .registry import (
+    available_backends,
+    get_backend,
+    get_backend_class,
+    register,
+    reset_backends,
+    resolve_backend_for_palace,
+    unregister,
+)
 
-__all__ = ["BaseCollection", "ChromaBackend", "ChromaCollection"]
+__all__ = [
+    "BackendClosedError",
+    "BackendError",
+    "BaseBackend",
+    "BaseCollection",
+    "ChromaBackend",
+    "ChromaCollection",
+    "DimensionMismatchError",
+    "EmbedderIdentityMismatchError",
+    "GetResult",
+    "HealthStatus",
+    "PalaceNotFoundError",
+    "PalaceRef",
+    "QueryResult",
+    "UnsupportedFilterError",
+    "available_backends",
+    "get_backend",
+    "get_backend_class",
+    "register",
+    "reset_backends",
+    "resolve_backend_for_palace",
+    "unregister",
+]

mempalace/backends/base.py

@@ -1,44 +1,370 @@
-"""Abstract collection interface for MemPalace storage backends."""
+"""Storage backend contract for MemPalace (RFC 001).
+
+This module defines the surface every storage backend must implement:
+
+* ``BaseCollection`` — the per-collection read/write interface, kwargs-only.
+* ``BaseBackend`` — the per-palace factory, addressed by ``PalaceRef``.
+* ``QueryResult`` / ``GetResult`` — typed result dataclasses that replace the
+  Chroma dict shape as the canonical return type.
+* Error classes + ``HealthStatus`` — uniform across backends.
+
+This is the v1 cleanup from RFC 001 §10: full typed results, ``PalaceRef``,
+registry-ready ABC. Embedder injection, maintenance hooks, and the full
+conformance suite land in follow-up PRs.
+"""
 
 from abc import ABC, abstractmethod
-from typing import Any, Dict, List, Optional
+from dataclasses import dataclass
+from typing import ClassVar, Optional
+
+
+# ---------------------------------------------------------------------------
+# Errors
+# ---------------------------------------------------------------------------
+
+
+class BackendError(Exception):
+    """Base class for every storage-backend error raised by core."""
+
+
+class PalaceNotFoundError(BackendError, FileNotFoundError):
+    """Raised when ``get_collection(create=False)`` is called on a missing palace.
+
+    Subclass of ``FileNotFoundError`` so legacy callers that catch the latter
+    (pre-#413 seam) keep working unchanged.
+    """
+
+
+class BackendClosedError(BackendError):
+    """Raised when a backend method is called after ``close()``."""
+
+
+class UnsupportedFilterError(BackendError):
+    """Raised when a where-clause uses an operator the backend does not implement.
+
+    Silent dropping of unknown operators is forbidden by spec (RFC 001 §1.4).
+    """
+
+
+class DimensionMismatchError(BackendError):
+    """Raised when the embedding dimension on write does not match the collection."""
+
+
+class EmbedderIdentityMismatchError(BackendError):
+    """Raised when the stored embedder model name differs from the current one."""
+
+
+# ---------------------------------------------------------------------------
+# Value objects
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class PalaceRef:
+    """A handle to a palace, consumed by backends.
+
+    ``id`` is always present and is the key backends use to cache handles.
+    ``local_path`` is populated for filesystem-rooted palaces.
+    ``namespace`` is used by server-mode backends for tenant / prefix routing.
+    """
+
+    id: str
+    local_path: Optional[str] = None
+    namespace: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class HealthStatus:
+    ok: bool
+    detail: str = ""
+
+    @classmethod
+    def healthy(cls, detail: str = "") -> "HealthStatus":
+        return cls(ok=True, detail=detail)
+
+    @classmethod
+    def unhealthy(cls, detail: str) -> "HealthStatus":
+        return cls(ok=False, detail=detail)
+
+
+_TYPED_RESULT_FIELDS = ("ids", "documents", "metadatas", "distances", "embeddings")
+
+
+class _DictCompatMixin:
+    """Transitional dict-protocol access for typed results.
+
+    RFC 001 §1.3 spec is attribute access (``result.ids``). The ``result["ids"]``
+    and ``result.get("ids")`` forms are retained as a migration shim for callers
+    that predate the typed interface and are scheduled for removal in a follow-
+    up cleanup. New code MUST use attribute access.
+    """
+
+    def __getitem__(self, key: str):
+        if key in _TYPED_RESULT_FIELDS:
+            return getattr(self, key)
+        raise KeyError(key)
+
+    def get(self, key: str, default=None):
+        if key in _TYPED_RESULT_FIELDS:
+            val = getattr(self, key, default)
+            return default if val is None else val
+        return default
+
+    def __contains__(self, key: object) -> bool:
+        return key in _TYPED_RESULT_FIELDS and getattr(self, key, None) is not None
+
+
+@dataclass(frozen=True)
+class QueryResult(_DictCompatMixin):
+    """Typed return from ``BaseCollection.query``.
+
+    Outer list dimension = number of query vectors / texts.
+    Inner list dimension = hits per query (may be zero).
+
+    Fields not in ``include=`` at the call site are populated with empty lists
+    of the correct outer shape (never ``None``), except ``embeddings`` which
+    is ``None`` when not requested.
+    """
+
+    ids: list[list[str]]
+    documents: list[list[str]]
+    metadatas: list[list[dict]]
+    distances: list[list[float]]
+    embeddings: Optional[list[list[list[float]]]] = None
+
+    @classmethod
+    def empty(cls, num_queries: int = 1, embeddings_requested: bool = False) -> "QueryResult":
+        """Construct an all-empty result preserving outer dimension.
+
+        When ``embeddings_requested`` is True, ``embeddings`` preserves the outer
+        query dimension with empty hit lists (matching the spec's rule that fields
+        requested via ``include=`` carry the outer shape even when empty). When
+        False, ``embeddings`` stays ``None`` to signal the field was not requested.
+        """
+        empty_outer = [[] for _ in range(num_queries)]
+        return cls(
+            ids=[[] for _ in range(num_queries)],
+            documents=[[] for _ in range(num_queries)],
+            metadatas=[[] for _ in range(num_queries)],
+            distances=[[] for _ in range(num_queries)],
+            embeddings=empty_outer if embeddings_requested else None,
+        )
+
+
+@dataclass(frozen=True)
+class GetResult(_DictCompatMixin):
+    """Typed return from ``BaseCollection.get``."""
+
+    ids: list[str]
+    documents: list[str]
+    metadatas: list[dict]
+    embeddings: Optional[list[list[float]]] = None
+
+    @classmethod
+    def empty(cls) -> "GetResult":
+        return cls(ids=[], documents=[], metadatas=[], embeddings=None)
+
+
+# ---------------------------------------------------------------------------
+# Collection contract
+# ---------------------------------------------------------------------------
 
 
 class BaseCollection(ABC):
-    """Smallest collection contract the rest of MemPalace relies on."""
+    """Per-collection read/write surface every backend must implement."""
 
     @abstractmethod
     def add(
         self,
         *,
-        documents: List[str],
-        ids: List[str],
-        metadatas: Optional[List[Dict[str, Any]]] = None,
-    ) -> None:
-        raise NotImplementedError
+        documents: list[str],
+        ids: list[str],
+        metadatas: Optional[list[dict]] = None,
+        embeddings: Optional[list[list[float]]] = None,
+    ) -> None: ...
 
     @abstractmethod
     def upsert(
         self,
         *,
-        documents: List[str],
-        ids: List[str],
-        metadatas: Optional[List[Dict[str, Any]]] = None,
+        documents: list[str],
+        ids: list[str],
+        metadatas: Optional[list[dict]] = None,
+        embeddings: Optional[list[list[float]]] = None,
+    ) -> None: ...
+
+    @abstractmethod
+    def query(
+        self,
+        *,
+        query_texts: Optional[list[str]] = None,
+        query_embeddings: Optional[list[list[float]]] = None,
+        n_results: int = 10,
+        where: Optional[dict] = None,
+        where_document: Optional[dict] = None,
+        include: Optional[list[str]] = None,
+    ) -> QueryResult: ...
+
+    @abstractmethod
+    def get(
+        self,
+        *,
+        ids: Optional[list[str]] = None,
+        where: Optional[dict] = None,
+        where_document: Optional[dict] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        include: Optional[list[str]] = None,
+    ) -> GetResult: ...
+
+    @abstractmethod
+    def delete(
+        self,
+        *,
+        ids: Optional[list[str]] = None,
+        where: Optional[dict] = None,
+    ) -> None: ...
+
+    @abstractmethod
+    def count(self) -> int: ...
+
+    # ------------------------------------------------------------------
+    # Optional methods with ABC defaults (spec §1.2)
+    # ------------------------------------------------------------------
+
+    def estimated_count(self) -> int:
+        return self.count()
+
+    def close(self) -> None:
+        return None
+
+    def health(self) -> HealthStatus:
+        return HealthStatus.healthy()
+
+    def update(
+        self,
+        *,
+        ids: list[str],
+        documents: Optional[list[str]] = None,
+        metadatas: Optional[list[dict]] = None,
+        embeddings: Optional[list[list[float]]] = None,
     ) -> None:
-        raise NotImplementedError
+        """Default non-atomic update: get + merge + upsert.
+
+        Backends advertising ``supports_update`` MUST override with an atomic
+        single-round-trip implementation.
+        """
+        if documents is None and metadatas is None and embeddings is None:
+            raise ValueError("update requires at least one of documents, metadatas, embeddings")
+
+        n = len(ids)
+        for label, value in (
+            ("documents", documents),
+            ("metadatas", metadatas),
+            ("embeddings", embeddings),
+        ):
+            if value is not None and len(value) != n:
+                raise ValueError(f"{label} length {len(value)} does not match ids length {n}")
+
+        existing = self.get(ids=ids, include=["documents", "metadatas"])
+        by_id = {
+            rid: (existing.documents[i], existing.metadatas[i])
+            for i, rid in enumerate(existing.ids)
+        }
+        merged_docs: list[str] = []
+        merged_metas: list[dict] = []
+        for i, rid in enumerate(ids):
+            prev_doc, prev_meta = by_id.get(rid, ("", {}))
+            merged_docs.append(documents[i] if documents is not None else prev_doc)
+            new_meta = dict(prev_meta or {})
+            if metadatas is not None:
+                new_meta.update(metadatas[i] or {})
+            merged_metas.append(new_meta)
+        self.upsert(
+            documents=merged_docs,
+            ids=list(ids),
+            metadatas=merged_metas,
+            embeddings=embeddings,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Backend contract
+# ---------------------------------------------------------------------------
+
+
+class BaseBackend(ABC):
+    """Long-lived factory serving many palaces (RFC 001 §2).
+
+    Instances are lightweight on construction — no I/O, no network. All
+    connection work is deferred to ``get_collection``. Instances are thread-
+    safe for concurrent ``get_collection`` calls across different palaces.
+    """
+
+    name: ClassVar[str]
+    spec_version: ClassVar[str] = "1.0"
+    capabilities: ClassVar[frozenset[str]] = frozenset()
 
     @abstractmethod
-    def query(self, **kwargs: Any) -> Dict[str, Any]:
-        raise NotImplementedError
+    def get_collection(
+        self,
+        *,
+        palace: PalaceRef,
+        collection_name: str,
+        create: bool = False,
+        options: Optional[dict] = None,
+    ) -> BaseCollection: ...
 
-    @abstractmethod
-    def get(self, **kwargs: Any) -> Dict[str, Any]:
-        raise NotImplementedError
+    def close_palace(self, palace: PalaceRef) -> None:
+        """Evict cached handles for a single palace. Default: no-op."""
+        return None
 
-    @abstractmethod
-    def delete(self, **kwargs: Any) -> None:
-        raise NotImplementedError
+    def close(self) -> None:
+        """Shut down the entire backend. Default: no-op."""
+        return None
 
-    @abstractmethod
-    def count(self) -> int:
-        raise NotImplementedError
+    def health(self, palace: Optional[PalaceRef] = None) -> HealthStatus:
+        return HealthStatus.healthy()
+
+    # Optional detection hint used by selection priority (RFC 001 §3.3 (4)):
+    @classmethod
+    def detect(cls, path: str) -> bool:  # pragma: no cover - default hook
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Adapter utilities
+# ---------------------------------------------------------------------------
+
+
+# Keys the Chroma ``include=`` parameter accepts.
+_VALID_INCLUDE_KEYS = frozenset({"documents", "metadatas", "distances", "embeddings"})
+
+
+@dataclass
+class _IncludeSpec:
+    """Resolve an ``include=`` parameter with spec-mandated defaults."""
+
+    documents: bool = True
+    metadatas: bool = True
+    distances: bool = True  # only meaningful for query
+    embeddings: bool = False
+
+    @classmethod
+    def resolve(
+        cls, include: Optional[list[str]], *, default_distances: bool = True
+    ) -> "_IncludeSpec":
+        if include is None:
+            return cls(
+                documents=True,
+                metadatas=True,
+                distances=default_distances,
+                embeddings=False,
+            )
+        keys = {k for k in include if k in _VALID_INCLUDE_KEYS}
+        return cls(
+            documents="documents" in keys,
+            metadatas="metadatas" in keys,
+            distances="distances" in keys,
+            embeddings="embeddings" in keys,
+        )

mempalace/backends/chroma.py

@@ -1,17 +1,136 @@
-"""ChromaDB-backed MemPalace collection adapter."""
+"""ChromaDB-backed MemPalace storage backend (RFC 001 reference implementation)."""
 
+import datetime as _dt
 import logging
 import os
 import sqlite3
+from typing import Any, Optional
 
 import chromadb
 
-from .base import BaseCollection
+from .base import (
+    BaseBackend,
+    BaseCollection,
+    GetResult,
+    HealthStatus,
+    PalaceNotFoundError,
+    PalaceRef,
+    QueryResult,
+    UnsupportedFilterError,
+    _IncludeSpec,
+)
 
 logger = logging.getLogger(__name__)
 
 
-def _fix_blob_seq_ids(palace_path: str):
+_REQUIRED_OPERATORS = frozenset({"$eq", "$ne", "$in", "$nin", "$and", "$or", "$contains"})
+_OPTIONAL_OPERATORS = frozenset({"$gt", "$gte", "$lt", "$lte"})
+_SUPPORTED_OPERATORS = _REQUIRED_OPERATORS | _OPTIONAL_OPERATORS
+
+
+def _validate_where(where: Optional[dict]) -> None:
+    """Scan a where-clause for unknown operators and raise ``UnsupportedFilterError``.
+
+    Spec (RFC 001 §1.4): silent dropping of unknown operators is forbidden.
+    """
+    if not where:
+        return
+    stack = [where]
+    while stack:
+        node = stack.pop()
+        if not isinstance(node, dict):
+            continue
+        for k, v in node.items():
+            if k.startswith("$") and k not in _SUPPORTED_OPERATORS:
+                raise UnsupportedFilterError(f"operator {k!r} not supported by chroma backend")
+            if isinstance(v, dict):
+                stack.append(v)
+            elif isinstance(v, list):
+                stack.extend(x for x in v if isinstance(x, dict))
+
+
+def quarantine_stale_hnsw(palace_path: str, stale_seconds: float = 3600.0) -> list[str]:
+    """Rename HNSW segment dirs whose files are stale vs. chroma.sqlite3.
+
+    When a ChromaDB 1.5.x PersistentClient opens a palace whose on-disk
+    HNSW segment is significantly older than ``chroma.sqlite3``, the Rust
+    graph-walk can dereference dangling neighbor pointers for entries that
+    exist in the metadata segment but not in the HNSW index, and segfault
+    in a background thread on the next ``count()`` or ``query(...)`` call.
+
+    This is the same failure mode reported at #823 (semantic search stale
+    after ``add_drawer``), observed at neo-cortex-mcp#2 (SIGSEGV on
+    ``count()`` with chromadb 1.5.5), and acknowledged as by-design at
+    chroma-core/chroma#2594. On one fork palace (135K drawers), the drift
+    caused a 65–85% crash rate on fresh-process opens; fresh-process
+    crash rate dropped to 0% after the segment dir was renamed out of the
+    way and ChromaDB rebuilt lazily.
+
+    Heuristic: if ``chroma.sqlite3`` is more than ``stale_seconds`` newer
+    than the segment's ``data_level0.bin``, the segment is considered
+    suspect and renamed to ``<uuid>.drift-<timestamp>``. ChromaDB reopens
+    cleanly without it and writes fresh index files on next use. The
+    original directory is renamed, not deleted, so recovery remains
+    possible if the heuristic misfires.
+
+    The default threshold (1h) is deliberately conservative — ChromaDB's
+    HNSW flush cadence means legitimate drift is normally on the order of
+    seconds to minutes. A segment that is more than an hour out of date is
+    almost certainly in a "crashed mid-write" state.
+
+    Args:
+        palace_path: path to the palace directory containing ``chroma.sqlite3``
+        stale_seconds: minimum mtime gap to treat a segment as stale
+
+    Returns:
+        List of paths that were quarantined (empty if nothing drifted).
+    """
+    db_path = os.path.join(palace_path, "chroma.sqlite3")
+    if not os.path.isfile(db_path):
+        return []
+    try:
+        sqlite_mtime = os.path.getmtime(db_path)
+    except OSError:
+        return []
+
+    moved: list[str] = []
+    try:
+        entries = os.listdir(palace_path)
+    except OSError:
+        return []
+
+    for name in entries:
+        if "-" not in name or name.startswith(".") or ".drift-" in name:
+            continue
+        seg_dir = os.path.join(palace_path, name)
+        if not os.path.isdir(seg_dir):
+            continue
+        hnsw_bin = os.path.join(seg_dir, "data_level0.bin")
+        if not os.path.isfile(hnsw_bin):
+            continue
+        try:
+            hnsw_mtime = os.path.getmtime(hnsw_bin)
+        except OSError:
+            continue
+        if sqlite_mtime - hnsw_mtime < stale_seconds:
+            continue
+        stamp = _dt.datetime.now().strftime("%Y%m%d-%H%M%S")
+        target = f"{seg_dir}.drift-{stamp}"
+        try:
+            os.rename(seg_dir, target)
+            moved.append(target)
+            logger.warning(
+                "Quarantined stale HNSW segment %s (sqlite %.0fs newer than HNSW); renamed to %s",
+                seg_dir,
+                sqlite_mtime - hnsw_mtime,
+                target,
+            )
+        except OSError:
+            logger.exception("Failed to quarantine stale HNSW segment %s", seg_dir)
+    return moved
+
+
+def _fix_blob_seq_ids(palace_path: str) -> None:
     """Fix ChromaDB 0.6.x -> 1.5.x migration bug: BLOB seq_ids -> INTEGER.
 
     ChromaDB 0.6.x stored seq_id as big-endian 8-byte BLOBs. ChromaDB 1.5.x
@@ -43,37 +162,363 @@ def _fix_blob_seq_ids(palace_path: str):
         logger.exception("Could not fix BLOB seq_ids in %s", db_path)
 
 
+# ---------------------------------------------------------------------------
+# Collection adapter
+# ---------------------------------------------------------------------------
+
+
+def _as_list(v: Any) -> list:
+    """Coerce possibly-None scalar-or-list into a list (defensive for chroma nulls)."""
+    if v is None:
+        return []
+    if isinstance(v, list):
+        return v
+    return [v]
+
+
 class ChromaCollection(BaseCollection):
-    """Thin adapter over a ChromaDB collection."""
+    """Thin adapter translating ChromaDB dict returns into typed results."""
 
     def __init__(self, collection):
         self._collection = collection
 
-    def add(self, *, documents, ids, metadatas=None):
-        self._collection.add(documents=documents, ids=ids, metadatas=metadatas)
+    # ------------------------------------------------------------------
+    # Writes
+    # ------------------------------------------------------------------
 
-    def upsert(self, *, documents, ids, metadatas=None):
-        self._collection.upsert(documents=documents, ids=ids, metadatas=metadatas)
+    def add(self, *, documents, ids, metadatas=None, embeddings=None):
+        kwargs: dict[str, Any] = {"documents": documents, "ids": ids}
+        if metadatas is not None:
+            kwargs["metadatas"] = metadatas
+        if embeddings is not None:
+            kwargs["embeddings"] = embeddings
+        self._collection.add(**kwargs)
 
-    def query(self, **kwargs):
-        return self._collection.query(**kwargs)
+    def upsert(self, *, documents, ids, metadatas=None, embeddings=None):
+        kwargs: dict[str, Any] = {"documents": documents, "ids": ids}
+        if metadatas is not None:
+            kwargs["metadatas"] = metadatas
+        if embeddings is not None:
+            kwargs["embeddings"] = embeddings
+        self._collection.upsert(**kwargs)
 
-    def get(self, **kwargs):
-        return self._collection.get(**kwargs)
+    def update(
+        self,
+        *,
+        ids,
+        documents=None,
+        metadatas=None,
+        embeddings=None,
+    ):
+        if documents is None and metadatas is None and embeddings is None:
+            raise ValueError("update requires at least one of documents, metadatas, embeddings")
+        kwargs: dict[str, Any] = {"ids": ids}
+        if documents is not None:
+            kwargs["documents"] = documents
+        if metadatas is not None:
+            kwargs["metadatas"] = metadatas
+        if embeddings is not None:
+            kwargs["embeddings"] = embeddings
+        self._collection.update(**kwargs)
 
-    def delete(self, **kwargs):
+    # ------------------------------------------------------------------
+    # Reads
+    # ------------------------------------------------------------------
+
+    def query(
+        self,
+        *,
+        query_texts=None,
+        query_embeddings=None,
+        n_results=10,
+        where=None,
+        where_document=None,
+        include=None,
+    ) -> QueryResult:
+        _validate_where(where)
+        _validate_where(where_document)
+
+        if (query_texts is None) == (query_embeddings is None):
+            raise ValueError("query requires exactly one of query_texts or query_embeddings")
+        chosen = query_texts if query_texts is not None else query_embeddings
+        if not chosen:
+            raise ValueError("query input must be a non-empty list")
+
+        spec = _IncludeSpec.resolve(include, default_distances=True)
+        chroma_include: list[str] = []
+        if spec.documents:
+            chroma_include.append("documents")
+        if spec.metadatas:
+            chroma_include.append("metadatas")
+        if spec.distances:
+            chroma_include.append("distances")
+        if spec.embeddings:
+            chroma_include.append("embeddings")
+
+        kwargs: dict[str, Any] = {
+            "n_results": n_results,
+            "include": chroma_include,
+        }
+        if query_texts is not None:
+            kwargs["query_texts"] = query_texts
+        if query_embeddings is not None:
+            kwargs["query_embeddings"] = query_embeddings
+        if where is not None:
+            kwargs["where"] = where
+        if where_document is not None:
+            kwargs["where_document"] = where_document
+
+        raw = self._collection.query(**kwargs)
+
+        num_queries = (
+            len(query_texts)
+            if query_texts is not None
+            else (len(query_embeddings) if query_embeddings is not None else 1)
+        )
+
+        ids = raw.get("ids") or []
+        if not ids:
+            return QueryResult.empty(
+                num_queries=num_queries,
+                embeddings_requested=spec.embeddings,
+            )
+
+        documents = raw.get("documents") or [[] for _ in ids]
+        metadatas = raw.get("metadatas") or [[] for _ in ids]
+        distances = raw.get("distances") or [[] for _ in ids]
+        embeddings_raw = raw.get("embeddings") if spec.embeddings else None
+
+        def _none_list_to_empty(outer):
+            return [(inner or []) for inner in outer]
+
+        return QueryResult(
+            ids=_none_list_to_empty(ids),
+            documents=_none_list_to_empty(documents),
+            metadatas=_none_list_to_empty(metadatas),
+            distances=_none_list_to_empty(distances),
+            embeddings=(
+                [list(inner) for inner in embeddings_raw]
+                if spec.embeddings and embeddings_raw is not None
+                else None
+            ),
+        )
+
+    def get(
+        self,
+        *,
+        ids=None,
+        where=None,
+        where_document=None,
+        limit=None,
+        offset=None,
+        include=None,
+    ) -> GetResult:
+        _validate_where(where)
+        _validate_where(where_document)
+
+        spec = _IncludeSpec.resolve(include, default_distances=False)
+        chroma_include: list[str] = []
+        if spec.documents:
+            chroma_include.append("documents")
+        if spec.metadatas:
+            chroma_include.append("metadatas")
+        if spec.embeddings:
+            chroma_include.append("embeddings")
+
+        kwargs: dict[str, Any] = {"include": chroma_include}
+        if ids is not None:
+            kwargs["ids"] = ids
+        if where is not None:
+            kwargs["where"] = where
+        if where_document is not None:
+            kwargs["where_document"] = where_document
+        if limit is not None:
+            kwargs["limit"] = limit
+        if offset is not None:
+            kwargs["offset"] = offset
+
+        raw = self._collection.get(**kwargs)
+        out_ids = list(raw.get("ids") or [])
+        out_docs = list(raw.get("documents") or []) if spec.documents else []
+        out_metas = list(raw.get("metadatas") or []) if spec.metadatas else []
+        out_embeds = raw.get("embeddings") if spec.embeddings else None
+
+        # Pad doc/meta lists to match ids so downstream zipping is safe.
+        if spec.documents and len(out_docs) < len(out_ids):
+            out_docs = out_docs + [""] * (len(out_ids) - len(out_docs))
+        if spec.metadatas and len(out_metas) < len(out_ids):
+            out_metas = out_metas + [{}] * (len(out_ids) - len(out_metas))
+
+        return GetResult(
+            ids=out_ids,
+            documents=out_docs,
+            metadatas=out_metas,
+            embeddings=[list(v) for v in out_embeds] if out_embeds is not None else None,
+        )
+
+    def delete(self, *, ids=None, where=None):
+        _validate_where(where)
+        kwargs: dict[str, Any] = {}
+        if ids is not None:
+            kwargs["ids"] = ids
+        if where is not None:
+            kwargs["where"] = where
         self._collection.delete(**kwargs)
 
     def count(self):
         return self._collection.count()
 
 
-class ChromaBackend:
-    """Factory for MemPalace's default ChromaDB backend."""
+# ---------------------------------------------------------------------------
+# Backend
+# ---------------------------------------------------------------------------
+
+
+class ChromaBackend(BaseBackend):
+    """MemPalace's default ChromaDB backend.
+
+    Maintains two caches:
+
+    * ``self._clients`` — ``palace_path -> PersistentClient`` for callers
+      using the ``PalaceRef`` / :meth:`get_collection` path.
+    * An inode+mtime freshness check absorbed from ``mcp_server._get_client``
+      (merged via #757) ensuring a palace rebuild on disk is detected on the
+      next :meth:`get_collection` call.
+    """
+
+    name = "chroma"
+    capabilities = frozenset(
+        {
+            "supports_embeddings_in",
+            "supports_embeddings_passthrough",
+            "supports_embeddings_out",
+            "supports_metadata_filters",
+            "supports_contains_fast",
+            "local_mode",
+        }
+    )
+
+    def __init__(self):
+        # palace_path -> PersistentClient
+        self._clients: dict[str, Any] = {}
+        # palace_path -> (inode, mtime) of chroma.sqlite3 at cache time.
+        self._freshness: dict[str, tuple[int, float]] = {}
+        self._closed = False
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _db_stat(palace_path: str) -> tuple[int, float]:
+        """Return ``(inode, mtime)`` of ``chroma.sqlite3`` or ``(0, 0.0)`` if absent."""
+        db_path = os.path.join(palace_path, "chroma.sqlite3")
+        try:
+            st = os.stat(db_path)
+            return (st.st_ino, st.st_mtime)
+        except OSError:
+            return (0, 0.0)
+
+    def _client(self, palace_path: str):
+        """Return a cached ``PersistentClient``, rebuilding on inode/mtime change.
+
+        Handles the palace-rebuild case (repair/nuke/purge) by invalidating the
+        cache when ``chroma.sqlite3`` changes on disk. Mirrors the semantics of
+        ``mcp_server._get_client`` (merged via #757):
+
+        * DB file missing while we hold a cached client → drop the cache so we
+          do not serve stale data after a rebuild that has not yet re-created
+          the DB.
+        * Transition 0 → nonzero stat (DB created after cache) counts as a
+          change, so the cached client is replaced with one that sees the DB.
+        * FAT/exFAT filesystems return inode 0; we never fire inode comparisons
+          when either side is 0 (safe fallback) but still honor mtime.
+        * Mtime change uses an epsilon (0.01 s) to tolerate FS timestamp
+          granularity without thrashing.
+        """
+        if self._closed:
+            from .base import BackendClosedError  # late import avoids cycles at module load
+
+            raise BackendClosedError("ChromaBackend has been closed")
+
+        cached = self._clients.get(palace_path)
+        cached_inode, cached_mtime = self._freshness.get(palace_path, (0, 0.0))
+        current_inode, current_mtime = self._db_stat(palace_path)
+
+        db_path = os.path.join(palace_path, "chroma.sqlite3")
+        # DB was present when cache was built but is now missing → invalidate.
+        if cached is not None and not os.path.isfile(db_path):
+            self._clients.pop(palace_path, None)
+            self._freshness.pop(palace_path, None)
+            cached = None
+            cached_inode, cached_mtime = 0, 0.0
+
+        inode_changed = current_inode != 0 and cached_inode != 0 and current_inode != cached_inode
+        # Transition from no-stat (0.0) to a real stat counts as a change so we
+        # pick up a DB that was created after the cache was built.
+        mtime_appeared = cached_mtime == 0.0 and current_mtime != 0.0
+        mtime_changed = (
+            current_mtime != 0.0
+            and cached_mtime != 0.0
+            and abs(current_mtime - cached_mtime) > 0.01
+        )
+
+        if cached is None or inode_changed or mtime_changed or mtime_appeared:
+            _fix_blob_seq_ids(palace_path)
+            cached = chromadb.PersistentClient(path=palace_path)
+            self._clients[palace_path] = cached
+            # Re-stat after the client constructor runs: chromadb creates
+            # chroma.sqlite3 lazily, so the stat captured before the call
+            # may still be (0, 0.0) on first open.
+            self._freshness[palace_path] = self._db_stat(palace_path)
+        return cached
+
+    # ------------------------------------------------------------------
+    # Public static helpers (legacy; prefer :meth:`get_collection`)
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def make_client(palace_path: str):
+        """Create a fresh ``PersistentClient`` (fixes BLOB seq_ids first).
+
+        Deprecated-ish: exposed for legacy long-lived callers that manage their
+        own client cache. New code should obtain a collection through
+        :meth:`get_collection` which manages caching internally.
+        """
+        _fix_blob_seq_ids(palace_path)
+        return chromadb.PersistentClient(path=palace_path)
+
+    @staticmethod
+    def backend_version() -> str:
+        """Return the installed chromadb package version string."""
+        return chromadb.__version__
+
+    # ------------------------------------------------------------------
+    # BaseBackend surface
+    # ------------------------------------------------------------------
+
+    def get_collection(
+        self,
+        *args,
+        **kwargs,
+    ) -> ChromaCollection:
+        """Obtain a collection for a palace.
+
+        Supports two calling conventions during the RFC 001 transition:
+
+        * New (preferred): ``get_collection(palace=PalaceRef, collection_name=...,
+          create=False, options=None)``.
+        * Legacy: ``get_collection(palace_path, collection_name, create=False)``
+          — still used by callers not yet migrated.
+        """
+        palace_ref, collection_name, create, options = _normalize_get_collection_args(args, kwargs)
+
+        palace_path = palace_ref.local_path
+        if palace_path is None:
+            raise PalaceNotFoundError("ChromaBackend requires PalaceRef.local_path")
 
-    def get_collection(self, palace_path: str, collection_name: str, create: bool = False):
         if not create and not os.path.isdir(palace_path):
-            raise FileNotFoundError(palace_path)
+            raise PalaceNotFoundError(palace_path)
 
         if create:
             os.makedirs(palace_path, exist_ok=True)
@@ -82,12 +527,116 @@ class ChromaBackend:
             except (OSError, NotImplementedError):
                 pass
 
-        _fix_blob_seq_ids(palace_path)
-        client = chromadb.PersistentClient(path=palace_path)
+        client = self._client(palace_path)
+        hnsw_space = "cosine"
+        if options and isinstance(options, dict):
+            hnsw_space = options.get("hnsw_space", hnsw_space)
+
         if create:
             collection = client.get_or_create_collection(
-                collection_name, metadata={"hnsw:space": "cosine"}
+                collection_name, metadata={"hnsw:space": hnsw_space}
             )
         else:
             collection = client.get_collection(collection_name)
         return ChromaCollection(collection)
+
+    def close_palace(self, palace) -> None:
+        """Drop cached handles for ``palace``. Accepts ``PalaceRef`` or legacy path str."""
+        path = palace.local_path if isinstance(palace, PalaceRef) else palace
+        if path is None:
+            return
+        self._clients.pop(path, None)
+        self._freshness.pop(path, None)
+
+    def close(self) -> None:
+        self._clients.clear()
+        self._freshness.clear()
+        self._closed = True
+
+    def health(self, palace: Optional[PalaceRef] = None) -> HealthStatus:
+        if self._closed:
+            return HealthStatus.unhealthy("backend closed")
+        return HealthStatus.healthy()
+
+    @classmethod
+    def detect(cls, path: str) -> bool:
+        return os.path.isfile(os.path.join(path, "chroma.sqlite3"))
+
+    # ------------------------------------------------------------------
+    # Legacy (pre-RFC 001) surface — retained while callers migrate.
+    # ------------------------------------------------------------------
+
+    def get_or_create_collection(self, palace_path: str, collection_name: str) -> ChromaCollection:
+        """Legacy shim for ``get_collection(..., create=True)`` by path string."""
+        return self.get_collection(palace_path, collection_name, create=True)
+
+    def delete_collection(self, palace_path: str, collection_name: str) -> None:
+        """Delete ``collection_name`` from the palace at ``palace_path``."""
+        self._client(palace_path).delete_collection(collection_name)
+
+    def create_collection(
+        self, palace_path: str, collection_name: str, hnsw_space: str = "cosine"
+    ) -> ChromaCollection:
+        """Create (not get-or-create) ``collection_name`` with the given HNSW space."""
+        collection = self._client(palace_path).create_collection(
+            collection_name, metadata={"hnsw:space": hnsw_space}
+        )
+        return ChromaCollection(collection)
+
+
+def _normalize_get_collection_args(args, kwargs):
+    """Unify legacy positional ``(palace_path, collection_name, create)`` calls
+    with the new kwargs-only ``(palace=PalaceRef, collection_name=..., create=...)``.
+
+    Returns ``(PalaceRef, collection_name, create, options)``.
+    """
+    # New-style: palace= kwarg with a PalaceRef (spec path).
+    if "palace" in kwargs:
+        palace_ref = kwargs.pop("palace")
+        if not isinstance(palace_ref, PalaceRef):
+            raise TypeError("palace= must be a PalaceRef instance")
+        collection_name = kwargs.pop("collection_name")
+        create = kwargs.pop("create", False)
+        options = kwargs.pop("options", None)
+        if kwargs:
+            raise TypeError(f"unexpected kwargs: {sorted(kwargs)}")
+        if args:
+            raise TypeError("positional args not allowed with palace= kwarg")
+        return palace_ref, collection_name, create, options
+
+    # Legacy: first positional is a path string.
+    if args:
+        palace_path = args[0]
+        rest = list(args[1:])
+        collection_name = kwargs.pop("collection_name", None) or (rest.pop(0) if rest else None)
+        if collection_name is None:
+            raise TypeError("collection_name is required")
+        create = kwargs.pop("create", False)
+        if rest:
+            create = rest.pop(0)
+        if rest:
+            raise TypeError(f"unexpected positional args: {rest!r}")
+        if kwargs:
+            raise TypeError(f"unexpected kwargs: {sorted(kwargs)}")
+        return (
+            PalaceRef(id=palace_path, local_path=palace_path),
+            collection_name,
+            bool(create),
+            None,
+        )
+
+    # Legacy kwargs-only (palace_path=..., collection_name=..., create=...)
+    if "palace_path" in kwargs:
+        palace_path = kwargs.pop("palace_path")
+        collection_name = kwargs.pop("collection_name")
+        create = kwargs.pop("create", False)
+        if kwargs:
+            raise TypeError(f"unexpected kwargs: {sorted(kwargs)}")
+        return (
+            PalaceRef(id=palace_path, local_path=palace_path),
+            collection_name,
+            bool(create),
+            None,
+        )
+
+    raise TypeError("get_collection requires palace= or a positional palace_path")

mempalace/backends/registry.py

@@ -0,0 +1,189 @@
+"""Backend registry + entry-point discovery (RFC 001 §3).
+
+Third-party backends ship as installable packages that declare a
+``mempalace.backends`` entry point::
+
+    # pyproject.toml of mempalace-postgres
+    [project.entry-points."mempalace.backends"]
+    postgres = "mempalace_postgres:PostgresBackend"
+
+MemPalace discovers them at process start. In-tree tests and local development
+can register manually via :func:`register`. Explicit registration wins on
+name conflict (matches RFC 001 §3.2).
+"""
+
+from __future__ import annotations
+
+import logging
+from importlib import metadata
+from threading import Lock
+from typing import Optional, Type
+
+from .base import BaseBackend
+
+logger = logging.getLogger(__name__)
+
+_ENTRY_POINT_GROUP = "mempalace.backends"
+
+_registry: dict[str, Type[BaseBackend]] = {}
+_instances: dict[str, BaseBackend] = {}
+_explicit: set[str] = set()
+_discovered = False
+_lock = Lock()
+
+
+def register(name: str, backend_cls: Type[BaseBackend]) -> None:
+    """Register ``backend_cls`` under ``name``.
+
+    Explicit registration wins over entry-point discovery on conflict
+    (RFC 001 §3.2).
+    """
+    with _lock:
+        _registry[name] = backend_cls
+        _explicit.add(name)
+        # Invalidate any cached instance so the new class is used on next get.
+        _instances.pop(name, None)
+
+
+def unregister(name: str) -> None:
+    """Remove a backend registration (primarily for tests)."""
+    with _lock:
+        _registry.pop(name, None)
+        _explicit.discard(name)
+        _instances.pop(name, None)
+
+
+def _discover_entry_points() -> None:
+    """Load entry-point-declared backends once per process."""
+    global _discovered
+    if _discovered:
+        return
+    with _lock:
+        if _discovered:
+            return
+        try:
+            eps = metadata.entry_points()
+            # Py ≥ 3.10 returns an EntryPoints object; older versions returned a dict.
+            group = (
+                eps.select(group=_ENTRY_POINT_GROUP)
+                if hasattr(eps, "select")
+                else eps.get(_ENTRY_POINT_GROUP, [])
+            )
+        except Exception:
+            logger.exception("entry-point discovery for %s failed", _ENTRY_POINT_GROUP)
+            group = []
+        for ep in group:
+            if ep.name in _explicit:
+                continue  # explicit registration wins
+            try:
+                cls = ep.load()
+            except Exception:
+                logger.exception("failed to load backend entry point %r", ep.name)
+                continue
+            if not isinstance(cls, type) or not issubclass(cls, BaseBackend):
+                logger.warning(
+                    "entry point %r did not resolve to a BaseBackend subclass (got %r)",
+                    ep.name,
+                    cls,
+                )
+                continue
+            _registry.setdefault(ep.name, cls)
+        _discovered = True
+
+
+def available_backends() -> list[str]:
+    """Return sorted list of all registered backend names."""
+    _discover_entry_points()
+    return sorted(_registry.keys())
+
+
+def get_backend_class(name: str) -> Type[BaseBackend]:
+    """Return the registered backend class for ``name``."""
+    _discover_entry_points()
+    try:
+        return _registry[name]
+    except KeyError as e:
+        raise KeyError(f"unknown backend {name!r}; available: {available_backends()}") from e
+
+
+def get_backend(name: str) -> BaseBackend:
+    """Return a long-lived instance of the named backend.
+
+    Instances are cached per-name; repeated calls return the same object.
+    Call :func:`reset_backends` in tests that need isolation.
+    """
+    _discover_entry_points()
+    with _lock:
+        inst = _instances.get(name)
+        if inst is not None:
+            return inst
+        cls = _registry.get(name)
+        if cls is None:
+            raise KeyError(f"unknown backend {name!r}; available: {sorted(_registry.keys())}")
+        inst = cls()
+        _instances[name] = inst
+        return inst
+
+
+def reset_backends() -> None:
+    """Close and drop all cached backend instances (primarily for tests)."""
+    with _lock:
+        for inst in _instances.values():
+            try:
+                inst.close()
+            except Exception:
+                logger.exception("error closing backend during reset")
+        _instances.clear()
+
+
+def resolve_backend_for_palace(
+    *,
+    explicit: Optional[str] = None,
+    config_value: Optional[str] = None,
+    env_value: Optional[str] = None,
+    palace_path: Optional[str] = None,
+    default: str = "chroma",
+) -> str:
+    """Resolve the backend name for a palace per RFC 001 §3.3 priority order.
+
+    1. Explicit kwarg / CLI flag
+    2. Per-palace config value
+    3. ``MEMPALACE_BACKEND`` env var
+    4. Auto-detect from on-disk artifacts (migration/upgrade path only)
+    5. Default (``chroma``)
+
+    Auto-detection is strictly a migration aid: it fires only when a local path
+    is presented, no earlier rule has chosen a backend, AND the path already
+    contains backend-identifiable artifacts. For new palaces, (5) wins.
+    """
+    for candidate in (explicit, config_value, env_value):
+        if candidate:
+            return candidate
+
+    _discover_entry_points()
+    if palace_path:
+        for name, cls in _registry.items():
+            try:
+                if cls.detect(palace_path):
+                    return name
+            except Exception:
+                logger.exception("detect() raised on backend %r", name)
+                continue
+    return default
+
+
+# ---------------------------------------------------------------------------
+# Built-in registration
+# ---------------------------------------------------------------------------
+
+
+def _register_builtins() -> None:
+    """Register chroma as the in-tree default."""
+    from .chroma import ChromaBackend
+
+    # Use setdefault semantics so a caller that pre-registered for tests wins.
+    if "chroma" not in _registry:
+        _registry["chroma"] = ChromaBackend
+
+
+_register_builtins()

mempalace/cli.py

@@ -4,7 +4,7 @@ MemPalace — Give your AI a memory. No API key required.
 
 Two ways to ingest:
   Projects:      mempalace mine ~/projects/my_app          (code, docs, notes)
-  Conversations: mempalace mine ~/chats/ --mode convos     (Claude, ChatGPT, Slack)
+  Conversations: mempalace mine <convo-dir> --mode convos     (Claude Code, Claude.ai, ChatGPT, Slack exports)
 
 Same palace. Same search. Different ingest strategies.
 
@@ -22,7 +22,7 @@ Commands:
 Examples:
     mempalace init ~/projects/my_app
     mempalace mine ~/projects/my_app
-    mempalace mine ~/chats/claude-sessions --mode convos
+    mempalace mine ~/.claude/projects/-Users-you-Projects-my_app --mode convos --wing my_app
     mempalace search "why did we switch to GraphQL"
     mempalace search "pricing discussion" --wing my_app --room costs
 """
@@ -34,35 +34,114 @@ import argparse
 from pathlib import Path
 
 from .config import MempalaceConfig
+from .version import __version__
+
+
+_MEMPALACE_PROJECT_FILES = ("mempalace.yaml", "entities.json")
+
+
+def _ensure_mempalace_files_gitignored(project_dir) -> bool:
+    """If project_dir is a git repo, ensure MemPalace's per-project files
+    are listed in .gitignore so they don't get committed by accident.
+
+    Returns True if .gitignore was updated, False otherwise. Issue #185:
+    `mempalace init` writes mempalace.yaml + entities.json into the
+    project root, where they previously had no protection against being
+    staged into git.
+    """
+    from pathlib import Path
+
+    project_path = Path(project_dir).expanduser().resolve()
+    if not (project_path / ".git").exists():
+        return False
+    gitignore = project_path / ".gitignore"
+    existing = gitignore.read_text() if gitignore.exists() else ""
+    existing_lines = {line.strip() for line in existing.splitlines()}
+    missing = [p for p in _MEMPALACE_PROJECT_FILES if p not in existing_lines]
+    if not missing:
+        return False
+    prefix = "" if not existing or existing.endswith("\n") else "\n"
+    block = prefix + "\n# MemPalace per-project files (issue #185)\n" + "\n".join(missing) + "\n"
+    with open(gitignore, "a") as f:
+        f.write(block)
+    print(f"  Added {', '.join(missing)} to {gitignore.name}")
+    return True
 
 
 def cmd_init(args):
     import json
     from pathlib import Path
-    from .entity_detector import scan_for_detection, detect_entities, confirm_entities
+    from .entity_detector import confirm_entities
+    from .project_scanner import discover_entities
     from .room_detector_local import detect_rooms_local
 
-    # Pass 1: auto-detect people and projects from file content
+    cfg = MempalaceConfig()
+
+    # Resolve entity-detection languages: --lang overrides config.
+    lang_arg = getattr(args, "lang", None)
+    if lang_arg:
+        languages = [s.strip() for s in lang_arg.split(",") if s.strip()] or ["en"]
+        cfg.set_entity_languages(languages)
+    else:
+        languages = cfg.entity_languages
+    languages_tuple = tuple(languages)
+
+    # Optional phase-2 LLM provider (opt-in via --llm).
+    llm_provider = None
+    if getattr(args, "llm", False):
+        from .llm_client import LLMError, get_provider
+
+        try:
+            llm_provider = get_provider(
+                name=args.llm_provider,
+                model=args.llm_model,
+                endpoint=args.llm_endpoint,
+                api_key=args.llm_api_key,
+            )
+        except LLMError as e:
+            print(f"  ERROR: {e}", file=sys.stderr)
+            sys.exit(2)
+        ok, msg = llm_provider.check_available()
+        if not ok:
+            print(
+                f"  ERROR: LLM provider '{args.llm_provider}' unavailable: {msg}",
+                file=sys.stderr,
+            )
+            sys.exit(2)
+        print(f"  LLM refinement enabled: {args.llm_provider}/{args.llm_model}")
+
+    # Pass 1: discover entities — manifests + git authors first, prose detection
+    # as supplement for names mentioned only in docs/notes. Optional phase-2
+    # LLM refinement runs inside discover_entities when llm_provider is given.
     print(f"\n  Scanning for entities in: {args.dir}")
-    files = scan_for_detection(args.dir)
-    if files:
-        print(f"  Reading {len(files)} files...")
-        detected = detect_entities(files)
-        total = len(detected["people"]) + len(detected["projects"]) + len(detected["uncertain"])
-        if total > 0:
-            confirmed = confirm_entities(detected, yes=getattr(args, "yes", False))
-            # Save confirmed entities to <project>/entities.json for the miner
-            if confirmed["people"] or confirmed["projects"]:
-                entities_path = Path(args.dir).expanduser().resolve() / "entities.json"
-                with open(entities_path, "w") as f:
-                    json.dump(confirmed, f, indent=2)
-                print(f"  Entities saved: {entities_path}")
-        else:
-            print("  No entities detected — proceeding with directory-based rooms.")
+    if languages_tuple != ("en",):
+        print(f"  Languages: {', '.join(languages_tuple)}")
+    detected = discover_entities(args.dir, languages=languages_tuple, llm_provider=llm_provider)
+    total = len(detected["people"]) + len(detected["projects"]) + len(detected["uncertain"])
+    if total > 0:
+        confirmed = confirm_entities(detected, yes=getattr(args, "yes", False))
+        # Save confirmed entities to <project>/entities.json (per-project
+        # audit trail — user can inspect or hand-edit) AND merge into the
+        # global registry the miner reads at mine time.
+        if confirmed["people"] or confirmed["projects"]:
+            entities_path = Path(args.dir).expanduser().resolve() / "entities.json"
+            with open(entities_path, "w", encoding="utf-8") as f:
+                json.dump(confirmed, f, indent=2, ensure_ascii=False)
+            print(f"  Entities saved: {entities_path}")
+
+            from .miner import add_to_known_entities
+
+            registry_path = add_to_known_entities(confirmed)
+            print(f"  Registry updated: {registry_path}")
+    else:
+        print("  No entities detected — proceeding with directory-based rooms.")
 
     # Pass 2: detect rooms from folder structure
     detect_rooms_local(project_dir=args.dir, yes=getattr(args, "yes", False))
-    MempalaceConfig().init()
+    cfg.init()
+
+    # Pass 3: protect git repos from accidentally committing per-project files
+    _ensure_mempalace_files_gitignored(args.dir)
 
 
 def cmd_mine(args):
@@ -98,6 +177,48 @@ def cmd_mine(args):
         )
 
 
+def cmd_sweep(args):
+    """Sweep a transcript file or directory.
+
+    The sweeper deduplicates against its own prior writes via
+    deterministic drawer IDs + a timestamp cursor. It does NOT currently
+    coordinate with the file-level miners (miner.py / convo_miner.py) —
+    those produce char-chunked drawers without compatible message
+    metadata, so running both miners may store overlapping content under
+    different IDs.
+    """
+    from .sweeper import sweep, sweep_directory
+
+    palace_path = os.path.expanduser(args.palace) if args.palace else MempalaceConfig().palace_path
+    target = os.path.expanduser(args.target)
+
+    if os.path.isfile(target):
+        result = sweep(target, palace_path)
+        print(
+            f"  Swept {target}: +{result['drawers_added']} new, "
+            f"{result['drawers_already_present']} already present, "
+            f"{result['drawers_skipped']} skipped (< cursor)."
+        )
+    elif os.path.isdir(target):
+        result = sweep_directory(target, palace_path)
+        print(
+            f"  Swept {result['files_succeeded']}/{result['files_attempted']} "
+            f"files from {target}: +{result['drawers_added']} new, "
+            f"{result['drawers_already_present']} already present, "
+            f"{result['drawers_skipped']} skipped (< cursor)."
+        )
+        failures = result.get("failures") or []
+        if failures:
+            print(
+                f"  WARNING: {len(failures)} file(s) failed to sweep - see stderr / logs for details.",
+                file=sys.stderr,
+            )
+            sys.exit(2)
+    else:
+        print(f"  ERROR: Not a file or directory: {target}", file=sys.stderr)
+        sys.exit(1)
+
+
 def cmd_search(args):
     from .searcher import search, SearchError
 
@@ -172,8 +293,8 @@ def cmd_status(args):
 
 def cmd_repair(args):
     """Rebuild palace vector index from SQLite metadata."""
-    import chromadb
     import shutil
+    from .backends.chroma import ChromaBackend
     from .migrate import confirm_destructive_action, contains_palace_database
 
     palace_path = os.path.abspath(
@@ -193,10 +314,11 @@ def cmd_repair(args):
     print(f"{'=' * 55}\n")
     print(f"  Palace: {palace_path}")
 
+    backend = ChromaBackend()
+
     # Try to read existing drawers
     try:
-        client = chromadb.PersistentClient(path=palace_path)
-        col = client.get_collection("mempalace_drawers")
+        col = backend.get_collection(palace_path, "mempalace_drawers")
         total = col.count()
         print(f"  Drawers found: {total}")
     except Exception as e:
@@ -243,8 +365,8 @@ def cmd_repair(args):
     shutil.copytree(palace_path, backup_path)
 
     print("  Rebuilding collection...")
-    client.delete_collection("mempalace_drawers")
-    new_col = client.create_collection("mempalace_drawers", metadata={"hnsw:space": "cosine"})
+    backend.delete_collection(palace_path, "mempalace_drawers")
+    new_col = backend.create_collection(palace_path, "mempalace_drawers")
 
     filed = 0
     for i in range(0, len(all_ids), batch_size):
@@ -276,7 +398,7 @@ def cmd_instructions(args):
 
 def cmd_mcp(args):
     """Show how to wire MemPalace into MCP-capable hosts."""
-    base_server_cmd = "python -m mempalace.mcp_server"
+    base_server_cmd = "mempalace-mcp"
 
     if args.palace:
         resolved_palace = str(Path(args.palace).expanduser())
@@ -297,7 +419,7 @@ def cmd_mcp(args):
 
 def cmd_compress(args):
     """Compress drawers in a wing using AAAK Dialect."""
-    import chromadb
+    from .backends.chroma import ChromaBackend
     from .dialect import Dialect
 
     palace_path = os.path.expanduser(args.palace) if args.palace else MempalaceConfig().palace_path
@@ -317,9 +439,9 @@ def cmd_compress(args):
         dialect = Dialect()
 
     # Connect to palace
+    backend = ChromaBackend()
     try:
-        client = chromadb.PersistentClient(path=palace_path)
-        col = client.get_collection("mempalace_drawers")
+        col = backend.get_collection(palace_path, "mempalace_drawers")
     except Exception:
         print(f"\n  No palace found at {palace_path}")
         print("  Run: mempalace init <dir> then mempalace mine <dir>")
@@ -394,9 +516,7 @@ def cmd_compress(args):
     # Store compressed versions (unless dry-run)
     if not args.dry_run:
         try:
-            comp_col = client.get_or_create_collection(
-                "mempalace_compressed", metadata={"hnsw:space": "cosine"}
-            )
+            comp_col = backend.get_or_create_collection(palace_path, "mempalace_compressed")
             for doc_id, compressed, meta, stats in compressed_entries:
                 comp_meta = dict(meta)
                 comp_meta["compression_ratio"] = round(stats["size_ratio"], 1)
@@ -424,10 +544,17 @@ def cmd_compress(args):
 
 
 def main():
+    version_label = f"MemPalace {__version__}"
     parser = argparse.ArgumentParser(
         description="MemPalace — Give your AI a memory. No API key required.",
         formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog=__doc__,
+        epilog=f"{version_label}\n\n{__doc__}",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=version_label,
+        help="Show version and exit",
     )
     parser.add_argument(
         "--palace",
@@ -445,6 +572,53 @@ def main():
         action="store_true",
         help="Auto-accept all detected entities (non-interactive)",
     )
+    p_init.add_argument(
+        "--lang",
+        default=None,
+        help=(
+            "Comma-separated language codes for entity detection "
+            "(e.g. 'en' or 'en,pt-br'). Defaults to value from config "
+            "(MEMPALACE_ENTITY_LANGUAGES env var or config.json), or 'en'. "
+            "When given, the value is also persisted to config.json."
+        ),
+    )
+    p_init.add_argument(
+        "--llm",
+        action="store_true",
+        help=(
+            "Enable LLM-assisted entity refinement (opt-in, local-first). "
+            "Runs after manifest/git/regex detection, asking the configured "
+            "provider to reclassify ambiguous candidates. "
+            "Ctrl-C during refinement returns partial results."
+        ),
+    )
+    p_init.add_argument(
+        "--llm-provider",
+        default="ollama",
+        choices=["ollama", "openai-compat", "anthropic"],
+        help="LLM provider (default: ollama). Use --llm to enable.",
+    )
+    p_init.add_argument(
+        "--llm-model",
+        default="gemma4:e4b",
+        help="Model name for the chosen provider (default: gemma4:e4b for Ollama).",
+    )
+    p_init.add_argument(
+        "--llm-endpoint",
+        default=None,
+        help=(
+            "Provider endpoint URL. Default for Ollama: http://localhost:11434. "
+            "Required for openai-compat."
+        ),
+    )
+    p_init.add_argument(
+        "--llm-api-key",
+        default=None,
+        help=(
+            "API key for the provider. For anthropic, defaults to $ANTHROPIC_API_KEY; "
+            "for openai-compat, defaults to $OPENAI_API_KEY."
+        ),
+    )
 
     # mine
     p_mine = sub.add_parser("mine", help="Mine files into the palace")
@@ -483,6 +657,17 @@ def main():
         help="Extraction strategy for convos mode: 'exchange' (default) or 'general' (5 memory types)",
     )
 
+    # sweep
+    p_sweep = sub.add_parser(
+        "sweep",
+        help="Tandem miner: catch anything the primary miner missed "
+        "(message-level, timestamp-coordinated, idempotent)",
+    )
+    p_sweep.add_argument(
+        "target",
+        help="A .jsonl transcript file, or a directory to scan recursively",
+    )
+
     # search
     p_search = sub.add_parser("search", help="Find anything, exact words")
     p_search.add_argument("query", help="What to search for")
@@ -615,6 +800,7 @@ def main():
         "mine": cmd_mine,
         "split": cmd_split,
         "search": cmd_search,
+        "sweep": cmd_sweep,
         "mcp": cmd_mcp,
         "compress": cmd_compress,
         "wake-up": cmd_wakeup,

mempalace/config.py

@@ -47,6 +47,30 @@ def sanitize_name(value: str, field_name: str = "name") -> str:
     return value
 
 
+def sanitize_kg_value(value: str, field_name: str = "value") -> str:
+    """Validate a knowledge-graph entity name (subject or object).
+
+    More permissive than sanitize_name — allows punctuation like commas,
+    colons, and parentheses that are common in natural-language KG values.
+    Only blocks null bytes and over-length strings.
+
+    Not used for wing/room names (which have filesystem constraints) or
+    predicates (which should be simple relationship identifiers).
+    """
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{field_name} must be a non-empty string")
+
+    value = value.strip()
+
+    if len(value) > MAX_NAME_LENGTH:
+        raise ValueError(f"{field_name} exceeds maximum length of {MAX_NAME_LENGTH} characters")
+
+    if "\x00" in value:
+        raise ValueError(f"{field_name} contains null bytes")
+
+    return value
+
+
 def sanitize_content(value: str, max_length: int = 100_000) -> str:
     """Validate drawer/diary content length."""
     if not isinstance(value, str) or not value.strip():
@@ -144,7 +168,10 @@ class MempalaceConfig:
         """Path to the memory palace data directory."""
         env_val = os.environ.get("MEMPALACE_PALACE_PATH") or os.environ.get("MEMPAL_PALACE_PATH")
         if env_val:
-            return env_val
+            # Normalize: expand ~ and collapse .. to match the CLI --palace
+            # code path (mcp_server.py:62) and prevent surprise redirection
+            # when the env var contains unresolved components.
+            return os.path.abspath(os.path.expanduser(env_val))
         return self._file_config.get("palace_path", DEFAULT_PALACE_PATH)
 
     @property
@@ -173,6 +200,42 @@ class MempalaceConfig:
         """Mapping of hall names to keyword lists."""
         return self._file_config.get("hall_keywords", DEFAULT_HALL_KEYWORDS)
 
+    @property
+    def entity_languages(self):
+        """Languages whose entity-detection patterns should be applied.
+
+        Reads from env var ``MEMPALACE_ENTITY_LANGUAGES`` (comma-separated)
+        first, then the ``entity_languages`` field in ``config.json``,
+        defaulting to ``["en"]``.
+        """
+        env_val = os.environ.get("MEMPALACE_ENTITY_LANGUAGES") or os.environ.get(
+            "MEMPAL_ENTITY_LANGUAGES"
+        )
+        if env_val:
+            return [s.strip() for s in env_val.split(",") if s.strip()] or ["en"]
+        cfg = self._file_config.get("entity_languages")
+        if isinstance(cfg, list) and cfg:
+            return [str(s) for s in cfg]
+        return ["en"]
+
+    def set_entity_languages(self, languages):
+        """Persist the entity-detection language list to ``config.json``."""
+        normalized = [s.strip() for s in languages if s and s.strip()]
+        if not normalized:
+            normalized = ["en"]
+        self._file_config["entity_languages"] = normalized
+        self._config_dir.mkdir(parents=True, exist_ok=True)
+        try:
+            with open(self._config_file, "w", encoding="utf-8") as f:
+                json.dump(self._file_config, f, indent=2, ensure_ascii=False)
+        except OSError:
+            pass
+        try:
+            self._config_file.chmod(0o600)
+        except (OSError, NotImplementedError):
+            pass
+        return normalized
+
     @property
     def hook_silent_save(self):
         """Whether the stop hook saves directly (True) or blocks for MCP calls (False)."""
@@ -227,4 +290,8 @@ class MempalaceConfig:
         self._config_dir.mkdir(parents=True, exist_ok=True)
         with open(self._people_map_file, "w") as f:
             json.dump(people_map, f, indent=2)
+        try:
+            self._people_map_file.chmod(0o600)
+        except (OSError, NotImplementedError):
+            pass
         return self._people_map_file

mempalace/convo_miner.py

@@ -55,7 +55,14 @@ CONVO_EXTENSIONS = {
 
 MIN_CHUNK_SIZE = 30
 CHUNK_SIZE = 800  # chars per drawer — align with miner.py
-MAX_FILE_SIZE = 10 * 1024 * 1024  # 10 MB — skip files larger than this
+MAX_FILE_SIZE = 500 * 1024 * 1024  # 500 MB — skip files larger than this.
+# Matches miner.py at 500 MB. Long Claude Code sessions, multi-year
+# ChatGPT exports, and lifetime Slack dumps routinely exceed 10 MB; the
+# cap at that level silently dropped them with `continue`. Per-drawer
+# size is bounded by CHUNK_SIZE, but larger source files still produce
+# more drawers and therefore more embedding/storage work — and content
+# is normalized and loaded fully into memory before chunking, so memory
+# use also scales with source size.
 
 
 def _register_file(collection, source_file: str, wing: str, agent: str):
@@ -471,7 +478,7 @@ def mine_convos(
             room_counts[r] += n
 
         total_drawers += drawers_added
-        print(f"  ✓ [{i:4}/{len(files)}] {filepath.name[:50]:50} +{drawers_added}")
+        print(f"  + [{i:4}/{len(files)}] {filepath.name[:50]:50} +{drawers_added}")
 
     print(f"\n{'=' * 55}")
     print("  Done.")

mempalace/convo_scanner.py

@@ -0,0 +1,160 @@
+"""
+convo_scanner.py — Parse Claude Code conversation directories into ProjectInfo.
+
+Claude Code stores sessions under ``~/.claude/projects/<slug>/<id>.jsonl``,
+where the ``<slug>`` is the original CWD with ``/`` replaced by ``-``. That
+encoding is lossy: we can't tell whether ``foo-bar`` in a slug is the
+literal project name ``foo-bar`` or two path segments ``foo/bar``.
+
+Fortunately, every message record in the JSONL carries a ``cwd`` field with
+the true path. This scanner reads one record per session to recover the
+accurate project name, falling back to slug-decoding only if the JSONL
+is malformed or empty.
+
+Output is the same ``ProjectInfo`` shape used by ``project_scanner``, so the
+``discover_entities`` orchestrator can mix-and-match sources.
+
+Public:
+    is_claude_projects_root(path) -> bool
+    scan_claude_projects(path) -> list[ProjectInfo]
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+from mempalace.project_scanner import ProjectInfo
+
+
+MAX_HEADER_LINES = 20  # lines to read per session looking for `cwd`
+
+
+def is_claude_projects_root(path: Path) -> bool:
+    """Return True if path looks like `.claude/projects/`.
+
+    Heuristic: at least one child dir whose name starts with ``-`` and which
+    contains at least one ``.jsonl`` file.
+    """
+    if not path.is_dir():
+        return False
+    try:
+        children = list(path.iterdir())
+    except OSError:
+        return False
+    for child in children:
+        if not (child.is_dir() and child.name.startswith("-")):
+            continue
+        try:
+            if any(p.suffix == ".jsonl" for p in child.iterdir() if p.is_file()):
+                return True
+        except OSError:
+            continue
+    return False
+
+
+def _extract_cwd_from_session(session_file: Path) -> Optional[str]:
+    """Return the ``cwd`` from the first message record that carries one.
+
+    Returns None if the file can't be read, has no JSON, or no record has cwd.
+    """
+    try:
+        with open(session_file, encoding="utf-8", errors="replace") as f:
+            for i, line in enumerate(f):
+                if i >= MAX_HEADER_LINES:
+                    break
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    obj = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                cwd = obj.get("cwd")
+                if isinstance(cwd, str) and cwd:
+                    return cwd
+    except OSError:
+        return None
+    return None
+
+
+def _decode_slug_fallback(slug: str) -> str:
+    """Best-effort project name from slug when cwd is unavailable.
+
+    The slug is lossy (`/` and `-` both become `-`). Last non-empty segment
+    is the closest guess at the project name, preserving kebab-case is
+    impossible without cwd.
+    """
+    stripped = slug.lstrip("-")
+    parts = [p for p in stripped.split("-") if p]
+    return parts[-1] if parts else slug
+
+
+def _safe_mtime(path: Path) -> float:
+    """Return file mtime, defaulting old on permission or filesystem errors."""
+    try:
+        return path.stat().st_mtime
+    except OSError:
+        return 0.0
+
+
+def _resolve_project_name(project_dir: Path) -> str:
+    """Read one session's cwd to recover the original project name.
+
+    Falls back to slug-decoding if no session has a readable cwd.
+    """
+    sessions = sorted(
+        (p for p in project_dir.iterdir() if p.is_file() and p.suffix == ".jsonl"),
+        key=_safe_mtime,
+        reverse=True,  # newest first — most likely to be well-formed
+    )
+    for session in sessions:
+        cwd = _extract_cwd_from_session(session)
+        if cwd:
+            return Path(cwd).name or cwd
+    return _decode_slug_fallback(project_dir.name)
+
+
+def scan_claude_projects(path: str | Path) -> list[ProjectInfo]:
+    """Scan a ``.claude/projects/`` directory for Claude Code conversations.
+
+    One ProjectInfo per subdir. ``has_git`` is False (the directory isn't a
+    repo itself) but ``total_commits`` is repurposed here as session count so
+    the UX surfaces a density signal for ranking.
+    """
+    root = Path(path).expanduser().resolve()
+    if not is_claude_projects_root(root):
+        return []
+
+    projects: dict[str, ProjectInfo] = {}
+    for sub in sorted(root.iterdir()):
+        if not (sub.is_dir() and sub.name.startswith("-")):
+            continue
+        try:
+            sessions = [p for p in sub.iterdir() if p.is_file() and p.suffix == ".jsonl"]
+        except OSError:
+            continue
+        if not sessions:
+            continue
+
+        name = _resolve_project_name(sub)
+        session_count = len(sessions)
+
+        proj = ProjectInfo(
+            name=name,
+            repo_root=sub,
+            manifest=None,
+            has_git=False,
+            total_commits=session_count,
+            user_commits=session_count,
+            is_mine=True,  # Claude Code sessions are authored by the user
+        )
+        existing = projects.get(name)
+        if existing is None or session_count > existing.user_commits:
+            projects[name] = proj
+
+    return sorted(
+        projects.values(),
+        key=lambda p: (-p.user_commits, p.name),
+    )

mempalace/dedup.py

@@ -27,7 +27,7 @@ import os
 import time
 from collections import defaultdict
 
-import chromadb
+from .backends.chroma import ChromaBackend
 
 
 COLLECTION_NAME = "mempalace_drawers"
@@ -130,8 +130,7 @@ def dedup_source_group(col, drawer_ids, threshold=DEFAULT_THRESHOLD, dry_run=Tru
 def show_stats(palace_path=None):
     """Show duplication statistics without making changes."""
     palace_path = palace_path or _get_palace_path()
-    client = chromadb.PersistentClient(path=palace_path)
-    col = client.get_collection(COLLECTION_NAME)
+    col = ChromaBackend().get_collection(palace_path, COLLECTION_NAME)
 
     groups = get_source_groups(col)
 
@@ -163,8 +162,7 @@ def dedup_palace(
     print("  MemPalace Deduplicator")
     print(f"{'=' * 55}")
 
-    client = chromadb.PersistentClient(path=palace_path)
-    col = client.get_collection(COLLECTION_NAME)
+    col = ChromaBackend().get_collection(palace_path, COLLECTION_NAME)
 
     print(f"  Palace: {palace_path}")
     print(f"  Drawers: {col.count():,}")

mempalace/dialect.py

@@ -158,6 +158,8 @@ _FLAG_SIGNALS = {
 }
 
 # Common filler/stop words to strip from topic extraction
+_ALPHA_RE = re.compile(r"[^a-zA-Z]")
+
 _STOP_WORDS = {
     "the",
     "a",
@@ -360,7 +362,7 @@ class Dialect:
         return cls(
             entities=config.get("entities", {}),
             skip_names=config.get("skip_names", []),
-            lang=config.get("lang"),
+            lang=config.get("lang", "en"),
         )
 
     def save_config(self, config_path: str):
@@ -541,7 +543,7 @@ class Dialect:
         # Fallback: find capitalized words that look like names (2+ chars, not sentence-start)
         words = text.split()
         for i, w in enumerate(words):
-            clean = re.sub(r"[^a-zA-Z]", "", w)
+            clean = _ALPHA_RE.sub("", w)
             if (
                 len(clean) >= 2
                 and clean[0].isupper()

mempalace/entity_detector.py

@@ -9,9 +9,21 @@ Two-pass approach:
 Used by mempalace init before mining begins.
 The confirmed entity map feeds the miner as the taxonomy.
 
+Multi-language support:
+    All lexical patterns (person verbs, pronouns, dialogue markers, project
+    verbs, stopwords, and the candidate-extraction character class) live in
+    the ``entity`` section of ``mempalace/i18n/<lang>.json``. Every public
+    function accepts a ``languages`` tuple and applies the union of the
+    requested locales' patterns. The default is ``("en",)`` — existing
+    English-only callers behave exactly as before.
+
+    To add a new language: add an ``entity`` section to that locale's JSON.
+    No code changes required.
+
 Usage:
-    from entity_detector import detect_entities, confirm_entities
-    candidates = detect_entities(file_paths)
+    from mempalace.entity_detector import detect_entities, confirm_entities
+    candidates = detect_entities(file_paths)                    # English only
+    candidates = detect_entities(paths, languages=("en", "pt-br"))
     confirmed = confirm_entities(candidates)  # interactive review
 """
 
@@ -21,382 +33,46 @@ import functools
 from pathlib import Path
 from collections import defaultdict
 
+from mempalace.i18n import get_entity_patterns
 
-# ==================== SIGNAL PATTERNS ====================
 
-# Person signals — things people do
-PERSON_VERB_PATTERNS = [
-    r"\b{name}\s+said\b",
-    r"\b{name}\s+asked\b",
-    r"\b{name}\s+told\b",
-    r"\b{name}\s+replied\b",
-    r"\b{name}\s+laughed\b",
-    r"\b{name}\s+smiled\b",
-    r"\b{name}\s+cried\b",
-    r"\b{name}\s+felt\b",
-    r"\b{name}\s+thinks?\b",
-    r"\b{name}\s+wants?\b",
-    r"\b{name}\s+loves?\b",
-    r"\b{name}\s+hates?\b",
-    r"\b{name}\s+knows?\b",
-    r"\b{name}\s+decided\b",
-    r"\b{name}\s+pushed\b",
-    r"\b{name}\s+wrote\b",
-    r"\bhey\s+{name}\b",
-    r"\bthanks?\s+{name}\b",
-    r"\bhi\s+{name}\b",
-    r"\bdear\s+{name}\b",
-]
+# ==================== LANGUAGE-AWARE PATTERN LOADING ====================
 
-# Person signals — pronouns resolving nearby
-PRONOUN_PATTERNS = [
-    r"\bshe\b",
-    r"\bher\b",
-    r"\bhers\b",
-    r"\bhe\b",
-    r"\bhim\b",
-    r"\bhis\b",
-    r"\bthey\b",
-    r"\bthem\b",
-    r"\btheir\b",
-]
 
-PRONOUN_RE = re.compile("|".join(PRONOUN_PATTERNS), re.IGNORECASE)
+def _normalize_langs(languages) -> tuple:
+    """Coerce a language input into a non-empty hashable tuple."""
+    if not languages:
+        return ("en",)
+    if isinstance(languages, str):
+        return (languages,)
+    return tuple(languages)
 
-# Person signals — dialogue markers
-DIALOGUE_PATTERNS = [
-    r"^>\s*{name}[:\s]",  # > Speaker: ...
-    r"^{name}:\s",  # Speaker: ...
-    r"^\[{name}\]",  # [Speaker]
-    r'"{name}\s+said',
-]
 
-# Project signals — things projects have/do
-PROJECT_VERB_PATTERNS = [
-    r"\bbuilding\s+{name}\b",
-    r"\bbuilt\s+{name}\b",
-    r"\bship(?:ping|ped)?\s+{name}\b",
-    r"\blaunch(?:ing|ed)?\s+{name}\b",
-    r"\bdeploy(?:ing|ed)?\s+{name}\b",
-    r"\binstall(?:ing|ed)?\s+{name}\b",
-    r"\bthe\s+{name}\s+architecture\b",
-    r"\bthe\s+{name}\s+pipeline\b",
-    r"\bthe\s+{name}\s+system\b",
-    r"\bthe\s+{name}\s+repo\b",
-    r"\b{name}\s+v\d+\b",  # MemPal v2
-    r"\b{name}\.py\b",  # mempalace.py
-    r"\b{name}-core\b",  # mempal-core (hyphen only, not underscore)
-    r"\b{name}-local\b",
-    r"\bimport\s+{name}\b",
-    r"\bpip\s+install\s+{name}\b",
-]
+@functools.lru_cache(maxsize=32)
+def _get_stopwords(languages: tuple) -> frozenset:
+    """Return the union of stopwords across the given languages."""
+    patterns = get_entity_patterns(languages)
+    return frozenset(patterns["stopwords"])
 
-# Words that are almost certainly NOT entities
-STOPWORDS = {
-    "the",
-    "a",
-    "an",
-    "and",
-    "or",
-    "but",
-    "in",
-    "on",
-    "at",
-    "to",
-    "for",
-    "of",
-    "with",
-    "by",
-    "from",
-    "as",
-    "is",
-    "was",
-    "are",
-    "were",
-    "be",
-    "been",
-    "being",
-    "have",
-    "has",
-    "had",
-    "do",
-    "does",
-    "did",
-    "will",
-    "would",
-    "could",
-    "should",
-    "may",
-    "might",
-    "must",
-    "shall",
-    "can",
-    "this",
-    "that",
-    "these",
-    "those",
-    "it",
-    "its",
-    "they",
-    "them",
-    "their",
-    "we",
-    "our",
-    "you",
-    "your",
-    "i",
-    "my",
-    "me",
-    "he",
-    "she",
-    "his",
-    "her",
-    "who",
-    "what",
-    "when",
-    "where",
-    "why",
-    "how",
-    "which",
-    "if",
-    "then",
-    "so",
-    "not",
-    "no",
-    "yes",
-    "ok",
-    "okay",
-    "just",
-    "very",
-    "really",
-    "also",
-    "already",
-    "still",
-    "even",
-    "only",
-    "here",
-    "there",
-    "now",
-    "then",
-    "too",
-    "up",
-    "out",
-    "about",
-    "like",
-    "use",
-    "get",
-    "got",
-    "make",
-    "made",
-    "take",
-    "put",
-    "come",
-    "go",
-    "see",
-    "know",
-    "think",
-    "true",
-    "false",
-    "none",
-    "null",
-    "new",
-    "old",
-    "all",
-    "any",
-    "some",
-    "true",
-    "false",
-    "return",
-    "print",
-    "def",
-    "class",
-    "import",
-    "from",
-    # Common capitalized words in prose that aren't entities
-    "step",
-    "usage",
-    "run",
-    "check",
-    "find",
-    "add",
-    "get",
-    "set",
-    "list",
-    "args",
-    "dict",
-    "str",
-    "int",
-    "bool",
-    "path",
-    "file",
-    "type",
-    "name",
-    "note",
-    "example",
-    "option",
-    "result",
-    "error",
-    "warning",
-    "info",
-    "every",
-    "each",
-    "more",
-    "less",
-    "next",
-    "last",
-    "first",
-    "second",
-    "stack",
-    "layer",
-    "mode",
-    "test",
-    "stop",
-    "start",
-    "copy",
-    "move",
-    "source",
-    "target",
-    "output",
-    "input",
-    "data",
-    "item",
-    "key",
-    "value",
-    "returns",
-    "raises",
-    "yields",
-    "none",
-    "self",
-    "cls",
-    "kwargs",
-    # Common sentence-starting / abstract words that aren't entities
-    "world",
-    "well",
-    "want",
-    "topic",
-    "choose",
-    "social",
-    "cars",
-    "phones",
-    "healthcare",
-    "ex",
-    "machina",
-    "deus",
-    "human",
-    "humans",
-    "people",
-    "things",
-    "something",
-    "nothing",
-    "everything",
-    "anything",
-    "someone",
-    "everyone",
-    "anyone",
-    "way",
-    "time",
-    "day",
-    "life",
-    "place",
-    "thing",
-    "part",
-    "kind",
-    "sort",
-    "case",
-    "point",
-    "idea",
-    "fact",
-    "sense",
-    "question",
-    "answer",
-    "reason",
-    "number",
-    "version",
-    "system",
-    # Greetings and filler words at sentence starts
-    "hey",
-    "hi",
-    "hello",
-    "thanks",
-    "thank",
-    "right",
-    "let",
-    "ok",
-    # UI/action words that appear in how-to content
-    "click",
-    "hit",
-    "press",
-    "tap",
-    "drag",
-    "drop",
-    "open",
-    "close",
-    "save",
-    "load",
-    "launch",
-    "install",
-    "download",
-    "upload",
-    "scroll",
-    "select",
-    "enter",
-    "submit",
-    "cancel",
-    "confirm",
-    "delete",
-    "copy",
-    "paste",
-    "type",
-    "write",
-    "read",
-    "search",
-    "find",
-    "show",
-    "hide",
-    # Common filesystem/technical capitalized words
-    "desktop",
-    "documents",
-    "downloads",
-    "users",
-    "home",
-    "library",
-    "applications",
-    "system",
-    "preferences",
-    "settings",
-    "terminal",
-    # Abstract/topic words
-    "actor",
-    "vector",
-    "remote",
-    "control",
-    "duration",
-    "fetch",
-    # Abstract concepts that appear as subjects but aren't entities
-    "agents",
-    "tools",
-    "others",
-    "guards",
-    "ethics",
-    "regulation",
-    "learning",
-    "thinking",
-    "memory",
-    "language",
-    "intelligence",
-    "technology",
-    "society",
-    "culture",
-    "future",
-    "history",
-    "science",
-    "model",
-    "models",
-    "network",
-    "networks",
-    "training",
-    "inference",
-}
+
+# ==================== BACKWARD-COMPAT MODULE CONSTANTS ====================
+#
+# These mirror the old module-level constants so existing imports keep working.
+# They reflect the English defaults and are populated at import time from
+# ``mempalace/i18n/en.json``. Callers that need multi-language behavior should
+# pass the ``languages`` parameter to the public functions below.
+
+_EN = get_entity_patterns(("en",))
+
+PERSON_VERB_PATTERNS = list(_EN["person_verb_patterns"])
+PRONOUN_PATTERNS = list(_EN["pronoun_patterns"])
+PRONOUN_RE = re.compile("|".join(PRONOUN_PATTERNS), re.IGNORECASE) if PRONOUN_PATTERNS else None
+DIALOGUE_PATTERNS = list(_EN["dialogue_patterns"])
+PROJECT_VERB_PATTERNS = list(_EN["project_verb_patterns"])
+STOPWORDS = set(_EN["stopwords"])
+
+
+# ==================== EXTENSION POINTS (not language-scoped) ====================
 
 # For entity detection — prose only, no code files
 # Code files have too many capitalized names (classes, functions) that aren't entities
@@ -437,62 +113,130 @@ SKIP_DIRS = {
     ".next",
     "coverage",
     ".mempalace",
+    ".terraform",
+    "vendor",
+    "target",
+}
+
+# Files whose content is boilerplate prose — poisons entity detection.
+# Matched by stem (case-insensitive), with or without an extension.
+SKIP_FILENAMES = {
+    "license",
+    "licence",
+    "copying",
+    "copyright",
+    "notice",
+    "authors",
+    "patents",
+    "third_party_notices",
+    "third-party-notices",
 }
 
 
 # ==================== CANDIDATE EXTRACTION ====================
 
 
-def extract_candidates(text: str) -> dict:
+def extract_candidates(text: str, languages=("en",)) -> dict:
     """
     Extract all capitalized proper noun candidates from text.
     Returns {name: frequency} for names appearing 3+ times.
-    """
-    # Find all capitalized words (not at sentence start — harder, so we use frequency as filter)
-    raw = re.findall(r"\b([A-Z][a-z]{1,19})\b", text)
 
-    counts = defaultdict(int)
-    for word in raw:
-        if word.lower() not in STOPWORDS and len(word) > 1:
+    Each language contributes its own character-class pattern (e.g. ASCII
+    for English, Latin+diacritics for pt-br, Cyrillic for Russian,
+    Devanagari for Hindi). Matches from all languages are unioned.
+    """
+    langs = _normalize_langs(languages)
+    patterns = get_entity_patterns(langs)
+    stopwords = _get_stopwords(langs)
+
+    counts: defaultdict = defaultdict(int)
+
+    # Single-word candidates — one pre-wrapped pattern per language
+    for wrapped_pat in patterns["candidate_patterns"]:
+        try:
+            rx = re.compile(wrapped_pat)
+        except re.error:
+            continue
+        for word in rx.findall(text):
+            if word.lower() in stopwords:
+                continue
+            if len(word) < 2:
+                continue
             counts[word] += 1
 
-    # Also find multi-word proper nouns (e.g. "Memory Palace", "Claude Code")
-    multi = re.findall(r"\b([A-Z][a-z]+(?:\s+[A-Z][a-z]+)+)\b", text)
-    for phrase in multi:
-        if not any(w.lower() in STOPWORDS for w in phrase.split()):
+    # Multi-word candidates — one pre-wrapped pattern per language
+    for wrapped_pat in patterns["multi_word_patterns"]:
+        try:
+            rx = re.compile(wrapped_pat)
+        except re.error:
+            continue
+        for phrase in rx.findall(text):
+            if any(w.lower() in stopwords for w in phrase.split()):
+                continue
             counts[phrase] += 1
 
-    # Filter: must appear at least 3 times to be a candidate
     return {name: count for name, count in counts.items() if count >= 3}
 
 
 # ==================== SIGNAL SCORING ====================
 
 
-@functools.lru_cache(maxsize=128)
-def _build_patterns(name: str) -> dict:
-    """Pre-compile all regex patterns for a single entity name."""
+@functools.lru_cache(maxsize=256)
+def _build_patterns(name: str, languages: tuple = ("en",)) -> dict:
+    """Pre-compile all regex patterns for a single entity name, per language set."""
     n = re.escape(name)
+    langs = _normalize_langs(languages)
+    sources = get_entity_patterns(langs)
+
+    def _compile_each(raw_patterns, flags=re.IGNORECASE):
+        compiled = []
+        for p in raw_patterns:
+            try:
+                compiled.append(re.compile(p.format(name=n), flags))
+            except (re.error, KeyError, IndexError):
+                continue
+        return compiled
+
+    direct_sources = sources.get("direct_address_patterns") or []
+    direct_compiled = []
+    for raw in direct_sources:
+        try:
+            direct_compiled.append(re.compile(raw.format(name=n), re.IGNORECASE))
+        except (re.error, KeyError, IndexError):
+            continue
+
     return {
-        "dialogue": [
-            re.compile(p.format(name=n), re.MULTILINE | re.IGNORECASE) for p in DIALOGUE_PATTERNS
-        ],
-        "person_verbs": [re.compile(p.format(name=n), re.IGNORECASE) for p in PERSON_VERB_PATTERNS],
-        "project_verbs": [
-            re.compile(p.format(name=n), re.IGNORECASE) for p in PROJECT_VERB_PATTERNS
-        ],
-        "direct": re.compile(rf"\bhey\s+{n}\b|\bthanks?\s+{n}\b|\bhi\s+{n}\b", re.IGNORECASE),
-        "versioned": re.compile(rf"\b{n}[-v]\w+", re.IGNORECASE),
+        "dialogue": _compile_each(sources["dialogue_patterns"], re.MULTILINE | re.IGNORECASE),
+        "person_verbs": _compile_each(sources["person_verb_patterns"]),
+        "project_verbs": _compile_each(sources["project_verb_patterns"]),
+        "direct": direct_compiled,
+        "versioned": re.compile(rf"\b{n}[-_]v?\d+(?:\.\d+)*\b", re.IGNORECASE),
         "code_ref": re.compile(rf"\b{n}\.(py|js|ts|yaml|yml|json|sh)\b", re.IGNORECASE),
     }
 
 
-def score_entity(name: str, text: str, lines: list) -> dict:
+@functools.lru_cache(maxsize=32)
+def _pronoun_re(languages: tuple):
+    """Compile a combined pronoun regex for the given languages."""
+    langs = _normalize_langs(languages)
+    patterns = get_entity_patterns(langs)
+    pronouns = patterns.get("pronoun_patterns") or []
+    if not pronouns:
+        return None
+    try:
+        return re.compile("|".join(pronouns), re.IGNORECASE)
+    except re.error:
+        return None
+
+
+def score_entity(name: str, text: str, lines: list, languages=("en",)) -> dict:
     """
     Score a candidate entity as person vs project.
     Returns scores and the signals that fired.
     """
-    patterns = _build_patterns(name)
+    langs = _normalize_langs(languages)
+    patterns = _build_patterns(name, langs)
+    pronoun_re = _pronoun_re(langs)
     person_score = 0
     project_score = 0
     person_signals = []
@@ -500,12 +244,19 @@ def score_entity(name: str, text: str, lines: list) -> dict:
 
     # --- Person signals ---
 
-    # Dialogue markers (strong signal)
+    # Dialogue markers (strong signal).
+    # The bare `^NAME:\s` colon-prefix pattern matches metadata lines like
+    # `Created: 2026-04-21`, so we require >= 2 hits for it to count as dialogue
+    # (real speaker markers repeat; single-line metadata doesn't).
     for rx in patterns["dialogue"]:
         matches = len(rx.findall(text))
-        if matches > 0:
-            person_score += matches * 3
-            person_signals.append(f"dialogue marker ({matches}x)")
+        if matches == 0:
+            continue
+        is_bare_colon = rx.pattern.endswith(r":\s") and not rx.pattern.endswith(r"[:\s]")
+        if is_bare_colon and matches < 2:
+            continue
+        person_score += matches * 3
+        person_signals.append(f"dialogue marker ({matches}x)")
 
     # Person verbs
     for rx in patterns["person_verbs"]:
@@ -515,22 +266,25 @@ def score_entity(name: str, text: str, lines: list) -> dict:
             person_signals.append(f"'{name} ...' action ({matches}x)")
 
     # Pronoun proximity — pronouns within 3 lines of the name
-    name_lower = name.lower()
-    name_line_indices = [i for i, line in enumerate(lines) if name_lower in line.lower()]
-    pronoun_hits = 0
-    for idx in name_line_indices:
-        window_text = " ".join(lines[max(0, idx - 2) : idx + 3])
-        if PRONOUN_RE.search(window_text):
-            pronoun_hits += 1
-    if pronoun_hits > 0:
-        person_score += pronoun_hits * 2
-        person_signals.append(f"pronoun nearby ({pronoun_hits}x)")
+    if pronoun_re is not None:
+        name_lower = name.lower()
+        name_line_indices = [i for i, line in enumerate(lines) if name_lower in line.lower()]
+        pronoun_hits = 0
+        for idx in name_line_indices:
+            window_text = " ".join(lines[max(0, idx - 2) : idx + 3])
+            if pronoun_re.search(window_text):
+                pronoun_hits += 1
+        if pronoun_hits > 0:
+            person_score += pronoun_hits * 2
+            person_signals.append(f"pronoun nearby ({pronoun_hits}x)")
 
     # Direct address
-    direct = len(patterns["direct"].findall(text))
-    if direct > 0:
-        person_score += direct * 4
-        person_signals.append(f"addressed directly ({direct}x)")
+    direct_hits = 0
+    for rx in patterns["direct"]:
+        direct_hits += len(rx.findall(text))
+    if direct_hits > 0:
+        person_score += direct_hits * 4
+        person_signals.append(f"addressed directly ({direct_hits}x)")
 
     # --- Project signals ---
 
@@ -598,17 +352,28 @@ def classify_entity(name: str, frequency: int, scores: dict) -> dict:
             signal_categories.add("addressed")
 
     has_two_signal_types = len(signal_categories) >= 2
-    _ = signal_categories - {"pronoun"}  # reserved for future thresholds
+    # Single-category pronoun signal still classifies as person when the
+    # evidence is overwhelming — a diary's main character is referenced
+    # with pronouns, not dialogue markers. Require both: many pronoun hits
+    # AND a high pronoun-to-frequency ratio so common sentence-start words
+    # (Never, Before, etc.) with incidental pronoun proximity don't qualify.
+    pronoun_hits = 0
+    for s in scores["person_signals"]:
+        m = re.search(r"pronoun nearby \((\d+)x\)", s)
+        if m:
+            pronoun_hits = int(m.group(1))
+            break
+    strong_pronoun_signal = pronoun_hits >= 5 and frequency > 0 and pronoun_hits / frequency >= 0.2
 
-    if person_ratio >= 0.7 and has_two_signal_types and ps >= 5:
+    if person_ratio >= 0.7 and (has_two_signal_types and ps >= 5 or strong_pronoun_signal):
         entity_type = "person"
         confidence = min(0.99, 0.5 + person_ratio * 0.5)
         signals = scores["person_signals"] or [f"appears {frequency}x"]
-    elif person_ratio >= 0.7 and (not has_two_signal_types or ps < 5):
-        # Pronoun-only match — downgrade to uncertain
+    elif person_ratio >= 0.7:
+        # Weak single-category person signal — downgrade to uncertain
         entity_type = "uncertain"
         confidence = 0.4
-        signals = scores["person_signals"] + [f"appears {frequency}x — pronoun-only match"]
+        signals = scores["person_signals"] + [f"appears {frequency}x — weak person signal"]
     elif person_ratio <= 0.3:
         entity_type = "project"
         confidence = min(0.99, 0.5 + (1 - person_ratio) * 0.5)
@@ -631,13 +396,15 @@ def classify_entity(name: str, frequency: int, scores: dict) -> dict:
 # ==================== MAIN DETECT ====================
 
 
-def detect_entities(file_paths: list, max_files: int = 10) -> dict:
+def detect_entities(file_paths: list, max_files: int = 10, languages=("en",)) -> dict:
     """
     Scan files and detect entity candidates.
 
     Args:
         file_paths: List of Path objects to scan
         max_files: Max files to read (for speed)
+        languages: Tuple of language codes whose entity patterns should be
+            applied (union). Defaults to ``("en",)``.
 
     Returns:
         {
@@ -646,6 +413,8 @@ def detect_entities(file_paths: list, max_files: int = 10) -> dict:
             "uncertain":[...entity dicts...],
         }
     """
+    langs = _normalize_langs(languages)
+
     # Collect text from files
     all_text = []
     all_lines = []
@@ -668,7 +437,7 @@ def detect_entities(file_paths: list, max_files: int = 10) -> dict:
     combined_text = "\n".join(all_text)
 
     # Extract candidates
-    candidates = extract_candidates(combined_text)
+    candidates = extract_candidates(combined_text, languages=langs)
 
     if not candidates:
         return {"people": [], "projects": [], "uncertain": []}
@@ -679,7 +448,7 @@ def detect_entities(file_paths: list, max_files: int = 10) -> dict:
     uncertain = []
 
     for name, frequency in sorted(candidates.items(), key=lambda x: x[1], reverse=True):
-        scores = score_entity(name, combined_text, all_lines)
+        scores = score_entity(name, combined_text, all_lines, languages=langs)
         entity = classify_entity(name, frequency, scores)
 
         if entity["type"] == "person":
@@ -826,6 +595,8 @@ def scan_for_detection(project_dir: str, max_files: int = 10) -> list:
         dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
         for filename in filenames:
             filepath = Path(root) / filename
+            if filepath.stem.lower() in SKIP_FILENAMES:
+                continue
             ext = filepath.suffix.lower()
             if ext in PROSE_EXTENSIONS:
                 prose_files.append(filepath)
@@ -843,13 +614,14 @@ if __name__ == "__main__":
     import sys
 
     if len(sys.argv) < 2:
-        print("Usage: python entity_detector.py <directory>")
+        print("Usage: python entity_detector.py <directory> [lang1,lang2,...]")
         sys.exit(1)
 
     project_dir = sys.argv[1]
-    print(f"Scanning: {project_dir}")
+    langs = tuple(sys.argv[2].split(",")) if len(sys.argv) >= 3 else ("en",)
+    print(f"Scanning: {project_dir} (languages: {', '.join(langs)})")
     files = scan_for_detection(project_dir)
     print(f"Reading {len(files)} files...")
-    detected = detect_entities(files)
+    detected = detect_entities(files, languages=langs)
     confirmed = confirm_entities(detected)
     print("Confirmed entities:", confirmed)

mempalace/entity_registry.py

@@ -178,6 +178,12 @@ def _wikipedia_lookup(word: str) -> dict:
     Look up a word via Wikipedia REST API.
     Returns inferred type (person/place/concept/unknown) + confidence + summary.
     Free, no API key, handles disambiguation pages.
+
+    **Privacy warning:** This function makes an outbound HTTPS request to
+    en.wikipedia.org, sending the queried word over the network.  It should
+    only be called when the caller has explicitly opted in via
+    ``allow_network=True`` in :meth:`EntityRegistry.research`.  The default
+    behaviour of ``research()`` is local-only (no network calls).
     """
     try:
         url = f"https://en.wikipedia.org/api/rest_v1/page/summary/{urllib.parse.quote(word)}"
@@ -244,13 +250,14 @@ def _wikipedia_lookup(word: str) -> dict:
 
     except urllib.error.HTTPError as e:
         if e.code == 404:
-            # Not in Wikipedia — strong signal it's a proper noun (unusual name, nickname)
+            # Not in Wikipedia — this tells us nothing definitive about
+            # the word.  Return "unknown" so the caller can decide.
             return {
-                "inferred_type": "person",
-                "confidence": 0.70,
+                "inferred_type": "unknown",
+                "confidence": 0.3,
                 "wiki_summary": None,
                 "wiki_title": None,
-                "note": "not found in Wikipedia — likely a proper noun or unusual name",
+                "note": "not found in Wikipedia",
             }
         return {"inferred_type": "unknown", "confidence": 0.0, "wiki_summary": None}
     except (urllib.error.URLError, OSError, json.JSONDecodeError, KeyError):
@@ -301,7 +308,7 @@ class EntityRegistry:
         path = (Path(config_dir) / "entity_registry.json") if config_dir else cls.DEFAULT_PATH
         if path.exists():
             try:
-                data = json.loads(path.read_text())
+                data = json.loads(path.read_text(encoding="utf-8"))
                 return cls(data, path)
             except (json.JSONDecodeError, OSError):
                 pass
@@ -309,7 +316,15 @@ class EntityRegistry:
 
     def save(self):
         self._path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            self._path.parent.chmod(0o700)
+        except (OSError, NotImplementedError):
+            pass
         self._path.write_text(json.dumps(self._data, indent=2), encoding="utf-8")
+        try:
+            self._path.chmod(0o600)
+        except (OSError, NotImplementedError):
+            pass
 
     @staticmethod
     def _empty() -> dict:
@@ -502,20 +517,41 @@ class EntityRegistry:
 
     # ── Research unknown words ───────────────────────────────────────────────
 
-    def research(self, word: str, auto_confirm: bool = False) -> dict:
+    def research(self, word: str, auto_confirm: bool = False, allow_network: bool = False) -> dict:
         """
-        Research an unknown word via Wikipedia.
-        Caches result. If auto_confirm=False, marks as unconfirmed (needs user review).
-        Returns the lookup result.
+        Research an unknown word.
+
+        By default this is **local-only**: it checks the wiki cache and
+        returns ``"unknown"`` for uncached words.  Pass
+        ``allow_network=True`` to explicitly opt in to an outbound
+        Wikipedia lookup.  This design honours the project's
+        *local-first, zero API* and *privacy by architecture* principles
+        — no data leaves the machine unless the caller requests it.
+
+        Caches result.  If *auto_confirm* is ``False``, marks the entry
+        as unconfirmed (needs user review).
         """
-        # Already cached?
-        cache = self._data.setdefault("wiki_cache", {})
+        # Check cache (read-only — no mutation when allow_network is False)
+        cache = self._data.get("wiki_cache", {})
         if word in cache:
             return cache[word]
 
+        if not allow_network:
+            return {
+                "inferred_type": "unknown",
+                "confidence": 0.0,
+                "wiki_summary": None,
+                "wiki_title": None,
+                "word": word,
+                "confirmed": False,
+                "note": "network lookup disabled — pass allow_network=True to query Wikipedia",
+            }
+
+        # Network path — ensure wiki_cache key exists before writing
+        cache = self._data.setdefault("wiki_cache", {})
         result = _wikipedia_lookup(word)
-        result["word"] = word
-        result["confirmed"] = auto_confirm
+        result.setdefault("word", word)
+        result.setdefault("confirmed", auto_confirm)
 
         cache[word] = result
         self.save()
@@ -547,15 +583,19 @@ class EntityRegistry:
 
     # ── Learn from sessions ──────────────────────────────────────────────────
 
-    def learn_from_text(self, text: str, min_confidence: float = 0.75) -> list:
+    def learn_from_text(self, text: str, min_confidence: float = 0.75, languages=("en",)) -> list:
         """
         Scan session text for new entity candidates.
         Returns list of newly discovered candidates for review.
+
+        ``languages`` is forwarded to entity detection — pass the user's
+        configured ``MempalaceConfig().entity_languages`` to match the
+        locales used at ``mempalace init`` time.
         """
         from mempalace.entity_detector import extract_candidates, score_entity, classify_entity
 
         lines = text.splitlines()
-        candidates = extract_candidates(text)
+        candidates = extract_candidates(text, languages=languages)
         new_candidates = []
 
         for name, frequency in candidates.items():
@@ -563,7 +603,7 @@ class EntityRegistry:
             if name in self.people or name in self.projects:
                 continue
 
-            scores = score_entity(name, text, lines)
+            scores = score_entity(name, text, lines, languages=languages)
             entity = classify_entity(name, frequency, scores)
 
             if entity["type"] == "person" and entity["confidence"] >= min_confidence:
@@ -616,7 +656,9 @@ class EntityRegistry:
         Find capitalized words in query that aren't in registry or common words.
         These are candidates for Wikipedia research.
         """
-        candidates = re.findall(r"\b[A-Z][a-z]{2,15}\b", query)
+        from .palace import _candidate_entity_words
+
+        candidates = _candidate_entity_words(query)
         unknown = []
         for word in set(candidates):
             if word.lower() in COMMON_ENGLISH_WORDS:

mempalace/exporter.py

@@ -49,9 +49,15 @@ def export_palace(palace_path: str, output_dir: str, format: str = "markdown") -
         return {"wings": 0, "rooms": 0, "drawers": 0}
 
     os.makedirs(output_dir, exist_ok=True)
+    try:
+        os.chmod(output_dir, 0o700)
+    except (OSError, NotImplementedError):
+        pass
 
     # Track which room files have been opened (so we can append vs overwrite)
     opened_rooms: set[tuple[str, str]] = set()
+    # Track which wing directories have been created and chmoded
+    created_wing_dirs: set[str] = set()
     # Track stats per wing: {wing: {room: count}}
     wing_stats: dict[str, dict[str, int]] = defaultdict(lambda: defaultdict(int))
     total_drawers = 0
@@ -82,7 +88,13 @@ def export_palace(palace_path: str, output_dir: str, format: str = "markdown") -
         for wing, rooms in batch_grouped.items():
             safe_wing = _safe_path_component(wing)
             wing_dir = os.path.join(output_dir, safe_wing)
-            os.makedirs(wing_dir, exist_ok=True)
+            if wing_dir not in created_wing_dirs:
+                os.makedirs(wing_dir, exist_ok=True)
+                try:
+                    os.chmod(wing_dir, 0o700)
+                except (OSError, NotImplementedError):
+                    pass
+                created_wing_dirs.add(wing_dir)
 
             for room, drawers in rooms.items():
                 safe_room = _safe_path_component(room)

mempalace/hooks_cli.py

@@ -17,22 +17,54 @@ from pathlib import Path
 SAVE_INTERVAL = 15
 STATE_DIR = Path.home() / ".mempalace" / "hook_state"
 
+
+def _mempalace_python() -> str:
+    """Return the python interpreter that has mempalace installed.
+
+    When hooks are invoked by Claude Code, sys.executable may be the system
+    python which lacks chromadb and other deps.  Resolution order:
+    1. MEMPALACE_PYTHON env var (explicit override)
+    2. Venv python from package install path
+    3. Editable install: venv/ sibling to mempalace/
+    4. sys.executable fallback
+    """
+    # Honor explicit override (used by shell hook wrappers)
+    env_python = os.environ.get("MEMPALACE_PYTHON", "")
+    if env_python and os.path.isfile(env_python) and os.access(env_python, os.X_OK):
+        return env_python
+    # This file lives at <venv>/lib/pythonX.Y/site-packages/mempalace/hooks_cli.py
+    # or <project>/mempalace/hooks_cli.py (editable install).
+    venv_bin = Path(__file__).resolve().parents[3] / "bin" / "python"
+    if venv_bin.is_file():
+        return str(venv_bin)
+    # Editable install: assumes project root has a venv/ sibling to mempalace/
+    project_venv = Path(__file__).resolve().parents[1] / "venv" / "bin" / "python"
+    if project_venv.is_file():
+        return str(project_venv)
+    return sys.executable
+
+
+_RECENT_MSG_COUNT = 30  # how many recent user messages to summarize
+
 STOP_BLOCK_REASON = (
     "AUTO-SAVE checkpoint (MemPalace). Save this session's key content:\n"
-    "1. mempalace_diary_write — AAAK-compressed session summary\n"
-    "2. mempalace_add_drawer — verbatim quotes, decisions, code snippets\n"
+    "1. mempalace_diary_write — session summary (what was discussed, "
+    "key decisions, current state of work)\n"
+    "2. mempalace_add_drawer — verbatim quotes, decisions, code snippets "
+    "(place in appropriate wing and room)\n"
     "3. mempalace_kg_add — entity relationships (optional)\n"
-    "Do NOT write to Claude Code's native auto-memory (.md files). "
-    "Continue conversation after saving."
+    "For THIS save, use MemPalace MCP tools only (not auto-memory .md files). "
+    "Use verbatim quotes where possible. Continue conversation after saving."
 )
 
 PRECOMPACT_BLOCK_REASON = (
     "COMPACTION IMMINENT (MemPalace). Save ALL session content before context is lost:\n"
-    "1. mempalace_diary_write — thorough AAAK-compressed session summary\n"
-    "2. mempalace_add_drawer — ALL verbatim quotes, decisions, code, context\n"
+    "1. mempalace_diary_write — thorough session summary\n"
+    "2. mempalace_add_drawer — ALL verbatim quotes, decisions, code, context "
+    "(place each in appropriate wing and room)\n"
     "3. mempalace_kg_add — entity relationships (optional)\n"
-    "Be thorough \u2014 after compaction, detailed context will be lost. "
-    "Do NOT write to Claude Code's native auto-memory (.md files). "
+    "For THIS save, use MemPalace MCP tools only (not auto-memory .md files). "
+    "Be thorough — after compaction this is all that survives. "
     "Save everything to MemPalace, then allow compaction to proceed."
 )
 
@@ -43,9 +75,32 @@ def _sanitize_session_id(session_id: str) -> str:
     return sanitized or "unknown"
 
 
+def _validate_transcript_path(transcript_path: str) -> Path:
+    """Validate and resolve a transcript path, rejecting paths outside expected roots.
+
+    Returns a resolved Path if valid, or None if the path should be rejected.
+    Accepted paths must:
+    - Have a .jsonl or .json extension
+    - Not contain '..' after resolution (path traversal prevention)
+    """
+    if not transcript_path:
+        return None
+    path = Path(transcript_path).expanduser().resolve()
+    if path.suffix not in (".jsonl", ".json"):
+        return None
+    # Reject if the original input contained '..' traversal components
+    if ".." in Path(transcript_path).parts:
+        return None
+    return path
+
+
 def _count_human_messages(transcript_path: str) -> int:
     """Count human messages in a JSONL transcript, skipping command-messages."""
-    path = Path(transcript_path).expanduser()
+    path = _validate_transcript_path(transcript_path)
+    if path is None:
+        if transcript_path:
+            _log(f"WARNING: transcript_path rejected by validator: {transcript_path!r}")
+        return 0
     if not path.is_file():
         return 0
     count = 0
@@ -82,37 +137,339 @@ def _count_human_messages(transcript_path: str) -> int:
     return count
 
 
+_state_dir_initialized = False
+
+
 def _log(message: str):
     """Append to hook state log file."""
+    global _state_dir_initialized
     try:
-        STATE_DIR.mkdir(parents=True, exist_ok=True)
+        if not _state_dir_initialized:
+            STATE_DIR.mkdir(parents=True, exist_ok=True)
+            try:
+                STATE_DIR.chmod(0o700)
+            except (OSError, NotImplementedError):
+                pass
+            _state_dir_initialized = True
         log_path = STATE_DIR / "hook.log"
+        is_new = not log_path.exists()
         timestamp = datetime.now().strftime("%H:%M:%S")
         with open(log_path, "a") as f:
             f.write(f"[{timestamp}] {message}\n")
+        if is_new:
+            try:
+                log_path.chmod(0o600)
+            except (OSError, NotImplementedError):
+                pass
     except OSError:
         pass
 
 
 def _output(data: dict):
-    """Print JSON to stdout with consistent formatting (pretty-printed)."""
-    print(json.dumps(data, indent=2, ensure_ascii=False))
+    """Print JSON to stdout without importing modules that may redirect streams.
+
+    If mempalace.mcp_server is already loaded, reuse its saved real stdout fd.
+    Otherwise, write directly to fd 1 so hook responses still go to stdout even
+    if sys.stdout has been redirected elsewhere.
+    """
+    payload = (json.dumps(data, indent=2, ensure_ascii=False) + "\n").encode("utf-8")
+
+    real_stdout_fd: int | None = None
+    mcp_mod = sys.modules.get("mempalace.mcp_server") or sys.modules.get(
+        f"{__package__}.mcp_server" if __package__ else "mcp_server"
+    )
+    if mcp_mod is not None:
+        real_stdout_fd = getattr(mcp_mod, "_REAL_STDOUT_FD", None)
+
+    fd = real_stdout_fd if real_stdout_fd is not None else 1
+    offset = 0
+    try:
+        while offset < len(payload):
+            try:
+                offset += os.write(fd, payload[offset:])
+            except InterruptedError:
+                continue
+        return
+    except OSError:
+        pass
+
+    sys.stdout.buffer.write(payload)
+    sys.stdout.buffer.flush()
 
 
-def _maybe_auto_ingest():
-    """If MEMPAL_DIR is set and exists, run mempalace mine in background."""
+def _get_mine_dir(transcript_path: str = "") -> str:
+    """Determine directory to mine from MEMPAL_DIR or transcript path."""
     mempal_dir = os.environ.get("MEMPAL_DIR", "")
     if mempal_dir and os.path.isdir(mempal_dir):
+        return mempal_dir
+    if transcript_path:
+        path = Path(transcript_path).expanduser()
+        if path.is_file():
+            return str(path.parent)
+    return ""
+
+
+_MINE_PID_FILE = STATE_DIR / "mine.pid"
+
+
+def _pid_alive(pid: int) -> bool:
+    """Cross-platform existence check for a PID.
+
+    On POSIX, ``os.kill(pid, 0)`` is the well-known no-op existence probe.
+    On Windows, ``os.kill`` maps to ``TerminateProcess(handle, sig)`` and
+    would *terminate* the target process with exit code ``sig`` — using
+    it here would kill our own mine child (or worse, the caller itself).
+    Use ``OpenProcess`` + ``GetExitCodeProcess`` via ctypes instead.
+    """
+    if sys.platform == "win32":
+        import ctypes
+        from ctypes import wintypes
+
+        PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+        STILL_ACTIVE = 259
+        kernel32 = ctypes.windll.kernel32
+        handle = kernel32.OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, False, pid)
+        if not handle:
+            return False
         try:
-            log_path = STATE_DIR / "hook.log"
-            with open(log_path, "a") as log_f:
-                subprocess.Popen(
-                    [sys.executable, "-m", "mempalace", "mine", mempal_dir],
-                    stdout=log_f,
-                    stderr=log_f,
+            code = wintypes.DWORD()
+            if not kernel32.GetExitCodeProcess(handle, ctypes.byref(code)):
+                return False
+            return code.value == STILL_ACTIVE
+        finally:
+            kernel32.CloseHandle(handle)
+    try:
+        os.kill(pid, 0)
+        return True
+    except (OSError, ValueError):
+        return False
+
+
+def _mine_already_running() -> bool:
+    """Return True if a background mine process from a previous hook fire is still alive."""
+    try:
+        pid = int(_MINE_PID_FILE.read_text().strip())
+    except (OSError, ValueError):
+        return False
+    return _pid_alive(pid)
+
+
+def _spawn_mine(cmd: list) -> None:
+    """Spawn a mine subprocess, write its PID to the lock file, log to hook.log."""
+    STATE_DIR.mkdir(parents=True, exist_ok=True)
+    log_path = STATE_DIR / "hook.log"
+    with open(log_path, "a") as log_f:
+        proc = subprocess.Popen(cmd, stdout=log_f, stderr=log_f)
+    _MINE_PID_FILE.write_text(str(proc.pid))
+
+
+def _maybe_auto_ingest(transcript_path: str = ""):
+    """Run mempalace mine in background if a mine directory is available."""
+    mine_dir = _get_mine_dir(transcript_path)
+    if not mine_dir:
+        return
+    if _mine_already_running():
+        _log("Skipping auto-ingest: mine already running")
+        return
+    try:
+        _spawn_mine([sys.executable, "-m", "mempalace", "mine", mine_dir])
+    except OSError:
+        pass
+
+
+def _mine_sync(transcript_path: str = ""):
+    """Run mempalace mine synchronously (for precompact -- data must land first)."""
+    mine_dir = _get_mine_dir(transcript_path)
+    if not mine_dir:
+        return
+    try:
+        STATE_DIR.mkdir(parents=True, exist_ok=True)
+        log_path = STATE_DIR / "hook.log"
+        with open(log_path, "a") as log_f:
+            subprocess.run(
+                [sys.executable, "-m", "mempalace", "mine", mine_dir],
+                stdout=log_f,
+                stderr=log_f,
+                timeout=60,
+            )
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+
+
+def _desktop_toast(body: str, title: str = "MemPalace"):
+    """Send a desktop notification via notify-send. Fails silently."""
+    try:
+        subprocess.Popen(
+            ["notify-send", "--app-name=MemPalace", "--icon=brain", title, body],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+    except OSError:
+        pass
+
+
+def _extract_recent_messages(transcript_path: str, count: int = _RECENT_MSG_COUNT) -> list[str]:
+    """Extract the last N user messages from a JSONL transcript."""
+    path = Path(transcript_path).expanduser()
+    if not path.is_file():
+        return []
+    messages = []
+    try:
+        with open(path, encoding="utf-8", errors="replace") as f:
+            for line in f:
+                try:
+                    entry = json.loads(line)
+                    # Claude Code format
+                    msg = entry.get("message") or entry.get("event_message") or {}
+                    if isinstance(msg, dict) and msg.get("role") == "user":
+                        content = msg.get("content", "")
+                        if isinstance(content, list):
+                            content = " ".join(
+                                b.get("text", "") for b in content if isinstance(b, dict)
+                            )
+                        if not isinstance(content, str) or not content.strip():
+                            continue
+                        if "<command-message>" in content or "<system-reminder>" in content:
+                            continue
+                        messages.append(content.strip()[:200])
+                    # Codex CLI format
+                    elif entry.get("type") == "event_msg":
+                        payload = entry.get("payload", {})
+                        if isinstance(payload, dict) and payload.get("type") == "user_message":
+                            text = payload.get("message", "")
+                            if isinstance(text, str) and text.strip():
+                                if "<command-message>" not in text:
+                                    messages.append(text.strip()[:200])
+                except (json.JSONDecodeError, AttributeError):
+                    pass
+    except OSError:
+        return []
+    return messages[-count:]
+
+
+_THEME_STOPWORDS = frozenset(
+    "the a an and or but in on at to for of is it i me my you your we our "
+    "this that with from by was were be been are not no yes can do did dont "
+    "will would should could have has had lets let just also like so if then "
+    "ok okay sure yeah hey hi here there what when where how why which some "
+    "all any each every about into out up down over after before between "
+    "get got make made need want use used using check look see run try "
+    "know think right now still already really very much more most too "
+    "file files code one two new first last next thing things way well".split()
+)
+
+
+def _extract_themes(messages: list[str], max_themes: int = 3) -> list[str]:
+    """Pull 2-3 distinctive topic words from recent messages.
+
+    Note: stopword list is English-only; non-English corpora will produce noisy themes.
+    """
+    from collections import Counter
+
+    words: Counter[str] = Counter()
+    for msg in messages:
+        for word in msg.lower().split():
+            # Strip punctuation, keep words 4+ chars
+            clean = word.strip(".,;:!?\"'`()[]{}#<>/\\-_=+@$%^&*~")
+            if len(clean) >= 4 and clean not in _THEME_STOPWORDS and clean.isalpha():
+                words[clean] += 1
+    return [w for w, _ in words.most_common(max_themes)]
+
+
+def _save_diary_direct(
+    transcript_path: str,
+    session_id: str,
+    wing: str = "",
+    toast: bool = False,
+) -> dict:
+    """Write a diary checkpoint by calling the tool function directly (no MCP roundtrip).
+
+    If `wing` is set, the entry lands in that wing (typically the project wing
+    derived from the transcript path). Otherwise falls back to `tool_diary_write`'s
+    default of `wing_session-hook`.
+
+    Returns {"count": N, "themes": [...]} on success, {"count": 0} on failure.
+    """
+    messages = _extract_recent_messages(transcript_path)
+    if not messages:
+        _log("No recent messages to save")
+        return {"count": 0}
+
+    themes = _extract_themes(messages)
+
+    # Build a compressed diary entry from recent conversation
+    now = datetime.now()
+    topics = "|".join(m[:80] for m in messages[-10:])
+    entry = (
+        f"CHECKPOINT:{now.strftime('%Y-%m-%d')}|session:{session_id}"
+        f"|msgs:{len(messages)}|recent:{topics}"
+    )
+
+    try:
+        from .mcp_server import tool_diary_write
+
+        result = tool_diary_write(
+            agent_name="session-hook",
+            entry=entry,
+            topic="checkpoint",
+            wing=wing,
+        )
+        if result.get("success"):
+            _log(f"Diary checkpoint saved: {result.get('entry_id', '?')}")
+            # Write state for ack tool to read
+            try:
+                ack_file = STATE_DIR / "last_checkpoint"
+                ack_file.write_text(
+                    json.dumps({"msgs": len(messages), "ts": now.isoformat()}),
+                    encoding="utf-8",
                 )
-        except OSError:
-            pass
+            except OSError:
+                pass
+            if toast:
+                _desktop_toast(f"Checkpoint saved \u2014 {len(messages)} messages archived")
+            return {"count": len(messages), "themes": themes}
+        else:
+            _log(f"Diary checkpoint failed: {result.get('error', 'unknown')}")
+    except Exception as e:
+        _log(f"Diary checkpoint error: {e}")
+    return {"count": 0}
+
+
+def _ingest_transcript(transcript_path: str):
+    """Mine a Claude Code session transcript into the palace as a conversation."""
+    path = Path(transcript_path).expanduser()
+    if not path.is_file() or path.stat().st_size < 100:
+        return
+
+    from .config import MempalaceConfig
+
+    try:
+        MempalaceConfig()  # validate config loads
+    except Exception:
+        return
+
+    try:
+        log_path = STATE_DIR / "hook.log"
+        STATE_DIR.mkdir(parents=True, exist_ok=True)
+        with open(log_path, "a") as log_f:
+            subprocess.Popen(
+                [
+                    _mempalace_python(),
+                    "-m",
+                    "mempalace",
+                    "mine",
+                    str(path.parent),
+                    "--mode",
+                    "convos",
+                    "--wing",
+                    "sessions",
+                ],
+                stdout=log_f,
+                stderr=log_f,
+            )
+        _log(f"Transcript ingest started: {path.name}")
+    except OSError:
+        pass
 
 
 SUPPORTED_HARNESSES = {"claude-code", "codex"}
@@ -130,6 +487,39 @@ def _parse_harness_input(data: dict, harness: str) -> dict:
     }
 
 
+def _wing_from_transcript_path(transcript_path: str) -> str:
+    """Derive a project wing name from a Claude Code transcript path.
+
+    Claude Code encodes the project's source directory by replacing path
+    separators with dashes, producing folders like:
+        ~/.claude/projects/-home-<user>-Projects-<project>/session.jsonl
+        ~/.claude/projects/-home-<user>-dev-<parent>-<project>/session.jsonl
+        ~/.claude/projects/-Users-<user>-<folder>-<project>/session.jsonl
+
+    The project directory name is the final dash-separated token of the
+    encoded folder. Returns ``wing_<project>`` (lowercased, spaces → ``_``).
+    Falls back to ``wing_sessions`` if the path does not match a Claude Code
+    project-folder layout.
+    """
+    # Normalize path separators for cross-platform (Windows backslashes)
+    normalized = transcript_path.replace("\\", "/")
+    # Primary: pull the encoded project folder out of ``.claude/projects/``
+    # and take its last dash-separated token.
+    match = re.search(r"/\.claude/projects/-([^/]+)", normalized)
+    if match:
+        encoded = match.group(1)
+        project = encoded.rsplit("-", 1)[-1]
+        if project:
+            return f"wing_{project.lower().replace(' ', '_')}"
+    # Legacy fallback: explicit ``-Projects-<name>`` segment, useful for
+    # transcripts not under the standard Claude Code projects dir.
+    match = re.search(r"-Projects-([^/]+?)(?:/|$)", normalized)
+    if match:
+        project = match.group(1).lower().replace(" ", "_")
+        return f"wing_{project}"
+    return "wing_sessions"
+
+
 def hook_stop(data: dict, harness: str):
     """Stop hook: block every N messages for auto-save."""
     parsed = _parse_harness_input(data, harness)
@@ -137,10 +527,29 @@ def hook_stop(data: dict, harness: str):
     stop_hook_active = parsed["stop_hook_active"]
     transcript_path = parsed["transcript_path"]
 
-    # If already in a save cycle, let through (infinite-loop prevention)
+    # If already in a block-mode save cycle, let through (infinite-loop prevention).
+    # Silent mode saves directly without returning {"decision":"block"}, so there's
+    # no loop to prevent — and Claude Code's plugin dispatch sets this flag on every
+    # fire after the first, which would otherwise suppress all subsequent auto-saves.
     if str(stop_hook_active).lower() in ("true", "1", "yes"):
-        _output({})
-        return
+        # Safe default: assume silent mode on any config-read failure so saves
+        # proceed rather than being silently dropped. Silent mode is the default
+        # (v3.3.0+), so if we can't read config, behave as if it's still on.
+        silent_guard = True
+        try:
+            from .config import MempalaceConfig
+        except ImportError as exc:
+            _log(
+                f"WARNING: could not import MempalaceConfig for stop guard: {exc}; defaulting to silent mode"
+            )
+        else:
+            try:
+                silent_guard = MempalaceConfig().hook_silent_save
+            except AttributeError as exc:
+                _log(f"WARNING: could not read hook_silent_save: {exc}; defaulting to silent mode")
+        if not silent_guard:
+            _output({})
+            return
 
     # Count human messages
     exchange_count = _count_human_messages(transcript_path)
@@ -160,18 +569,62 @@ def hook_stop(data: dict, harness: str):
     _log(f"Session {session_id}: {exchange_count} exchanges, {since_last} since last save")
 
     if since_last >= SAVE_INTERVAL and exchange_count > 0:
-        # Update last save point
-        try:
-            last_save_file.write_text(str(exchange_count), encoding="utf-8")
-        except OSError:
-            pass
-
         _log(f"TRIGGERING SAVE at exchange {exchange_count}")
 
-        # Optional: auto-ingest if MEMPAL_DIR is set
-        _maybe_auto_ingest()
+        # Read hook settings from config
+        from .config import MempalaceConfig
 
-        _output({"decision": "block", "reason": STOP_BLOCK_REASON})
+        try:
+            config = MempalaceConfig()
+            silent = config.hook_silent_save
+            toast = config.hook_desktop_toast
+        except Exception:
+            silent = True
+            toast = False
+
+        project_wing = _wing_from_transcript_path(transcript_path)
+
+        if silent:
+            # Save directly via Python API — systemMessage renders in terminal
+            result = {"count": 0}
+            if transcript_path:
+                result = _save_diary_direct(
+                    transcript_path, session_id, wing=project_wing, toast=toast
+                )
+                _ingest_transcript(transcript_path)
+            _maybe_auto_ingest(transcript_path)
+            # Only advance save marker after successful save
+            count = result.get("count", 0)
+            if count > 0:
+                try:
+                    last_save_file.write_text(str(exchange_count), encoding="utf-8")
+                except OSError:
+                    pass
+                themes = result.get("themes", [])
+                if themes:
+                    tag = " \u2014 " + ", ".join(themes)
+                else:
+                    tag = ""
+                _output(
+                    {
+                        "systemMessage": f"\u2726 {count} memories woven into the palace{tag}",
+                    }
+                )
+            else:
+                _output({})
+        else:
+            # Legacy: block and ask Claude to save via MCP tools.
+            # Marker advances before confirmed save — best-effort; if Claude
+            # fails to save, the checkpoint is lost but won't retry endlessly.
+            try:
+                last_save_file.write_text(str(exchange_count), encoding="utf-8")
+            except OSError:
+                pass
+            if transcript_path:
+                _ingest_transcript(transcript_path)
+            _maybe_auto_ingest(transcript_path)
+            reason = STOP_BLOCK_REASON + f" Write diary entry to wing={project_wing}."
+            _output({"decision": "block", "reason": reason})
     else:
         _output({})
 
@@ -191,29 +644,21 @@ def hook_session_start(data: dict, harness: str):
 
 
 def hook_precompact(data: dict, harness: str):
-    """Precompact hook: always block with comprehensive save instruction."""
+    """Precompact hook: mine transcript synchronously, then allow compaction."""
     parsed = _parse_harness_input(data, harness)
     session_id = parsed["session_id"]
+    transcript_path = parsed["transcript_path"]
 
     _log(f"PRE-COMPACT triggered for session {session_id}")
 
-    # Optional: auto-ingest synchronously before compaction (so memories land first)
-    mempal_dir = os.environ.get("MEMPAL_DIR", "")
-    if mempal_dir and os.path.isdir(mempal_dir):
-        try:
-            log_path = STATE_DIR / "hook.log"
-            with open(log_path, "a") as log_f:
-                subprocess.run(
-                    [sys.executable, "-m", "mempalace", "mine", mempal_dir],
-                    stdout=log_f,
-                    stderr=log_f,
-                    timeout=60,
-                )
-        except OSError:
-            pass
+    # Capture tool output via our normalize path before compaction loses it
+    if transcript_path:
+        _ingest_transcript(transcript_path)
 
-    # Always block -- compaction = save everything
-    _output({"decision": "block", "reason": PRECOMPACT_BLOCK_REASON})
+    # Mine synchronously so data lands before compaction proceeds
+    _mine_sync(transcript_path)
+
+    _output({})
 
 
 def run_hook(hook_name: str, harness: str):

mempalace/i18n/__init__.py

@@ -7,15 +7,40 @@ Usage:
     print(t("cli.mine_start", path="/docs"))  # "Extraction de /docs..."
     print(t("terms.wing"))    # "aile"
     print(t("aaak.instruction"))  # AAAK compression instruction in French
+
+Each locale JSON may include an ``entity`` section with patterns used by
+``mempalace.entity_detector``. See ``get_entity_patterns`` for the merge rules
+and the README section "Adding a new language" for the schema.
 """
 
 import json
 from pathlib import Path
+from typing import Optional
 
 _LANG_DIR = Path(__file__).parent
 _strings: dict = {}
 _current_lang: str = "en"
 
+# Cache: tuple(langs) -> merged entity pattern dict
+_entity_cache: dict = {}
+
+
+def _canonical_lang(lang: str) -> Optional[str]:
+    """Resolve a language code to its on-disk canonical filename stem.
+
+    BCP 47 tags are case-insensitive (RFC 5646 §2.1.1), and the locale
+    files mix conventions (``pt-br.json`` vs ``zh-CN.json``). Match on
+    lowercase so callers can pass ``PT-BR``, ``zh-cn``, ``Pt-Br``, etc.
+    Returns ``None`` if no file matches.
+    """
+    if not lang:
+        return None
+    target = lang.strip().lower()
+    for path in _LANG_DIR.glob("*.json"):
+        if path.stem.lower() == target:
+            return path.stem
+    return None
+
 
 def available_languages() -> list[str]:
     """Return list of available language codes."""
@@ -25,12 +50,12 @@ def available_languages() -> list[str]:
 def load_lang(lang: str = "en") -> dict:
     """Load a language dictionary. Falls back to English if not found."""
     global _strings, _current_lang
-    lang_file = _LANG_DIR / f"{lang}.json"
-    if not lang_file.exists():
-        lang_file = _LANG_DIR / "en.json"
-        lang = "en"
+    canonical = _canonical_lang(lang)
+    if canonical is None:
+        canonical = "en"
+    lang_file = _LANG_DIR / f"{canonical}.json"
     _strings = json.loads(lang_file.read_text(encoding="utf-8"))
-    _current_lang = lang
+    _current_lang = canonical
     return _strings
 
 
@@ -72,5 +97,189 @@ def get_regex() -> dict:
     return _strings.get("regex", {})
 
 
+def _load_entity_section(lang: str) -> dict:
+    """Load the raw entity section for one language. Returns {} if missing."""
+    canonical = _canonical_lang(lang)
+    if canonical is None:
+        return {}
+    lang_file = _LANG_DIR / f"{canonical}.json"
+    try:
+        data = json.loads(lang_file.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return {}
+    return data.get("entity", {}) or {}
+
+
+def _script_boundary(chars: str) -> str:
+    """Build a lookaround-based word boundary expression.
+
+    Python's built-in ``\\b`` is a transition between ``\\w`` and non-``\\w``.
+    ``\\w`` covers Unicode Letter and Number categories but NOT Marks (category
+    Mc/Mn), so for scripts whose words contain combining vowel signs — Devanagari
+    (ा ी ु), Arabic (ـَ ـِ ـُ), Hebrew (ִ ֵ), Thai, Tamil, Burmese, Khmer — the
+    default ``\\b`` drops the trailing mark, truncating names like ``अनीता`` to
+    ``अनीत`` and failing to match ``\\bकहा\\b`` because the trailing matra is
+    not a word character.
+
+    Locales with such scripts declare ``boundary_chars`` in their entity section
+    (e.g. ``"\\\\w\\\\u0900-\\\\u097F"`` for Hindi). This function returns a
+    regex fragment equivalent to ``\\b`` but where the "word" side is defined
+    as any char matching ``[chars]`` rather than just ``\\w``.
+    """
+    return (
+        rf"(?:(?<=[{chars}])(?=[^{chars}])"
+        rf"|(?<=[^{chars}])(?=[{chars}])"
+        rf"|^(?=[{chars}])"
+        rf"|(?<=[{chars}])$)"
+    )
+
+
+def _expand_b(pattern: str, boundary_chars: str) -> str:
+    """Replace every literal ``\\b`` in ``pattern`` with a script-aware boundary.
+
+    ``boundary_chars`` is the inside-word character class (without brackets).
+    If it's falsy, the pattern is returned unchanged so ``\\b`` keeps its
+    default Python ``re`` semantics.
+    """
+    if not boundary_chars:
+        return pattern
+    return pattern.replace(r"\b", _script_boundary(boundary_chars))
+
+
+def _wrap_candidate(raw_pat: str, boundary_chars: str) -> str:
+    """Wrap a candidate/multi-word extraction pattern with a capture group
+    and word boundaries appropriate for its locale.
+
+    Default: ``\\b(raw)\\b``. With ``boundary_chars``: the script-aware
+    equivalent, so names ending in combining marks are matched in full.
+    """
+    if boundary_chars:
+        b = _script_boundary(boundary_chars)
+        return f"{b}({raw_pat}){b}"
+    return rf"\b({raw_pat})\b"
+
+
+def _collect_entity_section(section: dict, acc: dict) -> None:
+    """Merge one language's entity section into the running accumulator.
+
+    Handles boundary expansion in-place so the caller merges already-expanded
+    strings: `candidate_patterns` and `multi_word_patterns` are pre-wrapped
+    with the locale's boundary (capture group included, ready to compile);
+    every ``\\b`` inside person/pronoun/dialogue/project/direct patterns is
+    replaced with the locale's script-aware boundary.
+    """
+    boundary_chars = section.get("boundary_chars")
+    if section.get("candidate_pattern"):
+        acc["candidate_patterns"].append(
+            _wrap_candidate(section["candidate_pattern"], boundary_chars)
+        )
+    if section.get("multi_word_pattern"):
+        acc["multi_word_patterns"].append(
+            _wrap_candidate(section["multi_word_pattern"], boundary_chars)
+        )
+    if section.get("direct_address_pattern"):
+        acc["direct_address"].append(_expand_b(section["direct_address_pattern"], boundary_chars))
+    acc["person_verbs"].extend(
+        _expand_b(p, boundary_chars) for p in section.get("person_verb_patterns", [])
+    )
+    acc["pronouns"].extend(
+        _expand_b(p, boundary_chars) for p in section.get("pronoun_patterns", [])
+    )
+    acc["dialogue"].extend(
+        _expand_b(p, boundary_chars) for p in section.get("dialogue_patterns", [])
+    )
+    acc["project_verbs"].extend(
+        _expand_b(p, boundary_chars) for p in section.get("project_verb_patterns", [])
+    )
+    acc["stopwords"].update(w.lower() for w in section.get("stopwords", []))
+
+
+def get_entity_patterns(languages=("en",)) -> dict:
+    """Return merged entity detection patterns for the requested languages.
+
+    Entity detection patterns live under each locale's ``entity`` section.
+    This function merges them into a single dict for consumption by
+    ``mempalace.entity_detector``.
+
+    Merge rules:
+      - List fields (person_verb_patterns, pronoun_patterns, dialogue_patterns,
+        project_verb_patterns) are concatenated in the order of ``languages``,
+        with duplicates removed while preserving first occurrence.
+      - ``stopwords`` is the set union across all languages, returned as a
+        sorted list.
+      - ``candidate_patterns`` and ``multi_word_patterns`` are returned as
+        **fully-wrapped regex strings** (boundary + capture group applied);
+        the consumer compiles them directly with no further wrapping.
+      - ``direct_address_pattern`` is returned as a list of per-language
+        alternation patterns (not concatenated — each is applied separately).
+
+    Locales with combining-mark scripts can declare ``boundary_chars`` in
+    their entity section (e.g. ``"\\\\w\\\\u0900-\\\\u097F"`` for Hindi);
+    every ``\\b`` inside that locale's patterns — plus the candidate/multi-
+    word wrapping — is expanded to a script-aware lookaround boundary that
+    treats the declared characters as "inside-word".
+
+    If ``languages`` is empty or no requested language declares entity data,
+    English is used as a fallback so callers always get a working config.
+    """
+    if not languages:
+        languages = ("en",)
+    # Normalize via canonical filename so callers using different casing
+    # (e.g. "PT-BR" vs "pt-br") share the same cache entry and load the
+    # same locale file. Unknown codes are kept as-is so the merge loop's
+    # "found_any" branch fires the English fallback exactly once.
+    languages = tuple(_canonical_lang(lang) or lang for lang in languages)
+    key = languages
+    if key in _entity_cache:
+        return _entity_cache[key]
+
+    acc = {
+        "candidate_patterns": [],
+        "multi_word_patterns": [],
+        "person_verbs": [],
+        "pronouns": [],
+        "dialogue": [],
+        "direct_address": [],
+        "project_verbs": [],
+        "stopwords": set(),
+    }
+
+    found_any = False
+    for lang in languages:
+        section = _load_entity_section(lang)
+        if not section:
+            continue
+        found_any = True
+        _collect_entity_section(section, acc)
+
+    if not found_any:
+        # Fallback: load English directly so callers always get a working config.
+        _collect_entity_section(_load_entity_section("en"), acc)
+
+    merged = {
+        "candidate_patterns": acc["candidate_patterns"],
+        "multi_word_patterns": acc["multi_word_patterns"],
+        "person_verb_patterns": _dedupe(acc["person_verbs"]),
+        "pronoun_patterns": _dedupe(acc["pronouns"]),
+        "dialogue_patterns": _dedupe(acc["dialogue"]),
+        "direct_address_patterns": acc["direct_address"],
+        "project_verb_patterns": _dedupe(acc["project_verbs"]),
+        "stopwords": sorted(acc["stopwords"]),
+    }
+    _entity_cache[key] = merged
+    return merged
+
+
+def _dedupe(items: list) -> list:
+    """Remove duplicates while preserving first-occurrence order."""
+    seen = set()
+    out = []
+    for item in items:
+        if item not in seen:
+            seen.add(item)
+            out.append(item)
+    return out
+
+
 # Auto-load English on import
 load_lang("en")

mempalace/i18n/be.json

@@ -0,0 +1,166 @@
+{
+  "lang": "be",
+  "label": "Беларуская",
+  "terms": {
+    "palace": "палац",
+    "wing": "крыло",
+    "hall": "зала",
+    "closet": "шафа",
+    "drawer": "шуфляда",
+    "mine": "майнінг",
+    "search": "пошук",
+    "status": "статус",
+    "init": "ініцыялізацыя",
+    "repair": "аднаўленне",
+    "migrate": "міграцыя",
+    "entity": "аб'ект",
+    "topic": "тэма"
+  },
+  "cli": {
+    "mine_start": "Майнінг {path}...",
+    "mine_complete": "Гатова. Створана шаф: {closets}, шуфляд: {drawers}.",
+    "mine_skip": "Майнінг скончаны. Выкарыстайце --force, каб перамайніць.",
+    "search_no_results": "Няма вынікаў для: {query}",
+    "search_results": "Знойдзена {count} вынікаў:",
+    "status_palace": "Палац: {path}",
+    "status_wings": "Крылаў: {count}",
+    "status_closets": "Шаф: {count}",
+    "status_drawers": "Шуфляд: {count}",
+    "init_complete": "Палац ініцыялізаваны ў {path}",
+    "init_exists": "Палац ужо існуе ў {path}",
+    "repair_complete": "Аднаўленне скончана. Выпраўлена праблем: {fixed}.",
+    "migrate_complete": "Міграцыя завершана.",
+    "no_palace": "Палац не знойдзены. Запусціце: mempalace init <дырэкторыя>"
+  },
+  "aaak": {
+    "instruction": "Сцісні да фармату індэкса. Злучкі паміж словамі, вертыкальныя рысы паміж паняткамі. Выдалі падставы і службовыя словы. Захавай дакладнасць імёнаў, нумароў, скланенняў і формаў."
+  },
+  "regex": {
+    "topic_pattern": "[А-ЯЁІЎ][а-яёіў]{2,}|[A-Z][a-z]{2,}|[A-Za-z][A-Za-z0-9_]{2,}",
+    "stop_words": "і а але бо каб калі калісьці хоць што хто дзе куды адкуль як чаму таму ж не ні так таксама яшчэ ўжо цяпер потым тут там адсюль туды ў на па з са без для над пад пры пра праз супраць замест акрамя сярод вакол уздоўж каля паміж пасля перад да ад у або альбо то ці быццам нібыта вось гэты гэта гэтыя той тая тыя некаторыя кожны кожная кожныя толькі вельмі можа трэба будзе быў была былі ёсць няма",
+    "quote_pattern": "«\\s*([^»]{10,200})\\s*»|\"([^\"]{10,200})\"",
+    "action_pattern": "(?:зрабіў|зрабіла|зрабілі|стварыў|стварыла|стварылі|дадаў|дадала|дадалі|абнавіў|абнавіла|абнавілі|наладзіў|наладзіла|наладзілі|пратэставаў|пратэставала|пратэставалі)\\s+[\\wа-яёА-ЯЁІіЎў\\s]{3,30}"
+  },
+  "entity": {
+    "candidate_pattern": "[А-ЯЁІЎ][а-яёіў]{1,19}",
+    "multi_word_pattern": "[А-ЯЁІЎ][а-яёіў]+(?:\\s+[А-ЯЁІЎ][а-яёіў]+)+",
+    "person_verb_patterns": [
+      "\\b{name}\\s+сказа(?:ў|ла|лі)\\b",
+      "\\b{name}\\s+спыта(?:ў|ла|лі)\\b",
+      "\\b{name}\\s+адказа(?:ў|ла|лі)\\b",
+      "\\b{name}\\s+расказа(?:ў|ла|лі)\\b",
+      "\\b{name}\\s+засмея(?:ўся|лася|ліся)\\b",
+      "\\b{name}\\s+усміхну(?:ўся|лася|ліся)\\b",
+      "\\b{name}\\s+заплака(?:ў|ла|лі)\\b",
+      "\\b{name}\\s+адчу(?:ў|ла|лі)\\b",
+      "\\b{name}\\s+думае\\b",
+      "\\b{name}\\s+хоча\\b",
+      "\\b{name}\\s+кахае\\b",
+      "\\b{name}\\s+ненавідзіць\\b",
+      "\\b{name}\\s+ведае\\b",
+      "\\b{name}\\s+вырашы(?:ў|ла|лі)\\b",
+      "\\b{name}\\s+напіса(?:ў|ла|лі)\\b",
+      "\\b{name}\\s+каза(?:ў|ла|лі)\\b",
+      "\\b{name}\\s+зрабі(?:ў|ла|лі)\\b",
+      "\\b{name}\\s+спытваецца\\b",
+      "\\b{name}\\s+адказвае\\b"
+    ],
+    "pronoun_patterns": [
+      "\\bён\\b",
+      "\\bяго\\b",
+      "\\bяму\\b",
+      "\\bім\\b",
+      "\\bяна\\b",
+      "\\bяе\\b",
+      "\\bёй\\b",
+      "\\bёю\\b",
+      "\\bяны\\b",
+      "\\bіх\\b",
+      "\\bімі\\b",
+      "\\bяно\\b",
+      "\\bвы\\b",
+      "\\bвас\\b",
+      "\\bвам\\b",
+      "\\bвамі\\b"
+    ],
+    "dialogue_patterns": [
+      "^>\\s*{name}[:\\s]",
+      "^{name}:\\s",
+      "^\\[{name}\\]",
+      "\"{name}\\s+сказа(?:ў|ла|лі)"
+    ],
+    "direct_address_pattern": "\\bпрывітанне[,:!.]?\\s+{name}\\b|\\bвітаю[,:!.]?\\s+{name}\\b|\\bдзякуй[,:!.]?\\s+{name}\\b|\\bдарагі[,:!.]?\\s+{name}\\b|\\bдарагая[,:!.]?\\s+{name}\\b|\\bпаважаны[,:!.]?\\s+{name}\\b|\\bпаважаная[,:!.]?\\s+{name}\\b",
+    "project_verb_patterns": [
+      "\\bзбіраю\\s+{name}\\b",
+      "\\bсабраў\\s+{name}\\b",
+      "\\bзапускаю\\s+{name}\\b",
+      "\\bзапусціў\\s+{name}\\b",
+      "\\bразгарнуў\\s+{name}\\b",
+      "\\bусталяваў\\s+{name}\\b",
+      "\\bсістэма\\s+{name}\\b",
+      "\\bпраект\\s+{name}\\b",
+      "\\bimport\\s+{name}\\b",
+      "\\bpip\\s+install\\s+{name}\\b"
+    ],
+    "stopwords": [
+      "і",
+      "ў",
+      "з",
+      "са",
+      "на",
+      "па",
+      "да",
+      "ад",
+      "у",
+      "без",
+      "для",
+      "над",
+      "пад",
+      "пры",
+      "пра",
+      "праз",
+      "супраць",
+      "замест",
+      "акрамя",
+      "сярод",
+      "вакол",
+      "уздоўж",
+      "каля",
+      "паміж",
+      "пасля",
+      "перад",
+      "або",
+      "альбо",
+      "каб",
+      "калі",
+      "хоць",
+      "бо",
+      "ж",
+      "не",
+      "ні",
+      "так",
+      "яшчэ",
+      "ужо",
+      "цяпер",
+      "вось",
+      "гэта",
+      "тое",
+      "тут",
+      "там",
+      "вельмі",
+      "толькі",
+      "можа",
+      "трэба",
+      "ёсць",
+      "няма",
+      "як",
+      "што",
+      "хто",
+      "чаму",
+      "таму",
+      "прывітанне",
+      "дзякуй",
+      "ласка"
+    ]
+  }
+}

mempalace/i18n/de.json

@@ -40,5 +40,87 @@
     "stop_words": "der die das ein eine eines einer einem einen den dem des und oder aber denn weil wenn als ob auch noch schon sehr viel nur nicht mehr kann wird hat ist sind war waren sein haben wurde mit von zu für auf in an um über nach durch",
     "quote_pattern": "\\u201E([^\\u201C]{10,200})\\u201C|\"([^\"]{10,200})\"",
     "action_pattern": "(?:gebaut|behoben|geschrieben|hinzugefügt|gepusht|gemessen|getestet|überprüft|erstellt|gelöscht|aktualisiert|konfiguriert|bereitgestellt|migriert)\\s+[\\wÄÖÜäöüß\\s]{3,30}"
+  },
+  "entity": {
+    "candidate_pattern": "[A-ZÄÖÜ][a-zäöüß]{1,19}",
+    "multi_word_pattern": "[A-ZÄÖÜ][a-zäöüß]+(?:\\s+[A-ZÄÖÜ][a-zäöüß]+)+",
+    "person_verb_patterns": [
+      "\\b{name}\\s+sagte\\b",
+      "\\b{name}\\s+fragte\\b",
+      "\\b{name}\\s+antwortete\\b",
+      "\\b{name}\\s+erzählte\\b",
+      "\\b{name}\\s+lachte\\b",
+      "\\b{name}\\s+lächelte\\b",
+      "\\b{name}\\s+weinte\\b",
+      "\\b{name}\\s+fühlte\\b",
+      "\\b{name}\\s+denkt\\b",
+      "\\b{name}\\s+will\\b",
+      "\\b{name}\\s+liebt\\b",
+      "\\b{name}\\s+hasst\\b",
+      "\\b{name}\\s+weiß\\b",
+      "\\b{name}\\s+entschied\\b",
+      "\\b{name}\\s+schrieb\\b"
+    ],
+    "pronoun_patterns": [
+      "\\ber\\b",
+      "\\bsie\\b",
+      "\\bes\\b",
+      "\\bihn\\b",
+      "\\bihm\\b",
+      "\\bihr\\b",
+      "\\bsein\\b",
+      "\\bihre\\b",
+      "\\bihnen\\b"
+    ],
+    "dialogue_patterns": [
+      "^>\\s*{name}[:\\s]",
+      "^{name}:\\s",
+      "^\\[{name}\\]",
+      "\"{name}\\s+sagte"
+    ],
+    "direct_address_pattern": "\\bhallo\\s+{name}\\b|\\bhi\\s+{name}\\b|\\bhey\\s+{name}\\b|\\bdanke\\s+{name}\\b|\\bservus\\s+{name}\\b|\\blieber\\s+{name}\\b|\\bliebe\\s+{name}\\b|\\bsehr\\s+geehrter\\s+{name}\\b|\\bsehr\\s+geehrte\\s+{name}\\b",
+    "project_verb_patterns": [
+      "\\bbaue\\s+{name}\\b",
+      "\\bgebaut\\s+{name}\\b",
+      "\\bstarte\\s+{name}\\b",
+      "\\bgestartet\\s+{name}\\b",
+      "\\bdeploye\\s+{name}\\b",
+      "\\binstalliert\\s+{name}\\b",
+      "\\bdie\\s+{name}\\s+architektur\\b",
+      "\\bdie\\s+{name}\\s+pipeline\\b",
+      "\\bdas\\s+{name}\\s+system\\b",
+      "\\bdas\\s+{name}\\s+repository\\b",
+      "\\b{name}\\s+v\\d+\\b",
+      "\\b{name}\\.py\\b",
+      "\\bimport\\s+{name}\\b",
+      "\\bpip\\s+install\\s+{name}\\b"
+    ],
+    "stopwords": [
+      "der", "die", "das", "ein", "eine", "eines", "einer", "einem", "einen",
+      "den", "dem", "des", "und", "oder", "aber", "denn", "weil", "wenn", "als",
+      "ob", "auch", "noch", "schon", "sehr", "viel", "nur", "nicht", "mehr",
+      "kann", "wird", "hat", "ist", "sind", "war", "waren", "sein", "haben",
+      "wurde", "worden", "werden", "mit", "von", "zu", "für", "auf", "in",
+      "an", "um", "über", "nach", "durch", "bei", "aus", "seit", "vor", "zwischen",
+      "ich", "du", "er", "sie", "es", "wir", "ihr", "mich", "dich", "mir", "dir",
+      "uns", "euch", "mein", "dein", "unser", "euer", "ihre", "seine",
+      "wer", "was", "wann", "wo", "wie", "warum", "welcher", "welche", "welches",
+      "so", "dann", "jetzt", "heute", "gestern", "morgen", "hier", "dort", "da",
+      "immer", "nie", "manchmal", "oft", "selten", "bald", "spät",
+      "ja", "nein", "vielleicht", "gut", "schlecht", "besser", "bitte", "danke",
+      "hallo", "hi", "hey", "tschüss",
+      "tag", "tage", "woche", "monat", "jahr", "jahre", "zeit", "welt", "leben",
+      "mensch", "menschen", "leute", "person", "ding", "dinge", "sache", "sachen",
+      "teil", "art", "weise", "stelle", "platz", "ort", "zimmer", "haus", "land",
+      "grund", "frage", "antwort", "fakt", "sinn", "idee", "punkt", "fall", "aspekt",
+      "beispiel", "version", "nummer", "zahl", "name", "namen", "system", "modell",
+      "sprache", "technologie", "gesellschaft", "kultur", "geschichte",
+      "wissenschaft", "zukunft", "erinnerung", "gedächtnis",
+      "datei", "ordner", "pfad", "schlüssel", "wert", "fehler", "warnung",
+      "ergebnis", "eingabe", "ausgabe", "quelle", "ziel", "daten", "elemente",
+      "montag", "dienstag", "mittwoch", "donnerstag", "freitag", "samstag", "sonntag",
+      "januar", "februar", "märz", "april", "mai", "juni", "juli", "august",
+      "september", "oktober", "november", "dezember"
+    ]
   }
 }

mempalace/i18n/en.json

@@ -40,5 +40,117 @@
     "stop_words": "the this that these those some many most each every other only such very will would could should must shall yeah okay also even then now already still back done make take give know think want need going come find work added saved session summary conversation topics source about once just really actually here there where good great better thank please sorry right wrong true false",
     "quote_pattern": "\"([^\"]{20,200})\"",
     "action_pattern": "(?:built|fixed|wrote|added|pushed|measured|tested|reviewed|created|deleted|updated|configured|deployed|migrated)\\s+[\\w\\s]{3,30}"
+  },
+  "entity": {
+    "candidate_pattern": "[A-Z][a-z]+(?:[A-Z][a-z]+|[A-Z]{2,})+|[A-Z][a-z]{1,19}",
+    "multi_word_pattern": "[A-Z][a-z]+(?:\\s+[A-Z][a-z]+)+",
+    "person_verb_patterns": [
+      "\\b{name}\\s+said\\b",
+      "\\b{name}\\s+asked\\b",
+      "\\b{name}\\s+told\\b",
+      "\\b{name}\\s+replied\\b",
+      "\\b{name}\\s+laughed\\b",
+      "\\b{name}\\s+smiled\\b",
+      "\\b{name}\\s+cried\\b",
+      "\\b{name}\\s+felt\\b",
+      "\\b{name}\\s+thinks?\\b",
+      "\\b{name}\\s+wants?\\b",
+      "\\b{name}\\s+loves?\\b",
+      "\\b{name}\\s+hates?\\b",
+      "\\b{name}\\s+knows?\\b",
+      "\\b{name}\\s+decided\\b",
+      "\\b{name}\\s+pushed\\b",
+      "\\b{name}\\s+wrote\\b",
+      "\\bhey\\s+{name}\\b",
+      "\\bthanks?\\s+{name}\\b",
+      "\\bhi\\s+{name}\\b",
+      "\\bdear\\s+{name}\\b"
+    ],
+    "pronoun_patterns": [
+      "\\bshe\\b",
+      "\\bher\\b",
+      "\\bhers\\b",
+      "\\bhe\\b",
+      "\\bhim\\b",
+      "\\bhis\\b",
+      "\\bthey\\b",
+      "\\bthem\\b",
+      "\\btheir\\b"
+    ],
+    "dialogue_patterns": [
+      "^>\\s*{name}[:\\s]",
+      "^{name}:\\s",
+      "^\\[{name}\\]",
+      "\"{name}\\s+said"
+    ],
+    "direct_address_pattern": "\\bhey\\s+{name}\\b|\\bthanks?\\s+{name}\\b|\\bhi\\s+{name}\\b",
+    "project_verb_patterns": [
+      "\\bbuilding\\s+{name}\\b",
+      "\\bbuilt\\s+{name}\\b",
+      "\\bship(?:ping|ped)?\\s+{name}\\b",
+      "\\blaunch(?:ing|ed)?\\s+{name}\\b",
+      "\\bdeploy(?:ing|ed)?\\s+{name}\\b",
+      "\\binstall(?:ing|ed)?\\s+{name}\\b",
+      "\\bthe\\s+{name}\\s+architecture\\b",
+      "\\bthe\\s+{name}\\s+pipeline\\b",
+      "\\bthe\\s+{name}\\s+system\\b",
+      "\\bthe\\s+{name}\\s+repo\\b",
+      "\\b{name}\\s+v\\d+\\b",
+      "\\b{name}\\.py\\b",
+      "\\b{name}-core\\b",
+      "\\b{name}-local\\b",
+      "\\bimport\\s+{name}\\b",
+      "\\bpip\\s+install\\s+{name}\\b"
+    ],
+    "stopwords": [
+      "the", "a", "an", "and", "or", "but", "in", "on", "at", "to",
+      "for", "of", "with", "by", "from", "as", "is", "was", "are", "were",
+      "be", "been", "being", "have", "has", "had", "do", "does", "did",
+      "will", "would", "could", "should", "may", "might", "must", "shall", "can",
+      "this", "that", "these", "those", "it", "its", "they", "them", "their",
+      "we", "our", "you", "your", "i", "my", "me", "he", "she", "his", "her",
+      "who", "what", "when", "where", "why", "how", "which",
+      "if", "then", "so", "not", "no", "yes", "ok", "okay",
+      "just", "very", "really", "also", "already", "still", "even", "only",
+      "here", "there", "now", "too", "up", "out", "about", "like",
+      "use", "get", "got", "make", "made", "take", "put", "come", "go", "see",
+      "know", "think", "true", "false", "none", "null", "new", "old", "all", "any", "some",
+      "return", "print", "def", "class", "import",
+      "step", "usage", "run", "check", "find", "add", "set", "list",
+      "args", "dict", "str", "int", "bool", "path", "file", "type", "name",
+      "note", "example", "option", "result", "error", "warning", "info",
+      "every", "each", "more", "less", "next", "last", "first", "second",
+      "stack", "layer", "mode", "test", "stop", "start", "copy", "move",
+      "source", "target", "output", "input", "data", "item", "key", "value",
+      "returns", "raises", "yields", "self", "cls", "kwargs",
+      "world", "well", "want", "topic", "choose", "social", "cars", "phones",
+      "healthcare", "ex", "machina", "deus", "human", "humans", "people",
+      "things", "something", "nothing", "everything", "anything", "someone",
+      "everyone", "anyone", "way", "time", "day", "life", "place", "thing",
+      "part", "kind", "sort", "case", "point", "idea", "fact", "sense",
+      "question", "answer", "reason", "number", "version", "system",
+      "hey", "hi", "hello", "thanks", "thank", "right", "let",
+      "click", "hit", "press", "tap", "drag", "drop", "open", "close",
+      "save", "load", "launch", "install", "download", "upload", "scroll",
+      "select", "enter", "submit", "cancel", "confirm", "delete", "paste",
+      "write", "read", "search", "show", "hide",
+      "desktop", "documents", "downloads", "users", "home", "library",
+      "applications", "preferences", "settings", "terminal",
+      "actor", "vector", "remote", "control", "duration", "fetch",
+      "agents", "tools", "others", "guards", "ethics", "regulation",
+      "learning", "thinking", "memory", "language", "intelligence",
+      "technology", "society", "culture", "future", "history", "science",
+      "model", "models", "network", "networks", "training", "inference",
+      "created", "updated", "deleted", "added", "removed", "modified",
+      "extracted", "processed", "generated", "compiled", "launched", "installed",
+      "deployed", "executed", "loaded", "parsed", "validated", "configured",
+      "total", "summary", "covered", "included", "pending", "failed", "success",
+      "ready", "active", "disabled", "enabled", "available", "completed",
+      "auto", "multi", "mini", "micro", "meta", "super", "hybrid",
+      "context", "bridge", "batch", "local", "global", "native", "cloud",
+      "before", "after", "during", "often", "always", "never",
+      "project", "contributor", "software",
+      "backend", "frontend", "server", "client", "service", "app", "api"
+    ]
   }
 }

mempalace/i18n/es.json

@@ -40,5 +40,89 @@
     "stop_words": "el la los las un una unos unas de del al en con por para su sus mi mis tu tus es son está están fue ser estar haber sido como pero más muy también todo todos toda todas este esta estos estas ese esa esos esas que quien cual donde cuando porque aunque sin",
     "quote_pattern": "\"([^\"]{10,200})\"|«([^»]{10,200})»",
     "action_pattern": "(?:construido|corregido|escrito|añadido|enviado|medido|probado|revisado|creado|eliminado|actualizado|configurado|desplegado|migrado)\\s+[\\wá-ú\\s]{3,30}"
+  },
+  "entity": {
+    "candidate_pattern": "[A-ZÁÉÍÓÚÑÜ][a-záéíóúñü]{1,19}",
+    "multi_word_pattern": "[A-ZÁÉÍÓÚÑÜ][a-záéíóúñü]+(?:\\s+[A-ZÁÉÍÓÚÑÜ][a-záéíóúñü]+)+",
+    "person_verb_patterns": [
+      "\\b{name}\\s+dijo\\b",
+      "\\b{name}\\s+preguntó\\b",
+      "\\b{name}\\s+respondió\\b",
+      "\\b{name}\\s+contó\\b",
+      "\\b{name}\\s+rió\\b",
+      "\\b{name}\\s+sonrió\\b",
+      "\\b{name}\\s+lloró\\b",
+      "\\b{name}\\s+sintió\\b",
+      "\\b{name}\\s+piensa\\b",
+      "\\b{name}\\s+quiere\\b",
+      "\\b{name}\\s+ama\\b",
+      "\\b{name}\\s+odia\\b",
+      "\\b{name}\\s+sabe\\b",
+      "\\b{name}\\s+decidió\\b",
+      "\\b{name}\\s+escribió\\b"
+    ],
+    "pronoun_patterns": [
+      "\\bél\\b",
+      "\\bella\\b",
+      "\\bellos\\b",
+      "\\bellas\\b",
+      "\\blo\\b",
+      "\\bla\\b",
+      "\\ble\\b",
+      "\\bles\\b",
+      "\\bse\\b"
+    ],
+    "dialogue_patterns": [
+      "^>\\s*{name}[:\\s]",
+      "^{name}:\\s",
+      "^\\[{name}\\]",
+      "\"{name}\\s+dijo"
+    ],
+    "direct_address_pattern": "\\bhola\\s+{name}\\b|\\bhey\\s+{name}\\b|\\bhi\\s+{name}\\b|\\bgracias\\s+{name}\\b|\\bquerido\\s+{name}\\b|\\bquerida\\s+{name}\\b|\\bestimado\\s+{name}\\b|\\bestimada\\s+{name}\\b|\\bdon\\s+{name}\\b|\\bdoña\\s+{name}\\b|\\bseñor\\s+{name}\\b|\\bseñora\\s+{name}\\b",
+    "project_verb_patterns": [
+      "\\bconstruyo\\s+{name}\\b",
+      "\\bconstruí\\s+{name}\\b",
+      "\\barmé\\s+{name}\\b",
+      "\\blancé\\s+{name}\\b",
+      "\\bdesplegué\\s+{name}\\b",
+      "\\binstalé\\s+{name}\\b",
+      "\\bla\\s+arquitectura\\s+{name}\\b",
+      "\\bel\\s+pipeline\\s+{name}\\b",
+      "\\bel\\s+sistema\\s+{name}\\b",
+      "\\bel\\s+proyecto\\s+{name}\\b",
+      "\\bel\\s+repositorio\\s+{name}\\b",
+      "\\b{name}\\s+v\\d+\\b",
+      "\\b{name}\\.py\\b",
+      "\\bimport\\s+{name}\\b",
+      "\\bpip\\s+install\\s+{name}\\b"
+    ],
+    "stopwords": [
+      "el", "la", "los", "las", "un", "una", "unos", "unas",
+      "de", "del", "al", "a", "en", "con", "sin", "por", "para", "sobre",
+      "entre", "hasta", "desde", "hacia", "contra", "según", "tras",
+      "y", "o", "u", "ni", "pero", "sino", "aunque", "porque", "pues",
+      "que", "quien", "quienes", "cual", "cuales", "cuyo", "cuya",
+      "donde", "cuando", "como", "cuanto", "cuanta",
+      "yo", "tú", "él", "ella", "nosotros", "vosotros", "ellos", "ellas",
+      "me", "te", "se", "nos", "os", "lo", "la", "le", "los", "las", "les",
+      "mi", "mis", "tu", "tus", "su", "sus", "nuestro", "nuestra", "vuestro",
+      "este", "esta", "estos", "estas", "ese", "esa", "esos", "esas",
+      "aquel", "aquella", "aquellos", "aquellas", "esto", "eso", "aquello",
+      "ser", "estar", "haber", "tener", "hacer", "poder", "querer", "saber",
+      "es", "son", "fue", "fueron", "era", "eran", "está", "están", "estaba",
+      "he", "ha", "hemos", "han", "había", "hay",
+      "muy", "mucho", "mucha", "muchos", "muchas", "poco", "poca", "pocos", "pocas",
+      "más", "menos", "tan", "tanto", "también", "tampoco",
+      "sí", "no", "quizás", "tal", "vez",
+      "aquí", "allí", "allá", "ahí", "acá",
+      "hoy", "ayer", "mañana", "ahora", "antes", "después", "luego", "entonces",
+      "siempre", "nunca", "jamás", "todavía", "aún", "ya",
+      "bien", "mal", "mejor", "peor", "bueno", "buena", "malo", "mala",
+      "gracias", "hola", "adiós", "por favor", "perdón",
+      "día", "días", "semana", "mes", "año", "años", "tiempo", "vez", "veces",
+      "cosa", "cosas", "persona", "gente", "mundo", "vida", "casa", "lugar",
+      "forma", "manera", "parte", "caso", "punto", "idea", "hecho", "razón",
+      "nombre", "número", "versión", "sistema", "modelo"
+    ]
   }
 }

mempalace/i18n/fr.json

@@ -40,5 +40,87 @@
     "stop_words": "le la les un une des de du au aux en et ou mais donc or ni car que qui ce cette ces son sa ses mon ma mes ton ta tes leur leurs nous vous ils elles on ne pas plus très bien aussi avec pour dans sur par est sont fait être avoir été comme tout tous toute toutes",
     "quote_pattern": "«\\s*([^»]{10,200})\\s*»|\"([^\"]{10,200})\"",
     "action_pattern": "(?:construit|corrigé|écrit|ajouté|poussé|mesuré|testé|révisé|créé|supprimé|mis à jour|configuré|déployé|migré)\\s+[\\wà-ÿ\\s]{3,30}"
+  },
+  "entity": {
+    "candidate_pattern": "[A-ZÀÂÄÇÉÈÊËÎÏÔÖÙÛÜŸÆŒ][a-zàâäçéèêëîïôöùûüÿæœ]{1,19}",
+    "multi_word_pattern": "[A-ZÀÂÄÇÉÈÊËÎÏÔÖÙÛÜŸÆŒ][a-zàâäçéèêëîïôöùûüÿæœ]+(?:\\s+[A-ZÀÂÄÇÉÈÊËÎÏÔÖÙÛÜŸÆŒ][a-zàâäçéèêëîïôöùûüÿæœ]+)+",
+    "person_verb_patterns": [
+      "\\b{name}\\s+a\\s+dit\\b",
+      "\\b{name}\\s+a\\s+demandé\\b",
+      "\\b{name}\\s+a\\s+répondu\\b",
+      "\\b{name}\\s+a\\s+raconté\\b",
+      "\\b{name}\\s+a\\s+ri\\b",
+      "\\b{name}\\s+a\\s+souri\\b",
+      "\\b{name}\\s+a\\s+pleuré\\b",
+      "\\b{name}\\s+a\\s+senti\\b",
+      "\\b{name}\\s+pense\\b",
+      "\\b{name}\\s+veut\\b",
+      "\\b{name}\\s+aime\\b",
+      "\\b{name}\\s+déteste\\b",
+      "\\b{name}\\s+sait\\b",
+      "\\b{name}\\s+a\\s+décidé\\b",
+      "\\b{name}\\s+a\\s+écrit\\b"
+    ],
+    "pronoun_patterns": [
+      "\\bil\\b",
+      "\\belle\\b",
+      "\\blui\\b",
+      "\\bils\\b",
+      "\\belles\\b",
+      "\\bleur\\b",
+      "\\bleurs\\b",
+      "\\beux\\b",
+      "\\bse\\b"
+    ],
+    "dialogue_patterns": [
+      "^>\\s*{name}[:\\s]",
+      "^{name}:\\s",
+      "^\\[{name}\\]",
+      "\"{name}\\s+a\\s+dit"
+    ],
+    "direct_address_pattern": "\\bbonjour\\s+{name}\\b|\\bsalut\\s+{name}\\b|\\bmerci\\s+{name}\\b|\\bcher\\s+{name}\\b|\\bchère\\s+{name}\\b|\\bmonsieur\\s+{name}\\b|\\bmadame\\s+{name}\\b|\\bhey\\s+{name}\\b|\\bhi\\s+{name}\\b",
+    "project_verb_patterns": [
+      "\\bconstruit\\s+{name}\\b",
+      "\\blancé\\s+{name}\\b",
+      "\\bdéployé\\s+{name}\\b",
+      "\\binstallé\\s+{name}\\b",
+      "\\bl'architecture\\s+{name}\\b",
+      "\\ble\\s+pipeline\\s+{name}\\b",
+      "\\ble\\s+système\\s+{name}\\b",
+      "\\ble\\s+projet\\s+{name}\\b",
+      "\\ble\\s+dépôt\\s+{name}\\b",
+      "\\b{name}\\s+v\\d+\\b",
+      "\\b{name}\\.py\\b",
+      "\\bimport\\s+{name}\\b",
+      "\\bpip\\s+install\\s+{name}\\b"
+    ],
+    "stopwords": [
+      "le", "la", "les", "un", "une", "des", "du", "de", "au", "aux",
+      "en", "dans", "sur", "sous", "avec", "sans", "pour", "par", "vers",
+      "chez", "entre", "depuis", "pendant", "avant", "après", "jusqu",
+      "et", "ou", "mais", "donc", "or", "ni", "car", "que", "qui",
+      "dont", "où", "quand", "comment", "pourquoi", "combien", "lequel",
+      "ce", "cet", "cette", "ces", "celui", "celle", "ceux", "celles",
+      "mon", "ma", "mes", "ton", "ta", "tes", "son", "sa", "ses",
+      "notre", "nos", "votre", "vos", "leur", "leurs",
+      "je", "tu", "il", "elle", "on", "nous", "vous", "ils", "elles",
+      "me", "te", "se", "lui", "eux",
+      "être", "avoir", "faire", "dire", "aller", "voir", "savoir", "pouvoir",
+      "est", "sont", "était", "étaient", "fut", "furent", "sera", "seront",
+      "ai", "as", "a", "avons", "avez", "ont", "avait", "avaient",
+      "très", "bien", "mal", "peu", "beaucoup", "trop", "assez", "aussi",
+      "plus", "moins", "tant", "si", "tellement",
+      "oui", "non", "peut-être", "vraiment",
+      "ici", "là", "là-bas", "partout", "ailleurs",
+      "aujourd'hui", "hier", "demain", "maintenant", "alors", "ensuite",
+      "toujours", "jamais", "souvent", "parfois", "déjà", "encore",
+      "bon", "bonne", "mauvais", "mauvaise", "meilleur", "pire",
+      "merci", "bonjour", "salut", "au revoir",
+      "jour", "jours", "semaine", "mois", "année", "temps", "fois",
+      "chose", "choses", "personne", "gens", "monde", "vie", "maison",
+      "endroit", "lieu", "partie", "façon", "manière", "sorte", "type",
+      "cas", "point", "idée", "fait", "raison", "nom", "nombre",
+      "version", "système", "modèle", "question", "réponse"
+    ]
   }
 }

mempalace/i18n/hi.json

@@ -0,0 +1,105 @@
+{
+  "lang": "hi",
+  "label": "हिंदी",
+  "terms": {
+    "palace": "महल",
+    "wing": "खंड",
+    "hall": "हॉल",
+    "closet": "अलमारी",
+    "drawer": "दराज़",
+    "mine": "खनन",
+    "search": "खोज",
+    "status": "स्थिति",
+    "init": "आरंभ",
+    "repair": "मरम्मत",
+    "migrate": "स्थानांतरित करना",
+    "entity": "इकाई",
+    "topic": "विषय"
+  },
+  "cli": {
+    "mine_start": "{path} का खनन किया जा रहा है...",
+    "mine_complete": "पूर्ण हुआ। {closets} अलमारियाँ, {drawers} दराज़ें बनाई गईं।",
+    "mine_skip": "पहले ही खनन हो चुका है। पुनः खनन के लिए --force का उपयोग करें।",
+    "search_no_results": "इसके लिए कोई परिणाम नहीं मिले: {query}",
+    "search_results": "{count} परिणाम मिले:",
+    "status_palace": "महल: {path}",
+    "status_wings": "{count} खंड",
+    "status_closets": "{count} अलमारियाँ",
+    "status_drawers": "{count} दराज़ें",
+    "init_complete": "महल {path} पर प्रारंभ किया गया",
+    "init_exists": "महल पहले से ही {path} पर मौजूद है",
+    "repair_complete": "मरम्मत पूर्ण। {fixed} समस्याएँ ठीक की गईं।",
+    "migrate_complete": "स्थानांतरण पूर्ण।",
+    "no_palace": "कोई महल नहीं मिला। चलाएँ: mempalace init <dir>"
+  },
+  "aaak": {
+    "instruction": "इंडेक्स प्रारूप में संपीड़न करें। शब्दों के बीच हाइफ़न और अवधारणाओं के बीच पाइप का प्रयोग करें। आर्टिकल और अनावश्यक शब्द हटाएँ। नाम और संख्याएँ सटीक रखें।"
+  },
+  "regex": {
+    "topic_pattern": "[\\u0900-\\u097F]{2,}|[A-Za-z][A-Za-z0-9_]{2,}",
+    "stop_words": "यह वह ये वे कुछ कई अधिकांश प्रत्येक हर अन्य केवल ऐसा बहुत होगा सकता चाहिए ज़रूर हाँ ठीक भी फिर अब पहले अभी वापस पूरा बनाना लेना देना जानना सोचना चाहना ज़रूरत जा आ आना जाना ढूँढना काम जोड़ा सहेजा सत्र सारांश वार्तालाप स्रोत विषय के एक बार बस वास्तव में कहाँ यहाँ वहाँ धन्यवाद कृपया सही गलत करें किया करता करती चलाएँ उपयोग",
+    "quote_pattern": "\"([^\"]{20,200})\"",
+    "action_pattern": "(?:बनाया|सुधारा|लिखा|जोड़ा|भेजा|मापा|परीक्षण किया|समीक्षा की|निर्मित किया|हटाया|अद्यतन किया|विन्यस्त किया|तैनात किया|स्थानांतरित किया)\\s+[\\w\\s\\u0900-\\u097F]{3,30}"
+  },
+  "entity": {
+  "boundary_chars": "\\w\\u0900-\\u097F",
+  "candidate_pattern": "[\\u0900-\\u097F]{2,20}",
+  "multi_word_pattern": "[\\u0900-\\u097F]+(?:\\s+[\\u0900-\\u097F]+)+",
+  "person_verb_patterns": [
+    "\\b{name}\\s+ने\\s+कहा\\b",
+    "\\b{name}\\s+ने\\s+पूछा\\b",
+    "\\b{name}\\s+ने\\s+बोला\\b",
+    "\\b{name}\\s+ने\\s+बताया\\b",
+    "\\b{name}\\s+हँसा\\b",
+    "\\b{name}\\s+मुस्कुराया\\b",
+    "\\b{name}\\s+रोया\\b",
+    "\\b{name}\\s+सोचा\\b",
+    "\\b{name}\\s+चाहा\\b",
+    "\\b{name}\\s+पसंद\\s+किया\\b",
+    "\\b{name}\\s+नफरत\\s+की\\b",
+    "\\b{name}\\s+जानता\\s+है\\b"
+  ],
+  "pronoun_patterns": [
+    "\\bवह\\b",
+    "\\bउसने\\b",
+    "\\bउसे\\b",
+    "\\bउसका\\b",
+    "\\bउन्होंने\\b",
+    "\\bउनका\\b",
+    "\\bवे\\b"
+  ],
+  "dialogue_patterns": [
+    "^>\\s*{name}[:\\s]",
+    "^{name}:\\s",
+    "^\\[{name}\\]",
+    "\"{name}\\s+ने\\s+कहा"
+  ],
+  "direct_address_pattern": "\\bअरे\\s+{name}\\b|\\bनमस्ते\\s+{name}\\b|\\bधन्यवाद\\s+{name}\\b",
+  "project_verb_patterns": [
+    "\\b{name}\\s+बना\\s+रहा\\s+है\\b",
+    "\\b{name}\\s+बनाया\\b",
+    "\\b{name}\\s+लॉन्च\\s+किया\\b",
+    "\\b{name}\\s+तैनात\\s+किया\\b",
+    "\\b{name}\\s+इंस्टॉल\\s+किया\\b"
+  ],
+  "stopwords": [
+      "यह", "वह", "ये", "वे",
+      "मैं", "हम", "आप", "तुम",
+      "मेरा", "हमारा", "आपका", "उसका", "उनका",
+      "मुझे", "हमें", "आपको", "उसे", "उन्हें",
+      "का", "के", "की",
+      "को", "से", "में", "पर",
+      "के लिए", "के साथ", "के बारे में", "द्वारा",
+      "और", "या", "लेकिन", "क्योंकि", "तो", "यदि",
+      "भी", "ही", "सिर्फ", "केवल",
+      "है", "हैं", "था", "थे", "थी",
+      "हो", "होगा", "होता", "होती",
+      "कर", "करना", "किया", "करते", "करती",
+      "नहीं", "हाँ", "शायद", "ज़रूर",
+      "क्या", "कौन", "कब", "कहाँ", "क्यों", "कैसे",
+      "अब", "तब", "यहाँ", "वहाँ",
+      "बहुत", "कम", "अधिक",
+      "कुछ", "कोई", "सब", "हर"
+    ]
+  }
+}

mempalace/i18n/id.json

@@ -0,0 +1,234 @@
+{
+  "lang": "id",
+  "label": "Bahasa Indonesia",
+  "terms": {
+    "palace": "istana",
+    "wing": "sayap",
+    "hall": "lorong",
+    "closet": "lemari",
+    "drawer": "laci",
+    "mine": "tambang",
+    "search": "cari",
+    "status": "status",
+    "init": "inisialisasi",
+    "repair": "perbaiki",
+    "migrate": "migrasi",
+    "entity": "entitas",
+    "topic": "topik"
+  },
+  "cli": {
+    "mine_start": "Menambang {path}...",
+    "mine_complete": "Selesai. {closets} lemari dan {drawers} laci berhasil dibuat.",
+    "mine_skip": "Sudah pernah ditambang. Gunakan --force untuk menambang ulang.",
+    "search_no_results": "Tidak ada hasil untuk: {query}",
+    "search_results": "Ditemukan {count} hasil:",
+    "status_palace": "Istana: {path}",
+    "status_wings": "{count} sayap",
+    "status_closets": "{count} lemari",
+    "status_drawers": "{count} laci",
+    "init_complete": "Istana diinisialisasi pada {path}",
+    "init_exists": "Istana sudah ada pada {path}",
+    "repair_complete": "Perbaikan selesai. {fixed} masalah berhasil diperbaiki.",
+    "migrate_complete": "Migrasi selesai.",
+    "no_palace": "Istana tidak ditemukan. Jalankan: mempalace init <dir>"
+  },
+  "aaak": {
+    "instruction": "Ringkas ke format indeks. Gunakan tanda hubung (-) antar kata dan garis vertikal (|) antar konsep. Buang kata fungsi dan kata pengisi yang tidak penting. Pertahankan nama serta angka tetap persis."
+  },
+  "regex": {
+    "topic_pattern": "[A-Z][a-z]{2,}|[A-Za-z][A-Za-z0-9_/-]{2,}",
+    "stop_words": "yang untuk pada ke para namun menurut antara dia ia seperti jika sehingga kembali dan tidak ini karena kepada oleh saat harus sementara setelah belum kami sekitar bagi serta di dari telah sebagai masih hal ketika adalah itu dalam bisa bahwa atau hanya kita dengan akan juga ada mereka sudah saya terhadap secara agar lain anda begitu mengapa kenapa yaitu yakni daripada itulah lagi maka tentang demi di mana ke mana pula sambil sebelum sesudah supaya guna kah pun sampai sedangkan selagi tetapi apakah kecuali sebab selain seolah seraya seterusnya tanpa agak boleh dapat dsb dst dll dahulu dulunya anu demikian tapi ingin nggak gak ga ngga enggak mari nanti melainkan oh ok oke seharusnya sebetulnya setiap setidaknya sesuatu pasti saja toh ya walau tolong tentu amat apalagi bagaimanapun udah banget bgt nih dong kok sih deh aja pun",
+    "quote_pattern": "\"([^\"]{20,200})\"|“([^”]{20,200})”|‘([^’]{20,200})’",
+    "action_pattern": "(?:dibangun|membangun|ngembangin|diperbaiki|memperbaiki|ditulis|menulis|ditambahkan|menambahkan|dibuat|membuat|diperbarui|memperbarui|diulas|mengulas|diuji|menguji|diukur|mengukur|dikonfigurasi|mengonfigurasi|dideploy|deploy|nge-?deploy|ngebuild|build|dikirim|push|dipush|nge-?push|dirilis|rilis|dimigrasi|migrasi|dibundle)\\s+[\\w\\s./_-]{3,30}"
+  },
+  "entity": {
+    "candidate_pattern": "[A-Z][a-z]{1,19}|[A-Z]{2,10}|[A-Za-z][A-Za-z0-9_]*[A-Z][A-Za-z0-9_]*|[a-z]+[A-Z][A-Za-z0-9_]*",
+    "multi_word_pattern": "(?:[A-Z][a-z]+|[A-Z]{2,10})(?:\\s+(?:[A-Z][a-z]+|[A-Z]{2,10}))+",
+    "person_verb_patterns": [
+      "\\b{name}\\s+berkata\\b",
+      "\\b{name}\\s+mengatakan\\b",
+      "\\b{name}\\s+bilang\\b",
+      "\\b{name}\\s+ngomong\\b",
+      "\\b{name}\\s+ceritain\\b",
+      "\\b{name}\\s+bertanya\\b",
+      "\\b{name}\\s+menanyakan\\b",
+      "\\b{name}\\s+tanya\\b",
+      "\\b{name}\\s+nanya\\b",
+      "\\b{name}\\s+menjawab\\b",
+      "\\b{name}\\s+jawab\\b",
+      "\\b{name}\\s+balas\\b",
+      "\\b{name}\\s+reply\\b",
+      "\\b{name}\\s+membalas\\b",
+      "\\b{name}\\s+menjelaskan\\b",
+      "\\b{name}\\s+cerita\\b",
+      "\\b{name}\\s+tertawa\\b",
+      "\\b{name}\\s+tersenyum\\b",
+      "\\b{name}\\s+menangis\\b",
+      "\\b{name}\\s+merasa\\b",
+      "\\b{name}\\s+memikirkan\\b",
+      "\\b{name}\\s+berpikir\\b",
+      "\\b{name}\\s+pikir\\b",
+      "\\b{name}\\s+ingin\\b",
+      "\\b{name}\\s+mau\\b",
+      "\\b{name}\\s+suka\\b",
+      "\\b{name}\\s+benci\\b",
+      "\\b{name}\\s+tahu\\b",
+      "\\b{name}\\s+memutuskan\\b",
+      "\\b{name}\\s+memilih\\b",
+      "\\b{name}\\s+decided\\b",
+      "\\b{name}\\s+menulis\\b",
+      "\\b{name}\\s+nulis\\b",
+      "\\b{name}\\s+ngetik\\b",
+      "\\b{name}\\s+push\\b",
+      "\\b{name}\\s+nge-?push\\b",
+      "\\b{name}\\s+review(?:ed)?\\b",
+      "\\b{name}\\s+nge-?review\\b",
+      "\\b{name}\\s+approve(?:d)?\\b",
+      "\\b{name}\\s+di-?approve\\b"
+    ],
+    "pronoun_patterns": [
+      "\\bdia\\b",
+      "\\bia\\b",
+      "\\bbeliau\\b",
+      "\\bmereka\\b"
+    ],
+    "dialogue_patterns": [
+      "^>\\s*{name}[:\\s]",
+      "^{name}:\\s",
+      "^\\[{name}\\]",
+      "\"{name}\\s+berkata",
+      "\"{name}\\s+bilang"
+    ],
+    "direct_address_pattern": "\\bhai\\s+{name}\\b|\\bhalo\\s+{name}\\b|\\bhi\\s+{name}\\b|\\bhei\\s+{name}\\b|\\bterima\\s+kasih\\s+{name}\\b|\\bmakasih\\s+{name}\\b|\\bmakasi\\s+{name}\\b|\\bpak\\s+{name}\\b|\\bbu\\s+{name}\\b|\\bmas\\s+{name}\\b|\\bmbak\\s+{name}\\b|\\bkak\\s+{name}\\b",
+    "project_verb_patterns": [
+      "\\bmembangun\\s+{name}\\b",
+      "\\bbangun\\s+{name}\\b",
+      "\\bdibangun\\s+{name}\\b",
+      "\\bngembangin\\s+{name}\\b",
+      "\\bmengerjakan\\s+{name}\\b",
+      "\\bngerjain\\s+{name}\\b",
+      "\\bgarap\\s+{name}\\b",
+      "\\bbuild(?:ing)?\\s+{name}\\b",
+      "\\bnge-?build\\s+{name}\\b",
+      "\\bmerilis\\s+{name}\\b",
+      "\\brilis\\s+{name}\\b",
+      "\\bship(?:ping|ped)?\\s+{name}\\b",
+      "\\bmeluncurkan\\s+{name}\\b",
+      "\\blaunch(?:ing|ed)?\\s+{name}\\b",
+      "\\bdeploy(?:ing|ed)?\\s+{name}\\b",
+      "\\bdideploy\\s+{name}\\b",
+      "\\bmendeploy\\s+{name}\\b",
+      "\\bnge-?deploy\\s+{name}\\b",
+      "\\binstall(?:ing|ed)?\\s+{name}\\b",
+      "\\bmenginstal\\s+{name}\\b",
+      "\\bmemasang\\s+{name}\\b",
+      "\\bpush\\s+{name}\\b",
+      "\\bnge-?push\\s+{name}\\b",
+      "\\breview(?:ing|ed)?\\s+{name}\\b",
+      "\\barsitektur\\s+{name}\\b",
+      "\\bpipeline\\s+{name}\\b",
+      "\\b{name}\\s+v\\d+\\b",
+      "\\b{name}\\.py\\b",
+      "\\b{name}-core\\b",
+      "\\b{name}-local\\b",
+      "\\bimport\\s+{name}\\b",
+      "\\bpip\\s+install\\s+{name}\\b"
+    ],
+    "stopwords": [
+      "yang",
+      "dan",
+      "atau",
+      "tetapi",
+      "namun",
+      "karena",
+      "jadi",
+      "kalau",
+      "jika",
+      "ketika",
+      "saat",
+      "supaya",
+      "agar",
+      "untuk",
+      "dari",
+      "ke",
+      "di",
+      "pada",
+      "dalam",
+      "dengan",
+      "tanpa",
+      "antara",
+      "tentang",
+      "sebagai",
+      "oleh",
+      "terhadap",
+      "ini",
+      "itu",
+      "tersebut",
+      "sini",
+      "situ",
+      "sana",
+      "saya",
+      "aku",
+      "kami",
+      "kita",
+      "kamu",
+      "anda",
+      "dia",
+      "ia",
+      "beliau",
+      "mereka",
+      "ada",
+      "tidak",
+      "bukan",
+      "iya",
+      "ya",
+      "oke",
+      "ok",
+      "baik",
+      "nah",
+      "nih",
+      "dong",
+      "deh",
+      "kok",
+      "sih",
+      "aja",
+      "juga",
+      "lagi",
+      "sudah",
+      "udah",
+      "belum",
+      "masih",
+      "baru",
+      "pernah",
+      "selalu",
+      "sering",
+      "jarang",
+      "banyak",
+      "sedikit",
+      "lebih",
+      "kurang",
+      "semua",
+      "setiap",
+      "beberapa",
+      "sesuatu",
+      "apa",
+      "siapa",
+      "mana",
+      "kapan",
+      "mengapa",
+      "kenapa",
+      "bagaimana",
+      "bisa",
+      "harus",
+      "mau",
+      "ingin",
+      "tahu",
+      "coba",
+      "pak",
+      "bu",
+      "mas",
+      "mbak",
+      "kak"
+    ]
+  }
+}

mempalace/i18n/it.json

@@ -0,0 +1,186 @@
+{
+  "lang": "it",
+  "label": "Italiano",
+  "terms": {
+    "palace": "palazzo",
+    "wing": "ala",
+    "hall": "corridoio",
+    "closet": "armadio",
+    "drawer": "cassetto",
+    "mine": "estrarre",
+    "search": "cercare",
+    "status": "stato",
+    "init": "inizializzare",
+    "repair": "riparare",
+    "migrate": "migrare",
+    "entity": "entità",
+    "topic": "argomento"
+  },
+  "cli": {
+    "mine_start": "Estrazione di {path}...",
+    "mine_complete": "Fatto. {closets} armadi, {drawers} cassetti creati.",
+    "mine_skip": "Già estratto. Usa --force per estrarre di nuovo.",
+    "search_no_results": "Nessun risultato per: {query}",
+    "search_results": "{count} risultati trovati:",
+    "status_palace": "Palazzo: {path}",
+    "status_wings": "{count} ali",
+    "status_closets": "{count} armadi",
+    "status_drawers": "{count} cassetti",
+    "init_complete": "Palazzo inizializzato in {path}",
+    "init_exists": "Esiste già un palazzo in {path}",
+    "repair_complete": "Riparazione completata. {fixed} problemi risolti.",
+    "migrate_complete": "Migrazione completata.",
+    "no_palace": "Nessun palazzo trovato. Esegui: mempalace init <cartella>"
+  },
+  "aaak": {
+    "instruction": "Comprimi in italiano. Trattini tra le parole, pipe tra i concetti. Elimina articoli e parole di riempimento. Mantieni nomi propri e numeri esatti."
+  },
+  "regex": {
+    "topic_pattern": "[A-ZÀ-Ú][a-zà-ú]{2,}|[A-Za-zÀ-ÿ][A-Za-zÀ-ÿ0-9_]{2,}",
+    "stop_words": "il lo la i gli le un uno una di del della dello dei degli delle al allo alla ai agli alle in con su per tra fra da dal dalla dallo dai dagli dalle e o ma che chi cui come dove quando perché mentre anche ancora già molto poco solo sempre mai essere avere sono sei siamo siete era erano stato stata questo questa questi queste quello quella quelli quelle mio mia miei mie tuo tua tuoi tue suo sua suoi sue nostro nostra nostri nostre vostro vostra vostri vostre loro",
+    "quote_pattern": "«\\s*([^»]{10,200})\\s*»|\"([^\"]{10,200})\"",
+    "action_pattern": "(?:costruito|corretto|scritto|aggiunto|inviato|misurato|testato|revisionato|creato|eliminato|aggiornato|configurato|distribuito|migrato)\\s+[\\wÀ-ÿ\\s]{3,30}"
+  },
+  "entity": {
+    "candidate_pattern": "[A-ZÀ-Ú][a-zà-ÿ]{1,19}",
+    "multi_word_pattern": "[A-ZÀ-Ú][a-zà-ÿ]+(?:\\s+[A-ZÀ-Ú][a-zà-ÿ]+)+",
+    "person_verb_patterns": [
+      "\\b{name}\\s+ha\\s+detto\\b",
+      "\\b{name}\\s+ha\\s+chiesto\\b",
+      "\\b{name}\\s+ha\\s+risposto\\b",
+      "\\b{name}\\s+ha\\s+riferito\\b",
+      "\\b{name}\\s+ha\\s+riso\\b",
+      "\\b{name}\\s+ha\\s+sorriso\\b",
+      "\\b{name}\\s+ha\\s+pianto\\b",
+      "\\b{name}\\s+ha\\s+sentito\\b",
+      "\\b{name}\\s+pensa\\b",
+      "\\b{name}\\s+vuole\\b",
+      "\\b{name}\\s+ama\\b",
+      "\\b{name}\\s+odia\\b",
+      "\\b{name}\\s+sa\\b",
+      "\\b{name}\\s+ha\\s+deciso\\b",
+      "\\b{name}\\s+ha\\s+scritto\\b"
+    ],
+    "pronoun_patterns": [
+      "\\blei\\b",
+      "\\blui\\b",
+      "\\bloro\\b",
+      "\\bgli\\b",
+      "\\ble\\b"
+    ],
+    "dialogue_patterns": [
+      "^>\\s*{name}[:\\s]",
+      "^{name}:\\s",
+      "^\\[{name}\\]",
+      "\"{name}\\s+ha\\s+detto"
+    ],
+    "direct_address_pattern": "\\bciao\\s+{name}\\b|\\bgrazie\\s+{name}\\b|\\bsalve\\s+{name}\\b|\\bcaro\\s+{name}\\b|\\bcara\\s+{name}\\b",
+    "project_verb_patterns": [
+      "\\bstiamo\\s+costruendo\\s+{name}\\b",
+      "\\babbiamo\\s+costruito\\s+{name}\\b",
+      "\\bstiamo\\s+lanciando\\s+{name}\\b",
+      "\\babbiamo\\s+lanciato\\s+{name}\\b",
+      "\\babbiamo\\s+distribuito\\s+{name}\\b",
+      "\\babbiamo\\s+installato\\s+{name}\\b",
+      "\\bil\\s+progetto\\s+{name}\\b",
+      "\\bil\\s+sistema\\s+{name}\\b",
+      "\\bimport\\s+{name}\\b",
+      "\\bpip\\s+install\\s+{name}\\b"
+    ],
+    "stopwords": [
+      "ciao",
+      "salve",
+      "grazie",
+      "prego",
+      "sì",
+      "si",
+      "no",
+      "forse",
+      "qui",
+      "qua",
+      "lì",
+      "oggi",
+      "ieri",
+      "domani",
+      "sempre",
+      "mai",
+      "ancora",
+      "anche",
+      "molto",
+      "poco",
+      "bene",
+      "male",
+      "così",
+      "poi",
+      "prima",
+      "dopo",
+      "tra",
+      "fra",
+      "con",
+      "senza",
+      "per",
+      "verso",
+      "contro",
+      "durante",
+      "mentre",
+      "sopra",
+      "sotto",
+      "oltre",
+      "oppure",
+      "ma",
+      "però",
+      "tuttavia",
+      "anche",
+      "se",
+      "quando",
+      "finché",
+      "perché",
+      "quindi",
+      "dunque",
+      "allora",
+      "forse",
+      "magari",
+      "abbiamo",
+      "stiamo",
+      "essere",
+      "avere",
+      "sono",
+      "sei",
+      "siamo",
+      "siete",
+      "era",
+      "erano",
+      "stato",
+      "stata",
+      "questo",
+      "questa",
+      "questi",
+      "queste",
+      "quello",
+      "quella",
+      "quelli",
+      "quelle",
+      "mio",
+      "mia",
+      "miei",
+      "mie",
+      "tuo",
+      "tua",
+      "tuoi",
+      "tue",
+      "suo",
+      "sua",
+      "suoi",
+      "sue",
+      "nostro",
+      "nostra",
+      "nostri",
+      "nostre",
+      "vostro",
+      "vostra",
+      "vostri",
+      "vostre",
+      "loro"
+    ]
+  }
+}

mempalace/i18n/ko.json

@@ -25,7 +25,7 @@
     "status_palace": "궁전: {path}",
     "status_wings": "날개 {count}개",
     "status_closets": "벽장 {count}개",
-    "status_drawers": "서랍 {drawers}개",
+    "status_drawers": "서랍 {count}개",
     "init_complete": "{path}에 궁전 초기화 완료",
     "init_exists": "{path}에 궁전이 이미 존재합니다",
     "repair_complete": "수리 완료. {fixed}개 문제 해결.",

mempalace/i18n/pt-br.json

@@ -0,0 +1,173 @@
+{
+  "lang": "pt-br",
+  "label": "Português (Brasil)",
+  "terms": {
+    "palace": "palácio",
+    "wing": "ala",
+    "hall": "corredor",
+    "closet": "armário",
+    "drawer": "gaveta",
+    "mine": "minerar",
+    "search": "buscar",
+    "status": "status",
+    "init": "inicializar",
+    "repair": "reparar",
+    "migrate": "migrar",
+    "entity": "entidade",
+    "topic": "tópico"
+  },
+  "cli": {
+    "mine_start": "Minerando {path}...",
+    "mine_complete": "Pronto. {closets} armários, {drawers} gavetas criados.",
+    "mine_skip": "Já minerado. Use --force para refazer.",
+    "search_no_results": "Sem resultados para: {query}",
+    "search_results": "{count} resultados encontrados:",
+    "status_palace": "Palácio: {path}",
+    "status_wings": "{count} alas",
+    "status_closets": "{count} armários",
+    "status_drawers": "{count} gavetas",
+    "init_complete": "Palácio inicializado em {path}",
+    "init_exists": "Já existe um palácio em {path}",
+    "repair_complete": "Reparo completo. {fixed} problemas corrigidos.",
+    "migrate_complete": "Migração completa.",
+    "no_palace": "Nenhum palácio encontrado. Execute: mempalace init <diretório>"
+  },
+  "aaak": {
+    "instruction": "Comprima em português. Hifens entre palavras, pipes entre conceitos. Remova artigos e palavras de preenchimento. Mantenha nomes próprios e números exatos."
+  },
+  "regex": {
+    "topic_pattern": "[A-ZÀ-Ú][a-zà-ÿ]{2,}|[A-Za-zÀ-ÿ]{3,}",
+    "stop_words": "o a os as um uma uns umas de do da dos das em no na nos nas por para com sem sobre entre ao aos seu sua seus suas meu minha meus minhas tu teu tua que quem qual onde quando porque embora mas porém também muito mais como este esta estes estas esse essa esses essas aquele aquela é são está estão foi ser estar ter sido",
+    "quote_pattern": "\"([^\"]{10,200})\"|«([^»]{10,200})»",
+    "action_pattern": "(?:construído|corrigido|escrito|adicionado|enviado|medido|testado|revisado|criado|excluído|atualizado|configurado|implantado|migrado)\\s+[\\wà-ÿ\\s]{3,30}"
+  },
+  "entity": {
+    "candidate_pattern": "[A-ZÀ-Ú][a-zà-ÿ]{1,19}",
+    "multi_word_pattern": "[A-ZÀ-Ú][a-zà-ÿ]+(?:\\s+[A-ZÀ-Ú][a-zà-ÿ]+)+",
+    "person_verb_patterns": [
+      "\\b{name}\\s+disse\\b",
+      "\\b{name}\\s+perguntou\\b",
+      "\\b{name}\\s+respondeu\\b",
+      "\\b{name}\\s+contou\\b",
+      "\\b{name}\\s+riu\\b",
+      "\\b{name}\\s+sorriu\\b",
+      "\\b{name}\\s+chorou\\b",
+      "\\b{name}\\s+sentiu\\b",
+      "\\b{name}\\s+pensa\\b",
+      "\\b{name}\\s+quer\\b",
+      "\\b{name}\\s+ama\\b",
+      "\\b{name}\\s+odeia\\b",
+      "\\b{name}\\s+sabe\\b",
+      "\\b{name}\\s+decidiu\\b",
+      "\\b{name}\\s+escreveu\\b"
+    ],
+    "pronoun_patterns": [
+      "\\bela\\b",
+      "\\bdela\\b",
+      "\\bele\\b",
+      "\\bdele\\b",
+      "\\beles\\b",
+      "\\belas\\b",
+      "\\bdeles\\b",
+      "\\bdelas\\b",
+      "\\bvocê\\b",
+      "\\bvocês\\b",
+      "\\bseu\\b",
+      "\\bsua\\b",
+      "\\bseus\\b",
+      "\\bsuas\\b"
+    ],
+    "dialogue_patterns": [
+      "^>\\s*{name}[:\\s]",
+      "^{name}:\\s",
+      "^\\[{name}\\]",
+      "\"{name}\\s+disse"
+    ],
+    "direct_address_pattern": "\\boi\\s+{name}\\b|\\bol[áa]\\s+{name}\\b|\\bobrigad[oa]\\s+{name}\\b|\\bcaro\\s+{name}\\b|\\bcara\\s+{name}\\b",
+    "project_verb_patterns": [
+      "\\bconstruindo\\s+{name}\\b",
+      "\\bconstruiu\\s+{name}\\b",
+      "\\blançando\\s+{name}\\b",
+      "\\blançou\\s+{name}\\b",
+      "\\bimplantando\\s+{name}\\b",
+      "\\bimplantou\\s+{name}\\b",
+      "\\binstalando\\s+{name}\\b",
+      "\\binstalou\\s+{name}\\b",
+      "\\bo\\s+sistema\\s+{name}\\b",
+      "\\bo\\s+projeto\\s+{name}\\b",
+      "\\bimport\\s+{name}\\b",
+      "\\bpip\\s+install\\s+{name}\\b"
+    ],
+    "stopwords": [
+      "oi",
+      "ola",
+      "olá",
+      "obrigado",
+      "obrigada",
+      "sim",
+      "não",
+      "talvez",
+      "aqui",
+      "ali",
+      "lá",
+      "agora",
+      "hoje",
+      "ontem",
+      "amanhã",
+      "sempre",
+      "nunca",
+      "ainda",
+      "também",
+      "muito",
+      "pouco",
+      "bem",
+      "mal",
+      "assim",
+      "então",
+      "depois",
+      "antes",
+      "durante",
+      "sobre",
+      "entre",
+      "para",
+      "como",
+      "mas",
+      "porém",
+      "contudo",
+      "embora",
+      "enquanto",
+      "porque",
+      "portanto",
+      "logo",
+      "todavia",
+      "desde",
+      "contra",
+      "perante",
+      "após",
+      "mediante",
+      "conforme",
+      "segundo",
+      "exceto",
+      "pois",
+      "apenas",
+      "mais",
+      "menos",
+      "cada",
+      "todo",
+      "toda",
+      "todos",
+      "todas",
+      "tudo",
+      "nada",
+      "algo",
+      "onde",
+      "quando",
+      "qual",
+      "quem",
+      "isso",
+      "isto",
+      "ser",
+      "ter"
+    ]
+  }
+}

mempalace/i18n/ru.json

@@ -0,0 +1,161 @@
+{
+  "lang": "ru",
+  "label": "Русский",
+  "terms": {
+    "palace": "дворец",
+    "wing": "крыло",
+    "hall": "зал",
+    "closet": "шкаф",
+    "drawer": "ящик",
+    "mine": "раскопка",
+    "search": "поиск",
+    "status": "статус",
+    "init": "создание",
+    "repair": "починка",
+    "migrate": "миграция",
+    "entity": "сущность",
+    "topic": "тема"
+  },
+  "cli": {
+    "mine_start": "Раскопка {path}...",
+    "mine_complete": "Готово. Шкафов: {closets}, ящиков: {drawers}.",
+    "mine_skip": "Уже обработано. Используйте --force для повторной обработки.",
+    "search_no_results": "Нет результатов по запросу: {query}",
+    "search_results": "Найдено результатов: {count}",
+    "status_palace": "Дворец: {path}",
+    "status_wings": "Крыльев: {count}",
+    "status_closets": "Шкафов: {count}",
+    "status_drawers": "Ящиков: {count}",
+    "init_complete": "Дворец создан в {path}",
+    "init_exists": "Дворец уже существует в {path}",
+    "repair_complete": "Починка завершена. Исправлено проблем: {fixed}.",
+    "migrate_complete": "Миграция завершена.",
+    "no_palace": "Дворец не найден. Выполните: mempalace init <директория>"
+  },
+  "aaak": {
+    "instruction": "Сжать до индексного формата. Дефисы между словами, вертикальные черты между понятиями. Убрать предлоги и служебные слова. Имена и числа сохранять точно."
+  },
+  "regex": {
+    "topic_pattern": "[А-ЯЁ][а-яё]{2,}|[A-Z][a-z]{2,}|[A-Za-z][A-Za-z0-9_]{2,}",
+    "stop_words": "это этот эта эти тот та те тех некоторые много каждый другой только такой очень будет может должен надо хорошо также даже потом сейчас уже ещё обратно сделано делать брать давать знать думать хотеть нужно если когда просто правда ладно вообще конечно например значит кстати наверное видимо похоже получается собственно кажется",
+    "quote_pattern": "«\\s*([^»]{10,200})\\s*»|\"([^\"]{10,200})\"",
+    "action_pattern": "(?:построил|исправил|написал|добавил|запустил|протестировал|проверил|создал|удалил|обновил|настроил|развернул|перенёс|собрал)\\s+[\\wа-яёА-ЯЁ\\s]{3,30}"
+  },
+  "entity": {
+    "candidate_pattern": "[А-ЯЁ][а-яё]{1,19}",
+    "multi_word_pattern": "[А-ЯЁ][а-яё]+(?:\\s+[А-ЯЁ][а-яё]+)+",
+    "person_verb_patterns": [
+      "\\b{name}\\s+сказал[аи]?\\b",
+      "\\b{name}\\s+спросил[аи]?\\b",
+      "\\b{name}\\s+ответил[аи]?\\b",
+      "\\b{name}\\s+рассказал[аи]?\\b",
+      "\\b{name}\\s+засмеял(ся|ась|ись)\\b",
+      "\\b{name}\\s+улыбнул(ся|ась|ись)\\b",
+      "\\b{name}\\s+заплакал[аи]?\\b",
+      "\\b{name}\\s+почувствовал[аи]?\\b",
+      "\\b{name}\\s+думает\\b",
+      "\\b{name}\\s+хочет\\b",
+      "\\b{name}\\s+любит\\b",
+      "\\b{name}\\s+ненавидит\\b",
+      "\\b{name}\\s+знает\\b",
+      "\\b{name}\\s+решил[аи]?\\b",
+      "\\b{name}\\s+написал[аи]?\\b"
+    ],
+    "pronoun_patterns": [
+      "\\bона\\b",
+      "\\bеё\\b",
+      "\\bей\\b",
+      "\\bон\\b",
+      "\\bего\\b",
+      "\\bему\\b",
+      "\\bони\\b",
+      "\\bих\\b",
+      "\\bим\\b"
+    ],
+    "dialogue_patterns": [
+      "^>\\s*{name}[:\\s]",
+      "^{name}:\\s",
+      "^\\[{name}\\]",
+      "\"{name}\\s+сказал"
+    ],
+    "direct_address_pattern": "\\bпривет\\s+{name}\\b|\\bспасибо\\s+{name}\\b|\\bздравствуй(те)?\\s+{name}\\b|\\bуважаемый\\s+{name}\\b|\\bуважаемая\\s+{name}\\b|\\bдорогой\\s+{name}\\b|\\bдорогая\\s+{name}\\b",
+    "project_verb_patterns": [
+      "\\bсобираю\\s+{name}\\b",
+      "\\bсобрал\\s+{name}\\b",
+      "\\bзапускаю\\s+{name}\\b",
+      "\\bзапустил\\s+{name}\\b",
+      "\\bразвернул\\s+{name}\\b",
+      "\\bустановил\\s+{name}\\b",
+      "\\bсистема\\s+{name}\\b",
+      "\\bпроект\\s+{name}\\b",
+      "\\bimport\\s+{name}\\b",
+      "\\bpip\\s+install\\s+{name}\\b"
+    ],
+    "stopwords": [
+      "привет",
+      "здравствуйте",
+      "спасибо",
+      "пожалуйста",
+      "да",
+      "нет",
+      "может",
+      "наверное",
+      "здесь",
+      "там",
+      "тут",
+      "сейчас",
+      "сегодня",
+      "вчера",
+      "завтра",
+      "всегда",
+      "никогда",
+      "ещё",
+      "тоже",
+      "очень",
+      "мало",
+      "хорошо",
+      "плохо",
+      "так",
+      "потом",
+      "перед",
+      "после",
+      "между",
+      "около",
+      "вместе",
+      "без",
+      "для",
+      "над",
+      "под",
+      "при",
+      "про",
+      "через",
+      "против",
+      "вместо",
+      "кроме",
+      "среди",
+      "вокруг",
+      "вдоль",
+      "ради",
+      "напротив",
+      "благодаря",
+      "согласно",
+      "навстречу",
+      "или",
+      "либо",
+      "но",
+      "однако",
+      "зато",
+      "хотя",
+      "если",
+      "когда",
+      "пока",
+      "чтобы",
+      "потому",
+      "поэтому",
+      "причём",
+      "притом",
+      "будто",
+      "словно"
+    ]
+  }
+}

mempalace/i18n/test_i18n.py

@@ -1,84 +0,0 @@
-#!/usr/bin/env python3
-"""Quick smoke test for i18n dictionaries + Dialect integration."""
-
-import sys
-from pathlib import Path
-
-# Add parent to path so we can import mempalace
-sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
-
-from mempalace.i18n import load_lang, t, available_languages
-from mempalace.dialect import Dialect
-
-
-def test_all_languages_load():
-    """Every JSON file loads without error and has required keys."""
-    required_sections = ["terms", "cli", "aaak"]
-    required_terms = ["palace", "wing", "closet", "drawer"]
-
-    langs = available_languages()
-    assert len(langs) >= 7, f"Expected 7+ languages, got {len(langs)}"
-
-    for lang in langs:
-        strings = load_lang(lang)
-        for section in required_sections:
-            assert section in strings, f"{lang}: missing section '{section}'"
-        for term in required_terms:
-            assert term in strings["terms"], f"{lang}: missing term '{term}'"
-            assert len(strings["terms"][term]) > 0, f"{lang}: empty term '{term}'"
-        assert "instruction" in strings["aaak"], f"{lang}: missing aaak.instruction"
-
-    print(f"  PASS: {len(langs)} languages load correctly")
-
-
-def test_interpolation():
-    """String interpolation works for all languages."""
-    for lang in available_languages():
-        load_lang(lang)
-        result = t("cli.mine_complete", closets=5, drawers=100)
-        assert "5" in result, f"{lang}: closets count missing from mine_complete"
-        assert "100" in result, f"{lang}: drawers count missing from mine_complete"
-
-    print("  PASS: interpolation works for all languages")
-
-
-def test_dialect_loads_lang():
-    """Dialect class picks up the language instruction."""
-    for lang in available_languages():
-        d = Dialect(lang=lang)
-        assert d.lang == lang, f"Expected lang={lang}, got {d.lang}"
-        assert len(d.aaak_instruction) > 10, f"{lang}: AAAK instruction too short"
-
-    print("  PASS: Dialect loads language instruction for all languages")
-
-
-def test_dialect_compress_samples():
-    """Compress sample text in different languages, verify output isn't empty."""
-    samples = {
-        "en": "We decided to migrate from SQLite to PostgreSQL for better concurrent writes. Ben approved the PR yesterday.",
-        "fr": "Nous avons décidé de migrer de SQLite vers PostgreSQL pour une meilleure écriture concurrente. Ben a approuvé le PR hier.",
-        "ko": "더 나은 동시 쓰기를 위해 SQLite에서 PostgreSQL로 마이그레이션하기로 했습니다. 벤이 어제 PR을 승인했습니다.",
-        "ja": "同時書き込みの改善のため、SQLiteからPostgreSQLに移行することを決定しました。ベンが昨日PRを承認しました。",
-        "es": "Decidimos migrar de SQLite a PostgreSQL para mejor escritura concurrente. Ben aprobó el PR ayer.",
-        "de": "Wir haben beschlossen, von SQLite auf PostgreSQL zu migrieren für bessere gleichzeitige Schreibvorgänge. Ben hat den PR gestern genehmigt.",
-        "zh-CN": "我们决定从SQLite迁移到PostgreSQL以获得更好的并发写入。Ben昨天批准了PR。",
-    }
-
-    for lang, text in samples.items():
-        d = Dialect(lang=lang)
-        compressed = d.compress(text)
-        assert len(compressed) > 0, f"{lang}: compression returned empty"
-        assert len(compressed) < len(text) * 2, f"{lang}: compression expanded text"
-        print(f"    {lang}: {len(text)} chars → {len(compressed)} chars")
-        print(f"         {compressed[:80]}")
-
-    print("  PASS: compression works for all sample languages")
-
-
-if __name__ == "__main__":
-    print("i18n smoke tests:")
-    test_all_languages_load()
-    test_interpolation()
-    test_dialect_loads_lang()
-    test_dialect_compress_samples()
-    print("\nAll tests passed.")

mempalace/i18n/zh-CN.json

@@ -40,5 +40,93 @@
     "stop_words": "的 了 在 是 我 有 和 就 不 人 都 一 一个 上 也 很 到 说 要 去 你 会 着 没有 看 好 自己 这 那 她 他 它 们 但是 因为 所以 如果 虽然 然后 或者 而且",
     "quote_pattern": "\\u201C([^\\u201D]{10,100})\\u201D|\"([^\"]{10,200})\"",
     "action_pattern": "(构建|修复|添加|删除|确认|创建|实现|修理|编写|测试|验证|更新|配置|启动|停止)(?:了|完成|成功)"
+  },
+  "entity": {
+    "boundary_chars": "\\u4E00-\\u9FFF",
+    "candidate_pattern": "[王李张刘陈杨赵黄周吴徐孙朱胡郭何高林罗郑梁谢宋唐许韩冯邓曹彭曾萧田董袁潘于蒋蔡余杜叶程苏魏吕丁任沈姚卢姜崔钟谭陆汪范金石廖贾夏韦方白邹孟熊秦邱江尹薛阎段雷侯龙史陶黎贺顾毛郝龚邵万钱严武戴莫孔向汤温庞殷章葛管甘卞冉蓝殷习][\\u4E00-\\u9FFF]{1,2}",
+    "person_verb_patterns": [
+      "{name}说",
+      "{name}问",
+      "{name}答",
+      "{name}表示",
+      "{name}回答",
+      "{name}提出",
+      "{name}决定",
+      "{name}认为",
+      "{name}指出",
+      "{name}解释",
+      "{name}告诉",
+      "{name}写道",
+      "{name}想",
+      "{name}觉得",
+      "{name}知道",
+      "{name}喜欢",
+      "{name}讨厌",
+      "{name}确认",
+      "{name}提醒",
+      "{name}分享",
+      "{name}建议",
+      "{name}同意",
+      "{name}反对"
+    ],
+    "pronoun_patterns": [
+      "他们",
+      "她们",
+      "他",
+      "她",
+      "它",
+      "您",
+      "咱"
+    ],
+    "dialogue_patterns": [
+      "^>\\s*{name}[:：\\s]",
+      "^{name}[:：]\\s?",
+      "^\\[{name}\\]",
+      "\u201C{name}[\u201D:：]",
+      "「{name}[」:：]"
+    ],
+    "direct_address_pattern": "嘿\\s*{name}|喂\\s*{name}|谢谢\\s*{name}|感谢\\s*{name}|哈喽\\s*{name}|亲爱的\\s*{name}",
+    "project_verb_patterns": [
+      "建立{name}",
+      "打造{name}",
+      "部署{name}",
+      "启动{name}",
+      "发布{name}",
+      "上线{name}",
+      "开发{name}",
+      "维护{name}",
+      "{name}系统",
+      "{name}平台",
+      "{name}项目",
+      "{name}架构",
+      "{name}管线",
+      "{name}v\\d+",
+      "\\bimport\\s+{name}\\b",
+      "\\bpip\\s+install\\s+{name}\\b"
+    ],
+    "stopwords": [
+      "的", "了", "着", "过", "得", "地", "吗", "吧", "呢", "啊", "喔", "耶",
+      "我", "你", "妳", "他", "她", "它", "您", "咱",
+      "我们", "你们", "妳们", "他们", "她们", "它们", "咱们",
+      "自己", "大家", "有人", "没人",
+      "今天", "明天", "昨天", "前天", "后天", "今年", "明年", "去年",
+      "早上", "下午", "晚上", "中午", "凌晨",
+      "现在", "刚才", "刚刚", "等等", "等下", "待会",
+      "最近", "以前", "之前", "之后", "以后", "后来",
+      "什么", "为什么", "怎么", "怎样", "哪里", "哪个",
+      "这个", "那个", "这里", "那里", "这些", "那些", "这样", "那样",
+      "但是", "可是", "然后", "所以", "因为", "如果", "虽然",
+      "而且", "或者", "或是", "还是", "不过", "只是", "不只",
+      "既然", "不然", "否则", "此外", "另外",
+      "很", "非常", "相当", "真的", "确实", "当然", "其实",
+      "已经", "正在", "即将", "将要", "刚好", "恰好",
+      "可能", "也许", "或许", "大概", "应该", "必须", "一定",
+      "完成", "执行", "进行", "开始", "结束", "继续", "停止", "完毕",
+      "没有", "有点", "有些", "一些", "许多", "很多",
+      "问题", "答案", "原因", "结果", "情况", "状况",
+      "主要", "重要", "基本", "简单", "复杂", "特别",
+      "谢谢", "感谢", "对不起", "不好意思", "请问",
+      "欢迎", "再见", "你好", "您好", "哈喽", "拜拜"
+    ]
   }
 }

mempalace/i18n/zh-TW.json

@@ -40,5 +40,93 @@
     "stop_words": "的 了 在 是 我 有 和 就 不 人 都 一 一個 上 也 很 到 說 要 去 你 會 著 沒有 看 好 自己 這 那 她 他 它 們 但是 因為 所以 如果 雖然 然後 或者 而且",
     "quote_pattern": "「([^」]{10,100})」|\u201c([^\u201d]{10,100})\u201d",
     "action_pattern": "(構建|修復|添加|刪除|確認|創建|實現|修理|編寫|測試|驗證|更新|配置|啟動|停止)(?:了|完成|成功)"
+  },
+  "entity": {
+    "boundary_chars": "\\u4E00-\\u9FFF",
+    "candidate_pattern": "[王李張劉陳楊趙黃周吳徐孫朱胡郭何高林羅鄭梁謝宋唐許韓馮鄧曹彭曾蕭田董袁潘于蔣蔡余杜葉程蘇魏呂丁任沈姚盧姜崔鍾譚陸汪范金石廖賈夏韋方白鄒孟熊秦邱江尹薛閻段雷侯龍史陶黎賀顧毛郝龔邵萬錢嚴武戴莫孔向湯溫龐殷章葛管甘卞冉藍殷習][\\u4E00-\\u9FFF]{1,2}",
+    "person_verb_patterns": [
+      "{name}說",
+      "{name}問",
+      "{name}答",
+      "{name}表示",
+      "{name}回答",
+      "{name}提出",
+      "{name}決定",
+      "{name}認為",
+      "{name}指出",
+      "{name}解釋",
+      "{name}告訴",
+      "{name}寫道",
+      "{name}想",
+      "{name}覺得",
+      "{name}知道",
+      "{name}喜歡",
+      "{name}討厭",
+      "{name}確認",
+      "{name}提醒",
+      "{name}分享",
+      "{name}建議",
+      "{name}同意",
+      "{name}反對"
+    ],
+    "pronoun_patterns": [
+      "他們",
+      "她們",
+      "他",
+      "她",
+      "它",
+      "您",
+      "咱"
+    ],
+    "dialogue_patterns": [
+      "^>\\s*{name}[:：\\s]",
+      "^{name}[:：]\\s?",
+      "^\\[{name}\\]",
+      "「{name}[」:：]",
+      "『{name}[』:：]"
+    ],
+    "direct_address_pattern": "嘿\\s*{name}|喂\\s*{name}|謝謝\\s*{name}|感謝\\s*{name}|哈囉\\s*{name}|親愛的\\s*{name}",
+    "project_verb_patterns": [
+      "建立{name}",
+      "打造{name}",
+      "部署{name}",
+      "啟動{name}",
+      "發布{name}",
+      "上線{name}",
+      "開發{name}",
+      "維護{name}",
+      "{name}系統",
+      "{name}平台",
+      "{name}專案",
+      "{name}架構",
+      "{name}管線",
+      "{name}v\\d+",
+      "\\bimport\\s+{name}\\b",
+      "\\bpip\\s+install\\s+{name}\\b"
+    ],
+    "stopwords": [
+      "的", "了", "著", "過", "得", "地", "嗎", "吧", "呢", "啊", "喔", "耶",
+      "我", "你", "妳", "他", "她", "它", "您", "咱",
+      "我們", "你們", "妳們", "他們", "她們", "它們", "咱們",
+      "自己", "大家", "有人", "沒人",
+      "今天", "明天", "昨天", "前天", "後天", "今年", "明年", "去年",
+      "早上", "下午", "晚上", "中午", "凌晨",
+      "現在", "剛才", "剛剛", "等等", "等下", "待會",
+      "最近", "以前", "之前", "之後", "以後", "後來",
+      "什麼", "甚麼", "為什麼", "怎麼", "怎樣", "哪裡", "哪個",
+      "這個", "那個", "這裡", "那裡", "這些", "那些", "這樣", "那樣",
+      "但是", "可是", "然後", "所以", "因為", "如果", "雖然",
+      "而且", "或者", "或是", "還是", "不過", "只是", "不只",
+      "既然", "不然", "否則", "此外", "另外",
+      "很", "非常", "相當", "真的", "確實", "當然", "其實",
+      "已經", "正在", "即將", "將要", "剛好", "恰好",
+      "可能", "也許", "或許", "大概", "應該", "必須", "一定",
+      "完成", "執行", "進行", "開始", "結束", "繼續", "停止", "完畢",
+      "沒有", "有點", "有些", "一些", "許多", "很多",
+      "問題", "答案", "原因", "結果", "情況", "狀況",
+      "主要", "重要", "基本", "簡單", "複雜", "特別",
+      "謝謝", "感謝", "對不起", "不好意思", "請問",
+      "歡迎", "再見", "你好", "您好", "哈囉", "掰掰"
+    ]
   }
 }

mempalace/instructions/init.md

@@ -49,7 +49,7 @@ If this fails, report the error and stop.
 
 Run the following command to register the MemPalace MCP server with Claude:
 
-    claude mcp add mempalace -- python -m mempalace.mcp_server
+    claude mcp add mempalace -- mempalace-mcp
 
 If this fails, report the error but continue to the next step (MCP
 configuration can be done manually later).

mempalace/instructions_cli.py

@@ -25,4 +25,4 @@ def run_instructions(name: str):
         print(f"Instructions file not found: {md_path}", file=sys.stderr)
         sys.exit(1)
 
-    print(md_path.read_text())
+    print(md_path.read_text(encoding="utf-8"))

mempalace/knowledge_graph.py

@@ -50,7 +50,12 @@ DEFAULT_KG_PATH = os.path.expanduser("~/.mempalace/knowledge_graph.sqlite3")
 class KnowledgeGraph:
     def __init__(self, db_path: str = None):
         self.db_path = db_path or DEFAULT_KG_PATH
-        Path(self.db_path).parent.mkdir(parents=True, exist_ok=True)
+        db_parent = Path(self.db_path).parent
+        db_parent.mkdir(parents=True, exist_ok=True)
+        try:
+            db_parent.chmod(0o700)
+        except (OSError, NotImplementedError):
+            pass
         self._connection = None
         self._lock = threading.Lock()
         self._init_db()
@@ -78,6 +83,8 @@ class KnowledgeGraph:
                 confidence REAL DEFAULT 1.0,
                 source_closet TEXT,
                 source_file TEXT,
+                source_drawer_id TEXT,
+                adapter_name TEXT,
                 extracted_at TEXT DEFAULT CURRENT_TIMESTAMP,
                 FOREIGN KEY (subject) REFERENCES entities(id),
                 FOREIGN KEY (object) REFERENCES entities(id)
@@ -88,8 +95,25 @@ class KnowledgeGraph:
             CREATE INDEX IF NOT EXISTS idx_triples_predicate ON triples(predicate);
             CREATE INDEX IF NOT EXISTS idx_triples_valid ON triples(valid_from, valid_to);
         """)
+        self._migrate_schema(conn)
         conn.commit()
 
+    def _migrate_schema(self, conn):
+        """Backwards-compatible schema migration for older triples tables.
+
+        Fresh palaces get ``source_drawer_id`` / ``adapter_name`` (RFC 002 §5.5)
+        directly from the canonical ``CREATE TABLE`` above, so this path is a
+        no-op on new installs. It exists for palaces that were created before
+        those columns were added: SQLite has no ``ADD COLUMN IF NOT EXISTS``,
+        so we introspect the schema and only issue the ALTER when the column
+        is missing.
+        """
+        existing = {row["name"] for row in conn.execute("PRAGMA table_info(triples)")}
+        if "source_drawer_id" not in existing:
+            conn.execute("ALTER TABLE triples ADD COLUMN source_drawer_id TEXT")
+        if "adapter_name" not in existing:
+            conn.execute("ALTER TABLE triples ADD COLUMN adapter_name TEXT")
+
     def _conn(self):
         if self._connection is None:
             self._connection = sqlite3.connect(self.db_path, timeout=10, check_same_thread=False)
@@ -99,9 +123,10 @@ class KnowledgeGraph:
 
     def close(self):
         """Close the database connection."""
-        if self._connection is not None:
-            self._connection.close()
-            self._connection = None
+        with self._lock:
+            if self._connection is not None:
+                self._connection.close()
+                self._connection = None
 
     def _entity_id(self, name: str) -> str:
         return name.lower().replace(" ", "_").replace("'", "")
@@ -131,10 +156,16 @@ class KnowledgeGraph:
         confidence: float = 1.0,
         source_closet: str = None,
         source_file: str = None,
+        source_drawer_id: str = None,
+        adapter_name: str = None,
     ):
         """
         Add a relationship triple: subject → predicate → object.
 
+        ``source_drawer_id`` and ``adapter_name`` are RFC 002 §5.5 provenance
+        fields populated by adapters that advertise ``supports_kg_triples``;
+        they default to ``None`` so every existing caller stays source-compatible.
+
         Examples:
             add_triple("Max", "child_of", "Alice", valid_from="2015-04-01")
             add_triple("Max", "does", "swimming", valid_from="2025-01-01")
@@ -167,8 +198,12 @@ class KnowledgeGraph:
                 triple_id = f"t_{sub_id}_{pred}_{obj_id}_{hashlib.sha256(f'{valid_from}{datetime.now().isoformat()}'.encode()).hexdigest()[:12]}"
 
                 conn.execute(
-                    """INSERT INTO triples (id, subject, predicate, object, valid_from, valid_to, confidence, source_closet, source_file)
-                       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+                    """INSERT INTO triples (
+                        id, subject, predicate, object,
+                        valid_from, valid_to, confidence,
+                        source_closet, source_file,
+                        source_drawer_id, adapter_name
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
                     (
                         triple_id,
                         sub_id,
@@ -179,6 +214,8 @@ class KnowledgeGraph:
                         confidence,
                         source_closet,
                         source_file,
+                        source_drawer_id,
+                        adapter_name,
                     ),
                 )
         return triple_id
@@ -260,7 +297,6 @@ class KnowledgeGraph:
     def query_relationship(self, predicate: str, as_of: str = None):
         """Get all triples with a given relationship type."""
         pred = predicate.lower().replace(" ", "_")
-        conn = self._conn()
         query = """
             SELECT t.*, s.name as sub_name, o.name as obj_name
             FROM triples t
@@ -274,45 +310,48 @@ class KnowledgeGraph:
             params.extend([as_of, as_of])
 
         results = []
-        for row in conn.execute(query, params).fetchall():
-            results.append(
-                {
-                    "subject": row["sub_name"],
-                    "predicate": pred,
-                    "object": row["obj_name"],
-                    "valid_from": row["valid_from"],
-                    "valid_to": row["valid_to"],
-                    "current": row["valid_to"] is None,
-                }
-            )
+        with self._lock:
+            conn = self._conn()
+            for row in conn.execute(query, params).fetchall():
+                results.append(
+                    {
+                        "subject": row["sub_name"],
+                        "predicate": pred,
+                        "object": row["obj_name"],
+                        "valid_from": row["valid_from"],
+                        "valid_to": row["valid_to"],
+                        "current": row["valid_to"] is None,
+                    }
+                )
         return results
 
     def timeline(self, entity_name: str = None):
         """Get all facts in chronological order, optionally filtered by entity."""
-        conn = self._conn()
-        if entity_name:
-            eid = self._entity_id(entity_name)
-            rows = conn.execute(
-                """
-                SELECT t.*, s.name as sub_name, o.name as obj_name
-                FROM triples t
-                JOIN entities s ON t.subject = s.id
-                JOIN entities o ON t.object = o.id
-                WHERE (t.subject = ? OR t.object = ?)
-                ORDER BY t.valid_from ASC NULLS LAST
-                LIMIT 100
-            """,
-                (eid, eid),
-            ).fetchall()
-        else:
-            rows = conn.execute("""
-                SELECT t.*, s.name as sub_name, o.name as obj_name
-                FROM triples t
-                JOIN entities s ON t.subject = s.id
-                JOIN entities o ON t.object = o.id
-                ORDER BY t.valid_from ASC NULLS LAST
-                LIMIT 100
-            """).fetchall()
+        with self._lock:
+            conn = self._conn()
+            if entity_name:
+                eid = self._entity_id(entity_name)
+                rows = conn.execute(
+                    """
+                    SELECT t.*, s.name as sub_name, o.name as obj_name
+                    FROM triples t
+                    JOIN entities s ON t.subject = s.id
+                    JOIN entities o ON t.object = o.id
+                    WHERE (t.subject = ? OR t.object = ?)
+                    ORDER BY t.valid_from ASC NULLS LAST
+                    LIMIT 100
+                """,
+                    (eid, eid),
+                ).fetchall()
+            else:
+                rows = conn.execute("""
+                    SELECT t.*, s.name as sub_name, o.name as obj_name
+                    FROM triples t
+                    JOIN entities s ON t.subject = s.id
+                    JOIN entities o ON t.object = o.id
+                    ORDER BY t.valid_from ASC NULLS LAST
+                    LIMIT 100
+                """).fetchall()
 
         return [
             {
@@ -329,19 +368,20 @@ class KnowledgeGraph:
     # ── Stats ─────────────────────────────────────────────────────────────
 
     def stats(self):
-        conn = self._conn()
-        entities = conn.execute("SELECT COUNT(*) as cnt FROM entities").fetchone()["cnt"]
-        triples = conn.execute("SELECT COUNT(*) as cnt FROM triples").fetchone()["cnt"]
-        current = conn.execute(
-            "SELECT COUNT(*) as cnt FROM triples WHERE valid_to IS NULL"
-        ).fetchone()["cnt"]
-        expired = triples - current
-        predicates = [
-            r["predicate"]
-            for r in conn.execute(
-                "SELECT DISTINCT predicate FROM triples ORDER BY predicate"
-            ).fetchall()
-        ]
+        with self._lock:
+            conn = self._conn()
+            entities = conn.execute("SELECT COUNT(*) as cnt FROM entities").fetchone()["cnt"]
+            triples = conn.execute("SELECT COUNT(*) as cnt FROM triples").fetchone()["cnt"]
+            current = conn.execute(
+                "SELECT COUNT(*) as cnt FROM triples WHERE valid_to IS NULL"
+            ).fetchone()["cnt"]
+            expired = triples - current
+            predicates = [
+                r["predicate"]
+                for r in conn.execute(
+                    "SELECT DISTINCT predicate FROM triples ORDER BY predicate"
+                ).fetchall()
+            ]
         return {
             "entities": entities,
             "triples": triples,

mempalace/layers.py

@@ -23,7 +23,7 @@ from collections import defaultdict
 
 from .config import MempalaceConfig
 from .palace import get_collection as _get_collection
-from .searcher import build_where_filter
+from .searcher import _first_or_empty, build_where_filter
 
 
 # ---------------------------------------------------------------------------
@@ -272,15 +272,17 @@ class Layer3:
         except Exception as e:
             return f"Search error: {e}"
 
-        docs = results["documents"][0]
-        metas = results["metadatas"][0]
-        dists = results["distances"][0]
+        docs = _first_or_empty(results, "documents")
+        metas = _first_or_empty(results, "metadatas")
+        dists = _first_or_empty(results, "distances")
 
         if not docs:
             return "No results found."
 
         lines = [f'## L3 — SEARCH RESULTS for "{query}"']
         for i, (doc, meta, dist) in enumerate(zip(docs, metas, dists), 1):
+            meta = meta or {}
+            doc = doc or ""
             similarity = round(1 - dist, 3)
             wing_name = meta.get("wing", "?")
             room_name = meta.get("room", "?")
@@ -323,10 +325,17 @@ class Layer3:
 
         hits = []
         for doc, meta, dist in zip(
-            results["documents"][0],
-            results["metadatas"][0],
-            results["distances"][0],
+            _first_or_empty(results, "documents"),
+            _first_or_empty(results, "metadatas"),
+            _first_or_empty(results, "distances"),
         ):
+            # ChromaDB may return None for doc/meta when a drawer's HNSW entry
+            # exists but its metadata/document rows haven't been materialized
+            # (partial-flush states, mid-delete, schema upgrade boundaries).
+            # Degrade gracefully — the hit still appears with real distance;
+            # storage fields show their fallback where content is missing.
+            meta = meta or {}
+            doc = doc or ""
             hits.append(
                 {
                     "text": doc,

mempalace/llm_client.py

@@ -0,0 +1,305 @@
+"""
+llm_client.py — Minimal provider abstraction for LLM-assisted entity refinement.
+
+Three providers cover the useful space:
+
+- ``ollama`` (default): local models via http://localhost:11434. Works fully
+  offline. Honors MemPalace's "zero-API required" principle.
+- ``openai-compat``: any OpenAI-compatible ``/v1/chat/completions`` endpoint.
+  Covers OpenRouter, LM Studio, llama.cpp server, vLLM, Groq, Fireworks,
+  Together, and most self-hosted setups.
+- ``anthropic``: the official Messages API. Opt-in for users who want Haiku
+  quality without setting up a local model.
+
+All providers expose the same ``classify(system, user, json_mode)`` method and
+the same ``check_available()`` probe. No external SDK dependencies — stdlib
+``urllib`` only.
+
+JSON mode matters here: we always ask for structured output. Providers
+differ on how to request it (Ollama: ``format: json``; OpenAI-compat:
+``response_format``; Anthropic: prompt-level instruction) and this module
+normalizes that away from the caller.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from typing import Optional
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+
+class LLMError(RuntimeError):
+    """Raised for any provider failure — transport, parse, auth, missing model."""
+
+
+@dataclass
+class LLMResponse:
+    text: str
+    model: str
+    provider: str
+    raw: dict
+
+
+# ==================== BASE ====================
+
+
+class LLMProvider:
+    name: str = "base"
+
+    def __init__(
+        self,
+        model: str,
+        endpoint: Optional[str] = None,
+        api_key: Optional[str] = None,
+        timeout: int = 120,
+    ):
+        self.model = model
+        self.endpoint = endpoint
+        self.api_key = api_key
+        self.timeout = timeout
+
+    def classify(self, system: str, user: str, json_mode: bool = True) -> LLMResponse:
+        raise NotImplementedError
+
+    def check_available(self) -> tuple[bool, str]:
+        """Return ``(ok, message)``. Fast probe that the provider is reachable."""
+        raise NotImplementedError
+
+
+def _http_post_json(url: str, body: dict, headers: dict, timeout: int) -> dict:
+    """POST JSON and return the parsed response. Raises LLMError on any failure."""
+    req = Request(
+        url,
+        data=json.dumps(body).encode("utf-8"),
+        headers={"Content-Type": "application/json", **headers},
+    )
+    try:
+        with urlopen(req, timeout=timeout) as resp:
+            return json.loads(resp.read())
+    except HTTPError as e:
+        detail = ""
+        try:
+            detail = e.read().decode("utf-8", errors="replace")[:500]
+        except Exception:
+            pass
+        raise LLMError(f"HTTP {e.code} from {url}: {detail or e.reason}") from e
+    except (URLError, OSError) as e:
+        raise LLMError(f"Cannot reach {url}: {e}") from e
+    except json.JSONDecodeError as e:
+        raise LLMError(f"Malformed response from {url}: {e}") from e
+
+
+# ==================== OLLAMA ====================
+
+
+class OllamaProvider(LLMProvider):
+    name = "ollama"
+    DEFAULT_ENDPOINT = "http://localhost:11434"
+
+    def __init__(
+        self,
+        model: str,
+        endpoint: Optional[str] = None,
+        timeout: int = 180,
+        **_: object,
+    ):
+        super().__init__(
+            model=model,
+            endpoint=endpoint or self.DEFAULT_ENDPOINT,
+            timeout=timeout,
+        )
+
+    def check_available(self) -> tuple[bool, str]:
+        try:
+            with urlopen(f"{self.endpoint}/api/tags", timeout=5) as resp:
+                data = json.loads(resp.read())
+        except (URLError, HTTPError, OSError, json.JSONDecodeError) as e:
+            return False, f"Cannot reach Ollama at {self.endpoint}: {e}"
+        names = {m.get("name", "") for m in data.get("models", []) or []}
+        # Ollama tags may or may not include ':latest' — accept either form
+        wanted = {self.model, f"{self.model}:latest"}
+        if not names & wanted:
+            return (
+                False,
+                f"Model '{self.model}' not loaded in Ollama. Run: ollama pull {self.model}",
+            )
+        return True, "ok"
+
+    def classify(self, system: str, user: str, json_mode: bool = True) -> LLMResponse:
+        body: dict = {
+            "model": self.model,
+            "messages": [
+                {"role": "system", "content": system},
+                {"role": "user", "content": user},
+            ],
+            "stream": False,
+            "options": {"temperature": 0.1},
+        }
+        if json_mode:
+            body["format"] = "json"
+        data = _http_post_json(f"{self.endpoint}/api/chat", body, headers={}, timeout=self.timeout)
+        text = (data.get("message") or {}).get("content", "")
+        if not text:
+            raise LLMError(f"Empty response from Ollama (model={self.model})")
+        return LLMResponse(text=text, model=self.model, provider=self.name, raw=data)
+
+
+# ==================== OPENAI-COMPAT ====================
+
+
+class OpenAICompatProvider(LLMProvider):
+    """Any OpenAI-compatible ``/v1/chat/completions`` endpoint.
+
+    Supply ``--llm-endpoint http://host:port`` (with or without ``/v1``).
+    API key via ``--llm-api-key`` or the ``OPENAI_API_KEY`` env var.
+    """
+
+    name = "openai-compat"
+
+    def __init__(
+        self,
+        model: str,
+        endpoint: Optional[str] = None,
+        api_key: Optional[str] = None,
+        timeout: int = 120,
+        **_: object,
+    ):
+        resolved_key = api_key or os.environ.get("OPENAI_API_KEY")
+        super().__init__(model=model, endpoint=endpoint, api_key=resolved_key, timeout=timeout)
+
+    def _resolve_url(self) -> str:
+        if not self.endpoint:
+            raise LLMError("openai-compat provider requires --llm-endpoint")
+        url = self.endpoint.rstrip("/")
+        if url.endswith("/chat/completions"):
+            return url
+        if not url.endswith("/v1"):
+            url = f"{url}/v1"
+        return f"{url}/chat/completions"
+
+    def check_available(self) -> tuple[bool, str]:
+        if not self.endpoint:
+            return False, "no --llm-endpoint configured"
+        base = self.endpoint.rstrip("/")
+        base = base.removesuffix("/chat/completions").removesuffix("/v1")
+        try:
+            req = Request(f"{base}/v1/models")
+            if self.api_key:
+                req.add_header("Authorization", f"Bearer {self.api_key}")
+            with urlopen(req, timeout=5):
+                pass
+        except (URLError, HTTPError, OSError) as e:
+            return False, f"Cannot reach {self.endpoint}: {e}"
+        return True, "ok"
+
+    def classify(self, system: str, user: str, json_mode: bool = True) -> LLMResponse:
+        body: dict = {
+            "model": self.model,
+            "messages": [
+                {"role": "system", "content": system},
+                {"role": "user", "content": user},
+            ],
+            "temperature": 0.1,
+        }
+        if json_mode:
+            body["response_format"] = {"type": "json_object"}
+        headers = {}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        data = _http_post_json(self._resolve_url(), body, headers=headers, timeout=self.timeout)
+        try:
+            text = data["choices"][0]["message"]["content"]
+        except (KeyError, IndexError, TypeError) as e:
+            raise LLMError(f"Unexpected response shape: {e}") from e
+        if not text:
+            raise LLMError(f"Empty response from {self.name} (model={self.model})")
+        return LLMResponse(text=text, model=self.model, provider=self.name, raw=data)
+
+
+# ==================== ANTHROPIC ====================
+
+
+class AnthropicProvider(LLMProvider):
+    name = "anthropic"
+    DEFAULT_ENDPOINT = "https://api.anthropic.com"
+    API_VERSION = "2023-06-01"
+
+    def __init__(
+        self,
+        model: str,
+        api_key: Optional[str] = None,
+        endpoint: Optional[str] = None,
+        timeout: int = 120,
+        **_: object,
+    ):
+        key = api_key or os.environ.get("ANTHROPIC_API_KEY")
+        super().__init__(
+            model=model,
+            endpoint=endpoint or self.DEFAULT_ENDPOINT,
+            api_key=key,
+            timeout=timeout,
+        )
+
+    def check_available(self) -> tuple[bool, str]:
+        if not self.api_key:
+            return False, "ANTHROPIC_API_KEY not set (use --llm-api-key or env)"
+        # Don't probe — a live request would cost money. First real call will
+        # surface auth errors if the key is invalid.
+        return True, "ok"
+
+    def classify(self, system: str, user: str, json_mode: bool = True) -> LLMResponse:
+        if not self.api_key:
+            raise LLMError("Anthropic provider requires ANTHROPIC_API_KEY env or --llm-api-key")
+        sys_prompt = system
+        if json_mode:
+            sys_prompt += "\n\nRespond with valid JSON only, no prose."
+        body = {
+            "model": self.model,
+            "max_tokens": 2048,
+            "temperature": 0.1,
+            "system": sys_prompt,
+            "messages": [{"role": "user", "content": user}],
+        }
+        headers = {
+            "X-API-Key": self.api_key,
+            "anthropic-version": self.API_VERSION,
+        }
+        data = _http_post_json(
+            f"{self.endpoint}/v1/messages", body, headers=headers, timeout=self.timeout
+        )
+        try:
+            text = "".join(
+                b.get("text", "") for b in data.get("content", []) or [] if b.get("type") == "text"
+            )
+        except (AttributeError, TypeError) as e:
+            raise LLMError(f"Unexpected response shape: {e}") from e
+        if not text:
+            raise LLMError(f"Empty response from Anthropic (model={self.model})")
+        return LLMResponse(text=text, model=self.model, provider=self.name, raw=data)
+
+
+# ==================== FACTORY ====================
+
+
+PROVIDERS: dict[str, type[LLMProvider]] = {
+    "ollama": OllamaProvider,
+    "openai-compat": OpenAICompatProvider,
+    "anthropic": AnthropicProvider,
+}
+
+
+def get_provider(
+    name: str,
+    model: str,
+    endpoint: Optional[str] = None,
+    api_key: Optional[str] = None,
+    timeout: int = 120,
+) -> LLMProvider:
+    """Build a provider by name. Raises LLMError on unknown provider."""
+    cls = PROVIDERS.get(name)
+    if cls is None:
+        raise LLMError(f"Unknown provider '{name}'. Choices: {sorted(PROVIDERS.keys())}")
+    return cls(model=model, endpoint=endpoint, api_key=api_key, timeout=timeout)

mempalace/llm_refine.py

@@ -0,0 +1,446 @@
+"""
+llm_refine.py — Optional LLM refinement of regex-detected entities.
+
+Takes the candidate set produced by phase-1 detection (manifests, git
+authors, regex on prose) and asks an LLM to reclassify each candidate as
+PERSON / PROJECT / TOPIC / COMMON_WORD / AMBIGUOUS.
+
+Design constraints:
+- Opt-in. Default init path never imports this module.
+- Local-first by default (Ollama).
+- Interactive UX: visible progress, clean cancellation (Ctrl-C returns
+  whatever was classified before the interrupt).
+- Don't feed the raw corpus to the LLM — feed candidates + a few sampled
+  context lines each. Keeps total input to ~50-100K tokens even for huge
+  prose corpora.
+
+Public:
+    refine_entities(detected, corpus_text, provider, ...) -> dict
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from dataclasses import dataclass
+
+from mempalace.llm_client import LLMError, LLMProvider
+
+
+BATCH_SIZE = 25  # candidates per LLM call; tuned for 4B local models
+CONTEXT_LINES_PER_CANDIDATE = 3
+CONTEXT_WINDOW_CHARS = 240  # max chars per context line to keep tokens bounded
+
+# Valid labels the LLM is allowed to return. Anything else is treated as
+# AMBIGUOUS so the user reviews it.
+VALID_LABELS = {"PERSON", "PROJECT", "TOPIC", "COMMON_WORD", "AMBIGUOUS"}
+
+
+SYSTEM_PROMPT = """You are helping organize a user's memory palace by classifying capitalized tokens found in their files.
+
+For each candidate, pick exactly ONE label:
+- PERSON: a specific real person the user knows (colleague, family, character they write about)
+- PROJECT: a named product, codebase, or effort the user works on
+- TOPIC: a recurring theme or subject (not a person, not a project) — cities, technologies, concepts
+- COMMON_WORD: an English word, verb, or fragment that isn't a named entity at all (e.g. "Created", "Before", "Never")
+- AMBIGUOUS: context is insufficient to decide between two of the above
+
+Frameworks, runtimes, APIs, cloud services, vendors, and third-party products
+(e.g. Angular, OpenAPI, Terraform, Bun, Google) are TOPIC unless the context
+clearly says this is the user's own named codebase, product, or active effort.
+
+Use the provided context lines to disambiguate. A capitalized word that only appears in metadata ("Created: 2026-04-24") is COMMON_WORD. A name that appears with pronouns and dialogue is PERSON.
+
+Respond with JSON only. Schema:
+{"classifications": [{"name": "<exact candidate name>", "label": "<LABEL>", "reason": "<one short sentence>"}]}
+
+One entry per candidate, same order as the input."""
+
+
+@dataclass
+class RefineResult:
+    merged: dict  # updated detected dict
+    reclassified: int  # entries whose type changed
+    dropped: int  # entries removed from the merged result (COMMON_WORD only)
+    errors: list[str]  # per-batch error messages (transport/parse failures)
+    batches_completed: int
+    batches_total: int
+    cancelled: bool
+
+
+def _collect_contexts(
+    corpus_lines: list[str], name: str, max_lines: int = CONTEXT_LINES_PER_CANDIDATE
+) -> list[str]:
+    """Return up to `max_lines` distinct lines from the corpus that mention `name`.
+
+    Case-insensitive token-boundary match. Lines are truncated to
+    CONTEXT_WINDOW_CHARS chars to keep token usage bounded.
+    """
+    needle = re.compile(rf"(?<!\w){re.escape(name)}(?!\w)", re.IGNORECASE)
+    seen: set[str] = set()
+    out: list[str] = []
+    for line in corpus_lines:
+        if not needle.search(line):
+            continue
+        trimmed = line.strip()[:CONTEXT_WINDOW_CHARS]
+        if not trimmed or trimmed in seen:
+            continue
+        seen.add(trimmed)
+        out.append(trimmed)
+        if len(out) >= max_lines:
+            break
+    return out
+
+
+def _build_user_prompt(candidates_with_contexts: list[tuple[str, str, list[str]]]) -> str:
+    """Shape: for each candidate, list its current type guess + sampled contexts."""
+    parts: list[str] = ["CANDIDATES:"]
+    for i, (name, current_type, contexts) in enumerate(candidates_with_contexts, 1):
+        parts.append(f"\n{i}. {name}  (currently: {current_type})")
+        if contexts:
+            for c in contexts:
+                parts.append(f"   > {c}")
+        else:
+            parts.append("   > (no context available)")
+    return "\n".join(parts)
+
+
+def _extract_json_candidates(text: str) -> list[str]:
+    """Return plausible JSON payloads extracted from an LLM response."""
+    text = text.strip()
+    if not text:
+        return []
+
+    candidates: list[str] = [text]
+
+    for match in re.finditer(r"```(?:json)?\s*([\s\S]*?)\s*```", text, re.IGNORECASE):
+        candidate = match.group(1).strip()
+        if candidate and candidate not in candidates:
+            candidates.append(candidate)
+
+    for start, opener in ((i, ch) for i, ch in enumerate(text) if ch in "{["):
+        closer = "}" if opener == "{" else "]"
+        depth = 0
+        in_string = False
+        escaped = False
+        for i in range(start, len(text)):
+            ch = text[i]
+            if in_string:
+                if escaped:
+                    escaped = False
+                elif ch == "\\":
+                    escaped = True
+                elif ch == '"':
+                    in_string = False
+                continue
+
+            if ch == '"':
+                in_string = True
+            elif ch == opener:
+                depth += 1
+            elif ch == closer:
+                depth -= 1
+                if depth == 0:
+                    candidate = text[start : i + 1].strip()
+                    if candidate and candidate not in candidates:
+                        candidates.append(candidate)
+                    break
+
+    return candidates
+
+
+def _parse_response(text: str, expected_names: list[str]) -> dict[str, tuple[str, str]]:
+    """Parse the LLM's JSON response into {name: (label, reason)}.
+
+    Robust to the model occasionally wrapping JSON in text or returning
+    slight schema variations. Falls back to matching by candidate name.
+    """
+    data = None
+    for candidate in _extract_json_candidates(text):
+        try:
+            data = json.loads(candidate)
+            break
+        except json.JSONDecodeError:
+            continue
+    if data is None:
+        return {}
+
+    entries = data.get("classifications") if isinstance(data, dict) else data
+    if not isinstance(entries, list):
+        return {}
+
+    name_to_label: dict[str, tuple[str, str]] = {}
+    expected_set = {n.lower(): n for n in expected_names}
+    for entry in entries:
+        if not isinstance(entry, dict):
+            continue
+        name = entry.get("name") or entry.get("candidate")
+        label = entry.get("label") or entry.get("type") or entry.get("classification")
+        reason = entry.get("reason") or ""
+        if not isinstance(name, str) or not isinstance(label, str):
+            continue
+        # Restore canonical casing from expected_names
+        canonical = expected_set.get(name.lower(), name)
+        lbl = label.strip().upper()
+        if lbl not in VALID_LABELS:
+            lbl = "AMBIGUOUS"
+        name_to_label[canonical] = (lbl, reason.strip()[:120])
+    return name_to_label
+
+
+def _apply_classifications(
+    detected: dict,
+    decisions: dict[str, tuple[str, str]],
+    allow_project_promotions: bool = True,
+) -> tuple[dict, int, int]:
+    """Merge LLM decisions back into the detected dict.
+
+    Returns (new_detected, reclassified_count, dropped_count).
+    """
+    label_to_bucket = {
+        "PERSON": "people",
+        "PROJECT": "projects",
+        "TOPIC": "uncertain",
+        "AMBIGUOUS": "uncertain",
+    }
+
+    # Index every entity by name for in-place update
+    all_entries: list[tuple[str, dict]] = []
+    for bucket, items in detected.items():
+        for e in items:
+            all_entries.append((bucket, e))
+
+    reclassified = 0
+    dropped = 0
+    new_detected: dict[str, list[dict]] = {
+        "people": [],
+        "projects": [],
+        "uncertain": [],
+    }
+
+    for old_bucket, entry in all_entries:
+        decision = decisions.get(entry["name"])
+        if decision is None:
+            # No LLM opinion — keep as-is
+            new_detected[old_bucket].append(entry)
+            continue
+
+        label, reason = decision
+        if label == "COMMON_WORD":
+            dropped += 1
+            continue
+
+        target_bucket = label_to_bucket[label]
+        if (
+            label == "PROJECT"
+            and not allow_project_promotions
+            and not _is_authoritative_project(entry)
+        ):
+            target_bucket = "uncertain"
+        updated = dict(entry)
+        # Append the LLM's reason as a new signal so the user sees why it moved
+        signals = list(updated.get("signals", []))
+        signals.append(f"LLM: {label.lower()} — {reason}" if reason else f"LLM: {label.lower()}")
+        updated["signals"] = signals
+        if target_bucket != old_bucket:
+            reclassified += 1
+            updated["type"] = (
+                "person"
+                if target_bucket == "people"
+                else "project"
+                if target_bucket == "projects"
+                else "uncertain"
+            )
+        new_detected[target_bucket].append(updated)
+
+    return new_detected, reclassified, dropped
+
+
+def _is_authoritative_person(entry: dict) -> bool:
+    """Return True for git-author people that should not be second-guessed."""
+    signals = " ".join(entry.get("signals", [])).lower()
+    return "commit" in signals and "repo" in signals
+
+
+def _is_authoritative_project(entry: dict) -> bool:
+    """Return True for manifest/git-backed projects that are already source-backed."""
+    signals = " ".join(entry.get("signals", [])).lower()
+    manifest_markers = ("package.json", "pyproject.toml", "cargo.toml", "go.mod")
+    return any(marker in signals for marker in manifest_markers) or "commit" in signals
+
+
+def _print_progress(batch_idx: int, total: int, current_name: str) -> None:
+    """Overwrite-line progress indicator."""
+    width = 40
+    filled = int(width * batch_idx / total) if total else 0
+    bar = "█" * filled + "░" * (width - filled)
+    msg = f"\r  LLM refine: [{bar}] batch {batch_idx}/{total}  current: {current_name[:30]:<30}"
+    sys.stderr.write(msg)
+    sys.stderr.flush()
+
+
+def refine_entities(
+    detected: dict,
+    corpus_text: str,
+    provider: LLMProvider,
+    batch_size: int = BATCH_SIZE,
+    show_progress: bool = True,
+    allow_project_promotions: bool = True,
+) -> RefineResult:
+    """Reclassify detected entities using the LLM provider.
+
+    Only regex-derived candidates are sent for refinement. Git authors and
+    manifest/git-backed projects are already source-backed and don't benefit
+    from LLM second-guessing.
+
+    Ctrl-C during refinement: cancels the remaining batches, returns a
+    RefineResult with ``cancelled=True`` and whatever was classified before
+    the interrupt. The partial result is safe to pass straight to
+    ``confirm_entities``.
+
+    Transport or parse failures in individual batches are recorded in
+    ``errors`` and do not abort the run.
+
+    ``allow_project_promotions=False`` keeps LLM-only project guesses in the
+    uncertain bucket. This is useful when manifest/git signal already supplied
+    canonical projects and regex/LLM hits are likely tools, vendors, or topics.
+    """
+    candidates: list[tuple[str, str]] = []
+    current_type = {"people": "person", "projects": "project", "uncertain": "uncertain"}
+    for bucket in ("people", "projects", "uncertain"):
+        for e in detected.get(bucket, []):
+            if bucket == "people" and _is_authoritative_person(e):
+                continue
+            if bucket == "projects" and _is_authoritative_project(e):
+                continue
+            candidates.append((e["name"], current_type[bucket]))
+
+    corpus_lines = corpus_text.splitlines() if corpus_text else []
+
+    # Deduplicate candidate names while preserving order
+    seen: set[str] = set()
+    unique: list[tuple[str, str]] = []
+    for name, kind in candidates:
+        if name not in seen:
+            seen.add(name)
+            unique.append((name, kind))
+
+    if not unique:
+        return RefineResult(
+            merged=detected,
+            reclassified=0,
+            dropped=0,
+            errors=[],
+            batches_completed=0,
+            batches_total=0,
+            cancelled=False,
+        )
+
+    # Build batches
+    batches: list[list[tuple[str, str, list[str]]]] = []
+    for i in range(0, len(unique), batch_size):
+        chunk = unique[i : i + batch_size]
+        enriched = [(name, kind, _collect_contexts(corpus_lines, name)) for name, kind in chunk]
+        batches.append(enriched)
+
+    all_decisions: dict[str, tuple[str, str]] = {}
+    errors: list[str] = []
+    completed = 0
+    cancelled = False
+
+    for idx, batch in enumerate(batches, 1):
+        if show_progress and batch:
+            _print_progress(idx - 1, len(batches), batch[0][0])
+        user_prompt = _build_user_prompt(batch)
+        try:
+            resp = provider.classify(SYSTEM_PROMPT, user_prompt, json_mode=True)
+        except KeyboardInterrupt:
+            cancelled = True
+            break
+        except LLMError as e:
+            errors.append(f"batch {idx}: {e}")
+            continue
+        names_in_batch = [name for name, _, _ in batch]
+        decisions = _parse_response(resp.text, names_in_batch)
+        if not decisions:
+            errors.append(f"batch {idx}: could not parse response")
+        all_decisions.update(decisions)
+        completed += 1
+        if show_progress:
+            _print_progress(idx, len(batches), batch[-1][0])
+
+    if show_progress:
+        sys.stderr.write("\n")
+        sys.stderr.flush()
+
+    merged, reclassified, dropped = _apply_classifications(
+        detected,
+        all_decisions,
+        allow_project_promotions=allow_project_promotions,
+    )
+
+    return RefineResult(
+        merged=merged,
+        reclassified=reclassified,
+        dropped=dropped,
+        errors=errors,
+        batches_completed=completed,
+        batches_total=len(batches),
+        cancelled=cancelled,
+    )
+
+
+def collect_corpus_text(
+    project_dir: str,
+    max_files: int = 30,
+    max_bytes_per_file: int = 20_000,
+) -> str:
+    """Gather prose text from ``project_dir`` for use as LLM context source.
+
+    Stratified: reads up to ``max_files`` prose files (``.md``, ``.txt``,
+    ``.rst``), preferring recently-modified. Each file capped at
+    ``max_bytes_per_file`` to bound total input.
+    """
+    from pathlib import Path
+
+    from mempalace.entity_detector import PROSE_EXTENSIONS, SKIP_DIRS
+
+    root = Path(project_dir).expanduser().resolve()
+    if not root.is_dir():
+        return ""
+    candidates: list[tuple[float, Path]] = []
+    for dirpath, dirs, files in _walk_prose(root, SKIP_DIRS):
+        for fname in files:
+            p = dirpath / fname
+            if p.suffix.lower() not in PROSE_EXTENSIONS:
+                continue
+            try:
+                mtime = p.stat().st_mtime
+            except OSError:
+                continue
+            candidates.append((mtime, p))
+    candidates.sort(reverse=True)
+    selected = [p for _, p in candidates[:max_files]]
+    chunks: list[str] = []
+    for p in selected:
+        try:
+            with open(p, encoding="utf-8", errors="replace") as f:
+                chunks.append(f.read(max_bytes_per_file))
+        except OSError:
+            continue
+    return "\n".join(chunks)
+
+
+def _walk_prose(root, skip_dirs):
+    """Walk a directory yielding (Path, dirs, files), pruning skip_dirs.
+
+    Inlined from ``project_scanner._walk`` to avoid a private-name import
+    coupling. Functionality is intentionally narrow: prose collection only.
+    """
+    import os
+    from pathlib import Path
+
+    for dirpath, dirs, files in os.walk(root):
+        dirs[:] = [d for d in dirs if d not in skip_dirs and not d.startswith(".")]
+        yield Path(dirpath), dirs, files

mempalace/mcp_server.py

@@ -2,7 +2,7 @@
 """
 MemPalace MCP Server — read/write palace access for Claude Code
 ================================================================
-Install: claude mcp add mempalace -- python -m mempalace.mcp_server [--palace /path/to/palace]
+Install: claude mcp add mempalace -- mempalace-mcp [--palace /path/to/palace]
 
 Tools (read):
   mempalace_status          — total drawers, wing/room breakdown
@@ -20,22 +20,47 @@ Tools (maintenance):
   mempalace_reconnect       — force cache invalidation and reconnect after external writes
 """
 
-import argparse
 import os
 import sys
-import json
-import logging
-import hashlib
-import time
-from datetime import datetime
-from pathlib import Path
 
-from .config import MempalaceConfig, sanitize_name, sanitize_content
-from .version import __version__
-import chromadb
-from .query_sanitizer import sanitize_query
-from .searcher import search_memories
-from .palace_graph import (
+# --- MCP stdio protection (issue #225) -----------------------------------
+# The MCP protocol multiplexes JSON-RPC over stdio: stdout MUST carry only
+# valid JSON-RPC messages, stderr is for human-readable logs. Some
+# transitive dependencies (chromadb → onnxruntime, posthog telemetry) print
+# banners and error messages directly to stdout — sometimes at C level —
+# which breaks Claude Desktop's JSON parser. Redirect stdout → stderr at
+# both the Python and file-descriptor level before heavy imports, then
+# restore the real stdout in main() before entering the protocol loop.
+_REAL_STDOUT = sys.stdout
+_REAL_STDOUT_FD = None
+try:
+    _REAL_STDOUT_FD = os.dup(1)
+    os.dup2(2, 1)
+except (OSError, AttributeError):
+    # Environments without fd-level stdio (embedded interpreters, some test
+    # harnesses). The Python-level redirect below still applies.
+    pass
+sys.stdout = sys.stderr
+
+import argparse  # noqa: E402  (deferred until after stdio protection above)
+import json  # noqa: E402
+import logging  # noqa: E402
+import hashlib  # noqa: E402
+import time  # noqa: E402
+from datetime import datetime  # noqa: E402
+from pathlib import Path  # noqa: E402
+
+from .config import (  # noqa: E402
+    MempalaceConfig,
+    sanitize_kg_value,
+    sanitize_name,
+    sanitize_content,
+)
+from .version import __version__  # noqa: E402
+from .backends.chroma import ChromaBackend, ChromaCollection  # noqa: E402
+from .query_sanitizer import sanitize_query  # noqa: E402
+from .searcher import search_memories  # noqa: E402
+from .palace_graph import (  # noqa: E402
     traverse,
     find_tunnels,
     graph_stats,
@@ -45,7 +70,7 @@ from .palace_graph import (
     follow_tunnels,
 )
 
-from .knowledge_graph import KnowledgeGraph
+from .knowledge_graph import KnowledgeGraph  # noqa: E402
 
 logging.basicConfig(level=logging.INFO, format="%(message)s", stream=sys.stderr)
 logger = logging.getLogger("mempalace_mcp")
@@ -96,14 +121,14 @@ try:
 except (OSError, NotImplementedError):
     pass
 _WAL_FILE = _WAL_DIR / "write_log.jsonl"
-# Pre-create WAL file with restricted permissions to avoid race condition
-if not _WAL_FILE.exists():
-    _WAL_FILE.touch(mode=0o600)
-else:
-    try:
-        _WAL_FILE.chmod(0o600)
-    except (OSError, NotImplementedError):
-        pass
+# Atomically create WAL file with restricted permissions (no TOCTOU race).
+# os.open with O_CREAT|O_WRONLY and mode 0o600 creates the file if absent
+# or opens it if present, both in a single syscall.
+try:
+    _fd = os.open(str(_WAL_FILE), os.O_CREAT | os.O_WRONLY, 0o600)
+    os.close(_fd)
+except (OSError, NotImplementedError):
+    pass
 
 # Keys whose values should be redacted in WAL entries to avoid logging sensitive content
 _WAL_REDACT_KEYS = frozenset(
@@ -177,7 +202,7 @@ def _get_client():
     mtime_changed = current_mtime != 0.0 and abs(current_mtime - _palace_db_mtime) > 0.01
 
     if _client_cache is None or inode_changed or mtime_changed:
-        _client_cache = chromadb.PersistentClient(path=_config.palace_path)
+        _client_cache = ChromaBackend.make_client(_config.palace_path)
         _collection_cache = None
         _metadata_cache = None
         _metadata_cache_time = 0
@@ -192,13 +217,15 @@ def _get_collection(create=False):
     try:
         client = _get_client()
         if create:
-            _collection_cache = client.get_or_create_collection(
-                _config.collection_name, metadata={"hnsw:space": "cosine"}
+            _collection_cache = ChromaCollection(
+                client.get_or_create_collection(
+                    _config.collection_name, metadata={"hnsw:space": "cosine"}
+                )
             )
             _metadata_cache = None
             _metadata_cache_time = 0
         elif _collection_cache is None:
-            _collection_cache = client.get_collection(_config.collection_name)
+            _collection_cache = ChromaCollection(client.get_collection(_config.collection_name))
             _metadata_cache = None
             _metadata_cache_time = 0
         return _collection_cache
@@ -258,7 +285,7 @@ def _get_cached_metadata(col, where=None):
 
 def _sanitize_optional_name(value: str = None, field_name: str = "name") -> str:
     """Validate optional wing/room-style filters."""
-    if value is None:
+    if value is None or not value.strip():
         return None
     return sanitize_name(value, field_name)
 
@@ -267,7 +294,11 @@ def _sanitize_optional_name(value: str = None, field_name: str = "name") -> str:
 
 
 def tool_status():
-    col = _get_collection()
+    # Use create=True only when a palace DB already exists on disk -- this
+    # bootstraps the ChromaDB collection on a valid-but-empty palace without
+    # accidentally creating a palace in a non-existent directory (#830).
+    db_exists = os.path.isfile(os.path.join(_config.palace_path, "chroma.sqlite3"))
+    col = _get_collection(create=db_exists)
     if not col:
         return _no_palace()
     count = col.count()
@@ -284,6 +315,7 @@ def tool_status():
     try:
         all_meta = _get_cached_metadata(col)
         for m in all_meta:
+            m = m or {}
             w = m.get("wing", "unknown")
             r = m.get("room", "unknown")
             wings[w] = wings.get(w, 0) + 1
@@ -337,6 +369,7 @@ def tool_list_wings():
     try:
         all_meta = _get_cached_metadata(col)
         for m in all_meta:
+            m = m or {}
             w = m.get("wing", "unknown")
             wings[w] = wings.get(w, 0) + 1
     except Exception as e:
@@ -360,6 +393,7 @@ def tool_list_rooms(wing: str = None):
         where = {"wing": wing} if wing else None
         all_meta = _fetch_all_metadata(col, where=where)
         for m in all_meta:
+            m = m or {}
             r = m.get("room", "unknown")
             rooms[r] = rooms.get(r, 0) + 1
     except Exception as e:
@@ -378,6 +412,7 @@ def tool_get_taxonomy():
     try:
         all_meta = _get_cached_metadata(col)
         for m in all_meta:
+            m = m or {}
             w = m.get("wing", "unknown")
             r = m.get("room", "unknown")
             if w not in taxonomy:
@@ -808,7 +843,7 @@ def tool_update_drawer(drawer_id: str, content: str = None, wing: str = None, ro
 def tool_kg_query(entity: str, as_of: str = None, direction: str = "both"):
     """Query the knowledge graph for an entity's relationships."""
     try:
-        entity = sanitize_name(entity, "entity")
+        entity = sanitize_kg_value(entity, "entity")
     except ValueError as e:
         return {"error": str(e)}
     if direction not in ("outgoing", "incoming", "both"):
@@ -822,9 +857,9 @@ def tool_kg_add(
 ):
     """Add a relationship to the knowledge graph."""
     try:
-        subject = sanitize_name(subject, "subject")
+        subject = sanitize_kg_value(subject, "subject")
         predicate = sanitize_name(predicate, "predicate")
-        object = sanitize_name(object, "object")
+        object = sanitize_kg_value(object, "object")
     except ValueError as e:
         return {"success": False, "error": str(e)}
 
@@ -847,9 +882,9 @@ def tool_kg_add(
 def tool_kg_invalidate(subject: str, predicate: str, object: str, ended: str = None):
     """Mark a fact as no longer true (set end date)."""
     try:
-        subject = sanitize_name(subject, "subject")
+        subject = sanitize_kg_value(subject, "subject")
         predicate = sanitize_name(predicate, "predicate")
-        object = sanitize_name(object, "object")
+        object = sanitize_kg_value(object, "object")
     except ValueError as e:
         return {"success": False, "error": str(e)}
     _wal_log(
@@ -868,7 +903,7 @@ def tool_kg_timeline(entity: str = None):
     """Get chronological timeline of facts, optionally for one entity."""
     if entity is not None:
         try:
-            entity = sanitize_name(entity, "entity")
+            entity = sanitize_kg_value(entity, "entity")
         except ValueError as e:
             return {"error": str(e)}
     results = _kg.timeline(entity)
@@ -883,10 +918,10 @@ def tool_kg_stats():
 # ==================== AGENT DIARY ====================
 
 
-def tool_diary_write(agent_name: str, entry: str, topic: str = "general"):
+def tool_diary_write(agent_name: str, entry: str, topic: str = "general", wing: str = ""):
     """
-    Write a diary entry for this agent. Each agent gets its own wing
-    with a diary room. Entries are timestamped and accumulate over time.
+    Write a diary entry for this agent. Entries are timestamped and
+    accumulate over time in a diary room.
 
     This is the agent's personal journal — observations, thoughts,
     what it worked on, what it noticed, what it thinks matters.
@@ -897,7 +932,10 @@ def tool_diary_write(agent_name: str, entry: str, topic: str = "general"):
     except ValueError as e:
         return {"success": False, "error": str(e)}
 
-    wing = f"wing_{agent_name.lower().replace(' ', '_')}"
+    if wing:
+        wing = sanitize_name(wing)
+    else:
+        wing = f"wing_{agent_name.lower().replace(' ', '_')}"
     room = "diary"
     col = _get_collection(create=True)
     if not col:
@@ -952,24 +990,38 @@ def tool_diary_write(agent_name: str, entry: str, topic: str = "general"):
         return {"success": False, "error": str(e)}
 
 
-def tool_diary_read(agent_name: str, last_n: int = 10):
+def tool_diary_read(agent_name: str, last_n: int = 10, wing: str = ""):
     """
     Read an agent's recent diary entries. Returns the last N entries
     in chronological order — the agent's personal journal.
+
+    When ``wing`` is provided, reads only from that wing. When ``wing``
+    is empty or omitted, returns entries from every wing this agent has
+    written to. Diary writes from hooks land in project-derived wings
+    (``wing_<project>``), so requiring a specific wing on read would
+    silo those entries from agent-initiated reads.
     """
     try:
         agent_name = sanitize_name(agent_name, "agent_name")
+        if wing:
+            wing = sanitize_name(wing)
     except ValueError as e:
         return {"error": str(e)}
     last_n = max(1, min(last_n, 100))
-    wing = f"wing_{agent_name.lower().replace(' ', '_')}"
     col = _get_collection()
     if not col:
         return _no_palace()
 
+    # Build filter: always scope by agent + room=diary. Wing is optional —
+    # when empty, return entries across all wings for this agent (matches
+    # the #1097 empty-string-as-no-filter convention for LLM ergonomics).
+    conditions = [{"room": "diary"}, {"agent": agent_name}]
+    if wing:
+        conditions.insert(0, {"wing": wing})
+
     try:
         results = col.get(
-            where={"$and": [{"wing": wing}, {"room": "diary"}]},
+            where={"$and": conditions},
             include=["documents", "metadatas"],
             limit=10000,
         )
@@ -1462,6 +1514,10 @@ TOOLS = {
                     "type": "string",
                     "description": "Topic tag (optional, default: general)",
                 },
+                "wing": {
+                    "type": "string",
+                    "description": "Target wing for this diary entry (optional). If omitted, uses wing_{agent_name}. Use this to write diary entries to a project wing instead of an agent-specific wing.",
+                },
             },
             "required": ["agent_name", "entry"],
         },
@@ -1480,6 +1536,10 @@ TOOLS = {
                     "type": "integer",
                     "description": "Number of recent entries to read (default: 10)",
                 },
+                "wing": {
+                    "type": "string",
+                    "description": "Wing to read diary entries from (optional). If omitted, reads from wing_{agent_name}.",
+                },
             },
             "required": ["agent_name"],
         },
@@ -1639,7 +1699,21 @@ def handle_request(request):
     }
 
 
+def _restore_stdout():
+    """Restore real stdout for MCP JSON-RPC output (see issue #225)."""
+    global _REAL_STDOUT, _REAL_STDOUT_FD
+    if _REAL_STDOUT_FD is not None:
+        try:
+            os.dup2(_REAL_STDOUT_FD, 1)
+            os.close(_REAL_STDOUT_FD)
+        except OSError:
+            pass
+        _REAL_STDOUT_FD = None
+    sys.stdout = _REAL_STDOUT
+
+
 def main():
+    _restore_stdout()
     logger.info("MemPalace MCP Server starting...")
     while True:
         try:

mempalace/migrate.py

@@ -7,8 +7,10 @@ Reads documents and metadata directly from the palace's SQLite database
 then re-imports everything into a fresh palace using the currently installed
 ChromaDB version.
 
-This fixes the 3.0.0 → 3.1.0 upgrade path where chromadb was downgraded
-from 1.5.x to 0.6.x, breaking the on-disk storage format.
+Since mempalace 3.2.0 (chromadb>=1.5.4), chromadb automatically migrates
+0.4.1+ databases on first open — no manual migration needed for upgrades.
+Use this command only when downgrading chromadb (e.g. rolling back to an
+older mempalace release) or if automatic migration fails.
 
 Usage:
     mempalace migrate                          # migrate default palace
@@ -134,7 +136,7 @@ def confirm_destructive_action(
 
 def migrate(palace_path: str, dry_run: bool = False, confirm: bool = False):
     """Migrate a palace to the currently installed ChromaDB version."""
-    import chromadb
+    from .backends.chroma import ChromaBackend
 
     palace_path = os.path.abspath(os.path.expanduser(palace_path))
     db_path = os.path.join(palace_path, "chroma.sqlite3")
@@ -152,19 +154,19 @@ def migrate(palace_path: str, dry_run: bool = False, confirm: bool = False):
 
     # Detect version
     source_version = detect_chromadb_version(db_path)
+    target_version = ChromaBackend.backend_version()
     print(f"  Source:    ChromaDB {source_version}")
-    print(f"  Target:    ChromaDB {chromadb.__version__}")
+    print(f"  Target:    ChromaDB {target_version}")
 
     # Try reading with current chromadb first
     try:
-        client = chromadb.PersistentClient(path=palace_path)
-        col = client.get_collection("mempalace_drawers")
+        col = ChromaBackend().get_collection(palace_path, "mempalace_drawers")
         count = col.count()
-        print(f"\n  Palace is already readable by chromadb {chromadb.__version__}.")
+        print(f"\n  Palace is already readable by chromadb {target_version}.")
         print(f"  {count} drawers found. No migration needed.")
         return True
     except Exception:
-        print(f"\n  Palace is NOT readable by chromadb {chromadb.__version__}.")
+        print(f"\n  Palace is NOT readable by chromadb {target_version}.")
         print("  Extracting from SQLite directly...")
 
     # Extract all drawers via raw SQL
@@ -208,8 +210,8 @@ def migrate(palace_path: str, dry_run: bool = False, confirm: bool = False):
 
     temp_palace = tempfile.mkdtemp(prefix="mempalace_migrate_")
     print(f"  Creating fresh palace in {temp_palace}...")
-    client = chromadb.PersistentClient(path=temp_palace)
-    col = client.get_or_create_collection("mempalace_drawers", metadata={"hnsw:space": "cosine"})
+    fresh_backend = ChromaBackend()
+    col = fresh_backend.get_or_create_collection(temp_palace, "mempalace_drawers")
 
     # Re-import in batches
     batch_size = 500
@@ -227,7 +229,7 @@ def migrate(palace_path: str, dry_run: bool = False, confirm: bool = False):
     # Verify before swapping
     final_count = col.count()
     del col
-    del client
+    del fresh_backend
 
     # Swap: remove old palace, move new one into place
     print("  Swapping old palace for migrated version...")

mempalace/miner.py

@@ -36,6 +36,7 @@ READABLE_EXTENSIONS = {
     ".jsx",
     ".tsx",
     ".json",
+    ".jsonl",
     ".yaml",
     ".yml",
     ".html",
@@ -51,6 +52,7 @@ READABLE_EXTENSIONS = {
 }
 
 SKIP_FILENAMES = {
+    "entities.json",
     "mempalace.yaml",
     "mempalace.yml",
     "mempal.yaml",
@@ -62,7 +64,14 @@ SKIP_FILENAMES = {
 CHUNK_SIZE = 800  # chars per drawer
 CHUNK_OVERLAP = 100  # overlap between chunks
 MIN_CHUNK_SIZE = 50  # skip tiny chunks
-MAX_FILE_SIZE = 10 * 1024 * 1024  # 10 MB — skip files larger than this
+MAX_FILE_SIZE = 500 * 1024 * 1024  # 500 MB — skip files larger than this.
+# Long Claude Code sessions and large transcript exports routinely exceed
+# 10 MB. The cap exists as a defensive rail against pathological binary
+# files, not as a limit on legitimate text. Per-drawer size is bounded
+# by CHUNK_SIZE, but larger sources still produce proportionally more
+# drawers and therefore more storage, embedding, and processing work —
+# and file reads are not streamed (the whole content is loaded into
+# memory before chunking), so memory use scales with source size too.
 
 
 # =============================================================================
@@ -264,16 +273,32 @@ def load_config(project_dir: str) -> dict:
     """Load mempalace.yaml from project directory (falls back to mempal.yaml)."""
     import yaml
 
-    config_path = Path(project_dir).expanduser().resolve() / "mempalace.yaml"
+    resolved_project_dir = Path(project_dir).expanduser().resolve()
+    config_path = resolved_project_dir / "mempalace.yaml"
     if not config_path.exists():
         # Fallback to legacy name
-        legacy_path = Path(project_dir).expanduser().resolve() / "mempal.yaml"
+        legacy_path = resolved_project_dir / "mempal.yaml"
         if legacy_path.exists():
             config_path = legacy_path
         else:
-            print(f"ERROR: No mempalace.yaml found in {project_dir}")
-            print(f"Run: mempalace init {project_dir}")
-            sys.exit(1)
+            wing_name = resolved_project_dir.name
+            print(
+                f"  No mempalace.yaml found in {resolved_project_dir} "
+                f"— using auto-detected defaults (wing='{wing_name}'). "
+                "Directories with the same basename will share a wing; "
+                "add mempalace.yaml to disambiguate.",
+                file=sys.stderr,
+            )
+            return {
+                "wing": wing_name,
+                "rooms": [
+                    {
+                        "name": "general",
+                        "description": "All project files",
+                        "keywords": ["general"],
+                    }
+                ],
+            }
     with open(config_path) as f:
         return yaml.safe_load(f)
 
@@ -447,6 +472,97 @@ def _load_known_entities_raw() -> dict:
     return dict(_ENTITY_REGISTRY_CACHE["raw"])
 
 
+def add_to_known_entities(entities_by_category: dict) -> str:
+    """Union ``entities_by_category`` into ``~/.mempalace/known_entities.json``.
+
+    Accepts ``{category: [names]}`` shape as produced by ``mempalace init``
+    and merges into the registry the miner reads at mine time. Existing
+    categories are preserved untouched unless also present in the input;
+    for categories present in both, entries are unioned case-insensitively
+    without changing the on-disk ordering of pre-existing names.
+
+    If a category is stored on-disk as ``{name: code}`` (the alternate
+    miner-supported shape, used by dialect-style configs), new names are
+    added as keys with ``None`` values so existing code mappings aren't
+    overwritten. A later compress pass can assign codes.
+
+    The in-process cache is invalidated on write so same-process callers
+    (notably ``cmd_init`` → ``cmd_mine`` in sequence) see the update
+    immediately instead of waiting for a mtime re-check.
+
+    Returns the registry path as a string for logging.
+    """
+    import json as _json
+    from pathlib import Path as _Path
+
+    registry_path = _Path(_ENTITY_REGISTRY_PATH)
+    registry_path.parent.mkdir(parents=True, exist_ok=True)
+
+    existing: dict = {}
+    if registry_path.exists():
+        try:
+            loaded = _json.loads(registry_path.read_text(encoding="utf-8"))
+            if isinstance(loaded, dict):
+                existing = loaded
+        except (_json.JSONDecodeError, OSError):
+            existing = {}
+
+    def _coerce_name(value):
+        if not value:
+            return None
+        name = str(value)
+        return name if name else None
+
+    for category, names in entities_by_category.items():
+        if not isinstance(names, list) or not names:
+            continue
+        current = existing.get(category)
+        if isinstance(current, list):
+            seen_lower = {str(n).lower() for n in current}
+            for n in names:
+                name = _coerce_name(n)
+                if not name:
+                    continue
+                if name.lower() not in seen_lower:
+                    current.append(name)
+                    seen_lower.add(name.lower())
+        elif isinstance(current, dict):
+            seen_lower = {str(name).lower() for name in current}
+            for n in names:
+                name = _coerce_name(n)
+                if not name or name.lower() in seen_lower:
+                    continue
+                current[name] = None
+                seen_lower.add(name.lower())
+        else:
+            # Missing or unrecognized shape — seed as a fresh list, deduped
+            seen: set = set()
+            ordered: list = []
+            for n in names:
+                name = _coerce_name(n)
+                if not name:
+                    continue
+                key = name.lower()
+                if key in seen:
+                    continue
+                seen.add(key)
+                ordered.append(name)
+            existing[category] = ordered
+
+    registry_path.write_text(_json.dumps(existing, indent=2, ensure_ascii=False), encoding="utf-8")
+    try:
+        registry_path.chmod(0o600)
+    except (OSError, NotImplementedError):
+        pass
+
+    # Invalidate in-process cache so later calls in the same run see the write.
+    _ENTITY_REGISTRY_CACHE["mtime"] = None
+    _ENTITY_REGISTRY_CACHE["names"] = frozenset()
+    _ENTITY_REGISTRY_CACHE["raw"] = {}
+
+    return str(registry_path)
+
+
 _HALL_KEYWORDS_CACHE = None
 
 
@@ -497,8 +613,10 @@ def _extract_entities_for_metadata(content: str) -> str:
         if re.search(r"(?<!\w)" + re.escape(name) + r"(?!\w)", content):
             matched.add(name)
 
+    from .palace import _candidate_entity_words
+
     window = content[:_ENTITY_EXTRACT_WINDOW]
-    words = re.findall(r"\b[A-Z][a-z]{2,}\b", window)
+    words = _candidate_entity_words(window)
     freq: dict = {}
     for w in words:
         if w in _ENTITY_STOPLIST:
@@ -586,7 +704,7 @@ def process_file(
     chunks = chunk_text(content, source_file)
 
     if dry_run:
-        print(f"    [DRY RUN] {filepath.name} → room:{room} ({len(chunks)} drawers)")
+        print(f"    [DRY RUN] {filepath.name} -> room:{room} ({len(chunks)} drawers)")
         return len(chunks), room
 
     # Lock this file so concurrent agents don't interleave delete+insert.
@@ -763,7 +881,7 @@ def mine(
         print("  .gitignore: DISABLED")
     if include_ignored:
         print(f"  Include: {', '.join(sorted(normalize_include_paths(include_ignored)))}")
-    print(f"{'─' * 55}\n")
+    print(f"{'-' * 55}\n")
 
     if not dry_run:
         collection = get_collection(palace_path)
@@ -793,7 +911,7 @@ def mine(
             total_drawers += drawers
             room_counts[room] += 1
             if not dry_run:
-                print(f"  ✓ [{i:4}/{len(files)}] {filepath.name[:50]:50} +{drawers}")
+                print(f"  + [{i:4}/{len(files)}] {filepath.name[:50]:50} +{drawers}")
 
     print(f"\n{'=' * 55}")
     print("  Done.")
@@ -821,17 +939,24 @@ def status(palace_path: str):
         print("  Run: mempalace init <dir> then mempalace mine <dir>")
         return
 
-    # Count by wing and room
+    # Count by wing and room — paginate to avoid SQLite "too many SQL
+    # variables" error on large palaces (see #802, #850).
     total = col.count()
-    r = col.get(limit=total, include=["metadatas"]) if total else {"metadatas": []}
-    metas = r["metadatas"]
-
-    wing_rooms = defaultdict(lambda: defaultdict(int))
-    for m in metas:
-        wing_rooms[m.get("wing", "?")][m.get("room", "?")] += 1
+    wing_rooms: dict = defaultdict(lambda: defaultdict(int))
+    batch_size = 5000
+    offset = 0
+    while offset < total:
+        r = col.get(limit=batch_size, offset=offset, include=["metadatas"])
+        batch = r["metadatas"]
+        if not batch:
+            break
+        for m in batch:
+            m = m or {}
+            wing_rooms[m.get("wing", "?")][m.get("room", "?")] += 1
+        offset += len(batch)
 
     print(f"\n{'=' * 55}")
-    print(f"  MemPalace Status — {len(metas)} drawers")
+    print(f"  MemPalace Status — {total} drawers")
     print(f"{'=' * 55}\n")
     for wing, rooms in sorted(wing_rooms.items()):
         print(f"  WING: {wing}")

mempalace/normalize.py

@@ -20,6 +20,12 @@ import re
 from pathlib import Path
 from typing import Optional
 
+# Provenance footer appended to Slack transcript output so downstream consumers
+# know the speaker roles are positionally assigned, not verified.
+_SLACK_PROVENANCE_FOOTER = (
+    "\n[source: slack-export | multi-party chat — speaker roles are positional, not verified]"
+)
+
 
 # ─── Noise stripping ─────────────────────────────────────────────────────
 # Claude Code and other tools inject system tags, hook output, and UI chrome
@@ -367,8 +373,13 @@ def _try_chatgpt_json(data) -> Optional[str]:
 def _try_slack_json(data) -> Optional[str]:
     """
     Slack channel export: [{"type": "message", "user": "...", "text": "..."}]
-    Optimized for 2-person DMs. In channels with 3+ people, alternating
-    speakers are labeled user/assistant to preserve the exchange structure.
+
+    Slack exports are multi-party chats where no speaker is inherently the
+    "user" or "assistant".  To preserve exchange-pair chunking (which relies
+    on ``>`` markers from the ``user`` role), we still alternate roles, but
+    prefix each message with the speaker ID so downstream consumers can
+    distinguish the original author.  A provenance header marks the
+    transcript as a Slack import.
     """
     if not isinstance(data, list):
         return None
@@ -378,7 +389,10 @@ def _try_slack_json(data) -> Optional[str]:
     for item in data:
         if not isinstance(item, dict) or item.get("type") != "message":
             continue
-        user_id = item.get("user", item.get("username", ""))
+        raw_user_id = item.get("user", item.get("username", ""))
+        # Sanitize speaker ID: strip brackets, newlines, and control chars
+        # to prevent chunk-boundary injection via crafted exports
+        user_id = re.sub(r"[\[\]\n\r\x00-\x1f]", "_", raw_user_id).strip()
         text = item.get("text", "").strip()
         if not text or not user_id:
             continue
@@ -391,9 +405,10 @@ def _try_slack_json(data) -> Optional[str]:
             else:
                 seen_users[user_id] = "user"
         last_role = seen_users[user_id]
-        messages.append((seen_users[user_id], text))
+        # Prefix with speaker ID so the original author is preserved
+        messages.append((seen_users[user_id], f"[{user_id}] {text}"))
     if len(messages) >= 2:
-        return _messages_to_transcript(messages)
+        return _messages_to_transcript(messages) + _SLACK_PROVENANCE_FOOTER
     return None
 
 

mempalace/palace.py

@@ -7,6 +7,7 @@ Consolidates collection access patterns used by both miners and the MCP server.
 import contextlib
 import hashlib
 import os
+import re
 
 from .backends.chroma import ChromaBackend
 
@@ -130,6 +131,35 @@ _ENTITY_STOPLIST = frozenset(
 )
 
 
+_CANDIDATE_RX_CACHE = None
+
+
+def _candidate_entity_words(text: str) -> list:
+    """Find entity candidate words using i18n-aware patterns.
+
+    Uses the same candidate_patterns as entity_detector (loaded from locale
+    JSON files via get_entity_patterns), so non-Latin names (Cyrillic,
+    accented Latin, etc.) are detected alongside ASCII names.
+    """
+    global _CANDIDATE_RX_CACHE
+    if _CANDIDATE_RX_CACHE is None:
+        from .config import MempalaceConfig
+        from .i18n import get_entity_patterns
+
+        patterns = get_entity_patterns(MempalaceConfig().entity_languages)
+        rxs = []
+        for pat in patterns["candidate_patterns"]:
+            try:
+                rxs.append(re.compile(pat))
+            except re.error:
+                continue
+        _CANDIDATE_RX_CACHE = rxs
+    words = []
+    for rx in _CANDIDATE_RX_CACHE:
+        words.extend(rx.findall(text))
+    return words
+
+
 def build_closet_lines(source_file, drawer_ids, content, wing, room):
     """Build compact closet pointer lines from drawer content.
 
@@ -144,9 +174,9 @@ def build_closet_lines(source_file, drawer_ids, content, wing, room):
     drawer_ref = ",".join(drawer_ids[:3])
     window = content[:CLOSET_EXTRACT_WINDOW]
 
-    # Extract proper nouns (capitalized words, 2+ occurrences). Filter out
-    # common sentence-starters that aren't real entities.
-    words = re.findall(r"\b[A-Z][a-z]{2,}\b", window)
+    # Extract proper nouns (2+ occurrences). Uses i18n-aware patterns so
+    # non-Latin names (Cyrillic, accented Latin, etc.) are also detected.
+    words = _candidate_entity_words(window)
     word_freq = {}
     for w in words:
         if w in _ENTITY_STOPLIST:

mempalace/palace_graph.py

@@ -18,6 +18,8 @@ No external graph DB needed — built from ChromaDB metadata.
 import hashlib
 import json
 import os
+import threading
+import time
 from collections import Counter, defaultdict
 from datetime import datetime, timezone
 
@@ -25,6 +27,23 @@ from .config import MempalaceConfig
 from .palace import get_collection as _get_palace_collection
 from .palace import mine_lock
 
+# Module-level graph cache with TTL and write-invalidation.
+# Warm cache serves build_graph() in O(1); invalidate_graph_cache() clears on writes.
+_graph_cache_lock = threading.Lock()
+_graph_cache_nodes = None
+_graph_cache_edges = None
+_graph_cache_time = 0.0
+_GRAPH_CACHE_TTL = 60.0  # seconds — graph changes less often than metadata
+
+
+def invalidate_graph_cache():
+    """Clear the graph cache. Called from mcp_server.py on writes."""
+    global _graph_cache_nodes, _graph_cache_edges, _graph_cache_time
+    with _graph_cache_lock:
+        _graph_cache_nodes = None
+        _graph_cache_edges = None
+        _graph_cache_time = 0.0
+
 
 def _get_collection(config=None):
     config = config or MempalaceConfig()
@@ -42,10 +61,25 @@ def build_graph(col=None, config=None):
     """
     Build the palace graph from ChromaDB metadata.
 
+    Returns cached result if fresh (within TTL). Cache is invalidated
+    on writes via invalidate_graph_cache(). Thread-safe via _graph_cache_lock.
+
+    Note: warm cache ignores ``col`` and ``config`` arguments — this is
+    intentional for the MCP server's single-palace use case. Callers
+    switching collections should call ``invalidate_graph_cache()`` first.
+
     Returns:
         nodes: dict of {room: {wings: set, halls: set, count: int}}
         edges: list of {room, wing_a, wing_b, hall} — one per tunnel crossing
     """
+    global _graph_cache_nodes, _graph_cache_edges, _graph_cache_time
+    now = time.time()
+    # NOTE: warm cache ignores col/config args — intentional for the MCP server's
+    # single-palace use case. Callers switching collections must invalidate first.
+    with _graph_cache_lock:
+        if _graph_cache_nodes is not None and (now - _graph_cache_time) < _GRAPH_CACHE_TTL:
+            return _graph_cache_nodes, _graph_cache_edges
+
     if col is None:
         col = _get_collection(config)
     if not col:
@@ -101,6 +135,14 @@ def build_graph(col=None, config=None):
             "dates": sorted(data["dates"])[-5:] if data["dates"] else [],
         }
 
+    # Only cache non-empty graphs so new data is picked up immediately
+    # when the palace is first populated.
+    if nodes:
+        with _graph_cache_lock:
+            _graph_cache_nodes = nodes
+            _graph_cache_edges = edges
+            _graph_cache_time = time.time()
+
     return nodes, edges
 
 

mempalace/project_scanner.py

@@ -0,0 +1,716 @@
+"""
+project_scanner.py — Detect projects and people from real signal.
+
+For a codebase with build manifests or git history, this beats regex-based
+entity detection by a wide margin: the project's own name is already written
+down in package.json / pyproject.toml / Cargo.toml / go.mod, and the people
+who worked on it are in `git log`.
+
+This module is used as the primary signal in `mempalace init`. The regex
+detector in entity_detector.py stays as a fallback for prose-only folders
+(notes, research, writing).
+
+Public:
+    scan(root) -> (projects, people)
+    to_detected_dict(projects, people) -> {people: [...], projects: [...], uncertain: []}
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+try:
+    import tomllib  # Python 3.11+
+except ImportError:  # pragma: no cover
+    try:
+        import tomli as tomllib  # Python 3.9/3.10 backport
+    except ImportError:
+        tomllib = None  # type: ignore
+
+
+SKIP_DIRS = {
+    ".git",
+    "node_modules",
+    "__pycache__",
+    ".venv",
+    "venv",
+    "env",
+    "dist",
+    "build",
+    ".next",
+    "coverage",
+    ".terraform",
+    "vendor",
+    "target",
+    ".mempalace",
+    ".cache",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".ruff_cache",
+}
+
+MAX_DEPTH = 6
+MAX_COMMITS_PER_REPO = 1000
+GIT_TIMEOUT = 10
+
+
+# ==================== DATACLASSES ====================
+
+
+@dataclass
+class ProjectInfo:
+    name: str
+    repo_root: Path
+    manifest: Optional[str] = None
+    has_git: bool = False
+    total_commits: int = 0
+    user_commits: int = 0
+    is_mine: bool = False
+
+    @property
+    def confidence(self) -> float:
+        if self.is_mine:
+            return 0.99
+        if self.has_git and self.total_commits > 0:
+            return 0.7
+        return 0.85  # manifest-only, no git
+
+    def to_signal(self) -> str:
+        parts: list[str] = []
+        if self.manifest:
+            parts.append(self.manifest)
+        if self.has_git:
+            if self.is_mine and self.user_commits:
+                parts.append(f"{self.user_commits} of your commits")
+            elif self.user_commits:
+                parts.append(f"{self.user_commits}/{self.total_commits} yours")
+            else:
+                parts.append(f"{self.total_commits} commits (none by you)")
+        return ", ".join(parts) or "repo"
+
+
+@dataclass
+class PersonInfo:
+    name: str
+    total_commits: int = 0
+    emails: set[str] = field(default_factory=set)
+    repos: set[str] = field(default_factory=set)
+
+    @property
+    def confidence(self) -> float:
+        if self.total_commits >= 100 or len(self.repos) >= 3:
+            return 0.99
+        if self.total_commits >= 20:
+            return 0.85
+        return 0.65
+
+    def to_signal(self) -> str:
+        r = len(self.repos)
+        return f"{self.total_commits} commit{'s' if self.total_commits != 1 else ''} across {r} repo{'s' if r != 1 else ''}"
+
+
+# ==================== MANIFEST PARSING ====================
+
+
+def _parse_package_json(path: Path) -> Optional[str]:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8", errors="replace"))
+    except (json.JSONDecodeError, OSError):
+        return None
+    name = data.get("name")
+    return name if isinstance(name, str) and name else None
+
+
+def _parse_toml(path: Path) -> dict:
+    if tomllib is None:
+        return {}
+    try:
+        with open(path, "rb") as f:
+            return tomllib.load(f)
+    except (OSError, tomllib.TOMLDecodeError):
+        return {}
+
+
+def _parse_pyproject(path: Path) -> Optional[str]:
+    data = _parse_toml(path)
+    name = data.get("project", {}).get("name")
+    if isinstance(name, str) and name:
+        return name
+    name = data.get("tool", {}).get("poetry", {}).get("name")
+    return name if isinstance(name, str) and name else None
+
+
+def _parse_cargo(path: Path) -> Optional[str]:
+    data = _parse_toml(path)
+    name = data.get("package", {}).get("name")
+    return name if isinstance(name, str) and name else None
+
+
+def _parse_gomod(path: Path) -> Optional[str]:
+    try:
+        for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+            line = line.strip()
+            if line.startswith("module "):
+                mod = line.split(None, 1)[1].strip()
+                return mod.split("/")[-1] or None
+    except OSError:
+        return None
+    return None
+
+
+MANIFEST_PRIORITY = {
+    "pyproject.toml": 0,
+    "package.json": 1,
+    "Cargo.toml": 2,
+    "go.mod": 3,
+}
+# Sentinel so unknown manifests always sort after the known manifest types above.
+UNKNOWN_MANIFEST_PRIORITY = max(MANIFEST_PRIORITY.values()) + 1
+MANIFEST_PARSERS = {
+    "package.json": _parse_package_json,
+    "pyproject.toml": _parse_pyproject,
+    "Cargo.toml": _parse_cargo,
+    "go.mod": _parse_gomod,
+}
+
+
+# ==================== GIT HELPERS ====================
+
+
+def _run_git(cwd: Path, *args: str, timeout: int = GIT_TIMEOUT) -> str:
+    try:
+        r = subprocess.run(
+            ["git", "-C", str(cwd), *args],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+        return r.stdout if r.returncode == 0 else ""
+    except (OSError, subprocess.SubprocessError):
+        return ""
+
+
+def _git_user_identity(repo: Path) -> tuple[str, str]:
+    """Return (name, email) for this repo, falling back to global config."""
+    name = _run_git(repo, "config", "user.name", timeout=2).strip()
+    email = _run_git(repo, "config", "user.email", timeout=2).strip()
+    return name, email
+
+
+def _global_git_identity() -> tuple[str, str]:
+    try:
+        n = subprocess.run(
+            ["git", "config", "--global", "user.name"],
+            capture_output=True,
+            text=True,
+            timeout=2,
+            check=False,
+        ).stdout.strip()
+        e = subprocess.run(
+            ["git", "config", "--global", "user.email"],
+            capture_output=True,
+            text=True,
+            timeout=2,
+            check=False,
+        ).stdout.strip()
+        return n, e
+    except (OSError, subprocess.SubprocessError):
+        return "", ""
+
+
+def _git_authors(repo: Path) -> list[tuple[str, str]]:
+    out = _run_git(
+        repo,
+        "log",
+        f"--max-count={MAX_COMMITS_PER_REPO}",
+        "--format=%aN|%aE",
+    )
+    result = []
+    for line in out.splitlines():
+        if "|" in line:
+            name, email = line.split("|", 1)
+            result.append((name.strip(), email.strip()))
+    return result
+
+
+# ==================== BOT / NAME FILTERING ====================
+
+
+_BOT_NAME_PATTERNS = [
+    r"\[bot\]",
+    r"^dependabot",
+    r"^renovate",
+    r"^github-actions",
+    r"^actions-user",
+    r"-bot$",
+    r"\bbot$",  # catches "PR Bot", "Release Bot", etc. Not "robot" (no \b)
+    r"^bot-",
+    r"^snyk",
+    r"^greenkeeper",
+    r"^semantic-release",
+    r"^allcontributors",
+    r"-autoroll$",
+    r"^auto-format",
+    r"^pre-commit-ci",
+]
+_BOT_EMAIL_PATTERNS = [
+    # `@users.noreply.github.com` is GitHub's privacy-protected human email —
+    # do NOT filter it. Real bots identify themselves via the display name
+    # (usually containing "[bot]"), which is caught by _BOT_NAME_PATTERNS.
+    r"bot@",
+    r"-bot@",
+    r"\[bot\]@",
+]
+
+_BOT_RE_NAMES = [re.compile(p) for p in _BOT_NAME_PATTERNS]
+_BOT_RE_EMAILS = [re.compile(p) for p in _BOT_EMAIL_PATTERNS]
+
+
+def _is_bot(name: str, email: str) -> bool:
+    ln, le = name.lower(), email.lower()
+    return any(rx.search(ln) for rx in _BOT_RE_NAMES) or any(rx.search(le) for rx in _BOT_RE_EMAILS)
+
+
+def _looks_like_real_name(name: str) -> bool:
+    """Heuristic: a human's name has a space and at least two title-cased parts.
+
+    Filters out handles (lowercase, digits, one-token usernames).
+    """
+    if not name or " " not in name:
+        return False
+    parts = name.split()
+    if len(parts) < 2:
+        return False
+    # First and last parts must start with an uppercase letter
+    return parts[0][:1].isupper() and parts[-1][:1].isupper()
+
+
+# ==================== DIRECTORY WALK ====================
+
+
+def _walk(root: Path, max_depth: int = MAX_DEPTH):
+    for dirpath, dirs, files in os.walk(root):
+        dirs[:] = [d for d in dirs if d not in SKIP_DIRS and not d.startswith(".")]
+        rel = Path(dirpath).relative_to(root)
+        depth = 0 if rel == Path(".") else len(rel.parts)
+        if depth > max_depth:
+            dirs.clear()
+            continue
+        yield Path(dirpath), dirs, files
+
+
+def _has_git_marker(path: Path) -> bool:
+    git_path = path / ".git"
+    return git_path.is_dir() or git_path.is_file()
+
+
+def _manifest_sort_key(entry: tuple[str, str, Path], repo_root: Path) -> tuple[int, int, str]:
+    """Sort manifests by shallowest path first, then known manifest priority,
+    then lexicographic path for deterministic tie-breaking.
+    """
+    manifest_file, _project_name, manifest_dir = entry
+    try:
+        rel = manifest_dir.relative_to(repo_root)
+        depth = len(rel.parts)
+        rel_str = rel.as_posix()
+    except ValueError:
+        depth = MAX_DEPTH + 1
+        rel_str = manifest_dir.as_posix()
+    return (depth, MANIFEST_PRIORITY.get(manifest_file, UNKNOWN_MANIFEST_PRIORITY), rel_str)
+
+
+def find_git_repos(root: Path, max_depth: int = MAX_DEPTH) -> list[Path]:
+    """Return git repo roots under `root` (including root itself if it's a repo)."""
+    root = root.resolve()
+    repos: list[Path] = []
+    if _has_git_marker(root):
+        # Root is a repo — still walk for nested repos (submodules, etc.)
+        repos.append(root)
+    for dirpath, dirs, _ in _walk(root, max_depth):
+        if dirpath == root:
+            continue
+        if _has_git_marker(dirpath):
+            repos.append(dirpath)
+            dirs.clear()  # don't descend into this repo's contents from here
+    return repos
+
+
+def _collect_manifest_names(repo_root: Path) -> list[tuple[str, str, Path]]:
+    """Return (manifest_filename, project_name, dirpath) within a repo.
+
+    Does not descend into nested git repos.
+    """
+    found: list[tuple[str, str, Path]] = []
+    for dirpath, dirs, files in _walk(repo_root):
+        if dirpath != repo_root and _has_git_marker(dirpath):
+            dirs.clear()
+            continue
+        for fname in files:
+            parser = MANIFEST_PARSERS.get(fname)
+            if not parser:
+                continue
+            name = parser(dirpath / fname)
+            if name:
+                found.append((fname, name, dirpath))
+    return sorted(found, key=lambda entry: _manifest_sort_key(entry, repo_root))
+
+
+# ==================== MAIN SCAN ====================
+
+
+class _UnionFind:
+    """Minimal union-find for (name, email) identity resolution."""
+
+    def __init__(self) -> None:
+        self.parent: dict = {}
+
+    def find(self, x):
+        if x not in self.parent:
+            self.parent[x] = x
+            return x
+        root = x
+        while self.parent[root] != root:
+            root = self.parent[root]
+        while self.parent[x] != root:
+            self.parent[x], x = root, self.parent[x]
+        return root
+
+    def union(self, a, b) -> None:
+        ra, rb = self.find(a), self.find(b)
+        if ra != rb:
+            self.parent[ra] = rb
+
+
+def _dedupe_people(
+    all_commits: list[tuple[str, str, str]],
+) -> dict[str, PersonInfo]:
+    """Group commits by identity. Two commits are the same person if they
+    share a name OR an email. Display name = most frequent non-bot variant.
+
+    ``all_commits`` is a list of (name, email, repo_str) triples from every repo.
+    """
+    uf = _UnionFind()
+    for name, email, _repo in all_commits:
+        uf.union(("name", name), ("email", email) if email else ("name", name))
+
+    # Aggregate by component root
+    component_commits: dict = {}
+    for name, email, repo in all_commits:
+        key = uf.find(("name", name))
+        entry = component_commits.setdefault(
+            key, {"name_counts": {}, "emails": set(), "repos": set(), "total": 0}
+        )
+        entry["name_counts"][name] = entry["name_counts"].get(name, 0) + 1
+        if email:
+            entry["emails"].add(email)
+        entry["repos"].add(repo)
+        entry["total"] += 1
+
+    # Pick display name per component: the most-frequent variant that looks
+    # like a real name; fall back to most-frequent overall.
+    people: dict[str, PersonInfo] = {}
+    for _key, entry in component_commits.items():
+        candidates = sorted(entry["name_counts"].items(), key=lambda x: -x[1])
+        display = next(
+            (n for n, _ in candidates if _looks_like_real_name(n)),
+            candidates[0][0],
+        )
+        if not _looks_like_real_name(display):
+            continue  # Skip handles and single-token names
+        # If we already have this display (rare — distinct components with the
+        # same chosen display), merge into the existing entry.
+        existing = people.get(display)
+        if existing:
+            existing.total_commits += entry["total"]
+            existing.emails.update(entry["emails"])
+            existing.repos.update(entry["repos"])
+        else:
+            people[display] = PersonInfo(
+                name=display,
+                total_commits=entry["total"],
+                emails=set(entry["emails"]),
+                repos=set(entry["repos"]),
+            )
+    return people
+
+
+def scan(root: str | os.PathLike) -> tuple[list[ProjectInfo], list[PersonInfo]]:
+    """Scan `root` for projects and people. Returns (projects, people) sorted."""
+    root_path = Path(root).expanduser().resolve()
+    if not root_path.is_dir():
+        return [], []
+
+    repos = find_git_repos(root_path)
+
+    # Identify current user from first repo's git config, fall back to global
+    me_name, me_email = "", ""
+    if repos:
+        me_name, me_email = _git_user_identity(repos[0])
+    if not me_name and not me_email:
+        me_name, me_email = _global_git_identity()
+
+    projects: dict[str, ProjectInfo] = {}
+    all_commits: list[tuple[str, str, str]] = []
+
+    for repo in repos:
+        manifests = _collect_manifest_names(repo)
+        if manifests:
+            manifest_file, proj_name, _ = manifests[0]
+        else:
+            manifest_file, proj_name = None, repo.name
+
+        authors = _git_authors(repo)
+        non_bot_authors = [(name, email) for name, email in authors if not _is_bot(name, email)]
+        total_commits = len(non_bot_authors)
+        user_commits = 0
+        author_counts: dict[str, int] = {}
+        for name, email in non_bot_authors:
+            author_counts[name] = author_counts.get(name, 0) + 1
+            all_commits.append((name, email, str(repo)))
+            if (me_name and name == me_name) or (me_email and email == me_email):
+                user_commits += 1
+
+        is_mine = False
+        if user_commits > 0:
+            sorted_authors = sorted(author_counts.items(), key=lambda x: -x[1])
+            top5 = {n for n, _ in sorted_authors[:5]}
+            if me_name and me_name in top5:
+                is_mine = True
+            elif total_commits and user_commits / total_commits >= 0.10:
+                is_mine = True
+            elif user_commits >= 20:
+                is_mine = True
+
+        proj = ProjectInfo(
+            name=proj_name,
+            repo_root=repo,
+            manifest=manifest_file,
+            has_git=True,
+            total_commits=total_commits,
+            user_commits=user_commits,
+            is_mine=is_mine,
+        )
+        existing = projects.get(proj_name)
+        if existing is None or proj.user_commits > existing.user_commits:
+            projects[proj_name] = proj
+
+    people = _dedupe_people(all_commits)
+
+    # Handle case: root has manifests but no git repo anywhere
+    if not repos:
+        manifests = _collect_manifest_names(root_path)
+        for manifest_file, proj_name, _dirpath in manifests:
+            if proj_name in projects:
+                continue
+            projects[proj_name] = ProjectInfo(
+                name=proj_name,
+                repo_root=root_path,
+                manifest=manifest_file,
+                has_git=False,
+            )
+
+    project_list = sorted(
+        projects.values(),
+        key=lambda p: (not p.is_mine, -p.user_commits, -p.total_commits, p.name),
+    )
+    people_list = sorted(people.values(), key=lambda p: -p.total_commits)
+
+    return project_list, people_list
+
+
+# ==================== ADAPTER ====================
+
+
+def to_detected_dict(
+    projects: list[ProjectInfo],
+    people: list[PersonInfo],
+    project_cap: int = 15,
+    people_cap: int = 15,
+) -> dict:
+    """Convert scan results into the dict shape produced by entity_detector.detect_entities."""
+    proj_entries = [
+        {
+            "name": p.name,
+            "type": "project",
+            "confidence": round(p.confidence, 2),
+            "frequency": p.user_commits or p.total_commits,
+            "signals": [p.to_signal()],
+        }
+        for p in projects[:project_cap]
+    ]
+    people_entries = [
+        {
+            "name": p.name,
+            "type": "person",
+            "confidence": round(p.confidence, 2),
+            "frequency": p.total_commits,
+            "signals": [p.to_signal()],
+        }
+        for p in people[:people_cap]
+    ]
+    return {
+        "people": people_entries,
+        "projects": proj_entries,
+        "uncertain": [],
+    }
+
+
+# ==================== MERGE WITH REGEX DETECTOR ====================
+
+
+def _merge_detected(primary: dict, secondary: dict, drop_secondary_uncertain: bool = False) -> dict:
+    """Merge two detected dicts. Primary entries win on name conflict.
+
+    Dedup is case-insensitive so "mempalace" (manifest name) absorbs "MemPalace"
+    (docs/prose reference) instead of surfacing both.
+
+    If ``drop_secondary_uncertain`` is True, the secondary's uncertain bucket is
+    dropped entirely — useful when the primary signal is strong (real repo
+    found) and we'd rather not ask the user to adjudicate prose-regex noise.
+    """
+    seen = {e["name"].lower() for cat in primary.values() for e in cat}
+    merged = {k: list(v) for k, v in primary.items()}
+    for cat_key in ("people", "projects", "uncertain"):
+        if cat_key == "uncertain" and drop_secondary_uncertain:
+            continue
+        for e in secondary.get(cat_key, []):
+            if e["name"].lower() in seen:
+                continue
+            merged.setdefault(cat_key, []).append(e)
+            seen.add(e["name"].lower())
+    return merged
+
+
+def discover_entities(
+    project_dir: str | os.PathLike,
+    languages: tuple = ("en",),
+    prose_file_cap: int = 10,
+    project_cap: int = 15,
+    people_cap: int = 15,
+    llm_provider: object = None,
+    show_progress: bool = True,
+) -> dict:
+    """Top-level entity discovery: real signals first, prose detection second.
+
+    Returns the same dict shape as ``entity_detector.detect_entities`` so it
+    plugs into ``confirm_entities`` unchanged.
+
+    Order of signal preference:
+      1. Package manifests (package.json, pyproject.toml, Cargo.toml, go.mod)
+         → canonical project names
+      2. Git commit authors → real people with real commit counts
+      3. Claude Code conversation dirs (~/.claude/projects/) → per-session
+         project names (pulled from each session's ``cwd`` metadata)
+      4. Regex entity detection on prose files → supplementary names only
+         mentioned in docs/notes (not code)
+      5. Optional LLM refinement pass — reclassifies ambiguous candidates
+         using the caller-supplied provider
+
+    Passing ``llm_provider`` enables phase-2 refinement. The caller is
+    responsible for constructing the provider (``llm_client.get_provider``)
+    and confirming availability. Refinement is blocking-interactive:
+    progress prints to stderr; Ctrl-C returns partial results.
+    """
+    projects, people = scan(project_dir)
+
+    # If the target is a Claude Code conversations root, extract per-project
+    # entries from there too. Same ProjectInfo shape, so dedup logic works.
+    from mempalace.convo_scanner import is_claude_projects_root, scan_claude_projects
+
+    root_path = Path(project_dir).expanduser().resolve()
+    if is_claude_projects_root(root_path):
+        convo_projects = scan_claude_projects(root_path)
+        # Dedup by name against the git-manifest list, preferring entries
+        # with more user_commits as signal strength. Keyed case-insensitively
+        # so a `pyproject.toml` name like `mempalace` and a Claude Code
+        # `cwd` variant like `MemPalace` collapse into one entry — matches
+        # the case-insensitive dedup used in `_merge_detected` and
+        # `miner.add_to_known_entities`.
+        by_name: dict[str, ProjectInfo] = {p.name.lower(): p for p in projects}
+        for cp in convo_projects:
+            key = cp.name.lower()
+            existing = by_name.get(key)
+            if existing is None or cp.user_commits > existing.user_commits:
+                by_name[key] = cp
+        projects = sorted(
+            by_name.values(),
+            key=lambda p: (not p.is_mine, -p.user_commits, -p.total_commits, p.name),
+        )
+
+    real_signal = to_detected_dict(projects, people, project_cap=project_cap, people_cap=people_cap)
+
+    # Secondary pass: prose-only extraction catches names mentioned in docs
+    # that never made a commit (e.g. a stakeholder or family member in notes).
+    from mempalace.entity_detector import detect_entities, scan_for_detection
+
+    prose_files = scan_for_detection(str(project_dir), max_files=prose_file_cap)
+    prose_detected = (
+        detect_entities(prose_files, languages=languages)
+        if prose_files
+        else {"people": [], "projects": [], "uncertain": []}
+    )
+
+    # Without LLM refinement, suppress regex "uncertain" noise when real
+    # manifest/git signal exists. With LLM refinement enabled, keep those
+    # candidates so the model can promote real entities or drop common words.
+    has_real_signal = bool(projects) or bool(people)
+    merged = _merge_detected(
+        real_signal,
+        prose_detected,
+        drop_secondary_uncertain=has_real_signal and llm_provider is None,
+    )
+
+    # Optional phase 2: LLM refinement.
+    if llm_provider is not None:
+        from mempalace.llm_refine import collect_corpus_text, refine_entities
+
+        corpus = collect_corpus_text(str(project_dir))
+        result = refine_entities(
+            merged,
+            corpus,
+            llm_provider,
+            show_progress=show_progress,
+            allow_project_promotions=not has_real_signal,
+        )
+        if show_progress:
+            status_bits = []
+            if result.cancelled:
+                status_bits.append("cancelled")
+            if result.reclassified:
+                status_bits.append(f"reclassified {result.reclassified}")
+            if result.dropped:
+                status_bits.append(f"dropped {result.dropped}")
+            if result.errors:
+                status_bits.append(f"{len(result.errors)} batch error(s)")
+            if status_bits:
+                import sys as _sys
+
+                print(f"  LLM refine: {', '.join(status_bits)}", file=_sys.stderr)
+        merged = result.merged
+
+    return merged
+
+
+# ==================== CLI ====================
+
+
+if __name__ == "__main__":
+    import sys
+
+    target = sys.argv[1] if len(sys.argv) > 1 else "."
+    projs, ppl = scan(target)
+    print(f"=== PROJECTS ({len(projs)}) ===")
+    for p in projs[:30]:
+        mark = "★" if p.is_mine else " "
+        print(f"  {mark} {p.name:35} conf={p.confidence:.2f}  {p.to_signal()}")
+    print()
+    print(f"=== PEOPLE ({len(ppl)}) ===")
+    for p in ppl[:30]:
+        print(f"    {p.name:30} conf={p.confidence:.2f}  {p.to_signal()}")

mempalace/repair.py

@@ -32,7 +32,7 @@ import os
 import shutil
 import time
 
-import chromadb
+from .backends.chroma import ChromaBackend
 
 
 COLLECTION_NAME = "mempalace_drawers"
@@ -90,8 +90,7 @@ def scan_palace(palace_path=None, only_wing=None):
     print(f"\n  Palace: {palace_path}")
     print("  Loading...")
 
-    client = chromadb.PersistentClient(path=palace_path)
-    col = client.get_collection(COLLECTION_NAME)
+    col = ChromaBackend().get_collection(palace_path, COLLECTION_NAME)
 
     where = {"wing": only_wing} if only_wing else None
     total = col.count()
@@ -174,8 +173,7 @@ def prune_corrupt(palace_path=None, confirm=False):
         print("  Re-run with --confirm to actually delete.")
         return
 
-    client = chromadb.PersistentClient(path=palace_path)
-    col = client.get_collection(COLLECTION_NAME)
+    col = ChromaBackend().get_collection(palace_path, COLLECTION_NAME)
     before = col.count()
     print(f"  Collection size before: {before:,}")
 
@@ -222,9 +220,9 @@ def rebuild_index(palace_path=None):
     print(f"{'=' * 55}\n")
     print(f"  Palace: {palace_path}")
 
-    client = chromadb.PersistentClient(path=palace_path)
+    backend = ChromaBackend()
     try:
-        col = client.get_collection(COLLECTION_NAME)
+        col = backend.get_collection(palace_path, COLLECTION_NAME)
         total = col.count()
     except Exception as e:
         print(f"  Error reading palace: {e}")
@@ -264,8 +262,8 @@ def rebuild_index(palace_path=None):
 
     # Rebuild with correct HNSW settings
     print("  Rebuilding collection with hnsw:space=cosine...")
-    client.delete_collection(COLLECTION_NAME)
-    new_col = client.create_collection(COLLECTION_NAME, metadata={"hnsw:space": "cosine"})
+    backend.delete_collection(palace_path, COLLECTION_NAME)
+    new_col = backend.create_collection(palace_path, COLLECTION_NAME)
 
     filed = 0
     for i in range(0, len(all_ids), batch_size):

mempalace/searcher.py

@@ -30,6 +30,21 @@ class SearchError(Exception):
 _TOKEN_RE = re.compile(r"\w{2,}", re.UNICODE)
 
 
+def _first_or_empty(results, key: str) -> list:
+    """Return the first inner list of a query result field, or [].
+
+    Accepts both the typed :class:`QueryResult` (attribute access) and the
+    pre-typed chroma dict shape; this polymorphism is retained so test mocks
+    still work and callers mid-migration do not crash. Preserves the empty-
+    collection semantics from issue #195: when no queries returned hits, the
+    outer list may be empty and indexing ``[0]`` would raise.
+    """
+    outer = getattr(results, key, None) if not isinstance(results, dict) else results.get(key)
+    if not outer:
+        return []
+    return outer[0] or []
+
+
 def _tokenize(text: str) -> list:
     """Lowercase + strip to alphanumeric tokens of length ≥ 2."""
     return _TOKEN_RE.findall(text.lower())
@@ -195,7 +210,7 @@ def _expand_with_neighbors(drawers_col, matched_doc: str, matched_meta: dict, ra
         return {"text": matched_doc, "drawer_index": chunk_idx, "total_drawers": None}
 
     indexed_docs = []
-    for doc, meta in zip(neighbors.get("documents") or [], neighbors.get("metadatas") or []):
+    for doc, meta in zip(neighbors.documents, neighbors.metadatas):
         ci = meta.get("chunk_index")
         if isinstance(ci, int):
             indexed_docs.append((ci, doc))
@@ -210,8 +225,7 @@ def _expand_with_neighbors(drawers_col, matched_doc: str, matched_meta: dict, ra
     total_drawers = None
     try:
         all_meta = drawers_col.get(where={"source_file": src}, include=["metadatas"])
-        ids = all_meta.get("ids") or []
-        total_drawers = len(ids) if ids else None
+        total_drawers = len(all_meta.ids) if all_meta.ids else None
     except Exception:
         pass
 
@@ -251,9 +265,9 @@ def search(query: str, palace_path: str, wing: str = None, room: str = None, n_r
         print(f"\n  Search error: {e}")
         raise SearchError(f"Search error: {e}") from e
 
-    docs = results["documents"][0]
-    metas = results["metadatas"][0]
-    dists = results["distances"][0]
+    docs = _first_or_empty(results, "documents")
+    metas = _first_or_empty(results, "metadatas")
+    dists = _first_or_empty(results, "distances")
 
     if not docs:
         print(f'\n  No results found for: "{query}"')
@@ -269,6 +283,7 @@ def search(query: str, palace_path: str, wing: str = None, room: str = None, n_r
 
     for i, (doc, meta, dist) in enumerate(zip(docs, metas, dists), 1):
         similarity = round(max(0.0, 1 - dist), 3)
+        meta = meta or {}
         source = Path(meta.get("source_file", "?")).name
         wing_name = meta.get("wing", "?")
         room_name = meta.get("room", "?")
@@ -353,11 +368,12 @@ def search_memories(
         closet_results = closets_col.query(**ckwargs)
         for rank, (cdoc, cmeta, cdist) in enumerate(
             zip(
-                closet_results["documents"][0],
-                closet_results["metadatas"][0],
-                closet_results["distances"][0],
+                _first_or_empty(closet_results, "documents"),
+                _first_or_empty(closet_results, "metadatas"),
+                _first_or_empty(closet_results, "distances"),
             )
         ):
+            cmeta = cmeta or {}
             source = cmeta.get("source_file", "")
             if source and source not in closet_boost_by_source:
                 closet_boost_by_source[source] = (rank, cdist, cdoc[:200])
@@ -372,14 +388,15 @@ def search_memories(
 
     scored: list = []
     for doc, meta, dist in zip(
-        drawer_results["documents"][0],
-        drawer_results["metadatas"][0],
-        drawer_results["distances"][0],
+        _first_or_empty(drawer_results, "documents"),
+        _first_or_empty(drawer_results, "metadatas"),
+        _first_or_empty(drawer_results, "distances"),
     ):
         # Filter on raw distance before rounding to avoid precision loss.
         if max_distance > 0.0 and dist > max_distance:
             continue
 
+        meta = meta or {}
         source = meta.get("source_file", "") or ""
         boost = 0.0
         matched_via = "drawer"
@@ -397,6 +414,7 @@ def search_memories(
             "wing": meta.get("wing", "unknown"),
             "room": meta.get("room", "unknown"),
             "source_file": Path(source).name if source else "?",
+            "created_at": meta.get("filed_at", "unknown"),
             "similarity": round(max(0.0, 1 - effective_dist), 3),
             "distance": round(dist, 4),
             "effective_distance": round(effective_dist, 4),
@@ -436,8 +454,8 @@ def search_memories(
             )
         except Exception:
             continue
-        docs = source_drawers.get("documents") or []
-        metas_ = source_drawers.get("metadatas") or []
+        docs = source_drawers.documents
+        metas_ = source_drawers.metadatas
         if len(docs) <= 1:
             continue
 
@@ -482,6 +500,6 @@ def search_memories(
     return {
         "query": query,
         "filters": {"wing": wing, "room": room},
-        "total_before_filter": len(drawer_results["documents"][0]),
+        "total_before_filter": len(_first_or_empty(drawer_results, "documents")),
         "results": hits,
     }

mempalace/sources/__init__.py

@@ -0,0 +1,74 @@
+"""Source adapter subsystem (RFC 002).
+
+Public surface:
+
+* :class:`BaseSourceAdapter` — per-source read-side contract.
+* Typed records: :class:`SourceRef`, :class:`SourceItemMetadata`,
+  :class:`DrawerRecord`, :class:`RouteHint`, :class:`SourceSummary`,
+  :class:`AdapterSchema`, :class:`FieldSpec`.
+* Error classes: :class:`SourceNotFoundError`, :class:`AuthRequiredError`,
+  :class:`AdapterClosedError`, :class:`TransformationViolationError`,
+  :class:`SchemaConformanceError`.
+* Registry: :func:`register`, :func:`get_adapter`, :func:`available_adapters`,
+  :func:`resolve_adapter_for_source`.
+* :class:`PalaceContext` — facade core passes to adapters during ``ingest``.
+* :mod:`transforms` — reference implementations of the reserved §1.4
+  transformations + :func:`get_transformation` resolver.
+"""
+
+from .base import (
+    AdapterClosedError,
+    AdapterSchema,
+    AuthRequiredError,
+    BaseSourceAdapter,
+    DrawerRecord,
+    FieldSpec,
+    IngestMode,
+    IngestResult,
+    RouteHint,
+    SchemaConformanceError,
+    SourceAdapterError,
+    SourceItemMetadata,
+    SourceNotFoundError,
+    SourceRef,
+    SourceSummary,
+    TransformationViolationError,
+)
+from .context import PalaceContext, ProgressHook
+from .registry import (
+    available_adapters,
+    get_adapter,
+    get_adapter_class,
+    register,
+    reset_adapters,
+    resolve_adapter_for_source,
+    unregister,
+)
+
+__all__ = [
+    "AdapterClosedError",
+    "AdapterSchema",
+    "AuthRequiredError",
+    "BaseSourceAdapter",
+    "DrawerRecord",
+    "FieldSpec",
+    "IngestMode",
+    "IngestResult",
+    "PalaceContext",
+    "ProgressHook",
+    "RouteHint",
+    "SchemaConformanceError",
+    "SourceAdapterError",
+    "SourceItemMetadata",
+    "SourceNotFoundError",
+    "SourceRef",
+    "SourceSummary",
+    "TransformationViolationError",
+    "available_adapters",
+    "get_adapter",
+    "get_adapter_class",
+    "register",
+    "reset_adapters",
+    "resolve_adapter_for_source",
+    "unregister",
+]

mempalace/sources/base.py

@@ -0,0 +1,245 @@
+"""Source adapter contract for MemPalace (RFC 002).
+
+Mirrors what ``mempalace/backends/base.py`` does for the write side: it defines
+the read-side surface every source adapter must implement. A source adapter
+extracts content from a specific origin (filesystem, git, Slack, Cursor …) and
+yields typed records (``SourceItemMetadata`` / ``DrawerRecord``) that core
+routes into the palace.
+
+This module is spec scaffolding. The first-party miners (``mempalace/miner.py``
+and ``mempalace/convo_miner.py``) are migrated onto it in a follow-up PR;
+in this PR we publish the contract so third-party adapters can begin building
+against a stable surface.
+
+See ``docs/rfcs/002-source-adapter-plugin-spec.md`` for the authoritative
+spec text.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, ClassVar, Iterator, Literal, Optional
+
+if TYPE_CHECKING:
+    from .context import PalaceContext  # noqa: F401  (used in string annotation)
+
+
+# ---------------------------------------------------------------------------
+# Errors
+# ---------------------------------------------------------------------------
+
+
+class SourceAdapterError(Exception):
+    """Base class for every source-adapter error raised by core."""
+
+
+class SourceNotFoundError(SourceAdapterError):
+    """Raised when a ``SourceRef`` does not resolve to a readable source."""
+
+
+class AuthRequiredError(SourceAdapterError):
+    """Raised when an adapter needs credentials that were not provided.
+
+    The message MUST name the env vars (or other supported mechanism) the
+    operator needs to set.
+    """
+
+
+class AdapterClosedError(SourceAdapterError):
+    """Raised when an adapter method is called after ``close()``."""
+
+
+class TransformationViolationError(SourceAdapterError):
+    """Raised by the conformance suite when round-tripping a drawer requires
+    an undeclared transformation (RFC 002 §7.2–7.3)."""
+
+
+class SchemaConformanceError(SourceAdapterError):
+    """Raised when a ``DrawerRecord.metadata`` violates the adapter schema
+    returned by :meth:`BaseSourceAdapter.describe_schema`."""
+
+
+# ---------------------------------------------------------------------------
+# Value objects
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class SourceRef:
+    """A handle to the source a user wants to ingest.
+
+    ``local_path`` is for filesystem-rooted sources (project dir, mbox file).
+    ``uri`` is for URL-like references (``github.com/org/repo``,
+    ``slack://workspace/channel``).
+    ``options`` carries adapter-specific non-secret config. Secrets MUST NOT
+    be placed here; see §4.2.
+    """
+
+    local_path: Optional[str] = None
+    uri: Optional[str] = None
+    options: dict = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class RouteHint:
+    """Adapter-supplied routing hint (RFC 002 §2.5)."""
+
+    wing: Optional[str] = None
+    room: Optional[str] = None
+    hall: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class SourceItemMetadata:
+    """Lightweight pointer yielded before drawers for lazy-fetch adapters.
+
+    Core inspects ``version`` via :meth:`BaseSourceAdapter.is_current` to
+    decide whether to skip extraction; an adapter that responds positively
+    stops yielding drawers for this item and moves to the next.
+    """
+
+    source_file: str
+    version: str
+    size_hint: Optional[int] = None
+    route_hint: Optional[RouteHint] = None
+
+
+@dataclass(frozen=True)
+class DrawerRecord:
+    """One drawer's worth of extracted content plus flat metadata.
+
+    ``metadata`` values MUST be flat scalars (``str``/``int``/``float``/``bool``)
+    per RFC 001 §1.4 — the chroma constraint. Nested data belongs on the
+    knowledge graph (§5.5) or in a declared ``json_string`` field (§5.4).
+    """
+
+    content: str
+    source_file: str
+    chunk_index: int = 0
+    metadata: dict = field(default_factory=dict)
+    route_hint: Optional[RouteHint] = None
+
+
+@dataclass(frozen=True)
+class SourceSummary:
+    """High-level description of a source returned by :meth:`source_summary`."""
+
+    description: str
+    item_count: Optional[int] = None
+
+
+IngestMode = Literal["chunked_content", "whole_record", "metadata_only"]
+
+
+@dataclass(frozen=True)
+class FieldSpec:
+    """Declared shape of a single per-adapter metadata field (§5.2)."""
+
+    type: Literal["string", "int", "float", "bool", "delimiter_joined_string", "json_string"]
+    required: bool
+    description: str
+    indexed: bool = False
+    delimiter: str = ";"
+    json_schema: Optional[dict] = None
+
+
+@dataclass(frozen=True)
+class AdapterSchema:
+    """The per-adapter metadata schema returned by :meth:`describe_schema`."""
+
+    fields: dict[str, FieldSpec]
+    version: str
+
+
+# The union type adapters yield from ``ingest``.
+IngestResult = object  # intentionally broad; runtime checks in core
+
+
+# ---------------------------------------------------------------------------
+# Adapter contract
+# ---------------------------------------------------------------------------
+
+
+class BaseSourceAdapter(ABC):
+    """Long-lived adapter serving many ``SourceRef`` invocations (RFC 002 §2).
+
+    Instances are lightweight on construction — no I/O, no network, no
+    credential fetch. All work is deferred to :meth:`ingest`. Instances are
+    thread-safe for concurrent ``ingest`` calls across different ``SourceRef``
+    values (v1 serializes within a single ``SourceRef``).
+
+    Class attributes form the adapter's identity contract:
+
+    * ``name`` — stable adapter name used for registration and drawer metadata.
+    * ``adapter_version`` — adapter's own version, independent of
+      ``spec_version``. Recorded on every drawer so re-extract workflows can
+      target drawers from a known-buggy adapter version.
+    * ``capabilities`` — free-form tokens; core inspects a documented subset.
+    * ``supported_modes`` — subset of ``chunked_content``, ``whole_record``,
+      ``metadata_only``.
+    * ``declared_transformations`` — set of transformation names the adapter
+      applies to source bytes. The empty set marks a byte-preserving adapter.
+    * ``default_privacy_class`` — privacy class level (§6) applied unless the
+      palace config overrides it.
+    """
+
+    name: ClassVar[str]
+    spec_version: ClassVar[str] = "1.0"
+    adapter_version: ClassVar[str] = "0.0.0"
+    capabilities: ClassVar[frozenset[str]] = frozenset()
+    supported_modes: ClassVar[frozenset[str]] = frozenset({"chunked_content"})
+    declared_transformations: ClassVar[frozenset[str]] = frozenset()
+    default_privacy_class: ClassVar[str] = "pii_potential"
+
+    # ------------------------------------------------------------------
+    # Required methods
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    def ingest(
+        self,
+        *,
+        source: SourceRef,
+        palace: "PalaceContext",
+    ) -> Iterator[IngestResult]:
+        """Enumerate and extract content from a source.
+
+        Yields a stream of ``SourceItemMetadata`` and ``DrawerRecord`` values.
+        Lazy adapters yield ``SourceItemMetadata`` ahead of the drawers for
+        that item so core can check :meth:`is_current` before committing to
+        the fetch. Eager adapters MAY interleave freely.
+        """
+
+    @abstractmethod
+    def describe_schema(self) -> AdapterSchema:
+        """Declare the structured metadata this adapter attaches.
+
+        The returned schema MUST be stable for a given ``adapter_version``.
+        Enterprises index on it; core uses it to validate adapter output.
+        """
+
+    # ------------------------------------------------------------------
+    # Optional methods with default implementations
+    # ------------------------------------------------------------------
+
+    def is_current(
+        self,
+        *,
+        item: SourceItemMetadata,
+        existing_metadata: Optional[dict],
+    ) -> bool:
+        """Return True if the palace already has an up-to-date copy of ``item``.
+
+        Default: always returns False (re-extract every time). Adapters
+        advertising ``supports_incremental`` MUST override.
+        """
+        return False
+
+    def source_summary(self, *, source: SourceRef) -> SourceSummary:
+        """Describe a source without extracting."""
+        return SourceSummary(description=self.name)
+
+    def close(self) -> None:
+        """Release any resources the adapter holds. Default: no-op."""
+        return None

mempalace/sources/context.py

@@ -0,0 +1,142 @@
+"""``PalaceContext`` facade passed to source adapters (RFC 002 §9).
+
+Bundles the palace-side surface an adapter needs during :meth:`ingest`:
+drawer collection, closet collection, knowledge graph, palace config, and
+progress hooks. Adapters receive a ``PalaceContext`` instance and MUST NOT
+import ``mempalace.palace`` directly — that coupling is what the facade
+exists to prevent.
+
+This module publishes the shape third-party adapters target. Core's mine
+loop will construct a concrete ``PalaceContext`` and pass it to adapters
+when the filesystem/conversations miners are migrated onto ``BaseSourceAdapter``
+in a follow-up PR; until then, no in-tree code constructs one, but the
+contract is stable.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional, Protocol
+
+from .base import DrawerRecord
+
+
+class _CollectionLike(Protocol):
+    """Minimum of :class:`mempalace.backends.BaseCollection` adapters rely on.
+
+    Declared as a Protocol so tests and third-party adapters can substitute
+    any object with compatible method signatures without importing the
+    concrete backend. See ``mempalace/backends/base.py`` for the full surface.
+    """
+
+    def add(self, **kwargs: Any) -> None: ...
+    def upsert(self, **kwargs: Any) -> None: ...
+    def query(self, **kwargs: Any) -> Any: ...
+    def get(self, **kwargs: Any) -> Any: ...
+    def delete(self, **kwargs: Any) -> None: ...
+    def count(self) -> int: ...
+
+
+class _KnowledgeGraphLike(Protocol):
+    def add_triple(self, subject: str, predicate: str, obj: str, **kwargs: Any) -> Any: ...
+
+
+# Progress hook signature: ``fn(event_name, **details) -> None``.
+ProgressHook = Callable[..., None]
+
+
+@dataclass
+class PalaceContext:
+    """Per-mine-invocation facade passed to :meth:`BaseSourceAdapter.ingest`.
+
+    Fields:
+        drawer_collection: The palace's drawer collection (via RFC 001 backend).
+        closet_collection: The palace's closet collection, or ``None`` if the
+            palace has no closets yet. Adapters should not write to this
+            directly; core builds closets post-step (RFC 002 §1.7).
+        knowledge_graph: The palace's SQLite knowledge graph. Adapters
+            advertising ``supports_kg_triples`` call ``add_triple`` on it.
+        palace_path: Filesystem root of the palace (convenience; same as
+            ``backend.PalaceRef.local_path``).
+        config: Palace config object (hall keywords, rooms list, privacy
+            floor, etc.). Shape is the existing :class:`MempalaceConfig`.
+        adapter_name: Name of the adapter currently ingesting; populated by
+            core so drawers can carry ``metadata["adapter_name"]``.
+        adapter_version: Version of the adapter currently ingesting.
+        progress_hooks: Optional callables core invokes on progress events.
+
+    Methods are intentionally thin wrappers so the concrete mine loop in
+    core can swap implementations without changing adapter code.
+    """
+
+    drawer_collection: _CollectionLike
+    knowledge_graph: _KnowledgeGraphLike
+    palace_path: str
+    closet_collection: Optional[_CollectionLike] = None
+    config: Optional[Any] = None
+    adapter_name: str = ""
+    adapter_version: str = ""
+    progress_hooks: list[ProgressHook] = field(default_factory=list)
+
+    # Internal: flag set by :meth:`skip_current_item` and checked by the core
+    # mine loop between yields. Not part of the adapter-facing contract; the
+    # adapter only needs to know that calling :meth:`skip_current_item` stops
+    # drawer emission for the current ``SourceItemMetadata``.
+    _skip_requested: bool = False
+
+    # ------------------------------------------------------------------
+    # Adapter-facing surface
+    # ------------------------------------------------------------------
+
+    def upsert_drawer(self, record: DrawerRecord) -> None:
+        """Persist a ``DrawerRecord`` to the drawer collection.
+
+        Applies the spec-mandated ``adapter_name`` and ``adapter_version``
+        metadata stamps (§5.1) so adapters never need to populate them.
+        """
+        meta = dict(record.metadata)
+        meta.setdefault("source_file", record.source_file)
+        meta.setdefault("chunk_index", record.chunk_index)
+        if self.adapter_name:
+            meta.setdefault("adapter_name", self.adapter_name)
+        if self.adapter_version:
+            meta.setdefault("adapter_version", self.adapter_version)
+        drawer_id = _build_drawer_id(record)
+        self.drawer_collection.upsert(
+            documents=[record.content],
+            ids=[drawer_id],
+            metadatas=[meta],
+        )
+
+    def skip_current_item(self) -> None:
+        """Signal to core that the current ``SourceItemMetadata`` is up-to-date
+        and no drawers should be emitted for it. Core resets the flag after
+        advancing past the item."""
+        self._skip_requested = True
+
+    def emit(self, event: str, **details: Any) -> None:
+        """Invoke each registered progress hook with ``(event, **details)``."""
+        for hook in self.progress_hooks:
+            try:
+                hook(event, **details)
+            except Exception:  # pragma: no cover - hook errors never fail mine
+                import logging
+
+                logging.getLogger(__name__).exception("progress hook failed on %r", event)
+
+
+def _build_drawer_id(record: DrawerRecord) -> str:
+    """Deterministic drawer id: ``<sha256(source_file)[:24]>_<chunk_index>``.
+
+    Matches the shape existing miners rely on (``source_file`` + chunk index
+    pair) while keeping the id chroma-safe (no separators that collide with
+    existing metadata values). 96-bit SHA-256 prefix keeps collision risk
+    negligible across corpora the size of a palace (sha1@64 bits was too
+    close to the birthday bound for large ingests). Adapters that need a
+    different id scheme can bypass :meth:`PalaceContext.upsert_drawer` and
+    write through ``drawer_collection.upsert`` directly.
+    """
+    import hashlib
+
+    digest = hashlib.sha256(record.source_file.encode("utf-8")).hexdigest()[:24]
+    return f"{digest}_{record.chunk_index}"

mempalace/sources/registry.py

@@ -0,0 +1,162 @@
+"""Source adapter registry + entry-point discovery (RFC 002 §3).
+
+Third-party adapters ship as installable packages that declare a
+``mempalace.sources`` entry point::
+
+    # pyproject.toml of mempalace-source-cursor
+    [project.entry-points."mempalace.sources"]
+    cursor = "mempalace_source_cursor:CursorAdapter"
+
+MemPalace discovers them at process start. In-tree tests and local
+development can register manually via :func:`register`. Explicit
+registration wins on name conflict (RFC 002 §3.2).
+
+Unlike storage backends (RFC 001 §3.3), source adapters are never auto-
+detected — the user selects the adapter explicitly via ``--source NAME``
+or config (§3.3). The default when no adapter is named is ``filesystem``
+(to preserve current ``mempalace mine <path>`` behavior).
+"""
+
+from __future__ import annotations
+
+import logging
+from importlib import metadata
+from threading import Lock
+from typing import Type
+
+from .base import BaseSourceAdapter
+
+logger = logging.getLogger(__name__)
+
+_ENTRY_POINT_GROUP = "mempalace.sources"
+_DEFAULT_ADAPTER = "filesystem"
+
+_registry: dict[str, Type[BaseSourceAdapter]] = {}
+_instances: dict[str, BaseSourceAdapter] = {}
+_explicit: set[str] = set()
+_discovered = False
+_lock = Lock()
+
+
+def register(name: str, adapter_cls: Type[BaseSourceAdapter]) -> None:
+    """Register ``adapter_cls`` under ``name``.
+
+    Explicit registration wins over entry-point discovery on conflict (§3.2).
+    """
+    with _lock:
+        _registry[name] = adapter_cls
+        _explicit.add(name)
+        _instances.pop(name, None)
+
+
+def unregister(name: str) -> None:
+    """Remove an adapter registration (primarily for tests)."""
+    with _lock:
+        _registry.pop(name, None)
+        _explicit.discard(name)
+        _instances.pop(name, None)
+
+
+def _discover_entry_points() -> None:
+    global _discovered
+    if _discovered:
+        return
+    with _lock:
+        if _discovered:
+            return
+        try:
+            eps = metadata.entry_points()
+            group = (
+                eps.select(group=_ENTRY_POINT_GROUP)
+                if hasattr(eps, "select")
+                else eps.get(_ENTRY_POINT_GROUP, [])
+            )
+        except Exception:
+            logger.exception("entry-point discovery for %s failed", _ENTRY_POINT_GROUP)
+            group = []
+        for ep in group:
+            if ep.name in _explicit:
+                continue  # explicit registration wins
+            try:
+                cls = ep.load()
+            except Exception:
+                logger.exception("failed to load adapter entry point %r", ep.name)
+                continue
+            if not isinstance(cls, type) or not issubclass(cls, BaseSourceAdapter):
+                logger.warning(
+                    "entry point %r did not resolve to a BaseSourceAdapter subclass (got %r)",
+                    ep.name,
+                    cls,
+                )
+                continue
+            _registry.setdefault(ep.name, cls)
+        _discovered = True
+
+
+def available_adapters() -> list[str]:
+    """Return sorted list of all registered adapter names."""
+    _discover_entry_points()
+    return sorted(_registry.keys())
+
+
+def get_adapter_class(name: str) -> Type[BaseSourceAdapter]:
+    """Return the registered adapter class for ``name``."""
+    _discover_entry_points()
+    try:
+        return _registry[name]
+    except KeyError as e:
+        raise KeyError(f"unknown source adapter {name!r}; available: {available_adapters()}") from e
+
+
+def get_adapter(name: str) -> BaseSourceAdapter:
+    """Return a long-lived instance of the named adapter.
+
+    Instances are cached per-name; repeated calls return the same object.
+    Call :func:`reset_adapters` in tests that need isolation.
+    """
+    _discover_entry_points()
+    with _lock:
+        inst = _instances.get(name)
+        if inst is not None:
+            return inst
+        cls = _registry.get(name)
+        if cls is None:
+            raise KeyError(
+                f"unknown source adapter {name!r}; available: {sorted(_registry.keys())}"
+            )
+        inst = cls()
+        _instances[name] = inst
+        return inst
+
+
+def reset_adapters() -> None:
+    """Close and drop all cached adapter instances (primarily for tests)."""
+    with _lock:
+        for inst in _instances.values():
+            try:
+                inst.close()
+            except Exception:
+                logger.exception("error closing adapter during reset")
+        _instances.clear()
+
+
+def resolve_adapter_for_source(
+    *,
+    explicit: str | None = None,
+    config_value: str | None = None,
+    default: str = _DEFAULT_ADAPTER,
+) -> str:
+    """Resolve the adapter name per RFC 002 §3.3 priority order.
+
+    1. Explicit ``--source`` flag or kwarg
+    2. Per-source config value
+    3. Default (``filesystem``)
+
+    Auto-detection is *intentionally* absent on the read side (§3.3); a
+    directory containing ``.git`` + ``workspaceStorage/`` + an ``mbox`` file
+    is not a signal of user intent.
+    """
+    for candidate in (explicit, config_value):
+        if candidate:
+            return candidate
+    return default

mempalace/sources/transforms.py

@@ -0,0 +1,196 @@
+"""Reference implementations of the reserved content transformations (RFC 002 §1.4).
+
+Every source adapter declares the set of transformations it applies to source
+bytes via ``declared_transformations``. The conformance suite then verifies
+that the adapter's output can be reproduced from the source bytes by applying
+*only* the declared transformations in declaration order, using these
+reference implementations.
+
+Each transformation is a pure function on strings (text content after UTF-8
+decoding). ``utf8_replace_invalid`` is the one that operates on bytes.
+
+The invariant the spec enforces: **no transformation is applied that is not
+declared in the adapter's set**. Adapters with an empty set are byte-preserving
+end-to-end (modulo the initial UTF-8 decode itself, which is captured by
+``utf8_replace_invalid`` when applicable).
+
+Adapters MAY add custom transformations beyond the reserved set; third-party
+names SHOULD be prefixed with the adapter name (``cursor.composer_ordering``).
+Custom transformations MUST expose a reference implementation under
+``mempalace.sources.transforms.<adapter_name>_<transform_name>`` so the
+conformance suite can locate and apply them.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Protocol, Union
+
+
+class Transformation(Protocol):
+    """Callable signature every reserved transformation conforms to.
+
+    Accepts the current stage of the pipeline — ``bytes`` on input
+    (``utf8_replace_invalid``) or ``str`` after decoding — and returns ``str``.
+    Adapters compose them in declaration order; the first step operates on the
+    original source bytes, every subsequent step on the prior step's output.
+    """
+
+    def __call__(self, data: Union[bytes, str], /) -> str: ...
+
+
+# ---------------------------------------------------------------------------
+# Reserved transformations
+# ---------------------------------------------------------------------------
+
+
+def utf8_replace_invalid(raw: bytes) -> str:
+    """Decode bytes as UTF-8; replace invalid sequences with U+FFFD.
+
+    Equivalent to ``raw.decode("utf-8", errors="replace")``. This is the one
+    reserved transformation that operates on bytes rather than decoded text.
+    """
+    return raw.decode("utf-8", errors="replace")
+
+
+def newline_normalize(text: str) -> str:
+    """Convert CRLF and bare-CR line endings to LF."""
+    return text.replace("\r\n", "\n").replace("\r", "\n")
+
+
+def whitespace_trim(text: str) -> str:
+    """Strip leading and trailing whitespace at the record boundary only."""
+    return text.strip()
+
+
+_RUN_OF_THREE_OR_MORE_BLANK = re.compile(r"(?:\n[ \t]*){3,}\n")
+
+
+def whitespace_collapse_internal(text: str) -> str:
+    """Collapse runs of three or more blank lines to exactly two blank lines.
+
+    A "blank line" here is a line containing only spaces or tabs. Single and
+    double blank-line runs are preserved.
+    """
+    # Normalise inputs before collapsing: turn internal blank lines with
+    # whitespace content into pure \n so the regex matches consistently.
+    lines = text.split("\n")
+    normalised = "\n".join(line if line.strip() else "" for line in lines)
+    return _RUN_OF_THREE_OR_MORE_BLANK.sub("\n\n\n", normalised)
+
+
+def line_trim(text: str) -> str:
+    """Strip leading and trailing whitespace from each individual line."""
+    return "\n".join(line.strip() for line in text.split("\n"))
+
+
+def line_join_spaces(text: str) -> str:
+    """Join adjacent non-blank lines with a single space, preserving paragraph breaks.
+
+    Two lines separated by at least one blank line remain on separate lines;
+    runs of non-blank lines collapse into a single space-separated line.
+    """
+    paragraphs = re.split(r"\n[ \t]*\n", text)
+    joined = [" ".join(line.strip() for line in p.split("\n") if line.strip()) for p in paragraphs]
+    return "\n\n".join(joined)
+
+
+def blank_line_drop(text: str) -> str:
+    """Drop blank lines between non-blank lines, keeping non-blank lines only."""
+    return "\n".join(line for line in text.split("\n") if line.strip())
+
+
+# The following reserved transformations are declared in the spec but are
+# deeply adapter-specific. Rather than guess a single reference implementation
+# now, we provide identity shims that leave the input unchanged when no
+# adapter-specific implementation is available. Adapters that declare these
+# MUST either override with a concrete implementation or provide a namespaced
+# reference under
+# ``mempalace.sources.transforms.<adapter_name>_<transform_name>`` (per the
+# module docstring). The conformance suite looks up the adapter-specific
+# implementation first, falling back to these identity shims only when none
+# exists.
+
+
+def strip_tool_chrome(text: str) -> str:
+    """Adapter-supplied: remove system tags, hook output, tool UI chrome.
+
+    The reference implementation here is intentionally an identity function
+    because the noise patterns differ per transcript format (Claude Code,
+    Codex, ChatGPT, Slack). The conversations adapter, when migrated, will
+    register a concrete reference implementation under
+    ``mempalace.sources.transforms.conversations_strip_tool_chrome``.
+    """
+    return text
+
+
+def tool_result_truncate(text: str) -> str:
+    """Adapter-supplied: head/tail window on tool output with a middle marker."""
+    return text
+
+
+def tool_result_omitted(text: str) -> str:
+    """Adapter-supplied: fully omit some tool outputs (e.g., Read/Edit/Write)."""
+    return text
+
+
+def spellcheck_user(text: str) -> str:
+    """Adapter-supplied: rewrite user turns via autocorrect.
+
+    Requires the optional ``spellcheck`` extra and a tokenizer; the spec does
+    not mandate a specific language model, so the reference is adapter-owned.
+    """
+    return text
+
+
+def synthesized_marker(text: str) -> str:
+    """Adapter-supplied: adapter inserts its own strings (e.g., '[N lines omitted]')."""
+    return text
+
+
+def speaker_role_assignment(text: str) -> str:
+    """Adapter-supplied: multi-party speakers alternately assigned user/assistant."""
+    return text
+
+
+# ---------------------------------------------------------------------------
+# Registry
+# ---------------------------------------------------------------------------
+
+
+# Reserved transformation name → reference implementation.
+# Adapters look up by name to compose a round-trip pipeline during testing.
+# The value conforms to the :class:`Transformation` protocol above; we type
+# it as that Protocol rather than a concrete ``Callable`` so static checkers
+# accept both the bytes→str (``utf8_replace_invalid``) and str→str shapes.
+RESERVED_TRANSFORMATIONS: dict[str, Transformation] = {
+    "utf8_replace_invalid": utf8_replace_invalid,
+    "newline_normalize": newline_normalize,
+    "whitespace_trim": whitespace_trim,
+    "whitespace_collapse_internal": whitespace_collapse_internal,
+    "line_trim": line_trim,
+    "line_join_spaces": line_join_spaces,
+    "blank_line_drop": blank_line_drop,
+    "strip_tool_chrome": strip_tool_chrome,
+    "tool_result_truncate": tool_result_truncate,
+    "tool_result_omitted": tool_result_omitted,
+    "spellcheck_user": spellcheck_user,
+    "synthesized_marker": synthesized_marker,
+    "speaker_role_assignment": speaker_role_assignment,
+}
+
+
+def get_transformation(name: str) -> Transformation:
+    """Resolve a reserved transformation by name.
+
+    Raises :class:`KeyError` if the name is neither reserved nor registered as
+    an adapter-namespaced reference (``<adapter>_<transform>``). Callers
+    looking for adapter-specific references SHOULD ``getattr`` on this module
+    first; this helper only covers the reserved names.
+    """
+    try:
+        return RESERVED_TRANSFORMATIONS[name]
+    except KeyError as e:
+        raise KeyError(
+            f"unknown transformation {name!r}; reserved names: {sorted(RESERVED_TRANSFORMATIONS)}"
+        ) from e

mempalace/split_mega_files.py

@@ -50,7 +50,7 @@ def _load_known_names_config(force_reload: bool = False):
 
     if _KNOWN_NAMES_PATH.exists():
         try:
-            _KNOWN_NAMES_CACHE = json.loads(_KNOWN_NAMES_PATH.read_text())
+            _KNOWN_NAMES_CACHE = json.loads(_KNOWN_NAMES_PATH.read_text(encoding="utf-8"))
             return _KNOWN_NAMES_CACHE
         except (json.JSONDecodeError, OSError):
             pass
@@ -184,7 +184,7 @@ def split_file(filepath, output_dir, dry_run=False):
     path = Path(filepath)
     max_size = 500 * 1024 * 1024  # 500 MB safety limit
     if path.stat().st_size > max_size:
-        print(f"  SKIP: {path.name} exceeds {max_size // (1024*1024)} MB limit")
+        print(f"  SKIP: {path.name} exceeds {max_size // (1024 * 1024)} MB limit")
         return []
     lines = path.read_text(errors="replace").splitlines(keepends=True)
 
@@ -224,7 +224,7 @@ def split_file(filepath, output_dir, dry_run=False):
             print(f"  [{i + 1}/{len(boundaries) - 1}] {name}  ({len(chunk)} lines)")
         else:
             out_path.write_text("".join(chunk), encoding="utf-8")
-            print(f"  ✓ {name}  ({len(chunk)} lines)")
+            print(f"  + {name}  ({len(chunk)} lines)")
 
         written.append(out_path)
 
@@ -273,7 +273,7 @@ def main():
     max_scan_size = 500 * 1024 * 1024  # 500 MB
     for f in files:
         if f.stat().st_size > max_scan_size:
-            print(f"  SKIP: {f.name} exceeds {max_scan_size // (1024*1024)} MB limit")
+            print(f"  SKIP: {f.name} exceeds {max_scan_size // (1024 * 1024)} MB limit")
             continue
         lines = f.read_text(errors="replace").splitlines(keepends=True)
         boundaries = find_session_boundaries(lines)
@@ -290,7 +290,7 @@ def main():
     print(f"  Source:      {src_dir}")
     print(f"  Output:      {output_dir or 'same dir as source'}")
     print(f"  Mega-files:  {len(mega_files)}")
-    print(f"{'─' * 60}\n")
+    print(f"{'-' * 60}\n")
 
     total_written = 0
     for f, n_sessions in mega_files:
@@ -301,11 +301,11 @@ def main():
         if not args.dry_run and written:
             backup = f.with_suffix(".mega_backup")
             f.rename(backup)
-            print(f"  → Original renamed to {backup.name}\n")
+            print(f"  -> Original renamed to {backup.name}\n")
         else:
             print()
 
-    print(f"{'─' * 60}")
+    print(f"{'-' * 60}")
     if args.dry_run:
         print(f"  DRY RUN — would create {total_written} files from {len(mega_files)} mega-files")
     else:

mempalace/sweeper.py

@@ -0,0 +1,347 @@
+#!/usr/bin/env python3
+"""
+sweeper.py — Message-granular miner that catches what the file-level
+primary miners dropped.
+
+Algorithm, per session:
+
+    cursor = max(timestamp of sweeper-written drawers for this session_id)
+    For each user/assistant message in the jsonl:
+        if cursor is not None and message.timestamp < cursor: skip
+        else: upsert a drawer keyed by (session_id, message_uuid)
+
+Properties:
+
+  - Idempotent on its own writes: rerunning is a no-op because drawer
+    IDs are deterministic and existence is pre-checked before counting.
+  - Resume-safe: a crash mid-sweep is recovered on the next run — the
+    cursor advances to the last ingested timestamp and re-attempts at
+    that boundary are de-duped by the deterministic ID.
+  - Tie-break safe: uses ``< cursor`` (not ``<=``), so if multiple
+    messages share the max timestamp and only some were ingested, the
+    rest are still picked up on re-run.
+  - No size caps: each drawer holds one exchange, ~1-5 KB.
+
+Coordination with the primary file-level miners (``miner.py`` /
+``convo_miner.py``) is limited: those miners chunk at a fixed char size
+and do not currently stamp ``session_id``/``timestamp`` metadata that
+the sweeper can key off. In practice the sweeper coordinates with its
+own prior runs, and may ingest content that also got chunked into
+primary-miner drawers (under different IDs). Follow-up: add uniform
+``ingest_mode`` + message metadata to the primary miners so dedup spans
+both paths.
+
+Usage:
+    from mempalace.sweeper import sweep
+    result = sweep("/path/to/session.jsonl", "/path/to/palace")
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Iterator, Optional
+
+from .palace import get_collection
+
+logger = logging.getLogger(__name__)
+
+
+# ── JSONL parsing ────────────────────────────────────────────────────
+
+
+def _flatten_content(content) -> str:
+    """Normalize Claude Code's message content to a plain string.
+
+    User messages are strings already; assistant messages are a list of
+    content blocks like [{"type": "text", "text": "..."}, {"type":
+    "tool_use", ...}]. All blocks are preserved verbatim — the design
+    principle is "verbatim always", so tool inputs and results are
+    serialized in full, never truncated.
+    """
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = []
+        for block in content:
+            if not isinstance(block, dict):
+                continue
+            btype = block.get("type", "")
+            if btype == "text":
+                parts.append(block.get("text", ""))
+            elif btype == "tool_use":
+                parts.append(
+                    f"[tool_use: {block.get('name', '?')} "
+                    f"input={json.dumps(block.get('input', {}), default=str)}]"
+                )
+            elif btype == "tool_result":
+                parts.append(f"[tool_result: {json.dumps(block.get('content', ''), default=str)}]")
+            else:
+                parts.append(f"[{btype}: {json.dumps(block, default=str)}]")
+        return "\n".join(p for p in parts if p)
+    return str(content)
+
+
+def parse_claude_jsonl(path: str) -> Iterator[dict]:
+    """Yield user/assistant records from a Claude Code .jsonl file.
+
+    Each yield is:
+        {
+          "session_id": str,
+          "uuid":       str,   # per-message UUID
+          "timestamp":  str,   # ISO 8601
+          "role":       "user" | "assistant",
+          "content":    str,   # flattened text
+        }
+
+    Non-message records (progress, file-history-snapshot, system,
+    queue-operation, last-prompt) are filtered out. Malformed lines are
+    skipped silently — data quality is the transcript writer's problem,
+    not ours.
+    """
+    with open(path, "r", encoding="utf-8", errors="replace") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                record = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            rtype = record.get("type")
+            if rtype not in ("user", "assistant"):
+                continue
+            msg = record.get("message") or {}
+            if not isinstance(msg, dict):
+                continue
+            role = msg.get("role")
+            if role not in ("user", "assistant"):
+                continue
+            timestamp = record.get("timestamp")
+            if not timestamp:
+                continue
+            uuid = record.get("uuid")
+            if not uuid:
+                continue
+            session_id = record.get("sessionId") or record.get("session_id")
+            if not session_id:
+                continue
+            content = _flatten_content(msg.get("content", ""))
+            if not content.strip():
+                continue
+            yield {
+                "session_id": session_id,
+                "uuid": uuid,
+                "timestamp": timestamp,
+                "role": role,
+                "content": content,
+            }
+
+
+# ── Cursor resolution ────────────────────────────────────────────────
+
+
+def get_palace_cursor(collection, session_id: str) -> Optional[str]:
+    """Return the max timestamp of drawers for this session_id, or None.
+
+    ISO-8601 strings compare lexically in the right order, so we don't
+    need to parse them. Query scans metadatas for the session via the
+    backend's where-filter, then reduces.
+
+    Backend errors are logged at WARNING and surface as a `None` cursor —
+    which makes the caller treat the session as empty and ingest every
+    message. That's intentional: a no-cursor sweep is recovered from on
+    the next run by deterministic drawer IDs, so a degraded cursor never
+    causes silent data loss.
+    """
+    try:
+        data = collection.get(
+            where={"session_id": session_id},
+            include=["metadatas"],
+        )
+    except Exception as exc:
+        logger.warning(
+            "sweeper: cursor lookup failed for session_id=%s (%s); "
+            "treating as empty — drawers will be re-upserted idempotently.",
+            session_id,
+            exc,
+        )
+        return None
+    metas = data.get("metadatas") or []
+    timestamps = [m.get("timestamp") for m in metas if m and m.get("timestamp")]
+    if not timestamps:
+        return None
+    return max(timestamps)
+
+
+# ── Sweep ────────────────────────────────────────────────────────────
+
+
+def _drawer_id_for_message(session_id: str, message_uuid: str) -> str:
+    """Deterministic drawer ID so upserts at the same message are no-ops.
+
+    Uses the full session_id (not a prefix) to avoid any cross-session
+    collision risk if a transcript source ever uses non-UUID session
+    identifiers or shares prefixes across sessions.
+    """
+    return f"sweep_{session_id}_{message_uuid}"
+
+
+def sweep(jsonl_path: str, palace_path: str, source_label: Optional[str] = None) -> dict:
+    """Ingest every user/assistant message not already represented.
+
+    For each message in the jsonl:
+      - If timestamp < cursor for that session, skip (strictly earlier
+        than anything already in the palace — already covered).
+      - At timestamp == cursor we do NOT skip, because multiple messages
+        can share the same ISO-8601 timestamp; if only some of them were
+        ingested before a crash, a `<= cursor` skip would lose the rest
+        forever. Deterministic drawer IDs make re-attempting at the
+        cursor boundary safe (existing rows are found via a pre-flight
+        `get(ids=...)` and counted as "already present", not "added").
+      - Else, upsert a drawer with deterministic ID so reruns dedupe.
+
+    Returns ``{drawers_added, drawers_already_present, drawers_skipped,
+    drawers_upserted, cursor_by_session}``:
+
+    * ``drawers_added`` — rows that did not exist before this sweep.
+    * ``drawers_already_present`` — rows whose deterministic ID was
+      already in the palace and got rewritten idempotently.
+    * ``drawers_skipped`` — records skipped by the cursor (strictly
+      earlier than what's already stored).
+    * ``drawers_upserted`` — total writes = added + already_present.
+    """
+    collection = get_collection(palace_path, create=True)
+    cursors: dict = {}
+
+    drawers_added = 0
+    drawers_already_present = 0
+    drawers_skipped = 0
+
+    batch_ids: list[str] = []
+    batch_docs: list[str] = []
+    batch_metas: list[dict] = []
+    BATCH_SIZE = 64
+
+    def _flush():
+        nonlocal drawers_added, drawers_already_present
+        if not batch_ids:
+            return
+        # Pre-flight: which IDs in this batch are already present?
+        # Upsert is idempotent on data but counts as "added" would lie;
+        # this pre-query makes the metric honest (Copilot PR 998 review).
+        try:
+            existing = collection.get(ids=list(batch_ids), include=[])
+            # Chroma returns a dict; typed backends return GetResult — the
+            # compat shim makes ``.get("ids")`` work on both.
+            present = set(existing.get("ids") or [])
+        except Exception as exc:
+            logger.warning(
+                "sweeper: existence pre-check failed (%s); "
+                "counting all batch rows as new (metric may over-count on reruns).",
+                exc,
+            )
+            present = set()
+        new_count = sum(1 for rid in batch_ids if rid not in present)
+        already_count = len(batch_ids) - new_count
+
+        collection.upsert(
+            ids=batch_ids,
+            documents=batch_docs,
+            metadatas=batch_metas,
+        )
+        drawers_added += new_count
+        drawers_already_present += already_count
+        batch_ids.clear()
+        batch_docs.clear()
+        batch_metas.clear()
+
+    for rec in parse_claude_jsonl(jsonl_path):
+        sid = rec["session_id"]
+        if sid not in cursors:
+            cursors[sid] = get_palace_cursor(collection, sid)
+
+        cursor = cursors[sid]
+        if cursor is not None and rec["timestamp"] < cursor:
+            drawers_skipped += 1
+            continue
+
+        drawer_id = _drawer_id_for_message(sid, rec["uuid"])
+        document = f"{rec['role'].upper()}: {rec['content']}"
+        metadata = {
+            "session_id": sid,
+            "timestamp": rec["timestamp"],
+            "message_uuid": rec["uuid"],
+            "role": rec["role"],
+            "source_file": source_label or jsonl_path,
+            "filed_at": datetime.now().isoformat(),
+            "ingest_mode": "sweep",
+        }
+
+        batch_ids.append(drawer_id)
+        batch_docs.append(document)
+        batch_metas.append(metadata)
+
+        if len(batch_ids) >= BATCH_SIZE:
+            _flush()
+
+    _flush()
+
+    return {
+        "drawers_added": drawers_added,
+        "drawers_already_present": drawers_already_present,
+        "drawers_upserted": drawers_added + drawers_already_present,
+        "drawers_skipped": drawers_skipped,
+        "cursor_by_session": cursors,
+    }
+
+
+def sweep_directory(dir_path: str, palace_path: str) -> dict:
+    """Sweep every .jsonl file in a directory (recursive).
+
+    Returns aggregated summary across all files. ``files_attempted``
+    includes files that raised, so the count reflects discovery rather
+    than only successes; ``files_succeeded`` is the subset that
+    completed without error.
+    """
+    dir_p = Path(dir_path).expanduser().resolve()
+    files = sorted(dir_p.rglob("*.jsonl"))
+
+    total_added = 0
+    total_already_present = 0
+    total_skipped = 0
+    per_file = []
+
+    failures: list[dict] = []
+    for f in files:
+        try:
+            result = sweep(str(f), palace_path, source_label=str(f))
+        except Exception as exc:
+            logger.error("sweeper: sweep failed on %s: %s", f, exc)
+            print(f"  WARNING: sweep failed on {f}: {exc}", file=sys.stderr)
+            failures.append({"file": str(f), "error": str(exc)})
+            continue
+        total_added += result["drawers_added"]
+        total_already_present += result.get("drawers_already_present", 0)
+        total_skipped += result["drawers_skipped"]
+        per_file.append(
+            {
+                "file": str(f),
+                "added": result["drawers_added"],
+                "already_present": result.get("drawers_already_present", 0),
+                "skipped": result["drawers_skipped"],
+            }
+        )
+
+    return {
+        "files_attempted": len(files),
+        "files_succeeded": len(per_file),
+        "drawers_added": total_added,
+        "drawers_already_present": total_already_present,
+        "drawers_skipped": total_skipped,
+        "per_file": per_file,
+        "failures": failures,
+    }

mempalace/version.py

@@ -1,3 +1,3 @@
 """Single source of truth for the MemPalace package version."""
 
-__version__ = "3.3.0"
+__version__ = "3.3.3"

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mempalace"
-version = "3.3.0"
+version = "3.3.3"
 description = "Give your AI a memory — mine projects and conversations into a searchable palace. No API key required."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -21,21 +21,34 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
     "Topic :: Utilities",
 ]
 dependencies = [
-    "chromadb>=0.5.0",
+    "chromadb>=1.5.4,<2",
     "pyyaml>=6.0,<7",
+    "tomli>=2.0.0; python_version < '3.11'",
 ]
 
 [project.urls]
-Homepage = "https://github.com/milla-jovovich/mempalace"
-Repository = "https://github.com/milla-jovovich/mempalace"
-"Bug Tracker" = "https://github.com/milla-jovovich/mempalace/issues"
+Homepage = "https://github.com/MemPalace/mempalace"
+Repository = "https://github.com/MemPalace/mempalace"
+"Bug Tracker" = "https://github.com/MemPalace/mempalace/issues"
 
 [project.scripts]
 mempalace = "mempalace.cli:main"
+mempalace-mcp = "mempalace.mcp_server:main"
+
+[project.entry-points."mempalace.backends"]
+chroma = "mempalace.backends.chroma:ChromaBackend"
+
+# RFC 002 source-adapter entry-point group. Core publishes no first-party
+# adapters under this group yet; ``miner.py`` and ``convo_miner.py`` migrate
+# onto ``BaseSourceAdapter`` in a follow-up PR. Third-party adapter packages
+# (``mempalace-source-cursor``, ``mempalace-source-git``, …) register here.
+[project.entry-points."mempalace.sources"]
 
 [project.optional-dependencies]
 dev = ["pytest>=7.0", "pytest-cov>=4.0", "ruff>=0.4.0", "psutil>=5.9"]

tests/benchmarks/benchmark_dialect.py

@@ -0,0 +1,14 @@
+import pytest
+import timeit
+import re
+
+from mempalace.dialect import Dialect
+
+def test_detect_entities_benchmark():
+    dialect = Dialect()
+    text = "Alice went to the market and met Bob who is a nice guy. They both discussed about Dr. Chen and how he solved the big issue. Another sentence with Name and Name2 and SomeName"
+
+    # Run the function multiple times to measure the performance
+    number = 10000
+    time = timeit.timeit(lambda: dialect._detect_entities_in_text(text), number=number)
+    print(f"\nDialect._detect_entities_in_text benchmark: {time:.4f} seconds for {number} iterations")

tests/test_backends.py

@@ -1,14 +1,42 @@
+import os
 import sqlite3
 
 import chromadb
 import pytest
 
-from mempalace.backends.chroma import ChromaBackend, ChromaCollection, _fix_blob_seq_ids
+from mempalace.backends import (
+    GetResult,
+    PalaceRef,
+    QueryResult,
+    UnsupportedFilterError,
+    available_backends,
+    get_backend,
+)
+from mempalace.backends.chroma import (
+    ChromaBackend,
+    ChromaCollection,
+    _fix_blob_seq_ids,
+    quarantine_stale_hnsw,
+)
 
 
 class _FakeCollection:
-    def __init__(self):
+    """Stand-in for a chromadb.Collection returning raw chroma-shaped dicts."""
+
+    def __init__(self, query_response=None, get_response=None, count_value=7):
         self.calls = []
+        self._query_response = query_response or {
+            "ids": [["a", "b"]],
+            "documents": [["da", "db"]],
+            "metadatas": [[{"wing": "w1"}, {"wing": "w2"}]],
+            "distances": [[0.1, 0.2]],
+        }
+        self._get_response = get_response or {
+            "ids": ["a"],
+            "documents": ["da"],
+            "metadatas": [{"wing": "w1"}],
+        }
+        self._count_value = count_value
 
     def add(self, **kwargs):
         self.calls.append(("add", kwargs))
@@ -16,41 +44,251 @@ class _FakeCollection:
     def upsert(self, **kwargs):
         self.calls.append(("upsert", kwargs))
 
+    def update(self, **kwargs):
+        self.calls.append(("update", kwargs))
+
     def query(self, **kwargs):
         self.calls.append(("query", kwargs))
-        return {"kind": "query"}
+        return self._query_response
 
     def get(self, **kwargs):
         self.calls.append(("get", kwargs))
-        return {"kind": "get"}
+        return self._get_response
 
     def delete(self, **kwargs):
         self.calls.append(("delete", kwargs))
 
     def count(self):
         self.calls.append(("count", {}))
-        return 7
+        return self._count_value
 
 
-def test_chroma_collection_delegates_methods():
+def test_chroma_collection_returns_typed_query_result():
+    fake = _FakeCollection()
+    collection = ChromaCollection(fake)
+
+    result = collection.query(query_texts=["q"])
+
+    assert isinstance(result, QueryResult)
+    assert result.ids == [["a", "b"]]
+    assert result.documents == [["da", "db"]]
+    assert result.metadatas == [[{"wing": "w1"}, {"wing": "w2"}]]
+    assert result.distances == [[0.1, 0.2]]
+    assert result.embeddings is None
+
+
+def test_chroma_collection_returns_typed_get_result():
+    fake = _FakeCollection()
+    collection = ChromaCollection(fake)
+
+    result = collection.get(where={"wing": "w1"})
+
+    assert isinstance(result, GetResult)
+    assert result.ids == ["a"]
+    assert result.documents == ["da"]
+    assert result.metadatas == [{"wing": "w1"}]
+
+
+def test_query_result_empty_preserves_outer_dimension():
+    empty = QueryResult.empty(num_queries=2)
+    assert empty.ids == [[], []]
+    assert empty.documents == [[], []]
+    assert empty.distances == [[], []]
+    assert empty.embeddings is None
+
+
+def test_typed_results_support_dict_compat_access():
+    """Transitional compat shim per base.py — retained until callers migrate to attrs."""
+    result = GetResult(ids=["a"], documents=["da"], metadatas=[{"w": 1}])
+    assert result["ids"] == ["a"]
+    assert result.get("documents") == ["da"]
+    assert result.get("missing", "default") == "default"
+    assert "ids" in result
+    assert "missing" not in result
+
+
+def test_chroma_collection_query_empty_result_preserves_outer_shape():
+    fake = _FakeCollection(
+        query_response={"ids": [], "documents": [], "metadatas": [], "distances": []}
+    )
+    collection = ChromaCollection(fake)
+
+    result = collection.query(query_texts=["q1", "q2"])
+    assert result.ids == [[], []]
+    assert result.documents == [[], []]
+    assert result.distances == [[], []]
+
+
+def test_chroma_collection_rejects_unknown_where_operator():
+    fake = _FakeCollection()
+    collection = ChromaCollection(fake)
+
+    with pytest.raises(UnsupportedFilterError):
+        collection.query(query_texts=["q"], where={"$regex": "foo"})
+
+
+def test_chroma_collection_delegates_writes():
     fake = _FakeCollection()
     collection = ChromaCollection(fake)
 
     collection.add(documents=["d"], ids=["1"], metadatas=[{"wing": "w"}])
     collection.upsert(documents=["u"], ids=["2"], metadatas=[{"room": "r"}])
-    assert collection.query(query_texts=["q"]) == {"kind": "query"}
-    assert collection.get(where={"wing": "w"}) == {"kind": "get"}
     collection.delete(ids=["1"])
     assert collection.count() == 7
 
-    assert fake.calls == [
-        ("add", {"documents": ["d"], "ids": ["1"], "metadatas": [{"wing": "w"}]}),
-        ("upsert", {"documents": ["u"], "ids": ["2"], "metadatas": [{"room": "r"}]}),
-        ("query", {"query_texts": ["q"]}),
-        ("get", {"where": {"wing": "w"}}),
-        ("delete", {"ids": ["1"]}),
-        ("count", {}),
-    ]
+    kinds = [call[0] for call in fake.calls]
+    assert kinds == ["add", "upsert", "delete", "count"]
+
+
+def test_registry_exposes_chroma_by_default():
+    names = available_backends()
+    assert "chroma" in names
+    assert isinstance(get_backend("chroma"), ChromaBackend)
+
+
+def test_registry_unknown_backend_raises():
+    with pytest.raises(KeyError):
+        get_backend("no-such-backend-exists")
+
+
+def test_resolve_backend_priority_order(tmp_path):
+    from mempalace.backends import resolve_backend_for_palace
+
+    # explicit kwarg wins over everything
+    assert resolve_backend_for_palace(explicit="pg", config_value="lance") == "pg"
+    # config value wins over env / default
+    assert resolve_backend_for_palace(config_value="lance", env_value="qdrant") == "lance"
+    # env wins over default
+    assert resolve_backend_for_palace(env_value="qdrant", default="chroma") == "qdrant"
+    # falls back to default
+    assert resolve_backend_for_palace() == "chroma"
+
+
+def test_chroma_detect_matches_palace_with_chroma_sqlite(tmp_path):
+    (tmp_path / "chroma.sqlite3").write_bytes(b"")
+    assert ChromaBackend.detect(str(tmp_path)) is True
+    assert ChromaBackend.detect(str(tmp_path.parent)) is False
+
+
+def test_query_rejects_missing_input():
+    fake = _FakeCollection()
+    collection = ChromaCollection(fake)
+    with pytest.raises(ValueError):
+        collection.query()
+
+
+def test_query_rejects_both_texts_and_embeddings():
+    fake = _FakeCollection()
+    collection = ChromaCollection(fake)
+    with pytest.raises(ValueError):
+        collection.query(query_texts=["q"], query_embeddings=[[0.1, 0.2]])
+
+
+def test_query_rejects_empty_input_list():
+    fake = _FakeCollection()
+    collection = ChromaCollection(fake)
+    with pytest.raises(ValueError):
+        collection.query(query_texts=[])
+
+
+def test_query_empty_preserves_embeddings_outer_shape_when_requested():
+    fake = _FakeCollection(
+        query_response={"ids": [], "documents": [], "metadatas": [], "distances": []}
+    )
+    collection = ChromaCollection(fake)
+
+    requested = collection.query(query_texts=["q1", "q2"], include=["documents", "embeddings"])
+    assert requested.embeddings == [[], []]
+
+    not_requested = collection.query(query_texts=["q1", "q2"], include=["documents"])
+    assert not_requested.embeddings is None
+
+
+def test_chroma_cache_invalidates_when_db_file_missing(tmp_path):
+    """A palace rebuild that removes chroma.sqlite3 must drop the stale cache.
+
+    Primes backend._clients/_freshness directly with a sentinel rather than
+    opening a real ``PersistentClient``: on Windows the sqlite file handle
+    would still be live and ``Path.unlink`` would raise ``PermissionError``,
+    making the test unable to exercise the branch we care about. The decision
+    logic under test is pure (no chromadb calls before the branch), so a
+    sentinel is sufficient.
+    """
+    backend = ChromaBackend()
+    palace_path = tmp_path / "palace"
+    palace_path.mkdir()
+    db_file = palace_path / "chroma.sqlite3"
+    db_file.write_bytes(b"")  # any file is enough for _db_stat to see it
+    st = db_file.stat()
+
+    sentinel = object()
+    backend._clients[str(palace_path)] = sentinel
+    backend._freshness[str(palace_path)] = (st.st_ino, st.st_mtime)
+
+    # Simulate a rebuild mid-flight: chroma.sqlite3 goes away. Safe to unlink
+    # because nothing in this test is holding an OS handle on the file.
+    db_file.unlink()
+
+    prior_freshness = (st.st_ino, st.st_mtime)
+    new_client = backend._client(str(palace_path))
+    # Cache was replaced (not the sentinel) and freshness reflects the post-
+    # rebuild stat (chromadb re-creates chroma.sqlite3 during PersistentClient
+    # construction; _client re-stats after the constructor so freshness is
+    # not frozen at the pre-rebuild value). The stale cached sentinel would
+    # have served wrong data if returned.
+    assert new_client is not sentinel
+    assert backend._freshness[str(palace_path)] != prior_freshness
+
+
+def test_chroma_cache_picks_up_db_created_after_first_open(tmp_path):
+    """The 0 → nonzero stat transition invalidates a cache built before the DB existed."""
+    backend = ChromaBackend()
+    palace_path = tmp_path / "palace"
+    palace_path.mkdir()
+
+    # Seed an entry in the caches as if a prior _client() call had opened the
+    # palace when chroma.sqlite3 did not exist yet. Freshness (0, 0.0) is the
+    # signal that the DB was absent at cache time.
+    sentinel = object()
+    backend._clients[str(palace_path)] = sentinel
+    backend._freshness[str(palace_path)] = (0, 0.0)
+
+    # The DB file now appears (real chromadb would have created it by now).
+    # Use a real chromadb call so _fix_blob_seq_ids and PersistentClient succeed.
+    import chromadb as _chromadb
+
+    _chromadb.PersistentClient(path=str(palace_path)).get_or_create_collection("seed")
+    assert (palace_path / "chroma.sqlite3").is_file()
+
+    # Next _client() call must detect the 0 → nonzero transition and rebuild.
+    refreshed = backend._client(str(palace_path))
+    assert refreshed is not sentinel
+    assert backend._freshness[str(palace_path)] != (0, 0.0)
+
+
+def test_base_collection_update_default_rejects_mismatched_lengths():
+    """The ABC default update() raises ValueError rather than silently misaligning."""
+    from mempalace.backends.base import BaseCollection
+
+    collection = ChromaCollection(_FakeCollection())
+
+    with pytest.raises(ValueError, match="documents length"):
+        BaseCollection.update(collection, ids=["1", "2"], documents=["only-one"])
+
+    with pytest.raises(ValueError, match="metadatas length"):
+        BaseCollection.update(collection, ids=["1", "2"], metadatas=[{"k": 9}])
+
+
+def test_chroma_backend_accepts_palace_ref_kwarg(tmp_path):
+    palace_path = tmp_path / "palace"
+    backend = ChromaBackend()
+    collection = backend.get_collection(
+        palace=PalaceRef(id=str(palace_path), local_path=str(palace_path)),
+        collection_name="mempalace_drawers",
+        create=True,
+    )
+    assert palace_path.is_dir()
+    assert isinstance(collection, ChromaCollection)
 
 
 def test_chroma_backend_create_false_raises_without_creating_directory(tmp_path):
@@ -140,3 +378,68 @@ def test_fix_blob_seq_ids_noop_without_blobs(tmp_path):
 def test_fix_blob_seq_ids_noop_without_database(tmp_path):
     """No error when palace has no chroma.sqlite3."""
     _fix_blob_seq_ids(str(tmp_path))  # should not raise
+
+
+# ── quarantine_stale_hnsw ─────────────────────────────────────────────────
+
+
+def _make_palace_with_segment(tmp_path, hnsw_mtime, sqlite_mtime):
+    """Helper: build a palace dir with one HNSW segment + sqlite at given mtimes."""
+    palace = tmp_path / "palace"
+    palace.mkdir()
+    (palace / "chroma.sqlite3").write_text("")
+    seg = palace / "abcd-1234-5678"
+    seg.mkdir()
+    (seg / "data_level0.bin").write_text("")
+    os.utime(seg / "data_level0.bin", (hnsw_mtime, hnsw_mtime))
+    os.utime(palace / "chroma.sqlite3", (sqlite_mtime, sqlite_mtime))
+    return palace, seg
+
+
+def test_quarantine_stale_hnsw_renames_drifted_segment(tmp_path):
+    """Segment whose data_level0.bin is 2h older than sqlite gets renamed."""
+    now = 1_700_000_000.0
+    palace, seg = _make_palace_with_segment(tmp_path, hnsw_mtime=now - 7200, sqlite_mtime=now)
+    moved = quarantine_stale_hnsw(str(palace), stale_seconds=3600.0)
+    assert len(moved) == 1
+    assert ".drift-" in moved[0]
+    assert not seg.exists()
+    # the renamed directory still exists and contains the original file
+    renamed = list(palace.iterdir())
+    drift_dirs = [p for p in renamed if ".drift-" in p.name]
+    assert len(drift_dirs) == 1
+    assert (drift_dirs[0] / "data_level0.bin").exists()
+
+
+def test_quarantine_stale_hnsw_leaves_fresh_segment_alone(tmp_path):
+    """Segment with recent mtime vs sqlite is not touched."""
+    now = 1_700_000_000.0
+    palace, seg = _make_palace_with_segment(tmp_path, hnsw_mtime=now - 10, sqlite_mtime=now)
+    moved = quarantine_stale_hnsw(str(palace), stale_seconds=3600.0)
+    assert moved == []
+    assert seg.exists()
+
+
+def test_quarantine_stale_hnsw_no_palace(tmp_path):
+    """Missing palace path or chroma.sqlite3: return [] without raising."""
+    assert quarantine_stale_hnsw(str(tmp_path / "missing")) == []
+    empty = tmp_path / "empty"
+    empty.mkdir()
+    assert quarantine_stale_hnsw(str(empty)) == []
+
+
+def test_quarantine_stale_hnsw_skips_already_quarantined(tmp_path):
+    """Directories already named with ``.drift-`` suffix are never re-renamed."""
+    now = 1_700_000_000.0
+    palace = tmp_path / "palace"
+    palace.mkdir()
+    (palace / "chroma.sqlite3").write_text("")
+    os.utime(palace / "chroma.sqlite3", (now, now))
+    drift = palace / "abcd-1234.drift-20260101-000000"
+    drift.mkdir()
+    (drift / "data_level0.bin").write_text("")
+    os.utime(drift / "data_level0.bin", (now - 99999, now - 99999))
+
+    moved = quarantine_stale_hnsw(str(palace), stale_seconds=3600.0)
+    assert moved == []
+    assert drift.exists()

tests/test_claude_plugin_hook_wrappers.py

@@ -0,0 +1,192 @@
+"""Execution tests for Claude plugin hook wrapper scripts."""
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+PLUGIN_HOOKS_DIR = REPO_ROOT / ".claude-plugin" / "hooks"
+BASH = shutil.which("bash")
+
+pytestmark = pytest.mark.skipif(
+    BASH is None,
+    reason="bash required for Claude plugin hook wrapper tests",
+)
+
+SCRIPT_CASES = [
+    ("mempal-stop-hook.sh", "stop"),
+    ("mempal-precompact-hook.sh", "precompact"),
+]
+
+
+def _shell_path(path: Path) -> str:
+    return path.as_posix()
+
+
+def _write_executable(path: Path, content: str) -> None:
+    path.write_text(content, encoding="utf-8")
+    path.chmod(0o755)
+
+
+def _make_bin_dir(tmp_path: Path, executables: dict[str, str]) -> Path:
+    bin_dir = tmp_path / "bin"
+    bin_dir.mkdir()
+    for name, content in executables.items():
+        _write_executable(bin_dir / name, content)
+    return bin_dir
+
+
+def _capture_stdin_to(output_path: Path) -> str:
+    return (
+        'stdin_payload=""\n'
+        'while IFS= read -r line || [ -n "$line" ]; do\n'
+        '  stdin_payload="${stdin_payload}${line}"\n'
+        "done\n"
+        f'printf \'%s\' "$stdin_payload" > "{_shell_path(output_path)}"\n'
+    )
+
+
+def _run_hook(
+    script_name: str,
+    payload: str,
+    bin_dir: Path,
+) -> subprocess.CompletedProcess[str]:
+    assert BASH is not None
+
+    env = os.environ.copy()
+    env["PATH"] = str(bin_dir)
+
+    return subprocess.run(
+        [BASH, _shell_path(PLUGIN_HOOKS_DIR / script_name)],
+        input=payload,
+        text=True,
+        capture_output=True,
+        cwd=REPO_ROOT,
+        env=env,
+    )
+
+
+@pytest.mark.parametrize(("script_name", "hook_name"), SCRIPT_CASES)
+def test_plugin_hook_wrapper_prefers_mempalace_cli(
+    tmp_path: Path, script_name: str, hook_name: str
+) -> None:
+    args_file = tmp_path / "args.txt"
+    stdin_file = tmp_path / "stdin.json"
+
+    bin_dir = _make_bin_dir(
+        tmp_path,
+        {
+            "mempalace": (
+                "#!/bin/sh\n"
+                f'printf \'%s\' "$*" > "{_shell_path(args_file)}"\n'
+                f"{_capture_stdin_to(stdin_file)}"
+                "printf '{}\\n'\n"
+            ),
+            "python": "#!/bin/sh\nexit 99\n",
+            "python3": "#!/bin/sh\nexit 99\n",
+        },
+    )
+
+    payload = '{"session_id":"abc123"}'
+    result = _run_hook(script_name, payload, bin_dir)
+
+    assert result.returncode == 0
+    assert result.stdout == "{}\n"
+    assert (
+        args_file.read_text(encoding="utf-8")
+        == f"hook run --hook {hook_name} --harness claude-code"
+    )
+    assert stdin_file.read_text(encoding="utf-8") == payload
+
+
+@pytest.mark.parametrize(("script_name", "hook_name"), SCRIPT_CASES)
+@pytest.mark.parametrize("python_name", ["python3", "python"])
+def test_plugin_hook_wrapper_falls_back_to_importable_python(
+    tmp_path: Path, script_name: str, hook_name: str, python_name: str
+) -> None:
+    args_file = tmp_path / "args.txt"
+    stdin_file = tmp_path / "stdin.json"
+
+    python_stub = (
+        "#!/bin/sh\n"
+        'if [ "$1" = "-c" ]; then\n'
+        "  exit 0\n"
+        "fi\n"
+        f'printf \'%s\' "$*" > "{_shell_path(args_file)}"\n'
+        f"{_capture_stdin_to(stdin_file)}"
+        "printf '{}\\n'\n"
+    )
+    bin_dir = _make_bin_dir(tmp_path, {python_name: python_stub})
+
+    payload = '{"session_id":"xyz789"}'
+    result = _run_hook(script_name, payload, bin_dir)
+
+    assert result.returncode == 0
+    assert result.stdout == "{}\n"
+    assert (
+        args_file.read_text(encoding="utf-8")
+        == f"-m mempalace hook run --hook {hook_name} --harness claude-code"
+    )
+    assert stdin_file.read_text(encoding="utf-8") == payload
+
+
+@pytest.mark.parametrize(("script_name", "hook_name"), SCRIPT_CASES)
+def test_plugin_hook_wrapper_errors_cleanly_when_no_runner_exists(
+    tmp_path: Path, script_name: str, hook_name: str
+) -> None:
+    bin_dir = _make_bin_dir(tmp_path, {})
+
+    payload = '{"session_id":"no-runner"}'
+    result = _run_hook(script_name, payload, bin_dir)
+
+    assert result.returncode != 0
+    assert result.stdout == ""
+    assert "could not find a runnable mempalace command or module" in result.stderr
+
+
+@pytest.mark.parametrize(("script_name", "hook_name"), SCRIPT_CASES)
+def test_plugin_hook_wrapper_falls_back_to_python_when_python3_cannot_import(
+    tmp_path: Path, script_name: str, hook_name: str
+) -> None:
+    args_file = tmp_path / "args.txt"
+    stdin_file = tmp_path / "stdin.json"
+    bad_python3_used = tmp_path / "bad_python3_used.txt"
+
+    bin_dir = _make_bin_dir(
+        tmp_path,
+        {
+            "python3": (
+                "#!/bin/sh\n"
+                'if [ "$1" = "-c" ]; then\n'
+                "  exit 1\n"
+                "fi\n"
+                f"printf 'used' > \"{_shell_path(bad_python3_used)}\"\n"
+                "echo 'No module named mempalace' >&2\n"
+                "exit 1\n"
+            ),
+            "python": (
+                "#!/bin/sh\n"
+                'if [ "$1" = "-c" ]; then\n'
+                "  exit 0\n"
+                "fi\n"
+                f'printf \'%s\' "$*" > "{_shell_path(args_file)}"\n'
+                f"{_capture_stdin_to(stdin_file)}"
+                "printf '{}\\n'\n"
+            ),
+        },
+    )
+
+    payload = '{"session_id":"fallback"}'
+    result = _run_hook(script_name, payload, bin_dir)
+
+    assert result.returncode == 0
+    assert result.stdout == "{}\n"
+    assert (
+        args_file.read_text(encoding="utf-8")
+        == f"-m mempalace hook run --hook {hook_name} --harness claude-code"
+    )
+    assert stdin_file.read_text(encoding="utf-8") == payload
+    assert not bad_python3_used.exists()

tests/test_cli.py

@@ -334,9 +334,9 @@ def test_mcp_command_prints_setup_guidance(monkeypatch, capsys):
 
     captured = capsys.readouterr()
     assert "MemPalace MCP quick setup:" in captured.out
-    assert "claude mcp add mempalace -- python -m mempalace.mcp_server" in captured.out
+    assert "claude mcp add mempalace -- mempalace-mcp" in captured.out
     assert "\nOptional custom palace:\n" in captured.out
-    assert "python -m mempalace.mcp_server --palace /path/to/palace" in captured.out
+    assert "mempalace-mcp --palace /path/to/palace" in captured.out
     assert "[--palace /path/to/palace]" not in captured.out
     assert captured.err == ""
 
@@ -349,7 +349,7 @@ def test_mcp_command_uses_custom_palace_path_when_provided(monkeypatch, capsys):
     captured = capsys.readouterr()
     expanded = str(Path("~/tmp/my palace").expanduser())
 
-    assert "python -m mempalace.mcp_server --palace" in captured.out
+    assert "mempalace-mcp --palace" in captured.out
     assert expanded in captured.out
     assert "Optional custom palace:" not in captured.out
     assert "[--palace /path/to/palace]" not in captured.out
@@ -412,12 +412,21 @@ def test_main_compress_dispatches():
 # ── cmd_repair ─────────────────────────────────────────────────────────
 
 
+def _mock_backend_for(col=None, new_col=None):
+    """Build a mock ChromaBackend whose get_collection/create_collection return *col* / *new_col*."""
+    mock_backend = MagicMock()
+    if col is not None:
+        mock_backend.get_collection.return_value = col
+    if new_col is not None:
+        mock_backend.create_collection.return_value = new_col
+    return mock_backend
+
+
 @patch("mempalace.cli.MempalaceConfig")
 def test_cmd_repair_no_palace(mock_config_cls, tmp_path, capsys):
     mock_config_cls.return_value.palace_path = str(tmp_path / "nonexistent")
     args = argparse.Namespace(palace=None)
-    mock_chromadb = MagicMock()
-    with patch.dict("sys.modules", {"chromadb": mock_chromadb}):
+    with patch("mempalace.backends.chroma.ChromaBackend"):
         cmd_repair(args)
     out = capsys.readouterr().out
     assert "No palace found" in out
@@ -429,8 +438,7 @@ def test_cmd_repair_requires_palace_database(mock_config_cls, tmp_path, capsys):
     palace_dir.mkdir()
     mock_config_cls.return_value.palace_path = str(palace_dir)
     args = argparse.Namespace(palace=None)
-    mock_chromadb = MagicMock()
-    with patch.dict("sys.modules", {"chromadb": mock_chromadb}):
+    with patch("mempalace.backends.chroma.ChromaBackend"):
         cmd_repair(args)
     out = capsys.readouterr().out
     assert "No palace database found" in out
@@ -443,11 +451,9 @@ def test_cmd_repair_error_reading(mock_config_cls, tmp_path, capsys):
     (palace_dir / "chroma.sqlite3").write_text("db")
     mock_config_cls.return_value.palace_path = str(palace_dir)
     args = argparse.Namespace(palace=None)
-    mock_chromadb = MagicMock()
-    mock_client = MagicMock()
-    mock_client.get_collection.side_effect = Exception("corrupt db")
-    mock_chromadb.PersistentClient.return_value = mock_client
-    with patch.dict("sys.modules", {"chromadb": mock_chromadb}):
+    mock_backend = MagicMock()
+    mock_backend.get_collection.side_effect = Exception("corrupt db")
+    with patch("mempalace.backends.chroma.ChromaBackend", return_value=mock_backend):
         cmd_repair(args)
     out = capsys.readouterr().out
     assert "Error reading palace" in out
@@ -460,13 +466,10 @@ def test_cmd_repair_zero_drawers(mock_config_cls, tmp_path, capsys):
     (palace_dir / "chroma.sqlite3").write_text("db")
     mock_config_cls.return_value.palace_path = str(palace_dir)
     args = argparse.Namespace(palace=None)
-    mock_chromadb = MagicMock()
     mock_col = MagicMock()
     mock_col.count.return_value = 0
-    mock_client = MagicMock()
-    mock_client.get_collection.return_value = mock_col
-    mock_chromadb.PersistentClient.return_value = mock_client
-    with patch.dict("sys.modules", {"chromadb": mock_chromadb}):
+    mock_backend = _mock_backend_for(col=mock_col)
+    with patch("mempalace.backends.chroma.ChromaBackend", return_value=mock_backend):
         cmd_repair(args)
     out = capsys.readouterr().out
     assert "Nothing to repair" in out
@@ -479,7 +482,6 @@ def test_cmd_repair_success(mock_config_cls, tmp_path, capsys):
     (palace_dir / "chroma.sqlite3").write_text("db")
     mock_config_cls.return_value.palace_path = str(palace_dir)
     args = argparse.Namespace(palace=None, yes=True)
-    mock_chromadb = MagicMock()
     mock_col = MagicMock()
     mock_col.count.return_value = 2
     mock_col.get.return_value = {
@@ -487,12 +489,9 @@ def test_cmd_repair_success(mock_config_cls, tmp_path, capsys):
         "documents": ["doc1", "doc2"],
         "metadatas": [{"wing": "a"}, {"wing": "b"}],
     }
-    mock_client = MagicMock()
-    mock_client.get_collection.return_value = mock_col
     mock_new_col = MagicMock()
-    mock_client.create_collection.return_value = mock_new_col
-    mock_chromadb.PersistentClient.return_value = mock_client
-    with patch.dict("sys.modules", {"chromadb": mock_chromadb}):
+    mock_backend = _mock_backend_for(col=mock_col, new_col=mock_new_col)
+    with patch("mempalace.backends.chroma.ChromaBackend", return_value=mock_backend):
         cmd_repair(args)
     out = capsys.readouterr().out
     assert "Repair complete" in out
@@ -506,20 +505,17 @@ def test_cmd_repair_aborts_without_confirmation(mock_config_cls, tmp_path, capsy
     (palace_dir / "chroma.sqlite3").write_text("db")
     mock_config_cls.return_value.palace_path = str(palace_dir)
     args = argparse.Namespace(palace=None)
-    mock_chromadb = MagicMock()
     mock_col = MagicMock()
     mock_col.count.return_value = 1
-    mock_client = MagicMock()
-    mock_client.get_collection.return_value = mock_col
-    mock_chromadb.PersistentClient.return_value = mock_client
+    mock_backend = _mock_backend_for(col=mock_col)
     with (
-        patch.dict("sys.modules", {"chromadb": mock_chromadb}),
+        patch("mempalace.backends.chroma.ChromaBackend", return_value=mock_backend),
         patch("builtins.input", return_value="n"),
     ):
         cmd_repair(args)
     out = capsys.readouterr().out
     assert "Aborted." in out
-    mock_client.create_collection.assert_not_called()
+    mock_backend.create_collection.assert_not_called()
 
 
 # ── cmd_compress ───────────────────────────────────────────────────────
@@ -529,10 +525,10 @@ def test_cmd_repair_aborts_without_confirmation(mock_config_cls, tmp_path, capsy
 def test_cmd_compress_no_palace(mock_config_cls, capsys):
     mock_config_cls.return_value.palace_path = "/fake/palace"
     args = argparse.Namespace(palace=None, wing=None, dry_run=False, config=None)
-    mock_chromadb = MagicMock()
-    mock_chromadb.PersistentClient.side_effect = Exception("no palace")
+    mock_backend = MagicMock()
+    mock_backend.get_collection.side_effect = Exception("no palace")
     with (
-        patch.dict("sys.modules", {"chromadb": mock_chromadb}),
+        patch("mempalace.backends.chroma.ChromaBackend", return_value=mock_backend),
         pytest.raises(SystemExit),
     ):
         cmd_compress(args)
@@ -542,13 +538,10 @@ def test_cmd_compress_no_palace(mock_config_cls, capsys):
 def test_cmd_compress_no_drawers(mock_config_cls, capsys):
     mock_config_cls.return_value.palace_path = "/fake/palace"
     args = argparse.Namespace(palace=None, wing="mywing", dry_run=False, config=None)
-    mock_chromadb = MagicMock()
     mock_col = MagicMock()
     mock_col.get.return_value = {"documents": [], "metadatas": [], "ids": []}
-    mock_client = MagicMock()
-    mock_client.get_collection.return_value = mock_col
-    mock_chromadb.PersistentClient.return_value = mock_client
-    with patch.dict("sys.modules", {"chromadb": mock_chromadb}):
+    mock_backend = _mock_backend_for(col=mock_col)
+    with patch("mempalace.backends.chroma.ChromaBackend", return_value=mock_backend):
         cmd_compress(args)
     out = capsys.readouterr().out
     assert "No drawers found" in out
@@ -567,7 +560,6 @@ def _make_mock_dialect_module(dialect_instance):
 def test_cmd_compress_dry_run(mock_config_cls, capsys):
     mock_config_cls.return_value.palace_path = "/fake/palace"
     args = argparse.Namespace(palace=None, wing=None, dry_run=True, config=None)
-    mock_chromadb = MagicMock()
     mock_col = MagicMock()
     mock_col.get.side_effect = [
         {
@@ -577,9 +569,7 @@ def test_cmd_compress_dry_run(mock_config_cls, capsys):
         },
         {"documents": [], "metadatas": [], "ids": []},
     ]
-    mock_client = MagicMock()
-    mock_client.get_collection.return_value = mock_col
-    mock_chromadb.PersistentClient.return_value = mock_client
+    mock_backend = _mock_backend_for(col=mock_col)
 
     mock_dialect = MagicMock()
     mock_dialect.compress.return_value = "compressed"
@@ -593,12 +583,9 @@ def test_cmd_compress_dry_run(mock_config_cls, capsys):
     }
     mock_dialect_mod = _make_mock_dialect_module(mock_dialect)
 
-    with patch.dict(
-        "sys.modules",
-        {
-            "chromadb": mock_chromadb,
-            "mempalace.dialect": mock_dialect_mod,
-        },
+    with (
+        patch("mempalace.backends.chroma.ChromaBackend", return_value=mock_backend),
+        patch.dict("sys.modules", {"mempalace.dialect": mock_dialect_mod}),
     ):
         cmd_compress(args)
     out = capsys.readouterr().out
@@ -613,22 +600,16 @@ def test_cmd_compress_with_config(mock_config_cls, tmp_path, capsys):
     config_file = tmp_path / "entities.json"
     config_file.write_text('{"people": [], "projects": []}')
     args = argparse.Namespace(palace=None, wing=None, dry_run=True, config=str(config_file))
-    mock_chromadb = MagicMock()
     mock_col = MagicMock()
     mock_col.get.return_value = {"documents": [], "metadatas": [], "ids": []}
-    mock_client = MagicMock()
-    mock_client.get_collection.return_value = mock_col
-    mock_chromadb.PersistentClient.return_value = mock_client
+    mock_backend = _mock_backend_for(col=mock_col)
 
     mock_dialect = MagicMock()
     mock_dialect_mod = _make_mock_dialect_module(mock_dialect)
 
-    with patch.dict(
-        "sys.modules",
-        {
-            "chromadb": mock_chromadb,
-            "mempalace.dialect": mock_dialect_mod,
-        },
+    with (
+        patch("mempalace.backends.chroma.ChromaBackend", return_value=mock_backend),
+        patch.dict("sys.modules", {"mempalace.dialect": mock_dialect_mod}),
     ):
         cmd_compress(args)
     out = capsys.readouterr().out
@@ -640,7 +621,6 @@ def test_cmd_compress_stores_results(mock_config_cls, capsys):
     """Non-dry-run compress stores to mempalace_compressed collection."""
     mock_config_cls.return_value.palace_path = "/fake/palace"
     args = argparse.Namespace(palace=None, wing=None, dry_run=False, config=None)
-    mock_chromadb = MagicMock()
     mock_col = MagicMock()
     mock_col.get.side_effect = [
         {
@@ -650,11 +630,10 @@ def test_cmd_compress_stores_results(mock_config_cls, capsys):
         },
         {"documents": [], "metadatas": [], "ids": []},
     ]
-    mock_client = MagicMock()
-    mock_client.get_collection.return_value = mock_col
     mock_comp_col = MagicMock()
-    mock_client.get_or_create_collection.return_value = mock_comp_col
-    mock_chromadb.PersistentClient.return_value = mock_client
+    mock_backend = MagicMock()
+    mock_backend.get_collection.return_value = mock_col
+    mock_backend.get_or_create_collection.return_value = mock_comp_col
 
     mock_dialect = MagicMock()
     mock_dialect.compress.return_value = "compressed"
@@ -668,12 +647,9 @@ def test_cmd_compress_stores_results(mock_config_cls, capsys):
     }
     mock_dialect_mod = _make_mock_dialect_module(mock_dialect)
 
-    with patch.dict(
-        "sys.modules",
-        {
-            "chromadb": mock_chromadb,
-            "mempalace.dialect": mock_dialect_mod,
-        },
+    with (
+        patch("mempalace.backends.chroma.ChromaBackend", return_value=mock_backend),
+        patch.dict("sys.modules", {"mempalace.dialect": mock_dialect_mod}),
     ):
         cmd_compress(args)
     out = capsys.readouterr().out

tests/test_config.py

@@ -3,7 +3,7 @@ import json
 import tempfile
 
 import pytest
-from mempalace.config import MempalaceConfig, sanitize_name
+from mempalace.config import MempalaceConfig, sanitize_kg_value, sanitize_name
 
 
 def test_default_config():
@@ -21,10 +21,62 @@ def test_config_from_file():
 
 
 def test_env_override():
-    os.environ["MEMPALACE_PALACE_PATH"] = "/env/palace"
-    cfg = MempalaceConfig(config_dir=tempfile.mkdtemp())
-    assert cfg.palace_path == "/env/palace"
-    del os.environ["MEMPALACE_PALACE_PATH"]
+    raw = "/env/palace"
+    os.environ["MEMPALACE_PALACE_PATH"] = raw
+    try:
+        cfg = MempalaceConfig(config_dir=tempfile.mkdtemp())
+        # palace_path normalizes with abspath + expanduser to match the
+        # --palace CLI code path. On Unix that's a no-op for "/env/palace";
+        # on Windows abspath prepends the current drive letter.
+        assert cfg.palace_path == os.path.abspath(os.path.expanduser(raw))
+    finally:
+        del os.environ["MEMPALACE_PALACE_PATH"]
+
+
+def test_env_path_expanduser():
+    # Tilde must be expanded to match the --palace CLI code path. We don't
+    # assert "~" is absent from the final string because Windows 8.3 short
+    # paths (e.g. C:\Users\RUNNER~1\...) legitimately contain tildes — the
+    # equality check is authoritative.
+    raw = os.path.join("~", "mempalace-test")
+    os.environ["MEMPALACE_PALACE_PATH"] = raw
+    try:
+        cfg = MempalaceConfig(config_dir=tempfile.mkdtemp())
+        assert cfg.palace_path == os.path.abspath(os.path.expanduser(raw))
+        assert cfg.palace_path.endswith("mempalace-test")
+    finally:
+        del os.environ["MEMPALACE_PALACE_PATH"]
+
+
+def test_env_path_abspath_collapses_traversal():
+    # Build a raw path with a .. segment using the platform separator so
+    # the assertion is portable (Windows uses \, POSIX uses /).
+    raw = os.path.join(tempfile.gettempdir(), "palace", "..", "mempalace-test")
+    expected = os.path.abspath(os.path.expanduser(raw))
+    os.environ["MEMPALACE_PALACE_PATH"] = raw
+    try:
+        cfg = MempalaceConfig(config_dir=tempfile.mkdtemp())
+        # .. segments must be collapsed, not preserved literally.
+        assert ".." not in cfg.palace_path
+        assert cfg.palace_path == expected
+    finally:
+        del os.environ["MEMPALACE_PALACE_PATH"]
+
+
+def test_env_path_legacy_alias_normalized():
+    # Legacy MEMPAL_PALACE_PATH gets the same normalization treatment as
+    # MEMPALACE_PALACE_PATH. We don't assert "~" is absent from the final
+    # string because Windows 8.3 short paths (e.g. C:\Users\RUNNER~1\...)
+    # legitimately contain tildes — the equality check below is authoritative.
+    os.environ.pop("MEMPALACE_PALACE_PATH", None)
+    raw = os.path.join("~", "legacy-alias", "..", "mempalace-test")
+    os.environ["MEMPAL_PALACE_PATH"] = raw
+    try:
+        cfg = MempalaceConfig(config_dir=tempfile.mkdtemp())
+        assert ".." not in cfg.palace_path
+        assert cfg.palace_path == os.path.abspath(os.path.expanduser(raw))
+    finally:
+        del os.environ["MEMPAL_PALACE_PATH"]
 
 
 def test_init():
@@ -66,3 +118,54 @@ def test_sanitize_name_rejects_path_traversal():
 def test_sanitize_name_rejects_empty():
     with pytest.raises(ValueError):
         sanitize_name("")
+
+
+# --- sanitize_kg_value ---
+
+
+def test_kg_value_accepts_commas():
+    assert sanitize_kg_value("Alice, Bob, and Carol") == "Alice, Bob, and Carol"
+
+
+def test_kg_value_accepts_colons():
+    assert sanitize_kg_value("role: engineer") == "role: engineer"
+
+
+def test_kg_value_accepts_parentheses():
+    assert sanitize_kg_value("Python (programming)") == "Python (programming)"
+
+
+def test_kg_value_accepts_slashes():
+    assert sanitize_kg_value("owner/repo") == "owner/repo"
+
+
+def test_kg_value_accepts_hash():
+    assert sanitize_kg_value("issue #123") == "issue #123"
+
+
+def test_kg_value_accepts_unicode():
+    assert sanitize_kg_value("Jānis Bērziņš") == "Jānis Bērziņš"
+
+
+def test_kg_value_strips_whitespace():
+    assert sanitize_kg_value("  hello  ") == "hello"
+
+
+def test_kg_value_rejects_empty():
+    with pytest.raises(ValueError):
+        sanitize_kg_value("")
+
+
+def test_kg_value_rejects_whitespace_only():
+    with pytest.raises(ValueError):
+        sanitize_kg_value("   ")
+
+
+def test_kg_value_rejects_null_bytes():
+    with pytest.raises(ValueError):
+        sanitize_kg_value("hello\x00world")
+
+
+def test_kg_value_rejects_over_length():
+    with pytest.raises(ValueError):
+        sanitize_kg_value("a" * 129)

tests/test_config_extra.py

@@ -63,10 +63,14 @@ def test_save_people_map(tmp_path):
 def test_env_mempal_palace_path(tmp_path):
     """MEMPAL_PALACE_PATH (legacy) should also work."""
     os.environ.pop("MEMPALACE_PALACE_PATH", None)
-    os.environ["MEMPAL_PALACE_PATH"] = "/legacy/path"
+    raw = "/legacy/path"
+    os.environ["MEMPAL_PALACE_PATH"] = raw
     try:
         cfg = MempalaceConfig(config_dir=str(tmp_path))
-        assert cfg.palace_path == "/legacy/path"
+        # palace_path is normalized via abspath + expanduser — compare
+        # against the normalized form so the test is portable between
+        # POSIX (no-op) and Windows (prepends current drive letter).
+        assert cfg.palace_path == os.path.abspath(os.path.expanduser(raw))
     finally:
         del os.environ["MEMPAL_PALACE_PATH"]
 

tests/test_convo_miner_size_cap.py

@@ -0,0 +1,31 @@
+"""TDD: convo_miner.py must not silently drop transcripts larger than 10 MB.
+
+Mirrors the miner.py fix shipped in the same PR family (see
+test_miner_jsonl_visibility.py). Long Claude Code sessions, ChatGPT
+exports, and multi-year Slack dumps routinely exceed 10 MB. The cap
+silently `continue`s past them at convo_miner.py:~289, same silent-drop
+pattern as the project miner's.
+
+Written BEFORE the fix.
+"""
+
+from mempalace.convo_miner import MAX_FILE_SIZE
+
+
+class TestConvoMinerSizeCap:
+    def test_max_file_size_accommodates_long_transcripts(self):
+        """The cap must be well above any realistic transcript.
+
+        Long sessions and lifetime exports exceed 10 MB. The cap exists
+        as a sanity rail against pathological binaries, not as a limit
+        on legitimate text — downstream chunking means source size does
+        not matter for storage or embedding cost.
+        """
+        assert MAX_FILE_SIZE >= 100 * 1024 * 1024, (
+            f"convo_miner.MAX_FILE_SIZE is {MAX_FILE_SIZE} bytes "
+            f"({MAX_FILE_SIZE / 1024 / 1024:.0f} MB). Same silent-drop "
+            "bug as miner.py's old 10 MB cap — long transcripts get "
+            "filtered out at convo_miner.py:~289 with `continue`. "
+            "Raise to at least 100 MB (match miner.py at 500 MB for "
+            "consistency across both miners)."
+        )