dsh-memorix-panel

在 DSH Web GUI 里查看与管理本地 Memorix 记忆库。

版本 0.1.0 · 许可证 MIT · 作者 @biubiu23333333 · 仓库 https://github.com/biubiu23333333/dsh-memorix-panel

本插件是一个 DSH profile 级插件(同时带 host 半与 client 半),常驻运行,可以被任何 DSH 部署安装使用。

项目简介

Memorix 是一个本地优先的 AI 记忆控制平面:它由 CLI(memorix)、MCP server 与本地 SQLite 数据库组成,把项目记忆保存在本机,供各种 AI 编码代理共享检索。

dsh-memorix-panel 把这份记忆库搬进 DSH Web GUI:在会话界面里直接浏览记忆库状态、按项目和类型检索记忆、查看单条记忆的完整正文与元信息,并在需要时修改记忆状态或新建记忆。读取是只读直连 SQLite;所有写入一律交给官方 memorix CLI 执行,以保证 Memorix 自己的检索索引保持同步。

功能一览

功能	说明
库状态	显示记忆库路径、文件大小、WAL 大小、最后更新时间、memorix CLI 版本
总量统计	记忆 / 项目 / 活跃 / 归档 / 长期记忆 / 迷你技能 / 会话 / 证据卡 / 知识页
搜索	按标题、实体(entityName)、类型检索记忆
筛选	按记忆类型与状态(active / resolved / archived)筛选
项目列表	手风琴式展开项目,查看该项目下的记忆
记忆详情	元信息 + 正文 + 要点(facts)+ 概念(concepts)+ 涉及文件 + 关联提交 + 关联实体
改状态	详情页可直接改记忆状态(带二次确认)
新建记忆	面板内新建一条记忆(带二次确认)
长期记忆视图	独立分区浏览耐用记忆层:状态(已批准 / 已确认 / 候选 / 已归档 / 已被取代)、作用域(用户级 / 项目级 / 团队级)、可携带性、类型(事实 / 流程 / 事件);按状态与作用域筛选;点开可看内容、要点、标签、适用性、证据链与审计事件(created → qualified → approved)。面板会提示「候选与已确认都不会进入 Workset,必须 approve」
长期记忆管理	详情页可直接驱动 Memorix 自己的状态机:候选 →「确认 (qualify)」→ 已确认 →「批准 (approve)」→ 已批准,以及「归档」;每次操作都要填理由(写入审计事件)并二次确认,状态机规则与报错由官方 CLI 给出
一键复制项目名	项目行上的「复制」按钮一键复制 projectId(点完变 ✓,且不会触发项目行的展开/折叠);记忆详情的「项目」行与长期记忆详情的「起源项目」行旁同样有复制按钮。复制失败时回退到 execCommand 方式

界面入口

1. 会话标题栏入口(默认位置):入口就挂在会话标题栏里「Session 日志」按钮的右边(与它同一行、紧邻其后)。
2. 右侧边缘停靠(无会话时的兜底):没有活动会话(或找不到「Session 日志」按钮)时,入口自动停靠到浏览器窗口右侧边缘、垂直居中处;一旦会话出现,会自动回到标题栏。会话切换/页面重渲染后也会自动重新落位。
3. 右侧工作台 tab(彩蛋):若部署里安装了 dsh-better-sidebar 且与本插件处于同一个客户端组装域,工作台的「+ / 空面板卡片」里还会多出一项「Memorix 记忆」。

无论停在哪个位置,面板都以**浏览器顶层浮层(top-layer)**抽屉的形式从右侧滑出。

⚠️ 为什么是 body 级挂载 + DOM 落位,而不是槽位:DSH 的浏览器侧由多个客户端组装域组成,槽位系统(slots)与 dsh-better-sidebar 的 tab 注册表都按域隔离;插件实例可能被挂进一个不被可见 UI 读取的域,于是出现"注册成功但界面上看不到"的静默失败(实测踩过)。现在入口先挂到 document.body,再按 DOM 查找「Session 日志」按钮把自己插进它右侧——不依赖任何域,也不需要任何注入声明。

前置条件

