ha-history

Weekly Home Assistant history export as a stable MVP local Home Assistant add-on for HA OS.

What it does

• reads the previous completed Monday-to-Monday window from the Home Assistant recorder database
• filters noisy entities
• writes:
  • week-XX.raw.json.gz
  • week-XX.summary.json
  • week-XX.suggestions.json
• updates /data/state/last_success.json
• runs inside a persistent add-on container and exports once per completed week

The current MVP targets the default SQLite recorder database used by Home Assistant.

Repository layout

config.yaml                 Home Assistant add-on metadata
DOCS.md                     add-on store instructions
Dockerfile                  add-on image build
run.sh                      add-on entrypoint
standalone.example.yaml     standalone sample config for local development
export_history.py           weekly export CLI
suggest_automations.py      regenerate suggestions from exported JSON
ha_history/                 Python package
tests/                      local tests

Files written by the add-on

With the default options, exports are written to:

/share/ha-history/<year>/week-XX.raw.json.gz
/share/ha-history/<year>/week-XX.summary.json
/share/ha-history/<year>/week-XX.suggestions.json

The add-on state is stored in:

/data/state/last_success.json

Step-by-step installation on Home Assistant OS

1. Create the add-on directory on the Home Assistant host:

   ssh ha 'mkdir -p /addons/ha-history-export'

2. Copy the repository contents into that directory.

   From your workstation:

   rsync -av --delete --exclude '.git' ./ ha:/addons/ha-history-export/

   If you use Samba or the File editor instead, copy the repository into:

   /addons/ha-history-export
   

3. Open Home Assistant:

   Settings -> Add-ons -> Add-on Store
   

4. Open the three-dot menu in the top right and click:

   Check for updates
   

5. Open HA History Export in the add-on store.

6. Click Install.

7. Open the Configuration tab and set at least:

   • recorder_db_path
   • output_dir

   By default, the add-on uses the system timezone from Home Assistant OS. Set timezone only if you want to override it manually.

   Default values already match a normal HA OS installation:

   recorder_db_path: /homeassistant_config/home-assistant_v2.db
   output_dir: /share/ha-history

8. Start the add-on.

9. Open the Logs tab. On first start, if the previous completed week has not been exported yet, the add-on will export it immediately.

10. Verify the files:

ssh ha 'find /share/ha-history -maxdepth 3 -type f | sort'

How scheduling works

The add-on stays running and checks every poll_interval_minutes whether the latest completed week is already exported.

• if that week is missing, it exports it immediately
• if that week is already exported, it waits

That means:

• a normal Monday export happens automatically
• if the add-on or host restarts later, the missed weekly export is still caught up

Updating the add-on

1. Copy the updated repository again:

   rsync -av --delete --exclude '.git' ./ ha:/addons/ha-history-export/

2. In Home Assistant, open Add-on Store and click Check for updates.

3. Open HA History Export and reinstall or update it if Home Assistant shows the new version.

Local development without Home Assistant OS

The exporter can still be run directly with a standalone config:

python3 -m pip install -r requirements.txt
python3 export_history.py --config ./standalone.example.yaml

Regenerating suggestions from exported files

python3 suggest_automations.py \
  --raw /share/ha-history/2026/week-19.raw.json.gz \
  --summary /share/ha-history/2026/week-19.summary.json \
  --output /share/ha-history/2026/week-19.suggestions.json

Notes

• The exporter is read-only against the Home Assistant recorder database.
• The suggestion engine only produces JSON candidates; it does not create or apply Home Assistant automations.
• PostgreSQL support is not implemented yet; the code raises a clear error if that backend is configured.
• The add-on includes a custom apparmor.txt; Home Assistant applies the extra security point after the add-on is installed and started.