Metadata-Version: 2.4
Name: antaris-agent
Version: 2.0.5
Summary: Antaris — Personal AI assistant. Single-package install for the core agent. Optional extras enable channels and integrations.
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: encrypted
Requires-Dist: cryptography>=40.0.0; extra == "encrypted"
Provides-Extra: secure-store
Requires-Dist: keyring>=24.0.0; extra == "secure-store"
Provides-Extra: discord
Requires-Dist: discord.py>=2.3.0; extra == "discord"
Provides-Extra: telegram
Requires-Dist: python-telegram-bot>=21.0; extra == "telegram"
Provides-Extra: slack
Requires-Dist: slack-bolt>=1.18.0; extra == "slack"
Provides-Extra: google
Requires-Dist: google-auth>=2.0; extra == "google"
Requires-Dist: google-auth-oauthlib>=1.0; extra == "google"
Requires-Dist: google-api-python-client>=2.0; extra == "google"
Provides-Extra: powerpoint
Requires-Dist: python-pptx>=1.0.0; extra == "powerpoint"
Provides-Extra: all
Requires-Dist: discord.py>=2.3.0; extra == "all"
Requires-Dist: cryptography>=40.0.0; extra == "all"
Requires-Dist: keyring>=24.0.0; extra == "all"
Requires-Dist: python-telegram-bot>=21.0; extra == "all"
Requires-Dist: slack-bolt>=1.18.0; extra == "all"
Requires-Dist: google-auth>=2.0; extra == "all"
Requires-Dist: google-auth-oauthlib>=1.0; extra == "all"
Requires-Dist: google-api-python-client>=2.0; extra == "all"
Requires-Dist: python-pptx>=1.0.0; extra == "all"
Dynamic: license-file

# 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.

```bash
pip install antaris-agent
antaris init
antaris start
```

**v2.0.4** · Python 3.10+ · test/docs counts vary by revision · Apache 2.0

---

## Contents

