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.

Was this page helpful?

← Previous

Wrong Results

Webhook Failures