dsh-recall

🌏 中文 · English

AI never forgets what you told it.

A native DeepSeek Harness (DSH) plugin that gives the agent a memory maze — corridors and rooms built from every conversation you have had together. Every decision, setting, discussion, or casually mentioned requirement is remembered. Ask "where were we?" and it walks the maze, brings back the conversation verbatim, and answers as naturally as if it had never forgotten — you won't even notice it thought for a moment.

Conversation history recall · Three-layer retrieval (literal / fuzzy / semantic) · Fully local & offline · Compaction-proof

• While searching, a quiet sweeping light appears in the corner:

  

• When done, no trace:

  

Who is it for

• Heavy users of long sessions — conversations spanning days and hundreds of turns, too long to scroll back through
• Writers / RP / tavern players — settings, foreshadowing, and character relationships scattered across months of chat
• Code & doc maintainers — the reasoning behind past decisions and pitfalls, now reduced to a one-line summary
• Anyone who has said "didn't we discuss this before?" — it brings back the original words instead of making you retell them

Conversely, if your sessions are short and easy to scroll, you probably don't need it — it is built for "history too long, memory compacted" scenarios.

Quick start

dsh plugin --profile web add dsh-recall@0.2.2

One command: the package ships its own composition patch (bundle layer), so the plugin and the search index it needs are wired up automatically. Restart dsh web. Nothing else to do — the model ships with the package (~37MB full install), the index builds on first search, and semantic warm-up finishes quietly in the background (a few minutes, imperceptible to you).

You can also install / disable / uninstall dsh-recall from the Add-ons block of the Plugin Management tab in dsh-extension-hub.

Install from source (git clone):

dsh plugin --profile web add git+https://github.com/Relistencode/dsh-recall.git

The repository tracks the model (models/model_merged.onnx) and the vendored runtime, so a git install is fully functional offline with no build step and no allowBuilds entry. The optional dsh-recall-models dependency is still attempted from npm; if it fails to resolve, the in-repo model is used instead — either way the semantic layer works. The harness resolves all paths through $DSH_HOME (default ~/.dsh), so this works identically regardless of where your harness home lives.

Optional configuration

- id: recall
  name: dsh-recall
  config:
    semantic: false   # disable the semantic layer (literal + fuzzy only, smaller package)
    warmup: gentle    # slower warm-up, lower background CPU (only during warm-up; zero afterwards)

What it is not

• ❌ Not context engineering — it does not cram history into the model window
• ❌ Not prompt engineering — it does not rely on prompts to make the model "pretend to remember"
• ❌ Not a memory-document system — no MEMORY.md or manual notes to maintain
• ✅ It is actual recall: on-demand retrieval of the original records — including history already compacted away (compaction only summarizes; the original text stays searchable forever)

Capability overview

Architecture

• Turn lifecycle (top): one recall is a straight line — the user asks, the agent calls the recall tool, the three layers are searched, hits are grouped into events per session, and the agent receives either a light coarse recall or a drill-down window, depending on what it needs.
• Retrieval layer: three independent retrieval channels (literal / fuzzy / semantic) that merge under a coverage gate (see Three-layer hybrid retrieval).
• Index & data: everything is read through official services (ctx.sessions / ctx.sessionPersistence / ctx.sessionQuery) — no .zstd parsing, no private formats. The plugin's own recall-index.db (SQLite) holds the fuzzy index, the vectors and the trigram FTS.
• Governance & scope: the scope red line (session by default), the coverage gate, the degradation chain, and the token budget live here.
• Automatic layer: a compaction/summary listener that turns every compaction into one lightweight anchor, so the agent keeps its bearings after history is folded away.

Core mechanisms

Three-layer hybrid retrieval

