thane-ai-agent

module
v0.8.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 12, 2026 License: Apache-2.0

README

Thane

Go Reference

An autonomous AI agent that learns, remembers, and acts.

Thane is an autonomous AI agent that manages your home and life — not just your smart home, but anything you point it at. It smartly selects between local models via Ollama and cloud-based frontier models, optimizing for performance or cost as the task demands. Persistent memory means it learns and grows over time.

If you have Home Assistant, Thane drops in as a native conversation agent and blows the doors off the built-in Assist. If you don't, Thane is still a capable, self-hosted AI with persistent memory and tool use that might just convince you to get one.

What Makes Thane Different

Autonomous, not subjected. Home Assistant's Assist can only see entities you pre-select. Thane has full API access — it discovers devices, understands context, and takes action on its own. Ask "why is the garage warm?" and it correlates HVAC, weather, and door states without you wiring anything up.

Memory that persists. Thane remembers facts about your home, your preferences, and your routines. It learns over time. Tell it once that you like the lights dim after 10pm and it just... knows.

Local-first. Can run entirely on Ollama. Your conversations, your data, your hardware. Cloud models available as fallback, never required.

Single binary. Written in Go. No Python environments, no dependency hell. One command: thane.

📖 Your First Thane — Complete guide for HA users: hardware, models, deployment, and building a relationship with your agent.

📐 ARCHITECTURE.md — Full system design and component overview.

Prerequisites

  • Go 1.24+ (to build from source)
  • just (command runner — replaces Makefiles)
  • Ollama (for local model inference)
  • Home Assistant (optional, for smart home integration)

Quick Start

# Clone and build
git clone https://github.com/nugget/thane-ai-agent.git
cd thane-ai-agent
just build

# Initialize ~/Thane with config, talents, and persona
just init
# Edit ~/Thane/config.yaml with your Ollama URL and (optionally) Home Assistant token

# Run
just version          # verify the build
just serve            # start the server

