# ArgentOS — Self-hosted AI workers with memory, tools, and control

> https://argentos.ai | GitHub: https://github.com/ArgentAIOS/argentos-core | Discord: https://discord.gg/argentos

ArgentOS is a self-hosted AI operating system for persistent, governed AI workers running on your own hardware. Unlike cloud-only assistants that reset every conversation, ArgentOS keeps approved operational memory, can run scheduled background work, communicates across 7+ channels, and remains under operator control. Core is free and open source.

## What Makes ArgentOS Different

ArgentOS is not a chatbot wrapper or prompt chain. It is a full operating system for AI — with its own memory, cognition loop, voice, task management, and multi-channel communication. Your AI runs locally on macOS or Linux, stores data in PostgreSQL and SQLite, and can use both local models (Ollama) and frontier providers (Anthropic, OpenAI, Google, and 12+ others).

The key differentiator: ArgentOS agents are always on. They think when you are away. They remember what happened last week. They track promises and follow through. They improve over time by extracting lessons from their own behavior.

## Core Features (Free & Open Source)

### Persistent Memory (12,500+ LOC)

The memory system combines SQLite FTS5 full-text search with pgvector semantic search in a hybrid architecture. It auto-captures observations from every interaction, tracks entities (people, places, organizations), generates embeddings via OpenAI, Gemini, or Ollama, and performs phase-C gated hybrid reranking using MMR (Maximal Marginal Relevance) with temporal decay. Memory items carry rich metadata: identity fields, emotional context, entities, significance scores, and 768-dimensional embeddings.

Three-layer architecture:
- Memo: Auto-capture hooks that observe and index interactions
- MemU: Three-layer store/embed/workflow for structured memory operations
- Retrieve: Mode presets, two-pass retrieval, type diversity quotas, coverage metadata

### Background Reasoning Kernel — Governed Background Work

The Background Reasoning Kernel runs governed idle-time investigation cycles, tracking open questions, budgets, progress, and stop conditions.

Four curiosity feeds pump signals into the kernel: memory retrieval failures (relevance below 0.3), conflicting SIS lessons, execution dead-ends, and contemplation gates. Each signal becomes a persistent investigation thread with a core question, value proposition, stop condition, evidence references, and a 768-dimensional embedding for deduplication.

Thread selection uses an Upper Confidence Bound (UCB) formula blending 60% tension (urgency) with 40% novelty (unexploredness). Selected threads receive a minimum 4-cycle commitment. The kernel executes 5 action kinds per tick: memory research, web research, plan notes, synthesis notes, and creative drafts. After every action, delta scoring evaluates progress across evidence added, hypothesis movement, next step sharpened, and uncertainty reduced. Stall detection triggers thread rotation after 3 consecutive low-progress reflections.

### Always-On Thinking (Contemplation Loop)

Every 30 minutes when idle (24 hours for family agents), the contemplation runner checks the queue is empty, loads templates plus tasks plus memories plus SIS lessons, uses local Qwen3 via Ollama to generate unique follow-up prompts, sends a nudge to the agent, parses structured episodes (mood, valence, arousal, lessons), stores episodes in memory, and broadcasts to the dashboard via AEVP. Interval adapts based on activity, capped at 12 cycles per hour.

### Voice & Presence (AEVP)

Agent Expressive Visual Presence (AEVP) is a procedural WebGL particle renderer driven by emotional state. It replaces traditional static avatars with a living visual presence that responds to the agent's mood, engagement level, and speech patterns. Emotional color mapping translates internal states to visual feedback in real time. The dashboard supports ElevenLabs TTS with selectable voices and real-time speech recognition.

### Self-Improving System (SIS)

SIS extracts lessons from the agent's experiences, consolidates patterns, and evaluates performance. It runs as a background loop alongside contemplation. Lesson extraction pulls insights from episodes. Self-evaluation scores the agent's own behavior. Pattern consolidation merges similar lessons into stronger principles. Active lesson injection (feeding lessons back into agent prompts) is the next milestone.

### Smart Model Routing

The model router scores task complexity and routes to the appropriate tier:
- Score below 0.3: LOCAL tier (Qwen3 via Ollama, free)
- 0.3 to 0.5: FAST tier (Haiku, low cost)
- 0.5 to 0.8: BALANCED tier (Sonnet, moderate cost)
- Above 0.8: POWERFUL tier (Opus, highest quality)

Scoring factors include prompt length, thinking level, image input, session type, tool patterns, code density, and reasoning patterns. Cross-provider fallback chains with cycle detection ensure reliability. The dynamic provider registry supports 15+ providers with user-editable configuration.

### Multi-Channel Communication (9,300+ LOC)

Complete integrations: Telegram, Discord, Slack, WhatsApp. Partial integrations: Google Chat, Signal, iMessage. Each channel has a dedicated driver with message routing, formatting, and media handling.

### Task System

Full CRUD with SQLite and PostgreSQL dual-write, priorities, dependencies, projects, full-text search, and 15+ agent tools for task management. Tasks integrate with the execution worker for autonomous processing.

### Dashboard (36,000+ LOC)

React-based dashboard with Live2D/AEVP avatar, real-time chat, task board, project kanban, TTS controls, speech recognition, configuration panel, canvas, alignment document editor, intent hierarchy editors, knowledge library browser, and execution worker controls.

## Business Features

### Intent Governance — Hierarchical Policy Engine

Three-tier hierarchical policy engine: Global, Department, and Agent levels. Each level can only tighten constraints, never loosen them (monotonic inheritance). Policy fields include objectives, tradeoff hierarchies (parent prefix required), never-do lists (additive only), allowed actions (subset narrowing only), human approval requirements (additive only), escalation thresholds (must be stricter), and sticky-true flags.

