@xiaoke8698/dsh-memory-forget

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)

---

使用

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

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

// 记住（带保质期，插上记忆总线）
const v = memory.plug({
  content: '验证饮品是 lapsang',
  ttlMs: 60_000,
  kind: 'preference',
  tags: ['validation'],
})

// 健康度：活跃/陈旧/已遗忘 + token 占用
console.log(memory.status())

// 想起即续命（use it or lose it）
memory.recall('lapsang')

// 拔下（物理删除 + 审计；restorable 时审计保留副本）
memory.unplug({ id: v.id })

// 恢复（restorable 模式）：新 id、新 TTL、审计记 restored
const back = memory.restore(v.id)

// 预算内注入选择：死记忆（stale/forgotten）绝不入选
const sel = memory.selectForInjection(2000)

// 干跑预览（不 touch，token 对账用）
console.log(memory.preview())

持久化：引擎是内存态，提供 StoreAdapter 即可落盘（见上方英文版示例）。