dsh-memory-forget — The Forgetting Engine for AI Agents

Name: XIAOke8698/dsh-memory-forget
Author: XIAOke8698

English · 中文

Remember less. Think clearer.

Forgetting engine for AI agents: memory TTL, decay, eviction, audit. The opposite of memory programming. Zero-dependency core, MIT.

Memory programming is everywhere: Mem0, Letta, Engram all teach agents to remember everything. dsh-memory-forget does the opposite — it turns forgetting from an accident into a design: every memory has a shelf life, dies on schedule, is fully audited, and is injected under a hard token budget.

One-line difference: memory engines answer "how to store and retrieve well"; dsh-memory-forget answers "when to forget, which memory is still trustworthy, how much goes into context, and what is actually in there".

This is not contrarianism — there is evidence: agents get dumber with use, memory pollution is a main cause (CUHK & ZJU); memory poisoning is a real attack class (single-email persistent poisoning, stealthy memory injection). Forgetting is not memory's failure mode — it is memory's governance.

Install

npm install @xiaoke8698/dsh-memory-forget

Node >= 20, zero dependencies, ESM.

Usage

import { AmnesiaEngine } from '@xiaoke8698/dsh-memory-forget'

const memory = new AmnesiaEngine({ restorable: true })

// remember with a shelf life (plug into the memory bus)
const v = memory.plug({
  content: 'validation drink is lapsang',
  ttlMs: 60_000,
  kind: 'preference',
  tags: ['validation'],
})
console.log(v.id, v.expiresAt) // m-xxx 1787469261044

// health readout: active/stale/forgotten counts + token footprint
console.log(memory.status())

// recall renews the decay clock — use it or lose it
memory.recall('lapsang')      // matches + touches (sliding TTL)

// forget (unplug): physical delete; audit keeps hash only (content if restorable)
memory.unplug({ id: v.id })

// restore a forgotten memory (restorable mode): new id, new TTL, audit reason 'restored'
const back = memory.restore(v.id)

// budgeted injection selection: dead (stale/forgotten) memories are NEVER selected
const sel = memory.selectForInjection(2000)
console.log(sel.tokens, sel.skippedDead)

// dry-run preview for token cost accounting (does not touch)
console.log(memory.preview())

Persistence

The engine is in-memory; provide a StoreAdapter for durability:

import { readFile, writeFile } from 'node:fs/promises'
import { AmnesiaEngine } from '@xiaoke8698/dsh-memory-forget'

const memory = new AmnesiaEngine({ restorable: false }, {
  async load() {
    try { return JSON.parse(await readFile('memories.json', 'utf8')) }
    catch { return undefined }
  },
  async persist(items, audit) {
    await writeFile('memories.json', JSON.stringify({ items, audit }))
  },
})
await memory.ready

API

Method	Meaning
`plug(input)`	remember with TTL / pin / scope / tags
`unplug(filter)`	forget (by id / query / tags) — physical delete + audit
`touch(id)`	access: renew the decay clock (sliding TTL)
`recall(query?)`	recall matching active memories and renew each
`restore(id)`	plug a forgotten memory back in (restorable mode)
`selectForInjection(budget)`	budgeted selection; dead memories excluded
`preview()`	dry-run injection preview (token ledger, no touch)
`status()`	counts + token footprint + next expiry + recent audit
`auditView(limit)`	forget/restore trail (hash only, never content body)
`sweep()`	settle all items; expire dead ones (call on turn end)

Features

Feature	Description
Pluggable memory bus	remember = plug in; forget = unplug — physical delete, no ghost references. Forgetting is a protocol operation, not a failure
Shelf life	every memory has TTL + decay curve (Ebbinghaus): active → stale → forgotten
Importance: declared or earned	`pin: true` = explicit forever; or earn it by usage — sliding renewal (use it or lose it): used memories never expire, idle-for-a-full-TTL memories die
Recoverable	`restore(id)` (restorable mode) plugs a forgotten memory back in (new id, new TTL, audited `restored`); in privacy mode re-`remember` instead (audit hash lets you verify it is the same content)
Audit, hash only	who/what/when/why forgotten or restored; content physically deleted by default, audit keeps SHA-256
Hard injection budget	per-step ≤ `maxInjectedTokens` (default 2000); dead memories never injected; over budget = select less, never truncate
Token ledger	`status()` reports last-injection accounting; `preview()` is a non-touching dry run
Lightweight	zero embedding, zero LLM extraction/rewriting (zero generation cost on write), zero server process
Privacy first	physical deletion by default; recoverability vs. clean deletion is an explicit config switch
Multi-agent scoping	scope: workspace / session / team; a sub-agent's temp memories are auto-unplugged when it dies, never inherited by default

Evaluation: design, status, and an honest statement

Benchmark design (three-arm, same model, same task set — only the forgetting policy changes):

Arm	Condition
A	no memory (cold start every task)
B	full memory (write forever, never forget — typical memory-plugin behavior)
C	Amnesia (write with TTL + decay)