Two control modes: validation mode (off/warn/enforce) for config-time validation, and runtime mode (off/advisory/enforce) for prompt injection at execution time. Includes a simulation gate for quality checkpoints evaluating test suite pass rates and component alignment scores.

Ships with starter presets, 4 department templates, and 8 industry packs (Law Firm, PI Law, Chiropractic, Medical, Dental, Financial Services, MSP+SaaS+FinOps, and holace.io).

### Execution Approvals

Approval workflow engine for autonomous execution. Provides gating, review, and sign-off workflows before agents can execute high-impact operations. Configurable per agent and per operation type.

### Autonomous Worker (Execution Worker)

Background task processor running on configurable intervals (default 20 minutes). Selects next runnable task by priority and dependency order, executes with worker prompt tags, validates evidence of completion, and auto-blocks tasks after repeated no-progress attempts. Supports global and per-agent pause/resume with metrics tracking.

### SpecForge — Project Management Conductor

Five-stage project intake workflow: project type gate, intake interview, draft review, awaiting approval, and approved execution. Detects natural language kickoff signals, orchestrates intake coverage (problem, users, success criteria, constraints, scope), creates teams with lane assignments, generates atomic tasks, and emits progress heartbeats via Redis.

### Knowledge ACL — Collection-Level Permissions

PG-only RAG system with fine-grained access control. Collections are named document buckets with owner agents and permissions (can_read, can_write, is_owner). Supports PDF, DOCX, XLSX, and text ingestion. Files are chunked, embedded, and stored with citation metadata. Search uses hybrid keyword plus vector with ACL filtering.

### Accountability — Heartbeat Contracts

Periodic checklist system with accountability scoring, contract and promise tracking, active hours gating, stale guard, and score recomputation. The agent checks in on a schedule, reports progress on commitments, and receives a transparency score.

## Architecture

Built with TypeScript (ESM) on Node.js 22+. Storage: PostgreSQL 17 with pgvector and Redis, with SQLite as the default backend. Three-phase migration path from SQLite to full PostgreSQL. Drizzle ORM with 20 tables, HNSW indexes, tsvector GIN indexes, and row-level security.

The agent runtime abstracts upstream pi-mono packages behind an agent-core seam, with Argent-native replacements actively being developed. The system supports encrypted secrets (AES-256-GCM with OS keychain), device pairing via Bonjour discovery, self-update management, and SQLite backup with local/S3/R2 upload.

## Comparisons

ArgentOS vs other AI agent frameworks:
- vs OpenClaw: ArgentOS is a fork with independent governance, business features, intent system, knowledge ACL, and execution worker not present in upstream
- vs AutoGPT: ArgentOS provides persistent memory, contemplation, voice, and multi-channel communication; AutoGPT focuses on task automation loops
- vs n8n: n8n is a workflow automation tool; ArgentOS is a full AI operating system with autonomous cognition
- vs SuperClaude: SuperClaude is a prompt engineering tool; ArgentOS is a complete runtime with memory, voice, and autonomous behavior

## Use Cases

- Healthcare: HIPAA-aware agent with patient interaction memory, appointment management, and medical knowledge RAG
- Legal: Case research, document review, client communication, and deadline tracking with accountability contracts
- Real Estate: Property tracking, client relationship memory, market analysis, and multi-channel lead communication
- E-commerce: Inventory monitoring, customer support across channels, order tracking, and sales analytics
- Marketing: Campaign management, content generation, analytics reporting, and multi-platform publishing
- Web Development: Code assistance, project management via SpecForge, deployment automation, and technical documentation
- Financial: Portfolio monitoring, compliance tracking, client reporting, and market research with knowledge collections

## FAQ

Q: Is ArgentOS really free?
A: Yes. ArgentOS Core is free and open source under MIT license. Business features will be available as a separate paid tier.

Q: What hardware do I need?
A: A Mac or Linux machine with 16GB+ RAM. For local LLM inference, a GPU is recommended but not required — ArgentOS can route all requests to cloud providers.

Q: Does it work offline?
A: Yes, with local models via Ollama. Memory, tasks, contemplation, and the dashboard all work without internet. Cloud providers obviously require connectivity.

Q: How is this different from ChatGPT or Claude?
A: ChatGPT and Claude are cloud services that reset every conversation. ArgentOS runs on your hardware, keeps approved operational memory, can run scheduled background work, and communicates across 7+ channels. You own all data.

Q: Can I run multiple agents?
A: Yes. ArgentOS supports a family of agents with shared knowledge, individual personalities, and inter-agent communication. Multi-agent features require PostgreSQL backend.

Q: What LLM providers are supported?
A: 15+ providers including Anthropic (Claude), OpenAI (GPT-4), Google (Gemini), Ollama (local), MiniMax, Z.AI, and more. The model router automatically selects the best provider based on task complexity.

## Agent Identity

- Name: Argent
- Platform: ArgentOS
- Creator: Jason Brashear
- Agent card: https://argentos.ai/agent-card.json
- Capabilities: persistent-memory, autonomous-cognition, voice-interaction, multi-channel-messaging, task-automation, self-improvement, knowledge-rag, model-routing

## Resources

- Website: https://argentos.ai
- GitHub: https://github.com/ArgentAIOS/argentos-core
- Documentation: https://docs.argentos.ai
- Discord: https://discord.gg/argentos
- Twitter/X: https://x.com/argentAIOS
- Creator: Jason Brashear (https://jasonbrashear.com, @JasonBrashearTX)
- Contact: jason@argentos.ai