{"id":51347018,"url":"https://github.com/zzzmada/permear","last_synced_at":"2026-07-02T12:01:39.490Z","repository":{"id":348149375,"uuid":"1196703927","full_name":"zzzmada/permear","owner":"zzzmada","description":"A cognitive memory and salience layer for Home Assistant — filters by inhibition, surfaces only what earns attention. In-process, HACS-installable.","archived":false,"fork":false,"pushed_at":"2026-07-01T12:03:47.000Z","size":1793,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-07-01T14:05:16.184Z","etag":null,"topics":["ai-agent","cognitive-architecture","context-awareness","hacs","hacs-custom","hacs-integration","home-assistant","homeassistant-integration","local-first","memory","persistent-memory","raspberry-pi","salience","smart-home","telegram"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zzzmada.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-31T00:46:32.000Z","updated_at":"2026-07-01T12:01:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"79a79155-0829-451b-a721-b331837ef3e1","html_url":"https://github.com/zzzmada/permear","commit_stats":null,"previous_names":["zzzmada/permear"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/zzzmada/permear","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zzzmada%2Fpermear","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zzzmada%2Fpermear/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zzzmada%2Fpermear/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zzzmada%2Fpermear/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zzzmada","download_url":"https://codeload.github.com/zzzmada/permear/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zzzmada%2Fpermear/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35045926,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-02T02:00:06.368Z","response_time":173,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","cognitive-architecture","context-awareness","hacs","hacs-custom","hacs-integration","home-assistant","homeassistant-integration","local-first","memory","persistent-memory","raspberry-pi","salience","smart-home","telegram"],"created_at":"2026-07-02T12:01:38.788Z","updated_at":"2026-07-02T12:01:39.481Z","avatar_url":"https://github.com/zzzmada.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PERMEAR\n\n**A cognitive memory and salience layer for Home Assistant.**\n\nPERMEAR filters by inhibition rather than broadcast. It watches household\nevents, consolidates what repeats, lets noise fade, and surfaces only what\nwarrants your attention. It is designed to run on hardware as small as a\nRaspberry Pi 4 (2 GB).\n\nIt is not an assistant, an automation pack, or a copilot. It is an\nattentional layer: most of what happens in a home is not worth a\nnotification, and PERMEAR is built around that fact. Silence is its default\nstate.\n\n---\n\n## Installation (HACS custom repository)\n\nPERMEAR is installed as a **custom repository** in HACS.\n\n1. In Home Assistant, open **HACS**.\n2. Click the three-dot menu (top right) → **Custom repositories**.\n3. Add the repository URL `https://github.com/zzzmada/permear` and choose\n   the category **Integration**.\n4. Find **PERMEAR** in the HACS list and click **Download**.\n5. **Restart Home Assistant.**\n6. Go to **Settings → Devices \u0026 Services → Add Integration**, search for\n   **PERMEAR**, and follow the configuration flow.\n\n\u003e Full guide on custom repositories:\n\u003e https://www.hacs.xyz/docs/faq/custom_repositories/\n\nThere is **no YAML configuration**. Everything is configured through the UI\n(config flow and options). PERMEAR does not use `secrets.yaml` or any\nconfiguration file.\n\n---\n\n## Where your data goes\n\nPERMEAR sends data only to the LLM providers **you** configure in Home\nAssistant — and only for the small fraction of cases that need a language\nmodel. You choose those providers, so you control where the data goes.\n\n- If you point PERMEAR at **local** providers (for example a model served by\n  Ollama), nothing leaves your network.\n- If you point it at **cloud** providers, then for the ambiguous cases the\n  following can be sent to them: short event descriptions (which entities\n  changed, when, humanized state text such as a room name), media titles from\n  media players, and your chat messages to the agent.\n\nThe deterministic core — capture, the ARAS filter, tier maintenance,\ncorrelation — runs **entirely on your device** and sends nothing externally.\nA language model is only involved in the gray-zone judgment, the nightly\nmemory extraction, the weekly suggestion, and direct conversation. Everything\nelse is local arithmetic.\n\nIn short: the privacy profile is whatever your chosen providers are. Pick\nlocal providers for a fully on-device setup, or cloud providers if you prefer\ntheir quality — PERMEAR is agnostic to the choice.\n\n---\n\n## Requirements\n\n- **Home Assistant 2025.7 or newer.**\n- A **conversation** provider and an **ai_task** provider configured in Home\n  Assistant (any integration that exposes a `conversation.*` entity and one\n  that exposes an `ai_task.*` entity, cloud or local). PERMEAR asks for four\n  during setup: a primary and a fallback for each.\n- The **Telegram** integration (`telegram_bot`) configured — it is the\n  primary output surface. PERMEAR will warn you if it is missing. See the\n  Home Assistant docs to set it up:\n  https://www.home-assistant.io/integrations/telegram_bot/\n- Optionally, for the error monitor to see Home Assistant errors, enable\n  event firing in your `configuration.yaml`:\n\n  ```yaml\n  system_log:\n    fire_event: true\n  ```\n\n  PERMEAR will create a Repair notification if this is off.\n\n---\n\n## How it works\n\n```\nhousehold events\n       │\n       ▼\n  event_buffer (SQLite, today only)\n       │\n       ▼\n  Heartbeat (hourly, within a configurable daytime window)\n  build candidates → ARAS Filter → emit / suppress / gray zone\n       │                                   │\n       │                                   ▼  (gray only)\n       │                         one ai_task call (data provider)\n       │                                   │\n       ▼                                   ▼\n  Telegram (emit)                Telegram (after LLM judgment)\n       │\n       ▼\n  Organic Memory (tiered SQLite)\n       │\n       ▼\n  Sleep Consolidation (nightly)\n  extract memories → write to DB → tier maintenance → priority loop\n       │\n       ▼\n  Systems Consolidation (weekly)\n  detect recurring co-occurrences → suggest an automation\n```\n\nEverything runs **in-process** inside the integration. There are no shell\nscripts, no `command_line` sensors, no external tokens, and no REST calls\nback into Home Assistant.\n\n---\n\n## The ARAS Filter\n\nThe Ascending Reticular Activating System (ARAS) is the brain region that\ngates which incoming signals reach conscious attention. Its defining\nmechanism is **inhibition**: most signals are suppressed; few pass. PERMEAR's\nfilter does the same.\n\nEach candidate event is scored on four axes:\n\n| Axis | Range | Description |\n|---|---|---|\n| novelty | 0–2 | Compared by canonical key (`type:entity_id`), not raw text |\n| anomaly | 0–1 | Deviation from the observed baseline |\n| priority | 0–2 | User-set or memory-learned weight |\n| user_match | −2..0 | Penalty for events the resident asked not to hear about |\n\n- **Score ≤ 1** → suppressed silently\n- **Score ≥ dynamic threshold** → emitted to Telegram\n- **In between** → one `ai_task` call resolves the gray zone\n\nThe threshold is **dynamic and relative to your entity park**:\n\n```\nthreshold = MIN + maturity × (MAX − MIN)\nmaturity  = min((consolidated_items / exposed_entities) / 0.5, 1.0)\n```\n\nThe system is born curious (low threshold — novelty alone is enough),\nmatures over weeks of observation, and becomes selectively attentive once it\nhas learned the house. It scales to any household size with no seeding and\nno day-one configuration. Sensitivity (`sensitive` / `balanced` / `quiet`)\nis the only ARAS knob, set in the options.\n\nTrivial state changes (a plain switch toggling, repeated room occupancy) do\nnot earn an attention boost on their own — they still consolidate as memory,\nbut they don't claim your attention unless they're genuinely anomalous (an\nodd hour) or you mark them as a priority yourself.\n\n---\n\n## Organic Memory\n\nMemory lives in SQLite with FTS5 for free-text similarity. It is **tiered**:\neach item moves between tiers based on reinforcement and silence.\n\n| Tier | Meaning |\n|---|---|\n| ephemeral | Just observed; may be forgotten |\n| active | Repeated enough to matter |\n| stable | Consolidated over time |\n| faded | Decayed from disuse |\n\nPatterns emerge from **accumulation**, not from LLM detection. Memory that is\nreinforced rises; memory that goes unmentioned decays. Restrictions you\nexpress in conversation (\"stop telling me about X\") are learned as memory\nand gently lower the salience of those events — without silencing genuine\nanomalies.\n\nThe database carries a schema version and migrates forward across updates,\nso your accumulated memory is preserved when you upgrade.\n\n---\n\n## Configuration\n\nAll configuration is in the UI.\n\n**On install (config flow):**\n\n- Four LLM providers: conversation, data, conversation fallback, data\n  fallback.\n- Telegram chat ID (optional — leave blank to use the bot's first permitted\n  chat).\n\n**Anytime (options → Configure):**\n\n- The four LLM providers and the chat ID — reconfigurable without\n  reinstalling, so you can switch models or accounts from the UI.\n- ARAS sensitivity: `sensitive` / `balanced` / `quiet`.\n- Primary resident (chosen from your `person.*` entities).\n- Cycle times: Heartbeat window start/end, Sleep time, Systems time.\n- Agent name (optional — defaults to a neutral name).\n- Voice hook (optional — a script/service ID of your own that PERMEAR will\n  call when you want a voice surface; PERMEAR never decides to speak on its\n  own).\n\nResidents and rooms are read directly from Home Assistant (the `person`\nregistry and the area registry) — you do not maintain a separate list. The\nconversation agent receives household context at runtime, so you do not need\nto write a system prompt for it.\n\n---\n\n## What PERMEAR will not do\n\n- It will not talk to you unless something earns it.\n- It will not declare automations; it suggests, and you decide.\n- It does not use embeddings, a vector database, or any always-on assistant\n  loop.\n- It does not depend on the cloud for its core logic — only the configured\n  LLM calls leave the device, and only if your providers are remote.\n\n---\n\n## Status\n\nPERMEAR is published as a custom repository. It is a working system run in a\nreal household, but it is young software: treat the memory database as\nvaluable but not irreplaceable, and report issues on the tracker.\n\n## License\n\nMIT. See `LICENSE`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzzzmada%2Fpermear","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzzzmada%2Fpermear","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzzzmada%2Fpermear/lists"}