Luisarg03/dsh-memory-vault

dsh-memory-vault

DeepSeek Harness
Cordis 4.0.1
pnpm 10.15.0
Node.js ≥22.18
TypeScript 7.0
Python ≥3.11
uv 0.11
MCP ≥1.2
SQLite FTS5
Vitest 5.0
tsdown 0.23
oxlint 1.82

为 DeepSeek Harness（DSH）提供持久化 OKF 记忆：
一个 Python MCP 服务器（SQLite FTS5 + Markdown）、两个 Cordis 插件（memory-mcp、memory-auto）
将其作为工具和命令暴露给 agent，以及一个带有模板和类型注册表的 vault 起始包。

记忆循环

每个会话一圈：agent 回忆 vault 已知的内容，工作，检查点捕获发生的事，摘要提交持久状态回去——这样
下一圈就从更丰富的记录开始。Markdown 始终是事实来源；SQLite FTS5 是由它派生的索引。

安装后你会得到什么

| | |
|---|---|
| 10 个 MCP 工具 | search_memory · store_decision · store_fact · store_learning · store_convention · store_profile · store_source · export_memories · get_profile · ping |
| 3 个命令 | /brain 和 /checkpoint 随 memory-mcp 提供；/checkpoint-auto 随 memory-auto 提供 |
| 自动捕获 | 在 git 提交、压缩和空闲时生成摘要——通过 harness 自身的 LLM 服务在进程内提取 |
| 一个 vault | 带有按类型模板、类型注册表和标签词汇表的 OKF 包；运行时数据在首次使用时创建 |

安装

1. 安装两个插件（npm，预构建——无需构建审批，无需克隆仓库）
dsh plugin --profile web add @luisarg/memory-mcp@0.1.5 @luisarg/memory-auto@0.1.5

2. 启动——首次启动会在 $DSH_HOME 下自动安装 vault 服务器 + 起始包
（~/.dsh/memory-vault-server 和 ~/.dsh/memory-vault）
dsh web

验证
dsh --profile web --dump-config | grep -A8 memory

版本被固定，因为 pnpm 默认的 minimumReleaseAge（3 天）否则会解析到更旧的版本。升级永远不会覆盖现有的 vault 文件：它们只复制缺失的内容。

开发者（使用本地检出而非 npm）：

dsh plugin --profile demo add ./packages/memory-mcp ./packages/memory-auto
离线：pnpm --filter @luisarg/memory-mcp pack，然后添加 .tgz 文件。从 GitHub 安装仓库根目录不受支持（根目录没有 dsh.bundle；pnpm 缺少 git 子目录规格）——请使用 npm 或 tarball。

发布由 CI 完成：推送 v 标签会构建、测试、验证 tarball，并将两个包发布到 npm，附带
来源证明，通过 GitHub OIDC 进行身份验证——此仓库或维护者的机器上都不存在发布令牌。制品发布前会运行什么，见 docs/releasing.md。

组件

| 组件 | 作用 | 包 |
|---|---|---|
| memory-mcp | MCP stdio 客户端：启动 vault 服务器，暴露其工具以及 brain / checkpoint 技能 | @luisarg/memory-mcp |
| memory-auto | 会话钩子 + 进程内摘要，以及 checkpoint-auto 技能 | @luisarg/memory-auto |
| memory-vault-server/ | Python MCP 服务器：SQLite FTS5 + Markdown OKF | — |
| memory-vault/ | Vault 起始模板：模板 + 类型注册表 + 标签词汇表 | — |
| scripts/digest_session.py | 可选的独立摘要 CLI（插件不使用） | — |

技术栈架构

使用它

在聊天中提问

智能体通过 MCP 工具（mcp__memory__——服务器名为 memory）访问 vault；
你不需要自己调用它们：

| 你说 | 智能体使用的工具 |
|---|---|
| “在你的记忆中搜索 ” | search_memory |
| “记住这个：” | store_decision / store_fact / … |
| “导出你关于  所知道的一切” | export_memories |
| “总结我的个人资料” | get_profile |

内置技能

两个插件还附带驱动这些工具的命令，因此全新安装即可获得它们，无需将任何内容复制到技能目录：

| 命令 | 随附于 | 作用 |
|---|---|---|
| /brain | memory-mcp | 读取 vault：主题搜索、按项目回忆、个人资料、完整导出 |
| /checkpoint | memory-mcp | 将会话捕获为 decision/fact/learning/convention 条目，然后提交 vault |
| /checkpoint-auto | memory-auto | 解释并引导自动捕获：触发器、[memory-checkpoint] 标记、各项调节参数 |

它们注册在 DSH 的内置等级，这是本地发现表中最弱的一级，因此 ~/.agents/skills、~/.dsh/skills 或项目的 .agents/skills 中同名的技能仍然优先——
这些是默认值，而非强制接管。要覆盖其中一个，请将其 SKILL.md 从
packages//skills/ 复制到你的技能根目录并编辑：该文件是其自身名称、描述和使用指南的唯一来源，因此在两处都能正常工作。

自动捕获

