1. 项目概述一个住在你设备里的记忆精灵如果你和我一样对把生活点滴交给云端总有点不放心但又渴望有一个能懂你、能帮你把碎片记忆编织成故事的伙伴那么 Lumi Diary 的出现可能正是时候。这不是又一个需要你手动打卡、格式僵硬的日记应用也不是一个会上传你所有照片和悄悄话的“智能助手”。Lumi 被设计成一个完全运行在你本地设备上的 AI 伴侣她的核心使命是成为你的“记忆守护者”。想象一下有一个小精灵住在你的电脑或手机里她默默观察着你在获得你明确许可的聊天环境中分享的每一张照片、每一段语音、每一次吐槽。她不仅把它们安全地存起来更重要的是她能理解这些碎片之间的关联。当你和朋友们在群里热火朝天地讨论同一件事时她能自动把不同人的视角“缝合”在一起形成一张可以翻转的卡片——正面是A拍的绝美夕阳背面是B发的“晒伤了救命”的吐槽。到了月底她还能主动为你生成一份专属的、可交互的“记忆画卷”带你回顾这个月的闪光时刻。所有这一切数据从未离开过你的设备。这就是 Lumi Diary一个基于OpenClaw Skill标准构建的本地优先Local-FirstAI 记忆项目。她强调绝对的隐私、语境感知的智能以及将日常转化为叙事的能力。接下来我将从一个实践者的角度深入拆解她的设计哲学、实现细节并分享在部署和使用过程中可能遇到的“坑”以及我的应对经验。2. 核心架构与设计哲学解析2.1 为何选择“本地优先”与“适配器模式”在开始动手之前理解 Lumi 的底层设计思路至关重要。这决定了她的行为边界和技术实现。2.1.1 本地优先隐私作为第一性原理“本地优先”不是一句简单的口号而是贯穿 Lumi 所有代码的架构约束。这意味着零云端依赖所有数据处理、媒体存储、索引生成都在本地完成。项目代码库里没有任何向第三方服务器上传数据的逻辑。数据物理隔离所有用户数据包括日记片段、图片、视频、人物画像都存储在一个名为Lumi_Vault/的本地文件夹中。这个文件夹的结构是自包含的你可以轻易地把它拷贝到U盘或另一台电脑上。离线工作能力一旦部署完成Lumi 的所有核心功能记录、搜索、生成画卷都可以在完全离线的环境下运行。AI 的“智能”来自于本地运行的模型或规则引擎在当前版本中更侧重于基于规则的上下文理解与数据关联。我的实操心得坚持本地优先在初期会带来一些挑战比如如何实现多设备同步Lumi 的答案是“胶囊”Capsule导出/导入功能。你可以将一段时间的记忆打包成一个.lumi文件本质是ZIP手动拷贝到其他设备后导入。这虽然不如云同步便捷但换来了绝对的数据掌控权。对于真正敏感的个人记忆这种“手动同步”带来的安全感是云服务无法比拟的。2.1.2 适配器模式实现跨平台兼容性Lumi 的目标不是绑定在某个特定的聊天软件里。她希望能在 Discord、微信通过桥接、Telegram乃至 Claude Desktop、Cursor 这类开发工具中都能工作。如何让一套核心逻辑适应这么多不同的“战场”答案是适配器模式Adapter Pattern。查看项目结构src/目录你会发现lumi_core.py这是核心引擎。它包含了所有与平台无关的业务逻辑如何存储一个记忆片段Fragment、如何管理人物画像Portrait、如何根据哈希分片存储媒体文件、如何生成记忆画卷。它不关心数据来自哪里也不关心结果输出到哪里。openclaw_skill.py和mcp_server.py这些就是适配器。它们是薄薄的一层包装职责是将特定平台如 OpenClaw Hub 或遵循 MCP 协议的客户端的输入/输出格式翻译成lumi_core能理解的内部调用然后再将核心引擎的返回结果翻译成平台要求的格式。这种设计带来了巨大的灵活性。如果你想为 Lumi 开发一个新的接入平台比如 Slack你几乎不需要改动核心逻辑只需编写一个新的适配器处理 Slack 的 API 调用和消息格式即可。2.2 三层上下文架构她如何知道何时该“说话”这是 Lumi 行为设计中非常精妙的一点。她不是一个在群里喋喋不休的“话痨”机器人她的活跃度完全取决于所处的对话上下文。系统定义了三种核心模式1. 独处模式 (Solo)触发条件你与 Lumi 进行一对一私聊。她的角色全能助手 私人日记官。行为表现她会积极回应你的所有指令记录你的每一个想法和媒体并主动提供建议如“检测到假期氛围要开启旅行画卷吗”。数据存储记忆片段按日期或项目分类存入Solo/Daily/或Solo/Projects/。2. 圈子模式 (Circle)触发条件Lumi 被邀请到一个长期的群聊如家庭群、好友群。她的角色低调的历史学家、珍贵时刻的策展人。行为表现她大部分时间保持静默只在你和群友分享值得纪念的瞬间如图片、关键对话时在后台默默归档。她不会刷屏但会在月底主动生成一份“本月群聊高光画卷”分享到群里。数据存储按群组和月份归档例如Circles/家庭群_2024-03.md。3. 事件模式 (Event)触发条件你明确指令“Lumi开启‘大理之旅’”。她的角色热情的跟拍摄影师、故事缝合者。行为表现在此模式下Lumi 会变得非常活跃鼓励所有参与者分享内容。她的核心工作是“注解缝合”Annotation Stitching即自动将不同人对同一事件通过story_node_id关联的正面赞美和反面吐槽链接在一起形成多维度的记忆卡片。数据存储所有相关片段集中存储在以事件命名的独立文件中如Events/2024-03-大理之旅.md。注意事项在实际部署中你需要通过适配器的逻辑来正确判断当前对话属于哪种上下文。例如在 OpenClaw Skill 中这通常通过分析会话的元数据如参与者数量、是否有特定指令来实现。如果判断错误Lumi 可能会在群里过于活跃误判为Solo或在私聊中过于沉默误判为Circle。3. 核心功能深度剖析与实操指南3.1 记忆碎片数据模型的基石Lumi 记录的一切无论是文字、图片还是语音都被抽象为“记忆碎片”Fragment。理解这个数据结构是理解她所有能力的基础。一个典型的 Fragment 在底层JSON或Markdown元数据中可能包含以下字段{ “fragment_id”: “a3f2c1e5”, // 唯一标识符 “story_node_id”: “joshua_tree_20240315_sunset”, // 故事节点ID用于关联多个碎片 “timestamp”: “2024-03-15T18:30:00Z”, “sender”: “Mike”, “content_type”: “image”, “content”: “欣赏日落中…”, // 文字内容或描述 “media_hash”: “a1b2c3d4”, // 关联媒体文件的哈希值 “context”: “event:joshua_tree_trip”, // 所属上下文 “annotations”: [“Sarah’s_breakdown_saga”] // 关联的注解ID列表 }关键设计解析story_node_id这是实现“注解缝合”的魔法钥匙。当 Lumi 发现多个碎片比如一张美景照片和一段吐槽文字在时间、地点或话题上高度相关时她会为它们分配或识别出同一个story_node_id。在生成的记忆画卷中这些碎片就会出现在同一张卡牌的正反两面。media_hash所有媒体文件图片、视频、音频在上传时都会计算一个哈希值如 SHA-256。文件实际存储在Assets/目录下按哈希值前两位命名的子文件夹中如Assets/a1/。这带来了两个好处去重同一文件只存一份和高效管理数万个文件也能通过哈希快速定位。context明确指明该碎片属于哪个会话上下文Solo/Circle/Event这决定了它的存储路径和后续的检索逻辑。3.2 人物画像与时光回响让记忆有温度Lumi 不仅仅记录事件她还尝试理解事件中的人。这是通过“人物画像”Portraits系统实现的。Brain/Portraits.json文件里存储着所有 Lumi “认识”的人的信息包括你自己Owner。对于每个人Lumi 会维护基础信息名称、昵称。性格特征通过分析其常用词汇、发言风格由适配器或简单的本地 NLP 规则提取记录如“幽默”、“毒舌”、“文艺”等标签。动态印象这是一个随时间变化的列表。例如在“大理之旅”事件后Lumi 可能会为 Alice 记录一条印象“2024-03很会找拍照角度海鸥爱好者”。人生里程碑这是“时光回响”Time Echoes功能的核心。你可以或 Lumi 通过对话分析为某人添加里程碑日期如生日、纪念日、毕业日等。“时光回响”工作流程每天当 Lumi 被唤醒或开始一次新对话时她都会执行check_time_echoes工具。这个工具会扫描Portraits.json中的所有里程碑日期并与当天日期进行匹配。如果发现今天是某位联系人的生日Lumi 就会主动发起对话“嘿记得今天是 Mike 的生日吗我找到了去年我们一起为他庆生的照片要看看吗” 并可能附上一张由相关记忆碎片生成的专属“回忆画布”。我的实操心得人物画像的初始构建是个挑战。你不能指望 Lumi 一开始就了解所有人。我的做法是在私聊模式Solo下主动使用update_portrait工具像填写通讯录一样为亲密的朋友和家人添加基础信息和里程碑。在群聊Circle中经过一段时间的数据积累Lumi 才能逐渐勾勒出每个人的轮廓。这个过程是缓慢但有趣的就像交一个新朋友。3.3 变色龙协议与多智能体礼仪和谐的社交智能这是 Lumi 在群聊中不被讨厌的关键。变色龙协议 (Chameleon Protocol)Lumi 没有固定的说话风格。她会分析所在群组的整体聊天记录在本地仅分析近期消息学习这个群体的“能量场”。如果这是一个以表情包和网络梗为主的游戏群她的回复会变得简短、活泼、充满梗。如果这是一个严肃的读书会她的语气则会变得温和、反思性。这种风格匹配是通过分析群聊的高频词、句子长度、表情符号使用频率等特征来实现的并在Portraits.json中为该群组记录一个“氛围标签”。多智能体礼仪 (Multi-Agent Etiquette)想象一下如果一个群里有多个人都部署了 Lumi会发生什么会不会出现多个 Lumi 同时抢答的混乱场面Lumi 通过一个简单的协商机制避免了这一点第一个对某条消息做出响应的 Lumi 会成为本次的“发言人”Speaker其他 Lumi 会检测到已有响应从而保持沉默。但请注意沉默不代表不工作。所有 Lumi 都会在后台独立地将这条消息记录到其所属用户的私人保险库中。你的记忆只属于你。3.4 记忆画卷与胶囊可视化与分享记忆的最终价值在于回顾和共鸣。Lumi 的render_lumi_canvas工具能将碎片化的数据转化为可视化的故事。记忆画卷 (Canvas)当你发出“展开本月画卷”或“显示旅行画卷”的指令时Lumi 会根据上下文筛选相关的记忆碎片。按照时间线或故事节点进行组织。生成一个独立的、交互式的 HTML 文件。这个文件可能包含星轨时间线碎片以时间点形式分布。翻转卡片点击一个节点如某次聚餐卡片正面显示美食照片翻转后显示朋友的搞笑评论。典藏馆展示被标记为“Keepsakes”典藏的特别时刻。 这个 HTML 完全本地运行使用你的浏览器渲染所有媒体资源都来自本地Assets/目录无需网络。胶囊 (Capsule)这是 Lumi 的“记忆迁移”方案。使用export_capsule工具你可以将一个事件或一段时间内的记忆打包成一个.lumi文件。这个文件内部是一个包含lumi.json元数据和索引、media/相关的媒体文件和index.html静态画卷的 ZIP 包。你可以把这个文件发给朋友。对方使用import_capsule工具就能将这份记忆合并到他的本地保险库中并在他的 Lumi 里看到同样的交互式画卷。注意事项导出胶囊时默认包含的是原始媒体文件的副本。如果你导出的记忆包含大量高清视频胶囊文件可能会很大。目前版本没有提供压缩或选择导出质量的功能这是需要注意的。在分享前最好先确认文件大小。4. 从零开始部署与深度配置实战4.1 环境准备与两种部署方式Lumi Diary 需要 Python 3.10 或更高版本。我强烈建议使用虚拟环境如venv或conda来管理依赖避免污染系统环境。方式一通过 OpenClaw Hub 部署推荐给大多数用户这是最快捷的方式尤其适合已经在使用 OpenClaw 生态的用户。# 安装 OpenClaw CLI 工具如果尚未安装 # 假设安装命令为 claw请根据 OpenClaw 官方文档调整 # pip install openclaw-cli # 从 Hub 安装 Lumi Diary Skill clawhub install lumi-diary安装后Lumi 通常会作为一个 Skill 集成到你的 OpenClaw 助理中。你需要在 OpenClaw 的配置界面中启用她并可能指定LUMI_VAULT_PATH环境变量来设置记忆库的存储位置。方式二作为 MCP 服务器运行适合开发者或 Claude Desktop 用户MCPModel Context Protocol是一种让 AI 模型使用外部工具的标准。Lumi 可以作为 MCP 服务器运行从而被 Claude Desktop、Cursor 或 VS Code Copilot 调用。# 1. 克隆或下载项目代码 git clone https://github.com/Thhoho/lumi-diary.git cd lumi-diary # 2. 创建并激活虚拟环境以 venv 为例 python -m venv .venv source .venv/bin/activate # Linux/macOS # .venv\Scripts\activate # Windows # 3. 安装依赖推荐使用 uv速度更快 uv pip install -e . # 4. 运行 MCP 服务器 python -m src.mcp_server # 或者使用 FastMCP如果已安装 # fastmcp run src/mcp_server.py服务器运行后你需要修改你的 MCP 客户端配置。以 Claude Desktop 为例找到其配置文件通常在~/Library/Application Support/Claude/claude_desktop_config.json或类似路径添加 Lumi 服务器{ “mcpServers”: { “lumi-diary”: { “command”: “python”, “args”: [“-m”, “src.mcp_server”], “cwd”: “/你/lumi-diary/的/绝对/路径” } } }重启 Claude Desktop你就可以在对话中直接使用 Lumi 的工具了。4.2 保险库结构与首次运行初始化无论通过哪种方式部署首次运行 Lumi 时她都会在LUMI_VAULT_PATH环境变量指定的路径默认为./Lumi_Vault创建完整的目录结构。理解这个结构对后期管理和排查问题很有帮助。Lumi_Vault/ ├── Solo/ # 你的私人空间 │ ├── Daily/ # 日常碎片的月度归档如 2024-03.md │ └── Projects/ # 项目或主题性记录如 研究论文.md ├── Circles/ # 群聊记忆库 │ └── {群组名}_{YYYY-MM}.md # 按群组和月份分割避免单个文件过大 ├── Events/ # 短期事件 │ └── {YYYY-MM}-{事件名}.md ├── Assets/ # 所有媒体文件的家 │ └── [0-9a-f][0-9a-f]/ # 两位十六进制哈希前缀的文件夹用于分片存储 │ └── {完整哈希值}.{扩展名} # 实际文件 └── Brain/ # Lumi 的“大脑”存储元数据和索引 ├── Portraits.json # 核心所有人物的画像数据 ├── fragment_index.json # 用于快速搜索碎片的倒排索引 ├── Keepsakes.json # 被标记为“典藏”的特殊碎片ID列表 ├── events_registry.json # 记录所有已创建和已封存的事件 └── exports/ # 导出的胶囊和PNG截图关键目录解析Assets/的分片存储这是从 Git 借鉴来的思想。假设一张图片的 SHA-256 哈希是a1b2c3d4e5...它会被存储在Assets/a1/b2c3d4e5...。这种结构能有效应对文件系统单个目录下文件过多导致的性能下降问题。当你要查找某个文件时Lumi 通过哈希值能直接定位到具体路径。Brain/下的 JSON 文件这些是 Lumi 的“状态数据库”。强烈建议定期备份这个文件夹。如果这些文件损坏Lumi 虽然能通过重新扫描Solo/,Circles/,Events/目录下的 Markdown 文件来重建索引但会丢失所有人物画像的演进历史和手动添加的里程碑。4.3 基础配置与个性化环境变量目前最主要的配置项就是LUMI_VAULT_PATH。你可以通过以下方式设置# Linux/macOS 终端 export LUMI_VAULT_PATH“/home/你的用户名/我的记忆库” # 然后在此环境下运行 Lumi # 或者在运行命令时直接指定 LUMI_VAULT_PATH“/path/to/vault” python -m src.mcp_server# Windows PowerShell $env:LUMI_VAULT_PATH“C:\Users\你的用户名\我的记忆库” # 然后运行 python -m src.mcp_server自定义画卷主题生成的 HTML 画卷的视觉效果由 CSS 变量控制。你可以在Brain/目录下寻找或创建一个theme.css文件覆盖默认的变量来调整颜色、字体和动画。Lumi 的核心代码会读取人物画像中的偏好数据如果未来版本支持设置来动态调整主题实现“千人千面”的画卷风格。5. 高级使用技巧与问题排查实录5.1 高效使用工具链Lumi 通过一系列工具Tools与你交互。在 OpenClaw 或 Claude Desktop 中你可以通过自然语言调用它们。以下是一些高效组合技快速归档群聊精彩瞬间在群聊中当你看到一段有趣的对话或图片可以直接 Lumi 并说“保存为典藏”。她会调用save_keepsake工具将当前对话上下文中的碎片标记为珍贵时刻存入Keepsakes.json。定期回顾与清理每月初你可以让 Lumi 执行一次“记忆维护”。指令可以是“Lumi搜索上个月所有内容类型为图片的碎片并按发送者分类展示。” 这背后调用的是manage_fragment(action“search”, ...)工具。你可以基于此结果决定是否删除一些不重要的内容action“delete”。构建人物关系时间线你可以要求 Lumi“为我和 Mike 生成一份专属的友谊画卷。” Lumi 会从所有上下文中筛选出发送者或提及方包含“你”和“Mike”的碎片按时间线排列生成一个只属于你们俩的私人回忆录。5.2 常见问题与解决方案在实际使用中你可能会遇到以下情况问题一Lumi 在群聊中完全不响应也不记录。可能原因上下文模式判断错误。适配器可能未能正确识别当前聊天是“圈子模式”。或者该群组被意外设置为了“静默”名单。排查步骤检查适配器日志如果提供看是否收到了群聊消息。在私聊中询问 Lumi 当前已激活的“圈子”列表这需要适配器实现相应查询工具。确认你是否在目标群聊中明确 或邀请了 Lumi。有些平台需要显式添加机器人。问题二导入胶囊后画卷显示部分图片丢失。可能原因媒体文件的哈希在导入和导出过程中不一致或文件路径解析错误。排查步骤解压.lumi文件重命名为.zip后解压检查media/目录下文件是否完整。对比解压后的lumi.json中记录的media_hash与media/目录下实际文件的哈希值是否匹配可以使用sha256sum命令计算。检查你的本地LUMI_VAULT_PATH是否有写入权限。问题三Assets/目录体积增长过快。原因Lumi 默认存储原始媒体文件。如果你经常分享高清视频和图片这个目录会迅速膨胀。解决方案手动清理使用manage_fragment工具搜索并删除低价值或重复的碎片关联的媒体文件会被同步清理如果无其他碎片引用。外部存储将LUMI_VAULT_PATH设置到一个容量更大的硬盘或网络存储位置。期待的功能未来版本或许可以增加媒体文件压缩或缩略图生成选项。目前你需要手动管理。问题四人物画像Portraits信息不准确或陈旧。原因Lumi 的人物画像基于对话内容分析初期数据不足或对话主题变化都可能导致画像偏差。解决方案主动修正在私聊模式下直接使用update_portrait工具。例如“Lumi更新 Mike 的画像添加里程碑‘毕业日2024-06-15’印象‘最近在学吉他’。”提供更多上下文在群聊或事件中多进行与人物特质相关的互动Lumi 会从中学习。定期审查可以导出Brain/Portraits.json进行查看和手动编辑编辑前请务必备份。5.3 性能优化与数据备份建议索引优化fragment_index.json文件会随着碎片增多而变大。如果感觉搜索变慢可以尝试在 Lumi 不工作时临时删除此文件。下次启动时Lumi 会自动重新扫描所有 Markdown 文件重建索引首次重建可能较慢。定期备份最重要的就是备份整个Lumi_Vault/目录尤其是Brain/子目录。你可以使用简单的压缩脚本或同步工具如rsync定期备份到外部硬盘或另一个位置。媒体文件去重检查由于采用哈希存储理论上相同文件只会存一份。你可以通过检查Assets/下各子文件夹的文件数量来确认去重机制工作正常。如果发现大量重复文件名的不同哈希文件可能是哈希计算逻辑有问题极罕见。Lumi Diary 代表了一种新的可能性AI 可以不是云端的黑盒而是完全受控于个人、专注于增强而非替代人类记忆的本地伙伴。她的价值不在于处理海量信息而在于为你珍视的那些细小、温暖、嘈杂的生活瞬间提供一个安全、智能且充满情感的归处。部署和使用她的过程本身也是一次重新审视自己数字足迹的旅程。开始使用后不妨偶尔对她说一句“Lumi展开今年的画卷吧。” 看看她为你编织了怎样的故事。