DeepSeek Harness (DSH) adopts a plugin-based architecture. In agent development, long-term memory often leads to context bloat and token consumption. dsh-engram draws inspiration from the symbolic-index and pi-esr concepts, providing DSH with a minimalist long-term memory system whose core goal is saving tokens.

Core Features

Zero-LLM Automatic Capture

The plugin captures meaningful events using pure pattern matching and does not invoke an LLM for hot-path processing.
* Event types: Supports git milestones (-m commit messages), key file edits, and repeated errors.
* Sensitive information redaction: All writes undergo deterministic redaction before being persisted. API keys, JWTs, Bearer tokens, private keys, and similar values are replaced with <REDACTED:...> markers.
* Exclusions: Silent operations (git push / git stash) are intentionally excluded and not recorded.
* Test failures: Test failures are identified through pure patterns (npm test, node --test, and failure lines from vitest/pytest/jest) and captured as entries with tags:["error","test"].

Symbolic Index and Progressive Disclosure

  • Index structure: A compact [ENGRAM] block is injected during prompt assembly (default budget of 700 characters, about 175 tokens, one memory per line).
  • Session freezing: The block is generated and frozen at session start, keeping request prefix bytes stable to support KV-cache reuse.
  • Drill-down tools: Use engram_recall or engram_detail to drill down instead of dumping raw hit results directly into context.
  • Recall algorithm: In-process BM25 recall (TF·IDF + tag/phrase weighting + time decay factor). Includes an entity neighbor table (esr_link format).
  • Recurring failure awakening: When a new failure is highly similar to an old error, older error entries are awakened based on recency and hit promotion (promoteHits), avoiding stacked failure records.
  • Fallback mechanism: If there are no local hits, it falls back to DSH’s own cross-session full-text index (ctx.sessionQuery); if still empty and containing CJK characters, it scans the latest session logs (zstd decompression, LRU cache).

Automatic Recall at Session Start

  • Enabled by default: autoRecallOnStart is enabled by default.
  • Mechanism: Runs deterministic BM25 recall once on the first user message in the session.
  • Injection form: Injects up to autoRecallLimit hits as a [RECALL] block (default 700-character budget).
  • Behavior: Pure read operation (does not increase hit counts) and excludes superseded entries.

Inter-Memory Semantic Management

  • Relationship definition: engram_store supports optional supersedes and contradicts parameters.
  • Supersession handling: Superseded entries (“stale truths”) are demoted to the tail of the recall list and excluded from the [ENGRAM] block, but can still be retrieved via engram_detail.
  • Contradiction handling: Contradicted entries keep their rank but are marked as · contradicted by <id>.
  • Automatic supersession: The autoSupersede setting (disabled by default) can automatically mark updates such as “updated to / no longer / switched…” as superseding older entries.

Failure → Repair Closed Loop

  • Command labels: Error memories carry a cmd: label signature.
  • Automatic repair: When that command subsequently succeeds, the plugin automatically creates a procedure memory (fixed: <cmd> — N earlier failing runs now succeed) and marks the old error entry as resolved, prioritizing the fix during recall.

ESR Lightweight Evidence Closed-Loop Protocol

  • Command set: esr_task / esr_close / esr_link.
  • Lifecycle: Tasks go through the lifecycle draft → active → stable. The stable state requires real evidence (artifact / evaluation / memory_ref).
  • Evidence verification: verifyArtifact (enabled by default) checks whether non-URL artifacts exist in the workspace (session cwd). If not, the task remains ACTIVE with a reason attached. force:true can skip the disk check.
  • Dependency management: esr_dep writes dependency edges into the task’s deps (blocking logic) and the shared link table, making dependencies visible edges in the graph.

Automatic Todo Sinking at Session End

  • Enabled by default: autoSinkTodosOnEnd is enabled by default.
  • Sinking mechanism: At session end, if the plan still has todo items, they are automatically sunk into ESR draft tasks (name is the todo text, description is marked “from session plan”).
  • Status: They are sunk as draft rather than active, avoiding evidence obligations. Explicit esr_claim / esr_task is required to activate them.

Technical Details

  • Required environment: Node.js >= 22.19.0; DSH >= 0.1.2-alpha.2 < 0.2.0-0.
  • Storage location: Data is stored in ctx.storageDomain.
  • Runtime mode: Runs with the current DSH process permissions.

Typical Usage

The plugin provides the following tools and interfaces for managing memories and tasks:

// 记忆操作
engram_store(supersedes: string, contradicts: string)
engram_recall()
engram_detail()

// ESR 任务操作
esr_task(entity: string)
esr_close(taskId: string)
esr_link(taskId: string, targetId: string)
esr_dep(taskId: string, depId: string)
esr_status()
esr_claim(taskId: string)

// HTTP 接口
GET /api/dsh-engram/goals
GET /api/dsh-engram/triggerstats

Use Cases and Notes

  • Use cases: Developers who need to introduce long-term memory into DeepSeek Harness agents but want to strictly control context token consumption while also requiring structured task management and evidence closed-loop capabilities.
  • Note: The plugin runs with the current DSH process permissions. Ensure you review the source code and license (MIT) before installation.