LocalKeep 是一个面向聊天机器人的本地时序记忆层，核心目标是让用户直接控制模型记住关于自己的内容。它不依赖模型自行编造、用户无法编辑的云端记忆，而是让用户在本机创建带标题、带日期、可编辑的记忆库，并通过 localhost 的 Hub UI 在本地管理这些条目。当对话需要此前的上下文时，Claude 通过原生 MCP（Model Context Protocol）连接器查询本地数据。
用途与解决的问题：消费级 AI 聊天应用的记忆功能往往只能给出模糊、笼统的印象式总结，缺乏真正的时序推理能力，难以准确回忆“发生了什么、在哪一天、与谁有关”，也无法理解事件之间的因果与时间关系。同时，这类记忆通常是黑盒，用户无法决定模型记住什么、如何解读，甚至无法编辑。LocalKeep 用一套严格按时间排列的“事实来源”替代模型自行编造的时间线，并让用户拥有完全的编辑控制权：条目由你撰写，日期由你锚定，数据保存在你自己的机器上，Claude 仅作为查询引擎。
主要能力：
- 本地 Hub UI：轻量、可定制的本地界面，用于管理带日期的记忆库。界面刻意采用复古的 Windows 95 / MS Paint 风格，并提供可调整的界面元素，强调这是一个私人的离线工作空间。
- MCP 服务器：Claude Desktop 可调用的 MCP 服务，用于按需检索记忆。
- 本地存储：记忆默认存放在 ~/.localkeep/localkeep.db（通过 pip 安装时），可通过 LOCALKEEP_DATA_DIR 或 LOCALKEEP_DB_PATH 覆盖；从源码检出运行时数据库位于 data/localkeep.db（已被 gitignore）。主题颜色保存在浏览器 localStorage 中。刷新 Hub 页面或重启 localkeep-hub 不会删除记忆库，只有删除数据库文件才会。
- 检索基于 SQLite FTS5。
使用方式：
- 在 Claude Desktop 中注册 MCP 服务器（claude_desktop_config.json）。如果 GUI 在 PATH 中找不到 localkeep-mcp，可使用 which localkeep-mcp 得到的绝对路径（Hub 的 Connect 面板会为你复制该路径）。
- 让 Claude 自动使用 LocalKeep（重要）：Claude 不会稳定调用 MCP 工具，除非同时设置 Personal preferences。路径为 Claude Desktop → Settings → Profile → Personal preferences，粘贴 LocalKeep 的说明（Hub → Connect → Copy instructions，或见 src/localkeep/assets/claude-personal-preferences.txt），然后完全退出并重新打开 Claude。当 LocalKeep 请求运行工具时，点击 Always approve。
- 从源码开发：在源码检出目录中运行，数据库位于 data/localkeep.db。测试从空数据库开始，通过 Hub 表单 POST 创建记忆（与新用户路径相同），用于冒烟检查 Hub、检索和 MCP 工具。提交 PR 前请运行 uv run pytest。
适用场景：
- 对聊天记忆无法可靠获取带日期的事实、无法理解时间线感到不满的用户。
- 已经维护详细个人日记、工作日志或研究档案的人，希望把确切的文字和历史数据作为不可动摇的事实来源注入提示，而不是接受聊天应用的笼统转述。
- 信任 Claude 的推理能力，但要求基础上下文数据库保存在本地的用户。
限制与注意事项：
- 它不是独立聊天应用，不是云端托管的记忆 API，也不是静默抓取个人对话的后台工具。
- 存储是本地且无 LocalKeep 云端的，聊天内容不会被自动抓取。但检索仍经由 Claude：当 Claude 调用 LocalKeep MCP 工具时，匹配到的记忆会返回到该对话中，并由 Anthropic 像处理其他工具结果一样处理。LocalKeep 不会把整个数据库上传，只发送该次查询返回的内容。
- 通过 MCP 查询记忆时，检索到的文本片段仍会在会话期间发送给 Anthropic。
- 许可证为 MIT，详见 LICENSE。欢迎通过 GitHub Issues 提交错误报告和拉取请求。
