antaris-agent 2.5.7

Antaris — Personal AI assistant. Single-package install for the core agent. Optional extras enable channels and integrations.

Antaris-Agent

A self-hosted AI assistant with persistent memory, tool use, and local-first control surfaces.

Single-package install for the core agent. Optional extras enable channels and integrations. Persistent memory. Five security levels. Runs on your machine — no cloud, no subscriptions beyond your LLM key.

pip install antaris-agent
antaris init
antaris start

v2.5.7 · Python 3.10+ · 25 built-in tools · Apache 2.0

---

Contents

• What Is This?

• Quick Start

• Install Extras

• Feature Overview

• Core Features

  • Memory That Persists
  • Persona System
  • Compaction Safety
  • Smart Reconnect Briefings

• Interaction Features

  • Teach Your Bot
  • Focus Mode
  • Conversation Threading
  • Proactive Memory
  • Shortcut Learning
  • Mood-Aware Responses
  • Reaction Feedback
  • Conversation Export
  • User Profiles

• Tool System

  • Built-in Tools
  • Google Workspace
  • Image & Screenshot UX
  • Video Understanding
  • PowerPoint
  • MCP Client
  • JavaScript Tool Bridge
  • Tool Security

• Platform Features

  • Multi-Channel Support
  • Multi-Provider Routing
  • Multi-Session Support
  • Cron Scheduler
  • Subagents
  • Cost Tracking
  • Daemon & IPC
  • Self-Repair

• Security

  • Five Security Levels
  • Guard Modes
  • Config Protection

• Extensions & Integrations

  • Auth Monitor
  • Model Control
  • Desktop Control
  • Webhooks
  • Custom Skills
  • Migration Wizard

• All Commands

• Configuration

• Architecture

• Project Layout

• Bundled Dependencies

• Testing

• Changelog

• License

---

What Is This?

Antaris is a self-hosted AI assistant that actually learns. It remembers your conversations, adapts to how you work, and can take real actions — searching the web, managing files, reading your email, building slide decks, controlling your desktop.

Most AI bots forget everything between sessions. Antaris doesn't. Every conversation is stored locally, searchable forever, with automatic classification so facts persist while small talk fades.

Who it's for:

• Developers who want a programmable, extensible AI assistant they fully control
• Power users migrating from OpenClaw who want more out-of-the-box capability
• Anyone who wants an AI that actually gets better the more you use it

What makes it different:

• Memory that persists across sessions, channels, and restarts
• Learns your shortcuts, adapts to your mood, tracks your feedback
• 30+ built-in tools — from web search to Google Workspace to PowerPoint
• Five enforced security levels (not just disclaimers)
• Runs on Discord, Telegram, Slack, or just your terminal

---

Quick Start

1. Install

pip install antaris-agent

No extra system packages are required for the baseline install. Some optional features still rely on external tools or extras — see Install Extras and the feature notes below.

2. Setup

antaris init

The setup system now supports both a simple init flow and a browser-based multi-wizard hub.

Browser-based setup examples:

• antaris setup — open the wizard hub
• antaris setup --wizard general — core runtime, provider, security
• antaris setup --wizard integrations — Discord / Telegram / Slack / Google Workspace
• antaris setup --wizard automation — media, docs, webhooks, auth monitoring
• antaris setup --wizard power — extensions, skills, model switching, browser/desktop/terminal control

For automated setup: antaris init --headless

3. Run

antaris start            # launch on all configured channels
antaris start --terminal # terminal only
antaris chat             # quick terminal conversation, no setup needed

4. Verify

antaris pulse            # pre-launch health check
antaris doctor           # diagnostic scan (read-only)
antaris status           # running bot status

---

Install Extras

The base install (pip install antaris-agent) covers the core runtime. Some integrations and features require extras and/or external tools.

# Channel adapters
pip install "antaris-agent[discord]"
pip install "antaris-agent[telegram]"
pip install "antaris-agent[slack]"

# Security
pip install "antaris-agent[encrypted]"     # Encryption key management (keyring + cryptography)
pip install "antaris-agent[secure-store]"   # OS keychain integration

# Google Workspace
pip install "antaris-agent[google]"

# PowerPoint
pip install "antaris-agent[powerpoint]"

# Everything
pip install "antaris-agent[all]"

---

Feature Overview

Antaris has a lot of surface area. Here's how it's organized:

Layer	What It Covers	Who It's For
Core	Memory, persona, conversation, safety	Everyone
Interaction	Teaching, focus mode, mood, feedback, threading	Daily users
Tools	Web search, files, browser, Google, video, slides	Power users
Platform	Multi-channel, sessions, cron, subagents	Multi-device / automation
Security	Five levels, guard, audit, encryption	Production / shared use
Extension	Webhooks, auth monitor, model control, custom skills	Developers

Read what you need. Skip what you don't. Every feature works independently.

---

Core Features

These are always active. No configuration needed beyond antaris init.

🧠 Memory That Persists