依赖	要求	说明
DSH (DeepSeek Harness)	已安装并可用 Web GUI	插件以 profile 级 bundle 形式挂载,默认 profile 名为 web
Node.js	≥ 22.18.0	这是 Memorix 自身的版本要求;本插件的 node:sqlite 读取路径需要 Node ≥ 22.5,已被覆盖
Git	已安装	Memorix 的项目身份来自真实 Git 根
Memorix CLI	已安装(见第一步)	提供 memorix 命令
dsh-better-sidebar	可选	只在需要「Memorix 记忆」侧边 tab 时才需要
python3	可选回退	当 node:sqlite 不可用时(如 Node < 22.5),插件自动回退到 python3 标准库 sqlite3 读库

插件本身零运行时依赖(除 DSH 自身与 react 外,不依赖任何第三方 npm 包)。

第一步:安装 Memorix

依据:Memorix 官方 README 的 #install 章节,以及官方 docs/SETUP.md。

1. 全局安装 CLI

官方推荐方式是 npm 全局安装:

npm install -g memorix

官方文档明确建议持久化配置里不要用 npx(docs/SETUP.md 原文:"Avoid npx in persistent MCP configs. Use the globally installed memorix binary so startup is predictable.")。如果你只是想临时试一下,可以用 npx memorix@latest --version,但正式接入请使用全局二进制。

2. 验证安装

memorix --version
which memorix

预期输出:版本号一行(本机验证为 1.9.1),以及二进制路径(本机为 /usr/bin/memorix)。版本号比 1.9.1 更高是正常的。

3.(可选)生成全局配置

memorix init --global

memorix init 是可选步骤,它会创建或更新 TOML 配置:~/.memorix/config.toml(全局默认值)与 <git-root>/memorix.toml(单项目可选覆盖)。

4. 接入 DSH

memorix setup --agent dsh --global

对 DeepSeek Harness 而言,这条命令会:往 $DSH_HOME/cordis.patch.yml(默认 ~/.dsh/cordis.patch.yml)写入一行 Memorix 的 @deepseek-ai/dsh-mcp-client 行;往 harness 的 AGENTS.md(~/.dsh/AGENTS.md)追加使用指引;并在 $DSH_HOME/skills(默认 ~/.dsh/skills)安装官方 skills。接入完成后 MCP 工具以 mcp__memorix__* 出现。

校验与修复:

memorix doctor agents --agent dsh    # 检查 MCP 配置与指引是否最新
memorix repair agents --agent dsh    # 需要时修复 Memorix 自己写入的条目

5. 让 Memorix 认识你的项目

Memorix 的项目身份来自真实 Git 根。让某个项目被注册,最简单的方式就是在该项目目录里跑一次命令:

cd /path/to/your/project
memorix status              # 查看当前项目身份(Name / ID / Root / Observations)

# 想确认项目上下文是否可检索,可以再跑一次:
memorix context "正在做的事" --brief-json

这一步的结果会体现在下面这两个文件里,本插件正是读取它们来还原「项目 ↔ 记忆」的映射:

路径	内容
~/.memorix/data/.project-aliases.json	项目别名分组:groups[].canonical / aliases / rootPaths
~/.memorix/last-project-root	最近一次使用的项目根路径

