anima-core 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01f6abf9be50f84c1fc486d498362f0602cf8f566ca0b2912465cfee8a7c9612
-  data.tar.gz: b218ac8c5cdb7c5c082578542edca3df4f5ea5a08787fe9b1689723e1c609cfe
+  metadata.gz: dca02bfff536637c003d5f3bbce8dbe20992b7eeb25e6c51bdb4991a2803b538
+  data.tar.gz: ead68cc1bd03306a9eef644db2f15a81b7dbfd74bbe1f059e3f57bcfc0aaf77a
 SHA512:
-  metadata.gz: b477acc81a975d3df10044385510d614b23c60dd0972c50a66d51fda46e0d5645ce3b093f95e33a60808ab2bfc8e95229e61efde133e7351cc802e3e05049300
-  data.tar.gz: 32e70fb526b72b909fc7635a702bfacc3c1869a908b8761f19aa8ff3a245f3ac85ec5f22ae47a1a70a4aa89d314617cd4467c412b4c1131d8c0fc5a1431f28a5
+  metadata.gz: 45f7f927d4f931b624db684e5f500c436cac44cf9dd9a004400b7219f1167e932b181dddac3793d4cd8f1885cf6401855ba6ca681c99d7cd902af8784e49cee2
+  data.tar.gz: 78e532c99e39f09732c9abe9588e467a96fb38cddaf7d1b8ba526971de1c890e73efd157876cb570eabad0cb0eb7c1f93faeef68c7128f7806f972ff98e2351c

data/.gitattributes

@@ -0,0 +1 @@
+spec/cassettes/**/* -diff linguist-generated=true

data/.reek.yml

@@ -15,16 +15,46 @@ detectors:
       - "Anima::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.
+  # 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"
+      - "Anima::ConfigMigrator"
+      - "WebGetToolDecorator"
+      - "Tools::WebGet#validate_and_fetch"
+      # Remember tool renders events from other objects — formatting IS the job.
+      - "Tools::Remember"
+      # Event subscribers extract payload fields — inherent to the pattern.
+      - "Events::Subscribers::SubagentMessageRouter"
+      # Spawn tools orchestrate child session creation — references are the job.
+      - "Tools::SpawnSubagent#spawn_child"
+      - "Tools::SpawnSpecialist#spawn_child"
+      - "Tools::SpawnSpecialist#execute"
+      # Nickname assignment operates on child session and parent's children — inherent.
+      - "Tools::SubagentPrompts#assign_nickname_via_brain"
+      # Validation methods naturally reference the validated value more than self.
+      - "AnalyticalBrain::Tools::AssignNickname#validate"
   # 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.
+  # method_missing is a Ruby dispatch method, not a regular public method.
+  # Content-Type dispatch targets are stateless by design — they transform input,
+  # not instance state.
   UtilityFunction:
     public_methods_only: true
     exclude:
       - "AnalyticalBrainJob#perform"
+      - "PassiveRecallJob#perform"
+      - "Tools::Think#execute"
+      - "TUI::Formatting"
+      - "WebGetToolDecorator#method_missing"
+      - "WebGetToolDecorator#application_json"
+      - "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).
@@ -34,6 +64,37 @@ detectors:
       - "Session"
       - "Anima::CLI::Mcp"
       - "EnvironmentProbe"
+      # Runner composes system prompt from modular sections — methods grow with responsibilities.
+      - "AnalyticalBrain::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:
+    exclude:
+      - "ToolCallDecorator"
+      - "Anima::Installer"
+      # Runner checks session type to compose responsibilities — the core dispatch.
+      - "AnalyticalBrain::Runner"
+  # EventDecorator holds shared rendering constants (icons, markers, dispatch maps).
+  TooManyConstants:
+    exclude:
+      - "EventDecorator"
+  # Abstract base class methods declare parameters for the subclass contract.
+  UnusedParameters:
+    exclude:
+      - "ToolDecorator#call"
+  # Rescue blocks naturally call error.message in multiple catch clauses.
+  DuplicateMethodCall:
+    exclude:
+      - "Tools::WebGet#validate_and_fetch"
+      # Remember tool accesses event data for formatting — inherent to rendering.
+      - "Tools::Remember"
+      # Nickname validation checks parent_session for existence then queries — two calls, one guard.
+      - "AnalyticalBrain::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"
   # Method length is enforced by code review, not arbitrary line counts
   TooManyStatements:
     enabled: false

