@yottameta/yotta-memory 0.4.0 → 0.5.0

package/README.md

@@ -15,25 +15,31 @@
   <a href="https://github.com/YottaMeta/yotta-memory"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen" /></a>
 </p>
 
+> 📖 面向用户的操作手册见 [USER_GUIDE.md](USER_GUIDE.md)。
+
 ## 核心价值
 
 多数记忆方案把「记住」做成了黑盒：数据进了数据库或云端，用户既看不到内容、也难以审计，更控制不了「哪个智能体能看到什么」。元忆换了一条路：
 
 - **记忆就是文件**：每条记忆是一个带 YAML frontmatter 的 Markdown 文件，放在用户自己的目录里。用任何编辑器都能查看、修改、删除，用 git 就能做版本管理与回滚。
-- **隔离由机制保证**：FACT 进公共区共享，PREF / BOUND / COMMIT 进私密区、按 agent 隔离。读取按 scope/owner 分区过滤，越界内容由 CLI 拦截、永不返回（默认静默跳过；显式跨读无授权才报错拒绝）——不依赖智能体的「自觉」。
+- **隔离由机制保证**：FACT 进公共区共享，PREF / BOUND / COMMIT 进私密区、按 owner 物理分目录隔离（`private/<owner>/<type>/`）。读取按 scope/owner 分区过滤，越界内容由 CLI 拦截、永不返回（默认静默跳过；显式跨读无授权才报错拒绝）；读写一律走 CLI / MCP，禁止 shell 直读写库文件——不依赖智能体的「自觉」。
 - **零依赖、即装即用**：无守护进程、无数据库、无向量库，只需要 Node.js。安装即用，数据留在本机。
+- **便携记忆盘**：记忆库本身就是记忆引擎——装在硬盘或主机上随盘走，局域网内其它主机上的智能体可远程读写；本地零进程模式与局域网常驻模式可并存，插上硬盘即恢复全部记忆。
 
 ## 核心优势
 
 | 优势 | 说明 |
 |---|---|
 | **数据主权在用户** | 明文文件存储，可读、可改、可审计；git 可版本化，回滚 / 团队同步都走标准工具 |
-| **真正的权限边界** | 公共 / 私密分区 + scope/owner 过滤 + 授权机制（grant / identity=user / `--unsafe`），越界内容由 CLI 过滤、永不返回（默认静默；显式跨读 `--all`/`--owner <其它>` 无授权时 exit 3），不靠 AI 自律 |
+| **真正的权限边界** | 公共 / 私密分区 + 按 owner 物理分目录（`private/<owner>/<type>/`）+ scope/owner 过滤 + 授权机制（grant / identity=user / `--unsafe`），越界内容由 CLI 过滤、永不返回（默认静默；显式跨读 `--all`/`--owner <其它>` 无授权时 exit 3）；`--agent <其它>` 仅作身份声明、不授予跨读。读写走 CLI / MCP，禁 shell 直读写，不靠 AI 自律 |
 | **跨智能体标准** | 符合 Agent Skills 开放标准（agentskills.io）；装一次，Claude Code / Codex / Cursor / OpenCode 等 78+ 智能体可共用同一份记忆 |
 | **轻量零依赖** | 无 daemon / 无数据库 / 无向量库；Node.js 自带即跑，任何机器可部署 |
 | **双级存储** | 用户级 `~/.yottamemory/`（跨项目）+ 项目级 `.yottamemory/`（随项目共享 / 交接）|
 | **检索与生命周期** | 索引 + TF 打分（中文分词友好）；质量分 / 盖棺分 / 自动归档，记忆库不会无限膨胀 |
 | **生态分发** | GitHub + npm 双源同步发布；npx skills / npm / install.sh 三种方式，覆盖 17+ 类智能体目录 |
+| **便携记忆盘（随盘走）** | 记忆库即引擎：装在硬盘 / 主机上，插上即恢复全部记忆；引擎主机只需装 CLI 当存放点，无需装任何 AI 智能体 |
+| **局域网共享与自启** | 每智能体独立 token（Bearer + X-Agent-Id）鉴权、可吊销；`lan enable` 注册开机自启（默认登录自启，可选开机即启）；MCP 工具集与 CLI 一致（8 个工具），管理动作不远程暴露 |
+| **本地 / 局域网双模式** | 本地 `serve --stdio` 零进程、按需拉起（无常驻）；局域网 streamable HTTP 常驻——两种模式可并存、按需选用 |
 
 ## 功能详解
 
@@ -55,16 +61,30 @@
 ### 权限与隔离
 
 - **读取三态**：公共 FACT 始终可读；自身私密始终可读；其它 agent 私密默认拒绝（不返回内容）。
+- **物理隔离目录**：私密记忆按 owner 存放于 `private/<owner>/<type>/`，不同智能体的私密文件物理分离；旧版根下平铺的 `prefs/` `bounds/` `commits/` 在 `reindex` 时自动迁移。
 - **三种授权入口（满足任一即可读他人私密）**：
   1. `grants.json` 显式授权：`{"<userAgent>": ["<ownerAgent>", ...]}`；
   2. identity=user：`--agent user` / `--owner user` / 环境变量 `YOTTA_AGENT_ID=user`；
   3. 显式 `--unsafe`（用户显式授权）。
 - **默认静默、显式跨读才报错**：默认 recall 遇其它 agent 私密静默跳过（不泄露「存在 N 条私密不可见」）；仅当显式跨智能体读取（`--all` / `--owner <其它>`）且无授权命中时才报错 / 警告。
+- **`--agent <其它>` 不越界**：`--agent <其它agent>` 仅作身份声明 / 展示用，不授予读取他人私密；读其它智能体私密仍需 grant / identity=user / `--unsafe`。
 - **隔离定位**：scope: private 保证的是 AI 之间的语义隔离（正常 recall 不会被搜到、不会主动去读），不是文件系统级机密保护——数据主权在用户，作为所有者有权看到任何记忆文件。
+- **禁止 shell 直读写**：记忆读写一律走 CLI / MCP 工具；用 shell（`Get-ChildItem` / `Get-Content` / `cat` / `ls` / `type` 等）直接读改库文件会绕过 scope/owner 权限边界，读到其它智能体私密内容。
+
+### 智能体身份（唯一 ID + 自我档案）
+
+每个智能体有一个**全局唯一的 agent ID**：它是私密记忆（PREF / BOUND / COMMIT）的归属键，也是远端接入的身份声明（`X-Agent-Id`）。
+
+- **登记（必须唯一）**：`yotta-memory iam <id>` 写入记忆库根目录 `agents.json`，**强制唯一性**——ID 已被其它主机 / 来源（含远端 token 登记）占用时拒绝，确认是同一智能体才 `--force`。
+- **确认身份**：`yotta-memory whoami`（远端 MCP 工具 `agent_info`）读「当次声明身份」（本机 `YOTTA_AGENT_ID` / CLI `--agent`；远端 `X-Agent-Id`），不猜不默认。
+- **自我档案（强制落盘）**：`iam` 自动写一条 PREF `subject=自我接入档案`（owner=自己），statement 为 `; ` 分隔的 key:value：`agent_id / host / memory_home / mcp_mode（stdio|http）/ engine_url（仅远端）/ token（仅远端；本机不存 token）`。开工先 `recall "自我接入档案"` 找回身份与接入信息。
+- **本机免 token**：本机 CLI / stdio 直连不经网络、不校验 token；身份经该智能体 MCP 配置的 `env.YOTTA_AGENT_ID` 声明。本机多个智能体各自声明唯一 ID，互不撞。
+- **私密记忆必须有 owner**：写 PREF / BOUND / COMMIT 时未声明身份会被拒绝（公共 FACT 不受影响），从机制上防止「抄别人的 ID」。
 
 ### 检索：索引 + 中文分词打分
 
 - `remember` 时自动构建 `index.json` 索引；recall 用 TF 打分排序，中文按 bigram 分词，不用额外模型。
+- `index.json` 的 `tokens` 字段是中文分词的词频表（TF 打分用），**不是**访问凭证；鉴权令牌在记忆目录下 `.server/tokens.json`。
 - 支持关键词、`--type` 过滤、`--limit` 截断、项目级优先。
 - 命中展示会累加 `access_count` / `last_accessed`，为生命周期管理提供依据。
 
@@ -80,6 +100,14 @@
 
 把技能装进智能体后，SKILL.md 会自动教会智能体一套工作流：**开工 `recall` 恢复上下文 → 重要信息 `remember` 落盘 → 收工归档**。也可在对话中直接说「记住 XXX」「上次说到哪了」「记一笔」触发。
 
+### 便携记忆盘（记忆库即引擎）
+
+- **记忆库即引擎**：`serve` 把记忆目录挂成 MCP 服务，目录随盘走；引擎主机只需装 CLI 当存放点，无需装任何 AI 智能体。
+- **双模式可并存**：本地 `serve --stdio` 零进程（客户端按需拉起）；局域网 streamable HTTP（默认 `0.0.0.0:8787`）+ 每智能体 token 鉴权。
+- **开机自启**：`lan enable` 注册 Windows 计划任务（默认登录自启，`--onstart` 开机即启需管理员）；`lan disable` 移除，`lan status` 查询。
+- **安全边界**：管理动作（init / config / token / lan / serve）不进 MCP，token 不远程暴露；远程智能体只能读写记忆，不能改配置、不能管 token。
+- 完整操作步骤见上文「局域网多机共享」章节与 [USER_GUIDE.md](USER_GUIDE.md)。
+
 ## 与其他方案对比
 
 > 以下按方案类型对比，不涉及具体产品名称。判断标准：数据主权、部署成本、权限边界、可审计性、跨智能体能力。
