Poppy

Poppy is a developer memory CLI and MCP server. Your AI coding agent stores decisions, preferences, and lessons in a local SQLite store, then recalls them when they're relevant. No cloud, no API keys, no per-query cost.

pipx install poppy-memory

Then wire up your agent, and restart it:

poppy setup claude-code   # or: claude-desktop, cursor, vscode, windsurf, codex,

gemini, copilot-cli, pi, goose, hermes-agent

The package on PyPI is poppy-memory; the command it installs is poppy. No pipx? See Install for the other ways in, and for the one PATH check that saves most first-day trouble.

First ten minutes

The order a new user walks, each step linking to its section:

1. Install Poppy with pipx, uv, or the one-line installer. See Install.
2. Check that `poppy` is on your PATH: command -v poppy should print a path. See Check your PATH.
3. Wire up your agent with poppy setup . See Supported clients.
4. Restart the agent so it loads the MCP server and hooks. See Restart the agent after setup.
5. Store and recall once with poppy remember and poppy recall. See What it does.
6. Pair with Trags (optional) with poppy setup trags, and approve it in the browser within five minutes. See Sync to Trags.
7. Install the daemon (optional) with poppy daemon install. See MCP daemon.
8. Run `poppy doctor` to check engine, storage, MCP config, and hooks. See Commands.

Install

Use the first option your machine already has:

• pipx: pipx install poppy-memory. Needs pipx and Python 3.11 or newer.
• uv: uv tool install poppy-memory. Needs only uv, which fetches its own Python. A fresh Mac has neither pipx nor uv.
• One-line installer: curl -fsSL https://trags.ai/install/poppy | sh. Needs Python 3.11 or newer. It uses pipx or uv when it finds one and otherwise installs into its own virtualenv.

Check your PATH

pipx and uv put the poppy command in ~/.local/bin. A fresh Mac often does not have that folder on its PATH, and the install still succeeds: uv only prints a warning. Check:

command -v poppy    # prints a path such as /Users/you/.local/bin/poppy

If it prints nothing, add the folder to your shell profile and open a new terminal (pipx ensurepath or uv tool update-shell do the same):

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

This matters for your agent too. The hooks call poppy by name, so an agent that cannot find it fails every hook with poppy: command not found. An agent keeps the PATH it started with, so restart it after you fix PATH. poppy doctor checks only the PATH of the terminal you run it in, so it can report the hooks as fine while your agent still cannot find poppy.

Restart the agent after setup

poppy setup ends with Restart to activate. Do that. Agents read their MCP servers and hooks only when they start, so a session that was already open does not see Poppy until you quit and reopen it.

What it does

• `remember` stores a fact, decision, preference, or lesson.
• `recall` pulls the few memories most relevant to a query.
• MCP server: agents call the tools in MCP tools directly. Works with Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Codex, Gemini CLI, Copilot CLI, Pi, and Goose. Hermes Agent gets a memory provider plugin instead.
• Hooks: Claude Code, Cursor, and Codex hooks surface relevant memories and capture new ones. Claude Code and Cursor use end-of-session and compaction backstops; Codex uses cadence-only capture.
• Zero-touch capture: with your one-time consent, Poppy extracts durable memories from your sessions automatically, locally, using the coding-agent CLI you already have. See Zero-touch capture.
• One retrieval pipeline: hybrid search and reranking run locally, with a built-in keyword-only fallback when ML dependencies or models are unavailable. See Engines.

poppy remember "we always use uv for python deps" --type preference

poppy recall "python package manager"

we always use uv for python deps

preference | 2026-05-25 | score: 0.91 | mem_3f9a1c2b7d4e

Supported clients

poppy setup wires Poppy into a coding agent. Eleven clients have an integration today:

• MCP server plus zero-touch capture hooks: Claude Code, Cursor, Codex.
• MCP server: Claude Desktop, VS Code, Windsurf, Gemini CLI, GitHub Copilot CLI, Pi, Goose. Most also get a short primer file so the agent knows the memory tools are there.
• Memory provider plugin that calls the Poppy CLI: Hermes Agent.

What supported means here: each integration is verified against its client at release time, and maintained best-effort between releases. These clients change on their own schedule, so when one of them breaks Poppy, that is a bug worth reporting as a GitHub issue rather than something that holds the next release back.

poppy doctor checks the integrations installed on your machine.

Setup treats any hook command of the form /poppy hook (including a versioned executable name such as poppy-0.3.3) as Poppy's own. It rewrites these commands to the current executable, so a deliberate pin to a development install is overwritten on the next setup and removed by --remove. Before downgrading, run poppy setup --remove with the current version, then set up again with the older version. Older versions do not recognise absolute-path hook entries and would add duplicates.

Claude Code plugin

