LYRA-88/workspace_memory_dsh

dsh-workspace-memory

English · 中文说明

面向 DSH（cordis）架构的工作区级持久记忆。该插件在每个会话工作区下维护一个 project_memory/ 目录，并向模型上下文注入一个有界的节点索引，使智能体能够通过覆盖性命题进行导航，而不是扫描一个无类型的目录。

flowchart LR
subgraph W ["写入路径 — 会话结束"]
EV["会话事件"] --> EX["提取 + 去重"] --> CL["LLM 分类"] --> RD["审阅文档"] --> PV["浏览器面板预览差异 → 提交"]
end
PV --> FN
subgraph S ["每个工作区的 project_memory/"]
FN["节点 P 漏斗core.md · regular.md · log"]
VS["向量分片（余弦）"]
GR["graph.jsonnodeEdges + entryLinks"]
FN --> VS
FN --> GR
end
subgraph R ["读取路径 — 下一次会话"]
Q["查询"] --> HR["混合检索余弦 + 词法 → RRF"] --> CTX["有界节点索引→ 模型上下文"]
end
VS --> HR
GR --> HR

记忆模型（v3）

从对话中提取的原子命题按两个语义层级进行分类：

1. 第 1 层 — 语义分类：命题被归组到覆盖性命题之下（“大命题”，持久化为节点 p）。
2. 第 2 层 — 向量网络：每个节点 P 以及每个漏斗条目都会被嵌入；层级之间的相关性即向量空间距离。细粒度条目可以链接到多个更高层节点（多对多 entryLinks），而节点则连接到其 k 个最近邻（nodeEdges）。

在节点网络之下是三层漏斗（每个节点）：core.md（核心事实）、regular.md（常规记忆）、log/.md（过程日志，原始，不向量化）。它们共同构成了分层向量网络。检索是混合式的：向量余弦 + 词法评分通过 RRF 合并，因此未配置的工作区会退化为词面召回，而不会丢失图结构。

存储/计算层没有“维度”概念；旧版维度路径仅作为 legacyLabel 保留——这是 GUI 用于分组导航的显示标签。

存储布局

project_memory/
.registry.json                     # 工作区注册表
_backup/v2/-/              # 迁移前快照（每个 id 保留 2 份）
_system/                           # 迁移锁
/
manifest.json                    # schema:3 — nodes[], graphVersion, migratedFrom?
doctrine.md
nodes//funnel/{core.md, regular.md, log/.md}
vec/index.json + vec/.json   # 向量分片（JSON，暴力余弦）
graph.json                       # nodeEdges + entryLinks（多对多）
早期版本创建的工作区（无 schema 清单，带有 dimensions 树）会在加载后首次 ensureWorkspace 时自动迁移：确定性的节点 id、通过相同 sha1 方案保留的条目 id、dimTreeVersion 作为 graphVersion 沿用、在任何写入前进行整目录备份，以及通过 _system/migrate-.lock 实现可重启的恢复。

嵌入配置

OpenAI 兼容端点通过插件根目录下的 api.json 进行配置（也支持 /project_memory/api.json 覆盖）：

{ "embedding": { "baseUrl": "https://…/v1", "apiKey": "sk-…", "model": "text-embedding-3-small", "dimensions": 1536 } }

配置缺失或无效 → 仅词法模式（needsReindex 会标记子项目，以便后续执行 memoryReindex）。

安装

该 bundle 有意安装在树外：

dsh plugin --profile web add

服务器端更改需要重启 dsh web 进程。浏览器端以 lib/client.js 形式提供。

客户端界面：

- MemoryButton（conversation.input.memory）——为当前会话打开记忆预览/确认面板。
- MemoryPreviewPanel（conversation.input.overlay）——读取所绑定子项目的文档，预览更新差异并提交（previewUpdate / commitUpdate）；绑定/解绑会话。
- MemoryTreeSection（sidebar.workspaces.memoryTree）——将工作区记忆组与普通侧边栏树一起内联渲染。

远程 API

workspaceMemory Remote 命名空间暴露 18 个方法：listSubprojects / listSubprojectsByPath、bindSession、classify / commitClassify、previewUpdate / commitUpdate、renameSubproject / renameSubprojectByPath、deleteByPath（+ getDeleteConfirmationTokenByPath）、reconcileAccountedSessions、listSessionIdsByPath、governance、search、seed、memoryReindex / memoryStatus。

开发

npm install      # pinned devDependencies — @deepseek-ai/* packages from public npm, esbuild, typescript
npm run build    # server/ TS -> lib/; client esbuild bundle -> lib/client.js
npm test         # 7 suites via node:test

源码布局：server/ 存放 TypeScript 源码（编译到 lib/），client/index.js 是浏览器入口（由 scripts/build-client.mjs 打包），scripts/ 存放构建工具。lib/ 是构建输出，不纳入 git 跟踪。

要求与范围

- 构建仅需公共 npm —— @deepseek-ai/ 宿主包已发布在那里。运行该插件需要 DSH 宿主：即加载 cordis 插件的 dsh CLI / web 进程。
- 嵌入端点是可选的；没有它时，工作区在保留图结构的同时以仅词法模式运行。

许可证

MIT

其他
范围： 本项目被设计为 会话记忆（Session Memory），主要用于在 Agent 会话之间保存和恢复项目进度、任务状态、关键决策、先前的尝试以及上下文连续性。它并非旨在成为大规模知识库或通用长期知识存储系统。

该设计面向通常在几次到十几次会话内完成的任务，以及文本生产工作流。主要目标是帮助 Agent 在新会话中快速恢复任务停在哪里、尝试过什么、为何做出某些决策，以及接下来应该做什么。

