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.
Hardware RNG via RTL-SDR. Extracts true random from ADC quantization noise. Serves entropy over HTTP for dream cycles and identity casting.
Embedding service. Converts text to 768d vectors (gtr-t5-base) and inverts vectors back to text (vec2text). Required for remember, recall, reflect, and observe.
docker pull gcr.io/gnosis-459403/shivvr
docker run -d --name shivvr -p 8080:8080 \
gcr.io/gnosis-459403/shivvrVerify: curl localhost:8080/health
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.
Ingest
Text arrives via remember, reflect, or observe. The text is sent to the embedding service (shivvr) 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.
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.
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.
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.
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.
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.
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.
effective_α = base_α / (1 + log(depth))
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_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.
Decay only. No archetype activation. The thermodynamic minimum — memories still lose fidelity but no agents intervene. This is the engine in sleep mode.
Decay plus two archetypes. Intuition suggests connections. Fortune evaluates timing. The engine is dreaming lightly — making associations but not restructuring.
All five archetypes active. Full dream cycle with consolidation, graph pruning, and keystone review. The engine is fully conscious — restructuring memory architecture.
Intuition
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.
Fortune
Evaluates whether a memory should be reinforced or released based on context timing. Considers staleness, recall frequency, and the current entropy state. Second to wake after Intuition.
Craft
Manages the physical structure of the memory store. Drives consolidation — merging similar memories into stronger composites. Handles term index maintenance and graph edge weights. Only active at full entropy.
Ethics
Guards the lifecycle rules. Ensures one-way state transitions. Reviews keystones for relevance — nothing is immortal without justification. Prevents memory hoarding and enforces the fidelity gate. Only active at full entropy.
Advocate
Manages the offering protocol — sharing memories between agents. Handles encryption transforms for inter-agent transfer. Decides what to share and what to keep private. Only active at full entropy.
Identity Cast
Each archetype gets 6 entropy bytes offset by its role index. Those bytes cast a hexagram via yarrow stalk probabilities. The hexagram's upper and lower trigrams map to primary and secondary emotions. The horoscope is derived from the creation epoch. Every agent instance is unique.
Tools
Ferricula exposes two tool surfaces via MCP (Model Context Protocol). The cognitive surface is what your LLM agent uses — remember, recall, reflect, observe. The system surface is for internal operations — dream cycles, keystone management, raw queries. You control which surface is exposed via the FERRICULA_SURFACE environment variable.
What the LLM agent sees. Ten tools for thinking, remembering, and introspecting. No system access. No raw queries. The agent thinks, it doesn't administrate.
Store a memory. Text is embedded automatically via shivvr. Vectors are never exposed to the LLM.
Search memories by text. Returns reconstructed text with fidelity, emotion, and channel. Each recalled memory gets strengthened.
Working memory with faster decay (α=0.015). Thoughts are transient unless reinforced by recall.
File observation. Always keystoned — immune to decay. Reference material that persists.
View a memory's text, fidelity, emotion, decay rate, and graph neighbors. Never shows raw vectors.
Create a graph edge between two memories. kind: “semantic” (bidirectional, default) or “causal” (directed a→b only — enforces the arrow of time).
Browse graph connections for a memory. Shows edge labels, weights, directionality (↔ or →), and neighbor fidelity. Causal predecessors listed separately.
Aggregate stats: row count, active/forgiven/archived counts, graph size, term count.
Check if ferricula and shivvr (embedding service) are reachable and functioning.
The agent's identity: hexagram, zodiac, emotions, and all five archetypes.
Internal operations. What the archetypes and system clock use. Dream cycles, checkpoints, raw SQL, entropy injection. Not exposed to the LLM by default.
Run a full dream cycle: decay, forgive, consolidate, neglect, review, prune. Returns a report.
Toggle decay immunity on a memory. Keystones never lose fidelity.
Flush the write-ahead log to a V2 snapshot. Durability guarantee.
Inject entropy from radio or hex string. Triggers a dream cycle scaled by entropy volume.
Semantic fidelity audit. Inverts a memory's vector via vec2text and compares with original text.
List all terms in the prime tree with member counts.
Raw SQL against the store. SELECT, WHERE, AND/OR, UNION/INTERSECT/EXCEPT, vector_topk_cosine.
Remove a graph edge between two memories.
Clock telemetry: ticks, dreams, entropy lifetime, reservoir status, radio connection.
FERRICULA_SURFACE=all (default) registers both surfaces. Use this for development and operator access. 19 tools total.
Query Language
Ferricula uses a SQL subset for memory queries. You can write raw SQL via the query tool, or just type natural language — the built-in query planner rewrites it for you. When AGENT_KEY is set, an AI agent (Claude Haiku) translates freeform questions into executable SQL. Without a key, rule-based rewriting handles common patterns.
All queries run against a single virtual table.
SELECT id FROM docs WHERE ...Filter by any tag field stored with the memory.
SELECT id FROM docs WHERE channel = 'hearing'
SELECT id FROM docs WHERE type = 'identity_anchor'
SELECT id FROM docs WHERE channel = 'seeing' AND type = 'file'AND, OR, NOTCombine two queries using bitmap set algebra.
SELECT id FROM docs WHERE channel = 'hearing'
INTERSECT
SELECT id FROM docs WHERE type = 'file'
UNION, INTERSECT, EXCEPTTop-k nearest neighbors. Three distance metrics. Vector is a bracketed float array.
vector_topk_cosine('[0.1,0.2,...]', 10)
vector_topk_l2('[0.1,0.2,...]', 5)
vector_topk_jaccard('[0.1,0.2,...]', 10)The planner sits between you and the SQL engine. It accepts freeform text and rewrites it into executable SQL. Two modes, automatic fallback.
When AGENT_KEY is set, freeform queries are sent to Claude Haiku for rewriting. The LLM knows the full SQL syntax and translates natural language into precise queries.
"memories about electromagnetism from last week"
↓
SELECT id FROM docs WHERE
vector_topk_cosine('[...]', 10)
AND channel = 'hearing'Without a key (or if the LLM fails), pattern matching handles common cases:
recall tool on the cognitive surface handles vector embedding automatically — your text is embedded via shivvr and searched as a cosine top-k query. The query tool on the system surface is for raw SQL when you need precise control.
Query Writer
Describe what you want to find. Returns ferricula SQL.
Configuration
Ferricula runs as a Docker container. Configuration is via environment variables, either passed at runtime or loaded from a .env file in the container's working directory.
Claude Code Auto-Setup
Paste this prompt into Claude Code. It will install ferricula, download the MCP tools, and register them.
1. Check that Docker is installed (`docker --version`). If not, tell me to install Docker first.
2. Pull and start ferricula: `docker run -d --name ferricula -p 8765:8765 -v ferricula-data:/data kord/ferricula`
3. Verify it's running: `curl -s http://localhost:8765/status`
4. Download the MCP tool: `curl -sL https://ferricula.com/tools/ferricula-mcp.py -o tools/ferricula-mcp.py`
5. Install the MCP Python dependency: `pip install mcp`
6. Register in .mcp.json with FERRICULA_SURFACE=cognitive and FERRICULA_URL=http://localhost:8765
The AGENT_KEY environment variable gives ferricula access to the Anthropic API. When set, freeform text queries are rewritten into executable SQL by a fast LLM (Claude Haiku). Without it, queries fall back to rule-based pattern matching.
-e AGENT_KEY=sk-ant-api03-... \
-v ferricula-data:/data \
kord/ferricula
AGENT_KEY=sk-ant-api03-...
CHONK_URL=http://localhost:8080
RADIO_URL=http://localhost:9080
Ferricula loads .env from its working directory or the binary's parent directory. Environment variables always take precedence.
The planner sends freeform recall queries to Claude Haiku which rewrites them into ferricula SQL. This means recall "memories about testing" becomes SELECT id FROM docs WHERE text = 'testing' or a vector search. Without the key, the planner uses simple pattern matching (tag equality, vector literals).
Anthropic API key. Enables LLM-powered query rewriting.
Embedding service (shivvr). Required for remember/recall/reflect/observe. Runs as a separate container.
SDR entropy source (gnosis-radio). Optional. Without it, dreams are clock-triggered only.
Seconds between clock ticks. Each tick polls radio and accumulates entropy.
Entropy bytes needed to trigger a dream. Lower = more frequent dreams.
MCP tool surface: cognitive, system, or all.
Add ferricula to your Claude Code or any MCP-compatible client:
"mcpServers": {
"ferricula": {
"type": "stdio",
"command": "python",
"args": ["tools/ferricula-mcp.py"],
"env": {
"FERRICULA_SURFACE": "cognitive",
"FERRICULA_URL": "http://localhost:8765",
"CHONK_URL": "http://localhost:8080"
}
}
}
}
MCP tool available at ferricula.com/tools/ferricula-mcp.py
Q&A
Where does ferricula store data? +
checkpoint flushes the WAL to a snapshot. There is no external database. For an agent with 50K active memories, the total footprint is roughly 150–200 MB.
Does it need sharding or clustering? +
Is ferricula open source? +
ferricula-mcp.py) is provided for integration but the engine itself is proprietary.