Persistent Memory and Salience Filter for Home Assistant.
An AI memory layer that learns what matters in your home — and stays silent about what doesn't.
📔 Persistent memory — daily, weekly, indefinite (JSON files, no database) 🔔 Proactive Telegram contact — alerts when something matters, silence when it doesn't 🧠 Daily and weekly self-reflection — distills events into reusable patterns ✨ Automation by chat — describe what you want, agent proposes, you confirm 🗑 Active forgetting — items not seen in 30 days move to archive ❤️ Health monitoring — circuit breaker, retry, automatic provider fallback 🔇 Smart error filtering — real HA errors come to Telegram, noise stays out
Runs on Home Assistant OS including Raspberry Pi 4 with 2 GB RAM. Estimated cost: ~$0.10/month in LLM tokens.
Two LLM paths kept intentionally separate:
| Path | Used for | Provider |
|---|---|---|
conversation.process |
Telegram chat, voice — needs HA Tools | Gemini Flash (free tier) |
ai_task.generate_data |
Briefings, weekly compile, automation creation | DeepSeek V4-Flash via OpenRouter |
Every non-interactive call has automatic fallback: DeepSeek → Gemini if primary fails. The sensor.permear_health reflects state in real time.
| Cycle | When | What |
|---|---|---|
| Pre-briefing | Hourly, 08:30–20:00 | Decides if you need to know (mostly silent) |
| Daily briefing | 23:30 | 120-word day summary + memory extraction |
| Entity discovery | 06:00 | Syncs with HA entity registry |
| Weekly compilation | Sunday 04:00 | 3 focused LLM calls update perennial memory |
| Real-time error monitor | Continuous | Filters noise, alerts on genuine errors |
# SSH or Terminal addon on your HA instance
cd /tmp
git clone https://github.com/zzzmada/permear
cd permear
bash install.shFollow the prompts. Full guide: docs/install.md.
Upgrading? See MIGRATION.md.
- Home Assistant OS or Supervised, 2025.7+ (native
ai_task.generate_data) - Telegram bot integration (polling mode)
- Two LLM integrations:
- Google Generative AI (free tier OK) — for interactive paths
- OpenRouter or DeepSeek — for
ai_taskcycles (~$0.10/month)
- ~50 MB disk, RPi4 2 GB RAM is enough
See docs/byok.md for the recommended DeepSeek via OpenRouter BYOK setup ($5 lasts ~4 years).
| Command | Effect |
|---|---|
| Type anything | Talks to the agent, can control devices |
/new_automation |
Starts automation creation flow with [Create] [Adjust] [Discard] |
/list_automations |
Shows agent-created automations with [Remove N] per row |
| Reply "I know" / "irrelevant" / "don't alert" | Agent learns a restriction |
After installation, edit /config/memory/:
soul.json— agent personalityusers.json— resident profilesmonitored_entities.json— setevents:per entity to log to daily
See docs/customization.md for the full guide.
Show PERMEAR health on your dashboard. Paste memory/lovelace_card.yaml into your dashboard's Raw configuration editor.
Displays 🟢 / 🟡 / 🟠 / 🔴 state + fallback usage + circuit breaker status.
PRs welcome. Principles:
- Simple, HA-native, no overengineering.
- Single source of truth — don't duplicate state across files.
- English everywhere in this public repo.
- Backward compatibility where reasonable.
Open issues at https://github.com/zzzmada/permear/issues.
MIT — see LICENSE.