What to try first, what to paste in a bug report.

Start with poppy doctor

Almost every “Poppy isn’t working” question is one poppy doctor run away from a fix. The output enumerates: the poppy executable, the storage directory, the active engine and memory count, embedding-index drift, MCP / hook / primer checks per agent, and the auto-capture state. When something is off, the doctor command prints the exact remediation command.

poppy doctor

Common problems

“poppy recall” returns nothing

• Have you stored anything? poppy stats shows memory count.
• Is the engine loaded? poppy doctor shows which engine is active. If you’re on seed, the FTS5-only fallback, semantic recall is gone; switch back with poppy engines use bloom.

“ModelUnavailableError” on first recall

The default bloom engine downloads its models (~160 MB) on first use. If you’re offline with a cold cache, that download fails. Retry once you’re online, or switch to the no-ML fallback:

poppy engines use seed      # FTS5 only, no downloads
# later, back to the default
poppy engines use bloom

Agent doesn’t see Poppy tools

• Restart the agent. Most clients only re-read MCP config on startup.
• Run poppy doctor, confirm the MCP entry is present in the agent’s config file.
• Confirm the agent supports MCP. Hermes and Claude Desktop use different paths; see Integrations.
• Check the primer file is installed. Some agents need the primer to learn the tool names.

Cloud sync says “401 unauthorized”

• The API token is stale or revoked. Re-run poppy setup trags.
• If it persists, log into trags.ai/dashboard and confirm the device still has an active key under Settings → API keys.

Sync hangs or push fails repeatedly

Push freezes the watermark on first failure deliberately. Nothing is silently skipped. Diagnose:

poppy sync status              # last pull/push, totals, pending flag
rm ~/.poppy/sync_state.json    # reset watermarks if state is genuinely lost
poppy sync run                 # full re-sync follows; cloud dedups by id

“poppy stats” shows engine: seed

Poppy is running the FTS5-only seed engine, either because you switched to it or because the ML dependencies for the configured engine aren’t loadable. Keyword recall still works, but semantic matching is gone. Switch back:

poppy engines use bloom

Database file is locked

SQLite locks happen when multiple Poppy processes write at once. Almost always caused by an old poppy serve still running. Find and kill it:

ps aux | grep 'poppy serve'
kill -9 <pid>

If the lock survives the kill, make sure no other poppy process is running and try again.

Where the logs live

All flat under ~/.poppy/:

• postcompact-debug.log and sessionend-debug.log, hook debug payloads, rolling JSONL, last 50 entries
• capture-worker.log, the detached zero-touch capture worker
• sync-worker.log, the auto-sync worker (plus sync-worker.raw.log for subprocess output, truncated at 1 MB)

To re-fire the most recent agent hook for debugging:

poppy hook replay-compact --last 1
poppy hook replay-session-end --last 1

Filing a bug report

The four steps that make a report we can act on:

1. Run poppy doctor and paste the output
2. Describe what you did, what you expected, what actually happened
3. Attach the last 20 lines of the relevant log under ~/.poppy/ (sync-worker.log or capture-worker.log usually)
4. Email it to feedback@trags.ai

For security issues, email security@trags.ai rather than filing in public.