HMS（Holographic Memory System）是一个用 Python 构建的长期记忆问答与评测框架，核心目标是在 LongMemEval 等长上下文/多会话记忆任务中，通过“检索记忆 → 组织证据 → 生成答案 → 模型裁判”的流程提升大模型的长期推理可靠性。项目不仅提供可复现实验管线，还提供 OpenAI 客户端包装器，可让应用在每次模型调用时自动召回相关记忆并保留新的对话记忆。
适用领域
大模型长期记忆 / RAG 与记忆增强生成 / 多轮对话记忆管理 / LLM 评测与基准复现 / LongMemEval / 证据组织与可追溯回答 / AI Agent 基础设施 / OpenAI 兼容模型集成
配置难度
中高。若只是运行演示，难度中等；若要完整复现 LongMemEval、调优 pgvector 检索、配置多模型角色并分析结果，需要较强的 Python 后端、LLM API、数据库和评测工程经验。
商业价值
该项目适合用于构建带长期记忆能力的 AI 助手、企业智能客服、个人知识助理和 Agent 平台。其商业价值主要体现在提升跨会话记忆、一致性回答和证据可追溯能力，降低单纯 RAG 在长周期用户交互中的遗忘、重复计数和状态混淆问题。对于正在研发 AI Agent Memory 层的团队，它可以作为实验参考、原型基础或评测框架；但在生产落地前仍需加强稳定性、安全合规、权限隔离、监控和成本控制。
01
技术亮点
- 提供一键自动记忆 demo，可包装现有 OpenAI Client，自动完成 retain 与 recall
- 支持 OpenAI Responses API 和 Chat Completions API，并提到支持 streaming
- 提出结构化 evidence ledger，在答案生成前显式组织时间、来源、事实类型、数字信号和原始片段
- 面向长时间跨度、多会话、多证据的复杂记忆问答场景
- 包含 ledger pipeline 和 self-evolution pipeline 两种实验模式
- self-evolution 模式针对计数去重、相对日期、金额差异、当前/历史状态冲突等失败模式加入轻量控制器
- 提供可视化 HTML/SVG demo，便于理解从原始会话到证据 ledger 再到答案生成的流程
- MIT 许可证，便于二次开发和商业集成
- README 对运行环境、配置项、benchmark 参数说明较完整
02
目标用户
- 研究长期记忆、RAG、Agent Memory 的算法研究者
- 需要为 AI 助手接入用户级长期记忆的应用开发者
- 希望复现 LongMemEval 或类似记忆问答 benchmark 的工程团队
- 构建个人助理、企业知识助手、客服助手的开发者
- 需要评估模型跨会话推理能力的 LLM 评测人员
- 熟悉 Python、PostgreSQL、OpenAI API 生态的后端工程师
03
配置要求
- 需要 Python 环境，README 中示例会通过 uv 创建隔离环境
- 需要 PostgreSQL 数据库，并启用 pgvector，用于存储与向量检索记忆
- 需要 OpenAI 兼容的大模型 API，可分别配置核心推理、记忆抽取、答案生成、裁判模型
- 需要 Embedding 模型配置，默认提到 text-embedding-3-small；如果服务商不支持需单独替换
- 关键配置包括 HMS_API_LLM_BASE_URL、HMS_API_LLM_API_KEY、HMS_API_LLM_MODEL
- 记忆抽取配置包括 HMS_API_RETAIN_LLM_BASE_URL、HMS_API_RETAIN_LLM_API_KEY、HMS_API_RETAIN_LLM_MODEL
- 答案生成配置包括 HMS_API_ANSWER_LLM_BASE_URL、HMS_API_ANSWER_LLM_API_KEY、HMS_API_ANSWER_LLM_MODEL
- 裁判模型配置包括 HMS_API_JUDGE_LLM_BASE_URL、HMS_API_JUDGE_LLM_API_KEY、HMS_API_JUDGE_LLM_MODEL
- Embedding 配置包括 HMS_API_EMBEDDINGS_OPENAI_BASE_URL、HMS_API_EMBEDDINGS_OPENAI_API_KEY、HMS_API_EMBEDDINGS_OPENAI_MODEL
- benchmark 需要本地 LongMemEval 数据集路径 HMS_DATASET_PATH
- 不要将填写真实密钥的 .env 提交到代码仓库
04
适用场景
- 为 OpenAI SDK 调用自动增加记忆召回与对话保留能力
- 复现 LongMemEval 上的长期记忆问答实验
- 比较普通检索结果列表与结构化证据 ledger 对答案质量的影响
- 研究模型是否能区分用户当前状态与历史状态
- 研究模型在多会话、多时间点、多证据条件下的推理能力
- 构建带有用户偏好、项目状态、历史事件记忆的 AI 助手
- 分析计数、时间、金额、状态更新等复杂记忆问题中的失败模式
05
部署与配置
- 克隆仓库：git clone https://github.com/Shadow-Weave/HMS.git
- 进入项目目录：cd HMS
- 复制环境变量模板：cp .env.example .env
- 编辑 .env，填写 OpenAI 兼容模型服务的 Base URL、API Key、模型名、Embedding 模型配置、PostgreSQL 数据库地址和数据集路径
- 准备 PostgreSQL，并确保数据库支持 pgvector 扩展
- 运行自动记忆演示：bash scripts/run_memory_demo.sh
- 如需运行 benchmark，设置环境变量 HMS_BENCHMARK=longmemeval、HMS_PIPELINE=ledger 或 self_evolution、HMS_MAX_INSTANCES 等
- 执行最小评测：bash .aaaSCRIPT/run_benchmark.sh --parallel 1 --max-concurrent-questions 1 --eval-semaphore-size 1
- 查看运行结果目录 .aaaRESULT/ 和日志目录 .aaaLOG/
06
风险与注意事项
- 项目星标数不高但已有一定关注度，成熟度仍需通过代码质量、issue、测试覆盖进一步确认
- 依赖外部 LLM 与 Embedding API，运行成本、速率限制和结果稳定性受模型服务影响
- benchmark 需要 LongMemEval 数据集，本仓库不一定直接包含数据，复现前需自行准备
- 依赖 PostgreSQL 与 pgvector，对只想快速本地体验的开发者有一定部署门槛
- 结构化记忆抽取、召回和裁判均可能受模型幻觉影响，需要在生产环境加入审计与容错
- README 提到 arXiv coming soon，说明相关论文或正式实验报告可能尚未发布
- 多角色模型配置较多，新手容易配置错误
- 长期记忆涉及用户隐私，若用于真实应用需要额外处理数据加密、权限隔离、删除机制和合规问题
2026-07-19
第20名
新收录 · github_search
2026-07-18
第21名
新收录 · github_search
2026-07-17
第30名
新收录 · github_search
