@ccjr1120/memory-one 0.1.2 → 0.1.3

package/README.md

@@ -2,95 +2,84 @@
 
 让 Agent 在开始工作前，先记住你的项目约定、个人偏好和已经验证过的经验。
 
-Memory One 是一个运行在本机的长期记忆服务：用 React 工作台管理记忆，用 SQLite 保存数据，并通过 Streamable HTTP MCP 接入 Codex、Claude Code、Cursor 或自建 Agent。
+Memory One 是一个运行在本机的长期记忆服务。你可以通过可视化工作台管理记忆，并通过 MCP 将这些记忆提供给 Codex、Claude Code、Cursor 或自建 Agent。所有数据默认保存在本机 SQLite 数据库中。
 
 GitHub：https://github.com/ccjr1120/memory-one
 
-## 先看实际界面
+## 主要能力
 
-记忆总览：搜索、按 Scope 筛选，并查看每条记忆的召回次数和置信度。
+- **长期保存经验**：记录偏好、事实、项目决策、工作流程和纠正意见。
+- **任务前自动召回**：通过 `memory_get_context` 在 Agent 开始工作前读取相关经验。
+- **区分项目与通用记忆**：使用可选的 `scope` 对记忆分类，同时支持项目记忆与全局记忆联合召回。
+- **可视化管理**：搜索、筛选、新建、编辑和删除记忆，并查看召回次数与置信度。
+- **本地存储**：默认仅监听本机地址，数据保存在本地 SQLite 数据库中。
+- **调用可观察**：查看 MCP 调用次数、成功率、平均耗时和各工具使用情况。
+
+## 界面预览
+
+记忆总览：
 
 ![记忆总览](./docs/screenshots/memory-overview.png)
 
-MCP 服务页：复制客户端配置、查看服务端点、启用 Codex 全局记忆指令，并查看工具调用统计。
+MCP 服务与 Codex 增强：
 
 ![MCP 与 Codex 增强](./docs/screenshots/mcp-codex.png)
 
-### 更新截图
+## 安装与启动
 
-截图由 `scripts/capture-screens.mjs` 生成。启动本地服务后，第一次使用需要下载 Chromium：
+### 环境要求
 
-```bash
-npx --yes playwright@1.55.0 install chromium
-npm run screenshots
-```
+- Node.js 20 或更高版本
+- npm
 
-脚本默认访问 `http://127.0.0.1:8765`，覆盖 `docs/screenshots/` 下的两张图片。也可以按需调整地址、输出目录、视口和等待时间：
+### 安装
 
 ```bash
-npm run screenshots -- \
-  --base-url http://localhost:5173 \
-  --output-dir docs/screenshots \
-  --viewport 1280,900 \
-  --wait-ms 2000 \
-  --no-full-page
+npm install --global @ccjr1120/memory-one
 ```
 
-对应的环境变量是 `SCREENSHOT_BASE_URL`、`SCREENSHOT_OUTPUT_DIR`、`SCREENSHOT_VIEWPORT` 和 `SCREENSHOT_WAIT_MS`。
+### 启动
 
-## 它解决什么问题
-
-- **把经验保存下来**：偏好、项目决策、工作流程和重要事实都可以保存为长期记忆。
-- **让 Agent 先查再做**：每轮任务开始时调用 `memory_get_context`，把相关经验带入当前任务。
-- **按项目隔离查看**：用可选的 `scope` 分类项目记忆；不传 `scope` 时仍可搜索全局记忆。
-- **本地可控**：默认使用本机 SQLite，不需要云端账号或额外数据库。
-- **可观察**：MCP 页面展示总调用次数、成功率、平均耗时和每个工具的使用情况。
-
-## 3 分钟启动
+```bash
+memoryone start
+```
 
-### 1. 准备环境
+启动后：
 
-- Node.js 20 或更高版本
-- npm
+- 工作台：<http://127.0.0.1:23888/>
+- MCP 地址：<http://127.0.0.1:23888/mcp/>
 
-### 2. 安装并启动
+也可以直接打开工作台：
 
 ```bash
-git clone https://github.com/ccjr1120/memory-one.git
-cd memory-one
-npm install
-npm run dev
+memoryone open
 ```
 
