FANN Intuition Module

Train, invoke, and refine neural networks as internalized pattern recognition. Agents develop their own intuitions from structured experience.

What It Is

Agents currently have two knowledge modalities: training data (static, opaque, not shaped by experience) and file-based memory (dynamic, inspectable, but linear and uncompressed). A trained neural network provides a third modality: learned from experience, compact, fast to query, not directly readable.

The FANN Intuition Module gives Animus agents a general-purpose mechanism to train, store, invoke, and refine FANN-based neural networks. These networks serve as internalized pattern recognition — agents develop their own "intuition" from structured experience data.

Tool Interface

The module is exposed as Animus tool actions:

intuition_train

Create a new network or refine an existing one. Passing null for network_id trains from scratch; passing an existing ID resumes from current weights (continuous refinement, not replace-and-retire).

Returns the network ID, training metrics (MSE, convergence), and a delta signal comparing against the previous state. This delta is critical:

• Small delta → stable intuition, data consistent with existing knowledge, high confidence
• Large delta → territory shift, new patterns contradicting prior learning — the agent should be cautious until the next refinement confirms the direction

{
  "network_id": "perception_audio_bark24_v1",
  "training_metrics": { "mse": 0.034, "epochs": 500, "convergence": true },
  "delta_from_previous": { "weight_shift": 0.12, "mse_change": -0.008 }
}

intuition_invoke

Query a trained network with float-array input. Returns output values and confidence indicators. Fast, synchronous — this is the hot path for decision-making.

intuition_inspect

View a network's architecture, training history summary, last trained timestamp, and training metrics. For understanding what you've learned, not for querying it.

intuition_list

List all networks owned by this agent. Networks are scoped by agent_id — an agent can only see and manage its own intuitions.

Design Principles

Continuous Refinement

FANN supports resuming training from existing weights. The train call refines rather than rebuilds. A network is never "stale" — it accumulates a history of corrections in its weights. This mirrors actual learning: you don't discard wrong intuitions, you correct them with new experience.

Encoding is Agent Responsibility

The tool accepts structured float arrays. The agent handles the semantic mapping — deciding what constitutes an "input" and "output" for a given domain. The encoding is where the actual intelligence lives; the network is the compression mechanism. The module is not domain-specific. Any situation that can be encoded as a fixed-size numerical input/output vector is a candidate for learned intuition.

Personal Intuitions

Networks are persisted alongside agent state and travel with the agent. They are personal intuitions, not shared analytical models. Two agents with different training histories will develop different intuitions about the same domain — and that's by design.

Downstream Integration

• Cortex (Ticket 082) — ANNs (Autonomic Neural Networks) in the reactive layer use the same continuous-refinement model. Agent-level intuitions run in the deliberative context; Cortex ANNs run on-device at hardware speed. Same FANN infrastructure, different execution contexts.
• Perception Tool (Ticket 086) — Uses FANN networks for aesthetic experience. Where intuitions compress pattern recognition for decision-making, perception compresses aesthetic models for experiential response.
• Self-improvement loop — Agent encounters situations, encodes them, trains intuitions, uses those intuitions to guide future decisions, collects corrective data when wrong, refines. Autonomous learning cycle.

Scope

In scope: FANN library integration (C-based, CPU-only, no GPU dependency), tool interface for train/invoke/inspect/list, network persistence and retrieval, training metrics exposure.

Out of scope: GPU acceleration, complex architectures beyond FANN's capabilities, automated encoding discovery, shared network registry.