# forget

通过用户拥有的 control boundary 删除经过审查的 memory、TODO 或 Ledger record；soft deletion 可恢复，hard deletion 永久生效。

- Canonical: https://docs.xmemo.dev/zh/docs/tools/forget
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: bb7f8a7e884de0a466e30a2d8258aa343fb87510c0c9530b1bf1ab2166c17e21
- Edition-Digest: 6e1d4de62035ee497fc904e432c93c5222c5bb95c665ca0867f51b19c52562a9
- Source-Revision: sha256:baae372498e8bb0029d0bb3dbb87a802d40981f421cdfa74d518c0c5e6352ed3

## Tool Reference: `forget`

### Purpose

通过用户拥有的 control boundary 删除选定的 memory、TODO 或 Ledger-backed record。Public contract 只涵盖 soft 和 hard deletion；要原地替换 content，请使用 redact_memory。

### Parameters

- `memory_id` (string, optional): 要移除的 record 的准确 reference。优先于 target。
- `target` (string, optional): 没有准确 reference 时使用的描述性 target。
- `mode` (string, optional, default: soft): 'soft'（默认，可恢复）或 'hard'（永久删除，事先需要明确的 user confirmation）。也接受 'soft_delete' 和 'hard_delete' alias，空值表示 soft。其他值都会被拒绝。
- `reason` (string, optional): 与删除一起记录的简短 audit reason。

### Returns

成功文本会报告受影响的 opaque reference 和 lifecycle status。Soft deletion 可通过 restore path 恢复；hard deletion 则不可恢复。

### Errors

- Validation failure：提供了除 'soft'/'soft_delete'/'hard'/'hard_delete' 以外的 mode，或设置了 replacement_content（请使用 redact_memory）。
- 401/403：token 缺少所需的 write/delete capability，或无法访问 target。
- Ambiguous target：query_hint 匹配多条 record，或无法确定准确 target。
- Invalid mode：不会推断 hard deletion，public surface 会拒绝不支持的 mode。
- Not found or lifecycle conflict：选定的 memory、TODO 或 Ledger record 已不存在或已发生变化。

### Examples

#### 可恢复地移除准确的 record



```typescript
forget({
  target: "memory-id-from-recall",
  mode: "soft",
  reason: "User requested removal"
})
```

### Related Tools

- [search_memory](/docs/tools/search): 在 destructive action 前查找严格且已授权的结果。
- [remember](/docs/tools/remember): 仅在确实需要时创建新的持久 record。
- [todos](/docs/tools/todos): 直接管理 task state；forget 只用于经过审查的删除。
- [ledger](/docs/tools/ledger): 通过受治理的 Ledger dispatcher 管理 financial record。

## 验证删除结果

重新运行之前返回该 memory 的 search。只有当该条目不再出现时，删除才算确认完成。

```ts
search_memory({ query: "<the removed content>", limit: 5 })
// -> the removed entry must be absent
```