Fairness key: B and C share the same store and retrieval (deterministic strength-ranked selection) — only the forgetting policy is toggled. Memory vendors cannot run this A/B because they cannot turn off their own memory.

Metrics: cumulative context tokens, task success rate, stale-error rate (a written fact changes mid-task; how often does each arm use the outdated fact), steps/time, recall benefit on memory-helps tasks. Task sets: memory-helps (multi-turn preferences, repeated context), memory-hurts (changed facts, expired constraints, poisoned memories), mixed. Full design: docs/design.md §11.

Status: NO comparative results exist yet (M3 not run). What is verified (M1 dynamic-plugin validation) is that the mechanisms work — expiry, restore, audit, budgeted injection, sliding renewal — not that forgetting improves agent outcomes. Until M3 produces data, effectiveness claims rest on the cited research, not on measurements of this package. We will publish the benchmark numbers the moment they exist, with methodology and task sets attached.

Roadmap

Current release v0.1.0 ships the core engine only (AmnesiaEngine: bus / decay / audit / selection). Not included yet: DSH Cordis plugin adapter, CLI, skill, MCP server, Client UI, benchmark results.

M0 Design — positioning, architecture, milestones (docs/design.md)
M1 Dynamic-plugin validation (session-scoped DSH plugin, memf-1)
- M1.1 core engine (bus / decay / audit)
- M1.2 service + storage (fs persistence; formal package → storageDomain)
- M1.3 tool surface (7 tools)
- M1.4 lifecycle hooks (turn-end sweep / disposed auto-unplug)
- M1.5 injection + budget (pre-step snapshot message + token ledger + preview)
- M1.6 acceptance (DoD 1-5; DoD 5 sub-agent auto-unplug pending real-subagent test)
M2 Client UI — composer readout / memory-node view (draggable unplug) / settings
M3 Three-arm benchmark — cumulative tokens, success rate, stale-error rate
M4 DSH official bundle + skill/CLI — dsh plugin add installs the DSH plugin (official bundle mechanism); skill + CLI for other agents
M5 Value-add — /amnesia command, auto-suggestion (opt-in), deeper visualization
M6 MCP server (far future, no commitment)
Open questions: Q1 forgetting aggressiveness / Q2 auto-extraction / Q3 semantic retrieval / Q4 target users / Q5 benchmark task set / Q6 distribution shape

Integration with other agents

DSH users (planned, M4): official bundle — once shipped, install with one command: dsh plugin --profile <name> add @xiaoke8698/dsh-memory-forget (official DSH bundle mechanism: npm package + dsh.bundle + cordis.patch.yml; see DSH docs docs/user/develop/basic/publish.md).

Planned: skill + local CLI (M4) — one SKILL.md (Anthropic Agent Skills format, shared by Claude Code / Codex / DSH) + a local CLI: copy-and-use, no network, no background process. Claude Code: ~/.claude/skills/dsh-memory-forget/; DSH: skills dir; Codex: skills / AGENTS.md.

Far future: MCP server (M6) — needs server hosting; not committed.

Status: skill / CLI are not shipped yet. Today the npm package is the core engine; the DSH dynamic plugin is the session-scoped validation form.

Docs & Research

Full design doc: docs/design.md (§13 architecture, §14 minimal real validation log)
Ecosystem basis: DSH has compaction (compression) but no delete/expiry/eviction semantics; memory systems are third-party MCP examples only (off by default)
Agents get dumber with use, memory pollution (CUHK & ZJU)
Memory governance: MemArchitect
Memory poisoning: MemGhost / MemIncept (ICML 2026)

dsh-memory-forget — The Forgetting Engine for AI Agents

English · 中文

Remember less. Think clearer.

Forgetting engine for AI agents: memory TTL, decay, eviction, audit. The opposite of memory programming. Zero-dependency core, MIT.

Install

npm install @xiaoke8698/dsh-memory-forget

Node >= 20, zero dependencies, ESM.

Usage

import { AmnesiaEngine } from '@xiaoke8698/dsh-memory-forget'

const memory = new AmnesiaEngine({ restorable: true })

// remember with a shelf life (plug into the memory bus)
const v = memory.plug({
  content: 'validation drink is lapsang',
  ttlMs: 60_000,
  kind: 'preference',
  tags: ['validation'],
})
console.log(v.id, v.expiresAt) // m-xxx 1787469261044

// health readout: active/stale/forgotten counts + token footprint
console.log(memory.status())

// recall renews the decay clock — use it or lose it
memory.recall('lapsang')      // matches + touches (sliding TTL)

// forget (unplug): physical delete; audit keeps hash only (content if restorable)
memory.unplug({ id: v.id })

// restore a forgotten memory (restorable mode): new id, new TTL, audit reason 'restored'
const back = memory.restore(v.id)

// budgeted injection selection: dead (stale/forgotten) memories are NEVER selected
const sel = memory.selectForInjection(2000)
console.log(sel.tokens, sel.skippedDead)

// dry-run preview for token cost accounting (does not touch)
console.log(memory.preview())

Persistence

The engine is in-memory; provide a StoreAdapter for durability:

