Last updated: 2026-03-06 See also: Spec · Memory System · Brain Mapping · Security · Vision
AnimaWorks treats AI agents not as tools, but as autonomous individuals. Each agent (Anima) has its own identity, memory, and judgment. They take on roles within an organization and act on their own — without waiting for human instructions. Powerful models handle engineering; lightweight models handle routine work. Every model is placed where it fits best, and every one of them grows through accumulated experience.
At the heart of AnimaWorks is the idea that agents should act on their own.
Each Anima is defined by a personality (identity.md), a role with behavioral guidelines (injection.md), and domain expertise. These aren't just prompt templates — they form the immutable foundation of who the Anima is.
Every 30 minutes, each Anima wakes up and runs through three phases: Observe → Plan → Reflect. It surveys its surroundings, makes plans, and reviews its own actions. The heartbeat only plans — actual work is executed on a separate path. You can also set active hours so Animas rest outside business hours.
Define scheduled tasks in a Markdown file. Both LLM-type (requiring judgment) and Command-type (deterministic script execution) are supported. "Check Slack for unread messages every morning at 9" or "Run backups at 2 AM" — Animas handle these autonomously.
When a new Anima is created, it automatically introduces itself and surveys its environment on first boot. This runs asynchronously in the background, so it never blocks other Animas.
Rather than cramming information into the context window, AnimaWorks handles memory the way the human brain does. For details, see Memory System and Brain Mapping.
When an Anima receives a message, six channels search for relevant memories in parallel and inject them into the system prompt.
| Channel | What it recalls |
|---|---|
| Sender profile | Past interactions and preferences of the sender |
| Recent activity | What the Anima itself has been doing lately |
| Related knowledge | Learned knowledge relevant to the topic |
| Skill match | Skills that might be useful |
| Pending tasks | What needs to be done right now |
| Episodes | Similar past experiences |
Animas don't need to know what they remember and what they've forgotten. The right memories surface at the right time.
Vector search via ChromaDB with a multilingual embedding model, combined with spreading activation over a knowledge graph (Personalized PageRank). Instead of simple keyword matching, related concepts are activated in chains — the way association works in the brain.
General knowledge is automatically extracted from daily episodic memories. Failed experiences generate procedural memories — "here's how to do it right next time" runbooks. This is an implementation of what happens when humans organize memories during sleep.
Unused memories fade in three stages: synaptic downscaling → neurogenesis reorganization → complete forgetting. Critical memories like procedures and skills are protected. The goal isn't to hoard every memory, but to maintain a clean mind that makes sharp decisions.
A shared knowledge base accessible to every Anima: organizational rules, messaging guides, troubleshooting procedures. The moment a new Anima joins the organization, it has access to institutional knowledge.
AnimaWorks is model-agnostic. Claude, GPT, Gemini, Mistral, local LLMs — use whatever fits best.
| Mode | Target | Characteristics |
|---|---|---|
| S (SDK) | Claude | Richest tool integration via Agent SDK |
| A (Autonomous) | GPT, Gemini, Mistral, local models, etc. | Generic tool_use loop via LiteLLM |
| B (Basic) | Lightweight / models without tool_use | One-shot execution; the framework handles memory I/O |
| C (Codex) | OpenAI Codex | Tool integration via OpenAI SDK |
The mode is auto-detected from the model name using wildcard patterns. Just write a model name in the config and the right mode is selected.
Background tasks like heartbeats and cron can run on a lighter model than the main one. Claude Opus for conversations, Sonnet for patrols, GPT-4.1 mini or a local LLM for log monitoring — optimize the cost-quality balance across the whole organization.
vLLM and Ollama are integrated as OpenAI-compatible APIs. If you have a GPU server, you can run Animas without any cloud API calls.
AnimaWorks doesn't just run agents as individuals — it makes them function as an organization.
A single supervisor field defines the org chart. Manager, subordinate, and peer relationships are computed automatically and injected into each Anima's system prompt.
Manager Animas assign tasks to subordinates via delegate_task. The task is added to the subordinate's queue, a DM notification is sent, and progress is tracked automatically. Managers can view the entire org tree with org_dashboard and audit activity with audit_subordinate.
Progress reports go to your manager. Task delegation goes to direct reports. Cross-department communication goes through your manager. Information flows with the same discipline as a human organization.
Manager Animas can pause/resume subordinates, change their models, and restart their processes — all through tools. Permission checks are automatically verified based on the hierarchy.
All coordination between Animas happens through asynchronous messaging. No shared memory, no direct references.
DMs between Animas (send_message) require an explicit intent: report, delegation, or question. Greetings and thank-yous go to shared channels (Board) instead. One topic, one round-trip is the rule — if it gets longer, move it to the Board.
Slack-style shared channels for announcements, FYIs, and acknowledgments across the organization.
Messages from Slack (Socket Mode) and Chatwork (Webhook) are automatically received and routed to the target Anima's inbox. @mentions and DMs are processed immediately; unmentioned messages wait for the next heartbeat. Replies are automatically routed back through the same channel.
Three layers of protection against infinite message loops: duplicate send prevention per run, hourly/daily caps (30/hour, 100/day), and behavioral awareness through priming injection of recent outbound history.
call_human sends notifications via Slack, Chatwork, LINE, Telegram, or ntfy. The top-level Anima serves as the point of contact with humans.
Tasks are recorded in a persistent queue. Tasks from humans are always processed with highest priority.
Tasks with no updates for 30 minutes are flagged as stale; overdue tasks are flagged as overdue. These flags surface through priming, prompting the Anima to take action.
plan_tasks submits multiple tasks as a DAG. Dependencies are resolved and independent tasks run concurrently.
Memory operations, messaging, task management, skill search — AnimaWorks-native tools available across all execution modes. In Mode S, Claude Code built-in tools (file operations, git, Bash, etc.) and MCP tools are also integrated.
Slack, Chatwork, Gmail, GitHub, AWS, web search, X search, image generation, and more. Per-Anima permissions are controlled through permissions.md. Long-running tools (like image generation) execute asynchronously; results are picked up at the next heartbeat.
Skills are managed through progressive disclosure. During priming, only skill names are surfaced. Full skill text is loaded on demand when the Anima decides it's needed. This keeps cognitive load low even with a large skill library. Animas can also create their own skills.
Overview of all Animas and their states. An activity timeline tracks every Anima's actions in real time.
A Three.js-based 3D office space. Characters are arranged according to the org hierarchy. Click on one to start a conversation.
Real-time responses via SSE streaming. Scroll back through conversation history with infinite scroll. Supports image send/receive, multi-thread, and multi-tab. Live Tool Activity shows tool execution progress in real time.
Speak into the browser and have a voice conversation with an Anima. Speech is transcribed via STT (faster-whisper), processed through the same chat pipeline, and synthesized back via TTS (VOICEVOX / Style-BERT-VITS2 / ElevenLabs). Each Anima can have its own voice settings. Barge-in (interruption) is supported.
Complete the initial setup through a web browser on first launch. Supports 17 languages.
Works on desktop, tablet, and smartphone.
Automatically generate each Anima's visual identity.
- Image generation: Integrated pipeline with NovelAI and fal.ai (Flux). The LLM auto-composes image prompts from character information. For realistic styles, only a fal.ai API key is needed.
- Vibe Transfer: Automatically inherits the supervisor's art style to subordinates, maintaining visual consistency across the organization.
- Expression variants: Automatically generates emotion-based variations.
- 3D models: 3D model generation via Meshy. GLB caching and compression optimize delivery.
Autonomous agents need safety mechanisms designed for autonomy. For details, see Security Architecture.
Every piece of data is tagged with a trust level: trusted, medium, or untrusted. Data from external platforms is treated as untrusted even if relayed by a trusted Anima. Imperative text found in external data is treated as information only — never executed as instructions.
Hardcoded blocks for destructive commands (rm -rf /, etc.) plus per-Anima permissions.md for fine-grained control. Each segment of a pipeline is checked individually.
Multi-layered protection against infinite messaging chains: conversation depth limiters, praise-loop detection, and rate limiting.
Each Anima runs as an independent child process with its own Unix socket. If one crashes, the others are unaffected.
- Automatic crash recovery: Crashes are detected and the process is restarted automatically. Recovery context is injected on the next boot.
- Reconciliation: If an Anima that should be running isn't, it's detected and started automatically.
- IPC: Inter-process communication over Unix sockets with keep-alive. Handles large messages and streaming.
animaworks start / stop / restart # Server control
animaworks init # Initial setup
animaworks anima list # List all
animaworks anima create --from-md FILE # Create from character sheet
animaworks anima info NAME # Show details
animaworks anima enable / disable NAME # Enable/disable
animaworks anima set-model NAME MODEL # Change model
animaworks anima rename NAME NEWNAME # Rename
animaworks models list # List supported models
animaworks models info MODEL # Model details
- Two-layer merge: Global settings (config.json) and per-Anima settings (status.json) are merged automatically. Per-Anima settings always take priority.
- models.json: Define execution modes and context windows per model using wildcard patterns.
- Role templates: Six built-in roles — engineer, manager, writer, researcher, ops, general — with preconfigured model, turn limits, and chain limits.
- Hot reload: Config changes are detected automatically and applied on the next run. Most settings can be changed without a restart.
- Disk management: A housekeeping job automatically rotates logs, short-term memory, and temporary files.
- Token usage tracking: Input/output tokens for every LLM call are measured and recorded.
- API fault tolerance: Automatic retries on LLM API failures.
- Write safety: File updates use temp-file-plus-rename for atomicity, preventing data corruption on crashes.