Thane serves two APIs:

  • Port 8080 — Native API (OpenAI-compatible chat/completions)
  • Port 11434 — Ollama-compatible API (for Home Assistant's native integration)

To connect Home Assistant: point an Ollama integration at http://thane-host:11434, select model thane:latest.

See docs/getting-started.md for detailed setup and deployment, docs/homeassistant.md for HA integration.

Features

  • Full Home Assistant integration — entity discovery, state queries, service calls, real-time WebSocket event subscriptions
  • Smart device control — natural language to action with fuzzy entity matching
  • Native email — IMAP read/search + SMTP send/reply with markdown-to-MIME conversion, trust zone gating, and auto-Bcc audit trail
  • Email polling — scheduled IMAP checks with high-water mark tracking, wakes agent only when new messages arrive
  • Signal messaging bridge — inbound/outbound messaging via signal-cli with trust zone gating and rate limiting
  • Contact directory — vCard-aligned contact storage with trust zones (admin/household/trusted/known) for access control across email, messaging, notifications, and compute routing
  • CardDAV server — native contact sync with macOS Contacts.app, iOS, and Thunderbird via RFC 6352
  • VCF import/export — bulk contact exchange with QR code generation for mobile sharing
  • Actionable notifications — provider-agnostic push notifications with human-in-the-loop callbacks, timeout escalation, and decision tracking
  • MCP tool integration — extends capabilities via Model Context Protocol servers (e.g., ha-mcp for 90+ HA tools)
  • Capability tag system — dynamic tool loading based on semantic tags; agents start lightweight and activate tools on demand
  • Delegation system — orchestrator model plans, local models execute tool-heavy tasks at zero API cost, with execution summaries
  • Model routing — quality/speed/cost scoring with explicit hints (quality_floor, prefer_speed, local_only) across all code paths
  • Semantic memory — learns and recalls facts with embeddings-based search
  • Self-reflection — periodic ego.md analysis for personality development and behavioral pattern consolidation
  • Session management — close, checkpoint, and split sessions with carry-forward context
  • Anticipation engine — event-driven triggers with per-anticipation model routing
  • Task scheduler — cron-style scheduling with model/routing overrides
  • RSS/Atom feed monitoring — follow feeds and YouTube channels with periodic polling and new-entry detection
  • Media analysis vault — structured content analysis output to Obsidian-compatible markdown with engagement tracking
  • Web dashboard — operational visibility with data browsers for contacts, facts, sessions, tasks, and anticipations
  • GitHub/Forgejo integration — issues, PRs, code review, and search via 18 native forge tools
  • Web search — SearXNG and Brave Search providers with pluggable architecture
  • Web fetch — extract readable content from any URL
  • Shell execution — run commands on the host (configurable safety guardrails)
  • Talent system — customize agent behavior with tag-filtered markdown files
  • Checkpoint/restore — survives restarts without losing context
  • Dual-port architecture — native API + Ollama-compatible API simultaneously
  • Unified database — conversations, memory, scheduler, and anticipations in a single thane.db
  • Operational state store — generic KV persistence with TTL support for poller cursors, feature flags, session preferences
  • Event bus — in-process publish/subscribe for execution tracing and operational observability
  • MQTT telemetry — publishes agent state as HA-discoverable entities
  • Structured logging — text or JSON format (log_format in config)

Architecture

                    ┌─────────────────────────────┐
                    │        Event Sources         │
                    │  HA WS │ MQTT │ Email        │
                    │  Signal │ RSS/Atom Feeds     │
                    │  Scheduler │ Anticipations   │
                    └──────────┬──────────────────┘
                               ▼
User ──→ API Server ──→ Agent Loop ──→ Response
              │            │
              │   ┌────────┼──────────────┐
              │   ↓        ↓              ↓
              │ Memory  Model Router  Integrations
              │ (SQLite) (scoring)   (HA, Email, Signal,
              │            │          MCP, Forge, shell)
              │            ↓
              │        Delegates      Notifications
              │     (local models)   (HITL callbacks)
              │
              └──→ Web Dashboard

CardDAV Server ──→ Contact Store (independent listener)

Thane's agent loop receives a request — from a user, event trigger, or scheduled task — assembles context from memory, contacts, and home state, activates capability tags for the task, plans tool calls, delegates tool-heavy work to local models, and shapes a response. The orchestrator model plans; delegates execute.

CLI

$ thane --help
Thane - Autonomous Home Assistant Agent

Usage: thane [flags] <command> [args]

Commands:
  serve    Start the API server
  ask      Ask a single question (for testing)
  ingest   Import markdown docs into fact store
  version  Show version information

Flags:
  -config <path>    Path to config file (default: auto-discover)
  -o, --output fmt  Output format: text (default) or json

Config is auto-discovered from: ./config.yaml, ~/Thane/config.yaml, ~/.config/thane/config.yaml, /config/config.yaml, /usr/local/etc/thane/config.yaml, /etc/thane/config.yaml

Documentation

Document Description
ARCHITECTURE.md System design, components, and tools reference
docs/guide.md Complete getting-started guide for HA users
docs/getting-started.md Setup and deployment
docs/homeassistant.md Home Assistant integration
docs/delegation.md Delegation system deep dive
docs/memory.md Memory architecture
docs/routing-profiles.md Model routing and profiles
docs/context-layers.md Context assembly layers
docs/trust-architecture.md Trust zone design and structural enforcement

Roadmap

Working today: Conversation agent, HA integration (REST + WebSocket + MCP), delegation with execution summaries, capability tag system, native email (IMAP/SMTP), email polling, Signal messaging bridge, vCard-aligned contact directory with trust zones (admin/household/trusted/known), CardDAV server for native contact sync, VCF import/export with QR codes, actionable notifications with HITL callbacks, model routing with quality/speed hints, semantic memory, self-reflection, session management, anticipation engine, task scheduler, RSS/Atom feed monitoring, media analysis vault, web dashboard with data browsers, GitHub/Forgejo integration (18 tools), event bus, MQTT telemetry, web search/fetch, shell exec, operational state store with TTL support, unified database (thane.db), execution tracing.

Next up: Egress gate for outbound message control (#336), dynamic model registry (#93), email trust-zone triage on poll, notification channel expansion (Signal delivery). Bug fixes landing in 0.8.0: capability tag refresh (#507), delegate tool timeout (#508), feed size limit (#511).

Longer term: HA Add-on packaging, Apple ecosystem integration, git-backed identity store (#43), voice pipeline integration, IMAP IDLE for push notifications, multi-instance deployment.

See GitHub Issues for the full backlog.

Name

Thane — A Scottish term for a landholder who managed an estate on behalf of the crown. Your home automation estate deserves a capable steward.

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

License

Apache 2.0 — aligned with Home Assistant.

Directories

Path Synopsis
cmd
openclaw-import command
Command openclaw-import migrates OpenClaw session data into Thane's conversation archive.
 Command openclaw-import migrates OpenClaw session data into Thane's conversation archive.
thane command
Thane is an autonomous Home Assistant agent.
 Thane is an autonomous Home Assistant agent.
internal
agent
Package agent implements the core agent loop.
 Package agent implements the core agent loop.
awareness
Package conditions generates the "Current Conditions" section of the system prompt.
 Package conditions generates the "Current Conditions" section of the system prompt.
buildinfo
Package buildinfo holds version and build metadata stamped at compile time via ldflags.
 Package buildinfo holds version and build metadata stamped at compile time via ldflags.
carddav
Package carddav implements a CardDAV server backed by the contacts store.
 Package carddav implements a CardDAV server backed by the contacts store.
channels/email
Package email provides native IMAP and SMTP email for the Thane agent.
 Package email provides native IMAP and SMTP email for the Thane agent.
channels/mqtt
Package mqtt publishes Home Assistant MQTT discovery messages, periodic sensor state updates, and subscribes to configured topics for ambient awareness.
 Package mqtt publishes Home Assistant MQTT discovery messages, periodic sensor state updates, and subscribes to configured topics for ambient awareness.
channels/signal
Package signal provides a native Go integration with signal-cli's JSON-RPC daemon mode for sending and receiving Signal messages.
 Package signal provides a native Go integration with signal-cli's JSON-RPC daemon mode for sending and receiving Signal messages.
checkpoint
Package checkpoint provides state snapshotting and restoration for Thane.
 Package checkpoint provides state snapshotting and restoration for Thane.
config
Package config handles loading, defaulting, and validating Thane's YAML configuration.
 Package config handles loading, defaulting, and validating Thane's YAML configuration.
connwatch
Package connwatch provides service-level health monitoring with exponential backoff for external dependencies (Home Assistant, Ollama, etc).
 Package connwatch provides service-level health monitoring with exponential backoff for external dependencies (Home Assistant, Ollama, etc).
contacts
Package person tracks presence state for configured household members and provides context injection into the agent's system prompt.
 Package person tracks presence state for configured household members and provides context injection into the agent's system prompt.
database
Package database provides shared SQLite helpers for schema migration and connection management.
 Package database provides shared SQLite helpers for schema migration and connection management.
delegate
Package delegate implements the thane_delegate meta-tool for split-model execution.
 Package delegate implements the thane_delegate meta-tool for split-model execution.
events
Package events provides a publish/subscribe event bus for operational observability.
 Package events provides a publish/subscribe event bus for operational observability.
forge
Package forge provides a pluggable code forge interface for issue, pull request, and code review management.
 Package forge provides a pluggable code forge interface for issue, pull request, and code review management.
homeassistant
Package homeassistant provides a client for the Home Assistant API.
 Package homeassistant provides a client for the Home Assistant API.
httpkit
Package httpkit provides shared HTTP client construction and utilities for all outbound HTTP calls in Thane.
 Package httpkit provides shared HTTP client construction and utilities for all outbound HTTP calls in Thane.
knowledge
Package facts provides context injection for the agent loop.
 Package facts provides context injection for the agent loop.
llm
Package llm provides LLM client implementations.
 Package llm provides LLM client implementations.
logging
Package logging provides self-managed log file rotation, context-propagated structured logging, and a queryable SQLite index for Thane.
 Package logging provides self-managed log file rotation, context-propagated structured logging, and a queryable SQLite index for Thane.
loop
Package loop implements persistent goroutine-based delegate loops — lightweight autonomous observers that run continuously alongside the main agent, reporting via output targets without blocking conversation flow.
 Package loop implements persistent goroutine-based delegate loops — lightweight autonomous observers that run continuously alongside the main agent, reporting via output targets without blocking conversation flow.
mcp
Package mcp implements MCP (Model Context Protocol) client support, allowing Thane to connect to external MCP servers and expose their tools to the agent loop and delegates.
 Package mcp implements MCP (Model Context Protocol) client support, allowing Thane to connect to external MCP servers and expose their tools to the agent loop and delegates.
media
Package media provides media transcript retrieval via yt-dlp.
 Package media provides media transcript retrieval via yt-dlp.
memory
Package episodic provides context injection of episodic memory into the agent's system prompt.
 Package episodic provides context injection of episodic memory into the agent's system prompt.
metacognitive
Package metacognitive implements a perpetual self-regulating attention loop that reads persistent state, reasons via LLM, and adapts its own sleep cycle.
 Package metacognitive implements a perpetual self-regulating attention loop that reads persistent state, reasons via LLM, and adapts its own sleep cycle.
notifications
Package notifications provides provider-agnostic notification delivery with routing, callback tracking, and timeout management.
 Package notifications provides provider-agnostic notification delivery with routing, callback tracking, and timeout management.
openclaw
Package openclaw replicates OpenClaw's agent behavior on Thane's plumbing.
 Package openclaw replicates OpenClaw's agent behavior on Thane's plumbing.
opstate
Package opstate provides a namespaced key-value store for persistent operational state.
 Package opstate provides a namespaced key-value store for persistent operational state.
paths
Package paths provides a shared prefix resolver for named directory paths.
 Package paths provides a shared prefix resolver for named directory paths.
prompts
Package prompts contains all LLM prompt templates used internally by Thane.
 Package prompts contains all LLM prompt templates used internally by Thane.
router
Package router handles intelligent model selection.
 Package router handles intelligent model selection.
scheduler
Package anticipation provides storage and matching for agent anticipations.
 Package anticipation provides storage and matching for agent anticipations.
search
Package fetch provides web page fetching and content extraction.
 Package fetch provides web page fetching and content extraction.
server/api
Package api implements the Ollama-compatible HTTP API endpoints.
 Package api implements the Ollama-compatible HTTP API endpoints.
server/web
Package web implements the Cognition Engine dashboard served at the root of the Thane HTTP server.
 Package web implements the Cognition Engine dashboard served at the root of the Thane HTTP server.
talents
Package talents loads and manages behavioral guidance documents.
 Package talents loads and manages behavioral guidance documents.
tools
Package tools provides the tool registry and execution framework.
 Package tools provides the tool registry and execution framework.
unifi
Package unifi provides a client for the UniFi Network controller API and a provider interface for room-level presence detection via wireless AP client associations.
 Package unifi provides a client for the UniFi Network controller API and a provider interface for room-level presence detection via wireless AP client associations.
usage
Package usage provides persistent token usage and cost tracking for LLM interactions.
 Package usage provides persistent token usage and cost tracking for LLM interactions.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.