Troubleshooting and FAQ
Use this guide when setup or behavior is unclear. For deterministic systems, the fastest path is to inspect state, provenance, and transport mode instead of guessing.
Agent is not storing memory entries
Check: Confirm MCP server is configured and running, then verify tool calls include store actions.
Fix: Recheck client config (`.cursor/mcp.json`, `.mcp.json`, or `.codex/config.toml`) and restart the client.
Entity query returns empty results
Check: Verify the entity type and filters used by your query.
Fix: Run `neotoma entities list --type <entity_type>` without search first, then narrow filters.
Unexpected or conflicting state values
Check: Inspect observations and provenance for that entity and field.
Fix: Use correction flows (`correct`, `reinterpret`) and confirm deterministic merge rules in schema/reducer logic.
CLI command behavior differs from API
Check: Check transport mode (`--offline`, `--api-only`, base URL) and environment selection.
Fix: Pin the mode explicitly for reproducible debugging, then compare with API endpoint responses.
Need to reset local state safely
Check: Export data first for auditability.
Fix: Back up data directory, then reinitialize. Avoid deleting data until exports are verified.
Useful commands
# Inspect entities neotoma entities list --type task --limit 20 # Trace lineage for one entity neotoma observations list --entity-id <entity_id> neotoma relationships list --entity-id <entity_id> # Confirm server health neotoma stats
See CLI reference, MCP reference, and architecture for deeper diagnostics.