Animaya v2

OverviewContext

Animaya currently deploys per-client OpenClaw (Node.js) containers on a VPS behind Traefik. Each client gets a Telegram bot, a workspace with flat .md files for memory, and bash scripts for management.

Problems Driving This Rebuild

• Updating clients requires restarting containers or sending CLI messages to each one
• No skill/tool marketplace — everything is baked into config
• No billing or usage tracking — all API calls use our keys with no limits
• Memory is flat unstructured .md files — no indexing, no search, no automatic learning
• No testing infrastructure at all
• Skills/tools can't be controlled per-client (no access tiers)

OverviewKey Decisions

• Rust core + Python tools — Rust for the agent loop, memory, triggers, responses. Python for tools executed as subprocesses via JSON protocol
• Container per client — maintains Docker isolation, ~50MB image per container
• Multi-provider LLM with billing — token balance system + BYOK (bring your own key) option
• Tree memory with librarian — hierarchical files, a cheap model periodically organizes and indexes
• Shared read-only volumes — update tools/skills/prompts once, all clients see changes instantly. No restart
• TDD from the start — unit, integration, behavioral, and E2E tests before features

OverviewComponent Model

Every component is defined as a Rust trait, making it pluggable. New variants can be added without changing the core.

Section 1Agent Loop

The central state machine. A trigger arrives, context is assembled, the model is called. The model either produces a final response or requests tool calls. Tool results feed back into the loop until the model responds with text or a safety limit is reached.

Safety Limits

• Max 10 tool-call turns per run (configurable)
• Model API failures: retry 3x with exponential backoff
• Tool failures: error reported back to model as tool result
• If turn limit reached: force final response via injected system message

Section 2Memory Tree

Memory is a file tree on disk. The model doesn't see the full tree — it gets a table of contents and can request specific files via tools.

Memory Tools

The Librarian

A background process inside each container that maintains memory quality. Uses a cheap fast model (GLM-4.7-FlashX at ~1/20th the cost of the primary model).

Section 3Tool Protocol

Tools are Python scripts that communicate with the Rust runtime over stdin/stdout JSON-RPC.

{
  "name": "web_search",
  "description": "Search the web using Brave Search API",
  "parameters": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "Search query" }
    },
    "required": ["query"]
  },
  "timeout_seconds": 30,
  "requires_secrets": ["BRAVE_API_KEY"],
  "tier": "standard"
}

{
  "method": "execute",
  "id": "call_abc123",
  "params": {
    "arguments": { "query": "weather in Moscow" },
    "secrets": { "BRAVE_API_KEY": "..." }
  }
}

{
  "id": "call_abc123",
  "result": { "status": "success", "output": "Results for: weather..." }
}

Section 4Skill System

Skills are markdown instruction files that tell the model when and how to use tools. Unlike tools (code), skills are pure prompt engineering.

Activation Modes

# Appointment Scheduling

## When to Activate
- Client asks to book/schedule an appointment
- Client asks about availability

## Steps
1. Read knowledge/services.md to check available services
2. Read knowledge/schedule.md to check working hours
3. Ask client which service they need
4. Ask for preferred date/time
5. Notify owner via owner_notify with requires_approval: true
6. Tell client: "I've sent your request to [owner]."

## Required Tools
- memory_read
- owner_notify

Per-Client Access Control

Each client has skills.json with overrides. Admins control which skills each client can access — this is the monetization lever: basic skills included, premium skills require a higher tier.

{
  "overrides": {
    "appointment_scheduling": { "activation": "auto" },
    "crm_integration": { "activation": "disabled" }
  }
}

Section 5Billing & Model Router

Each client has a credit balance. 1 credit = 1 token at base model price. Better models cost more credits.

BYOK (Bring Your Own Key)

Power users provide their own API key. When active: their key is used, no credits charged, usage still logged for analytics, key stored encrypted in .env.

When Balance Runs Out

1. Before each call, estimate cost. If insufficient → block
2. User sees: "I've reached my usage limit. Contact [owner] to add credits."
3. Owner gets notification: "Your assistant's balance is exhausted."
4. Low-balance warnings at 10% threshold

