Skip to main content

Debug semantic runtime and memory lane

Use this page when semantic retrieval, context assembly, or multilingual memory behaves unexpectedly and you need to determine whether the problem is graph runtime, model admission, memory migration, or context delivery.

When to use this page​

  • semantic context is missing, degraded, stale, or contradictory
  • a memory lane behaves differently than the rest of the retrieval path
  • a model choice or provider profile appears blocked, stale, or mismatched
  • operators need a bounded diagnosis order before restart, cutover, or rollback

Prerequisites​

  • You can read the relevant runtime health, readiness, and docs truth surfaces
  • You can distinguish source-owned business truth from derived projection or episodic memory
  • You can capture evidence before mutating runtime configuration

Architecture / Flow​

Step-by-step procedure​

1. Establish the shared posture first​

Use the relevant shared-truth and readiness families before restarting anything:

GET /health
GET /api/v1/platform/services
GET /api/v1/contracts/drift
GET /api/v1/docs/readiness

2. Separate the lane that is actually failing​

Classify whether the symptom is primarily in:

  • semantic projection
    • graph or projection runtime is stale, unhealthy, or inconsistent
  • context delivery
    • the bounded context does not match the admitted decision surface
  • episodic memory
    • remembered interaction facts are missing, duplicated, or on the wrong lane
  • model admission
    • the requested model profile or provider posture is blocked, stale, or unsupported

3. Check fail-closed states before changing runtime​

Common states to read back or classify:

  • knowledge_missing
  • source_stale
  • authority_conflict
  • model_not_admitted
  • degraded_retrieval

Treat these as diagnosis hints, not as reasons to force a restart immediately.

4. Use lane-specific recovery​

  • graph or projection issue
    • compare projection and readback truth before rebuild or replay
  • memory-lane issue
    • verify migration lane, collection posture, and rollback window before cutover
  • model-admission issue
    • confirm the admitted model profile, residency posture, and provider health instead of hardcoding a fallback
  • context delivery issue
    • confirm the Reed, Warp, and Fabric boundary before treating the graph itself as broken

5. Re-verify the same surfaces after any bounded fix​

After the fix, re-read the same health, readiness, and route family that exposed the issue. Do not stop at “service restarted” or “one query now works.”

Verification​

This runbook is being used correctly when:

  1. the failing lane is separated before mutation
  2. graph, memory, and model-admission problems are not collapsed into one generic outage
  3. post-fix readback uses the same evidence family that exposed the issue

Common failure modes​

Treating every semantic failure as a graph failure​

Problem:

  • a memory migration or model-admission issue gets misdiagnosed as core graph instability.

Better path:

  • classify projection, context, memory, and model posture separately first

Rolling forward to a new lane without checking rollback posture​

Problem:

  • a migration looks green until a later readback exposes missing or duplicated facts.

Better path:

  • verify cutover and rollback evidence before retiring the old lane

Using general model knowledge as a silent fallback​

Problem:

  • the system appears responsive while authoritative context is actually missing.

Better path:

  • keep domain-knowledge actions fail-closed when the required semantic or admitted-model lane is unavailable

Source Truth​

Next paths​