Powered by parsica-memory — an 11-layer BM25+ search engine with semantic decay ranking. No vector database. No cloud storage. Files on your machine.

How it works:

• Every conversation is permanently stored, searchable, and relevance-ranked
• Memories are scoped per user — each person gets isolated storage
• Recent memories score higher (decay weighting)
• On session start, the bot pulls recent context and injects it — you never start from scratch

Auto-classification at ingest time:

• Semantic memories (facts, decisions, preferences) persist across sessions
• Episodic memories (casual chat, task logs) stay scoped to the current session

Six memory types with different decay rates:

Type	Decay	Use Case
episodic	Normal	General conversation
semantic	Normal	Facts and decisions (crosses sessions)
fact	Normal	Verified knowledge
mistake	10× slower	Failures — never forget
preference	3× slower	User preferences
procedure	3× slower	How-to knowledge

!memory         — view conversation history length
!memory clear   — clear your conversation context

Config: memory.store, memory.searchLimit, memory.minRelevance, memory.perTurnRecall

🎭 Persona System

Drop a SOUL.md file in ~/.antaris/ to define the bot's personality. The bot runs an awakening sequence on first start to discover its identity.

Additional identity files (controlled via context.json):

File	Purpose	Default Cadence
SOUL.md	Core personality	Every message
AGENTS.md	Behavioral rules	Every message
MEMORY.md	Curated long-term memory	Startup only
TOOLS.md	Environment-specific notes	Startup only
USER.md	User information	Manual

antaris persona show     # view current SOUL.md
antaris persona edit     # edit in $EDITOR
antaris persona reset    # reset and trigger awakening

🛡️ Compaction Safety

Context compaction (when conversation history gets too long) is the #1 cause of AI amnesia. Antaris has three-layer defense:

1. Early warning (75%): Auto-saves session summary to searchable memory before context fills up
2. Alert (at threshold): DMs the owner, persists full session summary to searchable memory
3. Post-compaction restore: Rebuilds context from MEMORY.md + BM25 on first message after compaction. Context rebuilt = context.keepRecentTokens

Config: context.maxTokens, context.keepRecentTokens, bot.compactionThreshold, bot.preCompactionRatio

📋 Smart Reconnect Briefings

Catch up after being away:

!gather 12               — LLM-summarized briefing of last 12 hours

Valid intervals: 3, 6, 12, 18, 24, 48 hours. Each summary is also ingested into memory.

---

Interaction Features

Features that make the bot learn and adapt to you over time.

📚 Teach Your Bot

Explicitly teach facts and preferences that persist permanently:

!teach my timezone is PST
!teach I prefer concise answers
!teach when I say "deploy" I mean push to PyPI and restart
!teach list              — see all teachings
!teach remove 3          — remove teaching #3
!teach clear             — clear all

Teachings are stored per-user and injected into every conversation.

🎯 Focus Mode

Tell the bot what you're working on. Memory recall and responses bias toward that topic.

!focus antaris-agent 2h  — focus for 2 hours
!focus website           — focus indefinitely
!unfocus                 — exit focus mode

🧵 Conversation Threading

The bot detects topic shifts and files turns into named threads automatically.

!threads                 — list all threads
!thread website          — show a specific thread (fuzzy match)

Threads persist to disk. Ask "what were we saying about the website?" days later and get the actual flow.

💡 Proactive Memory

The bot passively notes things you mention — events, tasks, plans — and surfaces them at the right moment (greetings, reconnects). Notes expire after 7 days.

⚡ Shortcut Learning

After you use the same short phrase 3 times for the same purpose, the bot learns the pattern automatically. No !teach needed.

!shortcuts               — list learned shortcuts
!shortcuts remove <phrase>

🎭 Mood-Aware Responses

Detects mood from message patterns and adapts response style:

• Frustrated → short, direct, no filler
• Focused → technical, structured
• Excited → matches enthusiasm
• Relaxed → detailed, conversational
• Neutral → balanced

👍 Reaction Feedback (Discord)

React to bot messages with 👍/❤️/✅ (positive) or 👎/❌/😕 (negative). The bot tracks this and calibrates over time.

!feedback                — view stats
!feedback clear          — reset

📤 Conversation Export

!export today            — today's conversations as markdown
!export week             — last 7 days
!export project website  — conversations about a topic
!export all              — everything

CLI backup:

antaris export --full --output ~/backup/
antaris export --memories-only --output memories.jsonl
antaris export --identity-only --output identity/

👤 User Profiles

The bot tracks per-user profiles: display name, message count, style, last seen. Profile context is injected into the system prompt for personalized responses.

!profile                 — view your profile

---

Tool System

Full reference: docs/TOOLS.md

Antaris gives the LLM the ability to take actions, not just talk. Tools are injected as function definitions into LLM calls.

Built-in Tools

25 tools ship out of the box. Most are enabled by default — tools requiring external credentials (database, image_gen, Google Workspace) are opt-in.

Core

