Decision-and-goal memory with lineage: explicit commands and a model tool record decisions deterministically, a status card re-anchors them across compaction, a lossless event stream with BM25+jieba retrieval backs it, and a scenario-level fidelity regression suite gates releases.
Install
# from GitHub (first run asks for allowBuilds approval — follow the hint, retry)
dsh plugin --profile web add github:zhaoyuntao-wl/dsh-plugin-thread
Any plugin you install runs third-party code with your own permissions — it can read your files, use your credentials, and reach the network, and tool approvals don’t sandbox it. GitHub-sourced plugins also run build scripts at install time — pnpm blocks those until you allow them, so an install can stop with ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED or ERR_PNPM_IGNORED_BUILDS; dsh prints the exact key to add under allowBuilds in your profile’s pnpm-workspace.yaml, and the install works on the next run. Allowing a build is a trust decision: only install sources you trust, and pin a commit (github:owner/repo#sha).
README
Thread's deep-integration plugin for DeepSeek Harness — session memory with lineage for coding agents, using the base's native channels end to end.
What it does
- Lossless capture — subscribes to
session/event; the full event stream lands in dual SQLite databases with stable origins (idempotent append). - Structural delivery, three triggers — a first-turn anchor (project identity
- behavior contract + status card), a re-anchor after every compaction, and a cross-agent state delta at every turn boundary. No per-turn card noise. The design follows the deterministic-log line of memory research (e.g. arXiv:2605.21997 “The Log is the Agent”); the compaction re-anchor targets the “Compaction Cliff” failure mode (arXiv:2608.22752).
- Native query tool —
query_session_memoryregistered throughctx.tools.registerinto the model's tool schema, with filesystem-style navigationls/cd/cat/grep. The embedded MCP server remains as a fallback channel. Retrieval is deterministic BM25 over the lossless stream (jieba word segmentation for Chinese) with citation pull-back — no embedding dependency by default; a hybrid layer can be added at the integration boundary (evaluated against the BM25 baseline on the eval suite, not bundled). - Behavior-contract skill — a
threadskill is registered into the base's skill catalog ("need details → call the tool") and injected at anchors, so the model does not rely on memory to know it has memory. - Output recognition — write/edit tools on markdown documents register
knowledge_assetswith lineage edges on write;/thread-reg astcovers explicit registration. - Explicit decision & preference channels — decisions are recorded through
/thread-reg dec(user,--supersedes <id>for chain evolution) or the model'srecord_decisiontool (the behavior contract instructs the model to call it when the user settles a decision or it commits to one). Preferences and lessons are recorded through/thread-reg fdb(auto-classified as correction when phrased as "don't"). Natural-language extraction of decisions/preferences is off — zero text-heuristic false positives; the lossless event stream remains the backstop for anything unrecorded. (Goal detection from short imperative messages and completion detection stay on, guarded against pasted/multi-line text.) - Read-only panel — what the model believes, on demand —
/thread-panel(and thethread_panelMCP tool) renders goals, the decision chain with supersession, open items, handoffs, the last injection receipt, acceptance evidence and recent events. Scope is the session merged with its project: decisions and goals registered by other sessions in the same project show up too, so a brand-new session is not blind to what the project already decided (it reads the same merge the status card uses). The receipt line answers “what exactly was fed to the model this round”; the panel resolves the session's project bucket from disk, so it works from a command context that never saw the agent object. - Evidence gate — “done” must be proven — decisions and completions carry
evidence instead of claims:
verifyruns each acceptance criterion, records command + exit code + env fingerprint + commit in theevidencetable, and returnspassed/failed/missing-env(a criterion with no command is missing environment, never a pass). Completing a goal whose criteria are unproven is refused, and the refusal names the missing criteria. On close the registered criteria are re-run automatically, so the handoff carries fresh evidence rather than the previous round's verdict. - Blocking questions are captured —
ask_user_questioncalls land inopen_questionswith theircall_id; a real answer settles the row, a timeout (recognized by the base's documentedpendingNoticetext, not keyword guessing) is recorded astimed_outso “the agent decided for you” stays visible instead of being smoothed into “answered”. - Closing sediment + inbox — closing words sediment in-progress goals into
todos;
/thread-cfmis the single pending-work inbox: todos (t#id) and candidates (c#id) in one view —docompletes/promotes (candidates accept a corrected text),cnldiscards,cnl allclears both. The status card surfaces the top candidates so they cannot pile up silently. - Behavior notes (1.0, stated plainly) — candidates are not produced
automatically: natural-language extraction of decisions/preferences is off, so
c#entries only ever hold pre-existing rows until the post-release extraction layer arrives; todos are produced actively (closing sediment + goal-completion self-healing). Decisions never expire on their own — close out time-bound ones with--supersedes. Goal completion detection is conservative (≥4 non-ASCII / ≥8 pure-ASCII overlap; short English goals are missed rather than mis-judged — abandon them with/thread-rev gol). See the Thread README "Honest boundaries" section for the full list. - Resource cleanup —
/thread-rev <ast|dec|fdb|gol> <ids|all>revokes registrations: decisions/preferences/assets are deleted (the event stream keeps the text), goals are abandoned through the state machine with their todos self-healed. Every structured row carries a visible#idon the status card, so memory stays human-editable end to end. - Session isolation —
/thread-iso//thread-uniso, and/thread-pub <ast|dec|fdb|gol> <ids|all>shares rows produced while isolated. - Optional active compaction — with
THREAD_AUTO_COMPACT=1the plugin monitors token pressure at turn boundaries and triggerscompactNowsilently; state re-anchors after every compaction either way. - Dev probe, inert by default — the package ships a
batch0-probemodule used for contract smoke-testing during development; it is inert unlessTHREAD_B0_PROBE=1is set, so normal sessions are unaffected.
Supported dsh versions
Local-first, no daemon — everything runs in-process: embedded SQLite stores, no background service, no cloud dependency. Headless and web profiles of the same machine share the same store, and offline sessions behave identically.
Verified: dsh 0.2.2-rc.1 (current; the CLI and its SDK sub-packages ship version-locked). 0.1.x is no longer declared — dsh 0.2.0 replaced the shared
pluginmessage source with per-producerMessageSourceMapkinds, which this plugin now declares; 0.1.x users should stay ondsh-thread@1.2.x.The plugin pins its SDK peers to
^0.2.2-rc.1(dsh-tools/dsh-agent/dsh-session/dsh-user-questions) and@deepseek-ai/cordisto^4.1.0(dsh 0.2.2-rc.1 pins cordis at~4.1.0); every upgrade is verified by an isolated contract probe (type-level compile against the released SDK plus a live headless profile run) and the CI compat matrix (.github/workflows/ci.yml) before this table is updated.No promise is made beyond the verified entry; each new dsh release is evaluated and the matrix extended before support is claimed.
Install
dsh plugin add dsh-thread
dsh plugin add dsh-thread@latest # 升级:同命令重装最新版(core 经 ^1.0.0 依赖自动跟随)
The plugin pulls its kernel (@thread-memory/core) through a ^1.0.0 range,
so new installs and re-adds pick up the latest core automatically. The runtime
logs the resolved core version at startup ([dsh-thread] thread core vX.Y.Z)
and the embedded MCP server reports it in its handshake.
All dsh plugins must be referenced in a profile's bundles to take effect. In
~/.dsh/profiles/<your-profile>/package.json:
{
"name": "dsh-profile-my",
"private": true,
"dependencies": {},
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-headless",
"dsh-thread"
]
}
}
}
Zero configuration beyond that: @thread-memory/core + better-sqlite3 resolve
as dependencies; capture and injection start as soon as the plugin is activated.
Note (native module): if the plugin fails to start with "Could not locate the bindings file", pnpm 10 ignored the
better-sqlite3build script during install. Fix with one command in the profile directory:cd ~/.dsh/profiles/<your-profile> pnpm rebuild better-sqlite3This is a pnpm 10
onlyBuiltDependenciespolicy, not a plugin bug.
Configuration
| Config | Default | Meaning |
|---|---|---|
budgetLines |
200 | Status card line budget |
feedbackRows |
50 | Feedback rows consulted by the tool guard |
busyRetries / busyRetryDelayMs |
20 / 100 | SQLITE_BUSY retry policy |
compactPressureTokens |
0 | Active-compaction token threshold (0 = off; requires THREAD_AUTO_COMPACT=1 to pull the compaction service) |
Commands
Registered as real dsh commands — visible in the command palette, /-completable,
and executed directly (no model round-trip). The same lines also work as plain
messages where no command UI exists. One grammar, six commands:
| Command | Effect |
|---|---|
/thread-reg <ast|dec|fdb|gol> |
List that resource's rows (ids for rev/supersede) |
/thread-reg <ast|dec|fdb|gol> <text> |
Register: ast = path (directories expand recursively, cap 50) · dec = decision (active immediately; --supersedes <id> evolves the chain) · fdb = preference/lesson (auto-classified by "don't" phrasing) · gol = goal |
/thread-rev <ast|dec|fdb|gol> |
List that resource's rows |
/thread-rev <ast|dec|fdb|gol> <ids|all> |
Revoke: dec/fdb/ast are deleted (event stream keeps the text) · gol is abandoned (state machine + todos self-heal) |
/thread-cfm |
Pending-work inbox: todos (t#id) + candidates (c#id) |
/thread-cfm do <id> [text] |
t# complete a todo · c# promote a candidate to an active decision (optional corrected text) |
/thread-cfm cnl <id> / cnl all |
Discard one item / clear the inbox |
/thread-iso / /thread-uniso |
Silence / restore a session |
/thread-pub |
List isolated rows (all resources, ids for sharing) |
/thread-pub <ast|dec|fdb|gol> <ids|all> |
Share isolated rows |
/thread-handoff [target] |
Produce a handoff from this session's state (optional target role; no target = project-addressed) |
/thread-panel |
Read-only panel: goals · decision chain (with supersession) · open items · last injection receipt · acceptance evidence · handoffs · recent events |
Evidence gate
Acceptance is evidence, not assertion:
// record + run criteria (omit `criteria` to re-run what was registered before)
await mcp.callTool({ name: "verify", arguments: { criteria: [
{ key: "unit-tests", command: "pnpm test" },
{ key: "lint", command: "pnpm lint" },
] } });
// → 验收 1/2 已证(缺:lint) + per-criterion { status, exit, output, evidenceId }
- Each run stores command, exit code, environment fingerprint and commit in
evidence; the panel shows the latest row per criterion. checkCompletionGaterefuses to mark a goal complete while any registered criterion lacks a passing row, and the refusal is surfaced to the model ([Thread 证据门] 目标未标完成:#3 缺 lint), not swallowed.- Criteria with no command are
missing-env— they block completion but are never counted as proof. - Handoff briefs gain one line:
验收:验收 1/2 已证(缺:lint).
Visibility and receipts
The status card is injected as base instructions, so it is not a chat bubble.
To keep “what was injected” auditable, every injection writes a receipt
(kind: anchor | status-card | handoff, timestamp + summary) that the panel
renders as 「本轮注入」. Cards are rebuilt from the store at injection time —
they are never cached — and refreshed after decision confirmation, structural
commands, closing sediment and compaction, plus once per turn in agent/pre-step.
Handoffs (for orchestrators)
Thread carries state across sessions: a finishing session leaves a compact brief — goal, up to three active decisions, open items, next steps, artifact pointers — and the receiving session starts with it instead of rediscovering it.
Thread does not schedule, launch, or retry anything. It is the state base your orchestrator sits on, not another orchestrator.
// start a worker with two extra fields
env: { THREAD_TASK_ID: taskId, THREAD_ROLE: "dev" }
// claim the handoff addressed to that task/role (atomic; marks it delivered)
const { content } = await mcp.callTool({ name: "handoff_next", arguments: { task_id: taskId, role: "dev" } });
// → { id, status, brief: { goal, decisions[], open[], next[], artifacts[], conditions[] } }
// acknowledge once consumed
await mcp.callTool({ name: "handoff_ack", arguments: { id } });
Guarantees: claiming is a single UPDATE … RETURNING (two workers never get the
same row), producing is idempotent per goal, ack is idempotent, lookups are
project-scoped, and any handoff failure fails open so the agent path never
blocks. The brief carries pointers only — documents stay the artifact layer.
Measured (2026-11-13, three arms × 5 runs, empty workspace, same memory):
| handoff pushed | memory only | no Thread | |
|---|---|---|---|
| recalls the earlier decision | 5/5 | 5/5 | 1/5 |
| follows the producer's chosen next step | 5/5 | 0/5 | 0/5 |
| lookups by the receiving agent | 1.0 | 6.8 | 4.2 |
| mean wall time | 7s | 15s | 12s |
Details: Thread docs — handoff.
MCP fallback
The package ships an embedded MCP server (bin: dsh-thread) exposing the same
query_session_memory contract over MCP for bases and setups where native tool
registration is unavailable, plus thread_panel, verify, handoff_next and
handoff_ack. See the Thread Memory
Protocol.
Repository relationship
This repository hosts the dsh deep-integration plugin. The base-agnostic kernel
(@thread-memory/core) and the Qoder adapter live in the main
Thread repository.
License
MIT
Links
More in this category
vectorize-io/hindsight#coding-agents★ 62276
Hindsight, agent memory that learns: long-term project memory with auto recall and retain, knowledge pages, deep reflection, and per-repo memory banks.
volcengine/OpenViking#examples/dsh-memory-plugin★ 42543
OpenViking memory and context bundle for DeepSeek Harness: pre-step auto-recall and profile injection, session capture, `viking://` URI guarding, and recall/write memory tools backed by an OpenViking server.
MemTensor/MemOS#memos-local-plugin★ 12467
Local-first memory plugin for DeepSeek Harness: layered L1/L2/L3 memory with automatic capture, manual memos_* retrieval tools, and a built-in memory viewer.
agentscope-ai/ReMe#dsh★ 3827
Connects DeepSeek Harness to ReMe's local-first, self-evolving personal knowledge base: automatically captures completed main-agent conversations as user-owned Markdown memory, searches conversations and source material through reme_search with BM25, optional embeddings, and wikilink expansion, and schedules daily memory consolidation.
zilliztech/memsearch#MemSearch★ 2915
Shared Markdown memory for DSH and other coding agents, with automatic capture, pre-step context injection, searchable recall, and memory-to-skill self-evolution through a review panel.
vshulcz/deja-vu#extensions/dsh★ 1639
Cross-session memory and context recovery across forty-five other coding agents (45+) on this machine, reading session files they already wrote before install (Claude Code, Codex, Cursor, Windsurf, Trae, Antigravity, VS Code Copilot Chat, opencode, OpenClaw, Hermes, Kimi, Qoder, Cline, Zed, Magpie and more): six tools (deja_recall, deja_session, deja_blame, deja_fix, deja_how, deja_remember), a /deja command, and optional automatic recall injected into runtime context. Local BM25 CLI/MCP index, no LLM, no embeddings, no network (dsh plugin --profile web add dsh-deja).
Community comments
Comments are public GitHub Discussions. Loading them connects to GitHub and Giscus; a GitHub account is required to post.