dsh-memory

Memory retrieval plugin for DeepSeek Harness (dsh): a wiki double-link memory graph with 9 tools — hybrid search, read, list, link-scan, remember, forget, knowledge compile, graph health-check, and a resident retriever subagent.

记忆系统插件：为 dsh 提供「wiki 双链记忆图谱」——混合检索（向量+全文）、读写删、知识编译、图谱健康检查、驻留检索员子代理。

Features

Tool	What it does
memory_list	List the memory index (project + global slugs)
memory_search	Hybrid retrieval: semantic vector (memory_vector.py hybrid) + fulltext grep (auto-falls back to JS-native scan when grep is missing)
memory_read	Read a memory page by slug
memory_link_scan	Double-link traversal: in-edges (pages referencing the slug) + out-edges
memory_remember	Write a new memory into the dsh write zone (never touches your read source)
memory_forget	Delete from the write zone only (reference scan first)
memory_retrieve	Spawn a resident retriever subagent (continuable spawn + toolFilter allow-list + three-stage report); follow up with send_message, survives dsh restarts
memory_compile	Knowledge compiler: suggest-links / compile (five-section wiki page or update diff preview) / validate / slug-list — candidates only, you confirm before committing
memory_health	Graph health-check: graph-stats (density ≥1.5, orphans <20%) / reachability (multi-hop) / deadlink — pure JS, no python/grep needed

Plus a system-prompt section with memory-collaboration rules (remember-three-steps, chain-reading, compile-then-review).

Installation

1. Add the plugin to an agent preset

In your preset agent.cordis.yml, register the plugin by absolute path (or package name after publishing):

- id: dsh-memory
  name: /path/to/dsh-memory-plugin/lib/index.js
  # optional overrides (defaults shown below are the built-ins):
  config:
    readHome: ~/.reasonix-local
    writeDir: ~/.dsh/memory/
    scriptsDir: ""        # empty = bundled lib/scripts
    extraReadDirs: []
    retrieverProvider: spawn

2. Layout conventions

The plugin reads a .reasonix-local-style memory home:

<readHome>/
├── projects/
│   └── <any-project>/        # auto-discovered, no hard-coded names
│       └── memory/*.md       # project memories (wiki pages)
└── memory/
    └── global/*.md           # global memories

• readHome default is ~/.reasonix-local; all paths support ~ expansion and ${VAR} environment references.
• If you don't have a Reasonix memory layout, an empty home just reports "empty/unreadable" — you can start writing with memory_remember immediately.

3. Support matrix

Platform	No python	python3/python/py	+ vector index (bge cached)
Linux	✅ fulltext (JS-native scan)	✅ TF-IDF + bigram hybrid	✅ semantic hybrid (bge-small-zh)
macOS	✅ fulltext (grep or JS fallback)	✅	✅
Windows (no grep)	✅ JS-native scan	✅	✅

• No python: memory_search skips the vector leg and labels results （向量不可用，仅全文） — functionality stays usable (TF-IDF vectors are optional).
• No grep (native Windows): fulltext search, in-edge scan and forget reference scan all fall back to a JS-native substring scan (equivalent to grep -rnF semantics).
• bge model / pylibs: optional. memory_vector.py is zero-dependency (Python stdlib) with a pluggable embed_text(); the semantic model path is only used when the cache is built by your pipeline.

4. Runtime prerequisites

Feature	Prerequisite
memory_retrieve (retriever subagent)	dsh-subagent plugin family + a subagent provider supporting prepareContinuable (spawn in the default preset does) + session persistence — all present in the standard web deployment of dsh. Headless profiles without agent-presets/subagents degrade gracefully (the tool returns guidance instead of throwing).
memory_search vector leg	any of python3 / python / py on PATH
codegraph integration	optional; the preset snippet below masks codegraph_memory_* with --graph-only

Configuration

config:
  readHome: ~/.reasonix-local      # read source (read-only for dsh)
  writeDir: ~/.dsh/memory/         # dsh write zone (memory_remember/forget)
  scriptsDir: ""                   # override memory-map scripts dir; empty = bundled
  extraReadDirs: []                # extra memory dirs appended after auto-discovery
  retrieverProvider: spawn         # subagent provider for memory_retrieve

Trust boundaries:

• Read tools work directly on readHome; the plugin never writes there.
• memory_remember/memory_forget only touch writeDir.
• memory_compile only produces candidates; you commit them via memory_remember.

Full preset example

# agent.cordis.yml (standard preset + dsh-memory + codegraph)
- id: dsh-memory
  name: /path/to/dsh-memory-plugin/lib/index.js
  config:
    readHome: ~/.reasonix-local

- id: mcp-codegraph
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: codegraph
    transport: stdio
    args: ["--graph-only"]   # masks codegraph's own memory-* tools

Memory page format

Five-section wiki page (what memory_compile generates and validate checks):

# Title
## 结论（一句话）
## 关键事实
## 路径与方法论
## 关联（双链）
## 元数据（类型/来源/更新/空检索记录）

Double links are [[slug]] references between pages; memory_health measures graph density (target ≥1.5 edges/page, orphans <20%) and multi-hop reachability.

Ecosystem

This is a dsh-plugin for the DeepSeek Harness plugin ecosystem — add the dsh-plugin topic to the repository to be discovered by community directories (e.g. awesome-dsh-plugins, awesome-deepseek-harness).

License

MIT