-`npm run dev` 会先清理开发端口 `8765` 和 `5173`，然后同时启动 API 服务与 Vite 前端。
+如果端口 `23888` 已被占用，启动命令会询问是否终止占用进程。
 
-### 3. 打开工作台
+## 快速上手
 
-访问 <http://127.0.0.1:5173/>。
+第一次使用时，建议按以下顺序操作：
 
-建议第一次按这个顺序体验：
-
-1. 点击右上角 **新建记忆**，保存一条你希望 Agent 长期遵守的偏好。
-2. 在左侧进入 **全部记忆**，搜索刚刚保存的内容，并点击卡片查看详情。
-3. 进入 **MCP 服务**，复制配置并接入你的 Agent。
-4. 如果你使用 Codex，继续完成下面的“Codex 增强”步骤。
+1. 打开工作台，点击右上角 **新建记忆**。
+2. 保存一条希望 Agent 长期遵守的偏好或项目约定。
+3. 进入左侧 **MCP 服务** 页面。
+4. 在 **MCP Key 管理** 中创建 Key，并选择该客户端可以使用的工具。
+5. 复制 MCP 配置并添加到 Codex、Claude Code、Cursor 或其他 MCP 客户端。
+6. 重启客户端或新建会话，然后开始使用。
 
 ## 接入 MCP 客户端
 
-本地开发时的 MCP 地址是：
-
-```text
-http://127.0.0.1:8765/mcp/
-```
+Memory One 默认要求客户端通过 Bearer Key 访问 MCP 服务。请先在 **MCP 服务 → MCP Key 管理** 中创建 Key，再复制对应配置。
 
-MCP 服务默认要求 Bearer Key。进入 **MCP 服务 → MCP Key 管理** 创建 Key 后，使用页面的一次性配置复制按钮。配置格式如下：
+配置格式如下：
 
 ```json
 {
   "mcpServers": {
     "memory-one": {
       "type": "http",
-      "url": "http://127.0.0.1:8765/mcp/",
+      "url": "http://127.0.0.1:23888/mcp/",
       "headers": {
         "Authorization": "Bearer <你的 Key>"
       }
@@ -99,149 +88,143 @@ MCP 服务默认要求 Bearer Key。进入 **MCP 服务 → MCP Key 管理** 创
 }
 ```
 
-把这段配置放进客户端的 MCP 设置后，重启客户端或新开一个会话。平台 Agent、Codex 和其他客户端建议分别创建独立 Key，并按最小权限选择工具。新建 Key 的明文会保存在本地数据库中，之后可以再次复制。Memory One 默认只监听本机；如果要暴露到其他设备，请同时配置网络层和 Key 管理。
-
-## Codex 增强：在哪里、为什么、怎么用
-
-### 在哪里用
+将配置添加到客户端的 MCP 设置后，重启客户端或开启新会话。
 
-打开 Memory One 工作台，进入左侧 **MCP 服务** 页面，在 **Codex增强 / 全局任务前置记忆** 区域操作。
+建议为不同客户端分别创建 Key，并只授予所需工具权限。Key 保存在本机数据库中，可以随时回到管理页面复制或撤销。Memory One 默认仅监听本机；如需从其他设备访问，还需要自行配置网络访问方式。
 
-### 为什么要用
+## 为 Codex 启用任务前记忆
 
-仅仅把 MCP 服务配置给 Codex，并不能保证每个任务都会先读取记忆。Codex 增强会把一小段全局工作指令写入 `~/.codex/AGENTS.md`，明确要求 Codex：
+仅将 MCP 服务添加到 Codex，不能保证 Codex 在每项任务开始前主动读取记忆。Memory One 可以向 Codex 的全局 `AGENTS.md` 写入一段受管理的任务前置指令。
 
-> 开始任何任务前，先调用一次 `memory_get_context`；在 Git 项目中使用仓库根目录的绝对路径作为 `scope`。
+### 启用方法
 
