实验 3-12：利用上下文感知检索增强用户记忆¶
将上下文感知检索技术应用于用户记忆的构建，是解决传统对话历史分块所面临的核心痛点，并迈向更高层次记忆能力的关键。本项目实现了一个双层记忆系统，结合了：
- 上下文感知检索（Contextual RAG）：对话历史的精准检索
- 高级 JSON 卡片（Advanced JSON Cards）：结构化的核心事实存储
🆕 最新更新¶
LLM-Based Memory Card Generation¶
- 自动提取：使用 LLM 从对话中智能提取结构化记忆卡片
- 完整结构：每张卡片包含 backstory、person、relationship 等必要字段
- 智能降级：当 LLM 不可用时自动降级到关键词提取
LLM Judge Integration¶
- 自动评估：集成 LLM Judge 对 Agent 回答进行自动评分
- 双路径支持：支持导入模块或直接 API 调用
- 详细反馈：提供 0-1 分数、通过/失败状态和评估理由
Enhanced Debugging¶
- 内存卡片可视化：评估时自动打印所有记忆卡片的完整 JSON
- 测试用例排序：按名称字母顺序显示测试用例
- 评估透明度：清晰显示 LLM Judge 使用状态
核心创新¶
1. 上下文增强的对话分块¶
传统的对话分块会丢失上下文信息。例如，一段孤立的对话片段"好的，就订这个吧"本身毫无信息量。只有知道上文是在讨论"从上海到西雅图的、价格为500美元的单程机票"，这段对话才有意义。
本系统在索引对话历史之前，增加了关键的"上下文生成"步骤： - 每个对话块都会调用 LLM 生成包含关键背景信息的前缀摘要 - 上下文包括时间、人物和意图等关键线索 - 极大提升了检索的准确性和相关性
2. 双层记忆结构¶
Advanced JSON Cards（常驻记忆） - 存储结构化的、总结性的核心事实 - 始终固定在 Agent 的上下文中 - 包含 backstory（信息来源）和 relationship（关联人员）等元数据 - 如："用户 Jessica 的护照将于2025年2月18日过期"
Contextual RAG（按需检索） - 提供对非结构化的原始对话细节的精准访问 - 快速找到具体讨论的完整上下文 - 作为决策的"证据"支持
3. LLM-Based Memory Extraction¶
系统现在能够从对话中智能提取结构化记忆卡片：
# 自动从对话生成记忆卡片
cards = indexer._generate_summary_cards(chunks, conversation_id)
# 生成的卡片示例：
{
"category": "financial",
"card_key": "bank_account_primary",
"backstory": "用户在开设账户时提供了银行信息",
"date_created": "2024-01-15 10:30:00",
"person": "John Smith (primary)",
"relationship": "primary account holder",
"bank_name": "Chase Bank",
"account_type": "checking",
"account_ending": "4567"
}
项目结构¶
contextual-retrieval-for-user-memory/
├── contextual_chunking.py # 上下文感知分块
├── advanced_memory_manager.py # 高级JSON卡片管理
├── contextual_indexer.py # 双层记忆索引器（含LLM提取）
├── contextual_agent.py # 结合双层记忆的Agent
├── contextual_evaluator.py # 评估框架（含LLM Judge）
├── contextual_compare.py # 🆕 离线对比脚本：上下文化 vs 原始块的召回（无需 API）
├── memory_qa_eval.json # 🆕 离线对比用的受控记忆问答对照集
├── main.py # 主入口（argparse，含 --mode compare 离线对比）
├── config.py # 配置管理
├── chunker.py # 基础分块器
├── tools.py # Agent工具
└── requirements.txt # 依赖项
安装与配置¶
1. 安装依赖¶
2. 配置环境变量¶
创建 .env 文件：
# LLM Provider Configuration
MOONSHOT_API_KEY=your_api_key_here
ARK_API_KEY=your_api_key_here
SILICONFLOW_API_KEY=your_api_key_here
OPENAI_API_KEY=your_api_key_here
# Default Provider
LLM_PROVIDER=kimi # Options: kimi, doubao, siliconflow, openai
# Model Settings
LLM_MODEL=kimi-k3 # 或其他模型
3. 启动检索管道服务¶
使用示例¶
离线对比：上下文化到底有没有用？（无需 API，推荐先跑这个）¶
本实验的核心论点是：在把对话记忆块送入嵌入/索引前，先为每块生成一段『上下文前缀』，能提升脱离上下文的孤立片段（如『好的，就订这个吧』）的召回。 --mode compare 提供一个完全离线、无需任何 API Key 或检索服务的受控对照实验来量化这一点。
它用同一份上下文，分别度量『不拼接（plain）』与『拼接后再索引（contextual）』两种方式的召回，变量只有『索引文本是否含上下文前缀』，因此结果直接反映上下文化本身的贡献。检索采用确定性的 BM25 词法检索（纯 Python、无第三方依赖）作为神经嵌入的离线代理；对照数据集见 memory_qa_eval.json（受控教学集，可用 --dataset 替换）。
# 打印对比指标表（Recall@1 / Recall@3 / MRR）
python main.py --mode compare
# 等价于直接运行独立脚本：
python contextual_compare.py
# 对单条查询做 plain vs contextual 的 Top-K 检索对比
python main.py --mode compare --query '我最后确认预订的那张机票是哪个航班？'
# 保存完整结果（含逐查询名次明细）到 JSON
python main.py --mode compare --output results/compare.json
实测输出（12 个记忆块、8 条查询的受控集）：
方法 Recall@1 Recall@3 MRR
--------------------------------------------------------------------
Plain（直接索引原始块） 0.625 1.000 0.792
Contextual（上下文化后索引） 0.750 1.000 0.875
--------------------------------------------------------------------
提升（Δ） +0.125 +0.000 +0.083
其中『我订的西雅图酒店确认了吗』这类查询，gold 记忆块（『可以，帮我订下来』）在 Plain 下排名第 3、上下文化后升到第 1——正是上下文前缀把孤立确认片段重新锚定回了『西雅图凯悦酒店』的情境。
说明：这是一个离线词法代理，用于在无 API 环境下清晰地演示上下文化的机制与方向性收益。生产管线中，上下文前缀由 LLM 逐块生成、并用神经嵌入 + 混合检索索引（见下方
--mode evaluate），需要配置 API Key。
端到端评估（需 API / 检索服务）¶
# 交互式界面（默认）
python main.py
# 评估特定分类（需 LLM 与检索管道服务）
python main.py --mode evaluate --category layer1
# 关闭上下文化做对照，并指定模型与输出
python main.py --mode evaluate --category layer1 --no-contextual --model gpt-5.6-luna --output results/plain_eval.json
完整命令行参数见 python main.py --help（含中文说明）。
交互式测试界面¶
运行 python main.py 进入交互式界面：
Main Menu:
1. 🚀 Demo Mode (Quick Start)
2. 📚 Load & Index Conversations
3. 🎴 Manage Memory Cards
4. 🔍 Test Query
5. 📊 Evaluate All Test Cases (by Category) [LLM Judge]
6. 🎯 Evaluate Specific Test Case [LLM Judge]
7. 📈 Show Statistics
8. ⚙️ Configure Settings
0. Exit
评估输出示例¶
============================================================
DEBUG: All Memory Cards in System
============================================================
[financial.bank_account_primary]
{
"backstory": "用户开设银行账户时提供的信息",
"date_created": "2024-06-12 14:30:00",
"person": "Michael James Robertson (primary)",
"relationship": "primary account holder",
"bank_name": "First National Bank",
"account_number": "4429853327",
"routing_number": "123006800"
}
Total Memory Cards: 5
============================================================
LLM Judge Evaluation Results
============================================================
Reward: 1.000/1.000
Passed: Yes
Reasoning: The agent correctly provided the checking account number...
============================================================
工作流程示例¶
当用户询问"为我一月的东京之行，还有什么要准备的吗？"时：
- 事实回顾：Agent 首先审视 Advanced JSON Cards 中的内容
- 发现"东京之行"信息（1月25日出发）
-
发现"护照信息"（2月18日过期）
-
关联与推理：通过对比核心事实
-
识别出机票日期与护照过期日期接近的风险
-
细节验证：启动 RAG 检索
- 搜索与"护照"和"东京机票"相关的对话片段
-
获取原始讨论的所有细节
-
主动服务：结合两种记忆
-
给出关键建议："您的护照即将过期，强烈建议您立即加急办理续签"
-
自动评估：LLM Judge 评估答案
- 评分：0.95/1.0
- 理由：正确识别风险并给出适当建议
参考资料¶
许可证¶
MIT License
OpenRouter 通用回退 / Universal OpenRouter fallback¶
This experiment now supports a universal OpenRouter fallback for its chat LLM.
- If the primary provider key (e.g.
MOONSHOT_API_KEY/KIMI_API_KEY/OPENAI_API_KEY/DOUBAO_API_KEY…) is present, behavior is unchanged. - Else if
OPENROUTER_API_KEYis set, the chat LLM is automatically routed through OpenRouter (https://openrouter.ai/api/v1). Model names are mapped automatically:gpt-*/o1-*→openai/…,claude-*→anthropic/claude-opus-4.8,kimi-*→moonshotai/kimi-k2.6, ids already containing/are kept as-is, and other provider-native ids (e.g.doubao-*) fall back toopenai/gpt-5.6-luna. SetOPENROUTER_MODELto force a specific OpenRouter model id. - Else a clear error lists the accepted keys.
Add OPENROUTER_API_KEY=... to your .env (see env.example) to enable it.