anima-core 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ec0963d3bb57afc7a12414258c90d645dd200ca489bd7ab34e6ace19ea11927
-  data.tar.gz: 712d1904e5ddf7b0c244ddeffb2ed993f6265d097eb18000b139cdb08a9bfc4c
+  metadata.gz: 9fb5f4e6879e02892c861885896a154798a14e5eefa12ed0decaff968a085f5d
+  data.tar.gz: c28b8e1c2aed9cea3a3f9a6735f289961c1727562684b19960580b293bfd40cd
 SHA512:
-  metadata.gz: 3b70800258af5296bf243e7b0c020efd6f7736e3f1f58734352e022ca8ec7a15599ffce938fc1adc511bc37a7141472845dcead21b6512cdc09dfceae8b04b87
-  data.tar.gz: e70536705ac4d1cc468a951079799edd8677cae3c167251c60cccfbb51f79b0e2e7f896b5420f4972c8a59ee3d377ae0fd284d3603db441bd45313a1030f60ca
+  metadata.gz: 4cb148defa8d0b81ecb1559966f483137ebc10f24ee47c7ac4cc27d0e17332cf2232d45507e4abe7c67b4bdc364c7fd5f7ccd2ff70dac29fe43b2f21a277b1f4
+  data.tar.gz: 18227bfc5e3be5883f87c07f5215c10d97bb9565d3c41fb23e2799ce8624f83b9e1a15ad30c772c58119664d8d0adcfc6a68e5e456a17dc04e61f55a0e24e0c9

data/.reek.yml

@@ -13,43 +13,43 @@ detectors:
   NilCheck:
     exclude:
       - "Anima::Settings#get"
+      - "TUI::Settings#get"
   # Rescue blocks naturally reference the error object more than self.
-  # EnvironmentProbe assembles output from local data structures — not envy.
-  # Brain transcript builds from event collection — the method's entire purpose.
+  # Melete transcript builds from event collection — the method's entire purpose.
   # ConfigMigrator text processing methods naturally reference local line arrays.
   # ToolDecorator subclasses operate on the tool result — that's the pattern.
   # Tool rescue blocks naturally reference the error object.
   FeatureEnvy:
     exclude:
-      - "AnalyticalBrainJob#perform"
-      - "EnvironmentProbe"
-      - "AnalyticalBrain::Runner#build_messages"
+      - "Melete::Runner#build_messages"
       - "Anima::ConfigMigrator"
       - "WebGetToolDecorator"
       - "Tools::WebGet#validate_and_fetch"
-      # Remember tool renders events from other objects — formatting IS the job.
-      - "Tools::Remember"
+      # ViewMessages renders events from other objects — formatting IS the job.
+      - "Tools::ViewMessages"
       # Event subscribers extract payload fields — inherent to the pattern.
       - "Events::Subscribers::SubagentMessageRouter"
+      # Query-style predicate operates on the argument by design.
+      - "Session#subagent_trace_in_viewport?"
+      # Visibility restore operates on the child session — that's the job.
+      - "PendingMessage#restore_subagent_hud_visibility!"
       # Spawn tools orchestrate child session creation — references are the job.
       - "Tools::SpawnSubagent#spawn_child"
       - "Tools::SpawnSpecialist#spawn_child"
       - "Tools::SpawnSpecialist#execute"
       # Spawn helpers operate on child session — inherent to the mixin pattern.
-      - "Tools::SubagentPrompts#assign_nickname_via_brain"
+      - "Tools::SubagentPrompts#assign_nickname_via_melete"
       - "Tools::SubagentPrompts#inject_identity_context"
       # Registry dispatches to tool's threshold method — duck-typing delegation.
       - "Tools::Registry#truncation_threshold"
       # Goal tools operate on goal objects — inherent to the pattern.
-      - "AnalyticalBrain::Tools::UpdateGoal#execute"
+      - "Melete::Tools::UpdateGoal#execute"
       # Validation methods naturally reference the validated value more than self.
-      - "AnalyticalBrain::Tools::AssignNickname#validate"
+      - "Melete::Tools::AssignNickname#validate"
       # Tool execute methods naturally reference input hash and shell result hash.
       - "Tools::Bash#execute"
       - "Tools::Bash#execute_single"
       - "Tools::Bash#execute_batch"
-      # Delivery method orchestrates session, event, and agent_loop — inherent.
-      - "AgentRequestJob#deliver_persisted_event"
   # Private helpers don't need instance state to be valid.
   # ActiveJob#perform is always a utility function by design.
   # No-op tools (Think, EverythingIsReady) don't need instance state — by design.
@@ -59,8 +59,7 @@ detectors:
   UtilityFunction:
     public_methods_only: true
     exclude:
-      - "AnalyticalBrainJob#perform"
-      - "PassiveRecallJob#perform"
+      - "MeleteEnrichmentJob#perform"
       - "Tools::Think#execute"
       - "TUI::Formatting"
       - "WebGetToolDecorator#method_missing"
@@ -68,15 +67,15 @@ detectors:
       - "WebGetToolDecorator#text_html"
   # Session model is the core domain object — methods grow naturally.
   # Mcp CLI accumulates subcommand helpers across add/remove/list/secrets.
-  # EnvironmentProbe probes multiple orthogonal facets (OS, Git, project files).
-  # Each facet needs its own detection + formatting methods.
+  # ShellSession probes multiple orthogonal facets (CWD, Git, project files)
+  # and manages PTY lifecycle — methods grow with responsibilities.
   TooManyMethods:
     exclude:
       - "Session"
       - "Anima::CLI::Mcp"