import { readFile, writeFile } from 'node:fs/promises'
import { AmnesiaEngine } from '@xiaoke8698/dsh-memory-forget'

const memory = new AmnesiaEngine({ restorable: false }, {
  async load() {
    try { return JSON.parse(await readFile('memories.json', 'utf8')) }
    catch { return undefined }
  },
  async persist(items, audit) {
    await writeFile('memories.json', JSON.stringify({ items, audit }))
  },
})
await memory.ready

API

Method	Meaning
`plug(input)`	remember with TTL / pin / scope / tags
`unplug(filter)`	forget (by id / query / tags) — physical delete + audit
`touch(id)`	access: renew the decay clock (sliding TTL)
`recall(query?)`	recall matching active memories and renew each
`restore(id)`	plug a forgotten memory back in (restorable mode)
`selectForInjection(budget)`	budgeted selection; dead memories excluded
`preview()`	dry-run injection preview (token ledger, no touch)
`status()`	counts + token footprint + next expiry + recent audit
`auditView(limit)`	forget/restore trail (hash only, never content body)
`sweep()`	settle all items; expire dead ones (call on turn end)

Features

Feature	Description
Pluggable memory bus	remember = plug in; forget = unplug — physical delete, no ghost references. Forgetting is a protocol operation, not a failure
Shelf life	every memory has TTL + decay curve (Ebbinghaus): active → stale → forgotten
Importance: declared or earned	`pin: true` = explicit forever; or earn it by usage — sliding renewal (use it or lose it): used memories never expire, idle-for-a-full-TTL memories die
Recoverable	`restore(id)` (restorable mode) plugs a forgotten memory back in (new id, new TTL, audited `restored`); in privacy mode re-`remember` instead (audit hash lets you verify it is the same content)
Audit, hash only	who/what/when/why forgotten or restored; content physically deleted by default, audit keeps SHA-256
Hard injection budget	per-step ≤ `maxInjectedTokens` (default 2000); dead memories never injected; over budget = select less, never truncate
Token ledger	`status()` reports last-injection accounting; `preview()` is a non-touching dry run
Lightweight	zero embedding, zero LLM extraction/rewriting (zero generation cost on write), zero server process
Privacy first	physical deletion by default; recoverability vs. clean deletion is an explicit config switch
Multi-agent scoping	scope: workspace / session / team; a sub-agent's temp memories are auto-unplugged when it dies, never inherited by default

Evaluation: design, status, and an honest statement

Benchmark design (three-arm, same model, same task set — only the forgetting policy changes):

Arm	Condition
A	no memory (cold start every task)
B	full memory (write forever, never forget — typical memory-plugin behavior)
C	Amnesia (write with TTL + decay)

Roadmap

M0 Design — positioning, architecture, milestones (docs/design.md)
M1 Dynamic-plugin validation (session-scoped DSH plugin, memf-1)
- M1.1 core engine (bus / decay / audit)
- M1.2 service + storage (fs persistence; formal package → storageDomain)
- M1.3 tool surface (7 tools)
- M1.4 lifecycle hooks (turn-end sweep / disposed auto-unplug)
- M1.5 injection + budget (pre-step snapshot message + token ledger + preview)
- M1.6 acceptance (DoD 1-5; DoD 5 sub-agent auto-unplug pending real-subagent test)
M2 Client UI — composer readout / memory-node view (draggable unplug) / settings
M3 Three-arm benchmark — cumulative tokens, success rate, stale-error rate
M4 DSH official bundle + skill/CLI — dsh plugin add installs the DSH plugin (official bundle mechanism); skill + CLI for other agents
M5 Value-add — /amnesia command, auto-suggestion (opt-in), deeper visualization
M6 MCP server (far future, no commitment)
Open questions: Q1 forgetting aggressiveness / Q2 auto-extraction / Q3 semantic retrieval / Q4 target users / Q5 benchmark task set / Q6 distribution shape

Integration with other agents

Far future: MCP server (M6) — needs server hosting; not committed.

Status: skill / CLI are not shipped yet. Today the npm package is the core engine; the DSH dynamic plugin is the session-scoped validation form.

Docs & Research

Full design doc: docs/design.md (§13 architecture, §14 minimal real validation log)
Ecosystem basis: DSH has compaction (compression) but no delete/expiry/eviction semantics; memory systems are third-party MCP examples only (off by default)
Agents get dumber with use, memory pollution (CUHK & ZJU)
Memory governance: MemArchitect
Memory poisoning: MemGhost / MemIncept (ICML 2026)

XIAOke8698/dsh-memory-forget

dsh-memory-forget — The Forgetting Engine for AI Agents

Install

Usage

Persistence

API

Features

Evaluation: design, status, and an honest statement

Roadmap

Integration with other agents

Docs & Research

Community comments

XIAOke8698/dsh-memory-forget

dsh-memory-forget — The Forgetting Engine for AI Agents

Install

Usage

Persistence

API

Features

Evaluation: design, status, and an honest statement

Roadmap

Integration with other agents

Docs & Research

Community comments