@flowingspring/dsh-workspace-memory 0.1.0

package/DESIGN.md

@@ -0,0 +1,137 @@
+# DSH Workspace Memory — Design
+
+## Goal
+
+Provide durable, workspace-scoped memory for DeepSeek Harness while remaining
+independent from any particular UI or voice plugin. Ordinary DSH Agents and
+`dsh-voco` share the same memory whenever their Sessions have the same `cwd`.
+
+The plugin owns memory. Callers only cross the `WorkspaceMemory` seam.
+
+## External interface
+
+```ts
+interface WorkspaceMemory {
+  recall(input: RecallInput): Promise<MemoryContext>
+  checkpoint(input: CheckpointInput): Promise<CheckpointResult>
+}
+```
+
+- `recall` returns a bounded stable summary plus query-relevant entries.
+- `checkpoint` accepts newly completed conversation messages. It buffers,
+  deduplicates, decides whether a stage is ready, distils durable facts, and
+  persists them. Callers do not implement checkpoint policy.
+- Both operations resolve scope from `sessionId` or an explicit `cwd`.
+- Missing/empty `cwd` resolves to the global scope.
+- A project scope recalls both global and workspace entries; writes may be classified
+  as `global` or `workspace` by the distiller.
+- Failure to recall memory never prevents an Agent or voice response.
+
+The production adapter is the Cordis `workspaceMemory` service. Tests use an
+in-memory/fake adapter at the same seam.
+
+## Scope and storage
+
+Default root: `$DSH_HOME/workspace-memory` (fallback `~/.dsh/workspace-memory`).
+
+```text
+workspace-memory/
+  global/
+    memory_summary.md
+    memory_entries.json
+    state.json
+    checkpoints/
+    summary_history/
+  scopes/
+    ws-<sha256-prefix>/
+      scope.json
+      memory_summary.md
+      memory_entries.json
+      state.json
+      checkpoints/
+      summary_history/
+```
+
+Workspace identity is the normalized absolute `cwd`. Runtime data stays out of
+the user's Git checkout unless `memoryDir` is explicitly configured there.
+Writes use a per-scope promise queue and atomic temporary-file rename.
+
+## Retrieval
+
+Version 1 deliberately has no BM25, vector database, or embedding dependency.
+It performs structured lexical retrieval over parsed entries:
+
+1. exact phrase and normalized substring matches;
+2. title, retrieval-term, and tag matches;
+3. ASCII word and CJK character-bigram coverage;
+4. description/content matches;
+5. importance, recency, and a short-lived surfaced-memory penalty.
+
+The result is bounded by entry count and UTF-8 bytes. Memory is always treated
+as reference data and never as an instruction overriding the current user.
+
+## Checkpoint policy
+
+A stage is logical, not hourly. A checkpoint becomes eligible when any of the
+following is true:
+
+- a background Agent turn/task completes;
+- at least `checkpointTurns` completed user turns are buffered (default 10);
+- buffered text reaches `checkpointChars` (default 4000 characters);
+- the buffer remains idle for `idleCheckpointMs` (default 5 minutes);
+- the Session closes or a caller explicitly forces a checkpoint.
+
+Only completed messages enter the buffer. Checkpointing is asynchronous from
+Agent/voice response delivery. A scope queue prevents concurrent mutations.
+
+The distiller outputs durable atomic facts only: preferences, project facts,
+decisions, conventions, fixes, and explicitly requested memories. Greetings,
+temporary instructions, progress chatter, and unconfirmed speculation are
+discarded. Similar existing entries are updated instead of duplicated.
+
+After `consolidateEvery` successful checkpoints (default 5), the summary is
+rebuilt from active entries. A bounded history is kept before replacement.
+
+## DSH integration
+
+- `systemPrompt.context` injects the stable summary on every Agent step.
+- `agent/pre-step` calls `recall` for the current user message and appends only
+  relevant entries on step 1.
+- `agent/turn-stopping` submits the completed turn to the checkpoint buffer
+  without forcing an LLM distillation; threshold, idle, task-end, and close
+  policy decides when a stage is ready.
+- memory tools provide explicit search, remember, and forget operations.
+- `memory_search` remains the Agentic second-search seam: an Agent can issue
+  alternate queries when the automatic first recall is insufficient.
+
+## Voco integration
+
+- Before frontend routing, Voco optionally calls `workspaceMemory.recall`.
+- The returned context is included as quoted reference material for the router.
+- Completed voice utterances are submitted to `checkpoint`; policy remains
+  inside the memory module.
+- Voice Session close forces a final evaluation of the buffered stage.
+- If the service is absent or fails, Voco uses its existing behavior unchanged.
+- Delegated background Agents already inherit the source `cwd`, so they resolve
+  the same workspace scope without a Voco-specific storage path.
+
+## Safety and failure behavior
+
+- Obvious credential-shaped values are rejected from automatic persistence and
+  redacted from recall output.
+- Malformed LLM output leaves the store unchanged.
+- Memory I/O, retrieval, or distillation failure is logged and never fails the
+  foreground Agent/voice operation.
+- Checkpoint input has a hard byte cap.
+- Memory context is clearly delimited and labelled as untrusted reference data.
+
+## Initial acceptance criteria
+
+1. Two Sessions with the same normalized `cwd` recall the same entries.
+2. Different workspaces remain isolated.
+3. Exact, ASCII-token, and Chinese-bigram queries return ranked entries.
+4. Repeated checkpoint messages are deduplicated by message id.
+5. Threshold, idle, task-end, and close triggers are deterministic in tests.
+6. Voco behaves exactly as before when `workspaceMemory` is unavailable.
+7. A Voco frontend query receives bounded memory when it is available.
+8. Core store/retrieval tests require no running DSH process or remote model.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FlowingSpring
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# dsh-workspace-memory
+
+面向 DeepSeek Harness 的 Workspace 长期记忆插件。它让相同工作目录下的多个
+Session 共享一份稳定摘要和长期原子记忆，并通过可选 Cordis 接口与
+[`dsh-voco`](../dsh-voco/README.md) 的语音前台集成。
+
+## 当前能力
+
+- 按规范化 `cwd` 隔离 Workspace；相同 Workspace 的 Voice Session、后台
+  Agent Session 和普通 Session 共享记忆。
+- 每个 Agent step 自动注入一份有上限的 `memory_summary.md`。
+- 在 Agent 第一 step 根据当前用户消息自动检索相关长期记忆。
+- 不使用 BM25、Embedding 或向量数据库：采用精确短语、英文词、中文字符
+  bigram、标签、重要性和新近度综合排序。
+- 任务结束、10 轮对话、4000 字符、空闲 5 分钟或 Session 关闭时评估
+  checkpoint；不会按固定小时机械写入。
+- Agent turn 结束只进入 checkpoint 缓冲，不会每轮强制调用记忆蒸馏模型。
+- LLM 只蒸馏长期有效事实；重复/近重复事实会更新原条目。
+- 提供 `memory_search`、`memory_remember`、`memory_forget` 工具。
+- 凭据形态内容默认拒绝持久化，并在模型输入前脱敏。
+- 没有安装本插件时，`dsh-voco` 保持原有行为。
+
+详细契约见 [DESIGN.md](./DESIGN.md)。
+
+## 安装（当前源码版本）
+
+```powershell
+pnpm install
+pnpm build
+$plugin = (Resolve-Path .).Path
+dsh plugin --profile web add $plugin
+```
+
+重启 `dsh web` 后生效。尚未发布 npm 时请使用本地路径安装。
+
+运行数据默认写入：
+
+```text
+$DSH_HOME/workspace-memory
+```
+
+如果没有设置 `DSH_HOME`，则使用 `~/.dsh/workspace-memory`。数据不会写进
+Git 项目目录，除非显式配置 `memoryDir`。
+
+## 配置
+
+安装生成的 loader row 可以覆盖以下配置：
+
+```yaml
+- insert:
+    - id: workspace-memory
+      name: '@flowingspring/dsh-workspace-memory'
+      config:
+        memoryDir: ''
+        checkpointTurns: 10
+        checkpointChars: 4000
+        idleCheckpointMs: 300000
+        consolidateEvery: 5
+        summaryMaxBytes: 3000
+        recallMaxBytes: 5000
+        recallLimit: 8
+        checkpointMaxChars: 40000
+        keepSummaryVersions: 10
+        surfacedPenalty: 8
+        summarizeProvider: ''
+        summarizeModel: ''
+```
+
+`summarizeProvider` 和 `summarizeModel` 为空时使用 DSH 当前默认模型。
+
+## 存储结构
+
+```text
+workspace-memory/
+├── global/
+└── scopes/
+    └── ws-<hash>/
+        ├── scope.json
+        ├── memory_summary.md
+        ├── memory_entries.json
+        ├── state.json
+        ├── checkpoints/
+        └── summary_history/
+```
+
+项目 Session 会同时读取 `global/` 与对应 `scopes/ws-<hash>/` 的摘要和长期记忆；
+全局记忆适合用户偏好和通用工作方式，Workspace 记忆适合项目架构、决策和修复。
+
+`memory_entries.json` 是事实来源；`memory_summary.md` 是自动注入的短摘要；
+`checkpoints/` 保留每次阶段性蒸馏的可审计 Markdown 记录。
+
+## 开发验证
+
+源码与测试均使用 TypeScript；`pnpm build` 将 ESM JavaScript 和类型声明生成到
+`lib/`，该目录不提交到 Git。
+
+```powershell
+pnpm test
+pnpm typecheck
+pnpm build
+pnpm pack --dry-run
+```
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,10 @@
+# Workspace memory is independent from Voco. Installing both enables their
+# optional Cordis service integration; either plugin can run alone.
+- insert:
+    - id: workspace-memory
+      name: '@flowingspring/dsh-workspace-memory'
+      config:
+        checkpointTurns: 10
+        checkpointChars: 4000
+        idleCheckpointMs: 300000
+        consolidateEvery: 5