Install Poppy.

Prerequisites

Poppy is a Python 3.11+ package. You need either:

• pipx (recommended), installs Poppy into its own virtualenv so it never collides with your project dependencies
• uv (a fast alternative; same isolation guarantees)

pipx (recommended)

# install pipx if you don't have it
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# install poppy
pipx install poppy-memory

# verify
poppy --version
poppy doctor

The package on PyPI is poppy-memory (the poppy name was taken by an unrelated project). The installed CLI is poppy.

Engines

The default retrieval engine is bloom, a hybrid of FTS5 and embeddings into a cross-encoder rerank. It runs on local ONNX models, so a plain install already has everything it needs; the models themselves (~160 MB) download on first use. seed is FTS5-only with no ML dependencies and no downloads, and it is the automatic fallback when bloom cannot start. Switch with poppy engines use <name>.

Optional extras

One extra exists, off by default: encryption adds sqlcipher3 for encryption at rest (poppy encrypt enable).

# pipx installs poppy in its own virtualenv, so inject the dep there
pipx inject poppy-memory sqlcipher3

# plain pip installs use the extra directly
pip install 'poppy-memory[encryption]'

uv tool

uv tool install poppy-memory

Same semantics as pipx. Faster install on cold caches. Use this if your project is already on uv.

Verifying the install

poppy --version
poppy doctor

poppy doctor checks the poppy executable and storage directory, prints the active engine and memory count, warns about embedding-index drift, runs the MCP / hook / primer checks for each agent it finds, and reports the auto-capture state. It’s also the first command to paste into a bug report.

Upgrading

# pipx
pipx upgrade poppy-memory

# uv tool
uv tool upgrade poppy-memory

# the curl script's virtualenv fallback
${XDG_DATA_HOME:-$HOME/.local/share}/poppy/venv/bin/python -m pip install --upgrade poppy-memory

Upgrades preserve your local memory database at ~/.poppy/memories.db. Cloud sync keeps working without reconfiguration.

Uninstall

# remove the CLI
pipx uninstall poppy-memory     # or: uv tool uninstall poppy-memory

# optional: nuke local memories
rm -rf ~/.poppy/

Uninstalling the CLI does not remove the agent integrations; delete the poppy entry from each agent’s MCP config (and any primer block) by hand. If you used cloud sync, removing the CLI does not delete your cloud-side memories either. Use the dashboard to delete your account if you want a full wipe.