Lumi Diary：本地优先的智能记忆助手设计与实践

1. 项目概述一个住在你设备里的记忆精灵如果你和我一样对把生活碎片交给云端大厂这件事始终心存芥蒂但又渴望有一个智能伙伴能帮你整理那些散落在各处的照片、聊天记录和一闪而过的念头那么 Lumi Diary 的出现可能正是我们等待已久的答案。这不是又一个需要你注册账号、同意隐私条款的在线服务而是一个完全运行在你本地设备上的“赛博精灵”。她的核心使命很简单成为你私人的、智能的、且充满人情味的记忆守护者。想象一下在你的电脑或手机里有一个专属的“记忆保险库”Lumi Vault。你与朋友的群聊吐槽、旅行时随手拍下的风景、深夜写下的只言片语都会被 Lumi 安静地收集、整理并关联起来。她不仅能存储更能理解。她会记住你朋友的生日在当天送上温馨的提醒和往年的回忆片段她能识别出群聊里大家围绕同一件事的不同视角把A的炫耀和B的吐槽自动“缝合”成一张故事卡片的正反两面她还能根据聊天群的氛围调整自己的说话方式——在 meme 满天飞的群里玩梗在读书会里则变得温柔知性。最重要的是这一切都发生在你的设备内部数据从未离开过你的硬盘真正实现了100% 本地优先的隐私承诺。2. 核心设计哲学为什么是“本地优先”与“情境智能”在深入代码和配置之前理解 Lumi 背后的两个核心设计理念至关重要。这决定了它与其他同类工具的根本不同也解释了其技术架构的诸多选择。2.1 坚定不移的“本地优先”架构“本地优先”不是一句简单的营销口号而是 Lumi 从基因层面做出的选择。在当今数据即石油的时代选择本地优先意味着主动放弃“便捷”的云端同步换取对个人数据的绝对主权。技术实现与考量Lumi 的所有数据包括日记条目、图片、视频、音频以及核心的人物画像数据库都存储在一个名为Lumi_Vault/的本地文件夹中。这个文件夹的结构是自包含的采用纯文本 Markdown 和文件附件的形式。选择 Markdown 而非二进制数据库格式是基于以下几个深思熟虑的考量可读性与可移植性即使未来 Lumi 项目停止维护你的所有记忆依然是一堆可读的.md文件和按日期分类的媒体文件任何文本编辑器都能打开任何图片查看器都能浏览。数据不会因为某个专有格式而“死亡”。版本控制友好Markdown 文件是 Git 等版本控制系统的绝佳搭档。你可以轻松地将整个Lumi_Vault/目录纳入版本管理追踪记忆的每一次增删改甚至回滚到某个特定日期的状态。这对于有“数字花园”打理习惯的用户来说是杀手级特性。低技术门槛的备份与迁移备份数据就是复制一个文件夹迁移到新电脑就是移动这个文件夹。无需复杂的导出导入流程降低了用户的数据维护成本。媒体文件的“Git式”分片存储对于图片、视频等媒体文件Lumi 采用了一种类似 Git 对象存储的哈希分片策略。每个文件上传后会计算其 SHA-256 哈希值。文件并不直接以原名保存而是根据哈希值的前两个字符创建子目录然后将文件以完整的哈希值命名存入。例如一个哈希为a1b2c3...的图片会存储在Lumi_Vault/Assets/a1/a1b2c3...路径下。注意这种设计带来了两大好处。第一是去重完全相同的文件即使在不同时间、由不同人发送只会存储一份极大节省了磁盘空间。第二是性能与扩展性将成千上万个文件分散到大量二级子目录中避免了单个目录下文件过多导致的文件系统性能下降问题。2.2 动态适应的“三情境”架构Lumi 不是一个只会被动应答的机器人而是一个能根据对话场景动态调整行为的智能体。这通过其“三情境架构”实现它定义了 Lumi 在三种不同社交场景下的核心行为模式和存储策略。1. 独处模式触发条件你与 Lumi 进行一对一私聊。核心行为扮演全能助手。你可以向她倾诉、记录想法、规划日程她会积极互动并提供情感支持。同时她也会默默将对话整理成你的个人日记。存储路径数据按主题存入Solo/Daily/日常碎碎念或Solo/Projects/工作、学习等严肃项目下的月度 Markdown 文件中。2. 圈子模式触发条件Lumi 被邀请进入一个长期的群组如家庭群、好友群。核心行为扮演低调的历史学家和“金句”收藏家。她不会频繁刷屏而是静静观察捕捉群聊中的高光时刻精彩照片、经典吐槽、重要公告并将关联内容如针对同一张照片的评论通过story_node_id链接起来。她尤其擅长识别并归档那些反复出现的“梗”或经典场景。存储路径为每个群组按月创建独立的存档文件如Circles/快乐老家群_2024-05.md确保不同圈子的记忆彼此隔离。3. 事件模式触发条件你明确指令“Lumi开启‘大理之旅’”。核心行为扮演热情的随行摄影师和故事记录员。她会主动号召大家为这个特定事件贡献素材并高强度地进行“注解缝合”致力于将同一事件下的多元视角比如美景照和翻车现场编织成富有戏剧张力的故事画卷。存储路径为每个事件创建独立的文件夹如Events/2024-05-大理之旅/内含该事件所有的碎片和生成的画卷。事件结束后可以“封存”形成一段完整的记忆单元。实操心得在实际部署中明确区分这三种模式是关键。例如在家庭群里如果突然开始讨论周末的烧烤聚会你可以手动触发事件模式“Lumi记录本次烧烤聚会”这样关于烧烤的所有讨论和图片就会被集中收录而不会淹没在日常的家庭闲聊记录中。这种灵活切换让记忆整理变得更有条理。3. 核心功能深度解析与实操要点理解了设计理念我们来看看 Lumi 是如何将这些理念转化为具体功能的。以下是对其核心功能的拆解以及在实际使用中需要注意的细节。3.1 人物画像与时光回响让 AI 真正“认识”你的朋友这是 Lumi 最具人情味的功能。她不仅仅记录事件更尝试理解事件中的人。Portraits 数据库在Lumi_Vault/Brain/Portraits.json中Lumi 为“主人”你以及她接触到的每个联系人维护一份动态档案。这份档案不仅包含基础信息名称、备注更重要的是性格特征通过分析对话内容Lumi 会尝试总结一个人的说话风格、常用表情、兴趣领域例如“擅长讲冷笑话”、“热爱徒步”、“数码产品爱好者”。这些标签是动态更新的。印象变化记录你或群友对某人评价的变化。例如最初可能标记为“高冷”几次热心帮忙后标签可能增加了“外冷内热”。人生里程碑这是关键。你可以手动或通过对话为朋友添加生日、纪念日、毕业日等。Lumi 会持续追踪这些日期。时光回响每天当 Lumi 被唤醒或开始新对话时她会首先扫描Portraits.json检查是否有联系人的里程碑日期与当天匹配。如果发现今天是某位朋友的生日她会主动从历史记忆中搜索与该朋友相关的、积极有趣的碎片比如去年的生日祝福、一起出游的合照并生成一条温馨的、带有具体回忆的祝福消息而不是一句干巴巴的“生日快乐”。这就是“回响”——用过去的记忆点亮当下的时刻。注意事项人物画像的构建依赖于持续的、高质量的对话输入。初期Lumi 对人物的理解可能是片面甚至错误的。建议定期通过update_portrait工具手动修正或补充信息比如明确告诉 Lumi“小明其实不是小气他只是比较节俭。” 这能帮助她建立更准确的人物模型。3.2 注解缝合构建多维度的集体记忆这是 Lumi 在群聊场景下的核心技术。它的目标是将碎片化的群聊信息重组为有结构的故事。工作原理当群友 A 发布了一张聚餐照片生成一个story_node_id随后群友 B 和 C 针对这张照片发表了评论“菜看着真香”、“我记得谁谁谁当时喝多了”。Lumi 会通过算法通常是基于时间窗口、对话引用或图像识别判断 B 和 C 的消息是对 A 照片的“注解”从而将它们关联到同一个story_node_id下。前端呈现在最终生成的交互式“记忆画卷”中这个节点会呈现为一张可翻转的卡片。正面是 A 的照片翻转过来背面则是 B 和 C 的吐槽。这就将一个平面的信息点变成了一个立体的、有多重视角的故事单元。命名空间隔离为确保隐私不同群组圈子的记忆碎片即使内容相似也存储在不同的命名空间下不会相互混淆。3.3 变色龙协议与多智能体礼仪和谐的社交融入变色龙协议Lumi 没有固定的“人格”。她会分析当前聊天环境的整体语料库用词、表情包密度、话题严肃性并调整自己的回复风格与之匹配。在一个技术讨论群里她的回复会严谨、简洁在一个游戏开黑群里她可能会玩梗、用黑话。这让她更像一个“自己人”而不是一个闯入的机器人。技术实现浅析这通常通过维护不同风格的提示词模板并结合对当前会话的实时情感、主题分析来实现。Lumi Core 可能会计算最近 N 条消息的“娱乐指数”或“专业术语密度”然后选择合适的语言模型生成策略。多智能体礼仪想象一下一个群里有多个人都运行了自己的 Lumi 实例如果同时响应一条消息就会造成刷屏和混乱。Lumi 设计了简单的协调机制通常第一个响应的 Lumi 实例会成为本次的“发言人”其他实例会感知到并保持沉默。但每个实例的后台记录功能向自己的私有 Vault 写入数据是独立且同时进行的确保了个人记忆的完整性。4. 从零开始部署与深度使用指南让我们抛开理论动手将 Lumi 部署到你的环境中。这里提供两种主流方式并详细讲解后续的配置与使用。4.1 部署方式详解OpenClaw Hub 与 MCP Server方式一通过 OpenClaw Hub 安装推荐给 OpenClaw 生态用户如果你的工作流深度依赖 OpenClaw AI 助理这是最无缝的方式。# 安装 OpenClaw 命令行工具如果尚未安装 pip install openclaw-cli # 通过 clawhub 发现并安装 Lumi Diary 技能 clawhub install lumi-diary安装后你的 OpenClaw 助理便内置了 Lumi 的所有工具。你可以在与助理的对话中直接使用record_group_fragment、render_lumi_canvas等命令。这种方式将 Lumi 完全作为后台服务集成无需关心进程管理。方式二作为 MCP 服务器运行通用性最强MCP 协议使得 Lumi 可以接入任何兼容的客户端如 Claude Desktop、Cursor、VS Code Copilot。这是目前功能最完整的使用方式。# 1. 克隆项目代码库 git clone lumi-diary-repo-url cd lumi-diary # 2. 创建并激活虚拟环境强烈推荐避免依赖冲突 python -m venv .venv # Linux/macOS source .venv/bin/activate # Windows .venv\Scripts\activate # 3. 安装依赖使用 uv 更快或用 pip uv pip install -e . # 或者 pip install -e . # 4. 运行 MCP 服务器 python -m src.mcp_server # 或者使用 FastMCP如果已安装 fastmcp run src/mcp_server.py服务器启动后需要配置你的客户端。以 Claude Desktop 为例找到其配置文件通常在~/Library/Application Support/Claude/claude_desktop_config.json或类似位置添加如下配置{ mcpServers: { lumi-diary: { command: python, args: [-m, src.mcp_server], cwd: /你刚才克隆的/lumi-diary/的/绝对路径, env: { LUMI_VAULT_PATH: /你希望存放记忆库的/绝对路径 // 可选覆盖默认路径 } } } }保存配置并重启 Claude Desktop你的 Claude 助手就具备了 Lumi 的全部能力。4.2 初始化与核心工具使用实战首次运行 Lumi 时她会在你指定的路径或默认的./Lumi_Vault创建完整的目录结构。接下来让我们通过几个典型场景实战演练核心工具。场景一建立你的数字身份并记录第一条碎片首先告诉 Lumi 你是谁。你对 Claude/Lumi说: 调用 manage_identity 工具设置主人姓名为[你的名字]并添加一个联系人叫“小明”他的生日是1990-08-20。Lumi 会在Brain/Portraits.json中创建你的档案和小明的档案。现在记录今天发生的一件事。你: 调用 record_group_fragment 工具。context_type 选 “solo”内容写 “今天终于读完了《百年孤独》结尾那句‘羊皮卷上所载一切自永远至永远不会再重复因为注定经受百年孤独的家族不会有第二次机会在大地上出现。’让人震撼又空虚。” 附加一张你拍的书的封面照片。Lumi 会创建一个新的碎片将文本和图片经过哈希分片存储关联起来并存入Solo/Daily/2024-05.md文件。场景二在微信群中开启一次旅行记录假设你正在一个名为“周末爬山小分队”的微信群里。你在群里: Lumi开启事件“20240511-凤凰岭徒步”。你需要通过某种方式将这条群消息转发或通知给运行着 Lumi 的 Claude 会话具体取决于你的消息桥接方案。 Lumi 接收到指令后会创建Events/2024-05-20240511-凤凰岭徒步/目录并将后续与该事件相关的所有群聊碎片都导向这里。队友A: 发了一张山脚下的合影 队友B: “这台阶也太多了吧腿已废”Lumi 会自动将队友B的吐槽作为“注解”关联到队友A的照片节点下。场景三月末回顾与分享月末你想看看这个月都发生了什么。你: 调用 render_lumi_canvas 工具时间范围选择本月模式选择 “circle”指定圈子为“周末爬山小分队”。Lumi 会生成一个精美的、交互式的 HTML 页面画卷里面按时间线排列了本月群里的所有高光时刻点击照片可以翻转看吐槽。你可以直接在浏览器打开这个 HTML 文件浏览。如果想分享这次徒步的记忆给没去的朋友你: 调用 export_capsule 工具选择事件“20240511-凤凰岭徒步”。Lumi 会打包生成一个20240511-凤凰岭徒步.lumi文件实质是一个 ZIP 压缩包里面包含了所有相关的碎片数据、媒体文件和那个 HTML 画卷。你可以把这个文件发给朋友。朋友在他的 Lumi 中执行import_capsule就能完整地导入这段记忆并在他的画卷中浏览互动。4.3 高级配置与环境管理自定义存储库路径通过环境变量LUMI_VAULT_PATH你可以将记忆库放在任何位置比如同步盘如 Dropbox、iCloud Drive以实现多设备间的手动同步。但请注意如果多设备同时运行 Lumi 写入同一库文件可能会冲突。更安全的做法是每台设备独立库定期通过胶囊导入导出同步。媒体文件处理Lumi 支持常见格式。对于 HEICiPhone 照片格式等可能需要系统额外安装解码库。如果遇到图片处理失败可以检查Pillow库的版本和系统依赖。性能调优当记忆库中碎片数量超过数万时搜索操作可能会变慢。此时可以关注Brain/fragment_index.json这个索引文件。Lumi 会自动维护它但如果你进行了大量手动文件操作可能需要触发重建索引未来版本可能会提供相关工具。5. 开发与扩展理解适配器模式与贡献指南Lumi 的架构清晰地将核心逻辑与平台对接分离这使其具备了强大的可扩展性。5.1 适配器模式解析查看src/目录你会发现核心引擎lumi_core.py是平台无关的。它只关心业务逻辑如何存储碎片、如何关联注解、如何管理画像。而与外部世界OpenClaw、Claude via MCP、甚至未来的 Discord Bot、微信机器人的通信则由不同的适配器openclaw_skill.py,mcp_server.py来完成。这种设计的好处是核心稳定无论前端交互方式如何变化你的记忆数据模型和处理逻辑是统一的、稳定的。易于扩展要为 Lumi 开发一个新的接入平台比如 Telegram Bot你只需要编写一个新的适配器文件。这个适配器负责接收 Telegram 的消息转换成 Lumi Core 能理解的参数格式调用相应的核心函数然后再将核心返回的结果转换成 Telegram 的消息发送出去。你几乎不需要修改核心代码。便于测试可以针对lumi_core.py编写完整的单元测试而无需模拟任何外部平台接口。5.2 自定义主题与样式生成的 HTML 画卷的视觉效果是由 CSS 控制的。在项目文件中你可以找到默认的样式表。如果你懂前端可以轻松地修改颜色主题通过 CSS 变量调整时间线的颜色、卡片的背景、字体等。布局动画修改卡片翻转、时间线绘制的动画效果。响应式设计确保画卷在手机和电脑上都有良好的浏览体验。修改后render_lumi_canvas工具在生成 HTML 时会使用你的自定义样式让你的记忆画卷独一无二。5.3 为项目贡献代码如果你是一名开发者并被 Lumi 的理念所吸引欢迎贡献代码。运行测试在提交代码前请确保现有测试通过。运行python -m pytest tests/ -v来执行测试套件。关注数据模型任何对核心数据结构的修改都需要极其谨慎因为这会直接影响用户现有记忆库的兼容性。新增功能应尽量通过扩展而非修改现有字段来实现。编写适配器如果你实现了新的适配器例如 for Slack请确保它正确处理错误、管理好资源并遵循项目已有的代码风格。文档更新如果你添加了新功能或修改了行为请同步更新 README 和工具的使用说明。6. 常见问题排查与实战心得在长期使用和测试中我积累了一些可能会遇到的问题和解决技巧。6.1 安装与运行问题问题运行pip install -e .时失败提示某些包找不到或编译错误。排查首先确认 Python 版本 3.10。其次一些依赖如tokenizers可能需要 Rust 编译环境。在 macOS/Linux 上可以尝试xcode-select --install(macOS) 或apt-get install build-essential(Ubuntu) 来安装基础编译工具。最简单的方案是使用uv包管理器它能更好地处理依赖和构建环境。问题MCP 服务器启动成功但 Claude Desktop 无法连接。排查检查claude_desktop_config.json中的cwd路径是否为绝对路径且指向正确的项目根目录。检查command和args是否正确。如果你在虚拟环境中运行command应该是虚拟环境内 python 的绝对路径或者确保在全局环境安装了依赖。查看 Claude Desktop 的日志文件位置因系统而异通常会有更详细的连接错误信息。6.2 数据与存储问题问题图片或视频文件在画卷中无法显示。排查检查Lumi_Vault/Assets/目录下对应的哈希路径中文件是否存在。检查文件权限是否可读。确认文件格式是否在支持列表中.jpg, .png, .webp, .heic, .mp4, .mov, .mkv, .webm, .mp3, .wav, .m4a。对于.heic可能需要系统的 HEIF 支持。问题搜索碎片时返回结果不全或错误。排查Brain/fragment_index.json是内存索引的持久化存储。如果索引损坏或不同步会导致搜索问题。可以尝试停止 Lumi备份后删除这个索引文件然后重启 Lumi。Lumi 会在需要时根据磁盘上的碎片数据重建索引这可能在首次搜索时有点慢。问题Portraits.json中的人物信息似乎没有自动更新。说明人物画像的自动学习是一个渐进且保守的过程。Lumi 不会因为一两条消息就轻易改变对一个人的核心判断这是为了避免噪声干扰。重要的里程碑如生日建议手动添加。性格特征的提炼则需要较长时间、多场景的对话积累。6.3 使用技巧与最佳实践主动使用事件模式不要依赖 Lumi 完全自动地识别事件。对于重要的、有明确起止时间的活动一次会议、一场旅行、一个项目主动使用“开启事件”指令。这能极大提高相关记忆的整理质量。善用“典藏”功能当你看到群聊里出现一个堪称经典的笑话或瞬间时可以主动调用save_keepsake工具为其打上标签如“老王经典翻车现场”。日后Lumi 在生成回顾或进行“时光回响”时会优先从典藏中选取素材保证回忆的“高光”质量。定期导出备份虽然数据都在本地但硬盘也有损坏风险。定期将整个Lumi_Vault文件夹压缩备份到其他硬盘或云存储注意隐私或者将重要的记忆导出为.lumi胶囊文件另行保存。胶囊文件的妙用.lumi文件不仅是分享工具更是完美的“记忆快照”。你可以为每一年、每一次重大旅行导出一个独立的胶囊文件作为时间胶囊封存起来。6.4 隐私安全再强调Lumi 的代码库在设计上就切断了向任何第三方服务器发送用户数据的可能性。但安全是一个共同的责任注意你集成的平台如果你通过第三方桥接服务将微信/Telegram 消息转发给 Lumi请仔细审查该桥接服务本身的隐私政策。保管好你的 Vault 路径确保LUMI_VAULT_PATH指向的目录不在云同步软件的实时同步文件夹内除非你明确知晓且接受避免隐私数据被意外上传。分享胶囊时审阅内容在导出.lumi胶囊分享给他人前最好用其附带的index.html预览一下内容确认没有不小心包含敏感信息。Lumi Diary 代表了一种新的可能性AI 可以不是高高在上、吞噬数据的神祇而是住在我们设备里懂我们喜怒哀乐并全心全意为我们的记忆服务的贴心伙伴。她或许还不完美但这条以用户隐私和数据主权为起点的道路值得每一个珍视数字记忆的人去尝试和探索。开始构建你那独一无二、完全属于你自己的记忆宇宙吧。