Lorekeeper

Lorekeeper

为 AI Agent 提供可自我改进的记忆。一条命令，无需云服务或配置。

pip install lorekeeper-mcp && lorekeeper setup && lorekeeper

你的 Agent 能跨会话记忆——而且记忆会变得更好，而不只是更多。 本地运行。无需 API 密钥。无需注册。永久免费运行。

---

为什么选择 Lorekeeper

每次 AI Agent 会话开始时都是一片空白。你每次都要重新解释上下文、重述偏好、重新讲解模式。

CLAUDE.md 和 .cursorrules 这类文件有所帮助，但需要手动维护，无法自行搜索，而且会逐渐过时。云服务虽然可用，但会把会话数据传出你的设备，而且每次 API 调用都要付费。库功能强大，但集成工作得由你自己完成。

Lorekeeper 则采用了不同的方式：**一个只需 pip install 一次的本地 MCP 服务。**它可连接你现有的 Agent，将记忆存储在你自己磁盘上的 SQLite 中，并在每次会话中不断改进：

Agent uses a memory → rates it useful or not →
scores adjust automatically → weak memories decay →
strong memories surface more often → search gets sharper

全新安装和使用了六个月的安装，**确实是两种截然不同的产品。**使用时间越长，噪声就越少——你的 Agent 也越像是真正了解你的代码库。

---

快速开始

3 分钟即可完成，无需任何配置：

# 1. Install
pip install lorekeeper-mcp

# 2. Configure your agents (auto-detects Hermes, Claude Code, Cursor)
lorekeeper setup

# 3. Start the MCP server
lorekeeper

lorekeeper setup 会扫描已安装的 Agent，并自动注入 MCP 条目、Agent 提示词和捆绑技能。使用 --check 可预览而不写入。运行 lorekeeper --help 或 lorekeeper --version，验证安装是否成功。

然后向你的 Agent 提问：

“请记住，我更喜欢使用 curl -vX GET 调试端点。”

它会调用 lore_remember → 存储记忆。下次会话：

“我常用的调试命令是什么？”

它会调用 lore_search → 检索记忆。✅

完整操作指南 → 文档/快速入门

---

功能

功能	说明
混合搜索	语义向量 + BM25 关键词 + 时间衰减 + 使用频率 + 记忆评分——全部通过加权公式排序
自我改进	lore_update 反馈会调整评分。糟糕的记忆会逐渐淡去（置信度 <2 且无用 → 软删除）。有用的记忆则会提升。
自动关联	新记忆会自动关联到语义上最接近的记忆。无需费力即可形成轻量级知识图谱。
重复项检测	新增内容会与现有记忆进行比对。近乎相同的内容会被拦截（可使用 force=true 覆盖）。
仪表板	完整的 Web 界面——可浏览、搜索、编辑和删除。包含七个选项卡，其中包括支持重复项预览的备份/恢复功能。
通用 MCP	适用于 Claude Code、Cursor、Hermes、Copilot、OpenCode，以及任何兼容 MCP 的 Agent。
本地优先	数据保留在你的设备上。使用 SQLite + LanceDB。无需依赖云服务，也无需 API 密钥。
命名空间	多个 Agent 可通过隔离的命名空间共享同一个存储库。写入内容会进入各自的命名空间；读取时会包含共享池中的内容。
反思	Agent 会自动从会话中提取经验。发现和教训会成为可搜索的记忆。

---

使用场景

在不同会话间延续上下文

你周一搭好了认证层。到了周三，换了个 Agent 从头开始，对一切都一无所知。有了 Lorekeeper，它已经知道中间件路径、令牌格式，以及哪个测试覆盖了边缘情况——因为你只告诉过它一次。

"Remember that our JWT uses jose middleware in src/middleware/auth.ts
 and refresh tokens expire in 7 days."
→ lore_remember stores it
→ Every future session, on any agent: already in context

一个记忆池，多个 Agent

Claude Code 用于审查，Cursor 用于实现，Hermes 用于规划——它们不该每次都从零开始。Lorekeeper 的命名空间让它们共享同一个存储。一个 Agent 的发现，就会成为所有 Agent 的知识。

→ Engineer agent notes a performance quirk in the search service
→ lore_remember stores it under the shared namespace
→ PM agent surfaces it during sprint planning
→ No briefing, no copy-paste

跨会话调试