@@ -125,19 +153,35 @@ bash install.sh --dir /path/to/skills
 ```
 也可把整个 `yotta-memory` 文件夹复制到目标智能体的 skills 目录（常见位置见 install.sh --list）。
 
+## 升级
+
+两种升级方式对应两种安装方式：
+
+**升级 CLI**（重新执行一次安装命令即可，不带版本号默认装最新）：
+```bash
+npm i -g @yottameta/yotta-memory
+```
+
+**升级技能**：重新执行你当初的安装命令即可（`npx skills add YottaMeta/yotta-memory` 或 `yotta-memory-install -g`），覆盖旧版本技能文件夹。
+
+> 升级只影响命令与技能文件，**不会动你已存的记忆**（记忆是独立于安装的文件，保留在原目录）。
+
 ## CLI 用法
 
+
 | 命令 | 作用 |
 |---|---|
 | `yotta-memory init [--project] [--dir <目录>]` | 初始化记忆库（默认用户级 `~/.yottamemory/`；--dir 显式指定位置）|
 | `yotta-memory remember <type> <subject> <statement> [--owner <id>]` | 写入记忆（同 subject+statement 自动更新；--owner 标注归属）|
-| `yotta-memory recall [关键词] [--type T] [--limit N] [--agent <id>] [--owner <id>] [--all] [--unsafe]` | 检索记忆（索引+TF 打分，读取分区过滤；越界读其它智能体私密默认拒绝，需 grant / identity=user / `--unsafe`；项目级优先）|
+| `yotta-memory recall [关键词] [--type T] [--limit N] [--agent <id>] [--owner <id>] [--all] [--unsafe]` | 检索记忆（索引+TF 打分，读取分区过滤；越界读其它智能体私密默认拒绝，需 grant / identity=user / `--unsafe`；`--agent <其它>` 仅作身份声明、不授予跨读；项目级优先）|
 | `yotta-memory forget <文件>` | 删除一条记忆（按类型目录路径或文件名）|
 | `yotta-memory archive [--days 180] [--threshold 0.4]` | 归档旧记忆（盖棺分+年龄，immutable 除外）|
 | `yotta-memory reindex` | 重建索引（手动改 .md 后校正）|
 | `yotta-memory export [--out f.json]` / `import <f.json>` | 导出 / 导入 |
 | `yotta-memory config set memory_home <目录>` / `config get` | 持久记住 / 查看记忆库位置（`~/.yottamemory/config.json`）|
-| `yotta-memory token new --agent <id>` / `token list` / `token revoke --agent <id>` | 为智能体生成 / 列出 / 吊销访问 token（登记于记忆库 `.server/tokens.json`）|
+| `yotta-memory whoami` | 查看当前智能体身份与登记状态（读 `YOTTA_AGENT_ID` / `X-Agent-Id`，不猜不默认）|
+| `yotta-memory iam <id> [--force]` | 登记本智能体唯一身份并自动落自我档案（`agents.json`，ID 必须唯一）|
+| `yotta-memory token new --agent <id> [--force]` / `token list` / `token revoke --agent <id>` | 为智能体生成 / 列出 / 吊销访问 token（登记于记忆库 `.server/tokens.json`；同 ID 已被其它来源占用需 `--force` 覆盖，防不同智能体合流）|
 | `yotta-memory serve [--host 0.0.0.0] [--port 8787] [--no-auth] [--stdio]` | 启动 MCP 记忆引擎（streamable HTTP 局域网 / --stdio 本地零进程模式；Bearer token + X-Agent-Id 鉴权）|
 | `yotta-memory lan enable [--onstart] / disable / status` | 开机自启管理（Windows 计划任务，默认 ONLOGON 登录自启；--onstart 开机即启需管理员）|
 
@@ -153,7 +197,7 @@ yotta-memory recall --type FACT --limit 10
 
 环境变量：
 - `YOTTA_MEMORY_HOME`：覆盖用户级记忆库目录（默认 `~/.yottamemory/`）。
-- `YOTTA_AGENT_ID` / `AGENT_ID`：当前 agent 标识，参与读取分区判定。
+- `YOTTA_AGENT_ID` / `AGENT_ID`：当前 agent 标识（本机声明身份用，参与读取分区判定；私密记忆必须有 owner，未声明会被拒绝）。
 
 ## 智能体接入后怎么用
 
@@ -172,10 +216,11 @@ yotta-memory recall --type FACT --limit 10
 1. 初始化或接入记忆库（见 CLI 用法）。
 2. 为需要访问的每个智能体生成独立 token：
    ```bash
-   yotta-memory token new --agent <智能体ID>     # 打印一次，如 ytm_...
+   yotta-memory token new --agent <智能体ID>     # 打印一次，如 ytm_...（同 ID 已被其它来源占用需加 --force）
    yotta-memory token list                        # 查看已登记智能体
    yotta-memory token revoke --agent <智能体ID>   # 吊销
    ```
+   > 新生成的 token 即时生效，无需重启服务。
 3. 启动服务（默认监听 0.0.0.0:8787，Bearer token + X-Agent-Id 鉴权）——临时运行或注册开机自启二选一：
    ```bash
    yotta-memory serve                          # 临时前台运行
