dsh-maestro-memory

Durable memory and todos for DeepSeek Harness (DSH) — preserves ~/.dsh/memories in place.

Give the AI cross-session durable memory and todos — the more you use it, the more it understands you.

• Package: @ddtcorex/dsh-maestro-memory (cordis.patch.yml id maestro-memory)
• Version: see package.json · Changelog: CHANGELOG.md

Requirements

• Node.js ^22.19.0 || >=24.0.0, pnpm 11+ (packageManager in package.json)
• A DSH release inside the @deepseek-ai/dsh-client-* peer range declared in package.json

Install

pnpm install
pnpm run build   # -> lib/
pnpm test        # vitest run

DSH profile (operator):

dsh plugin --profile web add link:<workspace-root>/packages/dsh-maestro-memory
# production: dsh plugin --profile web add github:ddtcorex/dsh-maestro-memory#<tag-or-sha>

cordis.patch.yml is shipped with the package, including a connection entry that declares webServer (DSH 0.2.x needs it before rpc.handle can register a channel). Do not duplicate it in the profile. Pin a release with @ddtcorex/dsh-maestro-memory@<version> when installing from npm, and run pnpm install && pnpm build after every git pull of a link: checkout.

- insert:
    - id: maestro-memory
      name: '@ddtcorex/dsh-maestro-memory'
      config:
        memoryDir: null      # -> ~/.dsh/memories
        snapshotOrder: 500
        autoMemory: { enabled: false, userMessage: true, desensitize: true } # opt-in
        writeGuard: { enabled: false, threshold: 2 }  # per-turn write watchdog, opt-in

writeGuard is read once at apply() time — changing it needs a profile edit and a host restart. threshold counts consecutive working human turns with no daily/project write; any value below 1 is read as 1.

Tools

memory sanitizes sensitive fragments ([Filtered:API key/password/token/ID/phone], pure credential → content filtered).

System Prompt Snapshot

memory:snapshot (order 500) injects bounded deterministic context:

USER + MEMORY + KEY (branch-filtered) + Project Context (auto-recall top-4, 600 chars each, cap 1024) + Recent Daily (last 2 days, 512) + header + discipline note

Caps: memory 2048 / user 4096 / key 6144 / recentDaily 512 / autoRecall 1024, plus per-section entry budgets memory 8 / user 8 / key 12 / recentDaily 2 / autoRecall 4.

A cap is hard in both dimensions. The newest entry is always kept — compacted to head + [summary:…] when it carries a summary tag. An untagged entry larger than twice its byte cap is truncated with an explicit …[truncated] marker instead of being kept whole: before that rule, a single 2,293-byte global entry owned the 2,048-byte section and pushed every other entry out of the prompt.

Cost reporting. renderSnapshotWithStats (the renderer behind memory:snapshot) reports the bytes, entry count and excluded-entry count of every section. The host keeps the last 50 renders in memory and returns them as cost on /dsh-maestro-memory-health: samples, last, medianTotalBytes, maxTotalBytes, medianBySection. Entry text is never retained — byte counts only.

Write watchdog. With writeGuard.enabled, the host counts consecutive human turns in which work happened but no daily/project entry was written (agent/turn-stopping). Three things must hold for a turn to count:

1. it was opened by a direct human prompt — goal-continuation rounds (source.kind === 'goal') and injected context ('plugin', e.g. wake notices) carry no per-turn duty;
2. it is not a subagent session;
3. it dispatched at least one tool call. A turn that only answered a question is conversation, not work, so no debt accrues — otherwise the watchdog would push the model to write filler entries, exactly what the discipline note forbids.

Once the gap reaches threshold, the snapshot gains a # ⚠️ Memory Write Backlog section immediately before the discipline note, and it stays until a write succeeds. Only a write that actually recorded something counts — a deduplicated add does not. The alert text is static (threshold only, never the live count), so one open gap costs at most two tail snapshots: appear, then disappear.

Subagent sessions (session.header.origin === 'subagent') get a restrained per-achievement cadence instead of the per-turn duty, and never see the backlog alert. The shared memory context (MEMORY / USER / KEY / Project Context) is still injected for them.

The rendered snapshot collapses brace runs of two or more to a single brace: DSH interpolates each prompt context and fails the whole turn on a {{name}} group with a malformed or unregistered name, so free-form memory prose never reaches it as template syntax.

UI & RPC

One conversation.view slot (maestro-memory, order 40) with tabs Memory / Queue / Todo / Skills / Health. Health shows coverage, daily last 7d, longest + 5-dim score S/R/J/C/Safety (composite min*0.4+mean*0.6).

The Memory tab lists each track read-only and carries a manual add composer: pick a track, type an entry, press Add. It posts memory.mutate with action: 'add', so it needs no model round-trip; drafts are kept per track and the button stays disabled while the entry is empty or while key/project has no cwd. The model's key gate is exec.agent-scoped on the host, so it stays in force — a human writing key here is equivalent to approving a queued suggestion.

RPC: /dsh-maestro-memory + loopback /dsh-maestro-memory-health + /dsh-maestro-memory-propose.

Maintenance endpoints on /dsh-maestro-memory (both preview-first: dryRun defaults to true and an actual write needs confirm: true):

Archive vs. the two-machine sync. sync/ merges MEMORY.md, KEY.md and KEY-archive.md as a union — it never drops a version, and project/global entries carry no [id:…], so a deletion on one machine is indistinguishable from "the other machine has not seen it yet". Consequences worth knowing before archiving:

• Archiving on ONE machine only is not stable: the next union merge pulls the archived entries back into the live file, because the peer still carries them there. Archive on every machine (same policy) so both sides agree and the union is a no-op, or archive with sync disabled.
• MEMORY-archive.md is not in the merge set (only KEY-archive.md is), so a project-track archive stays local. That is safe for the live file but means the two machines' archive files can legitimately differ.
• The archive does not change what the prompt shows: # Project Key Memory is capped at 6,144 B and # Project Context at the newest 4 entries, both far below the archive policy's keep budget. Verified on the live store: rendering was byte-identical before and after the run.

One repair pass runs once at boot, gated by a flag file under <root>/.maestro-memory/ (maestroMetaDir): delimiter-repaired-v3 covers every store file and writes its run report into the flag. (v1 was a KEY-only pass that had been a silent no-op — it was called with a bogus cwd — and v2 covered the store without the stray-delimiter split; the versioned flag is what lets an existing machine pick up a new repair rule exactly once.)

Maintenance

Maintenance runs through the memory.repair and memory.maintenance RPC endpoints described under UI & RPC above (preview-first, confirm: true to write). There are no standalone maintenance scripts; scripts/ only holds the build helper.