dsh-memoryhub

English | 简体中文

MemoryHub (mh) integration for
DeepSeek Harness (dsh).

MemoryHub keeps project memory as purified sessions in git-versioned
checkpoints under .memoryhub/. This plugin wires that into dsh:

• Auto-load on session start — runs mh load in the session workspace and
  injects the checkpoint memory as durable plugin context. No prompt, no tool
  call; the model simply starts with its memory back.
• mh_save bridges dsh sessions to mh — dsh session files are not among
  the transcript formats mh discovers (Claude Code / pi / Codex), so the
  plugin renders the live session's durable event log as a pi-format JSONL
  transcript (in the temp dir) and saves through mh's existing
  --transcript path. Purified saves and agent-written compact saves both
  work, under a stable per-session identity: re-saving replaces, never
  duplicates.
• Six tools — mh_load, mh_save, mh_status, mh_list, mh_search,
  mh_checkpoint wrap the CLI; the model never has to shell out for the
  common operations. Rarer operations (mh link, mh back, mh import,
  mh ui) stay in the shell, as the skill explains.
• A "Memory" tab in the web UI — beside chat and trajectory: the mh ui
  checkpoint map of the session's workspace, embedded live (see
  The Memory tab).
• The mh workflow skill — registered at runtime, it teaches the model
  when to load, when and how to save (including writing compact summaries),
  and the hub rules (no HANDOFF.md files, git -C .memoryhub for anything
  mh does not cover).

Prerequisites

mh installed and on PATH (uv tool install git+https://github.com/solknight48/memoryhub;
needs git ≥ 2.32, Python ≥ 3.12). The plugin shells out to it — the hub
format, git commits, and error wording stay owned by mh.

Install

dsh plugin --profile web add github:solknight48/dsh-memoryhub

The package declares dsh.bundle, so the install appends its patch layer to
the profile. For a checkout instead: dsh plugin --profile web add ./dsh-memoryhub.

Git installs fetch sources, and pnpm ≥ 10 asks before running this package's
prepare build the first time; allowlist dsh-memoryhub in the profile's
pnpm-workspace.yaml as dsh instructs, then re-run the add.

Configure

Every field is optional; these are the defaults:

# $DSH_HOME/profiles/<name>/cordis.patch.yml — restates the whole row.
- insert:
    - id: memoryhub
      name: dsh-memoryhub
      config:
        mhBin: mh            # mh executable (PATH-resolved)
        autoLoad: true       # mh load + inject on every session start
        # loadBudget: 6000   # token budget for auto-load; omit for mh's default
        timeoutMs: 20000     # kill any mh invocation after this
        registerTools: true  # the six mh_* tools
        registerSkill: true  # the mh workflow skill
        noHubHint: false     # inject a one-line hint when no hub is found
        uiTab: true          # serve the mh-ui URL route the web Memory tab fetches
        uiReadOnly: false    # spawn mh ui --read-only for the Memory tab
        uiBudget: none       # the Memory tab map's initial budget ('none' = no over-budget badges)
        contextWindowTokens: 128000  # fallback window for the context-% estimate

With noHubHint: false, a workspace without .memoryhub/ stays completely
silent: no injection, no log spam. mh itself decides what "the project" is by
walking up from the session's recorded cwd — the same rule as in a shell.

Loading: no budget by default, with a context-% receipt

mh_load loads every session in the selected checkpoints — the
over-budget filtering of stock mh load is off by deployment choice. Pass
the tool's budget argument when you do want only the newest sessions that
fit. (Auto-load, if you re-enable it, keeps its budgeted semantics via
loadBudget: it injects into every session silently, so it stays opt-in per
token.)

Every successful mh_load ends with a receipt line, e.g.:

[memoryhub] memory ≈ 31,240 tokens ≈ 12.2% of the 256,000-token context window (adapter-reported); session total after load ≈ 18.6%

The window comes from the model adapter's own report (the session's newest
request/context event) when available, otherwise from
contextWindowTokens. The "session total" adds the last request's measured
input size, so it reads as "where this load leaves the conversation". Token
counting uses mh's own ~4 chars/token heuristic, so the number agrees with
the Memory tab's sizes.

The Memory tab (web UI)

The package is a dual-face dsh plugin: the same memoryhub row that loads
the host half also puts the browser half (dsh.client in package.json)
into the web boot graph. The browser half registers one entry into the
conversation.view slot ring — a Memory tab next to chat and trajectory.

