Argonaut Agent

Argonaut is the self-hosted personal AI agent that powers the intelligent automation layer of ArgoBox. It lives in packages/argonaut/ and operates in two modes: a lightweight cloud mode deployed to Cloudflare Workers, and a full local mode running as a daemon on the homelab with complete access to tools, RAG, memory, and scheduling.

Dual-Mode Architecture

Cloud Mode (Workers)

The cloud deployment runs on Cloudflare Workers and handles lightweight, latency-sensitive operations. In this mode, Argonaut can:

Respond to incoming webhooks (email, calendar events, monitoring alerts)
Route requests to the appropriate handler
Perform simple tool calls that do not require local resources
Queue tasks for the local agent to pick up

Cloud mode is stateless. It stores nothing locally and relies on the local agent for persistent storage, RAG lookups, and heavy computation. The Workers deployment is configured in packages/argonaut/wrangler.toml.

Local Mode (Full Agent)

The local deployment runs as a daemon process on a CT on Proxmox IO (10.0.0.2). In this mode, Argonaut has full capabilities:

Complete tool system with file operations, code execution, and network access
SQLite-backed RAG with vector search and BM25 hybrid retrieval
Persistent memory system with compaction
Scheduled task execution via cron
Multi-agent coordination
Direct access to homelab services on the local network

The local agent starts with node packages/argonaut/src/index.js and runs as a systemd service. It exposes an HTTP API on port 3100 for receiving requests from the cloud worker, the admin UI, and other internal services.

Capabilities

Email (Resend)

Argonaut sends and processes email using the Resend API. It can:

Send emails on behalf of the user (compose and send from argo@argobox.com)
Process incoming emails forwarded via webhook
Draft email responses based on conversation context
Schedule email follow-ups

The Resend API key is stored as RESEND_API_KEY in the agent's environment.

Calls (Twilio + ElevenLabs TTS)

Argonaut can initiate and receive phone calls using Twilio for telephony and ElevenLabs for text-to-speech voice synthesis:

Outbound calls — Argonaut generates speech from text using ElevenLabs TTS, then places calls via Twilio's API. The voice is configured to match a custom ElevenLabs voice clone.
Inbound calls — Twilio webhooks route incoming calls to Argonaut's handler, which can respond with TTS or route to voicemail.
Call transcription — Twilio provides real-time transcription that Argonaut processes for context.

Configuration: TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER, ELEVENLABS_API_KEY.

Google Calendar

Argonaut integrates with Google Calendar for scheduling:

Read upcoming events and provide daily briefings
Create new calendar events from natural language instructions
Send meeting reminders with relevant context from memory
Block focus time based on task priorities

The integration uses a Google service account with calendar API access. Credentials are stored in packages/argonaut/data/google-credentials.json.

Web Search

Argonaut can search the web using the web-search tool, which queries a search API and returns structured results. Search is used for fact-checking, research tasks, and answering questions that require up-to-date information beyond the knowledge base.

File Operations

The file-ops tool provides read, write, list, and delete operations on the local filesystem within a sandboxed directory (packages/argonaut/data/workspace/). This is used for:

Saving research results
Creating draft documents
Managing downloaded files
Storing intermediate computation results

RAG System

Argonaut's RAG (Retrieval-Augmented Generation) system provides contextual knowledge for all agent interactions. It uses a hybrid search approach combining vector similarity and BM25 keyword matching.

Storage

RAG data is stored in SQLite databases across three tiers:

rag-store-blog.db — Knowledge/Safe tier (33,101 chunks). Sanitized via identity_map.json at ingest time. Safe for any AI provider. Selected via mode: 'blog' in the chat UI as "Knowledge (Safe)".
rag-store-vaults.db — Vaults tier (132,151 chunks). Personal notes, conversations, session archives. The most comprehensive dataset. Selected via mode: 'vaults' as "Vaults (Personal)".
rag-store.db — Private tier (166K chunks). Includes credentials, secrets, and legal documents. Selected via mode: 'default' as "Private (Secrets)". Requires a separate password (ARGONAUT_PRIVATE_PASSWORD) and all access is logged to ~/Vaults/security/argonaut-private-audit.log.

