Ferricula | Documentation

Documentation

How Memory Lives.

Ferricula is a memory engine for AI agents. Text goes in, gets embedded into vectors, wrapped in a thermodynamic envelope, and placed on a manifold where it decays unless reinforced. This page explains the full processing lifecycle, the agents that manage it, and how to configure it.

Required Services

gnosis-radio

SDR entropy source. Marine VHF monitor that harvests FM noise as entropy for dream cycles and identity casting.

$19.95

one-time license

gnosis-chunk

Embedding service. Converts text to 768d vectors (gtr-t5-base) and inverts vectors back to text (vec2text). Required for remember, recall, reflect, and observe.

required

separate container

Memory Lifecycle

Every memory follows a one-way path. It enters as Active, decays over time, gets forgiven when text is no longer recoverable, and eventually archives. At each stage, different operations are available. The lifecycle is irreversible — there are no undo buttons, only new memories created from old seeds.

Processing Flow

Ingest

Text arrives via remember, reflect, or observe. The text is sent to the embedding service (chonk) which returns a 768-dimensional vector. The vector and a truncated text tag are stored together. A thermodynamic envelope wraps the raw data: fidelity starts at 1.0, decay alpha is set by the sensory channel, and the memory enters the Active state.

Hearing

α = 0.010

External input

Seeing

α = 0.010

Keystoned by default

Thinking

α = 0.015

Faster decay

ACT

Active

Full text and vector available. Searchable by cosine similarity and tag match. Fidelity decays each dream cycle: f(t) = f(t-1) × exp(-α). Recall resets the staleness clock and shrinks alpha by 5% — used memories decay slower. Neglected memories have alpha grow by 0.5% per cycle. Keystones are immune to decay entirely.

Recall → shrinks α, resets staleness

Neglect → grows α

Keystone → immune to decay

DRM

Dream Cycle

Triggered by entropy accumulation. Six phases in sequence: Decay ticks fidelity down. Forgive transitions memories below the 0.75 fidelity gate. Consolidate merges similar memories into fidelity-weighted centroids. Neglect grows alpha on stale memories. Review checks keystones for relevance. Prune removes archived husks.

1. decay_tick 2. forgive 3. consolidate 4. neglect 5. review 6. prune

FGV

Forgiven

Fidelity dropped below 0.75. The text is discarded — the original words are gone. But the vector seed survives. The inversion pipeline (vec2text) can reconstruct an approximation of what the memory said. The memory is no longer searched by default. It exists as a ghost — a direction in embedding space without words.

ARC

Archived

Cold storage. The vector still exists but the memory is dormant. Can be revived — but revival creates a new Active memory from the archived seed. The original is never resurrected. This preserves the one-way thermodynamic guarantee: entropy only increases.

DEL

Pruned

Gone. The row is deleted from the engine. The bitmap entry is cleared. The graph edges are removed. The prime tree term memberships are cleaned up. Nothing survives. This is the thermodynamic floor.

// Consolidation

During dreams, similar active memories are clustered by cosine similarity. Groups of 3+ above the similarity threshold merge into a single memory at the fidelity-weighted centroid. The consolidated memory inherits the highest fidelity, records its source IDs in provenance metadata, and increments its consolidation depth. Deeper consolidation reduces the effective decay rate — importance emerges from survival.

centroid = ∑(v_i × fidelity_i) / ∑(fidelity_i)
effective_α = base_α / (1 + log(depth))

// Adaptive Decay

The decay rate is not fixed. It adapts to how the memory is used. Recall shrinks alpha by 5% (memory becomes more durable). Neglect grows alpha by 0.5% per cycle (memory fades faster). Consolidation depth provides a logarithmic floor. The bounds are hard: minimum 0.001, maximum 0.02. A memory that is recalled frequently and consolidated deeply approaches immortality without being keystoned.

on_recall: α ×= 0.95
on_neglect: α ×= 1.005
bounds: 0.001 ≤ α ≤ 0.02

Agents

At creation, ferricula casts an I Ching hexagram from entropy bytes. That hexagram seeds an identity: emotion profile, zodiac sign, ECC keypair, and five archetype sub-agents. Each archetype has its own hexagram, its own emotional signature, and a distinct role in memory management. They activate based on entropy intensity — low entropy wakes fewer agents.

Entropy-Gated Activation

Minimal (< 0.25)

Decay only. No archetype activation. The thermodynamic minimum — memories still lose fidelity but no agents intervene. This is the engine in sleep mode.

Active agents: none

Moderate (0.25–0.75)

Decay plus two archetypes. Intuition suggests connections. Fortune evaluates timing. The engine is dreaming lightly — making associations but not restructuring.

Active: Intuition, Fortune

Full (≥ 0.75)

All five archetypes active. Full dream cycle with consolidation, graph pruning, and keystone review. The engine is fully conscious — restructuring memory architecture.

Active: all five

Intuition

pattern recognition

Identifies latent connections between memories. Suggests graph edges based on semantic proximity and temporal co-occurrence. Wakes at moderate entropy — the first voice in a light dream.