dsh-memory-forget

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.

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 (DSH plugin — official bundle)

dsh plugin --profile <name> add @xiaoke8698/dsh-memory-forget

Uninstall: dsh plugin --profile <name> remove @xiaoke8698/dsh-memory-forget (memories stay in the workspace file .dsh-memory-forget/store.json; delete that directory to wipe them).

For developers using the engine as a library: 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.2.1 ships the core engine + the DSH official bundle (AmnesiaEngine + Cordis plugin adapter). Not included yet: 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 — shipped in 0.2.1; install with dsh plugin add (official bundle mechanism)
• M4b skill + local CLI — for other agents (Claude Code / Codex / DSH), zero server
• 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 — installed via the official bundle mechanism (see Install above; dsh.bundle + cordis.patch.yml, DSH docs docs/user/develop/basic/publish.md).

Planned: skill + local CLI (M4b) — 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 + DSH official bundle; the DSH dynamic plugin was 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)