Missing Memories

Before diving into specifics, here's the complete list of reasons a stored memory won't appear in query results. Check each one in order — the most common causes are at the top:

1. Environment / project mismatch — the memory was stored in a different environment or project than the one you are querying.
2. Billing silent mode — the organization hit its quota when the write was made. The write pipeline was skipped entirely — no memory was stored.
3. Importance below the retrieval threshold — the memory was stored but the platform did not consider it useful enough to surface during retrieval.
4. Superseded — a newer memory representing the same fact replaced it.
5. Deduplicated at ingestion — an identical input was already stored within the input-dedup window.
6. Deleted — the memory was explicitly deleted or expired by a retention policy.

When you submit a memory, the platform checks for an identical recently-submitted memory from the same user in the same environment. If one is found inside the dedup window, the new submission is treated as a duplicate.

What triggers dedup:

• Identical text content
• Same user
• Same environment
• Within a short time window of the original

What happens on dedup: The new submission is skipped — no new record is created. The API still returns a success response so the operation is idempotent from your code’s perspective.

When the platform extracts structured facts from your input, each fact has a type (for example, “preference”) and a key (for example, “favorite_color”). If a memory representing the same fact already exists for the same user, the older memory is superseded:

• The older memory is marked as deleted and is no longer returned by query endpoints.
• The older memory’s metadata records a pointer to the newer memory that replaced it.
• The newer memory becomes the active version for that fact.

Example: You send “The user’s favorite color is blue” and later “The user’s favorite color is green”. Both represent the same fact (favorite color). The “blue” memory is superseded by “green”, and querying “What is the user’s favorite color?” correctly returns only “green”.

How to check: If you can fetch the memory directly but it does not appear in queries, the dashboard surfaces whether it has been superseded and links to its replacement.

MemorySync uses soft deletion — memories are not immediately purged when deleted. They are marked as deleted and excluded from query results.

What triggers soft deletion:

• An explicit delete via the API.
• Supersede by a newer memory representing the same fact.
• Retention policy expiration (when configured for the tenant).
• Compaction of older short-term memories into a longer-term summary.

Memories also carry a retention status. Memories marked for expiration but not yet purged may still be visible via direct lookup while being excluded from query results.

Memories are scoped to both an environment and a project. These scoping constraints are enforced at the vector search level — memories from a different scope are never even loaded into the candidate pool.

Environment scoping:

• Memories stored in development are invisible to queries in production
• The environment is set by the API key or the request context
• There is no cross-environment query — this is a hard isolation boundary

Project scoping:

• Each project has its own namespace. Memory IDs, user scopes, and vector collections are project-isolated.
• Querying with an API key scoped to Project A will never return memories from Project B, even within the same organization.

The retrieval pipeline applies a minimum importance threshold. Memories with an importance below the threshold are excluded from query results regardless of how semantically relevant they are to your query.

How importance is set:

• Automatically at ingestion time, based on the platform’s assessment of the fact’s long-term utility.
• Manually, by updating the memory through the API.
• By re-evaluation, when the platform reassesses importance based on how often a memory is actually used.

The memory still exists. A low-importance memory is still stored and is still accessible via direct lookup — it simply does not surface in query results.

Fix: If a memory should be surfaced but is not, raise its importance via a memory update.

When an organization exceeds its monthly add or retrieval quota, MemorySync enters silent mode. This is not an error — it is a graceful degradation that keeps your application running without surfacing billing failures into the response.

What silent mode does:

• Add requests return 200 OK with the canonical success body. No memory is stored, embedded, or indexed — the write pipeline is skipped entirely.
• Query requests return 200 OK with an empty results array. The retrieval pipeline is skipped — no search is run.
• No error is surfaced to your application.

How to detect silent mode:

• Check your billing dashboard — if a metric is at 100% of its plan limit, additional requests for that metric are being silently degraded.
• Configure usage alerts in the dashboard so you are notified before a metric reaches 100%.

Recovery: When the billing cycle resets (or you upgrade your plan), new add requests are processed normally and new query requests return real results. Writes that were skipped during silent mode are not automatically replayed — if you need them, re-submit them after quota is restored. For a full explanation, see Billing → Silent Mode Explained.