crowdmemory-runtime

Crowd Memory 本机记忆 Runtime 的 npm 发布包。包里带 Runtime（Python）、它依赖的契约包和两个默认模板（session-default、workflow-default）的 wheel，外加一个命令 crowdmemory-runtime：校验这些 wheel，离线装进独立 venv，生成 host config 和用户服务文件。不联网下载任何东西，也不依赖其他 npm 包。

DSH 适配器是另一个包 @fuxi-ailabs/crowdmemory-dsh-adapter。适配器在 DSH 进程里运行，把会话事件交给本包装好的 Runtime，两个包都从 npm 获取。

需要什么

| 依赖 | 版本 | |---|---| | Node.js | ≥ 22.18（带 npm） | | Python | ≥ 3.10，带 venv 模块（Debian/Ubuntu 要装 python3-venv）；不需要任何第三方 Python 包 | | 系统 | macOS 或 Linux（Runtime 走 Unix 套接字） |

Runtime 与 DSH 必须以同一个用户运行：令牌文件是 0600，只有这个用户能读。

安装

npm install --save-exact @fuxi-ailabs/[email protected]
npx --no-install crowdmemory-runtime install --prefix "$PWD/.runtime/crowdmemory"
npx --no-install crowdmemory-runtime start --prefix "$PWD/.runtime/crowdmemory"

install 依次做这些事：按 runtime-manifest.json 校验每个 wheel 的 SHA-256，对不上就拒绝安装；找一个 Python ≥ 3.10；在 <prefix>/releases/<id>/venv 建 venv 并离线装入 wheel；首次安装时生成 <prefix>/host-config.json。生成的 host config 打开了 agent_ingress，套接字放在 <prefix>/state/rt.sock。上例的 prefix 是项目下的 .runtime/crowdmemory；不传 --prefix 时才使用 ~/.crowdmemory。最后打印下一步要做的事。

| 选项 | 作用 | |---|---| | --prefix <目录> | 安装目录，默认 ~/.crowdmemory（也可用环境变量 CROWDMEMORY_RUNTIME_PREFIX）。所有命令都接受这个选项 | | --python <可执行文件> | 指定建 venv 的 Python。默认沿用上次安装用的，没有就找 PATH 上的 python3、python3.1x | | --service none\|launchd\|systemd | 生成用户服务文件到 <prefix>/service/，默认 none。只生成不加载，加载命令会打印出来 | | --profile session-default\|workflow-default | 首次生成 host config 时的默认模板。按 DSH workflow 记（L2）时选 workflow-default | | --socket <路径> | 首次生成 host config 时用的套接字路径。macOS 上不能超过 103 字节，prefix 很长时要指定 | | --json | 输出机器可读的结果 |

host config 只在首次安装时生成，之后归你所有，install 不会再覆盖它。要改模板或套接字，直接编辑这个文件，然后重启 Runtime。字段说明见 Crowd Memory 文档 configuration.md。

接上 DSH

export CROWDMEMORY_ENDPOINT_FILE="$PWD/.runtime/crowdmemory/state/endpoint.json"
dsh plugin --profile <profile> add @fuxi-ailabs/[email protected]
npx --no-install crowdmemory-runtime status --prefix "$PWD/.runtime/crowdmemory"

适配器不设环境变量时就在 ~/.crowdmemory/state/endpoint.json 找 Runtime，也就是默认安装的位置，桌面版从 Dock 启动也一样。用了 --prefix 时，要 export CROWDMEMORY_ENDPOINT_FILE=<prefix>/state/endpoint.json。

endpoint.json 由 Runtime 在套接字就绪后写出，退出时删除。适配器每次请求都会重读这个文件和令牌，所以 Runtime 重启或升级后不用重启 DSH。装在别处又要给 DSH 桌面版用时（它从 Dock 启动读不到 shell 的环境变量），处理办法见适配器 README 的「配置」一节。

命令

| 命令 | 说明 | |---|---| | crowdmemory-runtime install | 安装、升级或回滚（见下一节） | | crowdmemory-runtime start | 前台运行 crowdmemory-server --host-config <prefix>/host-config.json serve；已在运行时拒绝启动第二个 | | crowdmemory-runtime status [--json] | 用 endpoint 文件里的令牌请求 GET /v1/agent-ingress/status，打印摘要，加 --json 打印原始结果。令牌只发给 Runtime，不会打印出来 | | crowdmemory-runtime version [--json] | 本包版本、组件与模板 revision，以及 prefix 下当前装的是哪个 release | | crowdmemory-runtime prune [--keep N] [--dry-run] [--json] | 删除旧 release，释放磁盘。默认保留 2 个：当前的，和回滚历史里的上一个；其余的删掉，没装完的残留也删。--keep N 保留回滚历史里最近的 N 个（至少 1）。current 指向的 release 总是保留，state/、host-config.json、service/ 不动。--dry-run 只列出会删什么、能腾出多少空间 | | crowdmemory-runtime uninstall [--keep-state] | 删除 releases、venv、服务文件和安装记录。加 --keep-state 时保留 state/（本机记忆库）与 host-config.json。Runtime 还在运行时拒绝卸载 |

退出码：0 成功；1 Runtime 没在运行或没安装；2 用法或环境错误，例如找不到合适的 Python、包校验失败。

升级与回滚

npm install --save-exact @fuxi-ailabs/crowdmemory-runtime@<新版本>
npx --no-install crowdmemory-runtime install --prefix "$PWD/.runtime/crowdmemory"

每个包版本对应 <prefix>/releases/ 下的一个 release，current 符号链接原子切换到新 release。state/（本机记忆库、令牌、endpoint）和 host-config.json 跨版本保留。正在运行的 Runtime 仍跑旧版本，要重启才用上新版本：install 会打印重启命令；前台运行的先 Ctrl-C，再 start。

回滚用同样的两步，装回旧版本再执行 install。旧 release 还在磁盘上时直接切回，不会重建；已被 prune 删掉时，install 用旧版本包里的 wheel 重建它。

每个 release 都带一份完整的 venv，旧 release 不会自动删除。releases/ 下多于 2 个 release 时，install 会提示能删几个、能腾出多少空间，删不删由你决定：

crowdmemory-runtime prune --dry-run   # 先看会删什么
crowdmemory-runtime prune             # 保留当前与上一个
crowdmemory-runtime prune --keep 3    # 多留一个

prune 只删 releases/ 下的旧 release。删掉之后照样能回滚，只是 install 要多花一次建 venv 的时间重建它。Runtime 运行中也可以 prune，当前 release 不会被删。只有一种情况要先重启：连装两个新版本都没重启，运行中的 Runtime 还在用更早的 release，它不在默认保留范围内。

卸载

crowdmemory-runtime uninstall            # 连同 state/ 与 host-config.json 一起删
crowdmemory-runtime uninstall --keep-state
npm uninstall @fuxi-ailabs/crowdmemory-runtime

如果加载过服务文件，要先停掉服务（launchctl bootout gui/$(id -u)/com.crowdmemory.runtime 或 systemctl --user stop crowdmemory-runtime.service），删掉复制到 ~/Library/LaunchAgents/ 或 ~/.config/systemd/user/ 的那份文件。

许可证

Apache-2.0，见 LICENSE。