Preface

By default, DeepSeek Harness (DSH) agents lose all context after a session ends. dsh-memory (project name Cairn), as a plugin, provides DSH with cross-session persistent storage and context injection capabilities. It stores facts, preferences, and conventions in a persistent KV backend, ensuring that information remains after restarts.

Core Features

Persistence and Scope

The plugin stores memories in a persistent KV backend, with audit log support. Memories are divided into three scope tiers:
* global: Cross-project memory.
* project: Project-specific memory auto-detected per repository.
* user: User profile memory that spans projects.

Retrieval and Injection

  • BM25 Relevance Search: Uses the dependency-free Okapi BM25 algorithm, supporting CJK tokenization (Latin tokens + CJK single characters / bigrams). Retrieval quality is verified in CI (success@5 = 100%, MRR = 0.902).
  • Summary-First Injection: The system prompt retains only static instructions, while data is injected via <memory-digest> and <recalled-memory> tags. By default, only summaries are injected to keep prompt bytes stable.
  • Step-Level Automatic Recall: After each conversational step, the system performs a BM25 search based on the user’s text and appends a <recalled-memory> tag when matches are found, without touching the system prompt prefix, preserving KV cache stability.

Identity Layer

An optional identity layer is supported. Agents automatically generate and update two self-documentation files during conversation via the identity_update tool:
* SOUL.md: The agent’s role document.
* USER.md: The agent’s understanding of the user.
These two documents are stored with versioning, do not decay by default, and have lower priority than the deployment role.

Automation and Governance

  • Automatic Learning: A projection accumulator listens to conversations, capturing “remember intent”, corrections, and successes after validation failures. Once enough candidates are accumulated, LLM extraction is triggered.
  • Security Scanning: Scans for API Keys, Tokens, and prompt injection patterns during writing and loading, blocking storage and marking them as [BLOCKED: ...].
  • Deduplication Pipeline: Two-stage deduplication (Jaccard pre-filtering with stopword filtering + optional LLM judgment) prevents duplicate accumulation.
  • Two-Tier Lifecycle: Important memories can be pinned. Expired project-level memories are removed; expired global/user-level memories are soft-decayed (hidden but not deleted, and still searchable).

Management and Configuration

  • Frontend UI: Provides a “Memory” settings panel, including a health dashboard, a review queue, and a management interface (with search, filtering, archiving, and deletion).
  • Manual Review: When confirmBeforeWrite is enabled, extraction and tool writes enter a review queue and must be manually accepted or rejected.
  • Time-Window Browsing: memory_list supports filtering memories by time range (epoch-ms).

Installation and Enabling

The plugin depends on the dsh core service as a peer dependency and provides functionality in a single-package structure.

npm install -g @deepseek-ai/dsh

After installation, the plugin is activated as a configuration layer for DSH through its bundled cordis.patch.yml.

Typical Usage

The plugin provides the following tools and capabilities:

  • Memory Tools: memory_search, memory_add, memory_replace, memory_remove, memory_list, memory_get, memory_pin, memory_unpin, memory_forget.
  • Identity Tools: identity_update (used to update the agent’s SOUL and USER documents).

In practical use, agents automatically try to extract key information during conversation, and the BM25 algorithm is used to recall relevant memories in subsequent steps.

Applicable Scenarios and Notes

This plugin is suitable for complex task development that requires long-term context maintenance and cross-session consistency. Because the plugin runs with the permissions of the current DSH process, check the source code and license before use (the current documentation does not explicitly list the license).

Conclusion

dsh-memory solves the problem of agent “forgetfulness” through persistent storage, BM25 retrieval, and automatic extraction, making it a foundational component for building long-running agents.

  • Project Homepage: https://github.com/chenhw7/dsh-memory
  • Ecosystem Directory: https://www.skillhub.cn/plugins/chenhw7/dsh-memory