未覆盖的场景请参见 Memorix 官方 README 与 docs/SETUP.md(npm 包名 memorix,仓库 https://github.com/AVIDS2/memorix)。

第二步:安装本插件

三种安装方式任选其一。

# 方式一:从 npm 安装
dsh plugin --profile web add dsh-memorix-panel

# 方式二:从 GitHub 安装
dsh plugin --profile web add github:biubiu23333333/dsh-memorix-panel

# 方式三:本地开发安装
cd ~/.dsh/profiles/web && dsh plugin --profile web add /绝对路径/dsh-memorix-panel

安装完成后:硬刷新浏览器(Windows/Linux Ctrl+Shift+R,macOS Cmd+Shift+R),让 client 半生效;如果 host 半有更新,还需要重启 dsh-web。

第三步:验证

1. 确认 Memorix 侧正常

memorix --version
ls -la ~/.memorix/data/memorix.db

应当能看到版本号,以及记忆库文件(可能还会看到同目录下的 memorix.db-wal、memorix.db-shm)。

2. 确认插件侧生效

硬刷新页面后,打开任意一个会话:

• 会话标题栏里,「Session 日志」按钮的右边应出现入口「● 记忆 N」;
• 点它 → 右侧滑出顶层浮层抽屉(面板顶部显示记忆库路径与大小);
• 没有打开的会话时,入口会停靠在窗口右侧边缘垂直居中处(兜底位置);
• 若你装了 dsh-better-sidebar 且与插件同域,工作台「+ / 空面板卡片」里还会多一项「Memorix 记忆」(可选)。

统计区应给出记忆/项目/活跃/归档等数量。如果数量为 0,先按第一步第 5 小节在一个真实项目里跑一次 memorix status。

也可以用命令行直接验证 host 半(需把 <TOKEN> 换成启动日志里打印的令牌,loopback 访问时通常直接可通):

curl -s -X POST http://127.0.0.1:3080/memorix-panel/api \
  -H 'content-type: application/json' -d '{"action":"overview"}' | head -c 400

返回形如 {"ok":true,"backend":"node:sqlite",...} 即为正常。

使用说明

界面结构

区域	内容
库状态	记忆库路径、库文件大小、WAL 大小、最后更新时间、memorix CLI 版本
总计	记忆 / 项目 / 活跃 / 归档 / 长期记忆 / 迷你技能 / 会话 / 证据卡 / 知识页
搜索与筛选	搜索框(按标题、实体、类型)+ 记忆类型与状态筛选器
项目列表	手风琴分组,展开后列出该项目下的记忆
详情视图	元信息、正文、要点、概念、涉及文件、关联提交、关联实体;底部是改状态与操作按钮

数据存储(只读读取)

路径	说明
~/.memorix/data/memorix.db	SQLite 记忆库,单库多项目,以 projectId 列区分项目
~/.memorix/data/.project-aliases.json	项目映射:groups[].canonical / aliases / rootPaths
~/.memorix/last-project-root	最近使用的项目根

observations 表包含 id / type / title / narrative / facts / concepts / filesModified / status / createdAt / updatedAt / entityName / valueCategory / topicKey / source / visibility 等字段。

读取实现

按顺序尝试,任一成功即停止:

按顺序尝试,任一成功即停止:Node 内置 node:sqlite(需 Node ≥ 22.5)→ python3 标准库 sqlite3 模块 → 系统 sqlite3 CLI。

写入实现

写入一律通过官方 CLI,不做裸 SQL 写入(这样 Memorix 自己的检索索引才会同步)。

# 改状态
memorix memory resolve --id <n> --status active|resolved|archived --json --cwd <项目根>

# 新建记忆
memorix memory store --text <正文> --title <标题> --type <类型> \
  [--entity ...] [--facts a,b] [--concepts x,y] [--files p1,p2] [--topicKey ...] \
  --json --cwd <项目根>

记忆状态语义

状态	含义
active	活跃。默认检索可见
resolved	已解决
archived	已归档。默认检索不返回,但数据不会删除,可随时改回

面板里「改状态」和「新建记忆」都带二次确认,避免误操作。

配置

所有配置项都写在 profile 的 cordis.patch.yml 里该插件行的 config 中,全部可选。

配置项	默认值	说明
bin	memorix	Memorix CLI 可执行文件名或绝对路径
dbPath	自动探测 ~/.memorix/data/memorix.db	记忆库 SQLite 文件路径
cliTimeoutMs	25000	每次调用 CLI 的超时时间(毫秒)
allowWrite	true	是否允许「改状态」
allowStore	true	是否允许「新建记忆」

示例(cordis.patch.yml):

- insert:
    - id: memorix-panel
      name: dsh-memorix-panel
      config:
        bin: memorix
        cliTimeoutMs: 25000
        allowWrite: true
        allowStore: true

如果只想开放只读浏览,把 allowWrite 与 allowStore 都设为 false 即可。

开发与目录结构

插件是 DSH 常见的 host 半 + client 半结构:host 半跑在 DSH 的 Node 进程里,负责读库、探测路径、调用 memorix CLI;client 半跑在浏览器里,负责按钮入口、浮层抽屉与右侧工作台 tab。

目录布局(遵循 DSH 插件约定):

dsh-memorix-panel/
├── lib/
│   ├── index.js         # host 半:读 SQLite、探测项目映射、调用 memorix CLI
│   └── client.js        # client 半:标题栏入口按钮 / 浮层抽屉 / 侧边栏 tab
├── cordis.patch.yml     # bundle patch:把插件行挂到 profile 上
├── package.json         # dsh.bundle.patch + dsh.client.platform = web
└── LICENSE              # MIT

本地迭代:

# 以本地路径安装到 web profile
cd ~/.dsh/profiles/web && dsh plugin --profile web add /绝对路径/dsh-memorix-panel
# 只改了 client 半 → 硬刷新浏览器即可;改了 host 半 → 重启 dsh-web

常见问题

1. 看不到「● 记忆 N」入口

1. 硬刷新浏览器(Ctrl/Cmd+Shift+R)——client 半是独立 bundle,不刷新不会更新。
2. 确认你装的 profile 正确:本 README 以 web 为例,若你的 Web profile 名字不同,把命令里的 --profile web 换成实际名字。
3. 确认插件确实已安装:检查该 profile 的 package.json(依赖列表与 dsh.profile.bundles 数组里是否有 dsh-memorix-panel),或查看 profile 的 node_modules。
4. 如果 host 半刚更新过,重启 dsh-web。

2. 写入失败:EACCES: permission denied

这是沙箱 / 权限边界问题,不是插件 bug。Memorix 的库在 ~/.memorix 下,如果 DSH 进程的工作目录(或沙箱的 workspaceRoot)不包含 ~/.memorix,写入就会被拒绝。处理方式二选一:

• 让 dsh web 以 $HOME 为工作目录运行,使 ~/.memorix 落在可写范围内;
• 或使用更高的权限模式(如 full-access)运行。

3. 提示 Node 版本相关错误

插件的首选读取路径使用 Node 内置 node:sqlite,需要 Node ≥ 22.5。升级 Node 到 22.5 以上(建议直接满足 Memorix 要求的 ≥ 22.18.0);或安装 python3(标准库自带 sqlite3),让插件走回退路径。

4. 报「未找到项目根」

1. 检查 ~/.memorix/data/.project-aliases.json 是否有对应的 groups[] 条目(canonical / aliases / rootPaths);
2. 检查 ~/.memorix/last-project-root 指向哪里;
3. 在目标项目里跑一次 memorix(在该项目目录内,或带 --cwd <项目根>),让 Memorix 注册这个项目,然后回到面板重试。

5. 改了状态,但检索结果里还是老样子 / 或者仍然搜不到

Memorix 的 MCP 常驻进程持有内存索引,状态变更后可能滞后一拍。面板是直接读库的,所以面板始终显示最新状态;等常驻进程刷新后再检索即可。

6. 中文关键词检索效果弱

Memorix 默认使用 FTS/BM25 全文检索,对中文分词较弱。可考虑按官方文档配置 embedding 来提升中文召回质量(参见 Memorix 官方 README 与 docs/SETUP.md)。

安全与隐私

• 插件只读取本机 Memorix 记忆库;所有改动都交给官方 memorix CLI 执行,不做裸 SQL 写入。
• 所有 HTTP 路由都要求同源,且只接受 loopback 或部署的受信主机。
• 跨站请求被拒绝:携带 sec-fetch-site: cross-site 的请求直接返回 403。
• 无遥测、无外部网络请求。

License

MIT © biubiu23333333

---

Quick Start (English)

# 1. Install the Memorix CLI (requires Node >= 22.18.0 and Git)
npm install -g memorix
memorix --version              # expect e.g. 1.9.1
memorix setup --agent dsh --global   # wire Memorix into DSH

# 2. Register a project (project identity comes from the real Git root)
cd /path/to/your/project && memorix status

# 3. Install this panel
dsh plugin --profile web add dsh-memorix-panel
#    then hard-refresh the browser (Ctrl/Cmd+Shift+R)

Look for the native 「● 记忆 N」 button at the top-right of the session header (or the「Memorix 记忆」tab if dsh-better-sidebar is installed). Reads are direct and read-only against ~/.memorix/data/memorix.db; every write goes through the official memorix CLI. MIT licensed.