dsh-memory

@achasoft/dsh-memory

Persistent, per-project memory for the DeepSeek Harness (dsh). Each project gets a DuckDB file at <project>/.dsh/memory.db holding decisions, architecture notes, sprint goals, session summaries, and binding rules. Mandatory and forbidden rules are a system-prompt section, re-read on every model request, so they survive context compaction. Memories are ranked by keyword (BM25F) and, when an embeddings endpoint is configured, by vector similarity. The Web Client gets a Memory tab to browse and edit all of it.

Features

The Memory tab

A Memory tab sits beside Chat in every session. It always shows the memory of that session's project. The header shows the database path, how many memories are active and how many have a vector, and whether rules are currently injected. The tab has three panes:

• Memories: search box (labelled Semantic + keyword or Keyword only), category and status filters (Active, Archived, Expired, All), and actions: New, New rule, Import instructions file, Export JSON, Rebuild vectors.
• Rules: the live mandatory and forbidden rules, and a Show the injected text toggle that displays the rule block exactly as the model receives it.
• Sessions: the last 50 memory sessions, with summaries and how many memories each wrote and read.

Each memory card offers Edit, Archive or Restore, Delete permanently (removes the row and its audit trail, after confirmation), and History: the audit trail of creates, edits, reads, archives, restores, imports, and expiries.

Rules that bind every request

