memhub CLI

memhub 是面向 Agent 和终端用户的 MemHub 命令行工具。它从任意目录运行，默认输出人类可读文本，使用 --json 时只向 stdout 输出稳定 JSON。

CLI 帮助信息的格式规范见 ../docs/memhub-cli-help-style.md。新增或调整命令时，先按该模板更新 help 输出和测试。

安装

推荐从 npmjs 安装。正式 npmjs 包名为 @vvicat/memhub，会依赖 @vvicat/memhub-runtime，因此安装 CLI 后即可使用 memhub runtime 管理本机 Runtime：

npm install -g @vvicat/memhub

也可通过 MemHub 站点安装脚本包装 npm 安装：

curl --noproxy '*' -fsSL "https://memhub.vvicat.dev/cli/install.sh" -o /tmp/memhub-install.sh
bash /tmp/memhub-install.sh

Windows PowerShell：

irm "https://memhub.vvicat.dev/cli/install.ps1" | iex

安装脚本默认使用 npmjs registry 和 @vvicat/memhub；可通过 MEMHUB_NPM_REGISTRY 覆盖 registry，通过 MEMHUB_NPM_PACKAGE 覆盖包名。npm registry 不可用、版本不匹配或 npm 安装失败时会回退到单文件 CLI 下载方式。该 fallback 会内联 Agent Hook 模块、Codex hook 模板、Runtime 构建产物和最小 ws 依赖，可用于 doctor、request、hook doctor/install/run、runtime 和 setup。自建 registry 使用旧包名时可设置 MEMHUB_NPM_PACKAGE=@memhub/cli。

本地开发安装：

cd cli
make install-local
command -v memhub
memhub --help

默认安装到 ~/.local/bin/memhub。

发布 CLI

站点仍保留以下 target 的单文件 CLI fallback，供没有启用 npm registry 的环境使用：

• macos-aarch64
• macos-x86_64
• linux-x86_64
• linux-aarch64
• windows-x86_64

发布产物可放在 cli/dist/，命名格式为：

memhub-<version>.js

当前平台可执行：

make package-current

版本号来自 package.json。

认证与配置

配置优先级：

1. 命令行参数：--base-url、--api-key
2. 环境变量：MEMHUB_BASE_URL、MEMHUB_API_KEY
3. 凭据文件：~/.memhub/credentials.json
4. 默认地址：http://127.0.0.1:3100

浏览器 OAuth 登录并保存凭据：

memhub login

如果需要直接使用 API Key 登录，可以从 stdin 传入：

printenv MEMHUB_API_KEY | memhub login --with-api-key

初始化 Agent hook 并重启本机 Runtime：

curl --noproxy '*' -fsSL "https://memhub.vvicat.dev/cli/install.sh" -o /tmp/memhub-install.sh
bash /tmp/memhub-install.sh
memhub setup --agent codex --yes --strict --json
memhub --json doctor

自动化接入脚本应先运行站点安装器，再运行 memhub setup。memhub setup --yes 自身也会检查更新；如果它安装了新 CLI，会返回 restart_required=true 与 blocking_reason=cli_updated_restart_required，调用方必须立刻重跑同一条 memhub setup --agent codex --yes --strict --json，确保后续 hook 与 Runtime 安装由新版 CLI 执行。

memhub setup 会先打印当前配置并确认是否重置；确认后写入 ~/.memhub/credentials.json，安装或检查当前 Agent hook，重启 Runtime，并验证 gateway 状态。自动化脚本可传 --yes 跳过确认；--strict --json 是完整接入验收模式，只有输出 ok=true 时才能声明 Agent 已完整接入。如果当前 Agent 不支持 hook、安装失败、Codex App hooks feature 未启用，或 hook 已注册但尚未被 Codex 真实执行并回报 runtime_verified，strict 会输出 ok=false 和 blocking_reason，并保留全局提示词兜底接入。hook_pending_runtime_verification 不能由 CLI 绕过；自动化脚本可以改用 memhub setup --agent codex --yes --strict --wait-trust --trust-timeout-ms 120000 --json，让 CLI 在用户完成 Codex App 信任动作并触发任意 Codex 行为后继续轮询 doctor 并完成验收。若等待超时，仍必须提示用户触发一次 Codex 行为后重跑 memhub hook doctor --agent codex --json 或 memhub setup --agent codex --yes --strict --json。Codex hook active 后，本地 handler 只调用 POST /api/agent-hooks/dispatch，规则、知识库上下文、审计、通知和后续工作流由 MemHub 平台调度；平台不可用时默认放行。