Section 6Owner Communication

"Texting the owner" is a first-class response channel — distinct from regular Telegram messages. It supports structured notifications and approval workflows.

Approval Flow

owner_notify is a built-in tool (Rust, not Python) because it needs direct Telegram API access. Pending approvals timeout after 12h with a configurable default action.

Section 11Parallel Task Execution

The agent handles multiple tasks concurrently. A user can send a long-running request, then immediately send another. Tasks are queued, executed in parallel, and their progress is visible in real time.

Telegram Status Messages

Status messages are edited in-place as the task progresses:

Section 12Web UI

A web dashboard for owners to monitor their assistant. Served from {slug}.animaya.me behind the existing Telegram auth.

Architecture

Browser ──WebSocket──> animaya-server (Rust)
                           │
                           ├── /ws/tasks     → live task updates
                           ├── /ws/thinking  → agent thinking stream
                           │
                           ├── /api/conversations
                           ├── /api/memory
                           ├── /api/skills
                           ├── /api/usage
                           └── /api/settings

// Context assembled
{ "event": "context_assembled",
  "data": { "skills_loaded": ["scheduling", "greeting"],
            "total_tokens": 8500 }}

// Model response with tool call
{ "event": "model_response",
  "data": { "tool_calls": [{"name": "web_search",
            "args": {"query": "..."}}] }}

// Tool result
{ "event": "tool_result",
  "data": { "tool": "web_search", "status": "success",
            "duration_ms": 1200 }}

The static SPA is built at Docker image build time (Svelte/Preact/vanilla JS). No Node.js runtime needed in the container. Auth reuses existing Telegram Login Widget — same domain, same cookie.

Section 7Shared Volume Strategy

Section 8Testing Strategy

#[test]
fn test_appointment_triggers_owner_notification() {
    let mock = MockModelRouter::with_responses(vec![
        response_with_tool_call("owner_notify", ...),
        response_text("I've notified the doctor!"),
    ]);
    let trigger = telegram_message("@maria", "Book me for Tue 3pm");
    let result = runtime.run(trigger);
    assert!(result.tool_calls[0].name == "owner_notify");
}

Section 9Project Structure

animaya-v2/
  crates/
    animaya-core/          # Traits, types, interfaces
    animaya-runtime/       # Agent loop + context assembly
    animaya-memory/        # Filesystem memory + TOC + librarian
    animaya-tools/         # Subprocess tool executor
    animaya-models/        # Model router + billing
    animaya-triggers/      # Telegram (teloxide), cron, webhook
    animaya-responses/     # Telegram, owner notifications, file
    animaya-server/        # Main binary

  tools/                   # Python tools (shared volume)
    web_search/ audio_transcribe/ image_analyze/ ...

  skills/                  # Markdown skills (shared volume)
    appointment_scheduling/ greeting/ reminder_setting/ ...

  shared/                  # System prompts, guardrails, pricing

  docker/
    Dockerfile             # Multi-stage: Rust build → Python slim
    docker-compose.yml     # Traefik + auth + onboarding
    docker-compose.client.yml

  scripts/ tests/ auth/ onboarding/

Section 10Client Configuration

{
  "slug": "drsmith",
  "agent": {
    "model": "zai/glm-4.7",
    "max_turns": 10,
    "temperature": 0.7,
    "language": "ru"
  },
  "owner": {
    "telegram_username": "@drivanov",
    "telegram_chat_id": 123456789
  },
  "billing": {
    "mode": "prepaid",
    "balance_credits": 500000
  },
  "heartbeat": { "interval_minutes": 30 },
  "librarian": {
    "enabled": true,
    "run_every_n_turns": 5,
    "model": "zai/glm-4.7-flashx"
  }
}

RolloutMigration from v1

Migration Phases

1. Build v2 with feature parity to current OpenClaw setup
2. Run v2 in parallel for one test client, compare behavior
3. Migrate existing clients (automated script)
4. Remove OpenClaw dependency

RolloutImplementation Timeline

Total: ~14.5 weeks for one developer. Phases 2-4 can run in parallel with multiple devs.

RolloutEdge Cases & Risks