dsh-harnmem

dsh plugin --profile web add dsh-harnmem

dsh-harnmem

HarnMem memory for DeepSeek Harness (DSH): a byte-stable hot-memory index injected into the system prompt, five

harnmem_* tools for on-demand recall and writes, and session-end extraction that turns a

finished conversation into durable memories.

The plugin is a thin adapter. Storage, retrieval, deduplication and lifecycle live in

@harnmem/core; this package only maps DSH host hooks onto the core facade

(docs/design/08-dsh-adapter.md is the implementation contract).

What it does

• Injection — one prompt section (harnmem:hot-index, order 4050) renders the

in-memory hot index. Text is identical across turns (provider prefix cache stays warm);

it is rebuilt only at session start, compaction, after a write in the same

session, on a local-day rollover, and after manual consolidation. An empty store

injects "" (zero tokens). On the first prompt of a fresh process the snapshot may not

be ready yet, so the section falls back to a synchronous disk render of the persisted

index; both paths share one layout function and are byte-identical.

• Tools — harnmem_write, harnmem_search, harnmem_read, harnmem_forget,

harnmem_status. They are thin wrappers; no retrieval logic lives here. The prefix is

configurable (toolPrefix): the bare memory_* names belong to dsh-auto-memory, and

DSH keeps the first registration, so prefixed names are the only ones that can never be

shadowed.

• Session end — user/assistant messages and tool names are accumulated from

session/event (≤200 entries, ≤2 KB each; eviction drops the oldest non-user entry

first, so early user prompts survive tool noise) and handed to sessionEnd when the agent

is disposed. The dispose handlers return their promise, de-duplicate concurrent disposal,

and bound the extraction race at llmTimeoutMs (60 s). Extraction runs autoExtract gates

in core; without a host LLM the result is no_llm and nothing is written.

• Quit path / resume catch-up — the host tears the provider adapters down before

plugin_unload, so no LLM call can run at quit. The session journal is durable: on

the next open of the same session the digest is hydrated from it and, once

minUserMessages (default 3) prompts are covered, sessionEnd runs with

reason:"resume_catchup" while the LLM is alive. The extract audit events are the

cross-process watermark, so a completed extraction is never repeated; newer turns

are extracted on a later open.

• Child agents — subagents (delegationDepth > 0, parentSession, or

subagentDepth > 0) get a read-only engine: they can search/read but never auto-write

or extract. Only root agents persist memories.

Install

From npm:

dsh plugin --profile desktop add dsh-harnmem

For development against a repo checkout, install the local path instead:

dsh plugin --profile desktop add /path/to/packages/dsh-harnmem

The package declares dsh.manifestVersion: 1 and dsh.bundle.patch: ./cordis.patch.yml, so

the reconcile step activates a layer; cordis.patch.yml inserts one row (id: dsh-harnmem,

name: dsh-harnmem). Remove with:

dsh plugin --profile desktop remove dsh-harnmem

Config can be set in that patch row, or overridden per profile in

~/.dsh/profiles/<profile>/cordis.patch.yml by targeting the same id.

Configuration

Key · Default · Meaning

home · $HARNMEM_HOME or ~/.harnmem · Memory store root (plain files, shared by all harness adapters)

injectMaxTokens · 1200 · Hot-index token budget

hotEntries · 24 · Max entries in the hot index

autoExtract · true · Run session-end extraction when a host LLM is available

minUserMessages · 3 · User prompts required before extraction (also gates the resume catch-up)

projectScope · true · Attribute project-scope memories to the session cwd project

llmTimeoutMs · 60000 · Bound for extraction (never blocks shutdown; measured 10.8–14.1 s headless, 33.3 s desktop catch-up)

consolidateEveryWrites · 25 · Mechanical consolidation interval (0 disables)

toolPrefix · harnmem_ · Prefix for the five model-facing tools (env HARNMEM_TOOL_PREFIX)

log · on · File log mode: off / errors / on (env HARNMEM_LOG); writes ~/.harnmem/logs/dsh.jsonl

Example profile patch:

- id: dsh-harnmem
  config:
    home: /home/me/.harnmem
    injectMaxTokens: 1500
    autoExtract: true

Memory store

Plain files under ~/.harnmem (or $HARNMEM_HOME): one Markdown file per memory with

YAML-subset frontmatter, a rebuildable index, an audit log, and a migration ledger. No

server, no database, no network calls from the core — the only network path is the host

LLM bridge used for session-end extraction.

Memory browser panel

The DSH web GUI (the desktop app renders the same GUI) shows a Memory icon in the left

sidebar (sidebar.panellist, id harnmem, order 60). It opens a read-only browser for the

store: no new config keys, no new runtime dependency, and nothing to install beyond the

plugin itself.

View · What it shows

Overview · Store home and current project, totals (records, active, superseded, archived, pinned, bytes, tokens, shards, projects, trash), the injection-budget meter, health issues (over budget, duplicate candidates, orphans, last consolidation), index freshness, per-shard table, registered and unregistered projects, and extraction status (pending/failed).

Memories · Shard selector (all / user / each project), type and status filters, and a local search over title, description, preview, tags and id. Rows carry type/status/pinned badges, importance, size and relative update time. Inactive records stay visible for inspection; only active ones take part in injection.

De

…(truncated)