npm package: @superpms/memory-cli
Description: CLI for memory system — global layer, will sync, vendor updates
Latest version: 0.2.6

# memory CLI

`memory CLI` 用来连接 Cloud Brain，并管理两类内容：

- 用户级全局 `memory` system
- 当前项目本地 `.memory/`

当前架构已经不是“每个项目各自维护一份运行时 `memory/`”。运行时模型是：

```text
Cloud Brain
    <-HTTP API->
<global-memory-root>/ + current-project/.memory/
```

## 架构概览

### 全局目录

默认全局根目录：

```text
<os.homedir()>/.memory-brain/
```

典型内容：

```text
.memory-brain/
  credentials.json
  vendor/
    agent.platform.json
    start.md
    skills/
    specification/
  will/
    current/
```

说明：

- `credentials.json`：CLI 登录凭证
- `vendor/start.md`：后续 agent 的统一使用入口
- `vendor/`：系统规则、system skills、规范、启动模板
- `will/current/`：当前用户的全局 will
- `development.md` 只属于 `memory` 源码仓开发态，不属于普通用户全局 runtime

### 项目目录

每个项目只保留自己的 `.memory/`：

```text
your-project/
  .memory/
```

CLI 不再在项目根创建运行时 `memory/`。

## 项目识别规则

CLI 通过下面这个文件识别当前目录是否位于一个 `memory` 项目中：

```text
.memory/.project/config/runtime.md
```

也就是说：

- 有 `.memory/.project/config/runtime.md`，就视为 `memory` 项目
- 不再以 `memory/start.md` 或 `memory/vendor/start.md` 作为项目识别条件

## 环境变量

全局 root 解析顺序：

1. `MEMORY_BRAIN_DIR`
2. `MEMORY_CREDENTIALS_DIR`
3. `<os.homedir()>/.memory-brain`

说明：

- `MEMORY_BRAIN_DIR` 是当前推荐的全局 memory root 覆盖变量
- `MEMORY_CREDENTIALS_DIR` 仍兼容作为全局 root 覆盖变量
- 一旦设置上述变量，CLI 会把该目录视为整个全局 memory root，而不只是凭证目录

## 命令概览

```text
auth login
auth register
auth status
auth logout

project init
project business-ends set <end1,end2>
project status

update

will pull
will push
will status
will versions
will share <private|public|unlisted>
will followers

subscription add <will_id>
subscription remove <will_id>
subscription list
subscription pull <will_id>

vendor publish [--version=X.Y.Z]
vendor status
vendor history

skill list
skill remove <name>

cache status
cache clean [--older-than=30d]

overview
doctor
version
```

## 账户与登录

示例：

```bash
memory auth register --endpoint=https://memory-brain.example.com
memory auth login --endpoint=https://memory-brain.example.com
memory auth status
memory auth logout
```

规则：

- `register` / `login` 使用邮箱作为用户名
- `--endpoint=...` 可在首次注册或登录时传入
- 登录成功后，`api_endpoint`、`api_key`、`user_id`、`will_id` 会写入 `credentials.json`
- 后续命令默认使用已保存的 endpoint

## 初始化与更新

### 推荐顺序

```bash
memory auth login --endpoint=https://memory-brain.example.com
memory update
memory project init
```

### `memory update`

职责：

- 下载最新 vendor 到全局 `<global-memory-root>/vendor/`
- 同步全局 `<global-memory-root>/vendor/start.md`
- 若本地 `vendor/` 比云端发布多出旧文件，更新时会清理这些多余文件，使本地 vendor 恢复为云端发布快照
- 创建或保留全局 `<global-memory-root>/local/skills/` 作为当前用户本地 skill 变体层
- 拉取云端 will 到全局 `<global-memory-root>/will/current/`
- 拉取 will 后会同步记录云端当前 will visibility，建立本地 visibility lineage metadata
- 如果云端还没有 will，则从 vendor 模板自动 bootstrap 全局 will

特点：

- 只处理全局内容
- 不要求当前目录已经是 `memory` 项目
- 不创建项目 `.memory/`
- 不会覆盖 `<global-memory-root>/local/skills/`

### `memory project init`

职责：

