Debugging with Retrieval Traces

Every /v1/context and /v1/recall call is logged automatically. This guide shows how to use traces to understand and debug belief retrieval.

The debug header

Add X-Memcone-Debug: true to any /v1/context or /v1/recall request to get the retrieved beliefs inline in the response:

curl -X POST https://api.memcone.com/v1/context \
  -H "Authorization: Bearer $MEMCONE_API_KEY" \
  -H "X-Memcone-Debug: true" \
  -H "Content-Type: application/json" \
  -d '{"scopeId": "user_123", "task": "help user with coding"}'

curl -X POST https://api.memcone.com/v1/context \
  -H "Authorization: Bearer $MEMCONE_API_KEY" \
  -H "X-Memcone-Debug: true" \
  -H "Content-Type: application/json" \
  -d '{"scopeId": "user_123", "task": "help user with coding"}'

Response with debug enabled:

{
  "result": "The user prefers TypeScript strict mode and functional style. They deploy to Railway.",
  "tokens_saved": 42,
  "cache_hit": false,
  "sources": [
    { "text": "prefers TypeScript strict mode", "strength": 4.2, "similarity": 0.94 },
    { "text": "uses functional style, no classes", "strength": 3.8, "similarity": 0.87 },
    { "text": "deploys to Railway", "strength": 2.9, "similarity": 0.81 }
  ]
}

{
  "result": "The user prefers TypeScript strict mode and functional style. They deploy to Railway.",
  "tokens_saved": 42,
  "cache_hit": false,
  "sources": [
    { "text": "prefers TypeScript strict mode", "strength": 4.2, "similarity": 0.94 },
    { "text": "uses functional style, no classes", "strength": 3.8, "similarity": 0.87 },
    { "text": "deploys to Railway", "strength": 2.9, "similarity": 0.81 }
  ]
}

The sources array shows exactly which beliefs were retrieved and their strength scores.

Dashboard: Retrieval Traces

The Retrieval Traces page shows a global feed of all context and recall calls:

• Endpoint — context or recall
• Scope — which scope was queried
• Query — the task or query string
• Cache — HIT or MISS
• Beliefs — how many beliefs were retrieved

Click any trace to expand it and see each retrieved belief with its similarity score (how semantically close to the query) and strength score (how trusted the belief is).

Dashboard: Belief Explorer

The API scopes page shows per-scope memory state:

• Memory tab — all stored items for a scope, sorted by strength
• Traces tab — retrieval history for this scope
• Timeline tab — chronological lifecycle: formation, reinforcement, retrieval events

Common issues

Belief not being retrieved

The belief exists but isn't showing up in context. Possible causes:

1. Strength has decayed The belief was formed long ago and hasn't been reinforced. Check the strength score in the Belief Explorer. If it's below 1.0, it may be outranked by more recent beliefs.

2. Semantic mismatch The task/query isn't semantically close to the belief text. Try /v1/recall with a more specific query to test retrieval directly.

3. Cache hit serving stale data If you recently called /v1/remember but context still returns old results, you may have a stale cache entry. Force a fresh retrieval:

POST /v1/context
{ "scopeId": "user_123", "task": "...", "mode": "fresh" }

POST /v1/context
{ "scopeId": "user_123", "task": "...", "mode": "fresh" }

Or check cache_hit in the response — if true, the cache is serving a prior computation.

Wrong beliefs being retrieved

The wrong beliefs are showing up for a given task.

1. Overly broad task string The task parameter shapes which beliefs get retrieved. Make it specific:

// Too broad — retrieves everything
{ "task": "respond to user" }

// Better — retrieves relevant beliefs
{ "task": "help user debug a TypeScript compilation error" }

// Too broad — retrieves everything
{ "task": "respond to user" }

// Better — retrieves relevant beliefs
{ "task": "help user debug a TypeScript compilation error" }

2. Scope is too wide If you're using a broad scope like org_123, beliefs from many users may be mixing. Use per-user or per-context scopes.

Contradictions not resolving

If you're seeing conflicting beliefs (both old and new) with similar strength:

• The new fact may not be semantically close enough to the old one to trigger contradiction detection
• Call /v1/remember with a more explicit statement: "User switched from JavaScript to TypeScript" rather than just "User uses TypeScript"
• Check contradictions_resolved in the /v1/remember response — if 0, no contradictions were detected

Checking contradiction resolution

The /v1/remember response includes:

{
  "ok": true,
  "extracted": 2,
  "facts": ["user uses TypeScript", "user dislikes classes"],
  "contradictions_resolved": 1,
  "preview": "user uses TypeScript"
}

{
  "ok": true,
  "extracted": 2,
  "facts": ["user uses TypeScript", "user dislikes classes"],
  "contradictions_resolved": 1,
  "preview": "user uses TypeScript"
}

contradictions_resolved: 1 means one prior conflicting belief was decayed.

Viewing raw belief state

Use the API to inspect beliefs directly:

# List all scopes for your API key
GET https://api.memcone.com/v1/scopes

# Get all beliefs for a scope with strength scores
GET https://api.memcone.com/v1/scopes/user_123/beliefs

# Get retrieval traces for a scope
GET https://api.memcone.com/v1/scopes/user_123/traces

# List all scopes for your API key
GET https://api.memcone.com/v1/scopes

# Get all beliefs for a scope with strength scores
GET https://api.memcone.com/v1/scopes/user_123/beliefs

# Get retrieval traces for a scope
GET https://api.memcone.com/v1/scopes/user_123/traces

See Usage API reference for the full endpoint docs.