• The fuzzy layer is the primary path (it already covers the literal layer's ground with far more tolerance); the official FTS5 layer is the fallback; the semantic layer joins the mix only when it covers ≥90% of the literal/fuzzy hits — otherwise it stays silent rather than dragging the ranking down.
• Any layer failure degrades silently to the layer below — semantic → fuzzy → literal, never an error. The recall tool always answers.
• Inference runs in a worker thread (WASM on the main thread would block the host event loop; measured ~9.6 texts/sec with zero main-thread impact).
• Everything runs locally and offline — no external model APIs, no network.

Progressive disclosure

Recall happens in two stages, and the second stage only fires when the agent actually needs it:

Measured live on a real instance: coarse recall saved ~80% of tokens versus the old full-context windows (2500–3000 → ~600 on a 10-session hit, pre-aggregation). Event aggregation keeps the same discipline — snippets only, full event text one drill-down away — so a coarse call stays under ~800 tokens. Irrelevant content never enters the context — and when it matters, the original text is always one drill-down away.

Compaction anchors

Compaction is where memories get lost — the harness summarizes, the original text is shadowed. dsh-recall listens for compaction/summary and immediately injects one lightweight anchor into the compacted session:

• Content: the LLM summary + up to 3 key original fragments (user messages first, then longest text blocks).
• Expiry: after 3 assemblies, the anchor disappears — it is a bearing, not a crutch.
• Escape hatch: the exact original text stays one detail drill-down away, always.
• Verified end-to-end on a live instance: a real /compact produced the anchor in the very next assembly, with the correct content, expiring automatically after 3 turns.

Scope & privacy

• Default scope is the current session only — cross-session (workspace) and cross-project (all) searches happen only on the user's explicit request.
• The reply layer is invisible: a quiet "Recalling…" sweep, one "Recall complete" line, nothing else. Results never enter the UI — the agent presents them naturally.
• Data stays on this machine: no external APIs, no telemetry, no network.

Measured

Token benefit (live, v0.2.1)

Retrieval quality (golden set)

Synthetic 4-session corpus (32 docs) with 23 hand-annotated queries (exact / fuzzy-typo / paraphrase / cross-session), run in-memory with the real model — repro: node eval/run-golden.mjs:

• The hybrid merge beats every single layer (+19% recall@5 over the best solo layer) — all three layers contribute, none is decoration.
• The literal layer alone is the weakest (exact match only; FTS5 unicode61 is word-splitting-blind for Chinese) — confirming its fallback role.
• The fuzzy layer is the primary path (beats semantic solo); the semantic layer adds recall on paraphrase and word-swap queries.
• Coverage gate verified: at half warm-up the gate correctly falls back to fuzzy-only (0.587 = fuzzy-only); running the half-warmed semantic layer anyway yields a small gain on this small corpus (0.674) — the 0.90 gate is a conservative safety default for real long sessions, not tuned to this set.
• Known misses (documented boundaries): zero literal-overlap paraphrases below the semantic min-score (e.g. "打码" for "脱敏") and abstract-concept queries (e.g. "方案").

Recent updates

Roadmap

v1 · Done — Three-layer hybrid retrieval: official FTS5 literal / self-built trigram+bigram fuzzy / local bge embedding semantic; coverage gate, background warm-up, silent degradation chain.

v2 · Retrieval control

• [x] Two-stage recall (browse/detail drill-down): lightweight coarse recall by default (title + snippet, ~100–800 tokens); the agent picks the relevant sessions and requests full context on demand — irrelevant content never enters the context
• [x] Compaction anchors: on compaction/summary, inject one lightweight anchor (summary + key fragments) automatically; the original text stays one drill-down away
• [x] Proactive recall: the agent calls on its own when needed (after compaction, when details are missing); explicit user requests also work
• [x] Result aggregation: repeated mentions of one topic merge into complete "episodes" — consecutive hits ≤5 text blocks apart group into [startSeq..endSeq] events (threshold measured on real data: p50 same-topic gap = 3, 61% ≤ 5); the full event text stays one detail browse away

v3 · Memory organization

• Topic clustering: embed similarity clustering, present results grouped by topic
• Memory distillation: extract settings & decisions across sessions into durable long-term memory
• Longer term: evaluate topic-based / layered compaction mechanisms — evaluation only, no changes to DSH core

Known boundaries

• Semantic bridging for very short queries (≤4 chars) is weak (bge short-text cosine has limited separation); the fuzzy layer's LIKE fallback covers it
• Semantic ranking is not fully reliable for queries with zero literal overlap — the fuzzy layer is always the primary path, and the agent makes the final call
• The model is int8-quantized: semantic quality is "good enough" by design; swap in an fp32 model (~4× size) for maximum quality

Development & testing

node .smoke-recall.mjs      # unit + integration (mocked, no model needed) — 90+ assertions
node .smoke-semantic.mjs    # real-model integration (requires models/ present)

Covers: tokenizer alignment (token-for-token against transformers.js), index increments, scoping, hybrid ranking, degradation, warm-up, event aggregation.

Modules

Publish structure

• dsh-recall — main package (code + vendored runtime + tokenizer)
• dsh-recall-models — optional dependency (23MB model); npm installs it by default; --omit=optional yields the lightweight build, which degrades silently when the model is absent

References & acknowledgments

• Official: @deepseek-ai/dsh-session-query(-sqlite), dsh-tools, dsh-session-persistence
• Model: BAAI/bge-small-zh-v1.5 (MIT) · onnx-community int8 export · onnxruntime-web (MIT)
• Ecosystem: dsh-plugin-recall (official-FTS recall tool), dsh-mneme (local semantic memory, hybrid-recall degradation ideas)

License

MIT