Argonaut Agent

Argonaut is the self-hosted personal AI agent that powers the intelligent automation layer of Arcturus-Prime. 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 Izar-Host (10.42.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 [email protected])
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:

packages/argonaut/data/rag-store.db — the primary knowledge base containing embeddings and metadata for general content (docs, projects, personal notes)
packages/argonaut/data/rag-store-blog.db — a dedicated store for blog and journal content, kept separate for performance and to allow independent reindexing

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.

Hybrid Search

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

Vector search — the query is embedded using the same model as the index (nomic-embed-text on Ollama at localhost:11434 or text-embedding-3-small via OpenRouter). The resulting vector is compared against all stored embeddings using cosine similarity. Top-K results are retrieved.
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