Memory Failure-Mode Catalog

Fig. 2 failure catalog / C35-C43

FIG. 2

Which symptom are you seeing?

Pick the symptom closest to the bug report, then inspect the memory write path and retrieval trace before changing prompts or models.

C35

AI agent forgets context between sessions

Cause: The agent is relying on the current context window or chat history instead of a durable memory write path.
Inspect: Check whether the MCP server is connected, whether a memory was written, and whether a new session calls retrieval before answering.
Fix: Add a scoped MCP memory server, save source-linked facts through the write path, and test recall in a fresh session.

C35 forgetting between sessions

C36

Agent recommends stale or outdated info

Cause: Old source artifacts are still current in the retrieval path, or new artifacts were imported without superseding the old fact.
Inspect: Compare source timestamps, supersedes_id relationships, and the retrieval trace for whether stale items ranked above current items.
Fix: Record replacement relationships, prefer current source artifacts, and scope freshness language to the next supported sync or re-import.

C36 stale recommendations

C37

RAG returns wrong or irrelevant results

Cause: Chunking, embedding mismatch, query drift, missing reranking, stale indexes, ACL noise, or missing inspectability can push weak evidence into the answer.
Inspect: Open the candidate list, check ranks, citations, filters, query text, and whether the answer used evidence from the right source.
Fix: Tune chunking, hybrid search, reranking, filters, and source inspection before changing the model prompt.

C37 retrieval failure modes

C38

Need to delete or forget a specific memory

Cause: The memory layer lacks a delete handle, tombstone, or derived-artifact lifecycle that can target one remembered fact.
Inspect: Find the source artifact, derived summaries, embeddings, tags, and retrieval logs tied to the memory.
Fix: Delete or disable the source and derived artifacts, write an audit event, and run a recall check for the deleted fact.

C38 delete a memory

C39

Claude Code loses context after compaction

Cause: Compaction summarizes the active thread but does not automatically persist every project decision into shared memory.
Inspect: Check whether important decisions exist only in the compacted chat, then verify whether CLI transcript sync imported them.
Fix: Use MCP memory plus `ae sync run --source claude-code` for important decisions, issue context, and project rules.

C39 Claude Code compaction

C40

Agent contradicts earlier answers

Cause: Conflicting memories are retrieved together without source priority, supersession, or conflict inspection.
Inspect: Compare the disagreeing sources, timestamps, retrieval scores, and whether one memory should supersede another.
Fix: Add conflict metadata, mark old facts superseded, and require the agent to cite the current source before answering.

C40 contradictory memory

C41

Vector search returns noise or fabricated sources

Cause: The answer is generated from weak retrieval candidates, missing citations, or citation strings produced by the model rather than stored evidence.
Inspect: Check candidate relevance, citation IDs, source URLs, and whether every citation exists in the retrieved content set.
Fix: Use grounded retrieval, reject uncited claims, verify citations against stored artifacts, and show retrieval evidence to the user.

C41 noisy vector search

C42

Agent memory keeps growing or token cost rises

Cause: The system writes too much, retrieves too broadly, or resends raw context instead of curated source-aware memory.
Inspect: Measure memory write volume, duplicate facts, retrieval payload size, and repeated context sent per query.
Fix: Add write filters, summarization boundaries, lifecycle states, retrieval limits, and a cost review using the public calculator.

C42 memory bloat

C43

RAG leaks docs to the wrong users

Cause: Permissions are applied after retrieval or only in the app layer, so the vector layer can return out-of-scope candidates.
Inspect: Trace tenant_id, library scope, visibility filters, share rows, and prefilter IDs before the vector or hybrid search call.
Fix: Apply tenant and ACL filters before retrieval, join on tenant boundaries, and test cross-tenant negative cases.

C43 RAG oversharing

Fig. 3 labeled placeholder / product C.2

FIG. 3

Where is the live trace viewer?

The inspector is deliberately not presented as shipped on this resource page. The placeholder below labels the future product surface and the trace fields the debugging playbook depends on.

Labeled product placeholder

Live trace viewer

Roadmap until product C.2 inspector ships

The production inspector is not embedded here yet. This placeholder shows the fields the future trace viewer must expose: query, scope, candidates, ranks, citations, lifecycle state, and fix recommendation.

query: "why did the agent cite the old policy?" scope: tenant_id + library_id + visibility filter candidates: source id, rank, score, lifecycle state fix: supersede stale source and rerun retrieval

Fig. 4 current docs / external sources

FIG. 4

Which references ground the debugging model?

The catalog uses public protocol, memory, context, and conversation-state references plus the local troubleshooting posts.

Model Context Protocol debugging docs

Grounds tool/resource discovery, server capabilities, and transport-level debugging.

LangChain memory concepts

Separates short-term and long-term memory concepts used by the troubleshooting taxonomy.

Anthropic context engineering

Supports context curation and agent-context debugging framing.

OpenAI conversation state

Supports the distinction between model calls and application-managed state.

Fig. 5 FAQPage schema / visible answers

FIG. 5

FAQ

What is the fastest way to debug an agent memory failure?

Start with the symptom, then inspect the write path, retrieval candidates, source lineage, scope filters, lifecycle state, and final citations before changing the model prompt.

Is the live trace viewer available on this page?

No. The trace viewer shown here is a labeled placeholder until product C.2 ships the live inspector. The fields are listed so the debugging playbook stays useful now.

Which troubleshooting posts does this catalog cover?

It covers C35 through C43: forgetting between sessions, stale recommendations, wrong RAG results, deletion, Claude Code compaction, contradictions, fabricated citations, memory bloat, and RAG oversharing.

Should I fix memory failures by increasing the context window?

Only sometimes. Larger context can help a single run, but durable memory failures usually need source-aware writes, scoped retrieval, supersession, deletion, or inspection.

Debug memory failures from the trace outward.