Rules are injected through the system prompt, not a message, so every request carries the current rule set and an edit in the tab applies from the next request. Rule text reaches the model verbatim: a literal {{, as in ${{ secrets.GITHUB_TOKEN }}, is escaped so the harness prompt renderer does not treat it as a template variable.

Rules an agent recorded carry an Added by an agent badge in the tab and an [added by an agent] label in the prompt. When an agent-added rule is present, the block also tells the model that the user's own rules win on conflict.

Each rule is rendered on exactly one line, in the prompt and in memory_rules output. Line breaks (CR, LF, U+2028, U+2029), other control characters, and invisible format characters such as bidi overrides and zero-width spaces are collapsed to single spaces in the title and body, so a rule cannot add a heading or an unlabelled rule of its own. ZWNJ and ZWJ are kept. The stored text is unchanged; the Memory tab shows it as written.

The injected text is bounded, because it is paid for on every request:

Session continuity

Each top-level agent gets its own memory session. When it starts, the model receives one message with the last real session summary (up to 1,500 characters), up to 10 sprint goals, and up to 20 decisions from the last 7 days. Sprint goals and decisions follow the rule block's format: one line each, agent-recorded ones labelled [added by an agent], with a note that the user wins on conflict. Entries a subagent created or edited are left out of this message; they are still found by search and recall. Sessions left open by a crash or a disposed agent are closed with an [auto-closed: …] summary, which is skipped when picking the last summary. At the end of a turn the model is reminded to call memory_session_end (see remind).

A subagent (a session whose header has origin: 'subagent' or delegationDepth > 0) is bound by the same rules, but gets no memory session, no session context, and no reminder. A user's fork of a session is not a subagent.

Retention

Each non-rule memory gets an expiry date when it is written. Once that date passes, the memory drops out of search, session context, recall by title, and the Active list, and it is listed and reported as expired. Its stored status changes to expired at the next top-level session start in that project.

Priority 1 multiplies the lifetime by 1.5. Priority 2 and 3 never expire. Rules are always raised to at least priority 2. Restoring an archived or expired memory starts a new retention window.

Import and export

Import instructions file accepts .md, .markdown, or .txt (for example CLAUDE.md or AGENTS.md). Headings decide the category; list items under rule-like headings ("Never", "Always", "Rules", "Conventions", …) become one rule each. An import creates at most 1,000 entries and is validated in full before anything is written. Imported entries count as user-written.

Export JSON downloads every memory in the project, in all statuses, as <project>-memory.json. There is no JSON import.

Settings card

Settings → Plugins → Memory shows whether semantic recall is ready and lets you change the fields marked in Configuration.

Requirements

• Harness: tested with @deepseek-ai/dsh 0.1.5-rc.2.
• Node.js: ^22.19 || >=24 (engines in package.json).
• pnpm on PATH: dsh plugin forwards to it.
• DuckDB: @duckdb/node-api 1.5.5-r.4 is a regular dependency. Its bindings ship as prebuilt optional packages for macOS (arm64, x64), Linux (arm64, x64, glibc and musl), and Windows (arm64, x64); nothing is compiled at install time. Other platforms are not supported.
• Harness services: peer dependencies are @deepseek-ai/cordis, dsh-agent, dsh-credentials, dsh-llm, dsh-session, dsh-system-prompt, dsh-tools, dsh-typert-protocol, and schemastery, all provided by a standard dsh-base profile. The host half requires the agents service; settings (for the Settings card and live edits) and memoryEmbedding are optional. The browser half needs a Web Client profile (dsh-api-remotes, dsh-client-locale, dsh-client-ui-conversation, dsh-client-ui-settings, dsh-client-ui-settings-plugins).
• Embeddings (optional): any endpoint that implements OpenAI's POST /v1/embeddings, such as a hosted API, a local inference server, or Ollama. Without one, ranking is keyword-only and every other feature works.

Install

dsh plugin --profile web add @achasoft/dsh-memory
dsh web

dsh plugin --profile <name> <args> runs pnpm <args> in $DSH_HOME/profiles/<name> ($DSH_HOME defaults to ~/.dsh) and creates the profile on first use. After a successful add, any dependency whose package.json declares dsh.bundle is appended to the profile's dsh.profile.bundles. No manual edit is needed.

At boot the harness composes the profile from patch layers, in this order: each bundle's cordis.patch.yml (in bundles order), the profile's own cordis.patch.yml, $DSH_HOME/cordis.patch.yml, then any --patch <file> overlays. This package's patch inserts four rows:

To uninstall:

dsh plugin --profile web remove @achasoft/dsh-memory

This removes the dependency and its bundle entry. Remove any rows in your own patch files that target the ids above. .dsh/memory.db files in your projects are left in place.

Configuration

Override a row from your profile's cordis.patch.yml by id. A patch replaces the row's whole config, so restate every key the row needs:

- id: memory
  config:
    databasePath: .dsh/memory.db
    injectRules: true
    injectSessionContext: true
    autoSession: true
    remind: once
    vectorWeight: 0.6
    minSimilarity: 0.3
    searchLimit: 10
    candidateLimit: 1000
    embedBatch: 64
    retentionDays:
      sprint: 30
      decision: 0
    relevanceWeights:
      similarity: 0.7
      recency: 0.15
      access: 0.15

The patch row is the base layer. Values saved from the Settings card go to the harness settings layer (the memory: section of $DSH_HOME/settings.yaml) and take precedence over it. Committed changes apply from the next request or call, without a restart.

memory row

The shipped cordis.patch.yml restates retentionDays and relevanceWeights with these defaults. An older override that leaves them out still loads; the schema supplies the same defaults.

memory-tools row

memory-embeddings-openai row

Enable the row and restate its config:

- id: memory-embeddings-openai
  disabled: false
  config:
    baseUrl: http://127.0.0.1:11434/v1
    model: nomic-embed-text
    timeoutMs: 30000
    batchSize: 64

Vectors are stored with the model name and the vector length. When the model or length changes, old vectors are excluded from comparison and re-embedded in the background. If the provider cannot describe itself, the plugin does not attach it and ranks by keyword. If an embed call fails, that search falls back to keyword ranking. Rebuild vectors runs a backfill immediately and reports how many memories still lack a current vector.

Model-facing tools

Every tool resolves the project from the calling agent's session working directory. Writes are stamped source: assistant.

No tool hard-deletes a memory or restores an archived one; those actions are only available in the Memory tab.

RPC

The browser half calls a Typert remote namespace named memory. The contract is generated into generated/ and ships in the bundle. Every endpoint takes an optional project (an absolute directory; when omitted, the host process's working directory is used) and returns either { ok: true, … } or { ok: false, code: 'invalid' | 'not-found' | 'unavailable', message }.

Data and storage

• Location: <project>/.dsh/memory.db, where <project> is the session's working directory. The .dsh directory is created with mode 0700.
• Commit or ignore it: it is an ordinary file. Commit it to share rules with a team, or add it to .gitignore.
• Layout: version 1, stored in a meta table. A file with any other version is refused with a message; there are no migrations.
• Tables and views: memories, sessions, provenance, meta, plus two views for reading by hand:

duckdb .dsh/memory.db "select kind, title, content from rules"
duckdb .dsh/memory.db "select category, title, source, updated, expires from memory"

• Locking: DuckDB takes an exclusive lock on the file. While dsh holds a project open, another process (a second dsh, or the duckdb shell) cannot open it and gets a "locked by another process" error. Stop dsh before querying by hand.
• One open per file, per process: a process opens each database file once, whatever path spelling or plugin reload reaches it. An earlier bug that opened the same file twice in one process and corrupted it is fixed. Do not run two dsh servers against the same $DSH_HOME.
• Transactions: each write, its authorship check, and its audit entry run in one transaction, so an edit is always applied to the row as it currently is.
• Backups: stop dsh and copy .dsh/memory.db, or use Export JSON for a readable copy you cannot re-import.

Security and trust model

A rule is repeated to the model on every request, so the plugin limits who can change the rule set:

• User rules are the user's. A rule written in the Memory tab or imported from a file can only be edited, archived, or deleted from the Memory tab. A tool call that tries is refused with a message saying so. An agent also cannot turn a user-written memory into a rule.
• Agents can add rules and manage their own. With toolset: full, an agent can edit or archive rules that an agent added. It can also edit or archive any non-rule memory, including ones you wrote.
• Agent rule caps: a rule an agent writes is at most 4,000 characters, and a project holds at most 100 live agent-added rules. The user's rules count toward neither limit.
• Subagents cannot change rules at all. They can search, store non-rule memories, and read rules. Their writes are recorded in the history with the actor subagent, and anything with such a create or edit entry is kept out of the next session's opening context.
• Sessions are per agent. memory_session_end closes only the calling agent's own open session. A session_id naming another agent's session, a session opened by another process or an earlier run, or one that already ended is refused. Such an open session is closed as an orphan at the next session start.
• Authorship is the source column. Only the exact value assistant counts as agent-written. Anyone who can write the DuckDB file can change it.
• Credentials for embeddings are referenced by name (apiKeyEnv) and never stored in the database or shown in the UI.

Known limitations

• The RPC accepts any project path. Any authenticated Web Client caller can name any absolute directory as project. The plugin then creates .dsh/memory.db there and reads or writes it.
• memory_rules output is not capped. Unlike the injected block, it returns every rule in full.
• Subagent writes recorded by earlier versions are not recognised. They were recorded with the actor agent, so they are labelled as agent-added in session context but not left out of it.
• An agent's edit of a memory you wrote is not labelled. Authorship follows who created the entry, so a decision you wrote and a top-level agent later rewrote is shown unlabelled.
• The last session summary is carried as written, line breaks included. Only top-level agents file summaries.
• Changing retention does not recompute existing expiry dates. New values apply when a memory is created, or when its category or priority changes, or when it is restored.
• Single writer per file. See Locking.

Development

The devDependencies link a deepseek-harness checkout at ../../deepseek-harness, relative to this repository, for types and tests. pnpm install expects it there.

pnpm install
pnpm run typecheck
pnpm test             # checks generated/ against src/host, then runs vitest
pnpm run build        # writes generated/, then tsc, then tsdown

generated/ holds the Typert RPC contract, rendered from scripts/typert-endpoints.mjs. pnpm test (scripts/check-typert.mjs) fails when src/host/index.ts, src/host/types.ts, the endpoint table, or the renderer changed since the contract was last recorded, or when a file under generated/ differs from what the table renders. After updating the table to match src/host/, run:

pnpm run regen:typert

build writes generated/ but does not record the fingerprint; only regen:typert does.

To run a checkout in a local profile, add it by path and restart the web server:

dsh plugin --profile web add link:/absolute/path/to/dsh-memory
dsh web

A linked package resolves its imports from its own directory, so the harness packages it imports must resolve there to the same copies the running harness uses. The maintainers' workspace does this with publish-plugins.sh and .dsh-compat/install-plugins.sh in the parent dsh-plugins directory, not in this repository. After a rebuild, restart dsh web.

License

MIT