dsh-memory-lite-alanzhao

English | 简体中文

Cross-session long-term memory for your dsh agent. Plain Markdown files, zero dependencies: preferences, decisions and constraints from a session survive restarts, upgrades and profile switches.

Every dsh session starts from a blank page — transcripts are persisted for audit, but the model never sees them again. This plugin adds that layer back: one resident memory catalog + 5 memory tools + background extraction.

Quick start (3 steps)

# 1. Install (= pnpm add inside the profile; the package is added to
#    dsh.profile.bundles automatically)
dsh plugin --profile web add @alanzhao/dsh-memory-lite

# 2. Restart dsh (the host half and the browser half load at boot)

# 3. Verify — the three checks below

After installing you should see:

• a memory-lite capsule in the session header: green = last extraction ok, gray = extraction off, red = last extraction failed
• a full settings page under Settings → memory-lite (screenshot below)
• ask the model to remember something ("remember that I use pnpm") — it calls remember and a file lands under ~/.agent-memory/peers/<peer>/memories/preferences/ (directories are created on first use)

Compatibility: dsh ≥ 0.1.5 (full support for dsh 0.2.1-rc.2 specification and engines constraint, seamless integration with Working Directory decoupling and managed Subagent Activation isolation; dual-track compatibility for 0.1.7+ SettingsForms/configForms, backward compatible to 0.1.5), Node ≥ 22.

Features

What it costs

Default triggers: 50 new conversation messages (windowTurns) or 30 minutes idle (idleTimeoutMin); turn-boundary and flush triggers are off by default.

Tip: extraction is a structured JSON task and needs no reasoning. Set reasoning effort = off — otherwise the model can spend the whole output budget thinking (two calls and 20–80 s per run).

Configuration

Everything is edited in Settings → memory-lite and stored under the dsh-memory-lite: section of ~/.dsh/settings.yaml. Most fields apply on save; root and sharing.* need a restart.

Full schema and defaults: src/config.ts.

What the memory looks like

~/.agent-memory/
├── peers/{peer}/
│   ├── memories/
│   │   ├── _index.md              # L0 catalog (generated; hand-editable)
│   │   ├── preferences/  entities/  events/  experiences/
│   │   │   └── {slug}.md          # L1 full text
│   └── sessions/                  # extraction bookmark + audit + extraction.log
└── .trash/                        # soft-deleted memories (dated folders)

Each memory file uses ## Current / ## History / ## Related; updates archive instead of overwriting. The four categories are retrieval paths for the model: preferences (always relevant), entities (mentioned knowledge), events (time-related), experiences (task lessons).

How it works (short version)

• Catalog injection: in the agent/pre-step waterfall the peer's _index.md is rendered into one user/message carrying the official plugin source kind with the catalog form; subagent sessions get none.
• Extraction: triggered by windowTurns or idle → select the window → grep existing memories for dedup → one LLM decision → write files → advance the per-session bookmark. A failed run keeps the bookmark, so the same window is retried on the next trigger.
• Safety: every file access goes through a containment boundary (relative paths only; .., absolute paths and symlink escapes are rejected at the executor).
• Concurrency: all writes go through a serial queue with atomic tmp+rename replacement.

Details (design tradeoffs, incident notes, known deviations) live in IMPLEMENTATION.md.

Troubleshooting

Uninstall

dsh plugin --profile web remove @alanzhao/dsh-memory-lite
# restart dsh

Your memories are not deleted: ~/.agent-memory is left for you to keep or remove.

Known limits

• forget_memory has no approval gate (the model can soft-delete directly).
• ## Related auto-maintenance is not implemented.
• No CLI / MCP entry point.
• The browser half (indicator + settings page) needs the web profile's connection service; under a headless profile the plugin still loads (tools + extraction work) and simply has no browser surfaces.
• Extraction quality depends on the model you pick; small models produce JSON that needs repair more often.

Changelog

v0.4.1

• DSH 0.2.1-rc.2 Specification & Engines Alignment: Declared "engines": { "dsh": ">=0.1.2-rc.1" } in package.json, adhering to the official priority evaluation of engines.dsh.
• Fixed Volatile Reference Validation Bug: Resolved ValidationError during installSettingsCompat by cleanly unwrapping volatile references with unwrapConfig.
• L0 Catalog Category Priority & Anti-Truncation: Enforced stable output priority in renderIndex (preferences -> entities -> experiences -> events) and expanded default index.maxTokens to 2000, preventing core rules and assets from being dropped by token budgets.
• Triple Gate for Background Extraction: Overhauled extractionSystem with a strict negative exclusion list, 30-day durability test, and aggressive merge requirement to eliminate over-extraction and memory fragmentation.

Development

npm install
npm run build     # tsc -> lib/
npm test          # node:test + tsx, including a real Loader boot smoke test

License

MIT