- 在当前项目创建 `.memory/`
- 修复已存在但不完整的 `.memory/`
- 创建 `.memory/.project/config/runtime.md`
- 创建 `.memory/.project/config/install-lock.md`
- 创建 `.memory/.project/cache/`、`.memory/.project/global/`、`.memory/.project/skills/`
- 为已确认业务端补齐 `.memory/<业务端>/config|guidance|docs|planning|source`
- 生成一个 agent 入口文件

支持的接入模式：

- `--mode=fresh_project`
  适用于新项目；只建项目级 `.memory/.project/*`
- `--mode=in_progress_project`
  适用于已经开发中的项目接入；会在当前执行目录创建或修复 `.memory/`
- 不传 `--mode`
  当当前目录已经存在 `.memory/` 或已显式传入 `--business-ends=...` 时，CLI 会按 `in_progress_project` 处理；否则默认 `fresh_project`

支持的业务端声明方式：

- `--business-ends=admin,user`
  显式指定当前项目的业务端列表
- Windows PowerShell 兼容
  如果 shell 把 `admin,user` 折叠成 `admin user`，CLI 也会按同一组业务端处理
- 不传 `--business-ends`
  CLI 只创建或修复 `.memory/.project/*`，并保留空的 `business_ends`
- 后续如果已经明确业务端
  推荐执行 `memory project business-ends set <end1,end2>`；CLI 会更新 runtime 并补齐 `.memory/<业务端>/*`

项目根规则：

- 在哪个目录执行 `memory project init`，哪个目录就是项目根
- CLI 不会通过子目录里的 `package.json`、`src/`、`rust/` 或其他代码结构去反推“真正项目根”
- 业务端声明与项目根判定是两回事；是否传 `--business-ends=...` 不会改变项目根

支持的入口文件选择方式：

- `--platform=...`
  从 `<global-memory-root>/vendor/agent.platform.json` 里找预设路径
- `--entry=...`
  直接指定项目内自定义输出路径
- 都不传时
  CLI 会交互式让你选一个预设平台，或输入自定义路径

规则：

- 入口文件模板内容只有一份，平台差异只体现在输出路径
- 如果目标文件已存在，不覆盖，只提示已存在
- 如果当前项目已经存在配置里的 agent 入口文件，`project init` 不会再次弹出平台选择，也不会重复生成
- `.memory/.gitignore` 只忽略 `.memory/.project/cache/`，不会把业务端目录整体忽略掉
- `memory project init` 依赖全局 vendor 与全局 `vendor/start.md` 已存在；如果缺失，先运行 `memory update`

明确不做的事情：

- 不下载 vendor
- 不 bootstrap 全局 will
- 不迁移旧项目本地 `memory/`
- 不归档旧项目 backup
- 不做向下兼容修复

### `memory project business-ends set`

职责：

- 更新 `.memory/.project/config/runtime.md` 里的 `business_ends`
- 按当前显式列表补齐 `.memory/<业务端>/config|guidance|docs|planning|source`
- 同步刷新 `.memory/00-索引.md`

用法：

```bash
memory project business-ends set admin,user
```

PowerShell 兼容：

- 如果 shell 把 `admin,user` 传成 `admin user` 或拆成多个参数，CLI 会按同一组业务端处理

规则：

- 只在已经初始化过的 memory 项目里使用
- `set` 以你传入的列表为准更新 runtime 和索引
- 如果新列表里有此前不存在的业务端，会补建骨架
- 如果新列表移除了旧业务端，当前只更新 runtime 与索引；旧目录不会自动删除
- 当前没有用于声明 `working_business_ends` 的 CLI 命令；任务级工作作用域仍由 agent 在当前任务内判定，并写入 workflow session，而不是写入项目级 runtime

## agent 入口文件

预设路径来自：

```text
<global-memory-root>/vendor/agent.platform.json
```

示例：

```json
[
  { "platform": "Codex / OpenAI", "entry": "/AGENTS.md" },
  { "platform": "Claude Code", "entry": "/CLAUDE.md" },
  { "platform": "GitHub Copilot", "entry": "/.github/copilot-instructions.md" }
]
```

注意：

- 这里定义的是“预设输出路径”
- 不是多套模板内容
- 自定义路径仍然允许

## 管理全局 will

```bash
memory will pull
memory will push
memory will status
memory will versions
memory will share private
memory will share public
memory will share unlisted
memory will followers
```

