HL-Mem

中文 | English

中文

HL-Mem 是面向 AI Agent 的本地优先、证据驱动长期记忆系统。它不只是向量数据库：系统把不可变事件提取为带证据链的结构化 Claim，以有效时间和记录时间描述事实变化，并通过独立的 Experience 通道保存 Episode、Trace 和可复用 Policy。默认使用 SQLite WAL、FTS5 和向量 BLOB 精确扫描，也可选择 sqlite-vec 后端，无需部署外部数据库服务。

五分钟上手

需要 Python 3.11+。先从 PyPI 安装：

python -m pip install hl-mem

在准备存放本地配置和数据库的目录中，生成无需 API key 的离线配置并启动服务：

hlmem init --offline
hlmem server

另开一个终端，写入并召回记忆：

hlmem remember "Alice 喜欢深色模式"
hlmem recall "Alice 喜欢什么"

召回结果会同时给出 Claim ID、分数和证据引用，例如：

[1] Alice 喜欢深色模式
    ID: <claim-id>
    分数: 0.8123
    证据:
      - event/<event-id>

event/<event-id> 表示这条 Claim 可追溯到对应的不可变原始事件，而不是一段没有来源的模型文本。可用 hlmem list 再次查看 Claim ID，并将它用于 hlmem forget <claim-id>、REST 详情查询或 MCP 的 memory_explain。离线配置是 FTS-only 关键词召回；fake embedding 只保持存储结构兼容，不提供语义检索。

进阶安装与集成

从源码安装/运行

git clone https://github.com/lohr13/hl_mem.git
cd hl_mem
uv sync
uv run hlmem init --offline
uv run hlmem server

开发环境使用 uv sync --dev；安装后可运行 hlmem doctor 做只读诊断。SQLite 需要 FTS5，Python 官方发行版通常已包含。

受污染宿主环境

Hermes gateway 等宿主可能向子进程注入指向自身虚拟环境的 PYTHONPATH 或 PYTHONHOME。此时直接调用本仓库 .venv 的 Python，仍可能导入宿主环境中的包，并因 Python 版本不同而加载到不兼容的二进制扩展。从这类宿主运行源码时，请统一通过 launcher 启动：

bash scripts/hlmem-python.sh -m hl_mem.cli doctor

Windows cmd.exe 对应使用：

scripts\hlmem-python.cmd -m hl_mem.cli doctor

launcher 会清除两个污染变量、切换到仓库根目录，并固定使用 .venv/Scripts/python.exe。start_hl_mem.sh 和 start_production.bat 也委托给同一入口。

启用在线模型

从源码仓库将 config.example.toml 复制为本地 hl_mem.toml，并按需复制 .env.example。把启用组件的独立密钥写入 .env：LLM_API_KEY、EMBEDDING_API_KEY、RERANKER_API_KEY、IMAGE_API_KEY；再将对应的 extraction.mode、embedding.mode、reranker.mode、image_describer.mode 切换到在线模式。完整字段见 配置参考。

连接 Codex、Claude 与 Cursor

运行 python -m pip install "hl-mem[mcp]" 安装 MCP extra 后，可使用官方 SDK 2.x 的 stdio 入口 hl-mem-mcp 连接 Codex、Claude Code、Claude Desktop 或 Cursor。配置示例和七个工具的契约见 MCP 使用说明。

集成 Hermes

先启动 HL-Mem 并确认 curl --fail http://127.0.0.1:8200/healthz 成功，再从源码仓库运行：

uv run python scripts/install_to_hermes.py --hermes-home <HERMES_HOME>

插件安装到 <HERMES_HOME>/plugins/hl_mem/；完成后必须重启 Hermes。适配器通过本地 HTTP 提供超时、熔断、预取和 Episode/Trace 同步。

常驻部署与 systemd

常驻部署使用 scripts/healthcheck.py 探测 /healthz，将重启和告警交给 systemd、Windows 服务管理器或容器编排平台。systemd 的 WorkingDirectory 必须包含 hl_mem.toml 和可选 .env。

REST 的完整请求契约见 API 文档。

关键配置

非敏感配置只从当前工作目录的 hl_mem.toml 读取；密钥只从 .env 或同名进程环境变量读取。常用键如下，完整列表见 配置参考。

真实组件和外部调用路径必须提供各自密钥；失败时不会自动切换为 fake。任意 HL_MEM_* 环境变量都不再参与应用 Settings 配置。 Settings 与 config.example.toml 的 recall.default_limit / recall.relevance_reranker_floor 均为 5 / 0.15； 示例部署仅把 recall.relevance_relative_drop 从代码默认 0.15 显式调整为 0.30，并保持 recall.relevance_keep_top1 = true。query expansion 使用独立可配置模型，单次/总超时为 5/6 秒。

从 legacy 索引迁移既有数据库时，先只读预览，再显式执行回填；回填会同步 index_text、FTS 和 dense embedding，使用 real embedder 的部署需提供对应密钥：

