lean-memory 是一个嵌入式、本地优先的智能体记忆系统，无需服务器、守护进程或强制云密钥。它从自然语言中抽取事实，存储在每个命名空间对应的 SQLite 文件中，并通过稠密与稀疏混合检索进行召回。旧事实永远不会被删除，而是被取代，并可在任意过去时间点查询。它开箱即用可完全离线运行，可选组件能解锁真实模型质量。
主要能力：
- 记忆抽取：每次 mem.add() 运行四遍混合抽取流水线：规则（正则与 dateparser 处理常见谓词）、GLiNER2 开放词汇 NER 候选生成、路由器（召回偏置升级，低置信度、共指和推理性事实升级到 LLM 通道）、LLM 类型化（通过本地 Ollama 模型进行约束关系类型化）。
- 矛盾检测：按成本从低到高运行（槽位匹配 → 余弦 → 词元包含 → LLM）。冲突事实被取代而非删除，旧事实保留 is_latest=False 和 superseded_by 指针。
- 实体身份解析：基于规范化名称键（NFC + Unicode 大小写折叠 + 空白折叠），使 Acme、ACME 和 acme 视为同一主体，支持完整 Unicode 折叠，标点和变音符号刻意不折叠。
- 检索：融合两阶段 Matryoshka 稠密搜索（256 维粗 KNN → 全维重打分）与 BM25 稀疏搜索，应用 RRF 融合，用交叉编码器重排，并以显著性衰减评分（0.6·相关性 + 0.2·新近度 + 0.2·重要性）。
使用方式：
- MCP 服务器：给任何 MCP 智能体持久本地记忆，三个工具（memory_add、memory_search、memory_clear），每个命名空间一个 SQLite 文件，数据不离开本机。首次运行会下载三个开放模型（总计约 2.0 GB：Qwen3-Embedding-0.6B、Ettin-32M 重排序器用于检索，加上 GLiNER2-base 约 0.8 GB 用于真实抽取，均无需门控）。可先预热一次，避免 MCP 客户端等待下载。
- 数据根目录：LM_DATA_ROOT（默认 ~/.lean_memory）。也支持仅离线，服务器会机会性地升级已安装额外组件所对应的后端（[models] → 真实嵌入器 + 重排序器，[extract] → GLiNER2 抽取），否则回退到确定性桩后端（适合 CI，但真实使用中语义无意义——建议安装 [mcp,models,extract]）。
- 可选 [llm] 额外组件：标准 [mcp,models,extract] 安装没有 LLM 类型化通道，约 15% 升级的候选（几乎都是推理性事实）由确定性桩而非模型类型化。断言性事实不受影响；推理类型事实在默认路径上实际上是二等公民。添加 [llm]（本地 Ollama 模型）可将该升级层升级为真实的约束类型化。
- 睡眠时间维护与审查：一个离线任务，在非高峰时段运行，去重、摘要、降级低价值记录，然后将判断性操作交给用户次日早上在 Web 控制台或 Claude Code 中点击确认。CLI（lean-memory-maintain）是主要触发器，默认 dry-run，报告将执行的操作而不写入任何内容。--root 默认 $LM_DATA_ROOT；添加 --namespace NS 可只运行单个命名空间。可通过 crontab 安排夜间 3 点运行安全频段。
- 次日审查：判断性操作（近重复合并、摘要、驱逐）暂存为提案，在批准前存储的记忆不会改变。运行 /review-memory 插件命令（或在控制台服务器上调用 review-memory-maintenance MCP 提示），Claude 会按实体分组引导用户处理队列，提供前后证据，仅记录用户给出的裁决。四个 MCP 工具支持：memory_maintenance_run（默认 dry-run）、memory_maintenance_status、memory_review_queue 和 memory_review_decide，在核心 lean-memory-mcp 服务器和两个控制台 MCP 界面上均可用。设置 LM_MAINT_AUTO=1 可选择加入后台自动运行（仅安全频段），默认关闭。
- 控制台审查页面：同一队列按实体分组，每个提案有前后证据（近重复为两个文本 + 余弦，摘要为来源 + 建议文本，驱逐为评分证据），操作动词包括 Approve / Keep / Edit-then-approve / Promote，支持按实体批量批准，以及运行维护按钮（默认 dry-run；应用需确认）。两个前端驱动同一提案存储，采用比较并交换决策，避免重复应用。
安全性：任何内容都不会被删除——维护只会追加、退役（使用与普通取代相同的 superseded_by 翻转）或降级到冷层，因此完整历史仍可按任意过去时间点查询，存储谓词逐位相同并由可执行测试固定。只有两个转换自动应用：精确重复退役和严格驱逐频段；所有判断性操作都暂存供人工处理，未审查的提案在 30 天后过期而非自动应用——沉默从不代表同意。冷降级事实仍可通过 as_of 查询和 search(..., include_cold=True) 访问，提升回热层仅限显式操作，因此读取永远不会持久改变智能体所见内容。
适用场景：需要为本地或 MCP 智能体提供持久记忆、且重视数据不出本机和完整历史可追溯的个人或团队；适合离线环境、CI 测试，以及需要人工审核记忆维护的场景。
限制：默认后端是离线桩，语义无意义；生产级检索需安装真实模型。标准安装缺少 LLM 类型化通道，推理性事实由桩处理。实体名称规范化不折叠标点和变音符号，且仅大小写不同的两个真实不同主体（如 Mercury 行星与水银）会合并为一个。公开基准测试运行（LongMemEval/LoCoMo）被有意推迟到发布之后。
