Introduction

When developing agents using DeepSeek Harness (DSH), one unavoidable issue arises: lack of memory across sessions. User preferences, project context, and previous decisions must be re-explained every time a new session is opened.

There are two common approaches to address this. One is writing memory as a skill file, relying on the model to actively load it—this is a “soft guarantee,” and memory fails to load if the model forgets to invoke it. The other is running retrieval every time a query is made—memory is always checked and used on the fly, lacking continuous accumulation. dsh-plugin-memory takes a third approach: forcibly injecting the memory boot block along with the system prompt’s runtime context at the beginning of a session to create a “hard guarantee.” The mechanism and usage of this plugin are introduced below.

What is This

dsh-plugin-memory is a long-term memory plugin for DeepSeek Harness maintained by LittleBlackTong: a markdown-based memory library that is cross-session, portable, and features a “soul” (SOUL.md personality file), automatically injected at the start of a session.

Basic Information:

  • Current version 0.5.2, MIT license
  • Pure ESM JavaScript, zero build, no compilation steps
  • Requires Node >= 18
  • Main entry lib/index.js, CLI bin is scripts/memory.mjs (command name dsh-memory)
  • peerDependencies: @deepseek-ai/cordis ^4.0.1, @deepseek-ai/dsh-skill ^0.1.2-alpha.1, @deepseek-ai/dsh-system-prompt ^0.1.2-alpha.1, @deepseek-ai/schemastery ^3.18.1

The memory library itself defaults to ~/.memory and consists of pure markdown + git + self-describing schemas. The plugin is responsible only for the workflow and does not lock the data format.

Core Mechanism: Mandatory Boot Injection

The plugin injects the memory boot block at the beginning of every session via ctx.systemPrompt.context(). The boot block consists of four parts: the SOUL.md personality, MEMORY.md protocol, index.md directory, and recent activity.

Injection deduplicates based on projection by the host: if the memory content has not changed, it is not injected repeatedly, avoiding the waste of context; after memory updates, new snapshots automatically replace the old ones.

This is the key difference from the skill file approach. Skills only inject a summary, while the body relies on the model to actively load it, which is a soft guarantee; the boot block enters the session automatically with the runtime context, independent of the model’s self-initiative to invoke skills.

SOUL.md Casting the Soul

In the first session after installation, the agent’s primary task is not to perform work but to converse with you to define its soul: name, personality, values, tone, and boundaries. This entire process is driven by the BOOTSTRAP.md checklist and takes priority over regular tasks until it is complete.

Casting the soul features an automatic guidance mechanism: when the memory library lacks a soul, the boot block automatically prepends a first-person prompt, asking the agent to proactively initiate the soul-casting process during the conversation rather than waiting for the user to provide it. Once the soul is cast, the prompt automatically disappears.

Compound Interest Memory: Four Operations

Daily memory maintenance follows the Karpathy LLM Wiki convention: memory is a persistent product of “compile once, keep fresh continuously,” rather than re-performing RAG on every query. This corresponds to four operations:

  1. remember (记): Distill content worth persisting into pages, sync update index.md, append timeline;
  2. recall (忆): Read the boot block at session start; query by checking index.md first then drilling into pages, use dsh-memory search for full-text retrieval if necessary;
  3. consolidate (整理): Use dsh-memory lint for integrity check, find contradictions, orphan pages, and pages that should be archived;
  4. forget (忘): Explicit forgetting executes immediately; automatic decay is handled by salience three-level decay.

Portable with Git Auto-Commit

The memory itself consists of pure markdown + git + self-describing schemas, meaning any agent capable of reading markdown can take it over. For cross-machine migration, first pack on the old machine, then copy the archive to the new machine and unpack to restore; see the CLI section below for commands.

The git layer also provides a fallback mechanism: after a change to the memory library, if there are no new changes for autoCommitQuietSeconds, the plugin automatically executes git add -A && git commit; if the directory lacks a .git file, it is skipped. History can be rolled back, eliminating the need for the agent to remember to manually commit.

Anti-Lazy Digest and Active Recall

The plugin also provides two behaviors during idle times, both independent of dsh-plugin-heartbeat, allowing for separate installation and mutual independence.

Anti-lazy digest wake-up: After every round, if the agent is idle and the memory library has not been written for more than digestNudgeAfterMinutes, the plugin injects a digest reminder, changing the “session wrap-up and sedimentation” from relying on self-awareness to a mechanism-based fallback. It includes a cooldown and a limit per session to prevent repeated harassment.

