dsh-memory-standard
English | 简体中文
A Memory Standard Protocol (mm) plugin for the DeepSeek Harness (dsh): a
deterministic, layered, cross-agent memory system built on plain markdown
files — not a proprietary protocol.
The dsh ecosystem has dozens of memory plugins but no shared standard, and
the official core only ships a default-off MCP memory example. This plugin
claims the missing "standard seat": deterministic budgets + layered
MEMORY.md + cross-agent mutual recognition + session-log ingestion that
works with official compaction/session logs.
- Layered memory —
MEMORY.md is the hand-loaded index (hard cap:
200 lines / 25 KiB, default); detailed notes live in memories/<topic>.md
and load on demand.
- Deterministic budgets — over any budget is a structured error with
usage metrics demanding an index rewrite, never a silent truncation.
Writes carry a character budget and return usage so an agent can compress
on the spot.
- Cross-agent mutual recognition — a documented plain-markdown format,
portable
mm://<memoryId>/<topic> URIs, a JSON Schema
(schema/memory.schema.json), and an open read/write API. No closed
protocol.
- Write timing —
mem_write API plus session-end / periodic nudging;
writes persist to disk immediately and load in the next session
(in-session reads stay frozen, protecting any prompt cache).
- Ingestion collaboration —
mem_digest recognizes official dsh session
logs / compaction output as a memory source and distills candidate memories
(optional, self-contained, LLM-free).
- Toolchain — dsh tools
mem_read, mem_write, mem_search,
mem_budget, mem_digest, plus a dsh-memory CLI.
The core library is dependency-free (Node built-ins only) and works both
inside dsh and standalone.
Status
Developer-preview dsh ecosystem; format version mm v1 (see
SPEC.md). Compatible with the installed @deepseek-ai/dsh CLI
and bundle format (dsh.bundle.patch + cordis.patch.yml + apply(ctx)).
Quick start
1. Integrate with dsh (local directory bundle)
From the directory that contains this package (dsh-memory-standard/):
dsh plugin --profile demo add ./
# or install directly from this GitHub repository
dsh plugin --profile demo add github:JohnXu22786/memory-standard
# or from npm once published
dsh plugin --profile demo add dsh-memory-standard
# the standalone CLI is also published as a global npm bin
npm install -g dsh-memory-standard
# boot the profile; the five mem_* tools + the 'memory-standard' system section load
dsh --profile demo
dsh plugin forwards to pnpm inside the profile; peer dependencies
(@deepseek-ai/cordis, @deepseek-ai/dsh-tools, @deepseek-ai/schemastery)
resolve from the dsh installation. Verified against dsh@0.1.0-rc.6.
Notes for other install paths:
- As a dev overlay → copy
cordis.patch.yml and point a --patch overlay at
the package's entry (name = package name for the row).
- The plugin auto-initializes the memory root (
$DSH_HOME/memory, or
$DSH_MEMORY_ROOT) on first load — no manual init needed.
2. Configure
The bundle ships defaults; every value is overridable by overriding the
memory-standard row by id in a later layer (profile cordis.patch.yml,
$DSH_HOME overlay, or --patch):
- id: memory-standard
config:
root: '' # '' => $DSH_MEMORY_ROOT, else $DSH_HOME/memory
memoryId: local
indexLines: 200 # hard cap on MEMORY.md lines
indexBytes: 25600 # hard cap on MEMORY.md bytes (25 KiB)
detailMaxBytes: 65536 # hard cap per detail file
defaultWriteBudget: 4000 # per-write character budget
search:
mode: auto # auto | scan | fts5
limit: 10
maxSnippetChars: 160
nudge:
enabled: true # session-end / periodic nudging (memory/nudge events)
intervalMs: 1800000
lang: auto # auto | en | zh (system-prompt section language)
3. Use it
In a dsh session the agent gets the five tools (plus a system-prompt section
that explains the protocol):
| tool | purpose |
|---|
mem_read | read the index, all summaries, or one note's full body (frozen snapshot) |
mem_write | write/update a note with a character budget; returns usage; never truncates |
mem_search | search memory (FTS5 when available, else scan; CJK-aware scan) |
mem_budget | deterministic budget report (index caps, per-note usage, pending writes) |
mem_digest | distill candidate memories from a session log / text (never writes) |
Other plugins can access memory directly via the provided service:
const memory = ctx.get('memory')
memory.write({ topic: 'deploy-region', content: 'us-east-1', summary: 'Deployment region' })
memory.search('deploy')
4. Standalone CLI
npm run build # needed once to compile lib/
node lib/cli.js init --root <dir>
node lib/cli.js write deploy --content "we deploy to us-east-1" --root <dir>
node lib/cli.js read deploy --root <dir>
node lib/cli.js budget --root <dir>
node lib/cli.js search deploy --root <dir>
node lib/cli.js digest --file <session.log.jsonl> --root <dir>
All commands accept --json for machine-readable output; --root selects the
memory root. Install globally with npm i -g . to get the dsh-memory bin.
How it works
Layered memory
<root>/MEMORY.md hand-loaded index (small, hard-capped)
<root>/memories/t1.md on-demand detail notes (free markdown)
mem_read without a topic returns the index (the hand-load surface); a topic
returns that note's full body. Budget lets the agent decide what belongs in
the index summary vs. the detail note.
Deterministic budgets
Three no-truncation guarantees (see SPEC.md §6):
- a write over its character budget fails with
usage.overflow, writes
nothing; compress and retry,
- a note over its byte cap fails, preserving the previous content,
- an index over its line/byte hard cap fails and demands a rewrite —
the error text says so explicitly. Deleting/consolidating to fit again is
the recovery path.
A compliant writer must never "fix" an over-budget write by silently dropping
content — the standard views that as data loss.
Frozen snapshots
Memory loads a snapshot once per session. Reads and search serve that
snapshot; writes go to disk for the next session. pendingWrites exposes
staged writes; reload() re-snapshots (used by the CLI and integrations).
This keeps the session's view self-consistent and protects prompt caches.
Cross-agent interop
- The on-disk format is plain, documented markdown (
SPEC.md) and the URI
scheme is mm://<memoryId>/<topic>.
schema/memory.schema.json describes the note shape for any compliant
writer/reader.- The public API (
Memory, and ctx.get('memory') in dsh) is an open
interface — not a closed tool protocol. Any agent or tool can read/write the
same files.
Ingestion collaboration
dsh stores sessions under $DSH_HOME/sessions and compacts them; those logs
are recognized as a memory source. mem_digest reads the most recent
*.jsonl/*.md (or an explicit file/text), recognizes mm: markers,
MEMO:/记忆：/记住： lines, summary lines, and markdown headings, and
returns budgeted candidates for review. It never auto-writes — the agent
chooses what to commit.
Project layout
src/
types.ts shared/interop types + defaults (mm v1)
core/ dependency-free library (Node built-ins only)
memory.ts Memory facade: snapshots, writes, budget, search, digest
format.ts index/note markdown grammar + URIs (SPEC implementation)
budget.ts deterministic budget arithmetic
search.ts scan search + optional SQLite FTS5 (node:sqlite)
digest.ts session-log distillation
paths.ts layout & root resolution
dsh/
tools.ts the five mem_* defineTool registrations
guide.ts system-prompt "standard bit"
cli.ts dsh-memory CLI
index.ts dsh bundle entry (name/inject/Config/apply)
cordis.patch.yml bundle patch layer
schema/memory.schema.json
SPEC.md / README.md / README.zh.md
examples/root/ runnable example memory
test/ node:test suite (budget/layered/snapshot/search/digest/interop/cli)
Development
npm install
npm run build # tsc -> lib/
npm test # build + node --test
npm run typecheck
Uses only dev dependencies (typescript, @types/node, and the dsh peer
packages for type-checking). Runtime dependencies: none beyond Node built-ins
(node:sqlite optional for FTS5; graceful fallback to scan).
License
MIT — see LICENSE.
