Installation

Installation

Recollectium is designed to be a one-command, hassle-free install. The bootstrap installer installs uv if needed, installs Recollectium as an isolated tool, and makes the recollectium command available on your PATH when possible. On Linux and macOS it also attempts recollectium init as a best-effort step. On Windows, run recollectium init after installation.

Every release is tested through install-smoke checks across Linux, macOS, Windows, x86_64, and ARM64. The recommended install path is the same path CI verifies for users.

Use these commands:

Recommended bootstrap install

Linux and macOS:

curl -LsSf https://raw.githubusercontent.com/AlfonsoDehesa/recollectium/main/install.sh | sh

Windows PowerShell:

powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/AlfonsoDehesa/recollectium/main/install.ps1 | iex"

The bootstrap installer:

• Installs uv if needed.
• Installs Recollectium in an isolated tool environment.
• Attempts recollectium init on Linux and macOS, but continues if init fails.
• Does not run recollectium init on Windows.
• Installs shell completion in a managed block when safe.

Install a specific target

The default installer tracks the latest release. To pin a release:

curl -LsSf https://raw.githubusercontent.com/AlfonsoDehesa/recollectium/main/install.sh | RECOLLECTIUM_INSTALL_VERSION=1.0.2 sh

$env:RECOLLECTIUM_INSTALL_VERSION='1.0.2'; powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/AlfonsoDehesa/recollectium/main/install.ps1 | iex"

To track main instead:

curl -LsSf https://raw.githubusercontent.com/AlfonsoDehesa/recollectium/main/install.sh | RECOLLECTIUM_INSTALL_MAIN=1 sh

$env:RECOLLECTIUM_INSTALL_MAIN='1'; powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/AlfonsoDehesa/recollectium/main/install.ps1 | iex"

After installing, run init once if it did not already complete, especially on Windows:

recollectium init

Init creates config, data, cache, logs, and runtime directories, creates or migrates the SQLite database, and downloads the built-in FastEmbed model cache.

After bootstrap install, normal commands are direct Recollectium commands:

recollectium --version
recollectium --help
recollectium search-user "preferences about wording"

Package manager installs

If you already have Python 3.12 or newer:

pip install recollectium

For isolated CLI installs:

pipx install recollectium
uv tool install recollectium

Try without a permanent install:

uvx recollectium --version

After package-manager installs, initialize once:

recollectium init

Upgrade

Upgrade according to the target this install is tracking:

recollectium upgrade

By default, installs track the latest release. You can switch targets during upgrade:

recollectium upgrade --version latest
recollectium upgrade --version 1.0.2
recollectium upgrade --main

Pinned versions stay pinned. A plain recollectium upgrade will not move a pinned install unless you pass --force or choose a different target.

Non-mutating checks:

recollectium upgrade --check
recollectium upgrade --dry-run

• --check reports whether a newer release is available and does not change files, config, services, or data.
• --dry-run prints the upgrade command Recollectium would run and does not apply it.

Override install-method detection when needed:

recollectium upgrade --install-method pip
recollectium upgrade --install-method pipx
recollectium upgrade --install-method uv_tool
recollectium upgrade --install-method source

If a managed API or MCP service is running, Recollectium stops it, upgrades the package, then restarts the same service type when the upgrade succeeds.

Uninstall

Safe uninstall preserves memories and local data by default. It may edit shell profile or startup files only to remove Recollectium-managed completion blocks. It does not delete arbitrary shell configuration.

recollectium uninstall

Preview a destructive purge:

recollectium uninstall --purge --dry-run

Permanently delete Recollectium-owned config, data, cache, logs, runtime files, and memories:

recollectium uninstall --purge

For non-interactive purge automation:

recollectium uninstall --purge --yes-delete-all-recollectium-data

Use purge carefully. It deletes memories and cannot be undone.

Additional setup

Shell completion

Bootstrap install sets up completion automatically for supported shells when safe. You only need this section if you used another install method, skipped automatic setup, or want to reinstall completion manually.

Manual install:

recollectium completion --install
recollectium completion --install bash
recollectium completion --install zsh
recollectium completion --install fish

PowerShell:

recollectium completion --install powershell

Print setup instructions instead of installing:

recollectium completion bash
recollectium completion zsh
recollectium completion fish
recollectium completion powershell

Print the raw completion source:

recollectium completion bash --source

Development install

Use this when you are contributing to Recollectium from a source checkout:

git clone https://github.com/AlfonsoDehesa/recollectium.git
cd recollectium
uv sync --group dev
uv run recollectium --help

In a development checkout, use uv run recollectium ... so the command runs against the local source tree and managed development environment.