-      - "EnvironmentProbe"
+      - "ShellSession"
       # Runner composes system prompt from modular sections — methods grow with responsibilities.
-      - "AnalyticalBrain::Runner"
+      - "Melete::Runner"
   # Decorators branch on tool type across 4 render modes — inherent to the pattern.
   # Installer methods each guard idempotency with config_path.exist? — by design.
   RepeatedConditional:
@@ -84,13 +83,13 @@ detectors:
       - "ToolCallDecorator"
       - "Anima::Installer"
       # Runner checks session type to compose responsibilities — the core dispatch.
-      - "AnalyticalBrain::Runner"
+      - "Melete::Runner"
   # EventDecorator holds shared rendering constants (icons, markers, dispatch maps).
-  # Event model holds domain type constants (TYPES, CONTEXT_TYPES, SPAWN_TOOLS, etc.).
+  # Message holds domain type constants (TYPES, LLM_TYPES, CONVERSATION_TYPES, etc.).
   TooManyConstants:
     exclude:
       - "EventDecorator"
-      - "Event"
+      - "Message"
   # encode_utf8 is descriptive — the digit triggers a false positive.
   UncommunicativeMethodName:
     exclude:
@@ -108,16 +107,14 @@ detectors:
     exclude:
       - "Tools::WebGet#validate_and_fetch"
       # Remember tool accesses event data for formatting — inherent to rendering.
-      - "Tools::Remember"
+      - "Tools::ViewMessages"
       # Nickname validation checks parent_session for existence then queries — two calls, one guard.
-      - "AnalyticalBrain::Tools::AssignNickname#sibling_nickname_taken?"
-      # Delivery method references session.id for lookup, BounceBack, and auth broadcast.
-      - "AgentRequestJob#deliver_persisted_event"
+      - "Melete::Tools::AssignNickname#sibling_nickname_taken?"
   # Method length is enforced by code review, not arbitrary line counts
   # build_sections passes context through to sub-methods — inherent to assembly.
   LongParameterList:
     exclude:
-      - "Tools::Remember#build_sections"
+      - "Tools::ViewMessages#build_sections"
   # Method length is enforced by code review, not arbitrary line counts
   TooManyStatements:
     enabled: false

data/README.md

@@ -8,13 +8,13 @@ Every AI agent today is a tool pretending to be a person. One brain doing everyt
 
 Anima is different. It's built on the premise that if you want an agent — a real one — you need to solve the problems nobody else is solving.
 