Three embedding models are available: nomic-embed-text (768d), qwen3-embedding:0.6b (1024d), and qwen3-embedding:8b (4096d). Current database dimensions:

Database	Embedding Model	Dimensions
rag-store.db (Private)	nomic-embed-text	768
rag-store-blog.db (Knowledge)	qwen3-embedding:0.6b	1024
rag-store-vaults.db (Vaults)	qwen3-embedding:0.6b	1024

Embedding auto-detection: The agent probes each SQLite store for stored vector dimensions on init and automatically selects the matching Ollama model. This avoids dimension mismatches that would silently disable vector search.

Vector scan cap: Brute-force cosine similarity is capped at 200 MB of embedding data. Databases exceeding this (all current ones at scale) fall back to BM25-only keyword search, which is fast and still returns relevant results (~0.3 scores). Future improvement: add ANN (approximate nearest neighbor) indexing or re-embed with a smaller model.

Databases are also mirrored to /mnt/AllShare/rag/databases/. Each database contains tables for documents, chunks, embeddings, and metadata. The schema supports incremental updates so individual documents can be re-embedded without rebuilding the entire index.

RAG Scope Selector

The chat UI at /admin/argonaut/chat includes a scope dropdown in the top bar:

Scope	Database	Chunks	Auth	Color
Knowledge (Safe)	rag-store-blog.db	33,101	Admin only	Green
Vaults (Personal)	rag-store-vaults.db	132,151	Admin only	Blue
Private (Secrets)	rag-store.db	166K	Admin + password	Red

When selecting "Private (Secrets)", a modal prompts for the private password. Failed attempts are logged. The password is set via ARGONAUT_PRIVATE_PASSWORD in the .env file.

Environment variables:

ARGONAUT_BLOG_RAG_INDEX — path to knowledge/safe database (default: packages/argonaut/data/rag-store-blog.db)
ARGONAUT_VAULTS_RAG_INDEX — path to vaults database (default: packages/argonaut/data/rag-store-vaults.db)
ARGONAUT_RAG_INDEX — path to private database (default: packages/argonaut/data/rag-store.db)
ARGONAUT_PRIVATE_PASSWORD — password for private scope access

Hybrid Search

When a query comes in, the RAG system executes two parallel searches:

Vector search — the query is embedded using the auto-detected model matching the database's stored dimensions (via Ollama at localhost:11434). The resulting vector is compared against stored embeddings using cosine similarity. Top-K results are retrieved. Note: Vector search is skipped when the brute-force scan would exceed 200 MB (all current databases at scale), falling back to BM25-only.
BM25 search — the query terms are matched against the full-text index using BM25 scoring. This catches exact keyword matches that vector search might miss, especially for technical terms, error messages, and proper nouns.

Results from both searches are merged using reciprocal rank fusion (RRF). The fused results are re-ranked by a lightweight cross-encoder, and the top chunks are returned as context for the AI model.

RAG Manifest

The file packages/argonaut/data/rag-manifest.json tracks the state of the RAG index:

Which documents have been indexed and their last-modified timestamps
Chunk count per document
Embedding model and dimension used
Last full rebuild timestamp
Incremental update history

The manifest enables efficient incremental updates: only documents modified since the last index are re-embedded.

Memory System

Argonaut maintains a persistent memory that accumulates across all interactions. The memory system stores facts, preferences, decisions, and context that the agent can recall in future conversations.

Memory Storage

Memories are stored in packages/argonaut/data/memory.db (SQLite) with the schema:

content — the memory text
timestamp — when the memory was created
source — which conversation or task generated it
importance — a 1-10 score indicating how important the memory is
embedding — vector embedding for semantic search
tags — categorical tags for filtering

Memory Compaction

Over time, the memory store grows large with redundant and low-importance entries. The compaction process periodically:

Groups related memories by semantic similarity
Merges redundant memories into consolidated summaries
Drops memories below a configurable importance threshold
Re-embeds the compacted memory set

Compaction runs automatically when the memory count exceeds a threshold (default: 1000 entries) or can be triggered manually from the admin UI.

Tool System

Argonaut's tool system defines a set of capabilities the agent can invoke during conversations. Each tool is defined with a name, description, parameter schema, and execution function.

