HL-Mem
中文
HL-Mem 是面向 AI Agent 的本地优先、证据驱动长期记忆系统。它不只是向量数据库：系统把不可变事件提取为带证据链的结构化 Claim，以有效时间和记录时间描述事实变化，并通过独立的 Experience 通道保存 Episode、Trace 和可复用 Policy。默认使用 SQLite WAL、FTS5 和向量 BLOB，无需部署外部数据库服务。
五分钟上手
需要 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 官方发行版通常已包含。
启用在线模型
从源码仓库复制 config.example.toml 和 .env.example，或直接编辑 hl_mem.toml。把启用组件的独立密钥写入 .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
安装包同时提供官方 SDK 2.x 的 stdio MCP 入口 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 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 或同名进程环境变量读取。常用键如下，完整列表见
配置参考。
| TOML 键 | 代码默认值 | 说明 |
|---|---|---|
database.path |
var/hl_mem.db |
SQLite 数据库路径 |
extraction.mode |
fake |
提取器：fake、real 或 llm |
embedding.mode |
fake |
向量化：fake 或 real |
reranker.mode |
off |
重排：off、fake、on 或 real |
image_describer.mode |
off |
图片描述：off 或 on |
llm.provider |
dashscope |
dashscope、zhipu 或 openai_compatible |
llm.structured_mode |
json_object |
auto、json_object 或 json_schema |
index.text_mode |
legacy |
legacy、value_only、natural 或 answerable |
recall.query_expansion_mode |
auto |
多查询召回：off、auto 或 always |
relation.discovery_mode |
off |
关系发现：off、audit 或 auto |
recall.tag_channel_enabled |
false |
是否启用独立 Tag 检索通道 |
真实组件和外部调用路径必须提供各自密钥；失败时不会自动切换为 fake。任意 HL_MEM_* 环境变量都不再参与应用 Settings 配置。
代码默认值与示例部署配置刻意分离：Settings 的 recall.default_limit / recall.relevance_reranker_floor 仍为 20 / 0.4，而仓库 TOML 与 config.example.toml 显式覆盖为 5 / 0.15，并保持 recall.relevance_keep_top1 = true。query expansion 使用独立可配置模型，单次/总超时为 5/6 秒。
能力概览
- 记忆正确性：幂等事件摄入、事务原子写入、精确/语义去重、确定性冲突规则、LLM 灰区归并和受守卫的冲突终态收敛。
- 提取治理：确定性的 scope 降级、从规范属性执行 predicate 投影、subject 守卫隔离无效主体，以及有界结构化输出修复。
- 时间与证据：有效时间与记录时间双时间模型、证据链、实体归一化、显式遗忘和 stale 传播。
- 混合召回：中文 FTS5、稠密向量、RRF 融合、多因子排序、可选 Reranker、关系/查询扩展和按 Token 预算打包上下文。
- 生命周期：importance 联动 TTL、置信度衰减、归档、重分类、反馈效用、审计日志和在线备份。
- 经验通道：Episode、Trace、Reward、Policy/Procedure 和派生 Observation。
- 接口：FastAPI REST 与 Hermes Provider 为稳定主路径；七工具 MCP stdio 接口处于 Beta。
- 评测：离线提取/召回/生命周期指标、召回诊断、索引文本受控 A/B、跨模型提取 Benchmark 和 LongMemEval 适配器。
能力成熟度、默认开关和证据见 能力矩阵，架构与数据流见 架构文档。
项目状态
- Stable：事件与证据链、原子写入、LLM 提取、Embedding、FTS + Dense + RRF、双时间过滤、TTL/衰减/归档、冲突与去重、REST、Hermes、备份与审计。
- Beta：多查询召回、关系候选发现、反馈驱动维护、语义去重审计、MCP Server、Benchmark 与 LongMemEval。
- Experimental：图片证据、提取预过滤、独立 Tag 通道、PostgreSQL 连通性探针。
当前基线为 v0.21.2，共 36 个不可变、仅向前执行的 Migration。
文档
| 文档 | 内容 |
|---|---|
| 文档索引 | 所有维护中文档的导航 |
| 配置参考 | TOML 键、默认值、允许值与密钥边界 |
| 架构 | 分层、模块、写入/召回管线、存储和生命周期 |
| API | REST 端点和请求约定 |
| MCP | stdio 启动参数、Codex/Claude/Cursor 配置与工具错误语义 |
| 服务监督与健康检查 | 跨平台健康探针及 systemd、Windows、容器部署示例 |
| 兼容性策略 | 版本和公共契约保证 |
| 能力矩阵 | 成熟度、默认值和验证证据 |
| 变更日志 | 发布历史 |
Contributing / 贡献指南
欢迎通过 Issue 报告缺陷或提出功能建议。提交前请搜索是否已有同类 Issue，并附上复现步骤、预期行为、实际行为、环境信息和必要日志。Pull Request 应聚焦单一改动，说明动机与验证结果，并在行为或公共契约变化时同步更新测试和文档。
开发环境与检查命令：
git clone git@github.com:lohr13/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.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file hl_mem-0.21.2.tar.gz.
File metadata
- Download URL: hl_mem-0.21.2.tar.gz
- Upload date:
- Size: 1.4 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
b17649f5a1ce1ea8f1e0f3c964c77169e64b75055777ae8c7ff48d459087bc64
|
|
| MD5 |
053f4753eaf134ad5416deb2811b0826
|
|
| BLAKE2b-256 |
344caa028a4fd7f2a8a93c65cf061c9355ce37e46b3a1ce6813b1b3df71a9082
|
Provenance
The following attestation bundles were made for hl_mem-0.21.2.tar.gz:
Publisher:
publish.yml on lohr13/hl_mem
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
hl_mem-0.21.2.tar.gz -
Subject digest:
b17649f5a1ce1ea8f1e0f3c964c77169e64b75055777ae8c7ff48d459087bc64 - Sigstore transparency entry: 2340024446
- Sigstore integration time:
-
Permalink:
lohr13/hl_mem@722e21eba0ebb4a4944242d901d2876894a96fbf -
Branch / Tag:
refs/tags/v0.21.2 - Owner: https://github.com/lohr13
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@722e21eba0ebb4a4944242d901d2876894a96fbf -
Trigger Event:
push
-
Statement type:
File details
Details for the file hl_mem-0.21.2-py3-none-any.whl.
File metadata
- Download URL: hl_mem-0.21.2-py3-none-any.whl
- Upload date:
- Size: 343.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
bc49eb4c8f2bb0778e26891c99f3a85d1f58a3234efc3a544862347cddf54d20
|
|
| MD5 |
e61a82bd0a8c8624e52ed610a63df4ca
|
|
| BLAKE2b-256 |
37c10be831541f9d3008d46f6f0e583f038a7eb27b816c56fcffc42d2ea3810a
|
Provenance
The following attestation bundles were made for hl_mem-0.21.2-py3-none-any.whl:
Publisher:
publish.yml on lohr13/hl_mem
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
hl_mem-0.21.2-py3-none-any.whl -
Subject digest:
bc49eb4c8f2bb0778e26891c99f3a85d1f58a3234efc3a544862347cddf54d20 - Sigstore transparency entry: 2340024459
- Sigstore integration time:
-
Permalink:
lohr13/hl_mem@722e21eba0ebb4a4944242d901d2876894a96fbf -
Branch / Tag:
refs/tags/v0.21.2 - Owner: https://github.com/lohr13
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@722e21eba0ebb4a4944242d901d2876894a96fbf -
Trigger Event:
push
-
Statement type:
