ai.trags/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 <client>. 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 <client> ends with Restart <client> 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.

... View full README on GitHub