Tool	What It Does
file_ops	Read, write, edit, list files in workspace
shell	Execute shell commands with timeout and scoping
web_search	Search via Brave Search API
web_fetch	Fetch and extract content from URLs
http	General-purpose HTTP requests (GET/POST/PUT/PATCH/DELETE/HEAD)
code_sandbox	Isolated Python/JS execution (subprocess, no workspace access)
git	Structured git ops: status, diff, log, commit, push, pull, branch, stash

Memory & Tasks

Tool	What It Does
memory_management	Search, inspect, forget, and get stats on the agent's own memories
tasks	Local task board: add/list/update/done/delete/archive/search — persists to JSON
cron	Create, list, delete, enable/disable scheduled jobs from conversation

System (macOS)

Tool	What It Does
clipboard	Read and write the system clipboard (pbcopy/pbpaste)
notification	macOS Notification Center alerts and spoken TTS alerts

Media & AI

Tool	What It Does
image	Image understanding and screenshot analysis
video	Video analysis: inspect, transcribe, sample frames, summarize, Q&A
powerpoint	Read, summarize, extract, rewrite PowerPoint decks
tts	Text-to-speech synthesis
image_gen	Generate images via Google Imagen 3 (Vertex AI) — needs project_id

Agent Infrastructure

Tool	What It Does
spawn_subagent	Spawn autonomous subagents
discord_file	Send files and attachments to Discord channels
discord_proactive	Send proactive messages to any configured channel
model_control	Switch models mid-conversation
session_status	Bot status and diagnostics
skills	Access OpenClaw-style skill files

Integrations (opt-in)

Tool	What It Does
database	Query Postgres/Supabase directly via asyncpg — needs postgres_url
browser	Headless Chrome automation via Puppeteer
peekaboo	macOS UI automation

Google Workspace

Full docs: docs/GOOGLE_WORKSPACE.md

First-class integration using your machine's authorized gog CLI — no separate auth stack needed.

{
  "tools": {
    "google_workspace": {
      "enabled": true,
      "account": "[e-mail]"
    }
  }
}

Tool	Capabilities
Gmail	Search, read, draft, send (draft-first by default)
Calendar	List events, create events (confirmation-gated)
Drive	Search files, read content
Docs	Create documents
Sheets	Read ranges, append rows

Chat shortcuts:

!gmail search from:jason newer_than:7d
!gmail draft to=[e-mail] | subject=Hi | body=Draft content
!calendar list from=2026-03-19T09:00 | to=2026-03-19T18:00
!drive search quarterly planning

🖼️ Image & Screenshot UX

Visual input is a first-class workflow:

• Accept image attachments naturally in Discord
• Distinguish general image understanding from screenshot/UI analysis
• Screenshot-aware prompting: identifies the app, errors, UI state, next steps
• OCR of visible text
• Works alongside PDF/doc attachments

🎬 Video Understanding

Local-first video analysis workflow:

{"action": "inspect", "path": "demo.mp4"}
{"action": "transcribe", "path": "demo.mp4", "whisper_model": "base"}
{"action": "sample_frames", "path": "demo.mp4", "max_frames": 6}
{"action": "summarize", "path": "demo.mp4"}
{"action": "qa", "path": "demo.mp4", "question": "What happens at the end?"}

Requires: ffmpeg, ffprobe, whisper. Falls back to transcript-only if vision is unavailable.

📊 PowerPoint

Full deck workflow: read, structure map, extract slides, summarize, rewrite speaker notes, export outlines, find-and-replace text.

Requires: pip install "antaris-agent[powerpoint]"

MCP Client

Connect to any Model Context Protocol server:

{
  "tools": {
    "mcp": {
      "servers": {
        "filesystem": {
          "transport": "stdio",
          "command": ["npx", "@modelcontextprotocol/server-filesystem", "/path"]
        },
        "web": {
          "transport": "sse",
          "url": "http://localhost:8080/sse"
        }
      }
    }
  }
}

Supports stdio and SSE transports. Auto-discovers tools from the server.

JavaScript Tool Bridge

Wraps non-MCP JavaScript tools (e.g., OpenClaw extensions) via a Node.js subprocess. Auto-detects bridgeable extensions from package.json.

Tool Security

All tool calls respect the current security level:

• Level 1+: File ops scoped to workspace
• Level 3+: Destructive tools logged to audit log
• Level 4: Every tool call requires explicit y/N approval

antaris tools list       # list registered tools
antaris tools status     # show tool system status

---

Platform Features

Running Antaris across devices, channels, and automated workflows.

🤖 Multi-Channel Support

Run across platforms simultaneously from one config:

Channel	Capabilities
Discord	Full support: reactions, history, DMs, bridge mode
Telegram	Bot API integration
Slack	Socket Mode (bot + app tokens)
Terminal	Direct conversation, no external service
iMessage	Coming Very Soon

Each channel has surface-specific formatting. Messages route through the same pipeline.

🧭 Multi-Provider Routing

