diff --git a/apps/docs/memory-operations.mdx b/apps/docs/memory-operations.mdx
index 6f3906d51..f70a9b16d 100644
--- a/apps/docs/memory-operations.mdx
+++ b/apps/docs/memory-operations.mdx
@@ -121,28 +121,163 @@ Use **Create Memories** when you already know the exact facts to store (user pre
## Forget Memory
-Soft-delete a memory — excluded from search results but preserved in the system. Use this when you might want to restore later.
+Soft-delete a single memory — excluded from search results but preserved in the database. Identify it by `id` or by exact `content`, scoped to its `containerTag`.
```typescript
- await fetch("https://api.supermemory.ai/v4/memories/mem_abc123/forget", {
- method: "POST",
+ await fetch("https://api.supermemory.ai/v4/memories", {
+ method: "DELETE",
headers: {
- "Authorization": `Bearer ${API_KEY}`
- }
+ "Authorization": `Bearer ${API_KEY}`,
+ "Content-Type": "application/json"
+ },
+ body: JSON.stringify({
+ // Identify by ID or by exact content
+ id: "mem_abc123",
+ // content: "John prefers dark mode",
+ containerTag: "user_123",
+ reason: "outdated information"
+ })
});
```
```bash
- curl -X POST "https://api.supermemory.ai/v4/memories/mem_abc123/forget" \
- -H "Authorization: Bearer $SUPERMEMORY_API_KEY"
+ curl -X DELETE "https://api.supermemory.ai/v4/memories" \
+ -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "id": "mem_abc123",
+ "containerTag": "user_123",
+ "reason": "outdated information"
+ }'
```
-The memory will no longer appear in search results but remains in the database.
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | * | Memory ID to forget |
+| `content` | string | * | Exact content match to forget (alternative to ID) |
+| `containerTag` | string | yes | Container tag / space the memory belongs to |
+| `reason` | string | no | Optional reason recorded as `forgetReason` |
+
+\* Either `id` or `content` must be provided.
+
+The memory will no longer appear in search results but remains in the database (`isForgotten=true`).
+
+---
+
+## Forget Matching
+
+Forget **everything** about a topic in one call. You give a prompt or a query; the service semantically searches the container's memories, an LLM decides which ones are genuinely about your target, and those are soft-deleted. Use this for "forget everything about X" rather than deleting memories one by one.
+
+
+This is a bulk, destructive operation. Always **`dryRun` first** to review what would be forgotten, then re-run with `dryRun: false`. The match is semantic, so a too-broad query can select more than you intend — `threshold` and `maxForget` bound the blast radius.
+
+
+
+
+ ```typescript
+ // 1) Preview
+ const preview = await fetch("https://api.supermemory.ai/v4/memories/forget-matching", {
+ method: "POST",
+ headers: {
+ "Authorization": `Bearer ${API_KEY}`,
+ "Content-Type": "application/json"
+ },
+ body: JSON.stringify({
+ query: "forget everything about Project Titan",
+ containerTag: "user_123",
+ dryRun: true
+ })
+ }).then((r) => r.json());
+ // preview.candidates → [{ id, memory, score }, ...]
+
+ // 2) Apply
+ const result = await fetch("https://api.supermemory.ai/v4/memories/forget-matching", {
+ method: "POST",
+ headers: {
+ "Authorization": `Bearer ${API_KEY}`,
+ "Content-Type": "application/json"
+ },
+ body: JSON.stringify({
+ query: "forget everything about Project Titan",
+ containerTag: "user_123",
+ dryRun: false,
+ reason: "project cancelled"
+ })
+ }).then((r) => r.json());
+ // result.forgotten → [{ id, memory, score }, ...]
+ // result.forgetBatchId → tagged on every forgotten memory for traceability
+ ```
+
+
+ ```bash
+ # Preview
+ curl -X POST "https://api.supermemory.ai/v4/memories/forget-matching" \
+ -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "query": "forget everything about Project Titan",
+ "containerTag": "user_123",
+ "dryRun": true
+ }'
+
+ # Apply
+ curl -X POST "https://api.supermemory.ai/v4/memories/forget-matching" \
+ -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "query": "forget everything about Project Titan",
+ "containerTag": "user_123",
+ "dryRun": false,
+ "reason": "project cancelled"
+ }'
+ ```
+
+
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | string | yes | What to forget — a natural-language instruction ("forget everything about Project Titan") or a bare topic ("Project Titan") |
+| `containerTag` | string | yes | Container tag / space to scope the operation to |
+| `dryRun` | boolean | no | When `true`, returns what *would* be forgotten without changing anything. Defaults to `false` |
+| `threshold` | number | no | Similarity floor (0–1) for candidate memories. Lower casts a wider net. Defaults to `0.5` |
+| `maxForget` | number | no | Safety cap on how many memories may be forgotten in one call (1–500). Defaults to `100` |
+| `reason` | string | no | Reason recorded as `forgetReason` on each forgotten memory |
+
+### Response
+
+```json
+{
+ "dryRun": false,
+ "count": 3,
+ "forgetBatchId": "VcuQoGRz4hA4ak5Xu6DRUN",
+ "summary": "Forgot 3 memories about \"Project Titan\".",
+ "forgotten": [
+ { "id": "mem_1", "memory": "Project Titan ships in Q3", "score": 0.82 }
+ ]
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `dryRun` | boolean | Whether this was a preview or a real forget |
+| `count` | number | Number of memories selected (dryRun) or forgotten (apply) |
+| `forgetBatchId` | string \| null | ID tagged on every memory forgotten in this call; `null` on dryRun |
+| `summary` | string | One-line summary of the operation (e.g. `Forgot 3 memories about "Project Titan".`) |
+| `candidates` | array | On `dryRun`: the memories that **would** be forgotten (`{ id, memory, score }`) |
+| `forgotten` | array | On apply: the memories that **were** forgotten (`{ id, memory, score }`) |
+
+
+Identity is server-owned: the LLM only ever references opaque handles for the memories a search returned, so it can never forget a memory outside the results it reviewed, and every operation is scoped to the `containerTag` you pass.
+
---