From 349889a49626abe31f6852ec33d3b88a69873a21 Mon Sep 17 00:00:00 2001 From: DawnARC Date: Sat, 4 Apr 2026 00:51:46 +0800 Subject: [PATCH] =?UTF-8?q?docs:=E6=9B=B4=E6=96=B0mem=E5=A5=91=E7=BA=A6?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/a_memorix_sync.md | 9 ++++++--- src/A_memorix/CHANGELOG.md | 10 ++++++++++ src/A_memorix/CONFIG_REFERENCE.md | 9 +++++++-- src/A_memorix/IMPORT_GUIDE.md | 9 +++++++-- src/A_memorix/MODIFICATION_POLICY.md | 6 +++++- src/A_memorix/QUICK_START.md | 8 +++++--- src/A_memorix/README.md | 5 +++-- 7 files changed, 43 insertions(+), 13 deletions(-) diff --git a/docs/a_memorix_sync.md b/docs/a_memorix_sync.md index f93d669e..312fe9f6 100644 --- a/docs/a_memorix_sync.md +++ b/docs/a_memorix_sync.md @@ -5,7 +5,9 @@ - A_Memorix 主线源码位于 `src/A_memorix` - 宿主接入层位于 `src/services/memory_service.py`、`src/webui/routers/memory.py` 与 dashboard 长期记忆页面 - 运行配置位于 `config/a_memorix.toml` -- 运行数据位于 `data/plugins/a-dawn.a-memorix/` +- 运行数据由 `storage.data_dir` 决定（当前配置模板默认 `data/a-memorix/`） +- 旧离线脚本默认目录仍可能落在 `data/plugins/a-dawn.a-memorix/`（见脚本注释/参数说明） +- Web 上传暂存目录为 `data/memory_upload_staging/` - 上游同步方式固定为 `git subtree` ## 首次接入 @@ -40,6 +42,7 @@ git subtree pull --prefix=src/A_memorix https://github.com/A-Dawn/A_memorix.git ## 同步后检查 -1. 确认 `config/a_memorix.toml` 仍指向 `data/plugins/a-dawn.a-memorix` +1. 确认 `config/a_memorix.toml` 中 `storage.data_dir` 与你的运行目录规划一致（默认模板为 `data/a-memorix`） 2. 运行 `python src/A_memorix/scripts/runtime_self_check.py --help` -3. 运行 A_memorix 相关测试或最少执行一次针对性导入验证 +3. 运行 `python -m pytest pytests/A_memorix_test/test_memory_service.py` +4. 运行 `cd dashboard && npm run test -- src/routes/resource/__tests__/knowledge-base.test.tsx` diff --git a/src/A_memorix/CHANGELOG.md b/src/A_memorix/CHANGELOG.md index 772cff46..f1a20b9d 100644 --- a/src/A_memorix/CHANGELOG.md +++ b/src/A_memorix/CHANGELOG.md @@ -1,5 +1,15 @@ # 更新日志 (Changelog) +## [Unreleased] + +### 📚 文档口径同步 + +- 补充并统一“运行时目录”和“离线脚本默认目录”的说明： + - 运行时主目录由 `storage.data_dir` 决定（当前模板默认 `data/a-memorix`）； + - 部分离线脚本仍以 `data/plugins/a-dawn.a-memorix` 作为默认处理目录。 +- 修正文档中的导入示例参数，`memory_import_admin.create_paste` 的 `input_mode` 示例统一为 `text`/`json`。 +- 更新 `README.md` 关于元数据 schema 的描述，和当前代码 `SCHEMA_VERSION = 9` 保持一致。 + ## [2.0.0] - 2026-03-18 本次 `2.0.0` 为架构收敛版本，主线是 **SDK Tool 接口统一**、**管理工具能力补齐**、**元数据 schema 升级到 v8** 与 **文档口径同步到 2.0.0**。 diff --git a/src/A_memorix/CONFIG_REFERENCE.md b/src/A_memorix/CONFIG_REFERENCE.md index d55eb49b..421571c8 100644 --- a/src/A_memorix/CONFIG_REFERENCE.md +++ b/src/A_memorix/CONFIG_REFERENCE.md @@ -17,7 +17,7 @@ enabled = true [storage] -data_dir = "data/plugins/a-dawn.a-memorix" +data_dir = "data/a-memorix" [embedding] model_name = "auto" @@ -126,9 +126,14 @@ default_sample_size = 24 ### `storage` -- `storage.data_dir` (代码默认 `./data`；当前内置配置推荐 `data/plugins/a-dawn.a-memorix`) +- `storage.data_dir` (当前配置模板默认 `data/a-memorix`) : 数据目录。相对路径按 MaiBot 仓库根目录解析。 +补充说明： + +- 部分离线脚本若未显式覆盖路径，会回退到 `A_memorix.paths.default_data_dir()`（当前为 `data/plugins/a-dawn.a-memorix`）。 +- 建议在运维侧统一目录策略，避免“控制台写入目录”和“脚本处理目录”不一致。 + ### `embedding` - `embedding.model_name` (默认 `auto`) diff --git a/src/A_memorix/IMPORT_GUIDE.md b/src/A_memorix/IMPORT_GUIDE.md index 06e2834c..9d248178 100644 --- a/src/A_memorix/IMPORT_GUIDE.md +++ b/src/A_memorix/IMPORT_GUIDE.md @@ -29,6 +29,11 @@ python src/A_memorix/scripts/runtime_self_check.py --json data/plugins/a-dawn.a-memorix/raw/ ``` +说明： + +- `process_knowledge.py` 当前默认扫描上述目录。 +- 若你的运行配置使用 `storage.data_dir = "data/a-memorix"`，请在执行脚本前统一目录，避免脚本导入目录与运行目录不一致。 + 执行： ```bash @@ -52,7 +57,7 @@ python src/A_memorix/scripts/import_lpmm_json.py ## 2.3 LPMM 数据转换 ```bash -python src/A_memorix/scripts/convert_lpmm.py -i -o data/plugins/a-dawn.a-memorix +python src/A_memorix/scripts/convert_lpmm.py -i -o data/a-memorix ``` ## 2.4 历史数据迁移 @@ -115,7 +120,7 @@ python src/A_memorix/scripts/audit_vector_consistency.py --json "arguments": { "action": "create_paste", "content": "今天完成了检索调优回归。", - "input_mode": "plain_text", + "input_mode": "text", "source": "manual:worklog" } } diff --git a/src/A_memorix/MODIFICATION_POLICY.md b/src/A_memorix/MODIFICATION_POLICY.md index 19d39ab8..29031586 100644 --- a/src/A_memorix/MODIFICATION_POLICY.md +++ b/src/A_memorix/MODIFICATION_POLICY.md @@ -27,9 +27,13 @@ - `src/services/memory_service.py` - `src/webui/routers/memory.py` - `dashboard/src/routes/resource/knowledge-base.tsx` +- `dashboard/src/routes/resource/__tests__/knowledge-base.test.tsx` - `dashboard/src/routes/resource/knowledge-graph/` +- `dashboard/src/lib/memory-api.ts` - `config/a_memorix.toml` -- `data/plugins/a-dawn.a-memorix/` +- `data/a-memorix/` +- `data/plugins/a-dawn.a-memorix/`（旧脚本默认路径） +- `data/memory_upload_staging/`（Web 上传暂存） - `pytests/A_memorix_test/` - 同步脚本与同步文档，例如 `scripts/sync_a_memorix_subtree.sh` diff --git a/src/A_memorix/QUICK_START.md b/src/A_memorix/QUICK_START.md index 7ff61c38..b2b940aa 100644 --- a/src/A_memorix/QUICK_START.md +++ b/src/A_memorix/QUICK_START.md @@ -42,7 +42,7 @@ pip install -r requirements.txt --upgrade enabled = true [storage] -data_dir = "data/plugins/a-dawn.a-memorix" +data_dir = "data/a-memorix" [embedding] model_name = "auto" @@ -157,12 +157,14 @@ python src/A_memorix/scripts/runtime_self_check.py --json ### 4.1 文本批量导入 -把文本放到： +`process_knowledge.py` 当前默认扫描目录为： ```text data/plugins/a-dawn.a-memorix/raw/ ``` +若你当前运行目录使用 `storage.data_dir = "data/a-memorix"`，建议先把文本同步到脚本默认目录再执行，避免导入目录与运行目录不一致。 + 执行： ```bash @@ -181,7 +183,7 @@ python src/A_memorix/scripts/process_knowledge.py --chat-log --chat-reference-ti ```bash python src/A_memorix/scripts/import_lpmm_json.py -python src/A_memorix/scripts/convert_lpmm.py -i -o data/plugins/a-dawn.a-memorix +python src/A_memorix/scripts/convert_lpmm.py -i -o data/a-memorix python src/A_memorix/scripts/migrate_chat_history.py --help python src/A_memorix/scripts/migrate_maibot_memory.py --help python src/A_memorix/scripts/migrate_person_memory_points.py --help diff --git a/src/A_memorix/README.md b/src/A_memorix/README.md index 060bfb0d..572d01a7 100644 --- a/src/A_memorix/README.md +++ b/src/A_memorix/README.md @@ -21,7 +21,7 @@ A_Memorix 是 MaiBot 内置的长期记忆子系统。 - 旧 `components/commands/*`、`components/tools/*` 与 `server.py` 已移除。 - 统一入口为宿主侧 host service + [`core/runtime/sdk_memory_kernel.py`](core/runtime/sdk_memory_kernel.py)。 -- 元数据 schema 为 `v8`，新增外部引用与运维操作记录（如 `external_memory_refs`、`memory_v5_operations`、`delete_operations`）。 +- 元数据 schema 为 `v9`，支持外部引用与运维操作记录（如 `external_memory_refs`、`memory_v5_operations`、`delete_operations`）。 如果你还在使用旧版 slash 命令（如 `/query`、`/memory`、`/visualize`），需要按本文的 Tool 接口迁移。 @@ -140,6 +140,7 @@ enabled = true ### 配置方式 - 默认配置文件：`config/a_memorix.toml` +- 运行目录主路径：`storage.data_dir`（当前模板默认 `data/a-memorix`） - 长期记忆控制台：适合修改常用高频项，如 embedding、检索、Episode、人物画像、导入与调优开关。 - 原始 TOML：适合复制整份配置、批量粘贴参数，或编辑未在可视化表单中展示的高级项。 - 配置参考：请结合 [CONFIG_REFERENCE.md](CONFIG_REFERENCE.md) 查看各键的运行时语义与默认值。 @@ -171,7 +172,7 @@ python src/A_memorix/scripts/process_knowledge.py - `web/import.html`（导入中心） - `web/tuning.html`（检索调优） -当前分支不再内置独立 `server.py`，页面路由与 API 暴露由宿主侧 React 页面和 `/api/webui/memory/*` 接口承接。 +当前分支不再内置独立 `server.py`，页面路由与 API 暴露由宿主侧 React 页面和 `/api/webui/memory/*` 接口承接（并保留 `/api/*` 兼容路由）。 ### WebUI 验证脚本