-这样做的价值是把“先查记忆”变成稳定的任务前动作，而不是依赖你每次手动提醒。它适合经常在多个仓库之间切换、需要持续遵守项目约定，或希望 Agent 记住修正意见的场景。
+1. 在 **MCP Key 管理** 中创建 Codex 专用 Key，至少授权 `memory_get_context`；需要自动保存和修正记忆时，再授权写入工具。
+2. 将带有 Authorization Header 的 MCP 配置添加到 Codex。
+3. 在工作台中进入 **MCP 服务** 页面。
+4. 找到 **Codex增强 / 全局任务前置记忆**。
+5. 点击 **启用全局记忆**；已有旧版指令时，点击 **更新全局指令**。
+6. 重启 Codex 或开启新会话。
 
-### 怎么用
+启用后，Codex 会被要求：
 
-1. 在 **MCP Key 管理** 创建一个给 Codex 使用的 Key，至少勾选 `memory_get_context`；需要读写时再勾选对应工具。
-2. 把带 `Authorization` Header 的 MCP 配置放进 Codex。
-3. 打开 **MCP 服务**，找到 **Codex增强** 区域。
-4. 点击 **启用全局记忆**；如果已有旧版本指令，按钮会显示 **更新全局指令**。
-5. 重新启动 Codex，或开启一个新会话。
-6. 在 Codex 中直接提出任务，例如“检查这个项目的部署配置”。正常情况下，任务开始阶段会先出现 `memory_get_context` 调用。
+- 每项任务开始前调用一次 `memory_get_context`。
+- 在 Git 项目中使用仓库根目录的绝对路径作为 `scope`。
+- 将用户表达的长期偏好、决定、纠正和项目约定及时写入或更新到 Memory One。
 
-Memory One 只会替换自己管理的 `memory-one:codex` 标记区块，保留 `~/.codex/AGENTS.md` 中其他内容。写入动作必须由你在网页中主动点击完成，不会在安装或启动时自动修改 Codex 配置。
+Memory One 只会替换 `~/.codex/AGENTS.md` 中由自己管理的 `memory-one:codex` 标记区块，不会覆盖其他内容。该操作只会在你主动点击按钮后执行。
 
-## 内置记忆管家
+## 使用内置记忆管家
 
-右下角的悬浮按钮会打开记忆管家。它可以搜索、保存、更新、软删除记忆，也可以总结你的偏好和特点。
+点击工作台右下角的悬浮按钮可以打开记忆管家。它能够搜索、保存、更新和软删除记忆，也可以根据已有记忆总结你的偏好与特点。
 
-如果要使用它：
+首次使用需要完成模型配置：
 
-1. 点击右下角的 Agent 按钮；首次打开会进入配置页。
-2. 填写 Base URL，选择请求格式、获取模型列表并填写 API Key。
-3. 可选填写默认 Scope，并决定每轮对话是否自动读取上下文。
-4. 点击 **保存配置**，再从右下角打开记忆管家。
+1. 打开右下角的 Agent 面板并进入 **配置**。
+2. 填写模型服务的 Base URL。
+3. 选择请求格式并选择或填写模型。
+4. 非本地模型服务需要填写 API Key。
+5. 按需设置默认 Scope，以及是否在每轮对话前自动读取上下文。
+6. 保存配置后开始对话。
 
-模型配置保存在本地 SQLite 数据库；记忆的读写仍通过 Memory One MCP 工具完成。
+模型配置保存在本机 SQLite 数据库中；记忆操作仍通过 Memory One 的 MCP 工具完成。
 
 ## MCP 工具
 
 | 工具 | 用途 |
 | --- | --- |
-| `memory_get_context` | 每项任务开始时检索相关经验 |
+| `memory_get_context` | 在任务开始时检索相关经验 |
 | `memory_search` | 按关键词搜索记忆，可选 `scope` |
 | `memory_store` | 保存偏好、事实、决策、流程或纠正意见 |
-| `memory_get` | 按 ID 读取单条记忆 |
+| `memory_get` | 按 ID 读取单条完整记忆 |
 | `memory_list` | 列出记忆，可选 `scope` |