- 本项目可能仍存在一些尚未发现的 bug。感谢您的理解。

中文说明

English · 中文说明

面向 DSH(cordis)架构的工作区级持久记忆插件。插件在每个会话工作区下维护一个 project_memory/ 目录,并向模型上下文注入有界节点索引,使 agent 按"覆盖命题"导航记忆,而不是扫描无类型目录。

flowchart LR
subgraph W ["写入路径 — 会话结束"]
EV["会话事件"] --> EX["提取 + 去重"] --> CL["LLM 分类"] --> RD["审阅文档"] --> PV["浏览器面板预览 diff → 确认提交"]
end
PV --> FN
subgraph S ["project_memory/ 每工作区"]
FN["节点 P 漏斗core.md · regular.md · log"]
VS["向量分片(余弦)"]
GR["graph.jsonnodeEdges + entryLinks"]
FN --> VS
FN --> GR
end
subgraph R ["读取路径 — 下次会话"]
Q["查询"] --> HR["混合检索余弦 + 词法 → RRF"] --> CTX["有界节点索引→ 模型上下文"]
end
VS --> HR
GR --> HR

记忆模型(v3)

从对话中提取的原子命题按两个语义层分类:

1. 第一层 — 语义分类:命题被归入覆盖命题(大命题,持久化为节点 p)。
2. 第二层 — 向量网络:每个节点 P 与每个漏斗条目都被向量化,层间相关性以向量空间距离度量。细粒度条目可挂接多个上层节点(多对多 entryLinks),节点之间连接各自的 k 近邻(nodeEdges)。

节点网络之下是三层漏斗(每节点):core.md(基础事实)、regular.md(常规记忆)、log/.md(过程日志,原始内容,不做向量化)。二者共同构成层级向量网络。检索是混合式的:向量余弦 + 词法打分经 RRF 融合,因此未配置 embedding 的工作区会降级为词面召回,而不丢失图结构。

存储/计算层没有"维度"概念;旧的维度路径仅以 legacyLabel 的形式保留——GUI 用于分组导航的显示标签。

存储布局

project_memory/
.registry.json                     # 工作区注册表
_backup/v2/-/              # 迁移前快照(每个 id 保留 2 份)
_system/                           # 迁移锁
/
manifest.json                    # schema:3 — nodes[]、graphVersion、migratedFrom?
doctrine.md
nodes//funnel/{core.md, regular.md, log/.md}
vec/index.json + vec/.json   # 向量分片(JSON,暴力余弦)
graph.json                       # nodeEdges + entryLinks(多对多)

由早期版本创建的工作区(无 schema、带 dimensions 树的 manifest)会在加载后的首次 ensureWorkspace 时自动迁移:确定性节点 id、条目 id 经同一 sha1 方案保留、dimTreeVersion 顺延为 graphVersion、任何写入前先整体目录备份、经 _system/migrate-.lock 支持断点恢复。

嵌入配置

通过插件根目录的 api.json 配置 OpenAI 兼容端点(也支持 /project_memory/api.json 覆盖):

{ "embedding": { "baseUrl": "https://…/v1", "apiKey": "sk-…", "model": "text-embedding-3-small", "dimensions": 1536 } }

缺失或无效配置 → 纯词法模式(needsReindex 标记相应子项目,等待后续 memoryReindex)。

安装

本 bundle 有意安装在树外(out of tree):

dsh plugin --profile web add

服务端改动需重启 dsh web 进程。浏览器半边以 lib/client.js 提供。

客户端界面:
- MemoryButton(conversation.input.memory)——打开当前会话的记忆预览/确认面板。
- MemoryPreviewPanel(conversation.input.overlay)——读取已绑定子项目的文档，预览更新 diff 并提交（previewUpdate / commitUpdate）；绑定/解绑会话。
- MemoryTreeSection(sidebar.workspaces.memoryTree)——把工作区记忆分组内联渲染进侧栏树。

Remote API

workspaceMemory Remote 命名空间暴露 18 个方法：listSubprojects / listSubprojectsByPath、bindSession、classify / commitClassify、previewUpdate / commitUpdate、renameSubproject / renameSubprojectByPath、deleteByPath（附 getDeleteConfirmationTokenByPath）、reconcileAccountedSessions、listSessionIdsByPath、governance、search、seed、memoryReindex / memoryStatus。

开发

npm install      # 安装锁定的 devDependencies —— @deepseek-ai/ 来自公共 npm，以及 esbuild、typescript
npm run build    # server/ TS 编译 -> lib/；client 经 esbuild 打包 -> lib/client.js
npm test         # 7 个测试套件，由 node:test 运行

源码布局：server/ 为 TypeScript 源码（编译到 lib/），client/index.js 为浏览器入口（由 scripts/build-client.mjs 打包），scripts/ 为构建工具。lib/ 是构建产物，不入 git。

环境与范围

- 构建只需公共 npm——@deepseek-ai/* 宿主包发布在那里。运行插件需要 DSH 宿主：加载 cordis 插件的 dsh CLI / web 进程。
- embedding 端点是可选的；未配置时工作区以纯词法模式运行，同时保留图结构。

许可证

MIT
其他事项

定位说明： 本项目定位为 Session Memory（会话记忆），主要用于跨多个 Agent session 保存和恢复项目进度、任务状态、关键决策、尝试结果及上下文连续性。它并非面向超大规模数据集的知识库（Knowledge Base）或通用长期知识存储系统。

设计目标主要是支持通常在数个到十几个 session 内完成的任务，以及文字生产等场景；重点是帮助 Agent 在新的 session 中快速恢复“之前做到哪里、做过什么、为什么这样做以及下一步是什么”。

- 该项目可能包含未发现的小 bug，请见谅