检查或安装 hook：

memhub hook doctor --agent codex --json
memhub hook install --agent codex
memhub hook run --agent codex --event '{"type":"pre_exec","cwd":"/path/to/repo","command":"npm test"}'
memhub hook uninstall --agent codex

hook run 用于闭环验证或调试单个 hook 事件，支持 --event <json>、--event-file <file> 或从 stdin 读取 JSON。hook uninstall 只移除 MemHub 安装的 Codex hook 入口和内置 handler，不删除未知 handler。

查看或清除当前认证状态：

memhub auth status
memhub auth logout

memhub auth status 会读取当前解析到的服务器地址和 API Key，调用 /api/auth/me 显示当前用户，并只展示截断后的 token 预览。memhub auth logout 只删除 ~/.memhub/credentials.json 中保存的 api_key，保留 base_url 等其他配置。

memhub doctor 默认按步骤检查 CLI 版本、登录状态、Agent hook、Runtime 和服务健康状态；doctor --json 会保留完整结构化诊断，报告 token 是否存在、来源和截断预览，但不会打印完整 token。

一键 setup

Agent 接入推荐调用 setup，把凭据初始化、Agent hook 安装、Runtime 重启和 gateway 状态检查串成一个动作：

curl --noproxy '*' -fsSL "https://memhub.vvicat.dev/cli/install.sh" -o /tmp/memhub-install.sh
bash /tmp/memhub-install.sh
memhub setup --agent codex --yes --strict --json

如需把 Codex Provider 切到 MemHub LLM Gateway，可追加：

memhub setup --agent codex --enable-llm-gateway --yes --strict --json

无人值守脚本需要在用户面前完成 Codex App 信任验收时，可追加等待参数：

memhub setup --agent codex --yes --strict --wait-trust --trust-timeout-ms 120000 --json

setup 会：

• 检查 MemHub CLI 是否有可用更新；--yes 下会自动执行安装器更新。若本次安装了新版 CLI，当前进程会返回 restart_required=true，调用方必须重跑 setup，避免继续使用旧代码安装 hook。
• 写入 ~/.memhub/credentials.json。
• 检查 /api/auth/me。
• 传入 --enable-llm-gateway 时，写入 Codex provider 配置，并把 MEMHUB_API_KEY 写入 ~/.memhub/env（权限 0600）；安装器会在 shell profile 中 source 该文件，并在 macOS 当前登录会话中执行 launchctl setenv MEMHUB_API_KEY ...。API Key 不会写入 ~/.codex/config.toml。
• 安装或检查 Codex hook；会写入稳定 feature features.codex_hooks = true、兼容字段 features.hooks = true 和 .codex/hooks.json 事件配置。若发现 ~/.codex/config.toml 不是标准 UTF-8，安装器会先按 BOM/UTF-16 特征解码，写回 UTF-8，并保留一份 .bak 备份，避免编码混乱破坏 TOML。registered_pending_runtime_verification 表示 hook 文件、feature 和注册已就绪，但 CLI 尚未检测到 Codex 真实执行 hook 产生的 heartbeat；这不等同于用户没有在 Codex App 中信任。传入 --wait-trust 时，CLI 会等待 hook 从 Codex 真实执行并验收为 active。
• 重启 MemHub Runtime，确保新的认证信息进入 Runtime 环境；macOS 上默认写入用户级 LaunchAgent，随登录自动启动 Runtime，可用 --no-startup 关闭。Windows 或排障场景如需避免后台 learning connector bootstrap，可追加 --skip-connectors。
• 等待 worker heartbeat 后读取 /runtime/nodes 与 /runtime/sessions。
• 输出 learning 配置，默认通过 learning scheduler 启用 lark-minutes，启动后由 Runtime 自动创建 connection 并按同步状态拉取。

--strict 下 --skip-hook 是非法组合。strict 验收必须同时满足 API Key 认证成功、hook doctor 为 active、Runtime running、gateway connected、gateway 中对应 node online 且 session 非 closed。strict 失败时命令返回非零退出码，并在 JSON 中给出 blocking_reason；非 strict 的 setup 保持现有兼容行为。--wait-trust 只负责等待 hook 运行验证结果，不会绕过 Codex App 的信任确认。

JSON 契约

--json 成功时直接输出 API 对象、数组或 CLI 包装对象。错误时输出：

{
  "ok": false,
  "error": {
    "message": "HTTP 401: ..."
  }
}

CLI 会在错误中尽量隐藏 api_key、token、password、secret 等字段。

strict setup 失败时输出结构化阻断原因，例如：

