jason/mempalace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(install): recommend uv as the package manager

Browse Source 
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.
This commit is contained in:
Igor Lins e Silva
2026-05-08 01:37:46 -03:00
parent 25bfd37644
commit c35686c9e1
18 changed files with 99 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude-plugin/README.md
+1 -1
View File
@@ -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
+2 -2
View File
@@ -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
+3 -3
View File
@@ -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
+1
View File
@@ -0,0 +1 @@
3.12
CLAUDE.md
+6 -6
View File
@@ -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
+9 -5
View File
@@ -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
+8 -3
View File
@@ -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
+3 -3
View File
@@ -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
python benchmarks/longmemeval_bench.py /tmp/longmemeval-data/longmemeval_s_cleaned.json \
uv pip install fastembed # or: pip install fastembed
uv run python benchmarks/longmemeval_bench.py /tmp/longmemeval-data/longmemeval_s_cleaned.json \
--mode raw --embed-model bge-large
```
benchmarks/HYBRID_MODE.md
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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
+13 -6
View File
@@ -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
python3 -m venv .venv
# Create the venv and install MemPalace + dependencies in editable mode
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
+2 -2
View File
@@ -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
+18 -9
View File
@@ -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,
report the installed version and skip to Step 4.
Run `mempalace --version` to see if the CLI is already on the user's PATH.
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`
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
If the install command fails, try these fallbacks in order:
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
+1 -1
View File
@@ -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
+13 -5
View File
@@ -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
python3 -m venv .venv
# Create the venv and install MemPalace + dependencies
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
+6 -3
View File
@@ -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
+1 -1
View File
@@ -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
+10 -5
View File
@@ -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`