Users & agents

Delete an agent

Hard-delete an agent namespace in the key's project: purge every memory and fact stored under it. This frees its cap slot unless another project of the account still holds the name.

SDK: korely.delete_agent(agent_id). The Glossary defines the words used across the docs.

This is a hard delete (a purge), not the soft forget used elsewhere. Forgetting memories never frees a slot: the cap counts every row that carries the agent_id, forgotten and closed rows included. A slot frees when no row carrying the name is left in the account: deleting the namespace is the direct way.

Authentication

HTTP header, required: Authorization: Bearer kor_live_.... The key must carry the memories:write permission (the API calls it a scope).

Path parameter

This endpoint takes no query parameters and no request body.

Example request

curl -X DELETE https://api.korely.ai/v1/agents/support-triage \
  -H "Authorization: Bearer kor_live_..."

from korely_memory import Korely

korely = Korely(api_key="kor_live_...", region="eu")

receipt = korely.delete_agent("support-triage")

print(receipt.memories_deleted, receipt.facts_deleted)  # 4 9
print(receipt.audit_id)  # "aud_9f44c1d27b0a4e1c8d5f3a6b2e7c9d10"

import { Korely } from "korely-memory";

const korely = new Korely({ apiKey: "kor_live_..." });

const receipt = await korely.deleteAgent("support-triage");

console.log(receipt.memories_deleted, receipt.facts_deleted); // 4 9
console.log(receipt.audit_id); // "aud_9f44c1d27b0a4e1c8d5f3a6b2e7c9d10"

Response

200 OK. The purged namespace plus the counts of rows hard-deleted and the id of the audit record.

{
  "agent_id": "support-triage",
  "memories_deleted": 4,
  "facts_deleted": 9,
  "facts_reopened": 0,
  "audit_id": "aud_9f44c1d27b0a4e1c8d5f3a6b2e7c9d10"
}

The server sends no slot_freed field. The SDKs' receipts have a field of that name, and it stays empty: to see whether the slot is free, read cap and used in List agents.

Errors

Notes

• Hard delete, not forget. This is a purge, distinct from the soft forget endpoints. Soft-forgotten rows still count against the agent cap, so forgetting never frees a slot.
• Frees the cap slot. The cap set counts any row carrying the agent_id, including soft-deleted and invalidated rows. A slot frees when no row carrying the name is left in the account: deleting the namespace is the direct way. The cap counts a name across the account (queued batches included), so the slot is free only when no other project of the account still uses this agent_id; GET /v1/agents (cap, used) shows it.
• Facts go first. Facts are deleted by agent_id directly, so facts written straight to /v1/facts with no source memory are purged too. A fact's source_memory_id is ON DELETE CASCADE.
• Also removed. The names declared in that namespace (Declare a name with its agent_id) and the items of POST /v1/batch imports that name the agent, which are scrubbed from the import, queued or finished, so a queued import does not write the agent back.
• The end user's data under other agents stays. Only this namespace is purged. To erase one end user across every agent, use Erase a user.
• Audited. The purge leaves a receipt (audit_id) and an erase event in the audit log, counts only.
• Write scope required. The key must carry memories:write. A confined key cannot delete a namespace, because a namespace spans every end user.

Related

• List agents, enumerate the namespaces of this key's project before deleting one.
• Erase a user, the permanent end-user-scoped erasure (it frees an agent slot only if no row carrying that agent_id remains in the account).
• SDK reference, the full surface across cURL, Python, and Node.