{
  "ok": false,
  "strict": true,
  "blocking_reason": "hook_pending_runtime_verification",
  "fallback_prompt": {
    "available": true
  }
}

blocking_reason 取值包括 auth_failed、cli_install_failed、cli_updated_restart_required、runtime_worker_missing、runtime_worker_not_running、gateway_unreachable、gateway_node_offline、hook_install_failed、hook_inactive、hook_pending_runtime_verification、codex_hooks_feature_disabled 和 server_unreachable。

常用命令

memhub login
memhub auth status
memhub --json doctor
memhub update --json
memhub setup --agent codex --yes --strict --json
memhub hook doctor --agent codex --json
memhub hook run --agent codex --event '{"type":"pre_exec","cwd":"/path/to/repo","command":"npm test"}'
memhub run npm test
memhub run git status
memhub runtime start
memhub runtime status
memhub runtime stop
memhub adapter install @memhub/adapter-xxx
memhub adapter install ./local-adapter
memhub adapter list
memhub auth logout
memhub --json request get /knowledge-bases?scope=all
memhub --json request get /auth/me

Tool Output 压缩

memhub run <command> 用于执行本地命令并返回面向 Agent 的精简输出。CLI 会保留完整 stdout/stderr 到本地 artifact，并在屏幕输出中展示摘要、完整日志路径和 token 估算。

memhub run npm test
memhub run pytest
memhub run git status

默认完整输出位置：

~/.memhub/artifacts/runs/{run_id}.log

第一版优先压缩测试、git 和日志类高噪音输出；未知命令会返回截断摘要并保留完整 artifact。该能力只压缩工具输出，不等同于 LLM Gateway 的完整模型请求压缩。

Runtime

memhub runtime 用于从 CLI 管理本机 Runtime 进程。CLI 会优先从 npmjs 依赖 @vvicat/memhub-runtime 解析 Runtime 入口，并兼容自建 registry 包名 @memhub/runtime；用户不需要 MemHub 源码 checkout。

未显式传 --node-key 时，Runtime 默认使用 MemHub API Key 指纹 + 本机机器指纹生成节点 key；同一 API Key 安装在不同电脑上会注册为不同 Runtime 节点，不会互相覆盖。只有需要固定覆盖某个节点身份时，才手动传 --node-key。

memhub runtime start 和 memhub runtime restart 在 macOS 上默认注册用户级开机自启，写入 ~/Library/LaunchAgents/dev.vvicat.memhub.runtime.plist。该 LaunchAgent 会在用户登录时执行 memhub runtime start，复用当前 gateway、entry、pidfile 和 log 配置；如需只启动本次进程而不注册自启，可追加 --no-startup。如需跳过 lark-cli、本地记忆等 learning connector bootstrap，可追加 --skip-connectors。

memhub runtime start
memhub runtime status
memhub runtime stop

常用参数：

memhub runtime start --entry /path/to/packages/runtime/dist/server.js
memhub runtime start --node-key local-codex-1 --gateway ws://127.0.0.1:4101
memhub runtime start --no-startup
memhub runtime start --skip-connectors

默认 pidfile 和日志位置：

• ~/.memhub/runtime.pid
• ~/.memhub/runtime.log

Runtime Adapter 扩展

官方 Codex、Hermes 等 Provider 随 Runtime 内置分发，不需要单独安装。第三方 adapter 可通过 CLI 安装到本机 adapter registry：

memhub adapter install @memhub/adapter-xxx
memhub adapter install @memhub/adapter-xxx --registry https://registry.npmjs.org
memhub adapter install ./local-adapter --name local-test
memhub adapter list --json
memhub adapter uninstall memhub-adapter-xxx

npm 包会安装到 ~/.memhub/adapters，本地路径 adapter 会登记绝对路径；registry 文件是 ~/.memhub/adapters.json。该命令负责维护本机 adapter registry，供 Runtime adapter loader 消费。

源码开发环境可通过 runtime 或 setup --entry 指向本地构建产物：

cd packages/runtime
npm install
npm run build
memhub runtime start --entry "$PWD/dist/server.js"
memhub setup --agent codex --yes --strict --entry "$PWD/dist/server.js" --json

写操作策略

高层知识库、文档、skills、activities、agents 命令已从 CLI 命令面移除。确需访问这些 API 时，使用 raw request：

memhub --json request get /knowledge-bases?scope=all
memhub --json request post /knowledge-bases --body '{"name":"demo","description":"demo","visibility":"private"}'

删除、成员管理、API key 再生成等危险操作需要用户明确要求后才通过 raw request 执行。