@yottameta/yotta-memory 0.2.10 → 0.4.2

package/README.md

@@ -1,21 +1,21 @@
-# 元忆（yotta-memory）
-
 <p align="center">
-  <img src="assets/banner.png" alt="元忆（yotta-memory）banner" width="100%" />
+  <img src="assets/banner.png" alt="yotta-memory banner" width="100%" />
 </p>
 
+<h1 align="center">元忆（yotta-memory）</h1>
+
+<p align="center">元忆 —— 有权限边界的文件式智能体记忆。让任何 AI 智能体活过会话：开工 <code>recall</code> 恢复上下文、重要信息 <code>remember</code> 落盘、收工归档。文件式、零依赖、可 diff / 回滚；FACT 共享、PREF / BOUND / COMMIT 私密隔离——谁该读、谁不该读，由机制而非 AI 自觉决定。</p>
+
 <p align="center">
-  <img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" />
-  <img alt="Standard: agentskills.io" src="https://img.shields.io/badge/standard-agentskills.io-orange" />
-  <img alt="Agents: 17+" src="https://img.shields.io/badge/agents-17%2B-purple" />
-  <img alt="npm package" src="https://img.shields.io/npm/v/@yottameta/yotta-memory" />
-  <img alt="npm downloads" src="https://img.shields.io/npm/dt/@yottameta/yotta-memory" />
-  <img alt="GitHub stars" src="https://img.shields.io/github/stars/YottaMeta/yotta-memory" />
-  <img alt="last commit" src="https://img.shields.io/github/last-commit/YottaMeta/yotta-memory" />
-  <img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen" />
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" /></a>
+  <a href="https://agentskills.io/"><img alt="Standard: agentskills.io" src="https://img.shields.io/badge/standard-agentskills.io-orange" /></a>
+  <a href="https://www.npmjs.com/package/@yottameta/yotta-memory"><img alt="npm package" src="https://img.shields.io/npm/v/@yottameta/yotta-memory" /></a>
+  <a href="https://github.com/YottaMeta/yotta-memory"><img alt="GitHub stars" src="https://img.shields.io/github/stars/YottaMeta/yotta-memory" /></a>
+  <a href="https://github.com/YottaMeta/yotta-memory/commits/main"><img alt="last commit" src="https://img.shields.io/github/last-commit/YottaMeta/yotta-memory" /></a>
+  <a href="https://github.com/YottaMeta/yotta-memory"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen" /></a>
 </p>
 
-> 元忆 —— 有权限边界的文件式智能体记忆。让任何 AI 智能体活过会话：开工 `recall` 恢复上下文、重要信息 `remember` 落盘、收工归档。文件式、零依赖、可 diff / 回滚；FACT 共享、PREF / BOUND / COMMIT 私密隔离——谁该读、谁不该读，由机制而非 AI 自觉决定。
+> 📖 面向用户的操作手册见 [USER_GUIDE.md](USER_GUIDE.md)。
 
 ## 核心价值
 
@@ -24,6 +24,7 @@
 - **记忆就是文件**：每条记忆是一个带 YAML frontmatter 的 Markdown 文件，放在用户自己的目录里。用任何编辑器都能查看、修改、删除，用 git 就能做版本管理与回滚。
 - **隔离由机制保证**：FACT 进公共区共享，PREF / BOUND / COMMIT 进私密区、按 agent 隔离。读取按 scope/owner 分区过滤，越界内容由 CLI 拦截、永不返回（默认静默跳过；显式跨读无授权才报错拒绝）——不依赖智能体的「自觉」。
 - **零依赖、即装即用**：无守护进程、无数据库、无向量库，只需要 Node.js。安装即用，数据留在本机。
+- **便携记忆盘**：记忆库本身就是记忆引擎——装在硬盘或主机上随盘走，局域网内其它主机上的智能体可远程读写；本地零进程模式与局域网常驻模式可并存，插上硬盘即恢复全部记忆。
 
 ## 核心优势
 
@@ -36,6 +37,9 @@
 | **双级存储** | 用户级 `~/.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 常驻——两种模式可并存、按需选用 |
 
 ## 功能详解
 
@@ -64,9 +68,20 @@
 - **默认静默、显式跨读才报错**：默认 recall 遇其它 agent 私密静默跳过（不泄露「存在 N 条私密不可见」）；仅当显式跨智能体读取（`--all` / `--owner <其它>`）且无授权命中时才报错 / 警告。
 - **隔离定位**：scope: private 保证的是 AI 之间的语义隔离（正常 recall 不会被搜到、不会主动去读），不是文件系统级机密保护——数据主权在用户，作为所有者有权看到任何记忆文件。
 
+### 智能体身份（唯一 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`，为生命周期管理提供依据。
 
