POST /v1/forget

Remove memories from CortexDB. Matching entities and their relationship edges are immediately excluded from recall and search results. Every forget operation is tracked in the audit trail.

Usage

from cortexdb import Cortex

client = Cortex(api_key="your-api-key")

result = client.forget(
    query="old migration notes",
    reason="Decision reversed",
    tenant_id="my-app"
)

print(result.forgotten_entities)  # 3
print(result.forgotten_edges)     # 7
print(result.audit_id)            # "aud_abc123"

import { CortexDB } from "cortexdbai";

const client = new CortexDB({ apiKey: "your-api-key" });

const result = await client.forget(
    "old migration notes",
    "Decision reversed",
    "my-app"
);

console.log(result.forgottenEntities);  // 3
console.log(result.forgottenEdges);     // 7
console.log(result.auditId);           // "aud_abc123"

curl -X POST https://api.cortexdb.ai/v1/forget \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "old migration notes",
    "reason": "Decision reversed",
    "tenant_id": "my-app"
  }'

Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | query | string | Yes | Pattern or identifier of memories to forget | | reason | string | Yes | Human-readable justification for the deletion | | tenant_id | string | Yes | Tenant identifier |

Response

{
  "forgotten_entities": 3,
  "forgotten_edges": 7,
  "audit_id": "aud_abc123"
}

| Field | Type | Description | |---|---|---| | forgotten_entities | integer | Number of entities removed from recall | | forgotten_edges | integer | Number of relationship edges removed | | audit_id | string | Audit trail identifier for this operation |

Errors

| Status | Code | Description | |---|---|---| | 400 | validation_error | Missing required fields | | 401 | authentication_error | Invalid or missing API key | | 429 | rate_limit | Too many requests |

What happens under the hood

Both the Python and TypeScript SDKs wrap a POST /v1/forget REST call. The SDK handles authentication (reading CORTEX_API_KEY from your environment if not passed explicitly), serializes the request, and deserializes the response into a typed object. The forget is immediate -- forgotten memories are excluded from all subsequent recall queries. The original events remain in the immutable event log for audit purposes.