Features

1. Five-Tier Memory System

All conversational data is routed into five specialized memory tiers, each backed by its own SQLite table. ironclad-db/src/memory.rs

The MemoryBudgetManager in ironclad-agent/src/memory.rs allocates a configurable percentage of the total token budget to each tier (default: 30/25/20/15/10).

2. Full-Text Search

Working, episodic, and semantic tiers all feed into an FTS5 virtual table (memory_fts). The fts_search() function queries across all three tiers with a sanitized MATCH query, plus a LIKE fallback for procedural and relationship tables. This is the keyword-based leg of the retrieval pipeline.

ironclad-db/src/memory.rs

3. Embedding Store & Vector Search

Embeddings are stored as JSON-serialized Vec<f32> in an embeddings table. The search_similar() function does a brute-force scan computing cosine similarity against every stored embedding, filtering by a min_similarity threshold and returning the top-k results.

ironclad-db/src/embeddings.rs

4. Hybrid Search — The RAG Retrieval Path

hybrid_search() combines both legs:

• ▸FTS5 keyword match — scores are positional (rank-decayed) and weighted by (1 - hybrid_weight)
• ▸Vector cosine similarity — scores are weighted by hybrid_weight

Results from both are merged, re-sorted by combined score, and truncated to the limit. The hybrid_weight parameter (default 0.5, configurable in MemoryConfig) controls the balance.

ironclad-db/src/embeddings.rs

5. Semantic Cache

The SemanticCache operates at the LLM request layer with three lookup levels:

• L1Exact hash — SHA-256 of the prompt text, instant match
• L2Semantic similarity — character n-gram embeddings + cosine similarity (threshold 0.85)
• L3Tool-aware TTL — shorter TTL for tool-involving responses (1/4 of normal)

This avoids redundant LLM calls for semantically equivalent prompts.

ironclad-llm/src/cache.rs

6. Context Assembly

The build_context() function packs the final prompt within a token budget determined by query complexity (L0=2k, L1=4k, L2=8k, L3=16k tokens). It fills the context window in priority order: system prompt, then retrieved memories (the RAG output), then conversation history (newest first, truncated when budget exhausts). When context exceeds 80% capacity, soft_trim evicts oldest non-system messages and build_compaction_prompt can generate a summary for insertion.

ironclad-agent/src/context.rs

7. Post-Turn Ingestion

After each turn, ingest_turn() classifies the exchange (tool use, financial, social, creative, reasoning) and routes content into the appropriate memory tiers automatically, so future RAG queries have fresh material to retrieve.

ironclad-agent/src/memory.rs