Route messages to the best model based on complexity:

Tier	Use Case	Example
Trivial/Simple	Quick answers	Ollama (local, free)
Moderate	Conversation	Claude Sonnet, GPT-4o
Complex	Multi-step reasoning	Claude Sonnet + GPT-5.2
Expert	Deep analysis	Claude Opus, GPT-5.4

Override anytime:

!model opus              — switch to Claude Opus
!model gpt               — switch to GPT
!model qwen              — switch to local Qwen
!model auto              — return to automatic routing

Supported Providers

Provider	Models	Auth
Anthropic	Claude Opus, Sonnet, Haiku	OAuth or API key
OpenAI	GPT-5.4, GPT-5.2, GPT-4o, o1	API key
Google	Gemini 3.1 Pro, 2.5 Flash, 2.0 Flash	API key
Ollama	Any local model (Qwen, Llama, Mistral)	None (local)

All four can run simultaneously. The router selects per message.

🔀 Multi-Session Support

Each (user_id, channel_id) pair gets an independent session: separate history, compaction, and conversation buffer. Memory is shared across sessions — a fact learned in one channel is recallable in another.

!session                 — current session info
!sessions                — list active sessions

⏰ Cron Scheduler

Persistent, disk-backed scheduled tasks:

!cron list               — list jobs
!cron remove <id>        — remove a job
!cron run <id>           — force-run now

Supports every (recurring) and at (one-shot) schedules. Jobs survive restarts.

🤖 Subagents

Spawn autonomous sub-tasks:

!spawn ...               — spawn a subagent
!agents                  — list active subagents
!agent ...               — manage a subagent

Configurable max concurrency via bot.maxSubagents.

💰 Cost Tracking

Per-provider, per-model API cost tracking:

!cost                    — show accumulated costs

🖥️ Daemon & IPC

When running as a daemon (antaris start), CLI commands talk to the process over a Unix socket in the active Antaris config directory (by default ~/.antaris/antarisd.sock).

antaris status           # live status from daemon
antaris sessions         # list sessions
antaris sessions kill <id>
antaris security status
antaris security set <n>

🩺 Self-Repair

antaris repair           # auto-fix common issues
antaris doctor           # diagnostic scan (read-only)

Checks: config integrity, stale PID/socket files, memory store, missing directories, importable dependencies.

❤️ Health Endpoint

A lightweight HTTP health server runs alongside the bot on 127.0.0.1:8484 (stdlib only, no dependencies).

curl http://127.0.0.1:8484/health   # full status JSON
curl http://127.0.0.1:8484/ready    # 200 = accepting messages, 503 = starting up

/health response:

{
  "status": "ok",
  "uptime_seconds": 3600,
  "version": "2.5.6",
  "memory_count": 1247,
  "channels": ["Discord"],
  "model": "claude-sonnet-4-6"
}

Configure in config.json:

{ "health": { "enabled": true, "port": 8484 } }

---

Security

Deep dive: docs/SECURITY.md

Five Security Levels

Not just disclaimers — enforced at the OS level via sys.addaudithook().

Level	Name	Key Properties
0	Open	No restrictions. Developer mode.
1	Standard	File ops scoped to workspace + home. Subprocesses logged.
2	Sandboxed (default)	Filesystem restricted. Subprocesses blocked.
3	Secured	Network allowlisted. Tool calls logged. Destructive ops need approval.
4	Encrypted	All tools need y/N approval. OS-level access control + audit hook enforcement. Full data-at-rest encryption planned. Mandatory audit.

antaris start --security 2
antaris security status
antaris security set 3   # can always go UP at runtime
                         # going DOWN requires restart (by design)

Guard Modes

Separate from security levels — controls how violations are handled:

Mode	Behavior
monitor	Observe and log
warn	Alert on violations
block	Prevent violations

Config Protection

Config files are saved atomically (write-to-temp, rename) and auto-backed up before every save. Corruption auto-recovers from .config.json.bak.

---

Extensions & Integrations

Deep dive: docs/EXTENSIONS.md

Auth Monitor

Tracks API key health, rate limits, expiry. Auto-rotates between auth profiles when rate-limited.

{
  "extensions": {
    "auth-monitor": {
      "enabled": true,
      "check_interval": 300,
      "primary_provider": "anthropic"
    }
  }
}

Model Control

Model switching with thinking/reasoning levels:

Level
off
low
medium
high
max

Desktop Control

Browser automation, desktop control (mouse/keyboard), screenshot capture, terminal management, and Peekaboo integration (macOS UI automation).

{
  "extensions": {
    "desktop-control": {"enabled": true}
  }
}

Webhooks

Outbound HTTP notifications for bot events:

{
  "webhooks": {
    "endpoints": [{
      "url": "https://example.com/webhook",
      "secret": "your-secret",
      "events": ["message.responded", "pipeline.error", "auth.rate_limited"],
      "maxRetries": 3,
      "timeoutSeconds": 10
    }]
  }
}

Custom Skills

