<!--
  Full-page Markdown export (rendered HTML → GFM).
  Source: https://neotoma.io/hi/troubleshooting
  Generated: 2026-04-01T11:48:28.559Z
-->
# 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](/cli), [MCP reference](/mcp), and [architecture](/architecture) for deeper diagnostics.