- [What Is This?](#what-is-this)
- [Quick Start](#quick-start)
- [Install Extras](#install-extras)
- [Feature Overview](#feature-overview)
- [Core Features](#core-features)
  - [Memory That Persists](#-memory-that-persists)
  - [Persona System](#-persona-system)
  - [Compaction Safety](#️-compaction-safety)
  - [Smart Reconnect Briefings](#-smart-reconnect-briefings)
  - [Daily Memory Logs](#-daily-memory-logs)
- [Interaction Features](#interaction-features)
  - [Teach Your Bot](#-teach-your-bot)
  - [Focus Mode](#-focus-mode)
  - [Conversation Threading](#-conversation-threading)
  - [Proactive Memory](#-proactive-memory)
  - [Shortcut Learning](#-shortcut-learning)
  - [Mood-Aware Responses](#-mood-aware-responses)
  - [Reaction Feedback](#-reaction-feedback-discord)
  - [Conversation Export](#-conversation-export)
  - [User Profiles](#-user-profiles)
- [Tool System](#tool-system)
  - [Built-in Tools](#built-in-tools)
  - [Google Workspace](#google-workspace)
  - [Image & Screenshot UX](#️-image--screenshot-ux)
  - [Video Understanding](#-video-understanding)
  - [PowerPoint](#-powerpoint)
  - [MCP Client](#mcp-client)
  - [JavaScript Tool Bridge](#javascript-tool-bridge)
  - [Tool Security](#tool-security)
- [Platform Features](#platform-features)
  - [Multi-Channel Support](#-multi-channel-support)
  - [Multi-Provider Routing](#-multi-provider-routing)
  - [Multi-Session Support](#-multi-session-support)
  - [Cron Scheduler](#-cron-scheduler)
  - [Subagents](#-subagents)
  - [Cost Tracking](#-cost-tracking)
  - [Daemon & IPC](#️-daemon--ipc)
  - [Self-Repair](#-self-repair)
- [Security](#security)
  - [Five Security Levels](#five-security-levels)
  - [Guard Modes](#guard-modes)
  - [Config Protection](#config-protection)
- [Extensions & Integrations](#extensions--integrations)
  - [Auth Monitor](#auth-monitor)
  - [Model Control](#model-control)
  - [Desktop Control](#desktop-control)
  - [Webhooks](#webhooks)
  - [Custom Skills](#custom-skills)
  - [Migration Wizard](#migration-wizard)
- [All Commands](#all-commands)
- [Configuration](#configuration)
- [Architecture](#architecture)
- [Project Layout](#project-layout)
- [Bundled Dependencies](#bundled-dependencies)
- [Testing](#testing)
- [Changelog](#changelog)
- [License](#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

```bash
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](#install-extras) and the feature notes below.

### 2. Setup

```bash
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

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

### 4. Verify

```bash
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.

```bash
# 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**](#core-features) | Memory, persona, conversation, safety | Everyone |
| [**Interaction**](#interaction-features) | Teaching, focus mode, mood, feedback, threading | Daily users |
| [**Tools**](#tool-system) | Web search, files, browser, Google, video, slides | Power users |
| [**Platform**](#platform-features) | Multi-channel, sessions, cron, subagents | Multi-device / automation |
| [**Security**](#security) | Five levels, guard, audit, encryption | Production / shared use |
| [**Extension**](#extensions--integrations) | 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](https://github.com/Antaris-Analytics-LLC/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 `~/.antarisbot/` 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 |

```bash
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 daily log and 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` + daily logs + BM25 on first message after compaction

**Config:** `bot.compactionThreshold`, `bot.preCompactionRatio`, `bot.startupRestoreDays`

### 📋 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.

### 📝 Daily Memory Logs

Every 20 conversation turns, the bot writes a checkpoint to `memory/YYYY-MM-DD.md`. On shutdown, a session-end marker is written. Human-readable paper trail alongside the BM25 store.

---

## 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:**
```bash
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](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

| 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 |
| `browser` | Headless Chrome automation via Puppeteer |
| `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 |
| `canvas` | Visual HTML canvas for rendering |
| `peekaboo` | macOS UI automation |
| `session_status` | Bot status and diagnostics |
| `spawn_subagent` | Spawn autonomous subagents |

### Google Workspace

> **Full docs:** [docs/GOOGLE_WORKSPACE.md](docs/GOOGLE_WORKSPACE.md)

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

```json
{
  "tools": {
    "google_workspace": {
      "enabled": true,
      "account": "you@yourdomain.com"
    }
  }
}
```

| 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=you@domain.com | 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:
```json
{"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](https://modelcontextprotocol.io/) server:

```json
{
  "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

```bash
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 |

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 `~/.antarisbot/antarisd.sock`).

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

### 🩺 Self-Repair

```bash
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.

---

## Security

> **Deep dive:** [docs/SECURITY.md](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. |

```bash
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](docs/EXTENSIONS.md)

### Auth Monitor

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

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

### Model Control

Runtime model switching with thinking/reasoning levels:

| Level | Budget |
|-------|--------|
| `off` | No extended thinking |
| `low` | 1,024 tokens |
| `medium` | 4,096 tokens |
| `high` | 16,384 tokens |
| `max` | 32,768 tokens |

### Desktop Control

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

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

### Webhooks

Outbound HTTP notifications for bot events:

```json
{
  "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 `~/.antarisbot/skills/`) with a `SKILL.md` manifest and optional Python tool implementations:

```
~/.antarisbot/skills/
    weather/
        SKILL.md
        tool.py
        scripts/
```

### Migration Wizard

> **Full guide:** [docs/MIGRATION.md](docs/MIGRATION.md)

Coming from another platform? One command:

```bash
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`

<details>
<summary><strong>OpenClaw migration details</strong></summary>

| OpenClaw | Antaris |
|----------|---------|
| `openclaw.json` model/auth | `config.json` provider block |
| `channels.discord.token` | `channels.discord.token` |
| `SOUL.md`, `AGENTS.md`, etc. | Copied to `~/.antarisbot/` |
| Memory shards | Native BM25 copy (no conversion) |
| SQLite memory | Extracted and re-ingested |
| Daily logs | Copied directly |

Antaris needs its own Discord bot token — create one at [discord.com/developers](https://discord.com/developers/applications).

</details>

---

## 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 `~/.antarisbot/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.

<details>
<summary><strong>Full config reference</strong></summary>

```json
{
  "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": "~/.antarisbot/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

</details>

### Data Directories

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

---

## Architecture

> **Deep dive:** [docs/ARCHITECTURE.md](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

```bash
python3 -m pytest
```

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

---

## Changelog

<details>
<summary><strong>Full version history</strong></summary>

### v2.0.4 (current)
- 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)
- Enhanced daily logs
- 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

</details>

---

## License

Apache-2.0
