Debugging / Deduplication

Duplicate Writes

Near-identical writes can be ignored on purpose. The response tells you when that happened, so you can stop guessing whether a write landed.

Response

What the response tells you

A write returns one of three shapes. All three are HTTP 200, so the body is what tells you whether a record was created.

{
  "id": -1,
  "text": "",
  "summary": "Deduplicated memory ignored"
}

Nothing new was written because a near-identical memory already exists in this scope. The id is -1, which is the signal to check for — treat it as “already known”, not as an error.

result = ms.add(text, tags=["preference"])

if getattr(result, "id", None) == -1:
    pass            # already known — nothing to store, nothing to fix
else:
    save_reference(result.id)

Behavior

How deduplication is scoped

Same scope only: Duplicate detection compares against active memories in the same project and environment. It never compares across projects.
Similarity, not exact text: A reworded version of an existing memory can be treated as a duplicate, which is usually what you want for repeated facts.
Opt out per request: Deduplication can be turned off for a write when you deliberately want every occurrence recorded.
Fails open: If similarity cannot be evaluated, the write proceeds rather than being dropped — so a rare duplicate is possible by design.

If you are seeing genuine duplicates, check whether the writes carry slightly different text each time, or whether they are landing in different scopes.

← Previous

Wrong Results

Webhook Failures