What the tab shows is not a reimplementation: it is mh ui itself, the
checkpoint map (timeline, token budget, per-turn editing), embedded in an
iframe so every mh feature and fix shows up unchanged. The wiring:

1. The tab asks the host half for the map URL of its session:
   GET /plugins/memoryhub/mh-ui?session=<id>.
2. The host half resolves the session's workspace (session.header.cwd) and
   lazily spawns mh ui --no-browser --port 0 there — one server per
   workspace, pooled, killed when the plugin unloads. mh keeps its own hub
   discovery (walk up for .memoryhub/, MH_HUB override).
3. The token-bearing URL (http://127.0.0.1:<port>/?t=…) is parsed from the
   child's stdout and returned to the tab, which iframes it. mh's own
   security model (loopback bind, one-shot token, Host check) applies
   unchanged; uiReadOnly: true serves the map without editing.

A workspace without a hub renders an empty state with a retry button instead
of a server. The route is registered only when a web server exists, so
headless compositions never notice the feature.

The map is spawned with mh ui --budget <uiBudget> (default none, which
needs mh from the memoryhub repo with mh ui --budget support — 2026-08-14
or later): the map's budget box starts empty, so its over-budget preview
badges stay off, matching mh_load's load-everything default. Set uiBudget
to a number to restore the budgeted preview.

How saving works

mh save identifies a session through its transcript. mh knows Claude Code,
pi, and Codex transcript formats; dsh is not one of them (yet). So on
mh_save, the plugin:

1. Walks the session's durable event log and keeps exactly what mh's own
   purifier keeps: genuine user input (source.kind === 'user') and
   assistant text. Plugin-injected context (including this plugin's own
   auto-load snapshot), tool calls/results, and reasoning stay out.
   Assistant text that follows an mh load is dropped too, until the next
   genuine user message: that reply is the load receipt plus a digest of the
   memory that was just loaded — content that already lives in the
   checkpoints. Saving it would re-embed old memory into every new session
   and snowball. The load is detected whether it went through the mh_load
   tool directly or through a run_code block (the web GUI's path); the
   user's own request line stays. Detection is two-key: the call must
   have a load's shape (a direct mh_load call, tools.mh_load(…) in code,
   or mh load as a shell command — text that merely mentions mh load in a
   grep or edit payload does not count) AND the call's result must carry
   mh's own load receipt (<!-- mh | loaded: and friends); a failed load
   arms nothing.
2. Writes it as a pi-format transcript at
   $TMPDIR/dsh-memoryhub/dsh_<session-id>.jsonl.
3. Runs mh save --transcript <that file> (or
   mh save --compact --file <summary.md> --transcript <that file> with the
   summary the model wrote into the tool call).

Consequences worth knowing:

• The checkpoint filename key follows mh's pi rule (pi-<id12>) even though
  the session came from dsh. Cosmetic only; identity is stable per session.
• The bridge is rebuilt at every save, so a later save sees the whole session
  up to that point and replaces the earlier representation (mh keeps one
  representation per session).
• Steering messages and file attachments are not bridged (v1); a compact
  save's summary can still carry anything important.
• mh import backfills Claude Code / pi / Codex history only — dsh history
  enters checkpoints by being saved through this plugin.

Verify

npm install
npm run build
npm test        # e2e against the real mh CLI in a temp HOME

The test suite exercises the exact paths the plugin uses: bridge JSONL →
mh save --transcript → mh load, compact-replaces-purified,
save-twice-replaces, and the mh-ui pool against a real mh ui server
(spawn, token URL, page 200, guard 403, no-hub mapping). Plugin
registration (six tools + mh(runtime) skill + the Memory tab's client
bundle in the boot graph and the /plugins/memoryhub/mh-ui route branches)
was verified by booting a real dsh web profile with the bundle installed.
The agent/session-start → mh load → agent.inject path uses the same
extension points as dsh's own hook bridges; it has not been exercised
against a live model session yet (needs an API key), and neither has the
Memory tab's in-browser render.

Layout

src/index.ts   plugin: config schema, session-start auto-load, tools, skill,
               mh-ui route (webServer soft dependency)
src/bridge.ts  dsh session events -> pi-format JSONL transcript
src/mh.ts      execFile runner for the mh CLI (non-zero exits are data)
src/mh-ui.ts   mh ui process pool (one map server per workspace)
src/estimate.ts context-share estimate for mh_load (adapter window, mh's heuristic)
src/skill.ts   the mh workflow skill, adapted for dsh
src/client/    browser half: the Memory conversation-view tab (iframe of mh ui)
tests/         e2e against the real mh binary

License

MIT