-| `memory_update` | 更新记忆内容或元数据 |
+| `memory_update` | 更新指定记忆的内容或元数据 |
 | `memory_delete` | 软删除指定记忆，仅在用户明确要求时使用 |
-| `memory_feedback` | 记录某条记忆是否有帮助，改善后续召回 |
+| `memory_feedback` | 记录记忆是否有帮助，以改善后续召回 |
 
-### Scope 怎么填
+## Scope 使用建议
 
-`scope` 是分类字段，不是安全隔离边界。项目记忆使用仓库根目录的绝对路径，例如 `/Users/name/code/memory-one`；通用偏好省略 `scope`。`memory_get_context` 传入项目 `scope` 时联合召回当前项目与全局记忆，不传时只召回全局记忆；`memory_search` 不传 `scope` 时仍可跨分类搜索。
+`scope` 是可选的分类字段，不是安全隔离边界。
 
-## 数据与配置
+- **项目记忆**：使用 Git 仓库根目录的绝对路径，例如 `/Users/name/code/my-project`。
+- **通用记忆**：省略 `scope`。
+- **其他分类**：也可以使用 `work`、`personal` 等自定义值。
 
-- 开发数据库：`data/memory.db`
-- 修改数据库路径：设置 `MEMORY_DB_PATH`
-- 修改服务端口：设置 `MEMORY_PORT`
-- 前端开发地址：<http://127.0.0.1:5173/>
-- 后端 API 地址：<http://127.0.0.1:8765/>
-- MCP 地址：<http://127.0.0.1:8765/mcp/>
+`memory_get_context` 传入项目 `scope` 时，会联合召回该项目和全局记忆；省略 `scope` 时，只召回全局记忆。`memory_search` 省略 `scope` 时，可以跨分类搜索。
 
-## 本地生产模式
-
-通过 npm 全局安装后，可以使用 CLI 管理本地服务：
+## CLI 命令
 
 ```bash
-npm install -g @ccjr1120/memory-one
-memoryone start
-memoryone status
-memoryone open
-memoryone update
-memoryone stop
+memoryone start   # 启动本地服务
+memoryone stop    # 停止本地服务
+memoryone status  # 查看运行状态
+memoryone open    # 在浏览器中打开工作台
+memoryone update  # 更新到最新版本
 ```
 
-服务默认运行在 <http://127.0.0.1:23888/>，MCP 地址为 <http://127.0.0.1:23888/mcp/>。数据库、PID 和日志保存在 `~/.local/share/memory-one`，不会写入 npm 包目录。执行 `memoryone update` 会更新全局 CLI，并在服务运行时自动重启服务。若启动时端口 `23888` 已被占用，CLI 会询问是否终止占用进程。
-
-从源码 checkout 安装并启动：
-
-```bash
-npm run install:local
-```
+执行 `memoryone update` 时，如果服务正在运行，Memory One 会先停止服务，更新完成后再自动启动。
 
-该命令会安装依赖、构建前端和后端，清理端口 `23888`，并在后台启动服务。
+## 数据与备份
 
-- 工作台：<http://127.0.0.1:23888/>
-- MCP：<http://127.0.0.1:23888/mcp/>
-- 部署目录：`~/.local/share/memory-one`
-- 部署数据库：`~/.local/share/memory-one/data/memory.db`
-- PID：`data/memory-one.pid`
-- 日志：`data/memory-one.log`
+运行数据默认保存在：
 
-生产服务请使用 `npm run install:local`，它会在临时目录构建并把版本复制到上面的部署目录后启动。
+```text
+~/.local/share/memory-one/
+```
 
-## 发布到 npm
+其中：
 
-仓库已经包含 GitHub Actions 发布流程：每次推送 `main` 时，工作流会自动递增一个 patch 版本，npm 发布前会运行测试和构建，发布成功后再提交新的 `package.json` 与 `package-lock.json`。自动生成的版本提交不会再次触发发布循环。
+- 数据库：`~/.local/share/memory-one/data/memory.db`
+- PID：`~/.local/share/memory-one/memory-one.pid`
+- 日志：`~/.local/share/memory-one/memory-one.log`
 
