dsh-memory

English | 中文

Session stores what happened. Experience Memory stores what is worth reusing.

Unofficial project, independently developed and maintained by a community member.

dsh-experience-memory is keyword-based experience memory for DeepSeek Harness. It turns reusable successes and failures from coding tasks into persistent few-shot experiences that agents can explicitly search and recall across sessions.

The model searches lightweight candidate metadata, explicitly loads only a useful experience, and records a new lesson only when the current task produced something reusable.

See it work

This transcript is produced by the repository's real Cordis Loader demo, using the same plugin, tools, prompt registration, parser, and retriever as production.

From the repository root:

pnpm exec tsx packages/memory/memory/examples/encoding-experience/demo.ts

The complete example includes a real cordis.yml and seeded memory.md.

Real-world impact

In a real plugin-development workflow, Experience Memory was compared against a similar no-memory session export. This was not a synthetic benchmark: both archives contained actual development conversations, tool calls, subagents, and model usage records.

Metric	Without Experience Memory	With Experience Memory	Reduction
Model calls	503	313	37.8%
inputTokens	930,875	300,050	67.8%
outputTokens	343,697	150,145	56.3%
inputTokens + outputTokens	1,274,572	450,195	64.7%
reasoningTokens	113,192	23,628	79.1%
Tool calls	738	381	48.4%

The memory-enabled run spent far less context rediscovering project-specific habits, integration boundaries, Windows/PowerShell pitfalls, and previously validated fixes. The agent could search for a compact lesson, load one record when useful, and continue from that prior decision instead of re-deriving it from raw session history.

The complete exported session archives used for this comparison are committed under sessions/, including the full and development-only no-memory and memory-enabled plugin-development sessions. The memory.md file in this repository is the memory store used by the memory-enabled run.

It starts with compact reusable lessons like:

# DeepSeek Harness 里功能包的 Consumer-only 判定：单一内部调用者不必做成公共 Service {memory-1}

Keywords: dsh, cordis, capability seam, consumer-only plugin, inverse smell, ctx.sessionquery, tool-session-query, function plugin, service class
Recorded At: 2026-08-16T08:22:11.787Z
Outcome: mixed

## Lesson
新能力若只是已有 capability 的消费者，优先做 Consumer（函数插件），不要为一个内部调用者的方法再开一个 ctx 服务。

Why Experience Memory?

System	Stores	Best for	Main trade-off
Session history/search	Complete interactions and events	Audit, replay, recovery	Large and noisy as a reusable prompt
Generic RAG memory	Retrieved chunks from broad corpora	Finding potentially relevant information	A chunk is not necessarily a verified lesson
Experience Memory	Distilled success/failure records	Reusing proven debugging and task lessons	Requires deliberate experience capture

Experience Memory complements session storage. Session data remains the full historical evidence; memory.md contains compact lessons selected for future reuse.

A real UTF-8 debugging case

The plugin was motivated by a recurring Windows encoding failure: writing Chinese TypeScript or Markdown through an implicit default encoding corrupted the source. A failed approach and its successful UTF-8 resolution became one reusable experience.

The durable record is ordinary Markdown:

# Windows 中文源码写入必须显式使用 UTF-8 {memory-17}

Keywords: deepseek-harness, windows, encoding, filesystem, typescript
Recorded At: 2026-08-16T02:34:23.123Z
Outcome: success

## Problem

依赖 PowerShell 默认编码写回文件后，中文内容发生乱码。

## Resolution

读写包含非 ASCII 内容的文件时显式使用 UTF-8，并通过磁盘重新加载验证内容。

## Lesson

跨平台文本修改必须控制源文件编码，并用真实多语言内容做 round-trip 回归。

A later task searches without loading every body:

[memory-17]
title: Windows 中文源码写入必须显式使用 UTF-8
keywords: deepseek-harness, windows, encoding, filesystem, typescript
matched keywords: deepseek-harness, encoding, typescript
outcome: success

Only memory_get("memory-17") adds the complete experience to model context.

Features

• Experience-oriented success and failure few-shots rather than raw session replay.
• Explicit memory_search → memory_get progressive recall; no automatic prompt injection.
• Deterministic keyword retrieval with no vector database.
• Append-only, human-readable Markdown as the source of truth.
• Internal ranking selects candidates without exposing an opaque confidence score.
• Replaceable Retriever boundary without changing the three model-facing tools.

Installation

Install the local checkout into a DSH Profile:

dsh plugin --profile web add ./dsh-experience-memory
dsh --profile web --dump-config

Install directly from GitHub:

dsh plugin --profile web add github:ganfabo123-cmyk/dsh-experience-memory
dsh --profile web --dump-config
dsh --profile web

Git installs run this package's self-contained prepare build. pnpm 10 or later requires the user to explicitly allow that build in the Profile's pnpm-workspace.yaml and repeat the add command:

allowBuilds:
  dsh-experience-memory: true

Only allow and pin source you trust. A release tarball produced by pnpm pack includes prebuilt lib/ output and does not need install-time build permission.

The shipped Bundle layer inserts the plugin after the Profile's system-prompt and tool services:

- insert:
    - id: experience-memory
      name: dsh-experience-memory

memoryFile defaults to $DSH_HOME/memory.md. The host owns this path; the model cannot choose a workspace file. The parent directory and file are created on the first successful memory_record call.

Quick Start

After installation, start the Profile normally. The plugin registers memory_search, memory_get, and memory_record, plus a fixed Experience Memory section in the system prompt. Use --dump-config first and confirm the # == dsh-experience-memory Bundle layer and name: dsh-experience-memory row are present.

Tools

memory_search

Accepts specific keywords and an optional limit. It returns id, title, canonical keywords, matched keywords, and outcome. It never returns the body or an internal ranking score.

memory_get

Loads one complete record by stable memory-N id. A missing id returns an explicit model-readable message.

memory_record

Validates and directly persists the fields supplied by the model Tool Call. The Harness generates the id and ISO 8601 recordedAt; omitted outcomes become unknown. There is currently no human-confirmation step.

model Tool Call
  → validate title, keywords, body, outcome
  → normalize keywords
  → serialize the write
  → reload memory.md and allocate max(memory-N) + 1
  → atomic replace

Blank titles, bodies, or keyword lists are rejected. Bodies may contain ## through ###### headings, but a level-one heading is forbidden because only # <title> {memory-N} defines a record boundary.

Memory Format

Only # <title> {memory-N} starts a record. Metadata is stored directly below it, followed by the complete Markdown experience body. The body may contain ## through ###### headings but cannot contain another level-one heading.

Architecture

MemoryStore owns the Markdown source of truth. MemoryRetriever owns candidate selection. The V1 KeywordRetriever performs exact normalized keyword intersection and linear scanning.

Its internal matched-keyword count selects Top-K only. Selected candidates are then presented in ascending memory-N order, so presentation order is not a relevance claim. Model-facing output never exposes score, rankingScore, or similarity.

MemoryRetriever receives a MemorySearchSource. Future BM25, vector, or hybrid providers may maintain derived indexes without changing the Store, Service, or three model tools. Those providers are extension points, not V1 features.

Durability and concurrency

• memory.md is reloaded for every read and inside every append operation, so external edits remain visible.
• Writes use atomic replacement with owner-only file and directory permissions.
• A process-local serialized queue covers reload, id allocation, and write. Concurrent sessions in one process cannot duplicate ids or lose an append.
• Multiple processes writing the same file concurrently are not supported.

Verification

The release-focused suite covers:

• empty, single, multiple, malformed, and nested-heading Markdown records;
• maximum-id allocation, missing-file creation, external reload, and atomic batch rejection;
• three concurrent appends without duplicate ids or lost content;
• exact keyword matching, canonical normalization, zero-match behavior, limit, and Top-K/presentation separation;
• tool output contracts, including no body or score leakage from search;
• real Cordis Loader assembly and complete record → search → get tool execution;
• plugin unload cleanup for tools, service, and system-prompt section;
• multilingual UTF-8 round-trip with 中文, English, 日本語, emoji, Markdown, code spans, and a Chinese Windows path.

Run it with:

pnpm exec vitest run packages/memory/memory/tests
pnpm exec tsc -p packages/memory/memory/tsconfig.json --noEmit

Coverage percentage is diagnostic rather than the release definition; product contracts and reproducible integration behavior are the acceptance criteria.

See VERIFICATION.md for standalone Build, Tarball, Fresh Profile, installed Tool, lifecycle, and UTF-8 evidence.

Model guidance and token behavior

The plugin tells the model to generate several specific search keywords, treat results as candidates rather than truth, explicitly load only worthwhile records, and record reusable lessons rather than routine errors or complete session history.

Tool schemas and fixed guidance remain prefix-stable while plugin visibility is unchanged. Search cost grows with lightweight selected metadata; complete body tokens enter context only through explicit memory_get calls.

Limitations

• V1 is process-global and exact-keyword only; there is no workspace scope, BM25, embedding, vector, reranking, or hybrid retrieval.
• There is no automatic session mining, migration, deletion, merge, semantic deduplication, contradiction handling, or decay.
• The write queue protects one process only.
• Performance benchmarking and large-corpus retrieval evaluation are deferred until real usage invalidates the current linear-scan assumption.

Roadmap

BM25, vector, and hybrid Retrievers are possible future providers behind MemoryRetriever. They are not implemented or advertised as current features.

License

MIT licensed. This project preserves attribution to DeepSeek Harness in LICENSE and NOTICE. It is an unofficial community project and is not endorsed by or affiliated with DeepSeek.