Files

A-Dawn a1540d7e17 feat: A_Memorix：加强严格模式、错误与删除语义

在 A_Memorix 中强制更严格的检索语义，并改进错误传播与删除结果报告。

强制/校验受支持的搜索模式（search/time/hybrid/episode/aggregate）；移除 semantic 模式，并对不支持的模式返回明确错误。将 kernel 和 plugin 构造函数中的默认值从 hybrid 改为 search。（plugins/A_memorix/core/runtime/sdk_memory_kernel.py, plugins/A_memorix/plugin.py）
对 time/hybrid 模式要求必须提供 time_start/time_end，并在文档、快速开始和 README 中体现该语义。（plugins/A_memorix/QUICK_START.md, plugins/A_memorix/README.md）
改进删除预览/执行语义：跟踪“请求的来源”与“匹配的来源”，基于匹配/删除项计算成功状态，并返回详细计数（requested_source_count、matched_source_count、deleted_paragraph_count、error）。修复来源删除逻辑，使其基于匹配到的来源执行删除。（plugins/A_memorix/core/runtime/sdk_memory_kernel.py）
在搜索执行中移除遗留的 semantic 映射，并规范化 query_type 处理。（plugins/A_memorix/core/utils/search_execution_service.py）
向调用方传播后端搜索错误：为 MemorySearchResult 增加 success/error 字段，兼容多种运行时响应封装，并在异常时返回失败结果。更新调用方以处理并报告搜索失败。（src/services/memory_service.py, src/plugin_runtime/capabilities/data.py, src/chat/brain_chat/PFC/pfc_KnowledgeFetcher.py, src/memory_system/retrieval_tools/query_long_term_memory.py）

2026-03-19 15:38:36 +08:00

4.5 KiB

Raw Blame History

A_Memorix Quick Start (v2.0.0)

本文档面向当前 2.0.0 架构（SDK Tool 接口）。

0. 版本与接口变更

当前插件版本：2.0.0
接口形态：memory_provider + Tool 调用
旧版 slash 命令（如 /query、/memory、/visualize）不再作为本分支主文档入口

1. 环境准备

Python 3.10+
与 MaiBot 主程序相同的运行环境
可访问你配置的 embedding 服务

安装依赖：

pip install -r plugins/A_memorix/requirements.txt --upgrade

pip install -r requirements.txt --upgrade

2. 启用插件

在主程序插件配置中启用 A_Memorix。

若你使用 plugins/A_memorix/config.toml 方式，最小示例：

[plugin]
enabled = true

[storage]
data_dir = "./data"

[embedding]
model_name = "auto"
dimension = 1024
batch_size = 32
max_concurrent = 5
quantization_type = "int8"

3. 运行时自检（强烈建议）

先确认 embedding 实际输出维度与向量库兼容：

python plugins/A_memorix/scripts/runtime_self_check.py --json

如果结果 ok=false，先修复 embedding 配置或向量库，再继续导入。

4. 导入数据

4.1 文本批量导入

把文本放到：

plugins/A_memorix/data/raw/

执行：

python plugins/A_memorix/scripts/process_knowledge.py

常用参数：

python plugins/A_memorix/scripts/process_knowledge.py --force
python plugins/A_memorix/scripts/process_knowledge.py --chat-log
python plugins/A_memorix/scripts/process_knowledge.py --chat-log --chat-reference-time "2026/02/12 10:30"

4.2 其他导入脚本

python plugins/A_memorix/scripts/import_lpmm_json.py <json文件或目录>
python plugins/A_memorix/scripts/convert_lpmm.py -i <lpmm数据目录> -o plugins/A_memorix/data
python plugins/A_memorix/scripts/migrate_chat_history.py --help
python plugins/A_memorix/scripts/migrate_maibot_memory.py --help
python plugins/A_memorix/scripts/migrate_person_memory_points.py --help

5. 核心 Tool 调用

5.1 检索

{
  "tool": "search_memory",
  "arguments": {
    "query": "项目复盘",
    "mode": "aggregate",
    "limit": 5,
    "chat_id": "group:dev"
  }
}

mode 支持：search/time/hybrid/episode/aggregate

严格语义说明：

semantic 模式已移除，传入会返回参数错误。
time/hybrid 模式必须提供 time_start 或 time_end，否则返回错误（不会再当作“未命中”）。

5.2 写入摘要

{
  "tool": "ingest_summary",
  "arguments": {
    "external_id": "chat_summary:group-dev:2026-03-18",
    "chat_id": "group:dev",
    "text": "今天完成了检索调优评审"
  }
}

5.3 写入普通记忆

{
  "tool": "ingest_text",
  "arguments": {
    "external_id": "note:2026-03-18:001",
    "source_type": "note",
    "text": "模型切换后召回质量更稳定",
    "chat_id": "group:dev",
    "tags": ["worklog"]
  }
}

5.4 画像与维护

{
  "tool": "get_person_profile",
  "arguments": {
    "person_id": "Alice",
    "limit": 8
  }
}

{
  "tool": "maintain_memory",
  "arguments": {
    "action": "protect",
    "target": "模型切换后召回质量更稳定",
    "hours": 24
  }
}

{
  "tool": "memory_stats",
  "arguments": {}
}

6. 管理 Tool（进阶）

2.0.0 提供完整管理工具：

memory_graph_admin
memory_source_admin
memory_episode_admin
memory_profile_admin
memory_runtime_admin
memory_import_admin
memory_tuning_admin
memory_v5_admin
memory_delete_admin

可先用 action=list / action=status 等只读动作验证链路。

7. 常见问题

Q1: 检索为空

先看 memory_stats 是否有段落/关系
检查 chat_id、person_id 过滤条件是否过严
运行 runtime_self_check.py --json 确认 embedding 维度无误
若返回包含 error 字段，优先按错误提示修正 mode/时间参数

Q2: 启动时报向量维度不一致

原因：现有向量库维度与当前 embedding 输出不一致
处理：恢复原配置或重建向量数据后再启动

Q3: Web 页面打不开

本分支不内置独立 server.py。

web/index.html、web/import.html、web/tuning.html 由宿主侧路由/API 集成暴露
请检查宿主是否已映射对应静态页与 /api/* 接口

8. 下一步

配置细节见 CONFIG_REFERENCE.md
导入细节见 IMPORT_GUIDE.md
版本历史见 CHANGELOG.md

4.5 KiB Raw Blame History Unescape Escape