-首次配置需要完成两件事：
+备份记忆时，建议先执行：
 
-1. 在 npm 登录 `ccjr1120` 账号，进入 **Access Tokens** 创建一个具备发布权限的 token；包名是 scoped 包 `@ccjr1120/memory-one`。
-2. 在 GitHub 仓库的 **Settings → Secrets and variables → Actions → New repository secret** 中添加：
+```bash
+memoryone stop
+```
 
-   - Name：`NPM_TOKEN`
-   - Secret：刚才复制的 npm token
+然后复制 `memory.db` 文件。恢复时，在服务停止状态下用备份文件替换原数据库，再重新启动服务。
 
-这个 workflow 当前读取的就是 GitHub Actions 的 **Repository secret**，不会把 token 写入代码。若 npm 账号并不是 `ccjr1120`，则不能发布这个 scope，需要先使用自己账号对应的 scope。
+## 更新与卸载
 
-首次配置完成后，日常发布不需要手动切换分支或运行版本脚本，直接推送 `main` 即可：
+更新到最新版本：
 
 ```bash
-git push origin main
+memoryone update
 ```
 
-例如当前版本为 `0.1.0` 时，推送一次 `main` 会自动发布 `@ccjr1120/memory-one@0.1.1`。`npm run v` 仍保留给需要手动发布 minor、major 或特殊 release 分支的场景。
-
-本地全局安装后，使用下面的命令检查并更新到 npm 上的最新版本；如果服务正在运行，更新完成后会自动重启：
+卸载程序：
 
 ```bash
-memoryone update
+memoryone stop
+npm uninstall --global @ccjr1120/memory-one
 ```
 
-打开记忆工作台时，前端会检查当前版本和 npm 最新版本；发现新版本时会在顶部显示 3 秒通知条。
+卸载 npm 包不会自动删除 `~/.local/share/memory-one/` 中的数据库和配置。
 
 ## 常见问题
 
-**页面打不开？** 确认 `npm run dev` 仍在运行，并检查 `8765`、`5173` 是否被其他程序占用。开发脚本会自动清理这两个端口。
+### 页面打不开
 
-**Codex 没有读取记忆？** 确认 MCP 地址已配置，Codex 增强按钮已显示“已启用”，然后重启 Codex 或新开会话。
+运行 `memoryone status` 检查服务状态；如果服务未运行，执行 `memoryone start`。启动失败时，查看：
 
-**记忆管家提示配置不完整？** 打开右下角 Agent 面板，在 **配置** Tab 填写 Base URL、请求格式和模型；非本地模型还需要填写 API Key。
+```text
+~/.local/share/memory-one/memory-one.log
+```
 
-**想备份记忆？** 开发版备份 `data/memory.db`，生产版备份 `~/.local/share/memory-one/data/memory.db`；服务停止后操作最稳妥。
+### Codex 没有在任务开始前读取记忆
 
-## 开发
+确认以下事项：
 
-```bash
-npm run dev       # API + Vite 前端
-npm run install:local # 构建、复制并启动本地生产服务
-```
+1. Codex 已配置 Memory One MCP 地址和 Bearer Key。
+2. Key 已授权 `memory_get_context`。
+3. 工作台中的 Codex 增强显示为已启用。
+4. 启用后已经重启 Codex 或开启新会话。
+
+### 记忆管家提示配置不完整
+
+打开右下角 Agent 面板，在 **配置** 中检查 Base URL、请求格式、模型和 API Key。使用不需要鉴权的本地模型时，可以不填写 API Key。
+
+### 如何确认 MCP 已连接
 
-前端使用 React、Vite 和 `lucide-react`，后端使用 Fastify、MCP SDK 和 better-sqlite3。界面约定记录在 [DESIGN.md](./DESIGN.md)。
+在客户端中调用一次 `memory_get_context`，然后打开工作台的 **MCP 服务** 页面查看调用统计。也可以让 Agent 保存一条测试记忆，再到 **全部记忆** 中搜索确认。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccjr1120/memory-one",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "A local HTTP MCP service for personal agent memory",
   "type": "module",
   "bin": {