mai-bot/plugins/A_memorix/IMPORT_GUIDE.md

A_Memorix 导入指南 (v2.0.0)

本文档对应当前 2.0.0 代码路径，覆盖两类导入方式：

1. 脚本导入（离线批处理）
2. memory_import_admin 任务导入（在线任务化）

1. 导入前检查

建议先执行：

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

再确认：

• storage.data_dir 路径可写
• embedding 配置可用
• 若是升级项目，先完成迁移脚本

2. 方式 A：脚本导入（推荐起步）

2.1 原始文本导入

将 .txt 文件放入：

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"

2.2 OpenIE JSON 导入

python plugins/A_memorix/scripts/import_lpmm_json.py <json文件或目录>

2.3 LPMM 数据转换

python plugins/A_memorix/scripts/convert_lpmm.py -i <lpmm数据目录> -o plugins/A_memorix/data

2.4 历史数据迁移

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

2.5 导入后修复与重建

python plugins/A_memorix/scripts/backfill_temporal_metadata.py --dry-run
python plugins/A_memorix/scripts/backfill_relation_vectors.py --limit 1000
python plugins/A_memorix/scripts/rebuild_episodes.py --all --wait
python plugins/A_memorix/scripts/audit_vector_consistency.py --json

3. 方式 B：memory_import_admin 任务导入

memory_import_admin 是在线任务化导入入口，适合宿主侧面板或自动化管道。

3.1 常用 action

• settings / get_settings / get_guide
• path_aliases / get_path_aliases
• resolve_path
• create_upload
• create_paste
• create_raw_scan
• create_lpmm_openie
• create_lpmm_convert
• create_temporal_backfill
• create_maibot_migration
• list
• get
• chunks / get_chunks
• cancel
• retry_failed

3.2 调用示例

查看运行时设置：

{
  "tool": "memory_import_admin",
  "arguments": {
    "action": "settings"
  }
}

创建粘贴导入任务：

{
  "tool": "memory_import_admin",
  "arguments": {
    "action": "create_paste",
    "content": "今天完成了检索调优回归。",
    "input_mode": "plain_text",
    "source": "manual:worklog"
  }
}

查询任务列表：

{
  "tool": "memory_import_admin",
  "arguments": {
    "action": "list",
    "limit": 20
  }
}

查看任务详情：

{
  "tool": "memory_import_admin",
  "arguments": {
    "action": "get",
    "task_id": "<task_id>",
    "include_chunks": true
  }
}

重试失败任务：

{
  "tool": "memory_import_admin",
  "arguments": {
    "action": "retry_failed",
    "task_id": "<task_id>"
  }
}

4. 直接写入 Tool（非任务化）

若你不需要任务编排，也可以直接调用：

• ingest_summary
• ingest_text

示例：

{
  "tool": "ingest_text",
  "arguments": {
    "external_id": "note:2026-03-18:001",
    "source_type": "note",
    "text": "新的召回阈值方案已通过评审",
    "chat_id": "group:dev",
    "tags": ["worklog", "review"]
  }
}

external_id 建议全局唯一，用于幂等去重。

5. 时间字段建议

可用时间字段（按常见优先级）：

• timestamp
• time_start
• time_end

建议：

• 事件类记录优先写 time_start/time_end
• 仅有单点时间时写 timestamp
• 历史数据可先导入，再用 backfill_temporal_metadata.py 回填

6. source_type 建议

常见值：

• chat_summary
• note
• person_fact
• lpmm_openie
• migration

建议保持稳定枚举，便于后续按来源治理与重建 Episode。

7. 导入完成后的验证

建议执行以下顺序：

1. memory_stats 看总量是否增长
2. search_memory（mode=search/aggregate）抽检召回
3. memory_episode_admin 的 status/query 检查 Episode 生成
4. memory_runtime_admin 的 self_check 再确认运行时健康

8. 常见问题

Q1: 导入任务创建成功但无写入