Drop skill directories in the active Antaris config directory under skills/ (by default ~/.antaris/skills/) with a SKILL.md manifest and optional Python tool implementations:

~/.antaris/skills/
    weather/
        SKILL.md
        tool.py
        scripts/

Migration Wizard

Full guide: docs/MIGRATION.md

Coming from another platform? One command:

antaris migrate --from openclaw --path ~/.openclaw
antaris migrate --from mem0
antaris migrate --from langchain
antaris migrate --from lancedb
antaris migrate --from custom --path ~/dir

The wizard auto-detects your existing setup, copies identity files, translates config, and imports memories. Read-only on the source — you can run both side by side.

Dry run: antaris migrate --from openclaw --dry-run

OpenClaw migration details

OpenClaw	Antaris
openclaw.json model/auth	config.json provider block
channels.discord.token	channels.discord.token
SOUL.md, AGENTS.md, etc.	Copied to ~/.antaris/
Memory shards	Native BM25 copy (no conversion)
SQLite memory	Extracted and re-ingested
Antaris needs its own Discord bot token — create one at discord.com/developers.

---

All Commands

Chat Commands

Command	Description
Status
!help	Show available commands
!ping	Check if bot is alive
!status	Bot status: memory, providers, model, guard
!cost	API cost tracking
!session	Current session info
!sessions	List active sessions
!security	Current security level
Model
!model <name>	Switch model (opus/sonnet/haiku/gpt/gemini/qwen/auto)
Memory
!memory [clear]	View or clear conversation history
!gather [hours]	Smart LLM briefing (3/6/12/18/24/48)
!recap [args]	Recap recent conversation
!teach <text>	Teach a fact or preference
!teach list	List teachings
!teach remove <n>	Remove a teaching
!teach clear	Clear all teachings
!focus <topic> [duration]	Enter focus mode
!unfocus	Exit focus mode
!threads	List conversation threads
!thread <topic>	Show a thread (fuzzy match)
!shortcuts	List learned shortcuts
!shortcuts remove <phrase>	Remove a shortcut
Export
!export today/week/all	Export conversations
!export project <name>	Export by topic
Feedback
!feedback	Reaction feedback stats
!feedback clear	Clear feedback
Profile
!profile	View your user profile
Scheduler
!cron list	List scheduled jobs
!cron remove <id>	Remove a job
!cron run <id>	Force-run a job
Agents
!spawn ...	Spawn a subagent
!agents	List active subagents
!agent ...	Manage a subagent
Google Workspace
!gmail <action>	Gmail operations
!calendar <action>	Calendar operations
!drive <action>	Drive operations

Unknown ! commands fall through to the LLM instead of hard-failing.

CLI Commands

Command	Description
Lifecycle
antaris init	Interactive setup wizard
antaris init --headless	Automated setup
antaris setup	Open the browser-based wizard hub
antaris start	Launch bot
antaris start --terminal	Terminal-only mode
antaris stop	Stop bot
antaris restart	Restart bot
antaris chat	Direct terminal conversation
Diagnostics
antaris status	Bot status
antaris pulse	Health check
antaris doctor	Diagnostic scan
antaris repair	Auto-fix issues
antaris logs [--tail N] [--follow]	View logs
Security
antaris security status	Security configuration
antaris security set <level>	Change security level (0–4)
antaris guard status	Guard status
Sessions
antaris sessions	List active sessions
antaris sessions kill <id>	Kill a session
Persona
antaris persona show	View SOUL.md
antaris persona edit	Edit persona
antaris persona reset	Reset + awakening
Memory
antaris memory stats	Memory statistics
antaris memory search <query>	Search memories
antaris memory export	Export all memories
Config
antaris config show	View configuration
antaris config set model <model>	Change default model
antaris config open-channel list	List open channels
Tools
antaris tools list	List registered tools
antaris tools status	Tool system status
Migration
antaris migrate --from <source>	Import from another platform
Export
antaris export --full	Full backup
antaris export --memories-only	Memories as JSONL
antaris export --identity-only	Identity files only
Updates
antaris update	Check and apply updates
antaris update --check	Check only

---

Configuration

Config lives in the active Antaris config directory as config.json. By default this revision uses ~/.antaris/config.json unless you override it with --config-dir or ANTARIS_CONFIG_DIR. Created by antaris init, antaris setup, or any of the re-entry setup wizards.

Full config reference