hlmem backfill-index-text --mode natural --dry-run
hlmem backfill-index-text --mode natural

从 v0.24.0 升级

v0.26.0 是 v0.25.x 的向后兼容 minor 版本；v0.24.1/v0.24.2 只是仓库内过渡版本。从 v0.24.0 或更早版本升级前，请备份并停止 API、Worker 和其他写入者。migration 038 会在 BEGIN IMMEDIATE 中扫描并规范化存量 Claim subject， migration 039 为 Event 增加 nullable metadata_json，migration 040 增加有界 deferred task 队列；大库应安排维护窗口，数据库不支持向后迁移。 默认 auto FTS 查询同时兼容旧 raw-only 与新 raw+stem 索引，因此无需仅为词形兼容强制重建。

能力概览

• 记忆正确性：幂等事件摄入、事务原子写入、精确去重，以及覆盖摄入复用、维护等价边和召回折叠的保守近重复治理；确定性冲突规则、LLM 灰区归并和受守卫的冲突终态收敛。
• 提取治理：7 字段 compact 提取、统一 AdmissionPolicy、完整 Claim schema 后处理、双语复合事实/关系/枚举原子性规则、20 条输出边界审计、确定性的 scope/predicate 投影、subject 守卫和有界结构化输出修复。
• 时间与证据：有效时间与记录时间双时间模型、证据链、实体归一化、显式遗忘和 stale 传播。
• 混合召回：中文 FTS5、两阶段精确向量扫描或可选 sqlite-vec、RRF 融合、多因子排序、可选 Reranker、关系/查询扩展和按 Token 预算打包上下文。
• 生命周期：importance 联动 TTL、置信度衰减、归档、重分类、反馈效用、审计日志和在线备份。
• 经验通道：Episode、Trace、Reward、Policy/Procedure 和派生 Observation。
• 接口：FastAPI REST 与 Hermes Provider 为稳定主路径；七工具 MCP stdio 接口处于 Beta。
• 评测：离线提取/召回/生命周期指标、LongMemEval-S extract-once/config-compare、50 case 中文记忆测试集、召回诊断和索引文本受控 A/B。

LongMemEval holdout50 的冻结官方口径为 40/50（80%）：deepseek-v4-flash-0731、全部 reader 开启 thinking、Top-10 evidence、自有 judge；temporal gate 排除 2 道问题时点无有效答案的诊断口径为 40/48（83.3%），不替代官方分数。内容审查隔离跳过了 2 个输入 Event。benchmark reader 与生产 recall/context packing 是两套契约，该成绩不能直接视为生产端到端准确率。

评测结果

LongMemEval 三角对照统一使用 deepseek-v4-flash-0731 reader，reader 开启 thinking、judge 关闭 thinking。HL-Mem 以可治理的结构化 Claim 与证据链达到接近全上下文上限的结果；本地评测产物的 命名与目录说明见结果索引。

能力成熟度、默认开关和证据见 能力矩阵，架构与数据流见 架构文档。

项目状态

• Stable：事件与证据链、原子写入、LLM 提取、Embedding、FTS + Dense + RRF、双时间过滤、TTL/衰减/归档、冲突与去重、REST、Hermes、备份与审计。
• Beta：多查询召回、关系候选发现、反馈驱动维护、提取蕴含审计、语义去重审计、MCP Server、Benchmark 与 LongMemEval。
• Experimental：图片证据、提取预过滤、独立 Tag 通道、PostgreSQL 连通性探针。

当前基线为 v0.26.0，共 40 个不可变、仅向前执行的 SQL Migration。

文档

Contributing / 贡献指南

欢迎通过 Issue 报告缺陷或提出功能建议。提交前请搜索是否已有同类 Issue，并附上复现步骤、预期行为、实际行为、环境信息和必要日志。Pull Request 应聚焦单一改动，说明动机与验证结果，并在行为或公共契约变化时同步更新测试和文档。

开发环境与检查命令：

git clone git@github.com:REDACTED_USER/hl_mem.git
cd hl_mem
uv sync --dev
uv run pytest tests/unit/ -q --tb=short
uv run black --check src tests
uv run isort --check-only src tests
uv run ruff check src tests

提交信息使用英文，格式为 type(scope): description，其中 type 可选 feat、fix、refactor、test、docs 或 chore。

English: Please search existing issues before opening one and include reproduction steps, expected/actual behavior, environment details, and relevant logs. Keep each PR focused, explain the motivation and validation, update tests/docs when contracts change, set up with uv sync --dev, and run the checks above.

License / 许可证

本项目采用 Apache License 2.0。你可以在许可证条款允许的范围内使用、修改和分发本项目，并须保留所要求的版权及许可证声明。

English: Licensed under the Apache License 2.0. You may use, modify, and distribute this project subject to its terms, including the required notices.