HL-Mem

中文 | English

中文

HL-Mem 是面向 AI Agent 的本地优先、证据驱动长期记忆系统，而不只是一个向量数据库。它把不可变 Event 转化为带证据链的结构化 Claim，以双时间模型记录事实变化，并通过独立的 Experience 通道沉淀 Episode、Trace 与可复用 Policy；默认只需 SQLite，也可按需启用在线模型与 sqlite-vec。

每条记忆都可追溯到不可变的原始事件。

数据如何流动

flowchart LR
    A["Event 摄入<br/>不可变原始事件"] --> B["LLM 提取<br/>7 字段 compact"]
    B --> C["AdmissionPolicy<br/>准入与后处理"]
    C --> D["Claim<br/>证据链 · 双时间"]
    D --> E["混合召回<br/>FTS5 + Dense"]
    E --> F["RRF → Reranker"]
    F --> G["Context Packet / REST / MCP"]

30 秒极速上手

需要 Python 3.11+。前两行在当前终端执行；服务启动后，在另一个终端执行第三行：

python -m pip install hl-mem
hlmem init --offline && hlmem server
hlmem remember "Alice 喜欢深色模式" && hlmem recall "Alice 喜欢什么"

五分钟上手

需要 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 成功，再安装或升级插件：

hl-mem hermes install --hermes-home <HERMES_HOME>
hl-mem hermes upgrade --hermes-home <HERMES_HOME>

省略 --hermes-home 时会从环境变量和常见目录探测 Hermes 根目录。两条命令在目标副本一致时均保持 no-op；install 遇到漂移会拒绝覆盖，upgrade 会先备份既有插件文件再刷新。hlmem doctor 可区分路径正确、路径错误和副本漂移。插件安装到 <HERMES_HOME>/plugins/hl_mem/；完成后必须重启 Hermes。适配器通过本地 HTTP 提供超时、熔断、预取和 Episode/Trace 同步。

常驻部署与 systemd

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

悬空冲突可先只读巡检，再显式应用安全修复；默认命令不修改数据库，--apply 只删除终态且双侧 Claim 均已缺失的 case：

hl-mem conflicts repair-dangling
hl-mem conflicts repair-dangling --apply

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 秒。

向量检索规模指引

默认 sqlite_scan 是两阶段精确扫描，适合约 10 万条 Claim 以内的本地库；实际边界还取决于 embedding 维度、并发和延迟目标。接近或超过该规模时，应安装 hl-mem[sqlite-vec] 并显式设置 recall.vector_backend = "sqlite_vec"，避免把全量向量扫描当作无界生产索引。SQLite 主表仍是权威数据源， sqlite_vec 只维护可重建的派生投影。

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

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

从 v0.27.x 升级

v0.28.3 不新增配置键，也不改变 v0.27 的配置默认值：recall.resurrection_mode = "auto" 与 decay.model = "activation_halflife" 继续生效。若从 v0.26 跨版本升级并希望保持旧行为，仍可显式配置：

[recall]
resurrection_mode = "off"

[decay]
model = "legacy_linear"

升级前停止 API、Worker 和其他写入者，并保留主库的离线副本。首次由 v0.28 打开数据库时会自动执行 migration 043/044；随后应立即运行一次 hlmem backup，它会创建并绑定 <database>.tombstones.db，生成 manifest v2。主库 backup、manifest 与 tombstone ledger 必须作为一组保护；旧 manifest v1 无法证明删除历史， v0.28 restore 会明确拒绝。migration 不裁决存量冲突，也不自动删除历史异常，仍须通过显式 audit/repair 流程处理。

能力概览

评测结果（公开冻结口径）

中文基准的 embedding/reranker 均为 qwen3.7-text-embedding / qwen3-rerank。PerLTQA 直灌语料、不经提取；MemDaily 与中文 E2E 按提取 → 召回 → QA 全链路运行，提取和 QA 均使用 qwen3.7-plus。MemDaily 以 180 条轨迹全量计分。

LongMemEval 三角对照统一使用 deepseek-v4-flash-0731 reader，reader 开启 thinking、judge 关闭 thinking；benchmark reader 与生产 recall/context packing 是不同契约。中文隔离检索和 E2E 的当前运行与 回归口径见评测说明，本地产物命名见结果索引。

已知边界

• 当前模型在 v0.28 source-first 冻结 A/B 中只让 12% 的关系题 packet 获得完整 RAO，entity coverage@5 保持 34.7%，且没有形成可供关系扩展使用的边；因此该关系语义注解方案及 C 系列实验臂均未产品化。 生产仍只使用既有 compact Claim、来源受控的 RAO 渲染和普通 relation expansion，不能假设系统会从平铺文本 自动恢复高密度、方向完备的关系链。

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

项目状态

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

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

文档

Contributing / 贡献指南

欢迎通过 Issue 和 Pull Request 参与。开发环境、七项 CI 预检、数据边界及提交约定见 CONTRIBUTING.md。

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.