{
  "bot": {
    "name": "MyBot",
    "ownerUserId": "YOUR_DISCORD_ID",
    "compactionThreshold": 80,
    "preCompactionRatio": 0.75,
    "startupRestoreDays": 2,
    "maxSubagents": 3
  },
  "provider": {
    "name": "anthropic",
    "model": "claude-sonnet-4-6",
    "apiKey": "sk-ant-..."
  },
  "memory": {
    "store": "~/.antaris/memory",
    "searchLimit": 5,
    "minRelevance": 0.1,
    "perTurnRecall": true
  },
  "channels": {
    "discord": {
      "enabled": true,
      "token": "your-bot-token",
      "openChannels": ["channel-id"]
    },
    "telegram": { "enabled": false, "token": "" },
    "slack": { "enabled": false, "botToken": "", "appToken": "" }
  },
  "providers": {
    "openai": { "apiKey": "sk-..." },
    "google": { "apiKey": "AIza..." }
  },
  "security": { "mode": "sandboxed" },
  "guard": { "mode": "monitor" },
  "tools": {},
  "extensions": {},
  "webhooks": {},
  "rate_limit": {},
  "token_rate_limit": {},
  "cost_tracking": { "saveInterval": 300 },
  "updates": {}
}

Key sections:

• bot — name, owner, compaction, heartbeat, subagents, session persistence
• provider / providers — LLM provider keys and models
• channels — Discord, Telegram, Slack adapter configs
• memory — store path, search limits, relevance thresholds
• guard — guard mode (monitor/warn/block)
• security — security level (0–4)
• context — which .md files inject and when
• tools — native tools + MCP servers + Google Workspace
• extensions — auth monitor, model control, desktop control
• webhooks — outbound HTTP event notifications
• rate_limit / token_rate_limit — rate limiting
• cost_tracking — API cost tracking

Data Directories

Path	Contents
~/.antaris/config.json	Configuration
~/.antaris/memory/	Per-user BM25 memory stores
~/.antaris/profiles/	User profiles
~/.antaris/teachings/	Taught facts
~/.antaris/threads/	Conversation threads
~/.antaris/shortcuts/	Learned shortcuts
~/.antaris/proactive/	Proactive notes
~/.antaris/feedback/	Reaction feedback
~/.antaris/exports/	Exported conversations
~/.antaris/logs/	Structured logs
~/.antaris/cron/	Cron job state
~/.antaris/skills/	Custom skills
~/.antaris/SOUL.md	Persona
~/.antaris/AGENTS.md	Behavioral rules
~/.antaris/MEMORY.md	Long-term memory
~/.antaris/context.json	File injection control

---

Architecture

Deep dive: docs/ARCHITECTURE.md

Antaris Daemon (antaris start)
├── DaemonIPC (Unix socket)
├── SessionManager (per user+channel)
├── CronScheduler (persistent disk-based)
├── Security (5 levels, runtime-switchable up)
├── ToolRegistry (native + MCP + JS bridge)
├── ExtensionManager (auth, model control, desktop, webhooks, skills)
│
├── Channel Adapters
│     ├── Discord (+ bridge mode)
│     ├── Telegram
│     ├── Slack
│     └── Terminal
│
└── Per-Session Pipeline (10 stages):
      Message In
          ↓
      [0] Rate limit check
      [1] Input guard (injection detection, content filter)
      [2] User identification + profile
      [3] Memory recall (BM25 + startup recall)
      [4] System prompt assembly:
          persona + profile + teachings + tools
          + focus + proactive + shortcuts + feedback + mood
      [5] Context assembly (history + message)
      [6] LLM call (retry + routing + tool use)
      [7] Output guard
      [8] Memory ingest + thread filing + shortcut observation
      [9] Surface formatting (channel-specific)
          ↓
      Message Out

Non-critical stages fail gracefully. Critical stages (guard, LLM) return friendly errors.

---

Project Layout

antaris_agent/
  channels/      # Terminal + chat platform adapters
  core/          # Bot runtime, commands, memory, cron, sessions, etc.
  daemon/        # IPC + repair
  extensions/    # Auth monitor, model control, desktop, webhooks, skills
  llm/           # Provider clients and dispatcher
  migration/     # Importers from other frameworks
  persona/       # Awakening, cadence, user tracking
  security/      # Levels, audit, encrypted store, tool middleware
  setup/         # Setup server + wizard
  suite/         # Bundled Antaris suite packages
  tools/         # Native tool registry + MCP + JS bridge
parsica_memory/  # Bundled parsica-memory package
tests/           # 60 test files, 1,880+ tests

---

Bundled Dependencies

Ships with internal copies — no external installs needed:

Package	Version	Purpose
parsica-memory	2.9.9	11-layer BM25+ memory engine
antaris-guard	5.3.0	Prompt injection + content filtering
antaris-router	5.3.0	Adaptive LLM routing
antaris-pipeline	5.3.0	Message orchestration
antaris-context	5.3.0	Cross-session context management

---

Testing

python3 -m pytest

Test/docs counts change over time. Run python3 -m pytest in the checked-out revision for the current total.

---

Changelog

Full version history

v2.5.7 (current)

