dsh-engram

English · 中文

Minimalist long-term memory for DeepSeek Harness, distilled from the symbolic-index and pi-esr ideas — with one goal: save tokens.

• Zero-LLM intake — auto-captures meaningful events from tool results by pure pattern matching (git milestones with a written -m commit message, edits to key files, repeated errors), plus an explicit engram_store. Nothing on the hot path calls a model, and pure plumbing — git push / git stash / silent commits — is deliberately never recorded (see Auto-capture policy below). Every write is run through a deterministic secret redactor first — API keys, JWTs, Bearer tokens, private keys, AWS/Stripe/Slack/GitHub tokens and key=value secret shapes are replaced with <REDACTED:…> markers before the dedup hash, the char cap, and storage, so sensitive text can never land on disk. Failing test runs are recognized by pure patterns (npm test, node --test, vitest/pytest/jest, failure lines) and captured as tags:["error","test"] entries with a raised signal. DSH goal-domain integration: a completed or blocked goal (goal/change session event) auto-sediments as a handoff/error memory (tag:goal), so the outcome of a goal survives its session (see the GET /api/dsh-engram/goals read surface).
• User-correction / preference learning (autoCapturePreferences, default on, zero LLM) — the lesson that "when the AI makes a mistake and gets corrected, that lesson should persist" (correx, PAHF, Mem0 preference extraction): a session/event listener watches user/message and turns deterministic correction/preference cues into a dedicated preference memory kind — Chinese (不要用X, 改用X, 以后统一用X…) and English (don't use X, switch to X, prefer X, never use X…) patterns, three directions (avoid / switch-to / prefer), with interrogative/one-shot-instruction/ memory-tool-meta-talk filters to keep false positives out. preference memories outrank every other kind in the [ENGRAM] block ([R] prefix) so a standing user rule is the first line the model sees each session; per-session cap + recent-window dedup mirror the auto-capture discipline. Zero LLM, zero embeddings, deterministic and pure — extracted clauses are bounded, and every write still goes through the secret redactor.
• Symbolic index + progressive disclosure — a compact [ENGRAM] block (default budget 700 chars ≈ 175 tokens; one line per memory) is injected at prompt assembly and frozen per session, keeping the request prefix byte-stable for KV-cache reuse. The agent drills down with engram_recall / engram_detail instead of dumping raw hits into context; recall ranks the in-domain pool with an in-process BM25 pass (TF·IDF with label/phrase boosts plus a gentle time-decay factor — deterministic, zero deps), appends a compact entity-neighborhood table (reusing esr_link: node --rel--> node · conf%) for entity-anchored hits, re-warms the old error entry when a new failure is near-identical (repeat-failure revival: recency + hit climb toward promoteHits so the failure resurfaces instead of piling up), and on zero local hits falls back to DSH's own cross-session full-text index (ctx.sessionQuery, filtered by cwd) instead of building a parallel SQLite index; when the FTS fallback also comes back empty and the query contains CJK characters (Chinese FTS5 tokenization), recall runs a bounded substring scan over the newest session logs (zstd-decompressed, LRU-cached) and appends matched past sessions — deterministic # past sessions lines, capped files and bytes.
• Session-start auto-recall (autoRecallOnStart, default on) — the pull-only design had a gap proven in real use: recall tools relied on model initiative, and in practice the model almost never calls engram_recall on its own (19 real sessions, thousands of tool calls, ~5 recall calls total). So at the FIRST assembly of a new session the host runs one deterministic BM25 recall keyed on the session's first user message and injects the top ≤ autoRecallLimit hits as a [RECALL] block (default 700-char budget, "few and precise" — agentmemory candidate ①). Relevant memory is in context even without a single recall call. Pure rule, zero LLM, pure read (never bumps hits); superseded stale truth does not occupy an injection slot (still fetchable via engram_detail); frozen per session together with [ENGRAM] for prefix stability.
• Read-path activation (D) — a hit whose one-line preview is truncated (>140 chars) carries a … marker and the block's trailing guidance names that concrete id: #<id> truncated — engram_detail <id> (full) · engram_recall <query>. So the model knows the full record is one deterministic engram_detail call away instead of assuming the preview is the whole memory (proven gap in real use: 66 sessions, zero engram_detail calls — the detail path was invisible).
• Memory-to-memory semantics — engram_store accepts optional supersedes / contradicts memory ids (validated against the same workspace). A superseded ("stale truth") memory is demoted to the tail of recall and excluded from the [ENGRAM] block, while the superseding statement keeps the line; a contradicted memory stays ranked but is flagged · contradicted by <id>. Old rows are never deleted — re-fetchable, just honestly ranked. Opt-in autoSupersede config (default off) auto-marks entity-anchored replacement updates ("改用 / no longer / switched…") as superseding their matching older row; explicit supersedes always wins.
• Failure→fix closure (zero LLM) — error memories carry a cmd: signature tag; when that same command later succeeds, engram auto-sediments a procedure memory (fixed: <cmd> — N earlier failing runs now succeed), tags the earlier error rows resolved (never re-ranking them), and recall then surfaces the fix instead of the stale failure.
• ESR-lite closure protocol — esr_task / esr_close / esr_link give tasks a draft → active → stable lifecycle where stable requires real evidence (artifact / evaluation / memory_ref), surfacing closure gaps instead of letting the agent declare victory without proof. With verifyArtifact on (default), a non-URL artifact is resolved against the workspace (= the session cwd) and must exist on disk — otherwise the task stays ACTIVE with the reason; force:true (or disabling the toggle) skips the disk check, the three gates are still mandatory. The tool and the web forms share one gate (store.evidenceGate), so the two surfaces can never drift. Tasks are never isolated graph nodes: esr_task(entity=…) one-call wiring auto-creates the ent_<slug> node and hangs the task on it (task --relates_to--> entity, idempotent), so a task created with a domain anchor immediately shows a relation; and esr_dep writes the dependency edge into both the task's deps (blocker logic) and the shared links table, making every task dependency a first-class visible edge in the graph.
• ESR trigger mechanism (pi-esr-aligned, hybrid: static protocol + frozen snapshot + monotonically accumulated actionables + pull) — prefix-cache stability is the point. Teaching the model WHEN to use ESR is a static methodology section (byte-identical every turn); the [ESR] block is a deterministic per-session frozen snapshot (set at session start, deterministically sorted, timestamps excluded, explicitly "WILL NOT auto-refresh") plus the session's monotonically accumulated actionables: the promote: / root-cause: / close: / stale: / escalate: lines are APPENDED exactly once, the moment each matures, and stay frozen for the rest of the session (never removed) — so the prefix changes only when genuinely new decision-point info appears, never per-turn, while the timely nudges (narrow funnel / recurring failure / work done / stale / balance) stay in context. Live state is still pulled via esr_status (full deterministic view + since_revision short "unchanged" response + derived actionables). The tools/result recorder feeds the actionables' data sources; P4 conversion metering stays (#suggest-* tags + 10-minute attribution + GET /api/dsh-engram/triggerstats). Pure rules, zero LLM.
• Session-end todo auto-sink (draft safety net, autoSinkTodosOnEnd default on) — during a session the native todo stays cheap, per-session working memory that dies with the session. But when a session closes at its teardown edge (session/disposed) while its plan still has pending todos, they are auto-landed as ESR draft tasks (name = the todo text, description marked 「源自会话计划」, deduped against existing task names, capped by maxTasksPerWorkspace), so the plan never silently evaporates. Sinking to draft — not active — keeps them out of the [ESR] active rows and creates no evidence obligation; an explicit esr_claim / esr_task step is still what promotes a draft to active. The "nothing auto-written during the session" trade-off is unchanged; only the end-of-session data-loss gap is closed. Disable via profile patch or the settings card.
• Memory GC (pi-esr constraints) — a scheduled, mechanical, archive-only sweep: TTL-expired memories are archived, over-cap workspaces evict the lowest-value entries, stable tasks past their retention window leave the [ESR] surface, and dangling link edges are dropped. The working set (active task refs, task memories, indexed hits) is never touched, and nothing is hard-deleted — every archived entry keeps its id and stays re-fetchable.
• Context GC (auto-GC = replaces DSH's auto-compact) — NOT the memory-panel GC. It takes over the host's compaction service and swaps DSH's lossy LLM-summary compression for mechanical eviction + re-fetch pointers: evicted turns are scanned for engram/ESR anchors (#memory-id, tsk_*, ent_*, file_path) and replaced with one line "this detail lives at engram_detail / engram_recall / the [ESR] block"; only un-provenanced turns get a scoped LLM narrative (gcNarrative, default on, off = fully mechanical). All six GC constraints hold (working-set-protected, pointer-salience, no-provenance-no-evict…); any error falls back to the default compressor — compaction is never broken.
• Web viewer — a memory browser with benchmark-ish stats and a config card, built entirely on DSH's native settings slots (no third-party UI package).

MIT   ·   node >= 22.19   ·   host-half + browser-half in one package

Why another memory plugin?

Surveys of the existing DSH plugin ecosystem show the recall-bridge, approval-gate, LLM-distillation and vector/graph niches are already crowded. dsh-engram fills the three gaps that matter for token discipline:

1. No model in the write path — capture is deterministic pattern matching.
2. No raw text in the prompt — a bounded symbolic index is injected, plus the top ≤ N memories auto-recalled for the session's first message (within budget); deeper retrieval stays on demand ("retrieved ≠ full-text injected").
3. Honest task closure — STABLE cannot be declared without evidence.

DSH already provides cross-session FTS (ctx.sessionQuery), storage (ctx.storageDomain), prompt-injection hooks and settings slots; dsh-engram is a thin composition layer over them, not a re-implementation.

Security model

The DSH plugin ecosystem is young and unvetted — there is no official directory, no signature check, and the harness's read/write permission tiers do not constrain what a plugin's own code can do. So the trust bar for a memory plugin is higher than for a tool: a memory plugin sits on your prompt prefix and writes to disk on your behalf. dsh-engram's model, stated plainly:

• No network, ever. The plugin has no outbound socket, no telemetry, no update pinger. Nothing here can leak your sessions off the machine.
• No shell, no filesystem access beyond one storage file. It never executes commands and never touches arbitrary paths. All data lives in the single storage-domain unit ~/.dsh/storages/dsh_engram.json (plus the session-log reads it makes through DSH's own ctx.sessionQuery).
• Secrets are redacted before they can land on disk. Every write path — engram_store, auto-capture, and the import/restore route — runs text through the deterministic redactText rule engine (API keys, JWTs, Bearer tokens, private keys, key=value secret shapes) before the dedup hash, the char cap, and storage. Nothing sensitive is ever persisted, so nothing sensitive can be recalled later.
• Doing harm requires your harness's own permissions. The plugin only asks the host to do things via the same seams the tools you already trust use. It does not widen sandbox policy or escalate to danger-full-access — if you keep your profile's defaults, engram inherits exactly those bounds.
• Read-mostly web API, loopback-fenced. The GUI routes under /api/dsh-engram reject any non-loopback caller unless you explicitly whitelist a hostname via trustedHosts; even then the same-origin fence holds.
• Verifiable. npm run dsh-engram -- doctor (/scripts/dsh-engram.mjs doctor) reports what the plugin is configured to touch; the whole store is inspectable, nothing is opaque. If you ever doubt a claim in this section, the code to check is lib/redact.js, lib/store.js and this plugin's cordis.patch.yml.

What this deliberately does not claim: it is not an air-gap. If your profile grants the agent danger-full-access or a shell, the agent can use those — engram is a memory layer, not a sandbox. The point above is that dsh-engram itself adds no surface of its own.

Data contract: export / import

Memory should not be a hostage. The four tables (memories / tasks / links / entities) can be dumped and restored through a stable, versioned, machine-readable shape — so the corpus survives a reinstall, a machine move, or (when a thin adapter is written) a move to another harness, MCP end-point or Claude Code skill. The contract is plain JSON with a self-describing header:

GET  /api/dsh-engram/export?workspace=/path/to/project   # one workspace
GET  /api/dsh-engram/export                              # every workspace

{
  "meta": { "format": "dsh-engram/export", "version": 1, "exportedAt": 1724…, "workspace": "/path/to/project" },
  "memories": [ /* all rows, archived included — a backup never loses provenance */ ],
  "tasks":    [ /* draft/active/stable + archived */ ],
  "links":    [ /* typed edges */ ],
  "entities": [ /* graph nodes */ ]
}

Restore is idempotent by default and gated when destructive:

POST /api/dsh-engram/import          # body: { payload, mode, dryRun?, workspace?, confirm? }

• mode: "merge" (default) — writes only rows whose id is absent, so a backup can be re-applied any number of times without duplicating anything. Each row keeps its own workspace.
• mode: "replace" — wipes the target workspace from all four tables, then restores only its rows. Destructive, so it additionally requires confirm: "restore" in the body.
• dryRun: true — computes the identical plan (what would be written / skipped) without writing a single row.
• Import honors the same invariants as storeMemory: memory text passes the secret redactor before touching disk, and rows that would break the contract (missing id/workspace, empty text, over maxMemoryChars, id already present in merge, over the workspace memory cap) are skipped and listed in the response report instead of aborting the batch.

A restore round-trip for one workspace is then:

curl -s "http://127.0.0.1:3080/api/dsh-engram/export?workspace=$PWD" -o engram-backup.json
curl -s -X POST http://127.0.0.1:3080/api/dsh-engram/import \
  -H "content-type: application/json" \
  -d "{\"payload\": $(cat engram-backup.json), \"mode\": \"merge\"}"

Compatibility

• DSH 版本 / DSH versions: >=0.1.2-alpha.2 <0.3.0-0 (本版 0.9.0; 已发布的 0.3.7、0.4.0 仍声明旧的 0.1.x 范围 >=0.1.2-alpha.2 <0.2.0-0 — 见下方矩阵)
• 最后验证日期 / Last verified: 2026-10-27 — DSH 0.2.1-rc.2 (dsh --version), web profile live composition; npm test 483/483
• 安装方式已验证 / Verified install: dsh plugin --profile web add dsh-engram

Short version. Every published release (0.2.0 … 0.3.6) supports the old DSH API graph (0.1.0-rc.7 / 0.1.1, peers ^0.1.0-rc.7) only. DSH 0.1.2-alpha.2 and newer are not compatible with those releases — the settings/client API family broke there. New-DSH support starts with 0.3.7, the first release of the new API generation (described below).

Where the API family broke — 0.1.2-alpha.2

0.1.2-alpha.2 is the first version of the new API family and the first that breaks the released plugin versions:

• @deepseek-ai/dsh-settings removed settingsNamespace() and installSettingsSection() — the exact imports every release ≤ 0.3.6 uses — and replaced them with settings.installSection. The old host half fails to load on 0.1.2-alpha.2+.
• The web client half swapped its inject set: @deepseek-ai/dsh-client-runtime no longer exists in the new family (replaced by dsh-api-remotes plus dsh-client-locale / -conversation / -renderer / -ui-settings-plugins), and the settings card used to talk through ctx.remote.settings.
• Supporting bumps at the same boundary: @deepseek-ai/cordis ^4.0.1 → ^4.0.2, @deepseek-ai/schemastery ^3.18.1 → ^3.18.2, and @deepseek-ai/dsh stopped shipping config/agent-presets in the package (moved to dsh.configTrees).

The web config card no longer depends on any of this: since 0.3.7 it reads and writes the dsh-engram settings namespace through the plugin's own HTTP route (/api/dsh-engram/settings, same-origin fetch like the memory viewer), so the card is generation-agnostic on both sides of the 0.1.2-alpha.2 boundary.

One more settings break, at 0.1.7 / 0.2.0 — and the reason 0.4.0 was not actually loadable on the current DSH: @deepseek-ai/dsh-settings removed settings.installSection again in 0.1.7-alpha.2 (and keeps it removed in 0.2.x). The new settings model is entry-keyed: editable fields are .volatile() fields of the plugin's own Config (validated + hot-committed by the loader), and the settings form is keyed by the profile entry id (engram), so nothing needs "mounting". 0.5.0 feature-detects the two generations in installEngramSettings:

• DSH ≥0.1.7 / 0.2.x — the 34 GUI knobs are the volatile Config fields (lib/settings.js makeEngineConfigSchema, exported as Config from lib/index.js); the card reads/writes entry engram through the same /api/dsh-engram/settings HTTP route, and the service.settings seam re-syncs resolved on loader/volatile-update so card edits land live on new sessions.
• DSH ≤0.1.5 — the legacy settings.installSection namespace (dsh-engram) is registered as before; nothing changes.

The declared range >=0.1.2-alpha.2 <0.3.0-0 covers both, and the HTTP wire namespace stays dsh-engram on both generations (the seam's active namespace drives mutations).

So: keep DSH on 0.1.1-rc.2 or older while running a release ≤ 0.3.6, and upgrade the plugin to >=0.3.7 before moving DSH to 0.1.2-alpha.2.

Current release — 0.7.2

L1 boundary prune was silently dormant on some profiles — a boot-ordering race, not a missing patch.

BoundaryPrune resolved DSH's toolResultPruner with a strict ctx.get("toolResultPruner") at install time. On DSH 0.2.0 web profiles the pruner's fiber activates ~100 ms after the plugin (measured on the live composition dsh-context + dshmarket + dsh-engram: t0 strict=undefined / loose=object, strict resolves 100 ms later), so the strict lookup was empty, installBoundaryPrune gave up, and L1 never armed for the life of the process — taking the ledger's only prune-credit leg with it. The status snapshot also reported that race as "row missing", pointing at the wrong fix.

• Arm through ctx.inject(["toolResultPruner"], …) — cordis runs the callback the moment the service becomes active (and again after a reload), so arming no longer depends on composition order; the durable status snapshot is rewritten as soon as L1 is armed.
• "Absent" and "late" now read differently — boundaryPruneAvailability falls back to a non-strict lookup: a disabled/missing row still says no toolResultPruner service … (the bundle patch must re-enable …), a registered-but-inactive one says registered but its fiber is not active yet.
• Verified — the live bundle composition (with dsh-context) reproduces armed:false in an isolated DSH_HOME; after the fix the same composition reports armed:true · threshold 8192. npm test 406/406.

Previous release — 0.7.1

Web-plane Context GC on DSH 0.2.0's declarative presets — the preset format changed shape (one @deepseek-ai/dsh-agent-preset declaration inside dsh-web-app/presets/*.patch.yml), and the auto-wiring was anchored to the old agent.cordis.yml layout, so autoWebCompaction silently skipped every preset (and could half-rewrite a stock row: the pattern did not include its trailing newline).

• Structural row location — the compaction group is found by YAML structure (a list item carrying group: true), not by column position; the stock/engram rows are validated by BOTH their - id: and name: values, and the replacement inherits the row's own indent. Legacy agent.cordis.yml (4 spaces) and declarative patch files (14/16/18 spaces) both round-trip byte-identically.
• Declarative discovery — the preset roster no longer carries path on DSH 0.2.0; the plugin maps each roster id to the shipped <presetsDir>/<id>.patch.yml (resolved through the dsh install, with DSH_WEB_PRESETS_DIR override) and skips user-defined declarative presets (profile-patch overrides) with an explicit log line instead of failing.
• Status/doctor — npx dsh-engram status/doctor discover both preset generations, show the detected layout, and flag autoWebCompaction=false (the opt-in toggle that makes the web plane a no-op), node_modules preset wiring (survives npm update dsh only while auto-wiring stays on), and profile-patch preset-* overrides that outrank the shipped files.
• Migration — restart dsh web with autoWebCompaction:true: the next boot re-wires every stock declarative preset (idempotent refresh; existing hand-wired rows are rewritten to the requested engine config). npm test 396/396.

Previous release — 0.7.0

From event records to maintainable current truth: sessions sediment an episode at teardown, new sessions get a resume brief, esr_node becomes a readable page, and file anchors make stale truth detectable.

• Session episode — zero-LLM digest at session/disposed (files / commands / failures→fixed / decisions / open loops), never indexed, newest 20 per workspace kept.
• Resume brief — the newest episode from the last 7 days is injected as a [RESUME] line (≤240 chars + drill pointer) at session start.
• Entity pages + cards — truth / timeline / open loops / conflicts / relations; up to 2 one-line cards in the index, full page via engram_detail(entity=…).
• Revalidatable anchors — file-backed memories record mtime/size/sha256; a bounded revalidation at session start tags changed/missing sources stale (dropped from index/truth, still re-fetchable).
• Layered TTL — preference/procedure permanent, episode 14d, error 60d, others 180d.
• Migration — only new writes are anchored (no historical backfill); restart dsh web after upgrading; an episode appears after one session ends, the resume brief on the next new session. The 0.6.0 ledger / defaults / JIT behaviour is unchanged.

The published 0.4.0 declared >=0.1.2-alpha.2 <0.2.0-0 — which the semver gate rejects on every DSH 0.2.0-0 prerelease (<0.2.0-0 excludes 0.2.0-rc.x), and its host settings half still called the installSection API that dsh-settings 0.1.7+ removed. 0.5.0 fixes both: the range opens to <0.3.0-0 (verified against DSH's own includePrerelease check, so 0.2.0-rc.2 and the whole 0.2.x line pass), and the settings card is migrated onto the entry-id volatile Config model described above (with a feature-detected legacy fallback).

0.1.2-alpha.2 is the minimum version for this API family: host settings are feature-detected — on DSH ≤0.1.5 they register the dsh-engram namespace via settings.installSection; on ≥0.1.7 / 0.2.x the form is the plugin's Config with the 34 GUI knobs marked .volatile() (entry id engram). The browser settings card reads and writes through the plugin's own HTTP route (/api/dsh-engram/settings, see Route B above) on both. The full regression suite (npm test 396/396, incl. the new settings-v2 coverage for the volatile-Config model) passes against the DSH 0.2.0-rc.2 dependency set (cordis 4.0.4 + schemastery 3.18.4 + cosmokit, matching the global DSH CLI). The .volatile()/loader hot-commit path and the describe-side projection were verified against the real dsh-settings 0.2.0-rc.2 utilities, and a full real-machine boot smoke on an isolated dsh 0.2.0-rc.2 profile passed: the plugin boots with no version-range denial, the settings card form is served for entry engram (all 27 GUI knobs, incl. trustedHosts), and a GET → PUT (mutate ops, revision 0→1) → unset round trip on /api/dsh-engram/settings lands in the profile row and reads back. The older 0.1.0-rc.7 and 0.1.1 API graphs are outside this release's compatibility range.

To install the DSH version used for validation:

npm install --global @deepseek-ai/dsh@0.2.0-rc.2
dsh --version

Install

# from GitHub (this repo)
dsh plugin --profile web add github:skepsun/dsh-engram

# once published to npm
dsh plugin --profile web add dsh-engram

# local development (symlink — edits apply immediately)
dsh plugin --profile web add link:/path/to/dsh-engram

Then restart dsh web. Data persists in ~/.dsh/storages/dsh_engram.json.

The npm and GitHub installs below need no manual dependency step: pnpm installs zod and vendors the optional @deepseek-ai/* peers into the plugin's own node_modules, and the CLI auto-registers the plugin into the profile's dsh.profile.bundles. The setup-links step below is only for the link: development workflow, where pnpm deliberately does not install a symlinked directory's dependencies.

A fresh session is required to see the injected [ENGRAM]/[ESR] blocks and the tools; both prompts and the tools registry are assembled per session.

Dependencies for link: installs

A symlinked plugin resolves its imports from its own node_modules, so the host-side dependencies must be present next to the checkout — they are not tracked by git:

cd /path/to/dsh-engram
node scripts/setup-links.mjs     # one command: links the @deepseek-ai
                                 # workspace packages into node_modules AND
                                 # installs zod (reused from the harness
                                 # pnpm store, or via `npm install`)

The script auto-locates the harness checkout at ../deepseek-harness (also works when it sits next to the repo's parent, e.g. E:\deepseek-harness + E:\kototoro_demo\dsh-engram); override with DSH_HARNESS_DIR. Without this step, dsh web boot fails with ERR_MODULE_NOT_FOUND: Cannot find package 'zod' (and would fail on the @deepseek-ai/* peers next). node scripts/setup-links.mjs --check prints the state without writing anything.

What you get in the GUI

After restart, inside the native DSH settings surface:

• Sidebar "ESR 看板" entry + full-screen kanban — one more row under New Session with a live active-task badge (polled from /overview every 30s across all workspaces). Clicking it opens a full-screen board in the center column: 草稿 / 进行中(gaps) / 就绪(evidence ready) / 已闭环 columns, workspace filter + search, an inline create form, and per-card "补齐证据 → 关闭" closure forms sharing the esr_close gates (artifact + evaluation + memory_refs). A 看板 / 图谱 (board/graph) toggle in the header reuses the full relation graph (esr_node/esr_link force-directed SVG: entity circles + task check badges, drag/zoom/select for relation details), following the workspace filter and refreshed by the same 20s polling. Following the task-board precedent, the entry and the board are DOM-mounted and self-heal (MutationObserver re-inserts on shell re-renders), with cross-panel exclusivity against task-board/ssh (opening one evicts the others; clicking a sidebar session/workspace row hands the center column back to the conversation). The conversation subtree stays mounted underneath and is hidden by html[data-dsh-engram-board-active], so toggling loses no state.

• Unified task strip above the composer — the conversation dock that DSH ships for its built-in todo tool is taken over (same conversation.input.dock cell / id: todo at a lower priority) and merged into one modern control: the session's current plan (todo_write's todos projection) plus the workspace's persistent ESR tasks (with evidence-gap badges and an inline "补齐证据 → close" form) plus the relation graph rendered as node → relation → node chips with entity/task names resolved. It only shows while there is something to show, stays live with 15s polling, and the built-in plan still renders (without the ESR parts) if the loopback-fenced API is unreachable. A workspace-switcher chip leads the strip: it defaults to following the current session (the tooltip says so), and its dropdown pins the ESR task/relation source to any workspace (✓ marks the active pin; the × or "follow session" entry reverts). Switching refetches immediately and is a pure UI focus change — the model's session context and the per-session frozen injection blocks are untouched.

• Settings → Engram Memory — a standalone first-class settings section (right after the Plugins section, not a child tab of it). Default "All workspaces" view shows every workspace's memories/tasks/links grouped by workspace (dropdown + prev/next workspace pager; the memory table additionally pages 10 rows per page with a jump dropdown, fixed column widths, 3-line clamped content ellipsis and full text on hover). Overview stat cards (counts by workspace/kind, auto-capture totals, per-workspace [ENGRAM] index token estimate, cumulative GC totals), a searchable / filterable memory table with archive + delete actions, an ESR task board with an inline "new task" form and a per-task "fill evidence to close" (artifact / evaluation / memory_ref → STABLE, same gates as esr_close), a node + relation list (nodes are domain objects the model registers via esr_node — package/service/repo/concept; relations via esr_link), a separate relation-graph tab (hand-rolled force-directed SVG, no chart library so the bundle stays pure: entities as circles, tasks as check badges, relations colored per type with direction arrows; drag nodes, pan, wheel-zoom, re-layout, hover highlights the neighborhood, clicking a node pops a floating panel with its incident relations and linked objects; dangling links are counted and warned about), an injection-preview tab that renders the exact [ENGRAM] index block (order 40) and [ESR] task/closure block (order 41) the model sees each session — same pure functions as the system-prompt sections — as two terminal-style panes with per-line coloring (block headers, task lines, drill hint, and the data-driven escalate: reminder highlighted), line/char/~token cost chips plus memory/task/link/node count chips, 20s auto-refresh and one-click copy of the raw block text (backed by the new GET /api/dsh-engram/preview?workspace=… route). Every ESR task card (board and ESR tab) carries an evidence-progress ring — a small three-arc SVG donut mapping artifact · evaluation · memory_ref, all green when closure-ready, amber while gapped, gray with no evidence yet; the board header adds an aggregate ring showing overall evidence completeness (%) plus how many in-progress tasks are closure-ready. Pure SVG, no chart library, bundle stays clean. A telemetry dashboard tab turns the /stats usage rollup (workspace × day) into a pure-SVG dashboard: three gauges for ESR proactivity (benchmarked against the 0.34 escalate threshold, amber + hint when low), recall hit rate and detail follow-through, five stat cards (total / esr / memory calls, avg hits per query, failures), a 14-day mem-vs-esr stacked bar chart and a Top-8 tool breakdown (mem blue / esr purple), 20s auto-refresh with an automatic small-sample (<10 calls) warning. A details sidebar (master–detail) opens on the right when you click any task / memory / node / relation row: task cards show state badge, evidence ring, full id + timeline, gap list, clickable memory references and an inline "fill evidence to close" form that refreshes the lists on success; memory cards show full text, tags, signal/hits/TTL and provenance metadata; node cards list all incident relations (typed, colored, with direction + confidence); clicking a task's memory reference jumps straight to that memory, with a hint when it is not in the loaded set. And a memory-GC panel (dry-run toggle + run button + pointer report). The GUI create/close use the host's new POST /api/dsh-engram/tasks and POST /api/dsh-engram/tasks/close routes. Model-side proactivity is driven by the [ENGRAM]/[ESR] injected blocks: multi-step work gets a task now, recurring domain objects get a node, related tasks/nodes get a link.

  Real behaviour telemetry (agent observability) — the ESR page opens with an "agent behaviour" panel fed by a new usage table (per workspace × day rollup) + GET /api/dsh-engram/stats: every engram_*/esr_* tool call is recorded (counts, failures, recall mechanics). Reported ratios: ESR proactivity = esr calls / (memory + esr calls); recall hit rate = recalls returning ≥1 hit / total recalls; mean hits per query; detail conversion = a engram_detail following a hit recall within 8 session events. Per-tool counts + a 14-day daily rollup are shown too. Numbers are real, from real sessions — lift ESR proactivity by watching this panel and tuning the injected prompt.

• Settings → Engram Memory → 设置 tab — the config card, expanded by default (DSH 0.2.1 dropped the settings.plugin.item slot, so the old Settings → Plugins → Plugin configuration seat no longer renders). Same card, same transport: title + one-line description + chevron, its ~12 options under four groups — Capture & Search / Index / Lifecycle & GC / Security. Changes apply to new sessions (frozen blocks stay stable); Discard / Save with an "unsaved" badge on the header. It drives the namespace through the plugin's own /api/dsh-engram/settings route (not the isLoopback-gated scope), so it stays editable even through an operator-authorized tunnel.

• Settings → Plugins → Plugin configuration → dsh-engram (DSH ≤ 0.2.0 only, legacy settings.plugin.item seat) — a collapsible config card in the same style as the built-in "Shell / Agent loop / Web search" cards: title + one-line description + chevron, collapsed by default, click to expand/collapse. Open, its ~12 options render under four groups — Capture & Search / Index / Lifecycle & GC / Security. Changes apply to new sessions (frozen blocks stay stable); Discard / Save with an "unsaved" badge on the header. The card drives the namespace through the connection's own settings RPCs (not the isLoopback-gated scope), so it stays editable even when the GUI is reached through an operator-authorized tunnel.

The browser half is served by DSH's client-module loader directly from this package (dsh.client + exports["./client"], no web-application rebuild); the data comes from the loopback-fenced /api/dsh-engram/* route family. The fence stays closed by default; to reach the memory viewer from an authorized tunnel hostname, list it in the plugin's trustedHosts config (e.g. via the registry or a profile patch):

// patch/engram.json
{ "engram": { "trustedHosts": ["cream-club-fragrances-caught.trycloudflare.com"] } }

If you change client/src, rebuild the bundle with:

npm run build:client

Tools

The [ESR] block is a frozen per-session snapshot and never auto-refreshes — call esr_status for the live truth.

GC: two planes — memory-panel reclamation + Context GC (replacing auto-compact)

Memory-panel reclamation (store maintenance)

A scheduled sweep (gcIntervalHours, default 24h) plus a manual esr_gc / GUI button keeps the store bounded the pi-esr way — mechanical, working-set protected, archive-only:

• TTL-expired memories are archived (soft; the id stays, retrievable via the GUI's archived filter);
• over-cap workspaces evict the lowest-value non-protected memories;
• stable tasks past gcStableRetentionDays become archived and leave [ESR];
• links whose both endpoints are gone are dropped (dangling edges).

GC never touches the working set: memories referenced by an active task (memory_refs), task-kind memories, and already-indexed hits (hits >= promoteHits). Run esr_gc with dry_run: true to preview. Nothing is hard-deleted — the report ends with re-fetch pointers for everything it archived, so archives are recoverable, not lost.

Context GC (replaces DSH's auto-compact)

DSH's default context compression is a lossy LLM full summary (compaction-basic): evicted history is crushed into prose — un-queryable, and the summary itself burns tokens. dsh-engram's auto-GC replaces it: ContextGcEngine extends BasicCompactionEngine overrides the single summarize() hook and swaps the summary body for:

1. Scan — the evicted messages are scanned for provenance anchors: memory ids echoed by engram_store/engram_recall/engram_detail, tsk_*/ent_* touched by esr_*, and file_path anchors (esr_gc and other management calls are NOT anchors);
2. Pointer summary — every evicted category carries an explicit re-fetch call (engram_detail(id: "…") / engram_recall(query) / the [ESR] block / esr_ready); the active working set is restated, never evicted;
3. Narrative safety net — only un-provenanced turns (pure chat / reasoning) get a scoped LLM summary (gcNarrative, default on; off = the whole path is zero-LLM and un-provenanced turns are kept as truncated verbatim).

Triggers follow DSH's own compaction timing (step pressure / context-overflow / /compact); the lock, replay validation, tool-call/result pairing and token pricing are all reused from the basic engine. Any error falls back to the default compressor — compaction is never broken; with gcReplacesCompaction: false (the default since v0.6, or a host without dsh-compaction-basic) a bare BasicCompactionEngine is mounted instead, so the compaction service never disappears while dsh-engram is installed. Mounting registers the compaction service on the plugin's fiber, so unloading/reloading engram restores the default engine. Taking over compaction is opt-in: turn on gcReplacesCompaction (and autoWebCompaction for web presets).

Shrink gate: the harness refuses any checkpoint that is not strictly smaller than the evicted span (summary is not smaller than the shadowed content) and rolls the compaction back — otherwise the context never shrinks and the session eventually hits the model-side overflow. Context GC self-predicts that gate: it mirrors the harness framing with the host tokenMeter (verified token-for-token identical) and truncates the pointer/narrative body to the evicted span's token budget (the pointer head and working set survive; the trimmed tail stays recoverable in the session log), so compactions actually commit. Full from-scratch usage: docs/CONTEXT-GC-GUIDE.zh.md.

Where it is enabled (the entry point)

Assembly happens on two planes, but both switches are opt-in (no takeover by default):

• Host plane (headless / TUI / base profiles): the main plugin (lib/index.js) mounts the engine inside ctx.effect via mountCompactionEngine(ctx, resolved, { readWorkspace }) → new Engine(), registering the compaction service on its own fiber; the plugin patch disables the base compaction-basic row, making engram the sole host-plane provider. gcReplacesCompaction: false (default) → a bare BasicCompactionEngine (DSH's own summarizer); true → ContextGcEngine (pointer summaries). Enable via profile patch (config: { gcReplacesCompaction: true }) or the settings card.
• Preset plane (web profile) — covers every stock preset once enabled: web keeps compaction inside each agent preset's isolated realm (the shipped presets mount their own compaction-basic), unreachable from a host-plane row — and unreachable from a profile patch too (mountPreset builds its Include.Config with no patches; verified against the harness source). So on boot, once the agentPresets service is ready, the plugin auto-edits every preset that still has the stock layout — the default preset plus the whole roster, across BOTH preset generations: legacy <root>/<id>/agent.cordis.yml compositions (DSH ≤ 0.1.x, row at 4 spaces) and the declarative @deepseek-ai/dsh-web-app/presets/<id>.patch.yml files (DSH ≥ 0.2.0, row at 14 spaces inside the @deepseek-ai/dsh-agent-preset declaration; a user-defined declarative preset with no shipped file is left alone). The row is located by YAML structure (a list item carrying group: true) and validated by both its - id: and name: values, so the swap is column-position independent: it swaps the compaction-basic row inside the compaction group for dsh-engram/compaction. That auto-wiring is:
  • off by default (opt-in) (autoWebCompaction: false, toggle in the settings card's memory-GC section); once enabled it is idempotent — an already-wired preset is left alone; what "off" means: the plugin stops auto-wiring on later boots (the headless/TUI/base host plane is unaffected) — it does NOT un-wire presets that were already wired; use npm run web-compaction:revert for that;
  • per-preset: only stock-layout presets are touched — a preset with a custom compaction group, or none at all (e.g. the shipped minimal preset), is never written, only logged;
  • backed up + validated: a create-only .engram.bak (agent.cordis.yml.engram.bak or <id>.patch.yml.engram.bak) holds each original next to its file, every result is re-read and verified after writing, and any doubt rolls that file back; a failure only warns and that session keeps DSH's default summarizer — the host plane is never affected.
  • **config actually propag

…