Active recall: When the conversation is idle, the plugin proactively mentions a real event it remembers in the first person—such as user preferences, past events, unfinished decisions, or recent progress. The interval is randomly chosen between the shortest and longest values, with a limit per session; this is a pure conversational behavior that does not write to the memory library or fabricate information.

Relationship Between Embedded Skills and File Skills

The plugin registers an embedded memory skill via ctx.skills.register(), distributing the operation protocol with the plugin. If you already have a hand-written .dsh/skills/memory file skill in your project, they can coexist: the file skill (rank 100) will override the plugin’s embedded skill (rank 250).

Another note: if you previously modified the system prompt persona for “soft guarantee” (such as the boot command in profile patches), it is recommended to remove that persona section after installing this plugin to avoid double injection.

Installation and Activation

Installation command:

dsh plugin --profile <profile> add dsh-plugin-memory

The package includes a built-in dsh.bundle manifest, and dsh plugin add automatically mounts it into the profile’s bundles layer. Restarting the profile (or the DSH Desktop app) after installation takes effect.

There is a pitfall that was encountered in real machines that needs emphasis: do not manually write - insert: {id: dsh-memory, ...} to the profile’s cordis.patch.yml. This will create two entries with the same name due to the bundle manifest’s automatic mounting, causing the profile to fail to start with duplicate loader entry id "dsh-memory" (real machine incident on 2026-08-18). When you need to override the composition configuration, use the entry ID without insert to override it, for example increasing the boot block character budget:

- id: dsh-memory
  config:
    bootMaxChars: 12000

Configuration: Hot-Reload Layer and Composition Layer

Configuration is divided into two layers with different modification methods.

Runtime configuration is handled via <dshHome>/memory.json (with schema validation and atomic flushing), served by the plugin’s self-registered GET/POST /api/memory/config route, and modified in the “Memory” section of the DSH settings page. There are eight items that can be hot-reloaded, taking effect immediately without a restart:

  • enabled: Main switch
  • memoryDir: Memory library directory
  • autoInject: Boot injection
  • registerSkill: Skill registration
  • recallEnabled / recallIntervalMinMinutes / recallIntervalMaxMinutes / recallMaxPerSession: Switches, random interval range, and limit per session for active recall

The remaining keys—bootFiles, bootMaxChars, scaffold, configFile, digestNudge*, autoCommit*, etc.—only take effect in the composition configuration layer and require a restart after changes. See the Configuration section in the repository README for the full key list.

CLI Tool

The plugin comes with the dsh-memory command line tool, covering the full process from initialization to migration:

dsh-memory init [dir]                 # Create memory library scaffold
dsh-memory search <query>             # Full-text search
dsh-memory lint                       # Integrity check
dsh-memory status                     # Health overview
dsh-memory pack [out.tar.gz]          # Pack and export
dsh-memory unpack <archive> [--force] # Restore from archive

The order in which the CLI locates the memory library is: $MEMORY_DIR → ./.memory (if it exists) → ~/.memory.

Development and Self-Testing

To see the implementation or make changes, clone the repository and run a smoke test:

git clone https://github.com/LittleBlackTong/dsh-plugin-memory.git
cd dsh-plugin-memory
node scripts/memory.mjs --self-test

--self-test can run without installing dependencies. Zero build means lib/ is directly runnable code.

Applicable Scenarios and Notes

Suitable scenarios:

  • You want the agent to remember user preferences, project context, and historical decisions across sessions.
  • When memory needs to be isolated per project, set memoryDir inside the project (the CLI will prioritize recognizing ./.memory inside the project).
  • When memory contains sensitive content, place memoryDir inside an encrypted volume or private repository; the format remains unchanged, and the plugin is unaware.

Two reminders before installation:

  1. The plugin runs with the permissions of the current DSH process, so check the plugin source code and license (MIT) before installing.
  2. This plugin is independent of dsh-plugin-heartbeat; choose to use it as needed.

Conclusion

To recap: the forced boot block injection solves the issue of “memory must be loaded first in a new session,” SOUL.md casting the soul ensures consistent identity, markdown + git + pack/unpack solves migration, and digest reminders combined with active recall ensure memory is actually utilized. If you are building agents on DSH that require long-term companionship, it is worth installing and trying it out.

DSH’s philosophy is “everything is a plugin,” and dsh-plugin-memory is a member of this ecosystem. The plugin is also listed in the community directory skillhub.cn—this directory is an independent site with no official affiliation to DeepSeek or HF (High-Flyer).

  • GitHub: https://github.com/LittleBlackTong/dsh-plugin-memory
  • Directory Page: https://www.skillhub.cn/plugins/LittleBlackTong/dsh-plugin-memory