• Subagent parent_user_id fix — _active_user_id now set from message.author.id per inbound message; subagents always have correct parent context
• Subagent origin_channel fix — SpawnSubagentTool.set_active_channel() called per inbound message; replies always go to the right channel
• 25 built-in tools — memory_management, cron, clipboard, notification, git, http, code_sandbox, tasks, database, image_gen all added and registered by default
• Output cleaner — strips AI slop (filler openers, hedging preambles, performative closers) from all LLM responses; preserves code blocks
• Bridge structured logging — rotating file handler at ~/.openclaw/logs/bridge.log (5MB × 3 backups)
• Mood guidance hardened — excited mood no longer tells the model to "match their enthusiasm"; now explicitly blocks filler affirmations
• System prompt reinforcement — "skip filler" rule injected at end of system prompt where LLMs weight it most heavily
• Command registry refactor — commands.py if/elif chain replaced with dict[str, Callable] registry; 33 commands, extensible, testable
• Error leak audit — 11 raw exception paths fixed; tracebacks now go to logs, not Discord
• Health endpoint — GET /health and GET /ready on 127.0.0.1:8484 (stdlib only, configurable)

v2.5.5

• LLM timeout — Anthropic timeout set to 240s for long-running tool loops

v2.5.4

• PID lockfile fix — antaris start --daemon now writes PID only in the grandchild process after double-fork, preventing zombie process storms from rapid restarts

v2.5.3

• Default security mode → open — fresh installs start at level 0, no restrictions
• All tools enabled by default — shell, file ops, web fetch, web search, image, video, TTS, subagents, session status, PPTX, skills, model control, media, Discord proactive
• session_awareness bool→string fix — Parsica no longer throws warning on startup
• Zombie process guard — antaris start --daemon prevents duplicate instances via PID file; only launchd manages restarts
• launchd daemon support — antaris install-service / antaris uninstall-service now work on macOS
• antaris fleet — lists all named instances with status
• antaris init --name — named instance support for multi-agent deployments

v2.5.2

• Browser setup wizard (antaris setup) — full 10-step guided setup at localhost:7474. No more CLI prompts. Migration from existing configs, multi-provider support, model fallback chain builder, channel setup, Google Workspace, discovery page, review screen.
• Ordered fallback chain — model selection now shows #1 Primary, #2 Fallback, #3 Fallback badges. Click to build, click again to remove.
• Multi-provider persistence — all 10 providers (Anthropic, OpenAI, Google, Qwen, Ollama, DeepSeek, Mistral, Groq, Together, Kimi) persist across save/load/re-entry.
• antaris uninstall — clean removal from current Python environment, optionally wipes ~/.antaris
• antaris reinstall — force-reinstall latest from PyPI in one command
• antaris init — non-interactive scaffolding (no more prompts, just creates ~/.antaris/ skeleton)
• Startup security prompt removed — defaults to standard mode, configurable via wizard or --security flag
• --no-browser / --headless flag for headless Linux deployments (SSH tunnel friendly)
• Windows daemon support — antaris start --daemon now works on Windows via detached subprocess
• Config fields fixed — memory_storage_backend, memory_session_awareness, memory_tiered_storage added to Config (resolved startup crash on fresh installs)
• Migration fixes — skill migration uses correct target directory, nested config structure parsed correctly
• Dark theme wizard UI — charcoal background, gradient red buttons, accent-bordered cards
• 2,360 tests passing

v2.0.9

• !agent mode — full autonomous agent pipeline with tool use, thinking, and multi-turn reasoning
• !sync memory — peer memory sync command for Parsica PeerSync
• Bundled parsica-memory v3.3.3 (peer sync, recency recall, tz-aware timestamps)
• Security prompt on boot — interactive security mode picker before every launch
• --daemon / -d flag — proper daemonization with double-fork, log redirect, PID management
• Cascade search, archive enrichment, proactive recall from Parsica 3.1.6-3.1.8

v2.0.6

• OpenClaw parity release — major config and runtime alignment
• max_tokens output cap: 4096 → per-model defaults (Opus 4.6 128K, Sonnet 4.6 64K, GPT 5.4 128K, Haiku 4.5 64K, Haiku 3.5 8K, Gemini 65K). Configurable via llm.maxTokens.
• temperature: removed hardcoded 0.7 default. Models now use their own defaults. Configurable via llm.temperature.
• History cap: removed hardcoded 20-message limit. History grows until token-based compaction manages size.
• context_max_tokens default: 100K → 1M. Per-model config overrides this.
• Compaction: switched from message-count trigger to token-percentage trigger. Added context.keepRecentTokens (default 100K).
• Session restore: now uses token budget instead of message count for history truncation.
• HTTP timeouts: Google/OpenAI providers raised from 60s → 120s for long thinking turns.
• Tool iteration cap: 10 → 100 with cost warnings at iterations 25 and 50.
• Opus 4.6 pricing corrected ($5/$25, was $15/$75).
• Fix README version mismatch (was stuck at 2.0.4).
• Fix pyproject.toml parsica-memory version comment (3.1.0 → 3.1.5).

v2.0.5

• Bump for PyPI publish (parsica-memory v3.1.5)

v2.0.4

• Sync suite components to v5.3.0 (guard, router, context, pipeline)

v2.0.3

• Sync parsica-memory to v3.1.0 (Quality Levers + Transparency)