• 检查聊天过滤配置 filter（若 respect_filter=true 可能被过滤）
• 检查任务详情中的失败原因与分块状态

Q2: 任务反复失败

• 检查 embedding 与 LLM 可用性
• 降低并发（web.import.default_*_concurrency）
• 调整重试参数（web.import.llm_retry.*）

Q3: 导入后检索效果差

• 先做 runtime_self_check
• 检查 retrieval.sparse 是否启用
• 使用 memory_tuning_admin 创建调优任务做参数回归

9. 相关文档

• QUICK_START.md
• CONFIG_REFERENCE.md
• README.md
• CHANGELOG.md

10. 附录：策略模式参考

A_Memorix 导入链路仍然遵循策略模式（Strategy-Aware）。process_knowledge.py 会自动识别文本类型，也支持手动指定。

策略类型	适用场景	核心逻辑	自动识别特征
Narrative (叙事)	小说、同人文、剧本、长篇故事	按场景/章节切分，使用滑动窗口；提取事件与角色关系	#、Chapter、*** 等章节标记
Factual (事实)	设定集、百科、说明书	按语义块切分，保留列表/定义结构；提取 SPO 三元组	列表符号、术语: 解释
Quote (引用)	歌词、诗歌、名言、台词	按双换行切分，原文即知识，不做概括	平均行长短、行数多

11. 附录：参考用例（已恢复）

以下样例可直接复制保存为文件测试，或作为 LLM few-shot 示例。

11.1 叙事文本 (plugins/A_memorix/data/raw/story_demo.txt)

# 第一章：星之子

艾瑞克在废墟中醒来，手中的星盘发出微弱的蓝光。他并不记得自己是如何来到这里的，只依稀记得莉莉丝最后的警告：“千万不要回头。”

远处传来了机械守卫的轰鸣声。艾瑞克迅速收起星盘，向着北方的废弃都市奔去。他知道，那里有反抗军唯一的据点。

***

# 第二章：重逢

在反抗军的地下掩体中，艾瑞克见到了那个熟悉的身影。莉莉丝正站在全息地图前，眉头紧锁。

“你还是来了。”莉莉丝没有回头，但声音中带着一丝颤抖。
“我必须来，”艾瑞克握紧了拳头，“为了解开星盘的秘密，也为了你。”

11.2 事实文本 (plugins/A_memorix/data/raw/rules_demo.txt)

# 联邦安全协议 v2.0

## 核心法则
1. **第一公理**：任何人工智能不得伤害人类个体，或因不作为而使人类个体受到伤害。
2. **第二公理**：人工智能必须服从人类的命令，除非该命令与第一公理冲突。

## 术语定义
- **以太网络**：覆盖全联邦的高速量子通讯网络。
- **黑色障壁**：用于隔离高危 AI 的物理防火墙设施。

11.3 引用文本 (plugins/A_memorix/data/raw/poem_demo.txt)

致橡树

我如果爱你——
绝不像攀援的凌霄花，
借你的高枝炫耀自己；

我如果爱你——
绝不学痴情的鸟儿，
为绿荫重复单调的歌曲；

也不止像泉源，
常年送来清凉的慰籍；
也不止像险峰，
增加你的高度，衬托你的威仪。

11.4 LPMM JSON (lpmm_data-openie.json)

{
  "docs": [
    {
      "passage": "艾瑞克手中的星盘是打开遗迹的唯一钥匙。",
      "extracted_triples": [
        ["星盘", "是", "唯一的钥匙"],
        ["星盘", "属于", "艾瑞克"],
        ["钥匙", "用于", "遗迹"]
      ],
      "extracted_entities": ["星盘", "艾瑞克", "遗迹", "钥匙"]
    },
    {
      "passage": "莉莉丝是反抗军的现任领袖。",
      "extracted_triples": [
        ["莉莉丝", "是", "领袖"],
        ["领袖", "所属", "反抗军"]
      ]
    }
  ]
}