Merge upstream v3.3.5 into kostadis-dev

.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/hooks/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/mempal-stop-hook.sh"
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/mempal-stop-hook.sh\""
           }
         ]
       }
@@ -16,7 +16,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/mempal-precompact-hook.sh"
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/mempal-precompact-hook.sh\""
           }
         ]
       }

.claude-plugin/marketplace.json

@@ -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.4",
+      "version": "3.3.5",
       "author": {
         "name": "milla-jovovich"
       }

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mempalace",
-  "version": "3.3.4",
+  "version": "3.3.5",
   "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"

.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,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:

.codex-plugin/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CODEX_PLUGIN_ROOT}/hooks/mempal-hook.sh session-start"
+            "command": "\"${CODEX_PLUGIN_ROOT}/hooks/mempal-hook.sh\" session-start"
           }
         ]
       }
@@ -17,7 +17,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CODEX_PLUGIN_ROOT}/hooks/mempal-hook.sh stop"
+            "command": "\"${CODEX_PLUGIN_ROOT}/hooks/mempal-hook.sh\" stop"
           }
         ]
       }
@@ -28,7 +28,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CODEX_PLUGIN_ROOT}/hooks/mempal-hook.sh precompact"
+            "command": "\"${CODEX_PLUGIN_ROOT}/hooks/mempal-hook.sh\" precompact"
           }
         ]
       }

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mempalace",
-  "version": "3.3.4",
+  "version": "3.3.5",
   "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"

.github/workflows/deploy-docs.yml

@@ -29,7 +29,7 @@ jobs:
 
       - name: Configure GitHub Pages
         id: pages
-        uses: actions/configure-pages@v5
+        uses: actions/configure-pages@v6
 
       - uses: oven-sh/setup-bun@v2
         with:

.gitignore

@@ -36,6 +36,7 @@ venv/
 
 # ChromaDB local data
 *.sqlite3-journal
+.envrc
 
 # MemPalace per-project files (issue #185)
 mempalace.yaml

.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`
@@ -93,3 +97,15 @@ If you're planning a significant change, open an issue first to discuss the appr
 ## License
 
 MIT — your contributions will be released under the same license.
+
+## Git identity for contributions
+
+Before pushing commits, verify that Git is configured with an email address that GitHub can associate with your account:
+
+```bash
+git config user.name
+git config user.email
+```
+
+This is especially important when commits are created through agentic coding tools or automation, because those tools may not inherit your normal shell Git configuration. Avoid placeholder values such as `your@email.com` or localized template text; unresolved author emails can create avoidable provenance and SBOM review friction for downstream users.
+

README.md

@@ -6,6 +6,10 @@
 > domain — including `mempalace.tech` — is an impostor and may distribute
 > malware. Details and timeline: [docs/HISTORY.md](docs/HISTORY.md).
 
+> [!IMPORTANT]
+> **🚨 Claude Code sessions expire in 30 days w/out auto-save hooks wired!** **[Read this →](https://github.com/MemPalace/mempalace/discussions/1388)**
+
+
 <div align="center">
 
 <img src="assets/mempalace_logo.png" alt="MemPalace" width="240">
@@ -45,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
@@ -116,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
 ```
 
 ---
@@ -182,7 +191,7 @@ PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
 MIT — see [LICENSE](LICENSE).
 
 <!-- Link Definitions -->
-[version-shield]: https://img.shields.io/badge/version-3.3.4-4dc9f6?style=flat-square&labelColor=0a0e14
+[version-shield]: https://img.shields.io/badge/version-3.3.5-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/

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
-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

@@ -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
-python3 -m venv .venv
+# Create the venv and install MemPalace + dependencies in editable mode
+uv sync
+```
+
+This produces a `.venv/` directory inside the repo with everything installed.
+If you prefer plain pip:
 
-# Install dependencies and MemPalace in editable mode
+```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
 ```