docs(install): recommend uv as the package manager

End-user installs now lead with `uv tool install mempalace`, with
`pip install mempalace` kept as a fallback. Dev/contributor docs lead
with `uv sync --extra dev` and `uv run` for tests/benchmarks/lint, with
the equivalent pip recipe kept inline. The shipped `/mempalace:init`
skill instructions (mempalace/instructions/init.md) try `uv tool install`
first when uv is on PATH, then fall back through the pip variants.

Adds a .python-version pin at 3.12 because the lockfile's
onnxruntime==1.24.3 only ships wheels for Python >=3.11; without the
pin, `uv sync` on a host where uv prefers 3.10 fails with no source
distribution available, which would make the documented command a
footgun. pyproject's `requires-python = ">=3.9"` is unchanged — pip
users on 3.9/3.10 are unaffected.

Files updated: README.md, CONTRIBUTING.md, CLAUDE.md, the gemini-cli
guide and example, the .claude-plugin / .codex-plugin READMEs, the
mempalace SKILL, the openclaw SKILL, tools/save.md, the three
benchmarks docs, and the corresponding website mirrors.

.claude-plugin/README.md

@@ -23,7 +23,7 @@ claude plugin add /path/to/mempalace
 
 ## Post-Install Setup
 
-After installing the plugin, run the init command to complete setup (pip install, MCP configuration, etc.):
+After installing the plugin, run the init command to complete setup (installs the `mempalace` package via `uv tool` or `pip`, configures MCP, etc.):
 
 ```
 /mempalace:init

.claude-plugin/skills/mempalace/SKILL.md

@@ -16,10 +16,10 @@ Ensure `mempalace` is installed:
 mempalace --version
 ```
 
-If not installed:
+If not installed (uv recommended):
 
 ```bash
-pip install mempalace
+uv tool install mempalace   # or: pip install mempalace
 ```
 
 ## Usage

.codex-plugin/README.md

@@ -6,7 +6,7 @@ Give your AI a persistent memory -- mine projects and conversations into a searc
 
 - Python 3.9+
 - Codex CLI installed and configured
-- `pip install mempalace`
+- `uv tool install mempalace` (recommended) or `pip install mempalace`
 
 ## Installation
 
@@ -39,10 +39,10 @@ git clone https://github.com/MemPalace/mempalace.git
 cd mempalace
 ```
 
-2. Install the Python package:
+2. Install the Python package (uv recommended):
 
 ```bash
-pip install -e .
+uv sync   # or: pip install -e .
 ```
 
 3. The `.codex-plugin` directory is already in the repo root. Codex CLI will detect it automatically when you run Codex from inside the repository.

.python-version

@@ -0,0 +1 @@
+3.12

CLAUDE.md

@@ -36,26 +36,26 @@ We do not accept summarization of user content, cloud storage/sync features, tel
 ## Setup
 
 ```bash
-pip install -e ".[dev]"
+uv sync --extra dev   # recommended; or: pip install -e ".[dev]"
 ```
 
 ## Commands
 
 ```bash
 # Run tests
-python -m pytest tests/ -v --ignore=tests/benchmarks
+uv run pytest tests/ -v --ignore=tests/benchmarks
 
 # Run tests with coverage
-python -m pytest tests/ -v --ignore=tests/benchmarks --cov=mempalace --cov-report=term-missing
+uv run pytest tests/ -v --ignore=tests/benchmarks --cov=mempalace --cov-report=term-missing
 
 # Lint
-ruff check .
+uv run ruff check .
 
 # Format
-ruff format .
+uv run ruff format .
 
 # Format check (CI mode)
-ruff format --check .
+uv run ruff format --check .
 ```
 
 ## Project Structure

CONTRIBUTING.md

@@ -10,13 +10,17 @@ git clone https://github.com/<your-username>/mempalace.git
 cd mempalace
 git remote add upstream https://github.com/MemPalace/mempalace.git
 
-pip install -e ".[dev]"    # installs with dev dependencies (pytest, build, twine)
+# Recommended: uv (https://docs.astral.sh/uv/) handles the venv for you
+uv sync --extra dev
+
+# Or with pip in your own venv:
+# pip install -e ".[dev]"
 ```
 
 ## Running Tests
 
 ```bash
-pytest tests/ -v
+uv run pytest tests/ -v
 ```
 
 All tests must pass before submitting a PR. Tests should run without API keys or network access.