@@ -82,6 +97,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)。
+
 ## 与其他方案对比
 
 > 以下按方案类型对比，不涉及具体产品名称。判断标准：数据主权、部署成本、权限边界、可审计性、跨智能体能力。
@@ -127,17 +150,37 @@ 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]` | 初始化记忆库（默认用户级 `~/.yottamemory/`）|
+| `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 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 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 开机即启需管理员）|
 
 类型：`FACT`（事实，公共共享）/ `PREF`（偏好）/ `BOUND`（边界）/ `COMMIT`（承诺）。
 
@@ -151,12 +194,71 @@ yotta-memory recall --type FACT --limit 10
 
 环境变量：
 - `YOTTA_MEMORY_HOME`：覆盖用户级记忆库目录（默认 `~/.yottamemory/`）。
-- `YOTTA_AGENT_ID` / `AGENT_ID`：当前 agent 标识，参与读取分区判定。
+- `YOTTA_AGENT_ID` / `AGENT_ID`：当前 agent 标识（本机声明身份用，参与读取分区判定；私密记忆必须有 owner，未声明会被拒绝）。
 
 ## 智能体接入后怎么用
 
 把技能装进智能体后，SKILL.md 会自动教会智能体：开工 `recall` 恢复上下文 → 重要信息 `remember` 落盘 → 收工归档。也可在对话中直接说「记住 XXX」「上次说到哪了」。
 
+## 局域网多机共享（便携记忆盘模式）
+
+记忆库可以装在任何主机或硬盘上（= 记忆引擎），供局域网内其它主机上的智能体远程接入：
+
+- **本机直连**：CLI 直接读写，无需 token；
+- **远程接入**：引擎主机运行 `yotta-memory serve` 常驻（或 `lan enable` 注册开机自启），远程智能体通过 MCP 以 `url + token` 连接。
+- **本地零进程**：本机 MCP 客户端可用 `serve --stdio` 按需拉起 CLI（无常驻进程）。
+
+### 引擎侧（记忆所在主机）
+
+1. 初始化或接入记忆库（见 CLI 用法）。
+2. 为需要访问的每个智能体生成独立 token：
+   ```bash
+   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                          # 临时前台运行
+   yotta-memory lan enable                     # 注册开机自启（Windows 计划任务，登录自启）
+   yotta-memory lan status                     # 查看自启状态
+   ```
+   > `lan enable --onstart` 改为开机即启（需管理员）；`lan disable` 移除自启。
+
+> 首次监听 0.0.0.0 时，Windows / 系统防火墙可能询问是否放行，需允许放行，否则局域网内其它主机无法访问；`--no-auth` 会关闭鉴权，仅限可信内网使用。
+
+### 客户端侧（远程智能体）
+
+在智能体 MCP 配置中登记连接（`url` + 两个请求头）：
+
+```json
+{
+  "mcpServers": {
+    "yotta-memory": {
+      "url": "http://<引擎主机IP>:8787/mcp",
+      "headers": {
+        "Authorization": "Bearer <TOKEN>",
+        "X-Agent-Id": "<本智能体ID>"
+      }
+    }
+  }
+}
+```
+
+连接后可通过 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 私密隔离）。
+
+### 位置持久化
+
+CLI 会持久记住记忆库位置（`~/.yottamemory/config.json`），同一主机上的智能体此后开工 `recall` 自动使用正确位置，无需每次指定：
+
+```bash
+yotta-memory config set memory_home <记忆库目录>
+yotta-memory config get
+```
+
+位置解析优先级：`YOTTA_MEMORY_HOME`（临时覆盖）> `config.json#memory_home`（持久）> 默认 `~/.yottamemory`。把记忆库放在硬盘上、插到任意主机后执行一次 `config set memory_home`（或用 `yotta-memory init --dir <目录>` 一步初始化到指定位置），即可在该主机恢复全部记忆。
+
 ## 开发与校验
 
 本项目内运行：`python tools/validate-skill.py yotta-memory`。

package/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: yotta-memory
-description: "元忆 —— 有权限边界的文件式智能体记忆。文件式、零依赖、可 diff/回滚：让任何 AI 智能体活过会话，开工 recall 恢复上下文、重要信息 remember 落盘、收工归档。类型体系 FACT（公共共享）/ PREF / BOUND / COMMIT（私密隔离）。触发：记住、别忘了、记一笔、记忆、remember、recall、跨会话、上次说到、续测、交接、归档"
-version: 0.2.10
+description: "元忆 —— 有权限边界的文件式智能体记忆。文件式、零依赖、可 diff/回滚：让任何 AI 智能体活过会话，开工 recall 恢复上下文、重要信息 remember 落盘、收工归档。类型体系 FACT（公共共享）/ PREF / BOUND / COMMIT（私密隔离）。触发：记住、别忘了、记一笔、记忆、remember、recall、跨会话、上次说到、续测、交接、归档、记忆盘、共享记忆、局域网记忆"
+version: 0.4.2
 license: MIT
 ---
 
 # yotta-memory（元忆）— 有权限边界的文件式智能体记忆
 
 > 一句话：元忆 —— 有权限边界的文件式智能体记忆（不注入、可 diff、能回滚；FACT 共享、PREF / BOUND / COMMIT 私密隔离）。