说明：

- `will pull` / `will push` 作用于全局 `<global-memory-root>/will/current/`
- `will status` 展示的是全局 will 状态
- `will share` 修改的是云端 will 可见性
- 当前实现按目录中实际存在的 `.md` 文件读写 will，不依赖固定文件名列表

## 订阅别人的 will

```bash
memory subscription add <will_id>
memory subscription add <will_id> --dimensions=02,03
memory subscription list
memory subscription pull <will_id>
memory subscription remove <will_id>
```

说明：

- `subscription` 只处理“我订阅的别人”
- 订阅关系存在云端
- 拉取下来的订阅内容保存在项目本地：

```text
.memory/.project/subscriptions/<will_id>/
```

- `subscription` 不会改写自己的全局 `will/current/`

## 管理全局 vendor

```bash
memory vendor status
memory vendor history
memory vendor publish --version=0.1.0
```

说明：

- `vendor publish` 发布的是当前 `memory` 系统源码项目里的 `vendor/`
- 管理员应进入当前 `memory` 项目目录后再执行发布
- 当前源码项目通过仓库根的 `memory.system.json` 显式声明身份，不靠机器路径、仓库名或固定目录名判断
- 发布源不是已安装到 `<global-memory-root>/vendor/` 的全局快照
- 只有管理员可以发布

## Skills

```bash
memory skill list
memory skill remove <name>
```

读取来源：

- 项目 skill：`.memory/.project/skills/`
- 全局本地 skill：`<global-memory-root>/local/skills/`
- 全局 system skill：`<global-memory-root>/vendor/skills/`

说明：

- `skill list` 会同时展示 project skills、global local skills 和 system vendor skills
- 同名 skill 的优先级为：project > global local > system
- `skill remove` 只删除当前项目 skill

## Cache

```bash
memory cache status
memory cache clean
memory cache clean --older-than=7d
```

缓存目录：

```text
.memory/.project/cache/
```

## 概览与排障

```bash
memory overview
memory doctor
memory doctor auth
memory doctor project
memory doctor cloud
memory doctor cloud --endpoint=https://memory-brain.example.com
```

### `memory overview`

显示：

- 当前 Cloud Brain endpoint
- 当前用户
- 全局 memory root
- 全局 vendor / will 是否存在
- 当前目录是否位于 `memory` 项目中

### `memory doctor auth`

检查：

- `credentials.json` 是否存在
- `api_endpoint` 是否有效
- `api_key` 是否存在
- `/auth/me` 是否通过

### `memory doctor project`

检查：

- 当前目录是否位于 `.memory/` 项目中
- 全局 vendor 是否存在
- 全局 will 是否存在
- 项目本地 `runtime.md` 是否存在
- `runtime.md` 是否已经登记 `business_ends`
- 已登记业务端的最小骨架是否完整
- vendor proof / will proof
- will 可见性与内容一致性
- subscription 一致性、版本漂移、维度漂移、内容一致性
- vendor history、lineage、release reconciliation、文件一致性

补充规则：

- `doctor project` 只检查现行 runtime 合同，不负责旧本地 `memory/` 的迁移、归档或 residue 治理
- `doctor project` 不负责判定或保存任务级 `working_business_ends`；它检查的是项目级稳定状态，不是当前会话作用域
- 当前项目就算额外存在其他目录，运行时入口仍然只有全局 `<global-memory-root>` 加项目本地 `.memory/`

### `memory doctor cloud`

检查：

- endpoint 是否存在
- endpoint 是否是有效 URL
- `/health` 是否可达

## 常用流程

### 首次使用

```bash
memory auth register --endpoint=https://memory-brain.example.com
memory update
memory project init
memory overview
```

### 已有账号，接入新项目

```bash
memory auth login --endpoint=https://memory-brain.example.com
memory update
memory project init --mode=in_progress_project
memory project business-ends set admin,user
```

### 日常同步

```bash
memory update
memory will pull
memory will push
```

说明：

- `memory will pull` 在拉取云端 will 内容后，也会同步记录云端当前 visibility 到本地 `manifest.json`
- `memory update` 执行全局 will 同步时，也会做同样的 visibility lineage 同步
- 因此正常 pull/update 过的环境，不需要再额外执行一次 `memory will share ...` 才能建立本地 visibility lineage