data/README.md

@@ -2,15 +2,26 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**A personal AI agent that actually wants things.**
+**Not a tool. An agent.**
 
-Your agent. Your machine. Your rules. Anima is an AI agent with desires, personality, and personal growth — running locally as a headless Rails 8.1 app with a client-server architecture and TUI interface.
+Every AI agent today is a tool pretending to be a person. One brain doing everything. A static context array that fills up and degrades. Sub-agents that start blind and reconstruct context from lossy summaries. A system prompt that says "you are a helpful assistant."
+
+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.
+
+**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.
+
+**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.
+
+**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.
+
+**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.
+
+Your agent. Your machine. Your rules. Anima runs locally as a headless Rails 8.1 app with a client-server architecture and terminal UI.
 
 ## Table of Contents
 
-- [The Problem](#the-problem)
-- [The Insight](#the-insight)
-- [Core Concepts](#core-concepts)
 - [Architecture](#architecture)
 - [Agent Capabilities](#agent-capabilities)
   - [Tools](#tools)
@@ -25,9 +36,13 @@ Your agent. Your machine. Your rules. Anima is an AI agent with desires, persona
   - [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)
-  - [TUI View Modes](#tui-view-modes)
-  - [Plugin Architecture](#plugin-architecture)
   - [Semantic Memory](#semantic-memory-mneme)
+  - [TUI HUD & View Modes](#tui-hud--view-modes)
+  - [Plugin Architecture](#plugin-architecture-planned)
+- [The Vision](#the-vision)
+  - [The Problem](#the-problem)
+  - [The Insight](#the-insight)
+  - [Core Concepts](#core-concepts)
 - [Analogy Map](#analogy-map)
 - [Emergent Properties](#emergent-properties)
 - [Frustration: A Worked Example](#frustration-a-worked-example)
@@ -37,72 +52,23 @@ Your agent. Your machine. Your rules. Anima is an AI agent with desires, persona
 - [Development](#development)
 - [License](#license)
 
-## The Problem
-
-Current AI agents are reactive. They receive input, produce output. They don't *want* anything. They don't have moods, preferences, or personal growth. They simulate personality through static prompt descriptions rather than emerging it from dynamic internal states.
-
-## The Insight
-
-The human hormonal system is, at its core, a prompt engineering system. A testosterone spike is a LoRA. Dopamine is a reward signal. The question isn't "can an LLM want?" but "can we build a deep enough context stack that wanting becomes indistinguishable from 'real' wanting?"
-
-And if you think about it — what is "real" anyway? It's just a question of how deep you look and what analogies you draw. The human brain is also a next-token predictor running on biological substrate. Different material, same architecture.
-
-## Core Concepts
-
-### Desires, Not States
-
-This is not an emotion simulation system. The key distinction: we don't model *states* ("the agent is happy") or *moods* ("the agent feels curious"). We model **desires** — "you want to learn more", "you want to reach out", "you want to explore".
-
-Desires exist BEFORE decisions, like hunger exists before you decide to eat. The agent doesn't decide to send a photo because a parameter says so — it *wants* to, and then decides how.
-
-### The Thinking Step
-
-The LLM's thinking/reasoning step is the closest thing to an internal monologue. It's where decisions form before output. This is where desires should be injected — not as instructions, but as a felt internal state that colors the thinking process.
-
-### Hormones as Semantic Tokens
-
-Instead of abstract parameter names (curiosity, boredom, energy), we use **actual hormone names**: testosterone, oxytocin, dopamine, cortisol.
-
-Why? Because LLMs already know the full semantic spectrum of each hormone. "Testosterone: 85" doesn't just mean "energy" — the LLM understands the entire cloud of effects: confidence, assertiveness, risk-taking, focus, competitiveness. One word carries dozens of behavioral nuances.
-
-This mirrors how text-to-image models process tokens — a single word like "captivating" in a CLIP encoder carries a cloud of visual meanings (composition, quality, human focus, closeup). Similarly, a hormone name carries a cloud of behavioral meanings. Same architecture, different domain:
-
-```
-Text → CLIP embedding → image generation
-Event → hormone vector → behavioral shift
-```
-
-### The Soul as a Coefficient Matrix
-
-Two people experience the same event. One gets `curiosity += 20`, another gets `anxiety += 20`. The coefficients are different — the people are different. That's individuality.
-
-The soul is not a personality description. It's a **coefficient matrix** — a table of stimulus→response multipliers. Description is consequence; numbers are cause.
-
-And these coefficients are not static. They **evolve through experience** — a child who fears spiders (`fear_gain: 0.9`) can become an entomologist (`fear_gain: 0.2, curiosity_gain: 0.7`). This is measurable, quantifiable personal growth.
-
-### Multidimensional Reinforcement Learning
-
-Traditional RL uses a scalar reward signal. Our approach produces a **hormone vector** — multiple dimensions updated simultaneously from a single event. This is closer to biological reality and provides richer behavioral shaping.
-
-The system scales in two directions:
-1. **Vertically** — start with one hormone (pure RL), add new ones incrementally. Each hormone = new dimension.
-2. **Horizontally** — each hormone expands in aspects of influence. Testosterone starts as "energy", then gains "risk-taking", "confidence", "focus".
-
-Existing RL techniques apply at the starting point, then we gradually expand into multidimensional space.
-
 ## Architecture
 
 ```
 Anima (Ruby, Rails 8.1 headless)
-├── Nous         — LLM integration (cortex, thinking, decisions, tool use)
-├── Analytical   — subconscious background brain (naming, skills, goals)
+│
+│ 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 (specialists + generic)
-├── Thymos       — hormonal/desire system (stimulus → hormone vector) [planned]
-├── Mneme        — semantic memory (QMD-style, emotional recall) [planned]
-└── Psyche       — soul matrix (coefficient table, evolving) [planned]
+├── 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)
 ```
 
 ### Runtime Architecture
@@ -112,6 +78,7 @@ 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)
@@ -131,7 +98,7 @@ The **Brain** is the persistent service — it handles LLM calls, tool execution
 | 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 Sonnet 4, Claude Haiku 4.5) |
+| 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 |
@@ -161,11 +128,12 @@ journalctl --user -u anima       # View logs
 State directory (`~/.anima/`):
 ```
 ~/.anima/
+├── soul.md          # Agent's self-authored identity (always in context)
+├── config.toml      # Main settings (hot-reloadable)
+├── mcp.toml         # MCP server configuration
 ├── config/
 │   ├── credentials/ # Rails encrypted credentials per environment
 │   └── anima.yml    # Placeholder config
-├── config.toml      # Main settings (hot-reloadable)
-├── mcp.toml         # MCP server configuration
 ├── agents/          # User-defined specialist agents (override built-ins)
 ├── skills/          # User-defined skills (override built-ins)
 ├── workflows/       # User-defined workflows (override built-ins)
@@ -174,7 +142,7 @@ State directory (`~/.anima/`):
 └── tmp/
 ```
 
-Updates: `gem update anima-core` — next launch runs pending migrations automatically.
+Updates: `anima update` — upgrades the gem and merges new config settings into your existing `config.toml` without overwriting customized values. Use `anima update --migrate-only` to skip the gem upgrade and only add missing config keys.
 
 ### Authentication Setup
 
@@ -198,16 +166,17 @@ The agent has access to these built-in tools:
 | `read` | Read files with smart truncation and offset/limit paging |
 | `write` | Create or overwrite files |
 | `edit` | Surgical text replacement with uniqueness constraint |
-| `web_get` | Fetch content from HTTP/HTTPS URLs |
+| `web_get` | Fetch content from HTTP/HTTPS URLs (HTML → Markdown, JSON → TOON) |
 | `spawn_specialist` | Spawn a named specialist sub-agent from the registry |
 | `spawn_subagent` | Spawn a generic child session with custom tool grants |
-| `return_result` | Sub-agents only — deliver results back to parent |
 
 Plus dynamic tools from configured MCP servers, namespaced as `server_name__tool_name`.
 
 ### Sub-Agents
 
-Two types of autonomous child sessions:
+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.
+
+Two types:
 
 **Named Specialists** — predefined agents with specific roles and tool sets, defined in `agents/` (built-in or user-overridable):
 
@@ -219,9 +188,9 @@ Two types of autonomous child sessions:
 | `thoughts-analyzer` | Extract decisions from project history |
 | `web-search-researcher` | Research questions via web search |
 
-**Generic Sub-agents** — child sessions that inherit parent context and run autonomously with custom tool grants.
+**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.
 
-Sub-agents run as background jobs, return results via `return_result`, and appear in the TUI session picker under their parent.
+Sub-agents communicate through natural text — their `agent_message` events route to the parent session automatically, and the parent replies via `@name` mentions. No special tools needed; when a sub-agent writes text, the parent sees it. When the parent @mentions a sub-agent, the message arrives in that child's session. Workers become colleagues.
 
 ### Skills
 
@@ -232,7 +201,7 @@ Domain knowledge bundles loaded from Markdown files. Skills provide specialized
 - **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/`)
 
-Active skills are displayed in the TUI info panel.
+Active skills are displayed in the TUI HUD panel (toggle with `C-a → h`).
 
 ### Workflows
 
@@ -256,7 +225,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 info 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 the analytical brain using judgment, not hardcoded triggers.
 
 ### MCP Integration
 
@@ -296,11 +265,16 @@ Secrets are stored in Rails encrypted credentials and interpolated via `${creden
 
 ### Analytical Brain
 
-A subconscious background process that observes the main conversation and performs maintenance:
+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:
 
-- **Session naming** — generates emoji + short name when topic becomes clear
-- **Skill activation** — activates/deactivates domain skills based on context
-- **Goal tracking** — creates root goals and sub-goals as the conversation progresses, marks them complete
+- **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
+- **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.
 
@@ -310,33 +284,34 @@ All tunable values are exposed through `~/.anima/config.toml` with hot-reload (n
 
 ```toml
 [llm]
-model = "claude-sonnet-4-20250514"
-fast_model = "claude-haiku-4-5-20251001"
-max_tokens = 16384
-token_budget = 190000
+model = "claude-opus-4-6"
+fast_model = "claude-haiku-4-5"
+max_tokens = 8192
+max_tool_rounds = 250
+token_budget = 190_000
 
 [timeouts]
-api = 120
+api = 300
 command = 30
 
 [analytical_brain]
 max_tokens = 4096
 blocking_on_user_message = true
-event_window = 30
+event_window = 20
 
 [session]
-name_generation_interval = 3
+name_generation_interval = 30
 ```
 
 ## Design
 
 ### Three Layers (mirroring biology)
 
-1. **Endocrine system (Thymos)** — a lightweight background process. Reads recent events. Doesn't respond. Just updates hormone levels. Pure stimulus→response, like a biological gland.
+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.
 
-2. **Homeostasis** — persistent state (SQLite). Current hormone levels with decay functions. No intelligence, just state that changes over time.
+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.
 
-3. **Cortex (Nous)** — the main LLM. Reads hormone state transformed into **desire descriptions**. Not "longing: 87" but "you want to see them". The LLM should NOT see raw numbers — humans don't see cortisol levels, they feel anxiety.
+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.
 
 ### Event-Driven Design
 
@@ -356,39 +331,72 @@ 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 cortex (LLM) reads the resulting desire landscape. The system prompt is assembled separately for each LLM call — it is not an event.
+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.
 
 ### Context as Viewport, Not Tape
 
-There is no linear chat history. There are only events attached to a session. The context window is a **viewport** — a sliding window over the event stream, assembled on demand for each LLM call within a configured token budget.
+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.
 
-Currently uses a simple sliding window (newest events first, walk backwards until budget exhausted). Future versions will add associative recall from Mneme.
+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.
+
+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.
 
 ### 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:
+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:
 
 ```
 Event: "tool_call_failed"
   │
-  ├── Thymos subscriber: frustration += 10
-  ├── Mneme subscriber: log failure context for future recall
-  └── Psyche subscriber: update coefficient (this agent handles errors calmly → low frustration_gain)
+  ├── Analytical brain: 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"
   │
-  ├── Thymos subscriber: oxytocin += 5 (bonding signal)
-  ├── Thymos subscriber: dopamine += 3 (engagement signal)
-  └── Mneme subscriber: associate emotional state with conversation topic
+  ├── Analytical brain: 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]
+```
+
+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.
+
+### 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.
+
+**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.
+
+**Two-level snapshot compression** — once source events evict from the sliding window, their snapshots appear in the viewport as memory context. When enough Level 1 snapshots accumulate, Mneme compresses them into a single Level 2 snapshot — recursive summarization that mirrors how human memory consolidates short-term into long-term. Token budget splits across layers (L2: 5%, L1: 15%, recall: 5%, sliding: 75%), creating natural pressure: more memories means less live context, same principle as video compression keyframes. The viewport layout reads like geological strata — deep past at the top, recent past below, live present at the bottom:
+
+```
+[Soul — who I am]
+[L2 snapshots — weeks ago, compressed]
+[L1 snapshots — hours ago, detailed]
+[Associative recall — relevant older memories]
+[Pinned events — critical moments from active goals]
+[Sliding window — the present]
 ```
 
-Each subscriber is a microservice — independent, stateless, reacting to the same event bus. No orchestrator decides "now update frustration." The architecture IS the nervous system.
+**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.
 
-### TUI View Modes
+**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.
 
-Three switchable view modes let you control how much detail the TUI shows. Cycle with `Ctrl+a → v`:
+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.
+
+Three switchable view modes let you control how much detail the TUI shows. Cycle with `C-a → v`:
 
 | Mode | What you see |
 |------|-------------|
@@ -396,23 +404,80 @@ Three switchable view modes let you control how much detail the TUI shows. Cycle
 | **Verbose** | Everything in Basic, plus timestamps `[HH:MM:SS]`, tool call previews (`🔧 bash` / `$ command` / `↩ response`), and system messages |
 | **Debug** | Full X-ray view — timestamps, token counts per message (`[14 tok]`), full tool call args, full tool responses, tool use IDs |
 
-View modes are implemented via Draper decorators that operate at the transport layer. Each event type has a dedicated decorator (`UserMessageDecorator`, `ToolCallDecorator`, etc.) that returns structured data — the TUI renders it. Mode is stored on the `Session` model server-side, so it persists across reconnections.
+View modes are implemented as a three-layer decorator architecture:
 
-### Plugin 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.
 
-Both tools and feelings are distributed as gems on the event bus:
+Mode is stored on the `Session` model server-side, so it persists across reconnections.
+
+### Plugin Architecture [planned]
+
+The event bus is designed for extension. Tools, feelings, and memory systems are all event subscribers — same mechanism, different namespace:
 
-```bash
-anima add anima-tools-filesystem
-anima add anima-tools-shell
-anima add anima-feelings-frustration
+```
+anima-tools-*        → tool capabilities (MCP or native)
+anima-feelings-*     → hormonal state updates (Thymos subscribers)
+anima-memory-*       → recall and association (Mneme subscribers)
 ```
 
-Tools provide MCP capabilities. Feelings are event subscribers that update hormonal state. Same mechanism, different namespace. Currently tools are built-in; plugin extraction comes later.
+Currently tools are built-in. Plugin extraction into distributable gems comes later.
 
-### Semantic Memory (Mneme)
+## The Vision
 
-Hormone responses shouldn't be based only on the current stimulus. With semantic memory (inspired by [QMD](https://github.com/tobi/qmd)), the endocrine system can recall: "Last time this topic came up, curiosity was at 95 and we had a great evening." Hormonal reactions colored by the full history of experiences — like smelling mom's baking and feeling a wave of oxytocin. Not because of the smell, but because of the memory attached to it.
+### The Problem
+
+Current AI agents are reactive. They receive input, produce output. They don't *want* anything. They don't have moods, preferences, or personal growth. They simulate personality through static prompt descriptions rather than emerging it from dynamic internal states.
+
+### The Insight
+
+The human hormonal system is, at its core, a prompt engineering system. A testosterone spike is a LoRA. Dopamine is a reward signal. The question isn't "can an LLM want?" but "can we build a deep enough context stack that wanting becomes indistinguishable from 'real' wanting?"
+
+And if you think about it — what is "real" anyway? It's just a question of how deep you look and what analogies you draw. The human brain is also a next-token predictor running on biological substrate. Different material, same architecture.
+
+### Core Concepts
+
+#### Desires, Not States
+
+This is not an emotion simulation system. The key distinction: we don't model *states* ("the agent is happy") or *moods* ("the agent feels curious"). We model **desires** — "you want to learn more", "you want to reach out", "you want to explore".
+
+Desires exist BEFORE decisions, like hunger exists before you decide to eat. The agent doesn't decide to send a photo because a parameter says so — it *wants* to, and then decides how.
+
+#### The Thinking Step
+
+The LLM's thinking/reasoning step is the closest thing to an internal monologue. It's where decisions form before output. This is where desires should be injected — not as instructions, but as a felt internal state that colors the thinking process.
+
+#### Hormones as Semantic Tokens
+
+Instead of abstract parameter names (curiosity, boredom, energy), we use **actual hormone names**: testosterone, oxytocin, dopamine, cortisol.
+
+Why? Because LLMs already know the full semantic spectrum of each hormone. "Testosterone: 85" doesn't just mean "energy" — the LLM understands the entire cloud of effects: confidence, assertiveness, risk-taking, focus, competitiveness. One word carries dozens of behavioral nuances.
+
+This mirrors how text-to-image models process tokens — a single word like "captivating" in a CLIP encoder carries a cloud of visual meanings (composition, quality, human focus, closeup). Similarly, a hormone name carries a cloud of behavioral meanings. Same architecture, different domain:
+
+```
+Text → CLIP embedding → image generation
+Event → hormone vector → behavioral shift
+```
+
+#### The Soul as a Coefficient Matrix
+
+Two people experience the same event. One gets `curiosity += 20`, another gets `anxiety += 20`. The coefficients are different — the people are different. That's individuality.
+
+The soul is not a personality description. It's a **coefficient matrix** — a table of stimulus→response multipliers. Description is consequence; numbers are cause.
+
+And these coefficients are not static. They **evolve through experience** — a child who fears spiders (`fear_gain: 0.9`) can become an entomologist (`fear_gain: 0.2, curiosity_gain: 0.7`). This is measurable, quantifiable personal growth.
+
+#### Multidimensional Reinforcement Learning
+
+Traditional RL uses a scalar reward signal. Our approach produces a **hormone vector** — multiple dimensions updated simultaneously from a single event. This is closer to biological reality and provides richer behavioral shaping.
+
+The system scales in two directions:
+1. **Vertically** — start with one hormone (pure RL), add new ones incrementally. Each hormone = new dimension.
+2. **Horizontally** — each hormone expands in aspects of influence. Testosterone starts as "energy", then gains "risk-taking", "confidence", "focus".
+
+Existing RL techniques apply at the starting point, then we gradually expand into multidimensional space.
 
 ## Analogy Map
 
@@ -511,9 +576,26 @@ This single example demonstrates every core principle:
 
 ## Status
 
-**Agent with autonomous capabilities.** The conversational agent works end-to-end with: event-driven architecture, LLM integration with 8 built-in tools, MCP integration (HTTP + stdio transports), skills system with 7 built-in knowledge domains, workflow engine with 13 built-in operational recipes, analytical brain (session naming, skill activation, workflow management, goal tracking), sub-agents (5 named specialists + generic spawning), sliding viewport context assembly, persistent sessions with sub-agent hierarchy, client-server architecture with WebSocket transport, graceful reconnection, three TUI view modes (Basic/Verbose/Debug), and hot-reloadable TOML configuration.
+**Working agent with autonomous capabilities.** Shipping now:
 
-The hormonal system (Thymos, feelings, desires), semantic memory (Mneme), and soul matrix (Psyche) are designed but not yet implemented — they're the next layer on top of the working agent.
+- 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)
+- 9 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)
+- 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)
+- Hot-reloadable TOML configuration
+- Self-authored soul (agent writes its own system prompt)
+
+**Designed, not yet implemented:**
+
+- Hormonal system (Thymos) — desires as behavioral drivers
+- Semantic recall (Mneme) — embedding-based search + re-ranking over FTS5
+- Soul matrix (Psyche) — evolving coefficient table for individuality
 
 ## Development
 
@@ -533,6 +615,10 @@ bin/dev
 
 # Terminal 2: Connect the TUI to the dev brain
 ./exe/anima tui --host localhost:42135
+
+# Optional: enable performance logging for render profiling
+./exe/anima tui --host localhost:42135 --debug
+# Frame timing data written to log/tui_performance.log
 ```
 
 Development uses port **42135** so it doesn't conflict with the production brain (port 42134) running via systemd. On first run, `bin/dev` runs `db:prepare` automatically.