Merge pull request #1414 from MemPalace/chore/uv-and-3.3.4-housekeeping
chore: housekeeping — sync 3.3.4 version + recommend uv for installs
This commit is contained in:
Igor Lins e Silva
@@ -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
|
||||
|
||||
@@ -9,7 +9,7 @@
|
||||
"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.3.3",
|
||||
"version": "3.3.4",
|
||||
"author": {
|
||||
"name": "milla-jovovich"
|
||||
}
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "mempalace",
|
||||
"version": "3.3.3",
|
||||
"version": "3.3.4",
|
||||
"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"
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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,12 +39,17 @@ git clone https://github.com/MemPalace/mempalace.git
|
||||
cd mempalace
|
||||
```
|
||||
|
||||
2. Install the Python package:
|
||||
2. Install the Python package so the `mempalace-mcp` script lands on
|
||||
your PATH (the bundled `plugin.json` invokes it by bare name):
|
||||
|
||||
```bash
|
||||
pip install -e .
|
||||
uv tool install --editable . # or: pip install -e .
|
||||
```
|
||||
|
||||
Plain `uv sync` is **not** enough here — it installs the scripts into
|
||||
`.venv/bin/`, which Codex will not find unless you activate the venv
|
||||
before launching Codex.
|
||||
|
||||
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.
|
||||
|
||||
4. Initialize your palace:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "mempalace",
|
||||
"version": "3.3.3",
|
||||
"version": "3.3.4",
|
||||
"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"
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
3.12
|
||||
@@ -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
|
||||
|
||||
+9
-5
@@ -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`
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
---
|
||||
@@ -185,7 +190,7 @@ PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||
MIT — see [LICENSE](LICENSE).
|
||||
|
||||
<!-- Link Definitions -->
|
||||
[version-shield]: https://img.shields.io/badge/version-3.3.3-4dc9f6?style=flat-square&labelColor=0a0e14
|
||||
[version-shield]: https://img.shields.io/badge/version-3.3.4-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/
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
@@ -11,27 +11,39 @@ 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`. If it succeeds, the CLI is on PATH — report
|
||||
the installed version and skip to Step 4.
|
||||
|
||||
If `mempalace --version` fails, **do not** skip to Step 4 just because
|
||||
`pip show mempalace` or `uv tool list` reports the package as installed:
|
||||
the package may live inside a venv that isn't activated, in which case
|
||||
Step 5 (`mempalace init ...`) will fail with `command not found`. Treat
|
||||
that case as not-installed and continue to Step 3, which will (re)install
|
||||
into a PATH-visible location via `uv tool install` or `pip`.
|
||||
|
||||
## 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
|
||||
|
||||
|
||||
@@ -1,3 +1,3 @@
|
||||
"""Single source of truth for the MemPalace package version."""
|
||||
|
||||
__version__ = "3.3.3"
|
||||
__version__ = "3.3.4"
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
[project]
|
||||
name = "mempalace"
|
||||
version = "3.3.3"
|
||||
version = "3.3.4"
|
||||
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"
|
||||
|
||||
+1
-1
@@ -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`).
|
||||
|
||||
@@ -1169,7 +1169,7 @@ wheels = [
|
||||
|
||||
[[package]]
|
||||
name = "mempalace"
|
||||
version = "3.3.3"
|
||||
version = "3.3.4"
|
||||
source = { editable = "." }
|
||||
dependencies = [
|
||||
{ name = "chromadb" },
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 \
|
||||
|
||||
@@ -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`
|
||||
|
||||
Reference in New Issue
Block a user