Command reference.

poppy remember

Store a memory. The most-used command in the CLI.

poppy remember "keeping auth in Supabase, dropping Clerk"

# with explicit type + project
poppy remember "k8s ingress is nginx-ingress" --type decision --project infra

# pin an expiry
poppy remember "Q2 OKR target is 100 paying users" --expires-at 2026-07-01
poppy remember "staging runs on the eu-west cluster" --ttl 30d

The --type flag is a closed choice: fact, decision, preference, or lesson. Agents writing through MCP can also store summary. The project field is auto-derived from the current working directory if you don’t pass --project. --check-conflicts runs LLM conflict detection without writing; --auto-supersede replaces a high-confidence conflicting memory instead of adding a duplicate.

poppy recall

Search memories with the hybrid retrieval engine. Returns ranked matches.

poppy recall "auth provider"
poppy recall "deployment target" --project infra --limit 5
poppy recall "Q2 goals" --type decision --json
poppy recall "deploy" --since 7d

Without --json each match prints its content, then a line with the type, the project in brackets, the date, and the relevance score. Memory IDs are only included in the --json output, which is the agent-friendly format. --since takes an ISO date or a duration like 7d; --include-expired keeps TTL-expired memories in the results.

poppy list

List memories without ranking, most-recent first. Takes the same filters as recall: --project, --type, --since, --limit, --json, --include-expired.

poppy list
poppy list --project infra
poppy list --type decision --limit 20

poppy forget

Delete a memory by id. This is a hard delete; there is no undo. The recoverable paths are supersede (poppy remember --supersedes <id>) and deletes made in the web UI, which tombstone the memory for 7 days and can be restored in poppy ui.

poppy forget mem_a3f8
poppy forget mem_a3f8 --yes      # skip confirmation

poppy edit

Edit an existing memory in place. Use this for typo fixes (preserves id and lineage). For replacing one fact with a newer one, prefer supersede semantics. See poppy remember --supersedes.

poppy edit mem_a3f8 --content "new content"
poppy edit mem_a3f8 --type decision --project infra
poppy edit mem_a3f8 --ttl 30d        # or --expires-at / --no-expiry
poppy edit mem_a3f8 --no-project     # clear the project

poppy expire

List memories whose TTL has passed. Previews by default; --yes purges them.

poppy expire                # preview, deletes nothing
poppy expire --yes          # actually purge

poppy stats

Memory count, breakdown by type and project, active engine, database size. The first stop for “is this thing actually working.”

poppy stats

poppy serve

Start the MCP server over stdio. You shouldn’t normally need to run this yourself. The agents you set up call it. Run by hand for debugging.

poppy serve                       # stdio MCP, what agents invoke
poppy serve --source claude-code  # label memories written via this server

poppy ui

Start the local browse-and-edit web UI at http://localhost:7800. Stays running until you Ctrl+C. A non-loopback --host is refused unless you also pass --allow-remote. That puts the UI’s API on your network with no authentication of any kind: anyone who can reach the port can list and read every memory, tombstoned ones included, and edit, supersede, delete, or restore any of them. Treat it as a debugging convenience on a network you trust, not a way to share a store.

poppy ui                                # auto-opens browser
poppy ui --port 7900 --no-open          # bind elsewhere, don't open
poppy ui --host 0.0.0.0 --allow-remote  # expose on LAN (be careful)

poppy doctor

Diagnostic dump. Always paste this when filing a bug report. Reports:

• The poppy executable and the storage directory
• The active engine and memory count, plus embedding-index drift (stale vectors that need poppy migrate-engine)
• MCP entry, hook, and primer checks for each agent whose config exists
• The auto-capture state and when the last capture ran

poppy doctor

poppy config

Write CLI configuration. Values persist to ~/.poppy/config.json. Telemetry has its own switch: poppy telemetry on|off|status.

poppy config set trags-api-url https://trags.ai
poppy config set trags-api-key usr_xxx       # usually set by 'poppy setup trags'

poppy encrypt

Encrypt the local store at rest with a key held in your operating system’s keychain. Off by default: until you enable it, memories.db is a plaintext SQLite file protected only by file permissions. The sqlcipher3 dependency is not part of a plain install, so add it first.

pipx inject poppy-memory sqlcipher3   # or: pip install 'poppy-memory[encryption]'

poppy encrypt enable      # migrate the existing store in place
poppy encrypt status      # show whether the store is encrypted
poppy encrypt disable     # decrypt back to plaintext
poppy encrypt repair      # reconcile an inconsistent state

Stop poppy serve, poppy ui, and any capture or sync workers before enabling or disabling; both refuse to run when they detect a live writer. This is local encryption at rest, not end-to-end encryption: the key lives in your keychain, and if that entry is lost the store cannot be recovered.

poppy engines

List the engine catalog with the active engine starred, and switch between bloom (the default: FTS5 and embeddings into a cross-encoder rerank, on local ONNX models, included in a plain install) and seed (FTS5-only, no ML dependencies and no model downloads).

poppy engines                    # catalog, active engine starred
poppy engines use seed           # switch engine
poppy engines use bloom --migrate  # switch and re-embed existing memories

poppy setup

Wire Poppy into an agent. One subcommand per supported target. See Integrations for the per-agent details.

poppy setup claude-code
poppy setup cursor
poppy setup codex
poppy setup vscode
poppy setup windsurf
poppy setup gemini
poppy setup copilot-cli
poppy setup pi
poppy setup goose
poppy setup hermes-agent
poppy setup claude-desktop
poppy setup trags              # cloud-sync onboarding (device code)

Each setup command is idempotent; running it twice doesn’t duplicate anything.

poppy sync

Push to / pull from Trags. After poppy setup trags, sync is automatic: every local write (CLI or MCP) triggers a detached background worker that runs a pull-then-push. You generally don’t need to call these by hand, but they’re available for one-shot reconciliation. push, pull, and run take --dry-run; status only reads.

poppy sync push           # send local changes since the last push watermark
poppy sync pull           # apply remote rows newer than the pull watermark
poppy sync run            # pull then push, full bidirectional sync
poppy sync status         # watermarks, last-synced times, totals, pending flag

sync status shows the per-remote watermarks, when the last sync ran, cumulative pushed/pulled counts, and whether a sync is pending.

Other commands

• poppy autocapture [on|off|status] [--global] [--project NAME], show or change automatic capture. Bare on/off targets the current project; --global is the one-time consent that turns capture on or off everywhere and persists across upgrades. The per-project deny-list sits above consent, and only automatic capture stops: recall and poppy remember keep working in that project
• poppy consent (--enable, --disable, --status), the original visible consent command, still supported while callers migrate to poppy autocapture on --global
• poppy telemetry status|on|off, show or change anonymous usage telemetry, see Telemetry
• poppy import claude-memories and poppy import hermes-memories, import existing memory files from Claude Code or Hermes (both support --dry-run)
• poppy redaction add|remove|list, extend the secret masking that runs before an automatic capture is stored, with exact values or environment-variable names of your own
• poppy migrate-engine, re-embed memories so their vectors match the active engine (--project, --memory-type, --since, --all, --dry-run)
• poppy build mcpb, build the Claude Desktop Extension bundle

Source-of-truth note

This page is hand-curated and risks drifting from the actual CLI. The source of truth is poppy --help and poppy <subcommand> --help. If you spot a discrepancy, the docs are wrong; please email feedback@trags.ai.