Available Tools

Tool	Description
`email`	Send email via Resend API
`exec`	Execute shell commands in a sandboxed environment
`web-fetch`	Fetch a URL and return the content
`web-search`	Search the web and return results
`file-ops`	Read, write, list, delete files in the workspace
`memory-search`	Query the memory system for relevant past context
`calendar`	Read and create Google Calendar events
`rag-query`	Search the RAG knowledge base
`call`	Initiate a phone call via Twilio

Tools are defined in packages/argonaut/src/tools/ with one file per tool. The agent selects tools based on the conversation context and executes them in sequence or parallel as needed.

Profile System

Argonaut's behavior is configured through a set of profile documents stored in packages/argonaut/profiles/:

Profile	Purpose
`IDENTITY.md`	Core identity: name, role, personality traits
`SOUL.md`	Values, ethics, and behavioral boundaries
`BOOT.md`	Startup instructions and initialization sequence
`TOOLS.md`	Tool usage guidelines and preferences
`USER.md`	Information about the primary user (preferences, context)
`AGENTS.md`	Known agents for multi-agent coordination
`BLOG_WRITER.md`	Specialized profile for blog content generation
`HEARTBEAT.md`	Configuration for scheduled heartbeat tasks

These profiles are loaded at agent startup and included as system context. They can be edited through the admin UI at /admin/argonaut/profiles.

Multi-Agent Coordination

Argonaut can coordinate with other AI agents in the system. The AGENTS.md profile defines known agents and their capabilities. Coordination supports:

Task delegation — Argonaut can assign subtasks to specialized agents
Information sharing — agents can query each other's knowledge bases
Workflow chains — multi-step workflows where different agents handle different stages

Communication between agents uses HTTP APIs on the local network. Each agent exposes a standard /agent/message endpoint for receiving coordination messages.

Scheduled Tasks (Cron)

The heartbeat system runs scheduled tasks defined in HEARTBEAT.md. Each task specifies:

A cron expression for when to run
A description of what to do
Required tools and context

Example scheduled tasks:

Daily briefing (0 7 * * *) — compile calendar events, unread emails, and pending tasks into a morning briefing
Content review (0 12 * * 1) — scan the review queue and generate summaries of pending content
Memory compaction (0 3 * * 0) — run weekly memory compaction
Health check (*/15 * * * *) — check homelab services and report any issues

Docker Deployment

The local Argonaut agent is containerized for consistent deployment:

Dockerfile at packages/argonaut/Dockerfile — Node.js 20 alpine image with SQLite and build tools
docker-compose.yml at packages/argonaut/docker-compose.yml — defines the service with volume mounts for persistent data, environment variable injection, port mapping (3100:3100), and restart policy

Volumes mount packages/argonaut/data/ for persistent storage of SQLite databases, the workspace directory, and profile documents.

Admin UI

The Argonaut admin interface is accessible through several routes under /admin/argonaut:

Hub (/admin/argonaut) — overview of agent status, recent activity, and quick actions
Chat (/admin/argonaut/chat) — direct conversation with Argonaut
Profiles (/admin/argonaut/profiles) — edit the agent's profile documents
Tasks (/admin/argonaut/tasks) — view and manage scheduled tasks and their execution history
Writer (/admin/argonaut/writer) — the blog writing assistant powered by Argonaut with the BLOG_WRITER.md profile active

Dashboard RAG Stats

The hub page displays aggregated RAG statistics across all three scopes. In production (CF Pages), local SQLite databases are inaccessible, so the dashboard uses a two-tier data strategy:

Live API (/api/argonaut/ingest) — tries direct SQLite or daemon proxy
Static snapshot (/rag-stats.json) — generated at build time by scripts/build-rag-stats.js, includes all 3 scopes with collection breakdowns

The dashboard merges these: if the live API returns no scope data (daemon mode), it falls back to the static snapshot. The status bar RAG chunk count also uses the snapshot when it reports a higher total than the daemon.

Collection data is displayed in collapsible rows — three scope summary rows (Knowledge, Vaults, Private) with click-to-expand collection detail underneath. A "Snapshot from Xh ago" note appears when using build-time data.