Troubleshooting

Ingest succeeds but query misses facts

• Verify entity scope is identical between ingest and query.
• Check fact was invalidated by newer superseding memory.
• Confirm memory kind filters are not excluding expected hits.
• Inspect dedup table for accidentally collapsed records.

High latency spikes

• Reduce rerank candidate count.
• Tune HNSW `ef_search` for your latency budget.
• Check for disk saturation on data volume.
• Warm model cache before traffic cutover.

Quick diagnostic commands

curl -i --max-time 10 http://127.0.0.1:3000/query/semantic \
  -H "content-type: application/json" \
  -H "x-api-key: XXX1111AAA" \
  -d '{"entity_id":"user-123","textual_query":"latest preference","limit":3}'