@@ -25,10 +29,10 @@ All tests must pass before submitting a PR. Tests should run without API keys or
 
 ```bash
 # Quick test (20 questions, ~30 seconds)
-python benchmarks/longmemeval_bench.py /path/to/longmemeval_s_cleaned.json --limit 20
+uv run python benchmarks/longmemeval_bench.py /path/to/longmemeval_s_cleaned.json --limit 20
 
 # Full benchmark (500 questions, ~5 minutes)
-python benchmarks/longmemeval_bench.py /path/to/longmemeval_s_cleaned.json
+uv run python benchmarks/longmemeval_bench.py /path/to/longmemeval_s_cleaned.json
 ```
 
 See [benchmarks/README.md](benchmarks/README.md) for data download instructions and reproduction guide.
@@ -49,7 +53,7 @@ assets/             ← logo + brand
 1. Fork the repo and create a feature branch: `git checkout -b feat/my-thing`
 2. Write your code
 3. Add or update tests if applicable
-4. Run `pytest tests/ -v` — everything must pass
+4. Run `uv run pytest tests/ -v` — everything must pass
 5. Commit with a clear message following [conventional commits](https://www.conventionalcommits.org/):
    - `feat: add Notion export format`
    - `fix: handle empty transcript files`

README.md

@@ -49,11 +49,16 @@ Architecture, concepts, and mining flows:
 
 ## Install
 
+We recommend [`uv`](https://docs.astral.sh/uv/) — `uv tool install` puts
+the `mempalace` CLI in an isolated environment on your PATH:
+
 ```bash
-pip install mempalace
+uv tool install mempalace
 mempalace init ~/projects/myapp
 ```
 
+If you prefer pip, `pip install mempalace` still works.
+
 ## Quickstart
 
 ```bash
@@ -120,9 +125,9 @@ own research page for their published numbers.
 ```bash
 git clone https://github.com/MemPalace/mempalace.git
 cd mempalace
-pip install -e ".[dev]"
+uv sync --extra dev   # or: pip install -e ".[dev]"
 # see benchmarks/README.md for dataset download commands
-python benchmarks/longmemeval_bench.py /path/to/longmemeval_s_cleaned.json
+uv run python benchmarks/longmemeval_bench.py /path/to/longmemeval_s_cleaned.json
 ```
 
 ---

benchmarks/BENCHMARKS.md

@@ -344,7 +344,7 @@ The palace classifies each question into one of 5 halls. Pass 1 searches only wi
 ```bash
 git clone https://github.com/MemPalace/mempalace.git
 cd mempalace
-pip install -e ".[dev]"
+uv sync --extra dev   # or: 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
@@ -724,8 +724,8 @@ python benchmarks/longmemeval_bench.py /tmp/longmemeval-data/longmemeval_s_clean
 The question: how much of the 96.6% → 99.4% improvement is the heuristics, and how much would come from just using a better embedding model?
 
 ```bash
-pip install fastembed
+uv pip install fastembed   # or: pip install fastembed
-python benchmarks/longmemeval_bench.py /tmp/longmemeval-data/longmemeval_s_cleaned.json \
+uv run python benchmarks/longmemeval_bench.py /tmp/longmemeval-data/longmemeval_s_cleaned.json \
   --mode raw --embed-model bge-large
 ```
 

benchmarks/HYBRID_MODE.md

@@ -198,7 +198,7 @@ python benchmarks/longmemeval_bench.py data/longmemeval_s_cleaned.json --mode hy
 # Setup
 git clone https://github.com/MemPalace/mempalace.git
 cd mempalace
-pip install -e ".[dev]"
+uv sync --extra dev   # or: pip install -e ".[dev]"
 
 # Download data
 mkdir -p /tmp/longmemeval-data

benchmarks/README.md

@@ -7,7 +7,7 @@ Run the exact same benchmarks we report. Clone, install, run.
 ```bash
 git clone https://github.com/MemPalace/mempalace.git
 cd mempalace
-pip install -e ".[dev]"
+uv sync --extra dev   # or: pip install -e ".[dev]"
 ```
 
 ## Benchmark 1: LongMemEval (500 questions)

examples/gemini_cli_setup.md

@@ -9,17 +9,24 @@ This guide explains how to set up MemPalace as a permanent memory for the [Gemin
 
 ## 1. Installation
 
-On many Linux systems, installing Python packages globally is restricted. We recommend using a local virtual environment within the MemPalace directory.
+On many Linux systems, installing Python packages globally is restricted. We
+recommend [`uv`](https://docs.astral.sh/uv/), which creates and manages a
+local virtual environment for you.
 
 ```bash
 # Clone the repository (if you haven't already)
 git clone https://github.com/MemPalace/mempalace.git
 cd mempalace
 
-# Create a virtual environment
+# Create the venv and install MemPalace + dependencies in editable mode
-python3 -m venv .venv
+uv sync
+```
 
-# Install dependencies and MemPalace in editable mode
+This produces a `.venv/` directory inside the repo with everything installed.
+If you prefer plain pip:
+
+```bash
+python3 -m venv .venv
 .venv/bin/pip install -e .
 ```
 
@@ -29,7 +36,7 @@ Set up your "Palace" (the database) and configure your identity.
 
 ```bash
 # Initialize the palace in the current directory
-.venv/bin/python3 -m mempalace init .
+uv run python -m mempalace init .
 ```
 
 ### Identity and Wings (Optional but Recommended)
@@ -86,7 +93,7 @@ Once connected, Gemini CLI will automatically:
 ### Manual Mining
 If you want the AI to learn from your existing code or docs immediately, run the "mine" command:
 ```bash
-.venv/bin/python3 -m mempalace mine /path/to/your/project
+uv run python -m mempalace mine /path/to/your/project
 ```
 
 ### Verification

integrations/openclaw/SKILL.md

@@ -102,10 +102,10 @@ You have access to a local memory palace via MCP tools. The palace stores verbat
 
 ## Setup
 
-Install MemPalace and populate the palace:
+Install MemPalace and populate the palace (uv recommended):
 
 ```bash
-pip install mempalace
+uv tool install mempalace   # or: pip install mempalace
 mempalace init ~/my-convos
 mempalace mine ~/my-convos
 ```

mempalace/instructions/init.md

@@ -11,27 +11,36 @@ tell the user they need Python 3.9+ installed and stop.
 
 ## Step 2: Check if mempalace is already installed
 
-Run `pip show mempalace` to see if the package is already present. If it is,
+Run `mempalace --version` to see if the CLI is already on the user's PATH.
-report the installed version and skip to Step 4.
+If it succeeds, report the installed version and skip to Step 4.
+
+If that fails, fall back to `pip show mempalace` (and `uv tool list` if `uv`
+is available) to detect an existing install. If found, report it and skip
+to Step 4.
 
 ## Step 3: Install mempalace
 
-Run `pip install mempalace`.
+Prefer [`uv`](https://docs.astral.sh/uv/) — it isolates the CLI from system
+Python and avoids most environment-related failures:
 
-### Error handling -- pip failures
+1. If `uv` is on PATH (`uv --version`), run `uv tool install mempalace`.
+2. Otherwise run `pip install mempalace`.
 
-If `pip install mempalace` fails, try these fallbacks in order:
+### Error handling -- install failures
 
-1. Try `pip3 install mempalace`
+If the install command fails, try these fallbacks in order:
-2. Try `python -m pip install mempalace` (or `python3 -m pip install mempalace`)
+
-3. If the error mentions missing build tools or compilation failures (commonly
+1. If `uv tool install` failed, try `pip install mempalace` (or vice versa).
+2. Try `pip3 install mempalace`.
+3. Try `python -m pip install mempalace` (or `python3 -m pip install mempalace`).
+4. If the error mentions missing build tools or compilation failures (commonly
    from chromadb or its native dependencies):
    - On Linux/macOS: suggest `sudo apt-get install build-essential python3-dev`
      (Debian/Ubuntu) or `xcode-select --install` (macOS)
    - On Windows: suggest installing Microsoft C++ Build Tools from
      https://visualstudio.microsoft.com/visual-cpp-build-tools/
    - Then retry the install command
-4. If all attempts fail, report the error clearly and stop.
+5. If all attempts fail, report the error clearly and stop.
 
 ## Step 4: Ask for project directory
 

tools/save.md

@@ -23,4 +23,4 @@ Behavior:
    `--wing my_research`).
 4. Report back: how many drawers were filed, into which wing/room.
 
-Requires `mempalace` to be installed (`pip install mempalace`).
+Requires `mempalace` to be installed (`uv tool install mempalace` recommended, or `pip install mempalace`).

website/guide/gemini-cli.md

@@ -9,22 +9,30 @@ MemPalace works natively with [Gemini CLI](https://github.com/google/gemini-cli)
 
 ## Installation
 
+We recommend [`uv`](https://docs.astral.sh/uv/) — it creates and manages the
+virtual environment for you:
+
 ```bash
 # Clone the repository
 git clone https://github.com/MemPalace/mempalace.git
 cd mempalace
 
-# Create a virtual environment
+# Create the venv and install MemPalace + dependencies
-python3 -m venv .venv
+uv sync
+```
 
-# Install dependencies
+This produces a `.venv/` directory with the project installed in editable
+mode. If you prefer plain pip, the equivalent is:
+
+```bash
+python3 -m venv .venv
 .venv/bin/pip install -e .
 ```
 
 ## Initialize the Palace
 
 ```bash
-.venv/bin/python3 -m mempalace init .
+uv run python -m mempalace init .
 ```
 
 ### Identity and Project Configuration (Optional)
@@ -88,7 +96,7 @@ Once connected, Gemini CLI will automatically:
 
 Mine existing code or docs:
 ```bash
-.venv/bin/python3 -m mempalace mine /path/to/your/project
+uv run python -m mempalace mine /path/to/your/project
 ```
 
 ### Verification

website/guide/getting-started.md

@@ -2,12 +2,15 @@
 
 ## Installation
 
-Install MemPalace from PyPI:
+We recommend [`uv`](https://docs.astral.sh/uv/) — `uv tool install` puts
+the `mempalace` CLI in an isolated environment on your PATH:
 
 ```bash
-pip install mempalace
+uv tool install mempalace
 ```
 
+If you prefer pip, `pip install mempalace` still works.
+
 ::: danger Security Warning
 The domain `mempalace.tech` is a **brand-squatting site** not affiliated with this project. It is known to run ad-redirects and potential malware. The official MemPalace distribution is only available via this [GitHub repository](https://github.com/MemPalace/mempalace) and [PyPI](https://pypi.org/project/mempalace/). Never install binaries or scripts from unofficial domains.
 :::
@@ -25,7 +28,7 @@ No API key required for the core local workflow. After installation, the main st
 ```bash
 git clone https://github.com/MemPalace/mempalace.git
 cd mempalace
-pip install -e ".[dev]"
+uv sync --extra dev   # or: pip install -e ".[dev]"
 ```
 
 ## Quick Start

website/reference/benchmarks.md

@@ -113,7 +113,7 @@ Every benchmark runs deterministically from this repository.
 ```bash
 git clone https://github.com/MemPalace/mempalace.git
 cd mempalace
-pip install -e ".[dev]"
+uv sync --extra dev   # or: pip install -e ".[dev]"
 
 # LongMemEval — raw (96.6%)
 curl -fsSL -o /tmp/longmemeval_s_cleaned.json \

website/reference/contributing.md

@@ -7,13 +7,18 @@ PRs welcome. MemPalace is open source and we welcome contributions of all sizes
 ```bash
 git clone https://github.com/MemPalace/mempalace.git
 cd mempalace
-pip install -e ".[dev]"
+
+# Recommended: uv (https://docs.astral.sh/uv/) manages the venv for you
+uv sync --extra dev
+
+# Or with pip in your own venv:
+# pip install -e ".[dev]"
 ```
 
 ## Running Tests
 
 ```bash
-pytest tests/ -v
+uv run pytest tests/ -v
 ```
 
 All tests must pass before submitting a PR. Tests should run without API keys or network access.
@@ -22,10 +27,10 @@ All tests must pass before submitting a PR. Tests should run without API keys or
 
 ```bash
 # Quick test (20 questions, ~30 seconds)
-python benchmarks/longmemeval_bench.py /path/to/longmemeval_s_cleaned.json --limit 20
+uv run python benchmarks/longmemeval_bench.py /path/to/longmemeval_s_cleaned.json --limit 20
 
 # Full benchmark (500 questions, ~5 minutes)
-python benchmarks/longmemeval_bench.py /path/to/longmemeval_s_cleaned.json
+uv run python benchmarks/longmemeval_bench.py /path/to/longmemeval_s_cleaned.json
 ```
 
 See [Benchmarks](/reference/benchmarks) for data download instructions.
@@ -35,7 +40,7 @@ See [Benchmarks](/reference/benchmarks) for data download instructions.
 1. Fork the repo and create a feature branch: `git checkout -b feat/my-thing`
 2. Write your code
 3. Add or update tests if applicable
-4. Run `pytest tests/ -v` — everything must pass
+4. Run `uv run pytest tests/ -v` — everything must pass
 5. Commit with clear [conventional commits](https://www.conventionalcommits.org/):
    - `feat: add Notion export format`
    - `fix: handle empty transcript files`