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, prepares the configured embedding model, refreshes stale embeddings when needed, and makes the recollectium command available on your PATH when possible.

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.
• Runs embedding maintenance, which creates or migrates the database, prepares the configured FastEmbed model, and refreshes stale embeddings when needed.
• 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 through a package manager, run init once if it did not already complete:

recollectium init

Init creates config, data, cache, logs, and runtime directories, creates or migrates the SQLite database, downloads or prepares the configured FastEmbed model cache, and refreshes stale or missing embeddings inline when existing memories need it.

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, runs embedding maintenance with the upgraded code, then restarts the same service type when the upgrade succeeds. upgrade --check and upgrade --dry-run do not download models, create state, or re-embed.

Database upgrades and recovery

Recollectium applies SQLite schema migrations automatically during init, upgrade, and service startup. Pending migrations run in order and only once.

Upgrades are forward-only. If the database is newer than the installed Recollectium build, startup fails until you upgrade Recollectium to a build that understands the newer schema or restore a backup from before the newer schema was written. Downgrades are not supported.

If a migration fails or startup is interrupted while it is applying, the failed step is rolled back and the database stays on the last successful version. After fixing the problem, rerun the same command. Recollectium resumes from the last applied migration.

Before upgrading production data, stop the service and copy the Recollectium data directory or the SQLite database file somewhere safe. There is no dedicated backup command in v1. If the database becomes corrupted, restore that copy and start Recollectium again.

Uninstall

Safe uninstall preserves memories and config by default. It removes the Recollectium-owned derived local model cache and may edit shell profile or startup files only to remove Recollectium-managed completion blocks. It does not delete arbitrary shell configuration. Source and unknown installs report a manual package-removal hint because safe self-removal is not supported for those install types.

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.

In human-readable mode, --compact prints a short uninstall sentence and --verbose prints the full result payload. Both can show live progress on stderr while package removal runs when the terminal supports it. JSON output stays structured and automation-safe.

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.