三周前，你修复了一个隐蔽的 CORS 漏洞，Agent 当时也帮了忙。现在你们谁都不记得细节了。

"What did we figure out about the CORS issue?"
→ lore_search returns the root cause, the fix, and the context around it

项目入门

新的代码仓库，新的 Agent 会话。无需重新解释架构，你只需在第一次会话后运行几次 lore_remember 调用。下一次会话，以及之后的每个 Agent，都能从正确的基础开始。

"Remember: the payment service requires X-Idempotency-Key on all POST requests."
→ Claude Code, Cursor, and Codex all read from the same store

---

适用对象

如果你在使用以下工具，这很适合你：

• Claude Code，并希望它能在不同会话间记住项目上下文
• Cursor，并希望拥有持久的 Agent 记忆
• Hermes、OpenCode、Codex CLI、Copilot CLI，或任何兼容 MCP 的 Agent
• 多个 Agent，并希望它们共享知识

如果符合以下情况，目前可能不适合你：

• 你需要团队 RBAC、审计日志或 SSO（将在 Beta 之后推出）
• 你正在构建面向消费者的 AI 应用（我们以 Agent 为先，而非以 API 为先）
• 你不使用 AI 编码 Agent（Lorekeeper 是一款 MCP 工具）

---

对比

这个领域有很多优秀的工具，各自做出了不同的取舍。下面是 Lorekeeper 的定位：

	基于文件	云服务	Docker 服务	库（Mem0）	agentmemory（Node）	Lorekeeper
设置	内置	API 密钥 + 云配置	docker compose	编写集成代码	npx agentmemory	pip install
数据	本地	云端	本地	由你决定	本地	本地
搜索	grep	向量	向量	向量	混合	混合 + 时间衰减 + 使用情况 + 评分
自我改进	❌	❌	❌	❌	❌	✅ 质量循环
知识图谱	❌	付费	❌	付费	❌	✅ 免费自动关联
仪表板	❌	✅	❌	❌	查看器	✅ 完整 Web UI
依赖项	无	~300MB	~2GB	~1.4GB	~200MB	~1.4GB（嵌入模型）
由 Agent 构建	❌	❌	❌	❌	❌	✅ 每日实战使用

云服务和基于 Docker 的解决方案是团队或生产应用的可靠选择。Lorekeeper 针对的是另一端：独立开发者和 Agent 工作流；对他们而言，零运维、零云服务和可自我改进的存储最为重要。

**依赖项说明：**约 1.4GB 的体积来自 sentence-transformers 嵌入模型（PyTorch）。这与任何本地嵌入方案的体积处于同一量级。我们会如实说明。

---

MCP 工具

Lorekeeper 提供 10 个 MCP 工具，覆盖完整的记忆生命周期：

工具	用途
lore_search	结合语义和关键词的混合搜索，并提供相关性评分
lore_remember	快速保存单条记忆（自动生成标题、自动建立链接）
lore_insert	批量插入结构化内容，并自定义评分和链接
lore_update	反馈循环——为记忆评分，提升质量
lore_forget	软删除错误或过时的记忆
lore_reflect	会话结束时提取经验，并自动保存发现
lore_processed_sessions	检查哪些会话已处理
lore_recommend_links	为相关记忆推荐候选链接
lore_get_suggestions	列出扫描引擎生成的待处理链接建议
lore_review_suggestion	接受或拒绝一条或多条链接建议（批量处理）

完整 API 参考 → docs/api-reference.md

---

仪表板

本地 Web UI，可浏览、搜索、编辑和管理记忆库。

lorekeeper-dashboard
# → http://127.0.0.1:7777

七个选项卡：

选项卡	功能
记忆	可排序表格，支持实时筛选——标题、评分、置信度、使用次数、日期
详情	编辑记忆内容、管理其链接，以及软删除或硬删除
链接	浏览知识图谱——源 → 关系 → 目标
查询	临时语义和关键词搜索，并显示每条结果的评分明细
会话	所有已处理的 Agent 会话及提取的经验
配置	实时调整搜索权重、质量阈值和限制
备份	将记忆导出为 JSON 或从 JSON 导入，并预览去重结果
建议	查看扫描引擎生成的 AI 链接候选项——逐条或批量接受、拒绝

建议选项卡

建议选项卡会显示后台扫描引擎自动生成的链接候选项。每个候选项由一对引擎认为相关的记忆组成，并根据余弦相似度、BM25 关键词重叠度、实体共现情况和时间接近度进行评分。