Claude Code can also load Poppy as a plugin, in place of poppy setup claude-code. Install poppy-memory first, as above. The plugin only connects Claude Code to the poppy command you already have.

claude plugin marketplace add trags-garden/poppy

claude plugin install poppy@trags-garden

Restart Claude Code afterwards.

The plugin gives Claude Code the same MCP server and the same five hooks that setup writes. It looks for poppy on the PATH and then in the folders pipx, uv and pip install --user install into, so it works when ~/.local/bin is not on Claude Code's PATH. In place of the CLAUDE.md block it ships a memory skill with the same text. Claude loads the skill when memory is relevant, and you can run it yourself with /poppy:memory. The plugin needs macOS or Linux. On Windows, use poppy setup claude-code.

Use the plugin or setup, not both. With the plugin installed, poppy setup claude-code does not add the MCP server or hooks and says so. Pass --claude-md to add the CLAUDE.md block next to the skill, so the primer loads in every session. If you ran setup before installing the plugin, run poppy setup claude-code --remove to remove setup's entries, or every hook runs twice. poppy doctor warns when it finds both, and fails when the plugin cannot find poppy.

The plugin does not ask for capture consent the way setup does. Answer the notice at session start, or run poppy autocapture on --global.

Uninstall

Remove client integrations before uninstalling the CLI, so leftover hooks do not fail with poppy: command not found on every session.

1. Run the following for each client you set up:

   poppy setup claude-code --remove

poppy setup cursor --remove poppy setup codex --remove

This removes Poppy's MCP entry, hooks and managed primer blocks while preserving your other settings. If you installed the Claude Code plugin, also run claude plugin uninstall poppy@trags-garden. Other clients still need their Poppy entry and primer removed by hand: Claude Desktop's claude_desktop_config.json, VS Code's user-profile mcp.json, Windsurf, Gemini CLI, GitHub Copilot CLI ($COPILOT_HOME/mcp-config.json and copilot-instructions.md, default ~/.copilot), Pi ($PI_CODING_AGENT_DIR/mcp.json and AGENTS.md, default ~/.pi/agent), Goose, and Hermes Agent (plugin and SOUL.md guidance).

1. If you installed the daemon service, run poppy daemon uninstall.
2. Run pipx uninstall poppy-memory, or uv tool uninstall poppy-memory if you installed it with uv.
3. Optionally run rm -rf ~/.poppy. This permanently deletes your memories and local Poppy settings. If you use a custom POPPY_DIR, your data lives there instead.

--remove leaves your memory store, daemon service, Trags key and capture consent untouched. It also keeps the .pre-poppy.bak backups that setup and removal write next to each client file; delete those too if you are removing Poppy for good, since a backup can hold the daemon token. Use it on its own, without installation flags such as --daemon, --hooks, --claude-md or --yes.

Zero-touch capture

With the Claude Code, Cursor, or Codex hooks installed, Poppy can also extract durable memories from your sessions automatically: decisions, preferences, and lessons that would help a future session, written one sentence each.

Nothing is captured without your consent. Capture ships enabled by default but stays inert until you record a one-time consent. If you already had consolidate-enabled true set from an earlier version, that setting counts as your recorded consent and capture stays active with no new prompt. Setting POPPY_CONSOLIDATE=1 overrides the consent check entirely and turns capture on regardless. The unified command reports the resolved effect plus the project and global layers:

poppy autocapture                 # show resolved, project, and global status

poppy autocapture on --global # turn automatic capture on everywhere poppy autocapture off --global # opt out everywhere (persists across upgrades)

poppy setup claude-code asks once on a TTY (pass --yes for non-interactive installs). Until you decide, every session start shows a short notice and nothing runs. Opting out persists permanently; a later default change can never silently re-enable capture you turned off.

What fires when, once automatic capture is enabled globally:

• Every 3rd prompt, a detached background worker reads only the transcript turns added since the last capture and extracts memories from that window. It never blocks your prompt, captures no turn twice, and stops at a per-session soft cap in Claude Code and Cursor. Codex has no soft cap because it has no end-of-session flush.
• At session end in Claude Code and Cursor, a backstop pass flushes whatever the mid-session loop has not captured yet. Codex Stop fires after each turn, so Poppy uses it only as a liveness signal and never as a flush.
• Around context compaction, Claude Code consolidates the compact summary; Cursor flushes the live transcript at preCompact before compaction begins.

Extraction runs through the coding-agent CLI you already use (claude, cursor-agent, codex, or gemini), on your existing login. That CLI sends the transcript excerpt to the model provider you already use, so no new third party sees your conversation. The store, your memories, and retrieval stay on your machine; retrieval runs on local ONNX models. Poppy sends nothing to Trags unless you turn sync on. It never auto-spends on a paid remote model: if only an AP