@@ -204,7 +249,7 @@ yotta-memory recall --type FACT --limit 10
 }
 ```
 
-连接后可通过 MCP tools（remember / recall / search / forget / archive / reindex / export / import）读写记忆；管理动作（init / config / token / lan / serve）不进 MCP，token 管理不远程暴露。`X-Agent-Id` 必须与 token 登记的智能体一致；读取分区规则与 CLI 相同（FACT 公共可读，PREF / BOUND / COMMIT 私密隔离）。
+连接后可通过 MCP tools（remember / recall / search / forget / archive / reindex / export / import / agent_info）读写记忆与确认身份；管理动作（init / config / token / lan / serve）不进 MCP，token 管理不远程暴露。`X-Agent-Id` 必须与 token 登记的智能体一致；读取分区规则与 CLI 相同（FACT 公共可读，PREF / BOUND / COMMIT 私密隔离）。
 
 ### 位置持久化
 

package/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: yotta-memory
 description: "元忆 —— 有权限边界的文件式智能体记忆。文件式、零依赖、可 diff/回滚：让任何 AI 智能体活过会话，开工 recall 恢复上下文、重要信息 remember 落盘、收工归档。类型体系 FACT（公共共享）/ PREF / BOUND / COMMIT（私密隔离）。触发：记住、别忘了、记一笔、记忆、remember、recall、跨会话、上次说到、续测、交接、归档、记忆盘、共享记忆、局域网记忆"
-version: 0.4.0
+version: 0.5.0
 license: MIT
 ---
 
 # yotta-memory（元忆）— 有权限边界的文件式智能体记忆
 
 > 一句话：元忆 —— 有权限边界的文件式智能体记忆（不注入、可 diff、能回滚；FACT 共享、PREF / BOUND / COMMIT 私密隔离）。
-> 版本：0.4.0 | 最后更新：2026-08-25
+> 版本：0.5.0 | 最后更新：2026-08-25
 
 ## 这是什么
 
@@ -26,10 +26,42 @@ license: MIT
 
 ## 核心流程
 
-1. **开工定向**：运行 `yotta-memory recall`（可带关键词）恢复上下文；项目级记忆优先，其次用户级。
+1. **开工定向**：先按「开工第一步：确认记忆位置 + 智能体身份」检测记忆库与身份，再运行 `yotta-memory recall`（可带关键词）恢复上下文；项目级记忆优先，其次用户级。
 2. **进行中落盘**：重要信息立即 `yotta-memory remember <type> <subject> <statement>`，不攒到收工。
 3. **收工归档**：写会话小结（COMMIT / 笔记），旧记录定期 `yotta-memory archive`。
-4. **多智能体纪律**：FACT 写入公共区，PREF / BOUND / COMMIT 只写本智能体私密区；不读取其他智能体私密区。
+4. **多智能体纪律**：FACT 写入公共区，PREF / BOUND / COMMIT 只写本智能体私密区；不读取其他智能体私密区。**一切读写一律走 `yotta-memory` CLI / MCP 工具**——禁止用 shell（`Get-ChildItem` / `Get-Content` / `cat` / `ls` / `type` 等）直接读或改记忆库目录下的 `.md` / `index.json` / `tokens.json` / `agents.json` / `grants.json` 等文件，否则会绕过权限边界、读到别的智能体私密内容。
+
+
+### 开工第一步：确认记忆位置 + 智能体身份（每次会话先做，必做）
+
+**A. 确认记忆库位置**（AI 不会自动知道记忆库在哪，先检测，避免「recall 读空库 / 错库」）：
+
+1. 运行 `yotta-memory config get`。
+   - 输出 `memory_home: <目录>`（已显式设置）→ 直接用该位置。
+   - 输出 `memory_home: (未设置，默认 ~/.yottamemory)` → 🔒 征得同意后引导设置：问用户用默认还是指定目录（项目级 `<repo>/.yottamemory`、记忆盘等），确认后 AI 执行 `yotta-memory config set memory_home <目录>`，回读 `config get` 验证。
+2. **已有记忆**：目标目录已存在 `facts/` 等子目录或 `index.json` → 直接 recall；全新目录 → 按「便携记忆盘模式 §0.3」初始化。
+
+**B. 确认本智能体唯一身份（强制，写私密记忆前必做）**：
+
+1. 运行 `yotta-memory whoami`（远端经 MCP 用 `agent_info`）确认「我是谁」。
+   - 已显示身份 + 已登记 + 有自我档案 → 用它，进入第 3 步。
+   - 显示「未声明身份」或「未登记」→ 进入第 2 步。
+2. **登记唯一 ID（AI 自己定义，须用户确认）**：
+   - AI 提议一个**全局唯一** ID（建议 `<主机名>-<角色>` 或带随机后缀，如 `win-zhiwei` / `kali-dashu`；禁止用 `dashu` / `codex` 这类易撞名）。
+   - 🔒 征得用户同意后执行 `yotta-memory iam <id>`：引擎**强制唯一性**（ID 已被其它主机/来源占用 → 拒绝并提示换 ID；确认是同一智能体才 `--force`），并**自动写自我档案**到本智能体私密区。
+   - 回读：`yotta-memory whoami` 显示「已登记 + 自我档案」。
+3. **自我档案校验**：`yotta-memory recall "自我接入档案"`（本智能体）能读回字段才算就绪：
+   `agent_id / host / memory_home / mcp_mode（stdio|http）/ engine_url（仅远端）/ token（仅远端；本机不存 token）`。
+4. **本机多智能体**：本机多个 AI 智能体共用引擎时，**每个都必须**在它自己的 MCP 配置里声明唯一 `YOTTA_AGENT_ID`（如 `env: { YOTTA_AGENT_ID: "<该智能体唯一ID>" }`），各自 `whoami` 各回各的、互不撞；本机走 stdio 免 token。
+
+**C. 身份红线（强制）**：
+
+- 智能体 ID **必须全局唯一**；**禁止**「从记忆里读到别人的 ID 就当自己的」（如看到「Kali 智能体 ID 为 dashu」就把自己当 dashu）。
+- 不确定自己的 ID → 先 `whoami` / `agent_info`，再向用户确认；**禁止猜**。
+- 私密记忆（PREF / BOUND / COMMIT）**必须有 owner**：未声明身份写私密会被引擎拒绝（公共 FACT 不受影响）。
+- **禁止直接读写记忆库文件（硬红线）**：一切读写走 `yotta-memory` CLI / MCP 工具（`remember` / `recall` / `search` / `forget` / `archive` / `reindex` / `export` / `import` / `agent_info`）；**禁止用 shell**（`Get-ChildItem` / `Get-Content` / `cat` / `ls` / `type` / `vim` 等）直接读、改、删 `<root>/` 下的记忆文件——否则 `--agent` / `--owner` 的越界拦截形同虚设，会读到别的智能体私密内容。`--agent <其它agent>` 只作身份声明/展示，绝不授予跨智能体私密读取（读他人私密仍需 grant / identity=user / `--unsafe`）。
+
+> 已用 `YOTTA_MEMORY_HOME` 临时覆盖时不必改 config；本步骤是常规 CLI 直连用户级位置的引导。
 
 ## CLI 速查
 
@@ -37,19 +69,34 @@ license: MIT
 |---|---|
 | `yotta-memory init [--project] [--dir <目录>]` | 初始化记忆库（默认用户级；--dir 显式指定位置）|
 | `yotta-memory remember <type> <subject> <statement> [--owner <id>]` | 写入（同 subject+statement 自动更新；--owner 标注归属，默认取 agent id）|
-| `yotta-memory recall [关键词] [--type T] [--limit N] [--agent <id>] [--owner <id>] [--all] [--unsafe]` | 检索（索引+TF 打分，读取分区过滤；越界读其它智能体私密默认拒绝，需 grant / identity=user / `--unsafe`；项目级优先）|
+| `yotta-memory recall [关键词] [--type T] [--limit N] [--agent <id>] [--owner <id>] [--all] [--unsafe]` | 检索（索引+TF 打分，读取分区过滤；越界读其它智能体私密默认拒绝，需 grant / identity=user / `--unsafe`；`--agent <其它>` 只作身份声明/展示，不授予跨读——读他人私密同样要授权；项目级优先）|
 | `yotta-memory forget <文件>` | 删除（按类型目录路径或文件名）|
 | `yotta-memory archive [--days 180] [--threshold 0.4]` | 归档旧记忆（盖棺分+年龄，immutable 除外）|
 | `yotta-memory reindex` | 重建索引（手动改 .md 后校正）|
 | `yotta-memory export [--out f.json]` / `import <f.json>` | 导出 / 导入 |
 | `yotta-memory config set memory_home <目录>` / `config get` | 持久记住 / 查看记忆库位置（`~/.yottamemory/config.json`）|
-| `yotta-memory token new --agent <id>` / `token list` / `token revoke --agent <id>` | 每智能体访问 token：生成 / 列出 / 吊销（登记 `<记忆库>/.server/tokens.json`）|
+| `yotta-memory whoami` | 查看当前智能体身份与登记状态（读 `YOTTA_AGENT_ID` / `X-Agent-Id`，不猜不默认）|
+| `yotta-memory iam <id> [--force]` | 登记本智能体唯一身份并自动落自我档案（`agents.json`，ID 必须唯一）|
+| `yotta-memory token new --agent <id> [--force]` / `token list` / `token revoke --agent <id>` | 每智能体访问 token：生成 / 列出 / 吊销（登记 `<记忆库>/.server/tokens.json`；同 ID 已被其它来源占用需 `--force` 覆盖，防不同智能体合流）|
 | `yotta-memory serve [--host 0.0.0.0] [--port 8787] [--no-auth] [--stdio]` | 启动 MCP 记忆引擎（streamable HTTP 局域网 / --stdio 本地零进程模式；Bearer token + X-Agent-Id 鉴权）|
 | `yotta-memory lan enable [--onstart] / disable / status` | 开机自启管理（Windows 计划任务，默认 ONLOGON 登录自启；--onstart 开机即启需管理员）|
 
 ## 存储格式（摘要）
 
-`<YYYY-MM-DD>-<NNNN>.md`，frontmatter 含 `type / subject / statement / confidence / created / updated / tags / immutable / scope / owner / access_count / last_accessed`；正文为记忆内容。顶层另有 `index.json`（反向索引 + TF 打分）。
+目录结构（v0.5.0 起，私密记忆按 owner 物理分目录）：
+
+```
+<root>/
+├── facts/                    # FACT 事实（公共可共享）
+├── private/<owner>/<type>/   # PREF / BOUND / COMMIT，按智能体隔离
+├── .archive/                 # 归档区
+├── index.json                # 检索索引（tokens = 分词词频，非访问令牌）
+└── agents.json               # 智能体身份登记表（唯一性）
+```
+
+记忆文件 `<YYYY-MM-DD>-<NNNN>.md`，frontmatter 含 `type / subject / statement / confidence / created / updated / tags / immutable / scope / owner / access_count / last_accessed`；正文为记忆内容。旧版根下平铺的 `prefs/` `bounds/` `commits/` 会在 `reindex`（或首次 recall 建索引）时按 frontmatter `owner` 自动迁移到 `private/<owner>/<type>/`。
+
+自我档案（本智能体身份，强制落盘）：PREF，`subject=自我接入档案`，`owner=<本智能体ID>`，statement 为 `; ` 分隔的 key:value——`agent_id / host / memory_home / mcp_mode（stdio|http）/ engine_url（仅远端）/ token（仅远端；本机不存 token）`。
 
 ## 便携记忆盘模式（局域网多机共享）
 

package/USER_GUIDE.md

@@ -0,0 +1,287 @@
+# 元忆（yotta-memory）用户使用手册
+
+> 面向最终用户的操作手册：从安装、初始化，到便携记忆盘（局域网多机共享）的部署与接入。AI 智能体的自动引导流程见 `SKILL.md`。
+
+## 目录
+
+1. 这是什么
+2. 安装
+3. 本机单机使用
+4. 便携记忆盘 · 记忆引擎主机篇（Linux / Windows）
+5. 智能体接入篇（本机 / 局域网其它主机）
+6. CLI 命令速查
+7. 故障排查
+8. 安全与边界
+
+## 1. 这是什么
+
+元忆（yotta-memory）是一个文件式智能体记忆工具：每条记忆是一个 Markdown 文件，放在你自己的目录里，可以用任何编辑器查看、修改，用 git 做版本管理。FACT 记忆共享给所有智能体，PREF / BOUND / COMMIT 记忆按智能体隔离。
+
+- 零依赖：只需要 Node.js，没有数据库、没有常驻服务（除非你开启便携记忆盘模式）。
+- 记忆即文件：数据主权在你手里。
+
+**典型使用场景：**
+
+- **跨会话续接**：AI 开工 `recall` 恢复上次上下文，不丢记忆。
+- **多智能体共享**：FACT 进公共区共享，PREF / BOUND / COMMIT 各自私密隔离。
+- **交接与团队协作**：项目级 `.yottamemory` 随仓库走，交接即恢复。
+- **便携记忆盘**：记忆装在固定主机上，本机与局域网其它主机共享同一份记忆（见第 4 / 5 篇）。
+
+## 2. 安装（CLI + 技能）
+
+使用元忆需要两部分：**CLI**（命令行工具，负责读写记忆）与**技能**（SKILL.md，负责教 AI 智能体怎么用）。先装 CLI，再把技能装进要用的智能体。
+
+**CLI：任选一种方式**
+
+| 方式 | 命令 | 适用 |
+|---|---|---|
+| npm 全局（推荐） | `npm i -g @yottameta/yotta-memory` | 长期使用 |
+| npx 临时 | `npx -y @yottameta/yotta-memory` | 临时试用 |
+| install.sh | `bash <(curl -s https://raw.githubusercontent.com/YottaMeta/yotta-memory/main/install.sh)` | 离线 / 无 npm |
+
+安装后验证：`yotta-memory --version` 能输出版本号即成功。
+
+**技能（SKILL.md）：装进要用的 AI 智能体**
+
+| 方式 | 命令 | 适用 |
+|---|---|---|
+| npx skills（生态标准入口） | `npx skills add YottaMeta/yotta-memory` | 自动检测已装智能体 |
+| 安装器（npm 全局时） | `yotta-memory-install -g` / `yotta-memory-install --agent codex` | 装进所有 / 指定智能体 |
+| 手动 | 把整个 `yotta-memory` 文件夹复制到智能体的 skills 目录 | 离线 |
+
+> CLI 与技能分工不同：CLI 让命令行能读写记忆；技能让 AI 知道「开工 recall 恢复上下文、重要信息 remember 落盘、收工归档」。只装 CLI 不装技能，AI 不会自动使用这套工作流。
+
+**更新：** `npm i -g @yottameta/yotta-memory` 升级 CLI（不带版本号即最新版），再把技能文件夹重新装进智能体（重复执行上面的技能安装命令即可）。
+
+**卸载：** `npm rm -g @yottameta/yotta-memory`，并从智能体的 skills 目录删除整个 `yotta-memory` 文件夹。
+
+## 3. 本机单机使用
+
+```bash
+yotta-memory init                                    # 初始化记忆库（默认 ~/.yottamemory）
+yotta-memory remember FACT 项目 本周完成发布           # 记一条事实
+yotta-memory recall 项目                              # 检索记忆
+yotta-memory config get                              # 查看记忆库位置
+```
+
+- 想换记忆位置：`yotta-memory config set memory_home <目录>`，之后所有命令自动用新位置。
+- 项目级记忆：在项目目录里 `yotta-memory init --project`，该项目的智能体优先读项目级记忆。
+
+### 记忆库位置：本机智能体如何找到记忆
+
+位置解析优先级：`YOTTA_MEMORY_HOME`（环境变量，临时覆盖）> `config.json#memory_home`（`config set memory_home` 持久记住）> 默认 `~/.yottamemory`。
+
+- 本机智能体装好技能后，AI 开工执行 `yotta-memory config get` 即可看到当前生效位置，`recall` 会自动读对位置。
+- 记忆库换位置后，执行一次 `yotta-memory config set memory_home <新目录>` 即可，无需改技能。
+
+### 手动添加 / 编辑记忆
+
+记忆就是文件：读写一律走 `yotta-memory` CLI / MCP 工具，**请勿用 shell（`Get-ChildItem` / `Get-Content` / `cat` / `ls` / `type` 等）直接读改记忆库目录下的文件**——那会绕过 scope/owner 权限边界，可能读到其它智能体的私密内容。确需手改时，请把文件放对分类目录：公共事实放 `facts/`；私密的偏好 / 边界 / 承诺放 `private/<owner>/<type>/`（`<owner>` 用你登记的智能体 ID），frontmatter 至少包含 `type` / `subject` / `statement`：
+
+> 说明：`index.json` 是引擎自动维护的检索索引，其 `tokens` 字段是中文分词的词频表（供 TF 打分），**不是**访问令牌。手动改过 `.md` 后可用 `yotta-memory reindex` 校正索引，无需手动编辑 `index.json`。
+
+```markdown
+---
+type: FACT
+subject: 项目
+statement: 本周完成发布
+---
+本周完成发布
+```
+
+手动改过文件后运行 `yotta-memory reindex` 重建索引，`recall` 才能按索引检索到。整个记忆目录可以用 git 做版本管理与回滚。
+
+## 4. 便携记忆盘 · 记忆引擎主机篇
+
+场景：记忆放在一台主机上（Linux / Windows 均可），本机直接 CLI 读写；局域网内其它主机上的 AI 智能体经 MCP 远程接入。引擎主机只需装 CLI，不需要装任何 AI 智能体。
+
+**本机与局域网可同时用同一个记忆库**：引擎 `serve` 运行期间，本机智能体照常用 CLI（或 stdio MCP）读写（不经网络、不需要 token），局域网其它主机的智能体同时经 MCP + token 接入——两条通道并存、互不干扰。
+
+**第 1 步：安装 CLI**（见第 2 节）。
+
+**第 2 步：指定记忆位置并初始化（或接入现有记忆库）**
+
+```bash
+yotta-memory config set memory_home /srv/yotta-memory   # 改成你的实际目录
+yotta-memory init --dir /srv/yotta-memory               # 新库：初始化（自动建 facts/private/.archive）
+```
+
+如果目标目录**已经是记忆库**（里面有 `facts/` 等子目录或 `index.json`，例如从旧机复制或 git 克隆来的），直接 `config set memory_home <目录>` 接入即可，**不要重复 init**。
+
+**第 3 步：注册开机自启（可选，推荐）**
+
+```bash
+# Windows：内置命令（计划任务）
+yotta-memory lan enable              # 登录后自动启动（默认）
+yotta-memory lan enable --onstart    # 开机即启（需管理员）
+yotta-memory lan status              # 查看状态
+yotta-memory lan disable             # 取消
+
+# Linux：用 systemd 开机自启（lan 命令当前仅支持 Windows）
+# 先查 yotta-memory 实际路径：which yotta-memory（npm 全局默认 /usr/local/bin/yotta-memory）
+sudo tee /etc/systemd/system/yotta-memory.service > /dev/null <<'EOF'
+[Unit]
+Description=yotta-memory memory engine
+After=network.target
+
+[Service]
+ExecStart=/usr/local/bin/yotta-memory serve --host 0.0.0.0 --port 8787
+Restart=on-failure
+
+[Install]
+WantedBy=multi-user.target
+EOF
+sudo systemctl daemon-reload
+sudo systemctl enable --now yotta-memory
+systemctl status yotta-memory        # 查看状态
+```
+
+**第 4 步：为局域网其它主机的智能体生成访问 token**
+
+```bash
+yotta-memory token new --agent 我的智能体ID
+```
+
+命令会打印一次 `ytm_...`，请妥善保管（它就是访问凭证）。多个智能体就重复执行、用不同 ID。**本机上的 AI 智能体不需要 token**（见第 5 篇）。
+
+> token 丢失或要更换：重新执行 `token new --agent <id> --force` 会生成新 token 并覆盖旧的，旧 token 立即失效；不加 `--force` 时若该 ID 已被其它来源占用会被拒绝（每个 AI 的 ID 必须唯一）；`token list` 可查看已登记哪些智能体。
+
+**第 5 步：把连接信息交给远程智能体的用户**
+
+- 引擎地址：`http://<本机IP>:8787/mcp`
+- 该智能体的 token：`ytm_...`
+- 智能体 ID（对应 X-Agent-Id 请求头）
+
+查本机 IP：Linux 运行 `hostname -I`（或 `ip a`）；Windows 运行 `ipconfig` 找「IPv4 地址」。防火墙：Linux 若启用了 ufw，执行 `sudo ufw allow 8787/tcp`；Windows 首次监听时允许放行。否则局域网其它主机连不进来。
+
+**第 6 步：备份与迁移**
+
+- 备份 = 复制整个记忆目录（`facts/` `private/` `.archive/` + `index.json` + `agents.json` + `.server/`），复制到哪、哪就是记忆库；迁移同理，整个目录拷走即可。
+- `export` / `import` 是把记忆导出成单个 JSON 或从 JSON 导入，适合跨工具交换或归档，不是日常备份的必需步骤。
+
+## 5. 智能体接入篇（本机 / 局域网其它主机）
+
+接入智能体分两类：引擎主机本机的智能体、局域网其它主机上的智能体。本机不需要 token、不依赖远程服务；其它主机经 MCP + token 接入。
+
+### 5.1 本机 AI 智能体（引擎主机本机）
+
+**方式一（推荐，最简单）：让智能体直接调用 CLI。**
+
+```bash
+yotta-memory recall <关键词>            # 智能体开工恢复上下文
+yotta-memory remember FACT 主题 内容    # 智能体落盘
+```
+
+智能体装上技能后（`SKILL.md`）会自动学会这套工作流，无需任何 MCP 配置。
+
+**方式二：stdio MCP（零常驻进程，智能体按需拉起 CLI）。** 在智能体 MCP 配置里加：
+
+```json
+{
+  "mcpServers": {
+    "yotta-memory": {
+      "command": "yotta-memory",
+      "args": ["serve", "--stdio"],
+      "env": { "YOTTA_AGENT_ID": "<该智能体唯一ID>" }
+    }
+  }
+}
+```
+
+本机接入不需要 token，也不需要启动 HTTP 服务；但**必须在配置里声明唯一的 `YOTTA_AGENT_ID`**（见下），否则写私密记忆会被拒。
+
+**本机智能体装好技能后如何获取记忆存放位置？** 按优先级：`YOTTA_MEMORY_HOME` 环境变量 > `config set memory_home` 持久化的 `~/.yottamemory/config.json` > 默认 `~/.yottamemory`。AI 开工执行 `yotta-memory config get` 查看当前生效位置；记忆库移动后执行一次 `config set memory_home <新目录>` 即可。
+
+**给本机智能体设置唯一身份（强制）**：私密记忆（PREF / BOUND / COMMIT）按 owner 物理分目录隔离（存于 `private/<owner>/<type>/`），owner 取当前智能体的 agent ID。流程如下：
+
+1. 开工先 `yotta-memory whoami` 确认「我是谁」。
+2. 未登记 → 向用户确认一个**全局唯一** ID（建议 `<主机名>-<角色>`，别用 `dashu` / `codex` 这类易撞名），执行 `yotta-memory iam <id>`：引擎**强制唯一性**（被其它主机 / 来源占用会拒绝），并自动落一条「自我接入档案」PREF（owner=自己）。
+3. 本机多个 AI 智能体共用引擎时，**每个都要在它自己的 MCP 配置里声明唯一 `YOTTA_AGENT_ID`**（CLI 直连则每次带 `--agent <id>`），各自 `whoami` 各回各的、互不撞。
+4. **禁止**从记忆里读到别人的 ID 就当自己的（比如看到「Kali 智能体 ID 为 dashu」就把自己当 dashu）；不确定先 `whoami` 再问用户，**禁止猜**。
+5. **不设则 owner 为空**：写私密记忆会被引擎拒绝（公共 FACT 不受影响），避免私密隔离退化。
+
+### 5.2 局域网其它主机的 AI 智能体
+
+**第 1 步：向记忆引擎主机获取**：引擎 IP、端口（默认 8787）、本智能体的 token、智能体 ID。
+
+**第 2 步：配置 MCP**（可以让 AI 按 `SKILL.md` 引导自动完成；也可以手动在你的智能体 MCP 配置里加这段）：
+
+```json
+{
+  "mcpServers": {
+    "yotta-memory": {
+      "url": "http://<引擎主机IP>:8787/mcp",
+      "headers": {
+        "Authorization": "Bearer <TOKEN>",
+        "X-Agent-Id": "<本智能体ID>"
+      }
+    }
+  }
+}
+```
+
+**第 3 步：验证**：让 AI 调一次 `recall` / `search`，能读到记忆即连接成功。
+
+**第 4 步：复用**：连接成功后就一直复用；token 失效（被吊销）时回到第 1 步重新获取。
+
+**身份确认与自我档案（强制）**：先调一次 MCP 工具 `agent_info` 确认「我是谁」（读 X-Agent-Id 声明 + 登记状态）。随后用 `remember` 写一条 `subject=自我接入档案` 的 PREF（owner=自己），body 为 `; ` 分隔的 key:value——`agent_id / host / memory_home / mcp_mode: http / engine_url / token`，把接入信息存进自己的永久记忆；下次会话 `recall "自我接入档案"` 直接找回。
+
+## 6. CLI 命令速查
+
+| 命令 | 作用 |
+|---|---|
+| `yotta-memory init [--project] [--dir <目录>]` | 初始化记忆库 |
+| `yotta-memory remember <类型> <主题> <内容> [--owner <id>]` | 写入记忆 |
+| `yotta-memory recall [关键词] [--type T] [--limit N] [--agent <id>] [--owner <id>] [--all] [--unsafe]` | 检索记忆（读取分区过滤；`--agent <其它>` 仅作身份声明、不授予跨读；越界读其它智能体私密默认拒绝，需 grant / identity=user / `--unsafe`）|
+| `yotta-memory forget <文件>` | 删除一条记忆 |
+| `yotta-memory archive [--days 180] [--threshold 0.4]` | 归档旧记忆 |
+| `yotta-memory reindex` | 重建索引 |
+| `yotta-memory export [--out 文件.json]` / `import <文件.json>` | 导出 / 导入 |
+| `yotta-memory config set memory_home <目录>` / `config get` | 记忆库位置 |
+| `yotta-memory whoami` | 查看当前智能体身份与登记状态（读 `YOTTA_AGENT_ID` / `X-Agent-Id`，不猜不默认）|
+| `yotta-memory iam <id> [--force]` | 登记本智能体唯一身份并自动落自我档案（`agents.json`，ID 必须唯一）|
+| `yotta-memory token new --agent <id> [--force]` / `token list` / `token revoke --agent <id>` | 访问 token（同 ID 已被其它来源占用需 `--force` 覆盖）|
+| `yotta-memory serve [--port 8787] [--stdio] [--no-auth]` | 启动记忆引擎（--no-auth 关闭鉴权，仅限可信内网）|
+| `yotta-memory lan enable [--onstart] / disable / status` | 开机自启管理 |
+
+类型：`FACT`（事实，共享）/ `PREF`（偏好）/ `BOUND`（边界）/ `COMMIT`（承诺），后三类按智能体物理分目录隔离（`private/<owner>/<type>/`）。
+
+## 7. 故障排查
+
+**远程连不上时，按顺序检查：**
+
+1. 引擎在运行吗？Windows：`yotta-memory lan status`；Linux（systemd 自启时）：`systemctl status yotta-memory`，或 `ps aux | grep yotta-memory`；也可直接 `yotta-memory --version`。
+2. IP 对吗？引擎主机执行 `hostname -I`（Linux）或 `ipconfig`（Windows）确认。
+3. 端口对吗？默认 8787，两端要一致。
+4. 防火墙放行了吗？Linux：`sudo ufw status`，未放行则 `sudo ufw allow 8787/tcp`；Windows：允许首次监听的入站请求。
+5. token 有效吗？记忆盘主机执行 `yotta-memory token list` 看该智能体是否登记；无效就 `token new --agent <id>` 重新生成。
+6. 网络通吗？任意一台主机执行 `curl http://<引擎IP>:8787/mcp`：
+   - 返回 401：服务在运行，是鉴权问题（token / 请求头不对）。
+   - 连接被拒 / 超时：服务没启动，或防火墙拦截。
+
+**`lan enable` 失败提示 Access denied：** 需要管理员权限，请用管理员终端重新执行；`--onstart` 模式必须管理员。
+
+**启动引擎报端口被占用（EADDRINUSE）：** 用 `--port <其它端口>` 换端口启动，两端保持一致；或先查占用：Linux `ss -tlnp | grep 8787`，Windows `netstat -ano | findstr 8787`。
+
+**recall 没有结果：** 关键词太细或确实没有这条记忆；先 `recall`（不带关键词）看库里的全部记忆核对。
+
+**systemd 自启的引擎看日志：** `journalctl -u yotta-memory -n 50`。
+
+**记错位置了？** `yotta-memory config get` 查看当前生效位置；`config set memory_home <正确目录>` 改正。
+
+## 8. 安全与边界
+
+- token 等同密码：只给需要接入的智能体，别外传。
+- 元忆不做加密：PREF / BOUND / COMMIT 私密记忆的隔离是「权限边界」机制（谁该读由 scope/owner 决定），属于纪律层保护，不是机密数据保护层。
+- 记忆读写一律走 CLI / MCP；禁止用 shell（`Get-ChildItem` / `cat` / `ls` / `type` 等）直接读改记忆库目录下的文件——否则会绕过 scope/owner 权限边界。
+- 管理动作（init / config / token / lan / serve）不通过 MCP 暴露，远程只能读写记忆，不能改配置、不能管 token。
+- `--no-auth` 会关闭鉴权，仅限可信内网使用。
+- 数据主权在用户：所有数据都是本地明文文件，随时可看、可改、可删。
+
+**确实需要读取其它智能体的私密记忆时（三种授权方式，满足任一即可）：**
+
+1. 显式授权 `grants.json`：在记忆库根目录写 `{"<你的agentID>": ["<对方agentID>"]}`；
+2. identity=user：以 `--agent user` / `--owner user` / 环境变量 `YOTTA_AGENT_ID=user` 读取；
+3. 显式放行 `--unsafe`：用户明确同意时使用。
+
+**协作纪律**：FACT 写入公共区共享；PREF / BOUND / COMMIT 只写自己的私密区；不主动读取其它智能体的私密记忆。

package/bin/yotta-memory.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 // yotta-memory（元忆）: 有权限边界的文件式智能体记忆 CLI（零依赖）
 // v0.4.0 新增：lan（Windows 计划任务开机自启 serve）/ init --dir（显式指定位置）/ serve --stdio（本地零进程模式）/ MCP 工具补 reindex/export/import
+// v0.5.0 新增：隐私硬隔离——私密物理分目录 private/<agent_id>/{prefs,bounds,commits}/ + 关闭 --agent 越权读 + 私密写跨智能体需 --unsafe + 禁 shell 直读写（文档红线）
+// v0.4.2 新增：iam/whoami 智能体身份自注册（agents.json 唯一性）+ 自我档案 PREF + 私密记忆须声明 owner
 'use strict';
 
 const fs = require('fs');
@@ -10,9 +12,12 @@ const crypto = require('crypto');
 const http = require('http');
 const child_process = require('child_process');
 
-const VERSION = '0.4.0';
+const VERSION = '0.5.0';
 const TYPES = ['FACT', 'PREF', 'BOUND', 'COMMIT'];
 const TYPE_DIRS = { FACT: 'facts', PREF: 'prefs', BOUND: 'bounds', COMMIT: 'commits' };
+const PUBLIC_DIR = 'facts';
+const PRIVATE_DIR = 'private';
+const PRIVATE_LEAF = ['prefs', 'bounds', 'commits'];
 const ARCHIVE_DIR = '.archive';
 const INDEX_FILE = 'index.json';
 const PRIVATE_TYPES = ['PREF', 'BOUND', 'COMMIT'];
@@ -20,6 +25,7 @@ const FIELD_ORDER = ['type', 'subject', 'statement', 'confidence', 'created', 'u
 const CONFIG_FILE = 'config.json';
 const SERVER_SUBDIR = '.server';
 const TOKENS_FILE = 'tokens.json';
+const AGENTS_FILE = 'agents.json';
 
 // ---- 全局配置（记忆库位置持久化，固定 ~/.yottamemory/config.json）----
 function configPath() {
@@ -57,6 +63,14 @@ function typeDir(type) {
   }
   return TYPE_DIRS[t];
 }
+function privateIdDir(root, id) { return path.join(root, PRIVATE_DIR, id); }
+// 布局：FACT -> <root>/facts；PREF/BOUND/COMMIT -> <root>/private/<owner>/<type>
+function typeSubdir(type, owner) {
+  const t = String(type).toUpperCase();
+  if (t === 'FACT') return PUBLIC_DIR;
+  const id = owner || '';
+  return path.join(PRIVATE_DIR, id, TYPE_DIRS[t]);
+}
 function defaultScope(type) {
   return PRIVATE_TYPES.indexOf(String(type).toUpperCase()) === -1 ? 'public' : 'private';
 }
@@ -123,14 +137,12 @@ function frontmatterToText(meta, body) {
   return lines.join('\n') + String(b).replace(/^\n+/, '') + '\n';
 }
 function ensureInit(root) {
-  fs.mkdirSync(path.join(root, 'facts'), { recursive: true });
-  fs.mkdirSync(path.join(root, 'prefs'), { recursive: true });
-  fs.mkdirSync(path.join(root, 'bounds'), { recursive: true });
-  fs.mkdirSync(path.join(root, 'commits'), { recursive: true });
+  fs.mkdirSync(path.join(root, PUBLIC_DIR), { recursive: true });
+  fs.mkdirSync(path.join(root, PRIVATE_DIR), { recursive: true });
   fs.mkdirSync(path.join(root, ARCHIVE_DIR), { recursive: true });
   const readme = path.join(root, 'README.md');
   if (!fs.existsSync(readme)) {
-    fs.writeFileSync(readme, '# yotta-memory（元忆）记忆库\n\n有权限边界的文件式智能体记忆存储目录。结构：facts/ prefs/ bounds/ commits/ .archive/。\n', 'utf8');
+    fs.writeFileSync(readme, '# yotta-memory（元忆）记忆库\n\n有权限边界的文件式智能体记忆存储目录。结构：facts/（公共 FACT） private/<agent_id>/{prefs,bounds,commits}/（各智能体私密，物理隔离） .archive/（归档）。\n', 'utf8');
   }
 }
 function nextSeq(dir) {
@@ -160,17 +172,54 @@ function saveIndex(root, entries) {
   const clean = entries.map(function (e) { const c = Object.assign({}, e); delete c.meta; return c; });
   fs.writeFileSync(indexPath(root), JSON.stringify({ version: 2, updated: today(), entries: clean }, null, 2), 'utf8');
 }
-function buildIndex(root) {
-  const entries = [];
-  for (const t of Object.keys(TYPE_DIRS)) {
-    const dir = path.join(root, TYPE_DIRS[t]);
+function collectEntryFiles(root) {
+  const dirs = [];
+  const facts = path.join(root, PUBLIC_DIR);
+  if (fs.existsSync(facts)) dirs.push(path.join(root, PUBLIC_DIR));
+  const pdir = path.join(root, PRIVATE_DIR);
+  if (fs.existsSync(pdir)) {
+    for (const id of fs.readdirSync(pdir)) {
+      const idDir = path.join(pdir, id);
+      if (!fs.statSync(idDir).isDirectory()) continue;
+      for (const t of PRIVATE_LEAF) {
+        const d = path.join(idDir, t);
+        if (fs.existsSync(d)) dirs.push(d);
+      }
+    }
+  }
+  const out = [];
+  for (const dir of dirs) {
+    for (const f of fs.readdirSync(dir)) {
+      const fp = path.join(dir, f);
+      if (fs.statSync(fp).isFile()) out.push(fp);
+    }
+  }
+  return out;
+}
+// 迁移：把根下旧平铺 prefs|bounds|commits/*.md 按 frontmatter owner 迁入 private/<owner>/<type>/
+function migrateLayout(root) {
+  let moved = 0;
+  for (const t of PRIVATE_LEAF) {
+    const dir = path.join(root, t);
     if (!fs.existsSync(dir)) continue;
     for (const f of fs.readdirSync(dir)) {
       const fp = path.join(dir, f);
       if (!fs.statSync(fp).isFile()) continue;
-      entries.push(readEntry(fp, root));
+      const meta = parseFrontmatter(fs.readFileSync(fp, 'utf8')).meta;
+      const owner = meta.owner || '';
+      if (!owner) continue;
+      const target = path.join(root, PRIVATE_DIR, owner, t, f);
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.renameSync(fp, target);
+      moved++;
     }
   }
+  return moved;
+}
+function buildIndex(root) {
+  migrateLayout(root);
+  const entries = [];
+  for (const fp of collectEntryFiles(root)) entries.push(readEntry(fp, root));
   saveIndex(root, entries);
   return entries;
 }
@@ -282,14 +331,15 @@ function hasGrant(userAgent, ownerAgent) {
   return false;
 }
 // 三态读取判定：'read' | 'denied'
-function classifyRead(entry, agent, ownerFilter, unsafe) {
+// selfAgent 为可信身份（env 声明 / 调用方上下文）；--agent 仅供授权与展示，不得授予跨智能体私密读取。
+function classifyRead(entry, agent, ownerFilter, unsafe, selfAgent) {
   if (entry.scope === 'public') return 'read';
   const owner = entry.owner || '';
   if (!owner) return 'read';
-  if (agent && owner === agent) return 'read';
-  if (ownerFilter && owner === ownerFilter && agent && ownerFilter === agent) return 'read';
-  if (unsafe || String(ownerFilter).toLowerCase() === 'user' || String(agent && '' + agent).toLowerCase() === 'user') return 'read';
-  if (hasGrant(agent, owner)) return 'read';
+  const own = selfAgent || agent;
+  if (own && owner === own) return 'read';
+  if (unsafe || String(ownerFilter).toLowerCase() === 'user' || String(agent || '').toLowerCase() === 'user') return 'read';
+  if (hasGrant(agent || selfAgent, owner)) return 'read';
   return 'denied';
 }
 
@@ -300,17 +350,26 @@ function initCore(opts) {
   return { error: false, text: '已初始化记忆库: ' + root };
 }
 function rememberCore(type, subject, statement, opts) {
+  opts = opts || {};
   const root = userRoot();
   ensureInit(root);
   const t = String(type).toUpperCase();
   if (!TYPE_DIRS[t]) return { error: true, text: '未知记忆类型: ' + type + '（可用: ' + TYPES.join(' / ') + '）' };
-  const dir = path.join(root, TYPE_DIRS[t]);
   const stmt = String(statement || '').trim();
   const subj = String(subject || '').trim();
   if (!stmt) return { error: true, text: 'statement 不能为空' };
   if (!subj) return { error: true, text: 'subject 不能为空' };
-  const owner = opts.owner || currentAgent();
+  const selfAgent = opts.selfAgent || currentAgent();
+  const owner = opts.owner || selfAgent;
   const scope = opts.scope || defaultScope(t);
+  if (scope === 'private' && !owner) {
+    return { error: true, text: '私密记忆必须声明归属智能体：请设环境变量 YOTTA_AGENT_ID（或 AGENT_ID）、传 --owner <id>，或先 yotta-memory whoami / iam 登记唯一身份。公共记忆(FACT)不受影响。' };
+  }
+  if (scope === 'private' && owner && selfAgent && owner !== selfAgent && !opts.unsafe) {
+    return { error: true, text: '拒绝: 当前声明身份 ' + selfAgent + ' 不能写入其它智能体 ' + owner + ' 的私密区。请用 YOTTA_AGENT_ID 声明自己的身份，或加 --unsafe（用户显式授权）。' };
+  }
+  const dir = path.join(root, typeSubdir(t, owner));
+  fs.mkdirSync(dir, { recursive: true });
   if (fs.existsSync(dir)) {
     for (const f of fs.readdirSync(dir)) {
       const fp = path.join(dir, f);
@@ -345,17 +404,19 @@ function recallCore(query, opts) {
   const limit = opts.limit || 50;
   const onlyType = opts.type ? String(opts.type).toUpperCase() : null;
   const q = query ? String(query).toLowerCase() : '';
-  const agent = opts.agent || currentAgent();
+  const selfAgent = currentAgent();
+  const agent = opts.agent || selfAgent;
   const ownerFilter = opts.owner || '';
   const allSafe = !!opts.unsafe;
-  const explicitCross = !!opts.all || (!!ownerFilter && ownerFilter.toLowerCase() !== 'user' && ownerFilter !== agent);
+  const impersonation = !!(opts.agent && selfAgent && opts.agent !== selfAgent);
+  const explicitCross = !!opts.all || impersonation || (!!ownerFilter && ownerFilter.toLowerCase() !== 'user' && ownerFilter !== agent);
   const hits = [];
   let deniedCount = 0;
   for (const root of roots) {
     const entries = ensureIndex(root);
     for (const e of entries) {
       if (onlyType && e.type !== onlyType) continue;
-      const r = classifyRead(e, agent, ownerFilter, allSafe);
+      const r = classifyRead(e, agent, ownerFilter, allSafe, selfAgent);
       if (r === 'denied') { deniedCount++; continue; }
       let score = 0;
       if (q) {
@@ -403,38 +464,38 @@ function recallCore(query, opts) {
   }
   return { error: false, exitCode: 0, text: lines.join('\n') };
 }
-function forgetCore(fileRef) {
+function resolveMemoryFile(root, ref) {
+  const map = {};
+  for (const fp of collectEntryFiles(root)) {
+    const rel = path.relative(root, fp).replace(/\\/g, '/');
+    map[rel] = fp;
+    const base = path.basename(rel);
+    if (!map[base]) map[base] = fp;
+  }
+  if (map[ref]) return { fp: map[ref], rel: relOf(root, map[ref]) };
+  const base = path.basename(ref.replace(/\\/g, '/'));
+  if (map[base]) return { fp: map[base], rel: relOf(root, map[base]) };
+  return null;
+}
+function relOf(root, fp) { return path.relative(root, fp).replace(/\\/g, '/'); }
+function forgetCore(fileRef, opts) {
+  opts = opts || {};
+  const selfAgent = opts.selfAgent || currentAgent();
   const roots = [projectRoot(), userRoot()].filter(function (r) { return fs.existsSync(r); });
   const ref = String(fileRef || '').replace(/\\/g, '/');
-  const slash = ref.indexOf('/');
-  const dynTypeDir = slash === -1 ? '' : ref.slice(0, slash);
-  const dynBase = slash === -1 ? ref : ref.slice(slash + 1);
   let target = null, targetRoot = null, targetRel = null;
   for (const root of roots) {
-    if (dynTypeDir) {
-      const dir = path.join(root, dynTypeDir);
-      if (!fs.existsSync(dir)) continue;
-      const cand = path.join(dir, dynBase);
-      if (fs.existsSync(cand)) {
-        target = cand; targetRoot = root;
-        targetRel = dynTypeDir + '/' + path.basename(dynBase);
-        break;
-      }
-      continue;
-    }
-    for (const t of Object.keys(TYPE_DIRS)) {
-      const dir = path.join(root, TYPE_DIRS[t]);
-      if (!fs.existsSync(dir)) continue;
-      const cand = path.join(dir, dynBase);
-      if (fs.existsSync(cand)) {
-        target = cand; targetRoot = root;
-        targetRel = TYPE_DIRS[t] + '/' + path.basename(dynBase);
-        break;
-      }
-    }
-    if (target) break;
+    const found = resolveMemoryFile(root, ref);
+    if (found) { target = found.fp; targetRoot = root; targetRel = found.rel; break; }
   }
   if (!target) return { error: true, text: '未找到记忆文件: ' + fileRef };
+  const seg = targetRel.replace(/\\/g, '/').split('/');
+  if (seg[0] === 'private') {
+    const owner = seg[1] || '';
+    if (!opts.unsafe && (owner && (selfAgent ? owner !== selfAgent : true))) {
+      return { error: true, text: '拒绝: 不能删除其它智能体 ' + owner + ' 的私密记忆（当前身份 ' + (selfAgent || '未声明') + '）。请用 YOTTA_AGENT_ID 声明自己的身份，或加 --unsafe（用户显式授权）。' };
+    }
+  }
   fs.unlinkSync(target);
   if (targetRoot) removeIndexEntry(targetRoot, targetRel);
   return { error: false, text: '已删除: ' + target };
@@ -447,24 +508,20 @@ function archiveCore(opts) {
   const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
   let moved = 0;
   const movedFiles = [];
-  for (const t of Object.keys(TYPE_DIRS)) {
-    const dir = path.join(root, TYPE_DIRS[t]);
-    if (!fs.existsSync(dir)) continue;
-    for (const f of fs.readdirSync(dir)) {
-      const fp = path.join(dir, f);
-      if (!fs.statSync(fp).isFile()) continue;
-      const meta = parseFrontmatter(fs.readFileSync(fp, 'utf8')).meta;
-      if (meta.immutable === 'true') continue;
-      if (!meta.created) continue;
-      const createdTs = new Date(meta.created).getTime();
-      if (isNaN(createdTs)) continue;
-      if (vitality(meta) < threshold && createdTs < cutoff) {
-        const destDir = path.join(root, ARCHIVE_DIR, TYPE_DIRS[t]);
-        fs.mkdirSync(destDir, { recursive: true });
-        fs.renameSync(fp, path.join(destDir, f));
-        movedFiles.push(TYPE_DIRS[t] + '/' + f);
-        moved++;
-      }
+  for (const fp of collectEntryFiles(root)) {
+    const meta = parseFrontmatter(fs.readFileSync(fp, 'utf8')).meta;
+    if (meta.immutable === 'true') continue;
+    if (!meta.created) continue;
+    const createdTs = new Date(meta.created).getTime();
+    if (isNaN(createdTs)) continue;
+    const t = (meta.type || 'FACT').toUpperCase();
+    if (vitality(meta) < threshold && createdTs < cutoff) {
+      const destDir = path.join(root, ARCHIVE_DIR, TYPE_DIRS[t]);
+      fs.mkdirSync(destDir, { recursive: true });
+      fs.renameSync(fp, path.join(destDir, path.basename(fp)));
+      const rel = relOf(root, fp);
+      movedFiles.push(rel);
+      moved++;
     }
   }
   if (movedFiles.length) removeIndexEntries(root, movedFiles);
@@ -505,15 +562,9 @@ function cmdReindex() {
 }
 function collectAll(root) {
   const out = [];
-  for (const t of Object.keys(TYPE_DIRS)) {
-    const dir = path.join(root, TYPE_DIRS[t]);
-    if (!fs.existsSync(dir)) continue;
-    for (const f of fs.readdirSync(dir)) {
-      const fp = path.join(dir, f);
-      if (!fs.statSync(fp).isFile()) continue;
-      const e = readEntry(fp, root);
-      out.push({ file: e.file, meta: e.meta });
-    }
+  for (const fp of collectEntryFiles(root)) {
+    const e = readEntry(fp, root);
+    out.push({ file: e.file, meta: e.meta });
   }
   return out;
 }
@@ -541,7 +592,8 @@ function importCore(root, src) {
     const meta = item.meta || {};
     const t = (meta.type || 'FACT').toUpperCase();
     if (!TYPE_DIRS[t]) continue;
-    const dir = path.join(root, TYPE_DIRS[t]);
+    const dir = path.join(root, typeSubdir(t, meta.owner || ''));
+    fs.mkdirSync(dir, { recursive: true });
     let seq = nextSeq(dir);
     let file = path.join(dir, today() + '-' + seq + '.md');
     while (fs.existsSync(file)) { seq = String(parseInt(seq, 10) + 1).padStart(4, '0'); file = path.join(dir, today() + '-' + seq + '.md'); }
@@ -586,13 +638,18 @@ function saveTokens(root, data) {
   fs.writeFileSync(tokensPath(root), JSON.stringify(data, null, 2), 'utf8');
   try { fs.chmodSync(tokensPath(root), 0o600); } catch (e) {}
 }
-function cmdTokenNew(agentId) {
+function cmdTokenNew(agentId, opts) {
   const root = userRoot();
   ensureInit(root);
   if (!agentId) { console.error('请指定 --agent <id>'); process.exit(2); }
   const data = loadTokens(root);
   data.version = 1;
   data.tokens = data.tokens || {};
+  const conflict = identityConflict(root, agentId);
+  if (conflict && !opts.force) {
+    console.error("错误: 智能体 ID '" + agentId + "' " + conflict + '。每个 AI 智能体的 ID 必须唯一；确认是同一智能体后加 --force 覆盖。');
+    process.exit(2);
+  }
   const token = 'ytm_' + crypto.randomBytes(16).toString('hex');
   data.tokens[agentId] = { token: token, created: today() };
   saveTokens(root, data);
@@ -616,6 +673,106 @@ function cmdTokenRevoke(agentId) {
   else { console.log('未找到已登记智能体: ' + agentId); }
 }
 
+
+// ---- 智能体身份登记（agents.json）+ 自我档案 ----
+function agentsPath(root) { return path.join(root, AGENTS_FILE); }
+function loadAgents(root) {
+  try { return JSON.parse(fs.readFileSync(agentsPath(root), 'utf8')) || {}; } catch (e) { return {}; }
+}
+function saveAgents(root, data) {
+  fs.mkdirSync(root, { recursive: true });
+  fs.writeFileSync(agentsPath(root), JSON.stringify(data, null, 2), 'utf8');
+}
+const SELF_PROFILE_SUBJECT = '自我接入档案';
+function selfPrefsDir(root, agentId) { return path.join(root, PRIVATE_DIR, agentId, 'prefs'); }
+function findSelfProfile(root, agentId) {
+  const dir = selfPrefsDir(root, agentId);
+  if (!fs.existsSync(dir)) return '';
+  for (const f of fs.readdirSync(dir)) {
+    const fp = path.join(dir, f);
+    if (!fs.statSync(fp).isFile()) continue;
+    const meta = parseFrontmatter(fs.readFileSync(fp, 'utf8')).meta;
+    if (meta.subject === SELF_PROFILE_SUBJECT && (meta.owner || '') === agentId) return f;
+  }
+  return '';
+}
+function selfProfileBody(agentId, root, extra) {
+  const lines = [];
+  lines.push('agent_id: ' + agentId);
+  lines.push('host: ' + os.hostname());
+  lines.push('memory_home: ' + root);
+  lines.push('mcp_mode: ' + (extra.mcpMode || 'stdio'));
+  if (extra.engineUrl) lines.push('engine_url: ' + extra.engineUrl);
+  if (extra.token) lines.push('token: ' + extra.token);
+  return lines.join('; ');
+}
+function writeSelfProfile(root, agentId, extra) {
+  const dir = selfPrefsDir(root, agentId);
+  fs.mkdirSync(dir, { recursive: true });
+  const seq = nextSeq(dir);
+  const file = path.join(dir, today() + '-' + seq + '.md');
+  const body = selfProfileBody(agentId, root, extra || {});
+  const rec = {
+    type: 'PREF', subject: SELF_PROFILE_SUBJECT, statement: body,
+    confidence: 1.0, created: today(), updated: today(),
+    tags: ['自我档案'], immutable: false,
+    scope: 'private', owner: agentId, access_count: 0, last_accessed: '',
+  };
+  fs.writeFileSync(file, frontmatterToText(rec, body), 'utf8');
+  upsertIndexEntry(root, readEntry(file, root));
+  return file;
+}
+function identityConflict(root, agentId) {
+  const agents = loadAgents(root).agents || {};
+  const tokens = loadTokens(root).tokens || {};
+  const host = os.hostname();
+  const a = agents[agentId];
+  if (a && a.host && a.host !== host) return '已被智能体身份登记占用（host=' + a.host + '）';
+  if (tokens[agentId]) return '已被远端 token 登记占用（.server/tokens.json）';
+  return '';
+}
+function cmdIam(agentId, opts) {
+  const root = userRoot();
+  ensureInit(root);
+  if (!agentId) { console.error('请指定 <id>：yotta-memory iam <id> [--force]'); process.exit(2); }
+  const conflict = identityConflict(root, agentId);
+  if (conflict && !opts.force) {
+    console.error("错误: ID '" + agentId + "' " + conflict + '。每个 AI 智能体的 ID 必须唯一。请换一个唯一 ID，或确认是同一智能体后加 --force 覆盖。');
+    process.exit(2);
+  }
+  const data = loadAgents(root);
+  data.version = 1;
+  data.agents = data.agents || {};
+  const host = os.hostname();
+  const existed = data.agents[agentId];
+  data.agents[agentId] = { host: host, created: (existed && existed.created) || today() };
+  saveAgents(root, data);
+  const file = writeSelfProfile(root, agentId, { mcpMode: 'stdio' });
+  console.log('已登记智能体身份: ' + agentId + '（host=' + host + '，' + (conflict ? '--force 覆盖' : '新建') + '）');
+  console.log('已写入自我档案: ' + file);
+  console.log('本机免 token：以后用 whoami 确认身份；远端接入需 token new --agent ' + agentId);
+}
+function cmdWhoami() {
+  const root = userRoot();
+  const id = currentAgent();
+  if (!id) {
+    console.log('当前未声明智能体身份（YOTTA_AGENT_ID / AGENT_ID 未设置，也未传 --agent）。');
+    console.log('本机：请在该智能体的 MCP 配置 env 设 YOTTA_AGENT_ID=<唯一ID>，然后 yotta-memory iam <id> 登记；或 CLI 每次带 --agent <id> / --owner <id>。');
+    console.log('远端：X-Agent-Id 请求头 + token（token new --agent <id>）。');
+    return;
+  }
+  const agents = loadAgents(root).agents || {};
+  const tokens = loadTokens(root).tokens || {};
+  let reg = '未登记';
+  if (agents[id]) reg = 'agents.json 已登记（host=' + agents[id].host + '）';
+  else if (tokens[id]) reg = 'tokens.json 已登记（远端）';
+  const profile = findSelfProfile(root, id);
+  console.log('当前智能体身份: ' + id);
+  console.log('登记状态: ' + reg);
+  console.log('自我档案: ' + (profile ? profile : '未写入（请执行 yotta-memory iam ' + id + '）'));
+  if (!agents[id] && !tokens[id]) console.log('提示: 请先 yotta-memory iam ' + id + ' 登记唯一身份并落自我档案，再写私密记忆。');
+}
+
 // ---- config 命令 ----
 function cmdConfigSet(key, value) {
   if (key !== 'memory_home') { console.error('未知配置项: ' + key + '（可用: memory_home）'); process.exit(2); }
@@ -643,13 +800,16 @@ function mcpTools() {
     { name: 'reindex', description: '重建索引（手动改 .md 后校正；扫描 facts/prefs/bounds/commits 四目录）', inputSchema: { type: 'object', properties: {} } },
     { name: 'export', description: '导出全部记忆到引擎主机上的 JSON 文件。out 可选（默认 <记忆库>/yottamemory-export-<日期>.json）', inputSchema: { type: 'object', properties: { out: { type: 'string' } } } },
     { name: 'import', description: '从引擎主机上的 JSON 文件导入记忆。src 为文件路径（可绝对路径，或相对记忆库目录）', inputSchema: { type: 'object', properties: { src: { type: 'string' } }, required: ['src'] } },
+    { name: 'agent_info', description: '查看当前智能体身份与登记状态（远端读经 token 校验的 X-Agent-Id；本机读 YOTTA_AGENT_ID）。开工先确认「我是谁」，禁止从记忆里抄别人的 ID', inputSchema: { type: 'object', properties: {} } },
   ];
 }
 function callTool(name, args, ctx) {
   const agent = ctx.agent || '';
   try {
     if (name === 'remember') {
-      const r = rememberCore(String(args.type || ''), String(args.subject || ''), String(args.statement || ''), { owner: args.owner || agent });
+      const ownerArg = args.owner ? String(args.owner) : '';
+      if (ownerArg && ownerArg !== agent) return { text: '拒绝: MCP 写入的 owner 必须等于当前智能体身份（' + agent + '），不能写其它智能体私密区。', error: true };
+      const r = rememberCore(String(args.type || ''), String(args.subject || ''), String(args.statement || ''), { owner: agent, selfAgent: agent });
       return { text: r.text, error: r.error };
     }
     if (name === 'recall' || name === 'search') {
@@ -657,7 +817,7 @@ function callTool(name, args, ctx) {
       return { text: r.text, error: r.error };
     }
     if (name === 'forget') {
-      const r = forgetCore(String(args.file || ''));
+      const r = forgetCore(String(args.file || ''), { selfAgent: agent });
       return { text: r.text, error: r.error };
     }
     if (name === 'archive') {
@@ -678,6 +838,18 @@ function callTool(name, args, ctx) {
       const r = importCore(userRoot(), String(args.src || ''));
       return { text: r.text, error: r.error };
     }
+    if (name === 'agent_info') {
+      const root = userRoot();
+      const id = agent || '';
+      if (!id) return { text: '当前未声明智能体身份（无 X-Agent-Id / YOTTA_AGENT_ID）。本机请在 MCP 配置 env 设 YOTTA_AGENT_ID=<唯一ID> 并 iam 登记。', error: false };
+      const agents = loadAgents(root).agents || {};
+      const tokens = loadTokens(root).tokens || {};
+      let reg = '未登记';
+      if (agents[id]) reg = 'agents.json 已登记（host=' + agents[id].host + '）';
+      else if (tokens[id]) reg = 'tokens.json 已登记（远端）';
+      const profile = findSelfProfile(root, id);
+      return { text: '当前智能体身份: ' + id + '\n登记状态: ' + reg + '\n自我档案: ' + (profile || '未写入（本地引擎主机执行 yotta-memory iam ' + id + '）'), error: false };
+    }
     return { text: '未知工具: ' + name, error: true };
   } catch (e) {
     return { text: '错误: ' + (e && e.message ? e.message : String(e)), error: true };
@@ -856,13 +1028,15 @@ function usage() {
     '  yotta-memory config set memory_home <目录>  持久记住记忆库位置',
     '  yotta-memory config get                   查看当前配置与生效位置',
     '  yotta-memory remember <type> <subject> <statement> [--owner <id>]   写入记忆',
-    '  yotta-memory recall [关键词] [--type T] [--limit N] [--agent <id>] [--owner <id>] [--all] [--unsafe]  检索（索引+TF，读取分区）',
+    '  yotta-memory recall [关键词] [--type T] [--limit N] [--agent <id>] [--owner <id>] [--all] [--unsafe]  检索（索引+TF，读取分区；--agent 仅表示“以该身份检索/模拟”，跨智能体私密读取需 --unsafe / 授权）',
     '  yotta-memory forget <文件或文件名>         删除一条记忆',
     '  yotta-memory archive [--days 180] [--threshold 0.4]  归档（盖棺分+年龄）',
     '  yotta-memory reindex                       重建索引',
     '  yotta-memory export [--out 文件.json]      导出全部记忆',
     '  yotta-memory import <文件.json>            导入记忆',
-    '  yotta-memory token new --agent <id>       生成/重置某智能体访问 token（登记 .server/tokens.json，打印一次）',
+    '  yotta-memory whoami                       查看当前智能体身份与登记状态（读 YOTTA_AGENT_ID / X-Agent-Id，不猜不默认）',
+    '  yotta-memory iam <id> [--force]           登记本智能体唯一身份并自动落自我档案（agents.json；ID 必须唯一）',
+    '  yotta-memory token new --agent <id> [--force]  生成/重置某智能体访问 token（同 ID 已被其它来源占用需 --force 覆盖）',
     '  yotta-memory token list                   列出已登记智能体',
     '  yotta-memory token revoke --agent <id>    吊销某智能体 token',
     '  yotta-memory serve [--host 0.0.0.0] [--port 8787] [--no-auth] [--stdio]  启动 MCP 记忆引擎（streamable HTTP；--stdio 本地零进程模式）',
@@ -870,7 +1044,8 @@ function usage() {
     '  yotta-memory --version                    版本',
     '',
     '类型: FACT(公共共享) / PREF(偏好) / BOUND(边界) / COMMIT(承诺)',
-    '环境变量: YOTTA_MEMORY_HOME 临时覆盖用户级位置; YOTTA_AGENT_ID/AGENT_ID 当前 agent 标识（读取分区）',
+    '环境变量: YOTTA_MEMORY_HOME 临时覆盖用户级位置; YOTTA_AGENT_ID/AGENT_ID 当前 agent 标识（本机声明身份用；私密记忆必须有 owner）',
+    '隔离: 公共 FACT 在 facts/；私密 PREF/BOUND/COMMIT 物理分目录 private/<agent_id>/<type>/，禁止 shell 直读写记忆库，一律走本命令',
     '远端接入: MCP url http://<主机IP>:8787/mcp；请求头 Authorization: Bearer <token> + X-Agent-Id: <id>',
     '',
   ].join('\n'));
@@ -892,6 +1067,7 @@ function main() {
     else if (a === '--no-auth') opts.noAuth = true;
     else if (a === '--stdio') opts.stdio = true;
     else if (a === '--onstart') opts.onstart = true;
+    else if (a === '--force') opts.force = true;
     else if (valueOpts.has(a)) {
       const v = args[++i];
       if (a === '--type') opts.type = v;
@@ -914,6 +1090,8 @@ function main() {
   }
   switch (first) {
     case 'init': cmdInit(opts); break;
+    case 'whoami': cmdWhoami(); break;
+    case 'iam': cmdIam(positional[0], opts); break;
     case 'config': {
       const sub = positional[0];
       if (sub === 'set') cmdConfigSet(positional[1], positional[2]);
@@ -930,7 +1108,7 @@ function main() {
     case 'import': cmdImport(positional[0]); break;
     case 'token': {
       const sub = positional[0];
-      if (sub === 'new') cmdTokenNew(opts.agent);
+      if (sub === 'new') cmdTokenNew(opts.agent, opts);
       else if (sub === 'list') cmdTokenList();
       else if (sub === 'revoke') cmdTokenRevoke(opts.agent);
       else { console.error('token 子命令: new --agent <id> / list / revoke --agent <id>'); process.exit(2); }
@@ -968,4 +1146,7 @@ module.exports = {
   saveConfig: saveConfig,
   loadTokens: loadTokens,
   saveTokens: saveTokens,
+  collectEntryFiles: collectEntryFiles,
+  migrateLayout: migrateLayout,
+  typeSubdir: typeSubdir,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-memory",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "元忆 —— 有权限边界的文件式智能体记忆。文件式、零依赖、可 diff/回滚；FACT/PREF/BOUND/COMMIT 四分类（公共共享/私密隔离），用户级+项目级双级存储。",
   "license": "MIT",
   "keywords": [
@@ -15,6 +15,7 @@
     "SKILL.md",
     "LICENSE",
     "README.md",
+    "USER_GUIDE.md",
     "install.sh",
     "references",
     "scripts",

package/references/protocol.md

@@ -1,4 +1,4 @@
-# yotta-memory 协议规范 v0.2.9
+# yotta-memory 协议规范 v0.5.0
 
 > 本文件定义 yotta-memory 记忆标准：存储位置、目录结构、文件格式、类型体系与 CLI 命令参考。
 > 目标：任何支持 Agent Skills 开放标准的智能体，装完即可读写同一份记忆。
@@ -17,15 +17,29 @@
 
 ```
 <root>/
-├── facts/       # FACT 事实（公共可共享）
-├── prefs/       # PREF 偏好（私密）
-├── bounds/      # BOUND 边界（私密）
-├── commits/     # COMMIT 承诺（私密）
-├── .archive/    # 归档区（archive 命令移入）
-├── index.json   # 反向索引 + TF 打分
-└── README.md    # 记忆库说明
+├── facts/                  # FACT 事实（公共可共享）
+├── private/                # 私密区（按 owner 物理分目录）
+│   └── <owner>/            # 每个智能体一个子目录
+│       ├── prefs/          # PREF 偏好（该 owner 私密）
+│       ├── bounds/         # BOUND 边界（该 owner 私密）
+│       └── commits/        # COMMIT 承诺（该 owner 私密）
+├── .archive/               # 归档区（archive 命令移入）
+├── index.json              # 反向索引 + TF 打分（见下方说明）
+├── agents.json             # 智能体身份登记表（iam 写入，唯一性强制）
+└── README.md               # 记忆库说明
 ```
 
+> **`index.json` 说明**：条目内的 `tokens` 字段是中文分词的「词频表」，供 recall 的 TF 打分使用，**不是**访问令牌。真正的访问令牌由 `token` 命令生成，存放在 `<root>/.server/tokens.json`，仅在局域网 `serve` 模式下用于请求鉴权。
+
+> **目录结构（v0.5.0）**：私密记忆按 `owner` 物理分目录存放于 `private/<owner>/<type>/`。旧版根下平铺的 `prefs/` `bounds/` `commits/` 会在 `reindex`（或首次 recall 建索引）时按 frontmatter `owner` 自动迁移到 `private/<owner>/<type>/`。**AI 读写红线**：记忆读写一律走 `yotta-memory` CLI / MCP 工具；禁止用 shell（`Get-ChildItem` / `Get-Content` / `cat` / `ls` / `type` 等）直接读改记忆库目录下的文件——否则会绕过 `scope/owner` 权限边界，读到其它智能体的私密内容。
+
+## 2.5 智能体身份（谁在写 / 谁在读）
+
+- **agent ID 必须全局唯一**：`iam <id>` 写入 `agents.json`（记忆库根目录），唯一性强制——ID 已被其它主机 / 来源（含远端 token 登记）占用则拒绝，确认是同一智能体才 `--force`。
+- **当次身份声明**：`whoami` / MCP `agent_info` 读「当次声明身份」——本机 `YOTTA_AGENT_ID`（stdio 由 MCP 配置 `env` 注入，CLI 用 `--agent`/环境变量）；远端 `X-Agent-Id` 请求头（经 token 绑定校验）。不猜不默认。
+- **自我档案**：`iam` 自动写一条 PREF `subject=自我接入档案`（owner=自己），statement 为 `; ` 分隔的 key:value——`agent_id / host / memory_home / mcp_mode(stdio|http) / engine_url(仅远端) / token(仅远端；本机不存 token)`。
+- **私密记忆必须有 owner**：PREF / BOUND / COMMIT 写入时未声明身份（owner 空）直接拒绝（公共 FACT 不受影响），从机制上防止「抄别人的 ID」。
+
 ## 3. 文件格式
 
 每个记忆一条独立 `.md` 文件，文件名 `<YYYY-MM-DD>-<NNNN>.md`（NNNN 为当日序号）：
@@ -72,12 +86,14 @@ immutable: false
 | `COMMIT` | 承诺 / 约定 | 私密 |
 
 - 写入纪律：公共事实用 FACT；涉及用户偏好 / 边界 / 承诺一律用私密类型，避免公共区泄露。
-- 多智能体协作：每个智能体只读自己的私密区（如 `~/.yottamemory/<agent-id>/prefs/` 可自行约定），公共 FACT 共享。
+- 多智能体协作：每个智能体只读自己的私密区（如 `private/<owner>/<type>/` 可自行约定），公共 FACT 共享。
 
 ## 隔离说明
 
 > 隔离说明：scope: private 保证的是"AI 之间的语义隔离"——其他智能体在正常 recall 会话中不会被搜到、也不会主动去读本条私密记忆。但它不是文件系统级机密保护：在你自己的机器上，作为所有者你有权看到任何记忆文件，数据主权在你。本工具不承诺对抗同权限的本地进程主动读取。
 
+> **`--agent` 语义**：`--agent <其它agent>` 仅作身份声明 / 展示用（以该身份检索或模拟），并不授予跨智能体私密读取——读取其它智能体私密仍需满足 grant / identity=user / `--unsafe` 任一授权。
+
 读分区边界（recall 三态）：
 
 | 目标 | 行为 |