工作流：

1. 扫描引擎按可配置的时间间隔运行（LORE_SUGGEST_INTERVAL_HOURS，默认值为 12）。
2. 候选项会显示在建议选项卡中，并按分数从高到低排序。
3. 点击 ✓（或选择多行后点击 接受所选项），即可在两条记忆之间创建永久链接。
4. 点击 ✗（或 拒绝所选项）即可忽略该候选项——未来扫描不会再次显示已拒绝的配对。
5. 使用配置选项卡中的 立即触发扫描，即可立即运行扫描，无需等待时间间隔。

扫描配置（通过带 LORE_ 前缀的环境变量或配置选项卡设置）：

设置	默认值	说明
LORE_SUGGEST_INTERVAL_HOURS	12	扫描运行的频率（小时）
LORE_SUGGEST_MIN_SCORE	0.55	显示候选项所需的最低加权分数
LORE_SUGGEST_MAX_CANDIDATES	500	每次扫描运行的候选项上限
LORE_SUGGEST_TTL_DAYS	30	未审核建议的清理等待天数

---

由 Agent 构建，为 Agent 服务

Lorekeeper 是借助 AI Agent 开发的——包括 Claude Code、Hermes 和我们自己的 Agent 团队。开发周期本身就是一场实际演示，展示了它的功能：

agent builds a feature → uses Lorekeeper to capture what it learned →
searches those memories next session →
builds the next feature with the context already there

这不是营销宣传语。Lorekeeper 中的每个工具架构、返回类型和工作流，都是由每天使用它的 Agent 打磨出来的，而不是由阅读规范的人工开发者设计的。遇到使用不便之处，我们就做出改进。搜索结果出现噪声时，我们就调整权重。这个产品之所以成为现在的样子，是因为构建它的 Agent 也依赖它。

本仓库记录的 Agent 式开发循环，就是我们实际的工作方式；Lorekeeper 也旨在帮助你采用这种方式。

---

面向开发者

克隆项目、从源代码运行，或参与贡献：

git clone https://github.com/Jessinra/Lorekeeper.git
cd Lorekeeper
bash scripts/setup.sh

# Tests
uv run pytest

# Lint
uv run ruff check src tests

# Type check
uv run mypy src

# Dashboard dev
uv sync --extra dashboard
uv run lorekeeper-dashboard

项目结构

src/lorekeeper/
├── __main__.py          # Entrypoint — init_service() + mcp.run(stdio)
├── server.py            # FastMCP tool definitions (8 tools)
├── config.py            # Settings (pydantic-settings, LORE_ prefix)
├── models.py            # Pydantic models
├── dashboard/           # Web UI (FastAPI + uvicorn)
└── services/
    ├── orchestrator.py  # MemoryService — coordinates sub-services
    ├── memory_engine.py # Vector store abstraction
    ├── lancedb_engine.py# LanceDB backend
    ├── link_store.py    # SQLite — memories, links, suggestions
    ├── keyword_index.py # BM25 index
    ├── search.py        # Hybrid ranking
    └── ...

关键配置

所有设置均可通过带 LORE_ 前缀的环境变量或仪表板的配置选项卡进行配置：

变量	默认值	说明
LORE_DATA_DIR	~/.lorekeeper	数据目录（SQLite + 向量）
LORE_NAMESPACE	shared	Agent 命名空间——写入时限定作用域，读取时与 shared 合并
LORE_SEARCH_LIMIT	5	lore_search 的默认结果数量
LORE_LINK_TOP_M	10	lore_recommend_links 返回的候选项上限
LORE_LINK_SCORE_THRESHOLD	0.3	显示链接候选项所需的最低分数
LORE_LINK_TEMPORAL_TAU_DAYS	30	时间接近度评分的衰减半衰期（天）

完整列表 → src/lorekeeper/config.py 和 CLAUDE.md。

---

性能

LongMemEval-S 的全部 500 道问题，使用默认混合权重（sem=0.45，kw=0.30）：

指标	数值	延迟
R@1	84.6%	32.9 毫秒/查询
R@3	93.6%
R@5	96.6%
R@10	98.8%

完整的分类结果 → docs/research/2026-06-11-retrieval-benchmark-results.md

---

许可证

Apache-2.0 — 请参阅 LICENSE。

---

由 Agent 为 Agent 打造。 宣言 · 策略

上次验证时间：2026-06-20