1. 项目概述为你的智能家居AI注入“灵魂”如果你和我一样是Home Assistant的深度用户并且已经接入了像Gemini这样的对话式AI助手那你一定遇到过这个让人头疼的问题每次和它对话都像是第一次见面。你昨天刚告诉它“我习惯在晚上十点关掉客厅的灯”今天它又会问你“您希望几点关灯”。这种“金鱼记忆”让所谓的“智能”助手显得有点名不副实更像是一个高级的、但每次都要重新加载的问答脚本。这就是我折腾PERMEARPersistent Memory Architecture的初衷。我不想再要一个只会回答问题的聊天机器人我想要一个真正的“管家”——它能记住我家人的习惯能学习家庭设备的运行规律能主动监控系统健康甚至在获得我允许后帮我创建自动化。听起来有点科幻其实核心思路并不复杂为无状态的AI Agent构建一个基于文件的、持久化的记忆系统。这个项目完全运行在我的树莓派42GB内存上基于HAOS。它不依赖任何外部数据库或云服务所有数据都安全地存放在你的/config目录下。通过一系列精心设计的Python脚本和自动化流程它将Home Assistant的对话代理从一个“健忘的聊天窗口”转变为一个拥有“灵魂”、能够持续进化的智能家居中枢。简单来说PERMEAR给你的AI装上了三样东西一个不会丢失的记忆库一套自我反思和学习的机制以及一双能主动看护系统的眼睛。接下来我会带你从零开始彻底拆解这个系统的设计思路、每一步的实操细节以及我踩过的那些坑让你也能亲手打造一个真正“懂事”的智能家居大脑。2. 核心架构深度解析文件即记忆循环即成长很多智能家居项目喜欢把数据往云端一扔了事但PERMEAR选择了另一条路一切基于本地文件。这个选择背后有很实际的考量隐私、可控性、以及对HAOS轻量级环境的适配。让我们深入看看这个“文件大脑”是如何工作的。2.1 记忆文件体系JSON构成的长期记忆与短期日志PERMEAR的记忆体系分为“常年记忆”和“短期日志”两层全部由JSON文件承载。这种结构模拟了人类的记忆方式——既有长期稳定的性格和知识也有不断滚动更新的近期经历。常年记忆文件Perennial Memory存放在/config/memory/根目录下是系统的核心人格与知识库。guidelines.json系统的“宪法”。这里定义了AI代理必须遵守的最高行为准则比如“未经用户明确同意不得创建或修改自动化”。这个文件在初始化后会被设置为只读chmod 444防止AI在自我更新时不小心修改了根本原则。我的建议是在项目初期多花点时间打磨这里面的内容它决定了你的AI管家的“三观”。soul.jsonAI的“人格”。这里定义了它的说话风格、自我认知和核心职责。例如你可以设定它是一位“严谨但友善的英国管家”或者是一位“高效简洁的技术助手”。这个文件每周日会由AI自己根据一周的互动进行微调实现人格的缓慢演化。users.json家庭成员档案。记录每个用户的偏好、习惯、常用设备等。这是实现个性化服务的基础。比如记录下“妻子习惯在周六上午用咖啡机”那么AI在周六早晨的简报中就可能主动提醒咖啡豆是否充足。insights.json学习到的规律。这是AI通过分析日志自动发现的模式例如“每当室外温度低于15度时用户会在晚上7点打开客厅暖气”。这些洞察可以用于预测性提醒或作为创建新自动化的建议依据。monitored_entities.json被监控实体的唯一信源。这是v5.2版本的一个重要改进。它合并了之前“监控列表”和“事件缓冲”两个功能。每个实体在这里有两个关键属性monitor: true/false决定该实体是否需要在每日简报前被检查状态预简报。events: []一个数组用于缓冲该实体的状态变化事件这些事件稍后会被用于重新生成HA的自动化触发器。这解决了HA触发器YAML是静态文件而我们需要动态管理触发事件的矛盾。短期日志文件Daily Logs存放在/config/memory/daily/目录下按星期命名monday.json, tuesday.json…以7天为周期循环覆盖。这里记录了每一天发生的所有交互、系统事件、错误日志和AI提取的临时记忆点。每日简报21点和每周编译周日的任务就是咀嚼这些“短期记忆”把有价值的部分提炼、沉淀到上述的常年记忆文件中。这种循环覆盖的设计既保证了系统能回顾近期上下文又避免了日志文件无限膨胀占用存储空间。2.2 脚本生态系统分工明确的“器官”所有功能都由/config/scripts/目录下的Python脚本实现。v5.3版本引入的permear_config.py是大脑的“脑干”所有脚本都从这里导入路径、常量等共享配置极大提升了可维护性。主要脚本可分为几类1. 记忆与日志管理append_daily.py记忆系统的“感官”。任何交互、事件或需要记录的信息都通过它写入当天的日志文件。update_daily_memory.py在每日简报后运行将AI从当天对话中提取出的关键记忆点如用户明确说“我讨厌强光”格式化后保存。weekly_compile.py系统的“深度睡眠”。每周日运行调用LLM需要8192 tokens通读一周日志总结并更新soul.jsonusers.jsoninsights.json。2. 简报与评估系统build_prebriefing.py每30分钟08-20点运行的“主动巡检”。它检查系统健康通过ha_log_monitor.py、查看被监控实体的状态并生成一个简短的评估提示。关键点它引入了SELF_ERRORS概念能区分出由PERMEAR自身组件如某个脚本报出的错误和其他系统错误并指示AI在报告时附带上下文比如“我在尝试执行X操作时因为Y原因失败了”。build_briefing.py每日21点的“晚间汇报”。汇总一天的重要事件、系统状态更新通过ha_updates_check.py、以及从日志中提取的记忆生成一份全面的报告供AI向用户传达。3. 系统交互与自动化discover_entities.py每日早上6点运行的“实体发现”。它会扫描HA中所有should_expose属性为true的实体更新monitored_entities.json。这是AI了解家庭设备清单的基础。manage_agent_automations.pyAI创建和管理HA原生自动化的核心工具。它操作的是一个独立的YAML文件agent_automations.yaml通过HA的!include机制加载确保用户自己的自动化配置不被污染。generate_buffer_events.py自动化触发器的“代码生成器”。因为HA的YAML是静态的我们不能直接往里面写动态触发器。这个脚本读取monitored_entities.json中每个实体的events数组然后在agent_automations.yaml中对应的自动化里重新生成trigger部分。这是一个非常巧妙的“动态-静态”桥接方案。4. 健康监控ha_log_monitor.py解析HA的系统日志按严重程度分类错误并特别标记出SELF_ERRORS。ha_updates_check.py检查HA核心、集成或插件的更新。重要限制此脚本依赖SUPERVISOR_TOKEN环境变量因此只能在HAOS容器内部通过服务调用执行在SSH插件终端里直接运行会失败。2.3 运行周期让智能自主呼吸PERMEAR不是一个被动的工具而是一个拥有自主节律的系统。它的运行周期设计模仿了生物钟高频主动巡检每30分钟08-20点prebriefing周期。就像管家每隔半小时巡视一遍房间检查是否有异常错误日志、关注的重点设备被监控实体状态是否正常。这保证了系统问题的及时发现。每日深度汇总21点briefing周期。一天结束管家整理今日所见所闻形成报告并与用户沟通。同时将重要的短期记忆进行标记。每日资源盘点06点entity discovery周期。清晨系统重新扫描家中所有可用的设备实体确保“设备清单”是最新的。每周自我进化周日00:05weekly compile周期。这是一次深度学习和人格微调。AI回顾一周的所有日志提炼规律调整自己的行为倾向和用户画像实现缓慢的、持续的自我改进。按需交互通过Telegram机器人用户可以随时与AI管家对话发起指令或询问状态。这个循环体系确保了系统不仅是“有记忆的”更是“有生命的”能够主动感知、定期总结、并持续成长。3. 从零开始的部署与配置实战理论讲完了我们动手把它装起来。我将以手动安装为例带你走通每一个步骤因为理解每一步在做什么比一键脚本更重要。当然项目也提供了便捷的install.sh脚本但手动走一遍能让你在出问题时知道从哪里排查。3.1 环境准备与前期检查在开始复制文件之前我们必须确保Home Assistant的基础环境符合要求。第一步验证HA版本与自动化配置PERMEAR要求HA版本在2023.7以上主要是为了确保相关API的稳定性。请进入HA的“配置” - “关于”页面确认版本。最关键的一步是检查你的configuration.yaml中关于自动化的配置。PERMEAR依赖目录合并模式来安全地添加自动化。打开你的configuration.yaml找到automation部分它必须是这样的形式automation: !include_dir_merge_list automations/这意味着HA会加载/config/automations/目录下所有YAML文件中的自动化定义。如果你的配置是!include automations.yaml这种单个文件模式需要先修改为目录模式并重启HA生效。这是为了将PERMEAR的自动化与你个人的自动化隔离存放。第二步创建必要的目录结构通过HA的File Editor插件、Samba共享或SSH连接到你的HAOS执行以下命令# 进入HA配置目录 cd /config # 创建PERMEAR所需的记忆、脚本和日志目录 mkdir -p memory/daily scripts logs # 创建用于存放AI生成的自动化的独立文件 touch automations/agent_automations.yaml这个agent_automations.yaml文件是AI管家“沙箱”它通过!include被主自动化系统加载但内容由AI通过脚本管理与你手写的自动化互不干扰。第三步获取并保存HA长期访问令牌AI脚本需要与HA API通信。我们需要创建一个具有足够权限的长期令牌。在HA网页侧边栏点击你的用户名。滚动到最下方找到“长期访问令牌”。点击“创建令牌”命名为“PERMEAR”然后复制生成的那一串长字符。在/config目录下创建并保护这个令牌文件echo 你的长令牌字符串 /config/.permear_token chmod 600 /config/.permear_token # 设置只有所有者可读写注意chmod 600至关重要它防止其他用户或进程读取你的令牌这是基本的安全实践。3.2 核心配置文件详解与定制PERMEAR的灵活性很大程度上来自于它的配置文件。盲目复制粘贴会出问题我们必须理解每个配置项的含义。首先配置secrets.yaml项目从v5.5开始全面采用HA原生的!secret机制这是最佳实践。打开或创建/config/secrets.yaml添加以下内容permear_chat_id: YOUR_TELEGRAM_CHAT_ID permear_agent_id: conversation.your_agent_id permear_person_entity: person.your_namepermear_chat_id你的Telegram聊天ID。如何获取给你的Telegram Bot比如userinfobot发送/start它会回复你的数字ID。permear_agent_id你的对话代理实体ID。这是最容易出错的地方很多人以为是google_generative_ai这个实体。不对你需要的是**对话代理Conversation Agent**的实体。进入HA“开发者工具” - “状态”在实体筛选框里输入conversation.通常你会看到类似conversation.google_ai_conversation或conversation.openai_conversation的实体。复制这个完整的实体ID。permear_person_entity代表你自己的person实体例如person.john。这用于在日志和记忆中标识用户。其次深入定制permear_config.py这是整个系统的心脏。从项目根目录复制permear_config.py到/config/scripts/后你需要修改以下几个关键部分# 路径配置 - 通常与手动创建的目录一致 MEMORY_DIR /config/memory DAILY_DIR os.path.join(MEMORY_DIR, daily) SCRIPTS_DIR /config/scripts LOGS_DIR /config/logs AUTOMATIONS_FILE /config/automations/agent_automations.yaml # 语言设置 - 将星期几映射为中文 DAYS { 0: 星期一, 1: 星期二, # ... 依此类推 6: 星期日 } # 自我错误标记 - 定义哪些日志错误来自PERMEAR自身 SELF_COMPONENTS [ permear, script.permear, automation.agent_ # 你可以添加其他你自己的相关组件 ]SELF_COMPONENTS的配置让ha_log_monitor.py能够识别“自家孩子”犯的错并在预简报中让AI进行自我检讨这大大提升了系统的可信度和可调试性。最后塑造AI的“灵魂”与“宪法”soul.json不要怕大胆改。这里定义了AI的个性。你可以设定tone语气、core_duty核心职责、self_view自我认知。例如一个更主动的管家可能将core_duty设为“预测并满足家庭需求而不仅仅是响应指令”。guidelines.json这是行为红线。在系统运行前仔细阅读并修改它。明确写出你绝对禁止AI做的事情例如“未经二次确认永远不要删除任何实体或自动化”。修改完成后务必执行chmod 444 /config/memory/guidelines.json将其设为只读防止AI在后续学习过程中意外修改了根本大法。users.json预先填写家庭成员的基本信息。AI会在每周编译时更新这个文件但一个良好的初始状态有助于快速启动。3.3 集成对话代理与Telegram配置好文件后我们需要让AI能“说话”和“听话”。第一步配置Telegram Bot轮询模式在HA中安装并配置“Telegram Bot”集成选择“轮询Polling”模式。将你的permear_chat_id填入集成的配置中。确保在configuration.yaml中telegram_bot部分使用的是chat_id参数而不是旧的target参数。PERMEAR的自动化模板已经正确使用了chat_id。第二步更新LLM系统提示词这是“激活”AI管家行为模式的关键一步。进入你使用的对话代理如Google Generative AI的设置页面。找到“系统提示词”或“指令”的输入框。将PERMEAR项目README中提供的系统提示词模板粘贴进去并根据你的情况微调。核心是告诉AI你现在有了监控HA健康的能力遇到关键错误要立即报告。SELF_ERRORS是你自己组件的问题报告时要说明可能的原因。创建自动化前必须询问用户确认。管理被监控实体的专用指令monitor [实体]/stop monitoring [实体]。第三步暴露脚本服务给AI代理极易遗漏这是v5.6版本解决的一个关键痛点。HA的Shell命令shell_command对于对话AI代理是不可见的。AI只能调用通过“语音助手”设置暴露出来的script服务。复制项目中的configuration_additions.yaml内容到你的HA配置中可以直接放入/config/packages/目录作为独立包这是推荐做法。重启Home Assistant。重启后进入“设置” - “语音助手” - 点击你正在使用的对话代理。在“暴露的实体”列表中找到并启用以下三个脚本script.permear_list_automationsscript.permear_create_automationscript.permear_remove_automation如果没有这一步当你对AI说“创建一个自动化”它会返回“函数不存在”的错误。这三个脚本本质上是shell_command的包装器充当了AI与底层系统命令之间的桥梁。3.4 初始化与首次运行完成所有配置后重启Home Assistant以加载所有新的自动化、脚本和配置。重启后我们需要进行系统“冷启动”初始实体发现进入“开发者工具” - “服务”。选择服务shell_command.discover_entities然后点击“调用服务”。这会让discover_entities.py脚本首次运行扫描你的HA中所有可用的实体并填充monitored_entities.json。你可以在File Editor中打开这个文件查看结果。触发首次预简报你可以等待下一个30分钟周期08-20点之间或者手动调用服务shell_command.build_prebriefing来生成第一份系统健康报告并通过Telegram发送给你。测试对话给你的Telegram Bot发送消息例如“你好”或“报告系统状态”。观察AI的回应是否包含了从记忆文件中读取的上下文信息。如果一切顺利你的AI管家就已经不再是那个“健忘”的聊天机器人了。它现在拥有了一个基于本地文件的记忆系统并开始按照既定的周期主动地观察、思考和汇报你的智能家居状态。4. 高级功能与避坑指南系统跑起来只是第一步。要让它真正变得聪明、可靠你需要理解并驾驭以下几个高级功能同时避开我亲身经历过的那些“坑”。4.1 实体监控与动态自动化让AI真正“看”家monitored_entities.json是PERMEAR v5.2后的一个设计精华。它解决了“静态YAML”与“动态需求”之间的矛盾。如何使用假设你想让AI重点关注客厅温度传感器和 front_door 门锁。你可以直接编辑monitored_entities.json找到对应的实体ID将monitor设为true。更自然的方式是通过Telegram告诉AI“监控 sensor.living_room_temperature 和 lock.front_door”。AI会调用add_monitored_entity服务更新JSON文件。发生了什么预简报每30分钟build_prebriefing.py会读取所有monitor: true的实体检查它们的当前状态。如果客厅温度异常高AI会在预简报中提醒你“检测到客厅温度达到30度是否异常”事件缓冲与自动化生成这才是更强大的部分。假设你想让AI在门锁解锁时给你发消息。你告诉AI“当 front_door 解锁时在Telegram通知我”。AI会先将lock.front_door的events数组中加入unlocked。然后你需要手动或通过自动化运行generate_buffer_events.py脚本。这个脚本会读取所有实体的events数组并重新生成agent_automations.yaml文件中对应自动化的trigger部分。例如它会生成trigger: - platform: state entity_id: lock.front_door to: unlocked因为agent_automations.yaml被!include到HA中所以这个新自动化就生效了。核心避坑点HA的自动化YAML是静态的。你不能让AI直接去修改YAML文件中的trigger:部分。PERMEAR采用的“JSON配置 - Python脚本生成YAML”是一种优雅的间接方案。记住修改monitored_entities.json后自动化不会立即生效必须运行generate_buffer_events.py或触发调用它的自动化来重新生成YAML触发器。4.2 AI创建与管理自动化赋予管家行动力这是PERMEAR从“顾问”变为“执行者”的关键。通过manage_agent_automations.py脚本和暴露的script服务AI可以在你的授权下创建、列出和删除自动化。工作流程用户提出需求“当我在家且太阳下山时自动打开门廊灯。”AI理解并请求确认AI会解析需求将其转化为HA自动化的逻辑触发条件太阳实体状态为below_horizon条件我的person实体状态为home动作打开light.porch。然后它会问你“我将创建一个自动化在太阳下山且您在家时打开门廊灯。确认创建吗”用户确认你回答“是的”或“确认”。AI执行创建AI调用script.permear_create_automation服务。该服务背后是manage_agent_automations.py它会在agent_automations.yaml文件中追加一段新的自动化YAML配置。自动化生效由于agent_automations.yaml被包含在HA配置中HA会在下一次配置重载或你重启后识别并运行这个新自动化。安全机制独立文件所有AI创建的自动化都存放在独立的agent_automations.yaml中与你手写的自动化完全隔离避免误删或混淆。强制确认系统提示词和guidelines.json中都强调创建自动化前必须获得用户明确确认。可追溯自动化ID、名称和创建来源都会被记录方便管理。避坑指南有时AI生成的自动化YAML语法可能有误比如缩进不对、漏了冒号。manage_agent_automations.py脚本会尝试进行基本的YAML格式化和验证但并非万能。如果创建后自动化不工作第一件事是去检查/config/automations/agent_automations.yaml这个文件的语法。你可以通过“开发者工具” - “模板”来检查YAML是否有效或者直接看HA日志是否有配置错误。4.3 每周编译与自我进化AI的“反思时间”每周日的编译过程是PERMEAR的“学习时刻”。weekly_compile.py脚本会做以下几件事收集过去一周7个daily/日志文件的所有内容。将这些内容与当前的soul.jsonusers.jsoninsights.json一起构造一个超长的提示词发送给LLM。指示LLM分析日志并输出这三个文件的完整新版本。脚本用LLM输出的新版本替换旧文件。这个过程的风险与应对Token限制一周的日志内容可能很长。这就是为什么必须将你的LLM集成如Google Gemini的max_tokens参数设置为8192或更高。否则上下文窗口不够编译会失败。LLM的“创造力”风险你是在要求LLM重写核心配置文件。虽然指令明确但LLM有时会“过度发挥”输出不合规的JSON格式或完全偏离指令的内容。防护措施1guidelines.json被设为只读保证了根本原则不被篡改。防护措施2weekly_compile.py脚本在替换文件前应该最好实现有一个简单的JSON语法验证步骤。如果没有你可以考虑手动添加。防护措施3务必在首次运行每周编译前备份你的soul.jsonusers.jsoninsights.json文件。这是最重要的安全网。我的经验在初期我建议你在周日编译后花几分钟检查一下这三个文件的变化。观察AI是如何根据你们的对话调整它的“人格”soul.json和对你家人的认知users.json的。这是一个非常有趣的体验也能让你及时发现任何不希望的偏差。4.4 常见问题排查实录以下是我在部署和运行PERMEAR过程中遇到的最典型问题及其解决方案问题1AI对“创建自动化”指令回复“函数不存在”。原因没有在“语音助手”设置中暴露script.permear_create_automation等脚本服务。解决严格按照3.3章节的第三步操作。这是最高频的错误。问题2ha_updates_check.py脚本执行失败日志显示无法连接或权限错误。原因该脚本需要SUPERVISOR_TOKEN环境变量来访问HA Supervisor的API。这个变量只在HAOS容器内部运行时才存在。解决不要在SSH插件终端里直接运行这个Python脚本。只能通过HA的“开发者工具” - “服务”调用对应的shell_command如shell_command.ha_updates_check来触发它。HA服务调用是在正确的容器上下文中执行的。问题3Telegram消息发送失败错误提示关于chat_id或target。原因telegram_bot.send_message服务调用参数错误。旧版HA或某些教程可能使用target参数但当前标准是chat_id。解决检查PERMEAR提供的自动化YAML模板确保使用的是data:模板下的chat_id: “{{ states(‘sensor.permear_chat_id’) }}”。并确认sensor.permear_chat_id这个传感器已正确从secrets.yaml中读取了你的ID。问题4AI似乎没有记忆之前的对话。原因1append_daily.py可能没有成功记录对话。检查/config/memory/daily/下的当日日志文件看是否有新的对话条目被添加。原因2构建简报或预简报的脚本没有正确读取记忆文件。检查build_briefing.py和build_prebriefing.py中文件路径是否正确以及HA令牌是否有读取权限。原因3针对GeminiGemini在处理极长的对话历史时有时会忽略系统提示词中靠后的指令。尝试将最重要的指令如“你必须查阅记忆文件”放在系统提示词的前部或者在每次用户消息中以文本形式重新注入关键指令。问题5系统升级HA后出现大量“不可用”的实体干扰实体发现。原因HA核心或集成升级后旧的实体注册信息可能残留。解决定期清理。进入HA“设置” - “设备与服务” - “实体”在筛选框输入“不可用”勾选所有不可用实体然后点击右下角的“删除所选实体”。然后再运行一次shell_command.discover_entities。问题6Python脚本在SSH终端中运行报导入错误或找不到模块。原因HAOS的SSH插件终端环境可能与HA内部Python运行环境不同尤其是模块路径。解决所有PERMEAR脚本都设计为通过HA服务调用shell_command来运行。不要尝试在SSH中直接python3 /config/scripts/xxx.py。始终使用“开发者工具”中的服务面板来触发它们。部署并调通PERMEAR就像是教会一个新生儿感知世界、形成记忆、并学会按照规则行动。这个过程需要耐心和细致的调试。一旦系统稳定运行起来你会获得一个真正与众不同的智能家居体验——一个能记住你偏好、关注你家状态、并能与你共同管理这个家的数字伙伴。它不再是一个工具而是一个逐渐成长的系统成员。 
