Tyro Memory 使用说明

这是一个支持人物隔离、冲突检测、图增强检索的长短期记忆系统。

1. 功能概览

• 记忆提取：从当前对话中提取 episodic / attribute 记忆。
• 关键词标签：每条记忆自动生成 2~3 个关键词，便于后续检索。
• 人物隔离：按 Persona_ID 分区存储和检索。
• 关系判断：识别 contradicts（矛盾）和 refines（补充/演进）关系。
• 图增强检索：向量召回后做 k 跳图扩展，生成上下文块。

2. 环境准备

2.1 安装依赖

pip install -r requirements.txt

2.2 配置 API Key（DashScope）

export DASHSCOPE_API_KEY="你的Key"

若未配置 Key，系统仍可运行，但会启用本地回退逻辑（效果不如线上模型）。

2.3 配置文件

默认配置在：

• memory_system/config/config.yaml
• memory_system/config/config.py（社区构建参数）

可调参数包括：

• retrieval.vector_top_n：向量召回数量
• retrieval.keyword_top_n：关键词向量召回数量
• retrieval.rerank_top_n：重排保留数量
• retrieval.vector_score_threshold：向量相似度阈值
• retrieval.rerank_score_threshold：rerank 分数阈值
• retrieval.graph_depth_k：图扩展深度
• storage.vector_store_file / storage.graph_store_file：持久化文件路径

社区相关参数在 memory_system/config/config.py 中维护：

• rebuild_interval：每新增多少条记忆触发一次 Louvain 社区重建
• louvain_resolution：Louvain 分辨率
• louvain_seed：Louvain 随机种子
• max_hierarchy_layers：社区层级最大层数

社区结果会持久化到 graph_store.json 的图级元数据中（community_state），并包含每层社区的语义摘要（自底向上生成）。

3. 命令行使用

入口文件：main.py

3.1 查看帮助

python3 main.py -h
python3 main.py process -h
python3 main.py retrieve -h

4. 使用示例

示例 A：写入新记忆（process）

python3 main.py process \
  --speaker Caroline \
  --sentence "Last week I went to swim.And I met my best friend there" \
  --history "Melanie: How are you?" \
  --reference-time "2026-04-17, Monday"

输出中你会看到：

• extracted：提取出的结构化记忆
• processed[].new_memory：写入后的记忆节点
• processed[].new_memory.keywords：该记忆的 2~3 个关键词
• processed[].created_edges：新建关系边（若有）
• processed[].deduplicated：是否命中去重（若为 true，本次不会重复写入）
• community_update：社区构建触发状态（是否触发、阈值、待触发计数、层级数量等）

示例 B：检索长期记忆上下文（retrieve）

支持三种检索模式（通过 --retrieval-mode 选择）：

• manual：手动指定 --speaker（默认）
• all：不指定 speaker，在全量人物记忆中检索
• auto：由大模型根据 query 和人物列表自动选择检索人物

模式 1：manual（手动指定 speaker）

python3 main.py retrieve \
  --retrieval-mode manual \
  --speaker Melanie \
  --query "Where has Melanie camped?"

模式 2：all（全库检索）

python3 main.py retrieve \
  --retrieval-mode all \
  --query "Where has Melanie camped?"

模式 3：auto（LLM 自动选人）

python3 main.py retrieve \
  --retrieval-mode auto \
  --query "Where has Melanie camped?"

检索流程说明：

• 先按 retrieval.vector_top_n 做文本向量召回；
• 再按 retrieval.keyword_top_n 做关键词向量召回；
• 将两路召回结果混合去重后，再进入现有 rerank 与图扩散。

输出中你会看到：

• retrieval_mode：当前检索模式
• selected_persona_ids：本次实际参与检索的人物列表
• seed_memory_ids：向量+重排得到的种子节点
• expanded_memory_ids：图扩展后的节点集合
• context_block：可直接拼接到 Prompt 的长期记忆文本块

示例 C：关系判断触发（矛盾/演进）

python3 main.py process \
  --speaker Caroline \
  --sentence "I am married now." \
  --history "Caroline: I am single." \
  --reference-time "2026-04-15, Wednesday"

该示例会触发关系判断流程，并在输出的 created_edges 中体现 contradicts 或 refines。

5. 数据落盘位置

运行后会自动生成：

• memory_system/data/storage/vector_store.json
• memory_system/data/storage/graph_store.json

6. 为历史数据补关键词

如果你已有 memory_system/data/storage 下的历史数据（旧数据没有 keywords 字段），可运行：

python3 backfill_keywords.py --storage-dir memory_system/data/storage

该命令默认会输出进度（文件进度 + 节点 tqdm 进度条）。

可调节进度输出频率（默认每 500 条节点输出一次）：

python3 backfill_keywords.py --storage-dir memory_system/data/storage --progress-interval 1000

如需关闭进度输出：

python3 backfill_keywords.py --storage-dir memory_system/data/storage --no-progress

如需更快且不消耗 API，可禁用 LLM：

python3 backfill_keywords.py --storage-dir memory_system/data/storage --disable-llm

仅预览统计结果（不写回文件）：

python3 backfill_keywords.py --storage-dir memory_system/data/storage --dry-run

只处理指定文件（可重复 --file）：

python3 backfill_keywords.py --file memory_system/data/storage/vector_store.json

7. 问答测试

python3 qa_with_llm.py --query "Where has Melanie camped?"