forget_many

Delete 1–100 facts in one call. Prefer this over looping forget.

POST/v1/forget_many

Also an MCP tool named forget_many.

Find the facts with recall first. Each item names one fact exactly like forget.

The call is best effort. Facts that are found are deleted together in one transaction. Items that delete nothing come back in failed, and the response is still 200.

Request

{
  "facts": [
    { "subject": "user:maya", "predicate": "works_at", "ref": "X2C9A" },
    { "subject": "user:maya", "predicate": "has_skill", "ref": "Q7M2D" },
    { "subject": "user:maya", "predicate": "works_at", "ref": "X2C9A" }
  ]
}

Response

deleted lists the removed facts. failed lists the items that deleted nothing, sorted by index (the item's position in facts). Both are always arrays.

{
  "deleted": [
    { "id": "01KJ8Z3W5Q2YB7N4R6T8VX2C9A", "ref": "X2C9A", "subject": "user:maya", "predicate": "works_at", "object": "company:acme" }
  ],
  "failed": [
    { "index": 1, "subject": "user:maya", "predicate": "has_skill", "ref": "Q7M2D", "error": "fact not found" },
    { "index": 2, "subject": "user:maya", "predicate": "works_at", "ref": "X2C9A", "error": "same fact as an earlier item" }
  ]
}

| error | When | |:--|:--| | fact not found | No fact matches | | multiple facts match subject, predicate, and ref | Two facts share the ref. Pass the full id as ref | | ref must be the last 5 characters of a fact id, or the full id | ref is not 5 or 26 id characters | | same fact as an earlier item | An earlier item already names this fact. It is deleted once |

MCP returns deleted (the count), a facts_deleted table with the same columns as recall when something was deleted, and a failed table only when an item failed.

Errors

| Status | When | |:--|:--| | 400 | facts is empty or holds more than 100 items, or an item misses subject, predicate, or ref | | 404 | Unknown collection |

Each item is billed like one forget call, and the call runs under the same limits as forget. forget_many never deletes an entity. Use forget_entity to remove everything about one.