v2.0.2

• ⚠️ Breaking: Channel SDKs (discord.py, python-telegram-bot, slack-bolt) moved from core deps to optional extras. Existing users: pip install antaris-agent[discord], pip install antaris-agent[telegram], or pip install antaris-agent[all] to restore previous behavior.
• Security: audit hook refactored from string startswith() to proper Path.resolve() + relative_to() containment — closes /usr/bin exploit via broad Python root allowlisting
• Security: encrypted mode now fail-closed — raises RuntimeError if key init fails (was: silent degradation to unencrypted)
• Security: validate_key() gate on all encrypt/decrypt/save/load functions — prevents wrong-size key usage
• Security: encrypted store now persists only the 32-byte derived key (was: salt+key blob mismatch)
• Security: honest encryption_status property on BotMemory — data_at_rest_encrypted: False until real encryption ships
• Security: audit hook path coercion is fail-closed (deny if path can't be resolved)
• Reliability: Google provider normalizes all httpx transport errors to RuntimeError
• Reliability: MCP client retry converted from recursion to bounded loop
• Reliability: shell tool timeout kill path does bounded wait, defensive timeout validation
• Reliability: config wizard recursion replaced with loop, EOF/KeyboardInterrupt handled
• Tests: portable cwd in wizard tests (no more hardcoded paths)
• Tests: test_release_integrity.py — version sync, encrypted mode gate, CLI smoke, audit hook checks
• Config: handle provider.model as either string or dict with primary field (fixes Gonzo-style configs)
• Discord: rewrite plain-text @username outputs into real Discord mention tokens
• Discord: improved conversation pacing — proportional pre-send delay based on response length, more natural multi-chunk timing
• Pipeline: suppress user-facing "No tools were executed" fallback annotation (log only, no longer leaks to chat)
• UserTracker: fact quality filter — stopword blocklist prevents garbage facts like "Goes by: the/not/interested"
• UserTracker: removed overly broad single-word "i am X" → "Goes by: X" pattern

v1.9.9

• Bundle Parsica Memory 2.9.9 (upgraded from 2.7.0)

v1.9.8

• Runtime integrity hardening: awakening wiring, BotMemory path traversal, export_memories zero-export bug, security-mode normalization
• Audit-hook wave 2: fdopen / integer FD handling, stdlib MIME + parsica_memory allowlisting, false-positive reduction
• Optional imports (Discord, Slack, Telegram, discord_proactive) are truly import-soft — no crash on minimal installs
• Relay-intent detector (relay_intent.py): Mode A (acknowledge) / Mode B (compose) wired into pipeline Stage 4e; 44 dedicated tests
• Single version source (antaris_agent/_version.py), pyproject.toml reads version dynamically

v1.9.7

• Release discipline: single version source (_version.py), optional deps are truly import-soft
• Channel adapters (Discord, Telegram, Slack) no longer crash on minimal installs
• Packaging truthfulness: pyproject.toml version is dynamic from code
• Test portability improvements (optional-import and version-surface tests)

v1.9.6

• Google Workspace tools (Gmail, Calendar, Drive, Docs, Sheets)
• PowerPoint tool (read, summarize, extract, rewrite, export)
• Image/screenshot UX improvements
• Video understanding pipeline
• Extensions system (auth monitor, model control, desktop, webhooks)
• Custom skills system
• Canvas tool
• TTS tool
• Desktop control extension

v1.8.0

• Subagent orchestration
• Cost tracking
• Web setup wizard
• Discord bridge adapter
• Session persistence
• Token rate limiting
• Heartbeat system
• !recap command

v1.3.0

• Multi-session support
• Daemon IPC (Unix socket)
• 5-level security (expanded from 3)
• Self-repair (antaris repair)
• Security lock persistence

v1.2.5

• MCP client (stdio + SSE)
• Native tool system (5 built-in tools)
• Tool registry with access control
• JS tool bridge
• Pipeline tool integration

v1.2.0

• Migration wizard (OpenClaw, mem0, LangChain, LanceDB, custom)
• Export system
• Compaction safety (3-layer defense)
• Conversation buffer

v1.1.0

• Smart reconnect briefings
• !teach command
• Focus mode
• Conversation threading
• Proactive memory
• Shortcut learning
• Mood-aware responses
• Reaction feedback
• Conversation export

v1.0.0

• Identity stack (SOUL.md, AGENTS.md, MEMORY.md, TOOLS.md)
• All core chat commands
• Cron scheduler
• Per-user profiles
• Multi-provider dispatcher (Anthropic, OpenAI, Google, Ollama)
• Intelligent routing

v0.7.0

• Production hardening
• Gemini provider

v0.6.0

• Security modes with approval gates, audit enforcement, and owner-only memory access
• Tool approval middleware

v0.5.0

• Multi-channel (Discord, Telegram, Slack, Terminal)
• Persona system
• BM25 memory
• Migration from OpenClaw

---

License

Apache-2.0