https://github.com/riscue/ha-ai-memory
Long-term memory system for AI assistants in Home Assistant. Store facts, preferences, and context that persists across conversations.
https://github.com/riscue/ha-ai-memory
ai assist custom-component hacs home-assistant ltm memory sqlite
Last synced: 2 months ago
JSON representation
Long-term memory system for AI assistants in Home Assistant. Store facts, preferences, and context that persists across conversations.
- Host: GitHub
- URL: https://github.com/riscue/ha-ai-memory
- Owner: Riscue
- License: mit
- Created: 2025-11-23T22:13:10.000Z (7 months ago)
- Default Branch: master
- Last Pushed: 2025-12-19T11:17:59.000Z (6 months ago)
- Last Synced: 2025-12-22T04:11:53.218Z (6 months ago)
- Topics: ai, assist, custom-component, hacs, home-assistant, ltm, memory, sqlite
- Language: Python
- Homepage:
- Size: 288 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
README
# 🧠 AI Long Term Memory for Home Assistant
[](https://home-assistant.io)
[](https://www.hacs.xyz/docs/faq/custom_repositories/)
[![License][license-shield]](LICENSE.md)
[license-shield]: https://img.shields.io/github/license/Riscue/ha-ai-memory.svg?style=for-the-badge
[](https://github.com/Riscue/ha-ai-memory)
[](https://github.com/Riscue/ha-ai-memory/releases)
[](https://github.com/Riscue/ha-ai-memory/releases)
[](https://github.com/Riscue/ha-ai-memory/commits/master)
[](https://my.home-assistant.io/redirect/config_flow_start/?domain=ai_memory)
Long-term memory system for AI assistants in Home Assistant. Store facts, preferences, and context that persists across
conversations.
## ✨ Features
- **Native LLM Integration**: Automatically exposes tools to Home Assistant's Assist agents.
- **Multi-Engine Support**: Choose between `SentenceTransformer` (Best Quality), `FastEmbed` (RPi4 Optimized), or
`TF-IDF` (Lightweight).
- **Scoped Memory**: Supports `private` (agent-specific) and `common` (shared) memories.
- **Privacy First**: All data is stored locally in your Home Assistant instance.
- **Offline Capable**: Works entirely offline with TF-IDF or cached models.
## 🚀 Installation
### HACS Installation (Recommended)
[HACS Custom Repository Installation](https://www.hacs.xyz/docs/faq/custom_repositories/)
[](https://my.home-assistant.io/redirect/hacs_repository/?owner=Riscue&repository=ha-ai-memory)
### Manual Installation
1. Copy `custom_components/ai_memory` to your `config/custom_components/` directory.
2. Restart Home Assistant.
3. Add the integration via Settings > Devices & Services.
[](https://my.home-assistant.io/redirect/config_flow_start/?domain=ai_memory)
## ⚙️ Configuration
During setup (or via "Configure" on the integration entry), you can customize:
- **Storage Location**: Fixed at `/config/ai_memory/`.
- **Embedding Engine**:
- **SentenceTransformer**: Best accuracy. Requires ~500MB RAM. Ideal for PC/NUC.
- **FastEmbed**: Good accuracy, optimized for ARM/RPi4. Requires ~100MB RAM.
- **TF-IDF**: Zero dependencies, very fast, lower semantic accuracy. Best for low-power hardware.
- **Auto**: Tries engines in order: SentenceTransformer → FastEmbed → TF-IDF.
## 🤖 Usage
### For AI Agents (LLM Tools)
Once installed, the following tools are automatically available to your Assist agents:
- **`add_memory`**: Proactively saves information.
- `content`: The text to save.
- `scope`: `private` (default, specific to the agent) or `common` (shared household facts).
- **`search_memory`**: Retrieves relevant memories based on semantic similarity.
**Example Interaction:**
> **User:** "I'm allergic to peanuts."
> **AI:** *Calls `add_memory(content="User is allergic to peanuts", scope="private")`*
> **AI:** "I've made a note of your peanut allergy."
### For Automations (Services)
You can manage memories programmatically using Home Assistant services.
#### `ai_memory.add_memory`
Add a memory entry manually.
```yaml
service: ai_memory.add_memory
data:
memory_id: sensor.ai_memory_store
text: "The garage door code is 1234"
```
#### `ai_memory.list_memories`
Retrieve all memories.
```yaml
service: ai_memory.list_memories
response_variable: memories
```
#### `ai_memory.clear_memory`
Wipe all memories for a sensor.
```yaml
service: ai_memory.clear_memory
data:
memory_id: sensor.ai_memory_store
```
## 🐛 Troubleshooting
- **"No embedding engine available"**: Ensure you have selected a supported engine for your hardware. Try switching to
`TF-IDF` or `Auto`.
- **Import Errors**: Check logs. If using `SentenceTransformer` or `FastEmbed`, ensure dependencies are installed or
switch to `TF-IDF`.
- **Database Issues**: If the database becomes corrupted, stop HA and delete the `ai_memory.db` file in your storage
directory.
## License
MIT © [Riscue](https://github.com/riscue)