### 排障

```bash
memory doctor
memory doctor auth
memory doctor project
memory doctor cloud --endpoint=https://memory-brain.example.com
```

## 与旧模型相比

以下说法已经不再成立：

- “每个项目都要有一份运行时 `memory/`”
- “项目初始化会创建 `memory/start.md`”
- “项目初始化会把 vendor / will 复制进项目根的 `memory/`”
- “`memory project init` 会顺手处理旧本地 `memory/`”

现行模型是：

- 全局运行时内容在 `<global-memory-root>/`
- 项目运行时内容在 `.memory/`
- 全局同步由 `memory update` 负责
- 项目初始化由 `memory project init` 负责

## FAQ

### 为什么 `memory project init` 前要先运行 `memory update`？

因为项目初始化依赖全局 vendor、全局 `vendor/start.md` 和 `agent.platform.json`。这些都属于全局内容，不属于项目初始化职责。

### 为什么已经开发中的项目要用 `--mode=in_progress_project`？

因为这类项目不只是“建一个空 `.memory/`”。CLI 还需要在当前执行目录建立正式运行态；如果你已经明确业务端，再通过 `memory project business-ends set <end1,end2>` 把 `.memory/<业务端>/config|guidance|docs|planning|source` 一次补齐。

### 为什么新用户在没有云端 will 时也会有本地 will？

因为 `memory update` 会在云端没有 will 时，从 vendor 模板自动 bootstrap 一份全局本地 will，避免后续流程没有可用的 `will/current/`。

### 为什么 `memory update` 可以清理本地 vendor 多余文件？

因为 `<global-memory-root>/vendor/` 现在定义为云端发布快照层，应该始终与云端 release 一致。用户自己的全局本地 skill 变体应写到 `<global-memory-root>/local/skills/`，不再混写到 `vendor/`。

### 为什么 `memory login` / `memory init` 这类旧命令不能用了？

命令树已经改为分组式结构，旧入口不再兼容。现行入口以这些命令为准：

```bash
memory auth login
memory doctor
memory project init
memory update
```

### `ENOTFOUND` 通常意味着什么？

通常是 DNS 无法解析 Cloud Brain 域名，不是 CLI 命令树问题。先检查：

```bash
memory doctor cloud --endpoint=https://your-cloud-brain.example.com
```

如果明确提示 DNS 失败，再去检查域名解析或反向代理配置。

## 回归脚本

正式回归脚本：

```bash
npm run test:regression
```

等价源码入口：

```bash
node scripts/run-regression-matrix.mjs
```

特点：

- 脚本直接调用当前源码 CLI：`bin/memory.mjs`
- 脚本会自建 mock global root，不依赖你机器上已安装的全局 CLI、全局 vendor、全局 will 或真实凭证状态
- 脚本会自建时间戳矩阵目录，覆盖项目初始化、业务端显式登记、空业务端告警、替换业务端不删旧目录、补骨架、单业务端根项目、非法输入、入口文件保护、自定义入口、outside-project 失败、重复登记幂等等场景
- 脚本会在矩阵目录输出 `summary.json`、`summary.md` 与每个场景的 `commands.log`

常用参数：

```bash
node scripts/run-regression-matrix.mjs --matrix-parent=E:\claude\test
node scripts/run-regression-matrix.mjs --only=T04,T09
node scripts/run-regression-matrix.mjs --cleanup
```

规则：

- 默认矩阵目录会创建在系统临时目录下，避免样本目录被误判成当前仓库自己的 `.memory` 子目录
- 如果你把 `--matrix-parent` 指到某个已存在的 memory 项目内部，脚本会拒绝执行，避免污染项目根判定
- 在继续做手工真实项目验收前，优先先跑这套正式回归脚本；它负责把已经验证过的样本路径稳定复现出来

## 设计边界

- `memory CLI` 负责 Cloud Brain 连接、全局 memory root 与项目 `.memory/` 的管理
- 后来的 agent 不承担初始化流程
- 项目初始化由 `memory project init` 负责
- 全局 vendor 与全局 will 同步由 `memory update` 负责
- agent 使用入口始终是全局 `<global-memory-root>/vendor/start.md`
- 项目本地只保留 `.memory/`