memory-auto 在 git 提交、压缩和空闲会话时触发摘要。摘要会以
[memory-auto] … 行的形式记录在 harness 控制台中，条目会归入
/projects///（Markdown）加上 SQLite FTS5 索引。提取过程
在进程内通过 ctx.llm 运行——即 DSH 已配置好的凭据——因此没有
外部 CLI，也没有存储的密钥。在插件配置中设置 enabled: false 即可将其关闭。

配置

DSH 不会 chdir：启动目录无关紧要，路径都是绝对路径。它们按以下
顺序解析：

1. 环境变量（覆盖一切）：DSH_MEMORY_PATH、DSH_MEMORY_SERVER_DIR。
2. harness 主目录下的默认值：$DSH_HOME/memory-vault 和 $DSH_HOME/memory-vault-server
（当 $DSH_HOME 未设置时为 ~/.dsh）。
3. Profile 补丁（cordis.patch.yml）或带显式值的 --patch 覆盖层。

| 环境变量 | 用途 | 默认值 |
|---|---|---|
| DSH_MEMORY_PATH | vault 目录（服务器将其作为 MEMORY_PATH 接收） | $DSH_HOME/memory-vault |
| DSH_MEMORY_SERVER_DIR | 包含 server.py 的目录 | $DSH_HOME/memory-vault-server |

插件级配置（补丁层）：provider（deepseek-official）、model
（deepseek-v4-flash）、maxTokens、minTranscriptChars、enabled。

vault 起始包是一个 OKF bundle：templates/（每种条目类型一个）、type-registry.yaml
（类型的唯一事实来源）和 tag-vocabulary.json（标签规范化）。运行时数据
（projects/、raw/、logs/、memory.db）由服务器在首次使用时创建，并排除
在 git 之外。

服务器的运行时：推荐 PATH 上有 uv，但并非必需。捆绑的
launcher.mjs 在 uv 存在时用 uv run 运行服务器，否则回退到
pip 管理的 venv（python3 -m venv + pip install -r requirements.txt；首次启动需要
网络）。两个包都是自包含的：它们附带 Python 服务器和 vault 起始包。

操作

composed config shows both bundles with the resolved paths
dsh --profile web --dump-config | grep -A8 memory

what the vault holds (default vault: ~/.dsh/memory-vault)
ls ~/.dsh/memory-vault/projects/               # per-project OKF entries
grep -i "digest" ~/.dsh/memory-vault/log.md    # digest markers

talk to the vault MCP server directly (standalone smoke test)
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"cli","version":"0"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ping","arguments":{}}}' \
| MEMORY_PATH=$HOME/.dsh/memory-vault uv run --directory memory-vault-server python server.py

a second harness instance on another port (testing without touching your main session)
pnpm dsh web --port 3090

pnpm 故障排除

- unable to open database file → pnpm store 不可写（沙箱环境）。在每次
pnpm install 以及
dsh plugin --profile X --store-dir ./.pnpm-store add ... 时使用
--store-dir ./.pnpm-store。
- 从 GitHub 安装时出现 dsh: pnpm failed → 仅适用于带有 prepare 脚本的包；将打印出的 key 复制到配置文件的 pnpm-workspace.yaml（allowBuilds）中。此 monorepo 的子包完全无法通过 github:... 安装——请使用 npm 或 tarball。

第二个 MCP 客户端：opencode

该 vault 是一个普通的 stdio MCP 服务器，因此任何 MCP 客户端都可以使用同一个服务器和同一个 vault（共享 vault 布局参见 docs/central-zone.md）。对于 opencode，~/.config/opencode/opencode.json：

"mcp": {
"memory-server": {
"type": "local",
"command": ["uv", "run", "--directory", "/memory-vault-server", "python", "server.py"],
"enabled": true,
"environment": { "MEMORY_PATH": "" }
}
}

该 key 必须是 environment —— env 会被静默忽略，服务器会回退到默认 vault。插件技能是 DSH 的一项功能，不会通过 MCP 传递：想要相同命令的 opencode 用户需将 SKILL.md 文件复制到 opencode 读取的目录中（~/.config/opencode/skills//SKILL.md），并将工具前缀从 mcp__memory__ 重命名为 memory-server_。

开发

pnpm install
pnpm -r build

run the harness against the checkout, with an overlay (paths relative to the repo cwd)
dsh web --patch ./examples/dev-memory.cordis.yml

packages/memory-mcp/          # cordis bundle: MCP stdio client (+ brain, checkpoint skills)
packages/memory-auto/         # cordis bundle: automatic session digest (+ checkpoint-auto skill)
memory-vault-server/          # Python MCP server (SQLite + Markdown OKF)
memory-vault/                 # vault starter (templates + type registry)
scripts/digest_session.py     # optional standalone digest CLI (not used by the plugins)
examples/dev-memory.cordis.yml       # memory-mcp
examples/dev-memory-auto.cordis.yml  # memory-mcp + memory-auto

pnpm -r build 会运行每个包的构建；pnpm bundle 会将服务器和 vault starter 复制到各个包中，因此发布 tarball 是自包含的。CI 在每次 push 时都会运行 lint、build 和测试套件（pnpm lint && pnpm -r build && pnpm -r test）。

文档

- docs/ —— 架构、图表、中央区域、发布
- 发布与版本标签 —— 每个 v* 标签对应哪个提交
- 你的第一个插件
- 构建一个工具
- 插件配置
- 打包与安装