-**A brain modeled after biology, not chat.** The human brain isn't one process — it's specialized subsystems on a shared signal bus. Anima's [analytical brain](https://blog.promptmaster.pro/posts/llms-have-adhd/) runs as a separate subconscious process, managing context, skills, and goals so the main agent can stay in flow. Not two brains — a microservice architecture where each process does one job well. More subsystems are coming.
+**A brain modeled after biology, not chat.** The human brain isn't one process — it's specialized subsystems on a shared signal bus. Anima mirrors this with a triptych named after the three original Muses: **Aoide** performs (voice, reasoning, tool use), **[Melete](#preparation-as-a-second-brain-melete)** prepares (skills, workflows, goals, naming), **[Mneme](#semantic-memory-mneme)** remembers (summarization, compression, recall). Three processes on the same event bus, each doing one job well. More subsystems are coming.
 
-**Context that never degrades.** Other agents fill a static array until the model gets dumb. Anima assembles a fresh viewport over an event bus every iteration. No compaction. No lossy rewriting. Endless sessions. The [dumb zone](https://github.com/humanlayer/advanced-context-engineering-for-coding-agents/blob/main/ace-fca.md) never arrives — the analytical brain curates what the agent sees in real time.
+**Context that never degrades.** Other agents fill a static array until the model gets dumb. Anima assembles a fresh viewport over an event bus every iteration. No compaction. No lossy rewriting. Endless sessions. The [dumb zone](https://github.com/humanlayer/advanced-context-engineering-for-coding-agents/blob/main/ace-fca.md) never arrives — Melete curates what Aoide sees in real time.
 
-**Memory that works like memory.** Other systems bolt on memory as an afterthought — filing cabinets the agent has to consciously open mid-task. It never does; the truck is already moving. Anima's memory department ([Mneme](#semantic-memory-mneme)) runs as a third brain process on the event bus. It summarizes what's about to leave the viewport. It compresses short-term into long-term, like biological memory consolidating during sleep. It pins critical moments to active goals so exact instructions survive where summaries would lose nuance. And it recalls — automatically, passively — surfacing relevant older memories right after the soul, right before the present. The agent doesn't decide to remember. It just remembers.
+**Memory that works like memory.** Other systems bolt on memory as an afterthought — filing cabinets the agent has to consciously open mid-task. It never does; the truck is already moving. Mneme, the muse of memory, runs as a background process on the event bus. She summarizes what's about to leave the viewport. She compresses short-term into long-term, like biological memory consolidating during sleep. She pins critical moments to active goals so exact instructions survive where summaries would lose nuance. And she recalls — automatically, passively — surfacing relevant older memories right after the soul, right before the present. Aoide doesn't decide to remember. She just remembers.
 
-**Sub-agents that already know everything.** When Anima spawns a sub-agent, it inherits the parent's full event stream — every file read, every decision, every user message. No "let me summarize what I know." Lossless context. Zero wasted tool calls on rediscovery.
+**Sub-agents that know who they are.** When Anima spawns a sub-agent, it starts clean — identity, task, and nothing else. No inherited conversation history means the sub-agent works on its task, not the parent's trajectory. Context flows through explicit messages, not leaked assistant turns.
 
 **A soul the agent writes itself.** Anima's first session is birth. The agent wakes up, explores its world, meets its human, and writes its own identity. Not a personality description in a config file — a living document the agent authors and evolves. Always in context, always its own.
 
@@ -23,20 +23,24 @@ Your agent. Your machine. Your rules. Anima runs locally as a headless Rails 8.1
 ## Table of Contents
 
 - [Architecture](#architecture)
+  - [Three Muses](#three-muses)
+- [Installation](#installation)
+  - [Distribution Model](#distribution-model)
+  - [Authentication Setup](#authentication-setup)
 - [Agent Capabilities](#agent-capabilities)
   - [Tools](#tools)
   - [Sub-Agents](#sub-agents)
   - [Skills](#skills)
   - [Workflows](#workflows)
   - [MCP Integration](#mcp-integration)
-  - [Analytical Brain](#analytical-brain)
   - [Configuration](#configuration)
 - [Design](#design)
   - [Three Layers](#three-layers-mirroring-biology)
   - [Event-Driven Design](#event-driven-design)
   - [Context as Viewport](#context-as-viewport-not-tape)
   - [Brain as Microservices](#brain-as-microservices-on-a-shared-event-bus)
-  - [Semantic Memory](#semantic-memory-mneme)
+  - [Preparation as a Second Brain (Melete)](#preparation-as-a-second-brain-melete)
+  - [Semantic Memory (Mneme)](#semantic-memory-mneme)
   - [TUI HUD & View Modes](#tui-hud--view-modes)
   - [Plugin Architecture](#plugin-architecture-planned)
 - [The Vision](#the-vision)
@@ -54,63 +58,28 @@ Your agent. Your machine. Your rules. Anima runs locally as a headless Rails 8.1
 
 ## Architecture
 
-```
-Anima (Ruby, Rails 8.1 headless)
-│
-│ Implemented:
-├── Nous         — main LLM (cortex: thinking, decisions, tool use)
-├── Analytical   — subconscious brain (skills, workflows, goals, naming)
-├── Skills       — domain knowledge bundles (Markdown, user-extensible)
-├── Workflows    — operational recipes for multi-step tasks
-├── MCP          — external tool integration (Model Context Protocol)
-├── Sub-agents   — autonomous child sessions with lossless context inheritance
-├── Mneme        — memory department (summarization, compression, pinning, recall)
-│
-│ Designed:
-├── Thymos       — hormonal/desire system (stimulus → hormone vector)
-└── Psyche       — soul matrix (coefficient table, evolving individuality)
-```
+Anima splits into two processes. The **Brain** is persistent — it handles LLM calls, tool execution, event processing, and state. The **TUI** is a stateless client — it connects via WebSocket, renders events, captures input. If the TUI disconnects, the brain keeps running; when it reconnects, the session resumes with chat history preserved.
 
-### Runtime Architecture
+Inside the Brain, three independent LLM processes run in parallel on a shared event bus, named after the three original Muses described by Pausanias. They don't call each other — they all react to the same stream of events, and their outputs combine.
 
-```
-Brain Server (Rails + Puma)              TUI Client (RatatuiRuby)
-├── LLM integration (Anthropic)          ├── WebSocket client
-├── Agent loop + tool execution          ├── Terminal rendering
-├── Analytical brain (background)        └── User input capture
-├── Mneme memory department (background)
-├── Skills registry + activation
-├── Workflow registry + activation
-├── MCP client (HTTP + stdio)
-├── Sub-agent spawning
-├── Event bus + persistence
-├── Solid Queue (background jobs)
-├── Action Cable (WebSocket server)
-└── SQLite databases                ◄── WebSocket (port 42134) ──► TUI
-```
+### Three Muses
+
+**Aoide — the performer.** The main LLM (Claude Opus 4.6), the muse of voice and performance. Thinks, decides, uses tools, talks to the user. Reads a system prompt assembled fresh every turn (soul + sisters block + tool menu + snapshots) and a live **viewport** of events from the database — never a static array. Everything the agent outputs is Aoide; her sisters stay silent in her voice.
 
-The **Brain** is the persistent service — it handles LLM calls, tool execution, event processing, and state. The **TUI** is a stateless client — it connects via WebSocket, renders events, and captures input. If TUI disconnects, the brain keeps running. TUI reconnects automatically with exponential backoff and resumes the session with chat history preserved.
+**Melete — the preparer.** A separate LLM process (Claude Haiku 4.5) that runs as Aoide's subconscious between turns. She observes the conversation and handles everything Aoide shouldn't break flow for: activating relevant skills, managing workflows, tracking goals, naming the session. The first microservice on Anima's event bus — the working proof that background subscribers scale. → [Preparation as a Second Brain (Melete)](#preparation-as-a-second-brain-melete)
 
-### Tech Stack
+**Mneme — the rememberer.** The third muse, running on the same event bus, specializing in one job: making sure nothing important is ever truly lost. She summarizes what's about to leave the viewport, compresses short-term memories into long-term, pins critical events to active goals, and surfaces relevant older context automatically via passive recall. Biology, not a filing cabinet. → [Semantic Memory (Mneme)](#semantic-memory-mneme)
 
-| Component | Technology |
-|-----------|-----------|
-| Framework | Rails 8.1 (headless — no web views, no asset pipeline) |
-| Database | SQLite (3 databases per environment: primary, queue, cable) |
-| Event system | Rails Structured Event Reporter + Action Cable bridge |
-| LLM integration | Anthropic API (Claude Opus 4.6 + Claude Haiku 4.5) |
-| External tools | Model Context Protocol (HTTP + stdio transports) |
-| Transport | Action Cable WebSocket (Solid Cable adapter) |
-| Background jobs | Solid Queue |
-| Interface | TUI via RatatuiRuby (WebSocket client) |
-| Configuration | TOML with hot-reload (`Anima::Settings`) |
-| Process management | Foreman |
-| Distribution | RubyGems (`gem install anima-core`) |
+Two more subsystems are designed but not yet implemented: **Thymos** (a hormonal/desire subscriber) and **Psyche** (a coefficient matrix for evolving individuality). Both plug into the same event bus as Melete and Mneme — no orchestrator, no central loop, just more independent subscribers reacting to the same stream.
+
+## Installation
 
 ### Distribution Model
 
 Anima is a Rails app distributed as a gem, following Unix philosophy: immutable program separate from mutable data.
 
+**Requirements:** Ruby 3.4+, `tmux` (used as the persistent shell backend for the bash tool), `gh` (GitHub CLI, for issue/PR tools).
+
 ```bash
 gem install anima-core       # Install the Rails app as a gem
 anima install                # Create ~/.anima/, set up databases, start brain as systemd service
@@ -129,7 +98,8 @@ State directory (`~/.anima/`):
 ```
 ~/.anima/
 ├── soul.md          # Agent's self-authored identity (always in context)
-├── config.toml      # Main settings (hot-reloadable)
+├── config.toml      # Brain settings (hot-reloadable)
+├── tui.toml         # TUI settings (hot-reloadable)
 ├── mcp.toml         # MCP server configuration
 ├── config/
 │   └── credentials/   # Rails encrypted credentials (includes AR encryption keys)
@@ -141,7 +111,7 @@ State directory (`~/.anima/`):
 └── tmp/
 ```
 
-Updates: `anima update` — upgrades the gem, merges new config settings into your existing `config.toml` without overwriting customized values, and restarts the systemd service if it's running. Use `anima update --migrate-only` to skip the gem upgrade and only add missing config keys.
+Updates: `anima update` — upgrades the gem, merges new config settings into both `config.toml` and `tui.toml` without overwriting customized values, and restarts the systemd service if it's running. Use `anima update --migrate-only` to skip the gem upgrade and only add missing config keys.
 
 ### Authentication Setup
 
@@ -169,8 +139,8 @@ The agent has access to these built-in tools:
 | `spawn_specialist` | Spawn a named specialist sub-agent from the registry |
 | `spawn_subagent` | Spawn a generic child session with custom tool grants |
 | `think` | Think out loud or silently — reasoning step between tool calls |
-| `recall` | Search past conversations by keywords (FTS5). Returns ranked snippets with message IDs for drill-down |
-| `remember` | Recall full conversation context around a past message at fractal resolution |
+| `search_messages` | Keyword sweep across long-term memory (FTS5). Returns ranked snippets with message IDs for drill-down |
+| `view_messages` | Fractal window around a past message — full detail at the center, compressed snapshots at the edges |
 | `open_issue` | File a self-improvement issue when something is broken, missing, or could be better |
 | `mark_goal_completed` | Sub-agent only: signal task completion and deliver results to parent |
 
@@ -178,7 +148,7 @@ Plus dynamic tools from configured MCP servers, namespaced as `server_name__tool
 
 ### Sub-Agents
 
-Sub-agents aren't processes — they're sessions on the same event bus. When a sub-agent spawns, its viewport assembles from two scopes: its own events (prioritized) and the parent's events (filling remaining budget). No context serialization, no summary prompts — the sub-agent sees the parent's raw event stream and already knows everything the parent knows. Lossless inheritance by architecture, not by prompting.
+Sub-agents aren't processes — they're sessions on the same event bus. When a sub-agent spawns, it starts with a clean context: a system prompt (identity + communication instructions), a Goal from the task description, and a single user message containing the task — auto-pinned so it survives viewport eviction. No parent conversation history. Sub-agents inherit the parent shell's working directory at spawn time and use a separate model and token budget (configurable via `subagent_model` and `subagent_token_budget`).
 
 Two types:
 
@@ -194,24 +164,25 @@ Two types:
 
 **Generic Sub-agents** — child sessions with custom tool grants for ad-hoc tasks. Each generic sub-agent gets a Haiku-generated nickname (e.g. `@loop-sleuth`, `@api-scout`) for @mention addressing.
 
-Each sub-agent is spawned with a single **Goal** pinned from its task description and a framing message that redirects attention away from inherited parent goals. When done, the sub-agent calls `mark_goal_completed` to deliver results to the parent — this is the explicit finish line that prevents runaway agents. Sub-agents also get half the main agent's thinking budget to limit scope creep.
+Each sub-agent is spawned with a single **Goal** from its task description and a pinned user message containing the task text. When done, the sub-agent calls `mark_goal_completed` to deliver results to the parent — this is the explicit finish line that prevents runaway agents. Sub-agents also get half the main agent's thinking budget to limit scope creep.
 
 Between spawn and completion, sub-agents communicate through natural text — their `agent_message` events route to the parent session automatically, and the parent replies via `@name` mentions. Workers become colleagues.
 
 ### Skills
 
-Domain knowledge bundles loaded from Markdown files. Skills provide specialized expertise that the analytical brain activates and deactivates based on conversation context.
+Domain knowledge bundles loaded from Markdown files. Skills provide specialized expertise that Melete activates based on conversation context. Skill content enters the conversation as phantom tool_use/tool_result pairs through the `PendingMessage` promotion flow — the same mechanism used for sub-agent messages. This keeps the system prompt stable for prompt caching while skills flow through the sliding window like regular messages.
 
 - **Built-in skills:** ActiveRecord, Draper decorators, DragonRuby, MCP server, RatatuiRuby, RSpec, GitHub issues
 - **User skills:** Drop `.md` files into `~/.anima/skills/` to add custom knowledge
 - **Override:** User skills with the same name replace built-in ones
 - **Format:** Flat files (`skill-name.md`) or directories (`skill-name/SKILL.md` with `examples/` and `references/`)
+- **Viewport deduplication:** Melete's skill catalog excludes skills already visible in the viewport, preventing redundant activation
 
 Active skills are displayed in the TUI HUD panel (toggle with `C-a → h`).
 
 ### Workflows
 
-Operational recipes that describe multi-step tasks. Unlike skills (domain knowledge), workflows describe WHAT to do. The analytical brain activates a workflow when it recognizes a matching task, converts the prose into tracked goals, and deactivates it when done.
+Operational recipes that describe multi-step tasks. Unlike skills (domain knowledge), workflows describe WHAT to do. Melete activates a workflow when she recognizes a matching task and converts the prose into tracked goals. Like skills, workflow content enters the conversation as a `from_melete` phantom pair through the `PendingMessage` flow and rides the viewport until it evicts — there is no explicit deactivation.
 
 - **Built-in workflows:** `feature`, `commit`, `create_plan`, `implement_plan`, `review_pr`, `create_note`, `research_codebase`, `decompose_ticket`, and more
 - **User workflows:** Drop `.md` files into `~/.anima/workflows/` to add custom workflows
@@ -231,7 +202,7 @@ description: "Capture findings or context as a persistent note."
 You are tasked with capturing content as a persistent note...
 ```
 
-The active workflow is shown in the TUI HUD panel with a 📜 indicator. The full lifecycle — activation, goal creation, execution, deactivation — is managed by the analytical brain using judgment, not hardcoded triggers.
+The active workflow is shown in the TUI HUD panel with a 📜 indicator. The full lifecycle — activation, goal creation, execution, deactivation — is managed by Melete using judgment, not hardcoded triggers.
 
 ### MCP Integration
 
@@ -269,24 +240,11 @@ anima mcp secrets remove linear_api_key     # Remove secret
 
 Secrets are stored in an encrypted database table (Active Record Encryption) and interpolated via `${credential:key_name}` syntax in any TOML string value.
 
-### Analytical Brain
-
-A separate LLM process that runs as the agent's subconscious — the first microservice in Anima's brain architecture. For the full motivation behind this design, see [LLMs Have ADHD: Why Your AI Agent Needs a Second Brain](https://blog.promptmaster.pro/posts/llms-have-adhd/).
-
-The analytical brain observes the main conversation between turns and handles everything the main agent shouldn't interrupt its flow for:
-
-- **Skill activation** — activates/deactivates domain knowledge based on conversation context
-- **Workflow management** — recognizes tasks, activates matching workflows, tracks lifecycle
-- **Goal tracking** — creates root goals and sub-goals as work progresses, marks them complete, evicts finished goals from context after a configurable message threshold
-- **Session naming** — generates emoji + short name when the topic becomes clear
-
-Each of these would be a context switch for the main agent — a chore that competes with the primary task. For the analytical brain, they ARE the primary task. Two agents, each in their own flow state.
-
-Goals form a two-level hierarchy (root goals with sub-goals) and are displayed in the TUI. The analytical brain uses a fast model (Claude Haiku 4.5) for speed and runs as a non-persisted "phantom" session.
-
 ### Configuration
 
-All tunable values are exposed through `~/.anima/config.toml` with hot-reload (no restart needed):
+Brain and TUI have separate config files — both hot-reloadable (no restart needed).
+
+**Brain settings** (`~/.anima/config.toml`):
 
 ```toml
 [llm]
@@ -294,32 +252,51 @@ model = "claude-opus-4-6"
 fast_model = "claude-haiku-4-5"
 max_tokens = 8192
 max_tool_rounds = 250
-token_budget = 190_000
+token_budget = 120_000
+subagent_model = "claude-sonnet-4-6"
+subagent_token_budget = 90_000
 
 [timeouts]
 api = 300
 command = 30
 
-[goals]
-completed_decay_messages = 5
-
-[analytical_brain]
+[melete]
 max_tokens = 4096
 blocking_on_user_message = true
 message_window = 20
 
 [session]
 default_view_mode = "basic"
-name_generation_interval = 30
 ```
 
+**TUI settings** (`~/.anima/tui.toml`):
+
+```toml
+[connection]
+default_host = "localhost:42134"    # Override per-launch with --host
+
+[chat]
+scroll_step = 1
+viewport_back_buffer = 3
+
+[theme]
+rate_limit_warning = 70             # Yellow at 70%
+rate_limit_critical = 90            # Red at 90%
+user_message_bg = 22                # 256-color: dark green
+assistant_message_bg = 17           # 256-color: dark navy
+scrollbar_thumb = "cyan"
+border_focused = "yellow"
+```
+
+The TUI is a standalone client with zero Rails dependency. Its settings cover connection tuning, scroll behavior, terminal watchdog, theme colors, and performance logging. See `~/.anima/tui.toml` for all available options.
+
 ## Design
 
 ### Three Layers (mirroring biology)
 
-1. **Cortex (Nous)** — the main LLM. Thinking, decisions, tool use. Reads the system prompt (soul + skills + goals) and the event viewport. This layer is fully implemented.
+1. **Cortex (Aoide)** — the main LLM, the muse of performance. Thinking, decisions, tool use. Reads the system prompt (soul + sisters + tool menu + snapshots) and the event viewport. This layer is fully implemented.
 
-2. **Endocrine system (Thymos)** [planned] — a lightweight background process. Reads recent events. Doesn't respond. Just updates hormone levels. Pure stimulus→response, like a biological gland. The analytical brain is the architectural proof that background subscribers work — Thymos plugs into the same event bus.
+2. **Endocrine system (Thymos)** [planned] — a lightweight background process. Reads recent events. Doesn't respond. Just updates hormone levels. Pure stimulus→response, like a biological gland. Melete is the architectural proof that background subscribers work — Thymos plugs into the same event bus.
 
 3. **Homeostasis** [planned] — persistent state (SQLite). Current hormone levels with decay functions. No intelligence, just state that changes over time. The cortex reads hormone state transformed into **desire descriptions** — not "longing: 87" but "you want to see them." Humans don't see cortisol levels, they feel anxiety.
 
@@ -341,35 +318,33 @@ Events flow through two channels:
 1. **In-process** — Rails Structured Event Reporter (local subscribers like Persister)
 2. **Over the wire** — Action Cable WebSocket (`Event::Broadcasting` callbacks push to connected TUI clients)
 
-Events fire, subscribers react, state updates. The system prompt — soul, active skills, active workflow, current goals — is assembled fresh for each LLM call from live state, not from the event stream. The agent's identity (soul.md) and capabilities (skills, workflows) are always current, never stale.
+Events fire, subscribers react, state updates. The system prompt — soul, sisters block, tool menu, and snapshots — is assembled fresh for each LLM call. Skills, workflows, and goals flow through the message stream as phantom tool pairs instead, keeping the system prompt stable for prompt caching. The agent's identity (soul.md) is always current, never stale.
 
 ### Context as Viewport, Not Tape
 
 Most agents treat context as an append-only array — messages go in, they never come out (until compaction destroys them). Anima has no array. There are only events persisted in SQLite, and a **viewport** assembled fresh for every LLM call.
 
-The viewport is a live query, not a log. It walks events newest-first until the token budget is exhausted. Events that fall out of the viewport aren't deleted — they're still in the database, just not visible to the model right now. The context can shrink, grow, or change composition between any two iterations. If the analytical brain marks a large accidental file read as irrelevant, it's gone from the next viewport — tokens recovered instantly.
+The viewport is a live query, not a log. It walks events newest-first until the token budget is exhausted. Events that fall out of the viewport aren't deleted — they're still in the database, just not visible to the model right now. The context can shrink, grow, or change composition between any two iterations. If Melete marks a large accidental file read as irrelevant, it's gone from the next viewport — tokens recovered instantly.
 
-This means sessions are endless. No compaction. No lossy rewriting. The model always operates in fresh, high-quality context. The [dumb zone](https://github.com/humanlayer/advanced-context-engineering-for-coding-agents/blob/main/ace-fca.md) never arrives. Meanwhile, Mneme runs as a background department — summarizing evicted events into persistent snapshots so past context is preserved, not destroyed.
+This means sessions are endless. No compaction. No lossy rewriting. The model always operates in fresh, high-quality context. The [dumb zone](https://github.com/humanlayer/advanced-context-engineering-for-coding-agents/blob/main/ace-fca.md) never arrives. Meanwhile, Mneme runs as a background muse — summarizing evicted events into persistent snapshots so past context is preserved, not destroyed.
 
-Sub-agent viewports compose from two event scopes — their own events (prioritized) and parent events (filling remaining budget). Same mechanism, no special handling. The bus is the architecture.
+Sub-agent viewports use the same mechanism — their own events only, no parent context inheritance. The parent provides context through the task description, and the sub-agent builds its own conversation from a clean slate.
 
 ### Brain as Microservices on a Shared Event Bus
 
-The human brain isn't a single process — it's dozens of specialized subsystems communicating through shared chemical and electrical signals. The prefrontal cortex doesn't "call" the amygdala. They both react to the same event independently, and their outputs combine.
-
-Anima mirrors this with an event-driven architecture. The analytical brain is the first subscriber — a working proof that the pattern scales. Future subscribers plug into the same bus:
+The prefrontal cortex doesn't "call" the amygdala. Dozens of specialized subsystems react to the same chemical and electrical signals independently, and their outputs combine — no central coordinator, no blocking RPC, no orchestrator deciding the order of thoughts. Anima mirrors this with an event bus. Melete is the first subscriber that proves the pattern scales; Mneme is the second. Future subscribers plug into the same bus:
 
 ```
 Event: "tool_call_failed"
   │
-  ├── Analytical brain: update goals, check if workflow needs changing
+  ├── Melete: update goals, check if workflow needs changing
   ├── Mneme: summarize evicted context into snapshot
   ├── Thymos subscriber: frustration += 10 [planned]
   └── Psyche subscriber: update coefficient (this agent handles errors calmly) [planned]
 
 Event: "user_sent_message"
   │
-  ├── Analytical brain: activate relevant skills, name session
+  ├── Melete: activate relevant skills, name session
   ├── Mneme: check viewport eviction, fire if boundary left viewport
   ├── Thymos subscriber: oxytocin += 5 (bonding signal) [planned]
   └── Psyche subscriber: associate emotional state with topic [planned]
@@ -377,11 +352,26 @@ Event: "user_sent_message"
 
 Each subscriber is a microservice — independent, stateless, reacting to the same event bus. No orchestrator decides what to do. The architecture IS the nervous system.
 
+### Preparation as a Second Brain (Melete)
+
+Every agent today does everything with one brain. Skill selection, workflow tracking, goal management, session naming — all of it competes with the primary task for the same context window and the same attention. Each of these is a micro-task that requires the agent to stop thinking about the real work, do the bookkeeping, and try to pick up where it left off. Flow breaks on every interruption. The full motivation is in [LLMs Have ADHD: Why Your AI Agent Needs a Second Brain](https://blog.promptmaster.pro/posts/llms-have-adhd/).
+
+Melete is the answer: a second LLM process that runs between turns as Aoide's subconscious. She observes the conversation and handles everything Aoide shouldn't break flow for:
+
+- **Skill activation** — recognizes when a domain becomes relevant and activates matching skill content into Aoide's viewport. A skill rides the viewport as a `from_melete` phantom pair until it naturally evicts — there is no deactivation.
+- **Workflow management** — recognizes multi-step tasks, activates matching workflows, and tracks their lifecycle from start to finish.
+- **Goal tracking** — creates root goals and sub-goals as work progresses, marks them complete, evicts finished goals from context after a configurable message threshold.
+- **Session naming** — generates an emoji + short name the moment the topic becomes clear.
+
+Each of these would be a context switch for Aoide — a chore that competes with the primary task. For Melete, they ARE the primary task. Two muses, each in her own flow state.
+
+Goals form a two-level hierarchy (root goals with sub-goals) and are displayed in the TUI HUD. Melete uses a fast model (Claude Haiku 4.5) for speed and runs as a non-persisted "phantom" session: she emits events for activation tools but no trace of her own reasoning lands in the database. Her decisions reach Aoide only through the skills, workflows, goals, and names she leaves behind.
+
 ### Semantic Memory (Mneme)
 
 Every AI agent today has the same disability: amnesia. Context fills up, gets compacted, gets destroyed. The agent gets dumber as the conversation gets longer. When the session ends, everything is gone. Some systems bolt on memory as an afterthought — markdown files with procedures for when to save and what format to use. Filing cabinets the agent has to consciously decide to open, mid-task, while in flow. It never does. The truck is already moving.
 
-Mneme is not a filing cabinet. It's *remembering* — the way biological memory works. Continuous, automatic, layered. A third brain department running on the same event bus as the analytical brain, specializing in one job: making sure nothing important is ever truly lost.
+Mneme is not a filing cabinet. She's *remembering* — the way biological memory works. Continuous, automatic, layered. The third muse running on the same event bus as Aoide and Melete, specializing in one job: making sure nothing important is ever truly lost.
 
 **Eviction-triggered summarization** — Mneme tracks a boundary event on each session. When that event leaves the viewport, Mneme fires: it builds a compressed view of the conversation (full text for messages, `[N tools called]` counters for tool work), sends it to a fast model, and persists a snapshot. The boundary advances after each run — a self-regulating cycle that fires exactly when context is about to be lost, no sooner or later. No timer. No manual trigger. The architecture itself knows when to remember.
 
@@ -398,16 +388,40 @@ Mneme is not a filing cabinet. It's *remembering* — the way biological memory
 
 **Goal-scoped event pinning** — some moments are too important for summaries. Exact user instructions. Key decisions. Critical corrections. Mneme pins these events to active Goals — they float above the sliding window, protected from eviction, surviving intact where compression would lose the nuance that matters. Pins are goal-scoped and many-to-many: one event can attach to multiple Goals, and cleanup is automatic via reference counting. When the last active Goal completes, the pin releases. No manual unpin, no stale pins accumulating forever.
 
-**Associative recall** — FTS5 full-text search across the entire event history, across all sessions. Two modes: *passive* recall triggers automatically when goals change — Mneme searches for relevant older context and injects it into the viewport between snapshots and the sliding window. Memories surface on their own, right after the soul, right before the present. The agent doesn't have to decide to remember — the remembering happens around it. *Active* recall via the `remember(event_id:)` tool returns a fractal-resolution window centered on a target event — full detail at the center, compressed snapshots at the edges, like eye focus with sharp fovea and blurry periphery.
+**Associative recall** — FTS5 full-text search across the entire message history, across all sessions. Two modes: *passive* recall triggers automatically when goals change — Mneme searches for relevant older context and injects it into the viewport between snapshots and the sliding window as `from_mneme` phantom pairs. Memories surface on their own, right after the soul, right before the present. Aoide doesn't have to decide to remember — the remembering happens around her. *Active* search is available to Aoide through `search_messages(query:)` (keyword sweep across long-term memory) and `view_messages(message_id:)` (fractal window around a specific message — full detail at the center, compressed snapshots at the edges, like eye focus with sharp fovea and blurry periphery).
 
 The difference from every other system: memory isn't a tool the agent uses. It's the substrate the agent thinks in. Every LLM call assembles a fresh viewport where identity comes first, then memories, then the present — the agent always knows who it is, always has access to what it learned, and never has to break flow to make that happen.
 
 ### TUI HUD & View Modes
 
-The right-side HUD panel shows session state at a glance: session name, goals (with status icons), active skills, workflow, and sub-agents. Toggle with `C-a → h`; when hidden, the input border shows `C-a → h HUD` as a reminder.
+The right-side HUD panel shows session state at a glance: session name, goals (with status icons), active skills, workflow, and sub-agents. Toggle with `C-a → h`; when hidden, the input border shows `C-a → h HUD` as a reminder. The sub-agent list mirrors what Aoide actually carries in her viewport: once Mneme eviction takes the last spawn pair or `from_<nickname>` response out of the sliding window, the entry drops from the HUD; if a later response reintroduces a trace, the entry comes back.
 
 **Braille spinner**: An animated braille character (U+2800-U+28FF) replaces the old "Thinking..." label in both the chat viewport and HUD. Each processing state has a distinct animation pattern — smooth snake rotation for LLM generation, staccato pulse for tool execution, rapid deceleration for interrupting. Sub-agents in the HUD show state-driven icons: `●` (generating, green), `◉` (tool executing, green), `●` (interrupting, red), `◌` (idle, grey).
 
+**Token Economy HUD**: A fixed panel at the bottom of the HUD displays API economics extracted from every Anthropic response:
+
+```
+╭ 📊 Token Economy ────────────────────╮
+│  5h ░░░░░░░░  1% ➞3h42m              │
+│  7d ▓▓▓▓▓▓▓▓ 98%                     │
+│  ⚡ ▓▓▓▓▓▓░░ 69%                     │
+│  💾 6.3K tokens                      │
+│     ⠛⣿⣷⣶⣿⣿⣿⣿⣷⣶⣿⣿⣿           │
+│  🟢 Verbose                          │
+╰──────────────────────────────────────╯
+```
+
+| Row | Description |
+|-----|-------------|
+| `5h` | 5-hour rate limit utilization with progress bar and reset countdown |
+| `7d` | 7-day rate limit utilization with progress bar |
+| `⚡` | Cache hit rate of the latest call — percentage of input tokens served from cache |
+| `💾` | Tokens served from cache on the latest call |
+| `⠛⣿` | Braille sparkline — per-call cache hit history (2 calls per character); drops signal cache busts |
+| `🟢` | Connection status and current view mode |
+
+Progress bars are color-coded: green (< 70%), yellow (70-89%), red (>= 90%) for rate limits; inverted for cache hits (green >= 70%, red < 30%). All data comes from Anthropic API response headers and usage objects, broadcast as message metadata via ActionCable.
+
 When content exceeds the panel height, the HUD scrolls. Three input methods:
 
 | Input | Action |
@@ -419,7 +433,7 @@ When content exceeds the panel height, the HUD scrolls. Three input methods:
 | `Escape` or `C-a` | Exit HUD focus mode |
 | Mouse wheel over HUD | Scroll without entering focus mode |
 
-**Escape key interrupt:** Press `Escape` while the agent is working to stop execution mid-tool. Running shell commands receive Ctrl+C and return partial output; pending tool calls are skipped; LLM text generation is discarded. The interrupt cascades to active sub-agents.
+**Escape key interrupt:** Press `Escape` while the agent is working to signal an interrupt. Running shell commands cooperatively abort — they receive Ctrl+C and return partial output tagged `Your human wants your attention`, which the LLM sees on the next round and pivots from. The interrupt cascades to active sub-agents.
 
 Three switchable view modes let you control how much detail the TUI shows. Cycle with `C-a → v`:
 
@@ -432,8 +446,8 @@ Three switchable view modes let you control how much detail the TUI shows. Cycle
 View modes are implemented as a three-layer decorator architecture:
 
 - **ToolDecorator** (server-side, pre-event) — transforms raw tool responses for LLM consumption. Content-Type dispatch converts HTML → Markdown, JSON → TOON. Sits between tool execution and the event stream.
-- **EventDecorator** (server-side, Draper) — uniform per event type (`UserMessageDecorator`, `ToolCallDecorator`, etc.). Decides WHAT structured data enters the wire for each view mode.
-- **TUI Decorator** (client-side) — unique per tool name (`BashDecorator`, `ReadDecorator`, `EditDecorator`, etc.). Decides HOW each tool looks on screen — tool-specific icons, colors, and formatting.
+- **EventDecorator** (server-side, Draper) — uniform per message type (`UserMessageDecorator`, `ToolCallDecorator`, etc.) for promoted messages, and a parallel family (`PendingUserMessageDecorator`, `PendingToolResponseDecorator`, `PendingSubagentDecorator`, `PendingFromMnemeDecorator`, `PendingFromMelete{Skill,Workflow,Goal}Decorator`) for in-flight `PendingMessage` rows. Decides WHAT structured data enters the wire for each view mode; pending payloads carry `status: "pending"` so the TUI dims them.
+- **TUI Decorator** (client-side) — unique per tool name (`BashDecorator`, `ReadDecorator`, `EditDecorator`, etc.). Decides HOW each tool looks on screen — tool-specific icons, colors, and formatting. Honors `status: "pending"` to render in-flight content in the muted theme color.
 
 Mode is stored on the `Session` model server-side, so it persists across reconnections.
 
@@ -605,11 +619,11 @@ This single example demonstrates every core principle:
 
 - Event-driven architecture on a shared event bus
 - Dynamic viewport context assembly (endless sessions, no compaction)
-- Analytical brain (skills, workflows, goals, session naming)
-- Mneme memory department (eviction-triggered summarization, persistent snapshots, goal-scoped event pinning, associative recall)
+- Melete, muse of practice (skills, workflows, goals, session naming)
+- Mneme, muse of memory (eviction-triggered summarization, persistent snapshots, goal-scoped event pinning, associative recall)
 - 12 built-in tools + MCP integration (HTTP + stdio transports)
 - 7 built-in skills + 13 built-in workflows (user-extensible)
-- Sub-agents with lossless context inheritance (5 specialists + generic)
+- Sub-agents with isolated context (5 specialists + generic)
 - Client-server architecture with WebSocket transport + graceful reconnection
 - Collapsible HUD panel with goals, skills, workflow, and sub-agent tracking
 - Three TUI view modes (Basic / Verbose / Debug)