-> 版本：0.2.10 | 最后更新：2026-08-23
+> 版本：0.4.2 | 最后更新：2026-08-25
 
 ## 这是什么
 
@@ -26,27 +26,173 @@ 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 只写本智能体私密区；不读取其他智能体私密区。
 
+
+### 开工第一步：确认记忆位置 + 智能体身份（每次会话先做，必做）
+
+**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_HOME` 临时覆盖时不必改 config；本步骤是常规 CLI 直连用户级位置的引导。
+
 ## CLI 速查
 
 | 命令 | 作用 |
 |---|---|
-| `yotta-memory init [--project]` | 初始化记忆库（默认用户级）|
+| `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 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 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 打分）。
+`<YYYY-MM-DD>-<NNNN>.md`，frontmatter 含 `type / subject / statement / confidence / created / updated / tags / immutable / scope / owner / access_count / last_accessed`；正文为记忆内容。顶层另有 `index.json`（反向索引 + TF 打分，其 `tokens` 字段是分词词频，非访问令牌）与 `agents.json`（智能体身份登记表，唯一性）。
+
+自我档案（本智能体身份，强制落盘）：PREF，`subject=自我接入档案`，`owner=<本智能体ID>`，statement 为 `; ` 分隔的 key:value——`agent_id / host / memory_home / mcp_mode（stdio|http）/ engine_url（仅远端）/ token（仅远端；本机不存 token）`。
+
+## 便携记忆盘模式（局域网多机共享）
+
+记忆库可装在任何主机或硬盘上（= 记忆引擎）：本机 AI 用 CLI 直连，局域网内其它主机上的 AI 经 MCP 远程接入。全程 AI 自主执行；关键动作（🔒）执行前一句话说明「做什么 + 为什么 + 影响」并征得用户同意，用户只需回答「可以 / 好 / 允许」；除复制粘贴 token 外，用户不做任何手工操作。
+
+### 4.0 前置：CLI 自装 + 记忆位置准备 + 持久记住
+
+**步骤 0.1 检查 CLI 是否已装**
+```bash
+yotta-memory --version    # 或 command -v yotta-memory / where yotta-memory
+```
+已装 → 跳过。未装 → 🔒 **征得同意后**自行安装（三选一，AI 判断）：
+| 方式 | 命令 | 适用 |
+|---|---|---|
+| npx 临时 | `npx -y @yottameta/yotta-memory` | 任何有 Node 的机器 |
+| npm 全局 | `npm i -g @yottameta/yotta-memory` | 长期使用 |
+| install.sh | `bash <(curl -s https://raw.githubusercontent.com/YottaMeta/yotta-memory/main/install.sh)` | 离线 / 国内 / 无 npm |
+装后验证：`yotta-memory --version` 出版本即就绪。
+
+**步骤 0.2 确定记忆存储位置**
+| 位置 | 目录 | 适用 |
+|---|---|---|
+| 用户级（默认） | `~/.yottamemory` | 个人跨项目记忆 |
+| 项目级 | `<repo>/.yottamemory` | 随项目提交共享 |
+| 便携记忆盘 | 硬盘上目录（如 `D:\memory` / 挂载点） | 记忆盘 / 局域网共享 |
+
+**步骤 0.3 接入现有 vs 初始化新库（关键判断）**
+1. 检查目标目录是否已是记忆库：存在 `facts/` 等子目录或 `index.json`。
+2. 已是 → 🔒 **征得同意后**直接接入（不重复初始化）：设位置后 `recall` 验证能读到旧记忆。
+3. 不是 → 🔒 **征得同意后**初始化新库：`yotta-memory init --dir <目录>` 或 `YOTTA_MEMORY_HOME=<目录> yotta-memory init`（项目级用 `init --project`）。
+4. 验证：`recall` 跑通。
+
+**步骤 0.4 持久记住位置（重要）**
+- 🔒 **征得同意后**执行：`yotta-memory config set memory_home <目录>`（项目级可跳过）。
+- 作用：写入 `~/.yottamemory/config.json`，此后该机器 AI 开工 `recall` 自动用对位置。
+- 验证：`yotta-memory config get` 显示 memory_home 与预期一致。
+
+> 记忆盘场景：硬盘插上 → AI 检查盘上目录是否有数据 → 有则接入 + config 记住 → 插盘即恢复，机器记住位置。
+
+**步骤 0.5 启动记忆引擎（仅引擎主机，供远程接入）**
+- 本机若作引擎：🔒 **征得同意后**启动服务——临时运行 `yotta-memory serve`（默认 `0.0.0.0:8787`，Bearer token + X-Agent-Id 鉴权；`--no-auth` 仅限可信内网），或注册开机自启 `yotta-memory lan enable`（Windows 计划任务，默认登录自启；`--onstart` 开机即启需管理员）。
+- 本地零进程模式：本机 AI 也可用 `serve --stdio` 由 MCP 客户端按需拉起 CLI（无常驻进程，照灵魂盘）。
+- 远程客户端接入前，先确认引擎主机 serve 已运行（`lan status` 可查）。
+
+### 4.1 触发
+用户提及「记忆盘 / 记忆引擎 / 共享记忆 / 局域网记忆」，或开工 `recall` 发现需要访问远程记忆库时进入本流程。
+
+### 4.2 第一步：检查是否已配置（避免重复询问）
+1. `YOTTA_MEMORY_HOME` 或 `config get` 显示 memory_home 已指向本机可读目录 → 「本机直连」，直接用 CLI。
+2. 当前智能体 MCP 配置已有 `yotta-memory` server → 「远程已配置」，直接用 MCP tools。
+3. 都没有 → 进入 4.3。
+
+### 4.3 第二步：向用户确认引擎位置（AI 提问，用户回答）
+1. **记忆引擎在本机，还是局域网内其他主机？**（本机 / 远程）
+2. 若**远程**：引擎主机 **IP**（或主机名）？**端口**？（默认 8787）
+3. 本机 → 4.4；远程 → 4.5。
+
+### 4.4 本机直连
+确认记忆库目录（`config get` / `YOTTA_MEMORY_HOME` / 默认 `~/.yottamemory`）→ 直接 CLI 读写，**不配置 MCP、不需要 token**。
+
+### 4.5 远程连接：AI 引导用户获取 token（用户只做复制粘贴）
+1. AI 告知需要为本智能体申请访问 token。
+2. AI 引导用户在**引擎主机**执行：`yotta-memory token new --agent <本智能体ID>`（引擎主机没装 → 按 4.0 先装；或请引擎主机上的 AI 代执行）。
+3. 命令打印 token（`ytm_...`），只打印一次，请用户妥善保管。
+4. AI 请用户复制 token 发给 AI。
+5. 用户发来 → AI 继续 4.6。
+
+> 用户不会操作时：AI 逐步引导（开终端 → 粘贴命令 → 回车 → 复制输出），直到成功。**除复制粘贴外用户不做别的**。
+
+### 4.6 配置 MCP（AI 自己完成，🔒 需同意）
+1. 🔒 说明将把 yotta-memory 写入本智能体 MCP 配置并请用户同意；
+2. 定位当前智能体 MCP 配置文件（见 4.7）；
+3. 添加 server（JSON 见 4.8）；
+4. 按当前智能体机制重载 MCP（必要时请用户重启会话）；
+5. 用 MCP tools 读写记忆。
+
+> MCP 工具集与 CLI 一致：remember / recall / search / forget / archive / reindex / export / import；管理动作（init / config / token / lan / serve）不进 MCP，token 管理不远程暴露。
+
+### 4.7 MCP 配置位置表
+| 智能体 | 常见 MCP 配置位置 |
+|---|---|
+| Claude Code | 项目 `.mcp.json` 或用户级 `~/.claude.json` |
+| Codex | `~/.codex/config.toml`（`[mcp_servers]`） |
+| Cursor | 项目 `.cursor/mcp.json` 或用户级 |
+| 其它（Trae / Qwen / Comate / Kimi 等） | 各自 MCP 配置 |
+
+### 4.8 通用 MCP server 配置片段
+```json
+{
+  "mcpServers": {
+    "yotta-memory": {
+      "url": "http://<IP>:8787/mcp",
+      "headers": {
+        "Authorization": "Bearer <TOKEN>",
+        "X-Agent-Id": "<本智能体ID>"
+      }
+    }
+  }
+}
+```
+
+### 4.9 验证连接（循环兜底）
+- 🔒 连接远程引擎前已获同意（4.5 / 4.6）→ 调一次 `recall` / `search` 确认能读到记忆 → 成功。
+- 失败：查 IP / 端口 / token 完整性 / 防火墙 / token 吊销；仍失败回 4.3。
+
+### 4.10 复用
+- 成功后优先复用现有连接；失败（token 吊销等）再回 4.3。
 
 ## 渐进披露
 
-- 协议细节、目录结构与类型规则见 `references/protocol.md`，需要时读取，不要每次全读。
+- 协议细节、目录结构与类型规则见 `references/protocol.md`，需要时读取，不要每次全读。