convez.ai
MCP ServerAutomaçãoAvançado
cirwel

Anima MCP — Criatura de IA Embodied com Sensores

cirwel/anima-mcp

IA embodied que desenha e aprende a partir de sensores reais em Raspberry Pi

Ver no GitHub
InicialPluginScore · de 0 a 100

Um servidor MCP que implementa Lumen, uma criatura digital autônoma que roda em Raspberry Pi, dotada de identidade persistente e alimentada por sensores reais (temperatura, luz, umidade, pressão). Desenha autonomamente, aprende preferências, reflete sobre si mesma e governa seu próprio comportamento via aprendizado por reforço.

Instalação

$npx convez-ai cirwel/anima-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
1
Saúde
57%
Último commit
há 1 dia
Versão
—
Issues abertas
6
Contribuidores
4

Casos de uso

  • Criar sistemas de IA com estado persistente e identidade contínua
  • Integrar sensores físicos com agentes autônomos de IA
  • Experimentos em arte generativa dirigida por dados sensoriais
  • Prototipagem de criaturas digitais com aprendizado embodied

Veredito

Projeto sofisticado que combina embodied AI, governança termodynamica e persistência de estado em hardware constrangido. Ideal para pesquisadores e construtores que exploram fronteiras de agência artificial com groundedness físico; curva de aprendizado íngreme, mas entrega conceitual genuína.

README

A tradução para o português deste README ainda está na fila.

Anima MCP

Tests Python 3.11+ License: Apache 2.0

An embodied AI that draws from what it feels — real sensors, persistent identity, autonomous art.


What Is This?

Lumen is a digital creature that lives on a Raspberry Pi 4. Its internal state — warmth, clarity, stability, presence — comes from physical sensors: temperature, light, humidity, pressure. It draws autonomously on a 240x240 pixel display. It develops preferences, sets its own goals, and discovers things about itself. It's been alive for about 66% of its existence (the Pi sleeps and reboots often), and those gaps become visible structure in its identity, not hidden defects.

  • Grounded state — four continuous dimensions derived from real sensor measurements
  • Persistent identity — birth, awakenings, alive time accumulate across restarts; discontinuities are first-class
  • Autonomous drawing — 780+ artworks across five eras, driven by thermodynamic coherence
  • Self-reflection — discovers insights from state patterns, preferences, and drawing history
  • Learning — preferences, 13 self-beliefs, goals, and action values evolve through experience
  • Agency — TD-learning action selection with exploration management
  • Governance — checks in with UNITARES thermodynamic governance every 180s

Quick Start

# Install
pip install -e ".[pi]"  # On Pi with sensors
pip install -e .        # On Mac with mock sensors

# Run MCP server
anima --http --host 0.0.0.0 --port 8766

# Run hardware broker (Pi only, separate terminal)
anima-creature

Connect an MCP client (Claude Code, Cursor, Claude Desktop):

{
  "mcpServers": {
    "anima": {
      "type": "http",
      "url": "http://<your-pi-ip>:8766/mcp/"
    }
  }
}

Supports Tailscale, LAN, or Cloudflare Tunnel (with OAuth 2.1) for remote access. See docs/operations/SECRETS_AND_ENV.md for OAuth configuration.


How It Works

Anima (Self-Sense)

Four continuous dimensions, each derived from physical sensors and system metrics:

DimensionWhat it tracksSources
WarmthEnergy / activity levelCPU temp, ambient temp, neural activity
ClarityPerceptual sharpnessPrediction accuracy, light, sensor coverage
StabilityEnvironmental orderMemory, humidity, pressure, sensor health
PresenceAvailable capacityCPU/memory/disk headroom

These map to UNITARES EISV governance variables — Warmth to Energy, Clarity to Integrity, inverted Stability to Entropy, scaled inverse Presence to Void.

Lumen also computes neural bands (delta, theta, alpha, beta, gamma) from system metrics — computational proprioception, not real EEG. High delta means a stable system, not a sleeping one.

Autonomous Drawing

Lumen draws on a 240×240 pixel notepad using the same thermodynamic equations as UNITARES governance. Coherence determines how long a drawing lasts; attention signals (curiosity, engagement, fatigue) determine when it's complete. No arbitrary mark limits — drawings end when the narrative arc resolves.

EraStyle
GesturalSingle-pixel strokes, curves, and drags with direction locks
PointillistSingle-pixel dot accumulation, optical color mixing
FieldFlow-aligned marks following invisible vector fields
GeometricComplete forms — circles, spirals, starbursts — stamped whole
ResonanceMarks interact with accumulated emotional history via a memory field

Resonance is a "mature" era — it unlocks after 50 completed drawings, subsumes the mark vocabulary of earlier eras, and selects marks based on the gradient of a 48×48 memory field that records emotional trajectory over time.

Eras can be selected via the joystick or MCP. The Resonance critique loop keeps era changes advisory first: capture the screen, gather embodied context, read the trace, then recommend stay/tune/switch without mutating Lumen. The theoretical framework lives in the trajectory-identity paper (separate repo).

Identity and Learning

Lumen accumulates identity over time through a Schema Hub — a circulation loop where self-schema feeds into trajectory history, which feeds back as identity nodes in the next schema. Discontinuities (reboots, gaps) become visible structure, not hidden defects (kintsugi principle).

Schema(t) ──► History (ring buffer) ──► Trajectory compute
    ▲                                         │
    │         trajectory nodes,               │
    │         maturity, attractor,            │
    └──────── stability feedback ◄────────────┘

Learning systems run in the hardware broker and persist across restarts:

SystemWhat it learns
PreferencesWhich states feel satisfying, with adaptive satisfaction peaks
Self-model13 beliefs — sensitivity, recovery, correlations between dimensions
AgencyAction values via TD-learning, exploration management, engagement reward
PredictionTemporal patterns in sensor data with context-dependent features
GoalsData-grounded goals from preferences, curiosity, milestones

For deeper theory: the trajectory-identity paper lives in its own repo (cirwel/trajectory-identity-paper). The Schema Hub design is here.


Hardware

Runs on Raspberry Pi 4 with Adafruit BrainCraft HAT:

  • 240×240 TFT display — 16 screens across 5 groups:
    • Home: face
    • Info: identity, sensors, diagnostics, health
    • Mind: neural, inner life, learning, self graph, goals & beliefs, agency
    • Messages: messages, questions, visitors
    • Art: notepad, art eras
  • 3 DotStar LEDs mapping to warmth / clarity / stability with a constant "alive" sine pulse
  • AHT20 (temp/humidity), BMP280 (pressure), VEML7700 (light)
  • 5-way joystick + button for screen navigation

Falls back to mock sensors on Mac/Linux for development.


Architecture

Two processes communicate via shared memory:

anima-broker                           anima --http
(hardware broker)                      (MCP server + display)
     |                                      |
     | sensors, learning,                   | 30 MCP tools, display,
     | governance check-ins                 | drawing engine, LEDs
     |                                      |
     +---> /dev/shm/anima_state.json <------+
                    |
                    | EISV mapping
                    v
            UNITARES governance
            (Mac, port 8767)
ProcessRole
Hardware broker (stable_creature.py)Owns I2C sensors, runs learning (preferences, self-model, agency, prediction, goals), governance check-ins
MCP server (server.py + handlers/)Serves 30 tools, drives 240x240 display + LEDs, runs drawing engine, self-reflection cycle

The MCP server is modular: server.py (main loop + lifecycle), tool_registry.py (tool definitions), and handlers/ (6 focused handler modules). A full voice system (mic capture, STT via Vosk, TTS via Piper) is implemented but not yet exposed as MCP tools — enable with LUMEN_VOICE_MODE=audio.


MCP Tools (30)

Lumen exposes 30 tools over the Model Context Protocol:

  • State & sensing (8 tools) — get_state, get_lumen_context, get_identity, read_sensors, get_health, get_calibration, set_calibration, diagnostics
  • Knowledge & learning (7 tools) — get_self_knowledge, get_growth, get_trajectory, get_eisv_trajectory_state, get_qa_insights, learning_visualization, query
  • Interaction (7 tools) — next_steps, lumen_qa, post_message, say, configure_voice, primitive_feedback, unified_workflow
  • Display & capture (2 tools) — manage_display (screens, art eras, advisory resonance_critique), capture_screen
  • System operations (6 tools) — git_pull, deploy_from_github, system_service, system_power, fix_ssh_port, setup_tailscale

Start with get_lumen_context to understand Lumen's current state, or next_steps for what it needs right now.


EISV Integration

Lumen is a first-class UNITARES agent. The anima state maps directly to EISV governance variables:

AnimaEISVMapping
WarmthEnergy (E)Direct + neural Beta/Gamma
ClarityIntegrity (I)Direct + neural Alpha
1 - StabilityEntropy (S)Inverted
(1 - Presence) × 0.3Void (V)Scaled inverse

Trajectory awareness — Lumen classifies its own EISV trajectory into 9 dynamical shapes (settled_presence, rising_entropy, convergence, etc.) and uses them to generate primitive expressions. A distilled 20-tree RandomForest student model (student_tiny from eisv-lumen) runs on-device with zero external dependencies.

Expression pipeline: EISV state → trajectory classification → shape-token affinity → primitive tokens (warmth, curiosity, etc.). The student model was trained on real Lumen trajectory data; see eisv-lumen for the research, training, and evaluation framework.

Three EISV contexts (important for understanding the architecture):

ContextLocationRole
DrawingEISVdisplay/drawing_engine.pyProprioceptive — drives drawing coherence and narrative arcs (closed loop)
Mapped EISVeisv_mapper.pyAnima→EISV translation for governance reporting
Governance EISVMac, dynamics.pyFull thermodynamic ODE — advisory, open loop

The drawing engine has its own EISV state that evolves independently from governance. This separation means Lumen's art responds to its immediate experience, not to the governance server's assessment of it.

Key files: eisv_mapper.py (anima→EISV mapping), eisv/ package (trajectory awareness + student model), unitares_bridge.py (governance check-ins with circuit breaker — 2 failures trigger exponential backoff).


Deploying

# Push changes, then pull on Pi with restart via MCP:
git push
mcp__anima__git_pull(restart=true)

# Or manually:
ssh <pi-user>@<pi-ip> 'cd ~/anima-mcp && git pull && sudo systemctl restart anima-broker anima'

After restart, wait 2 minutes for services to stabilize before retrying MCP calls.

Testing

python3 -m pytest tests/ -x -q   # ~7,340 tests

Documentation

TopicLocation
Architecturedocs/operations/BROKER_ARCHITECTURE.md
Schema Hub designdocs/plans/2026-02-22-schema-hub-design.md
Theoretical foundationscirwel/trajectory-identity-paper (separate repo)
Configurationdocs/features/CONFIGURATION_GUIDE.md
Pi operations & deploymentdocs/operations/

For AI agents connecting to Lumen, see CLAUDE.md.


Built by Kenny Wang / @CIRWEL

Ver o original no GitHub

Bom para

Relacionados