Embeddings

Embeddings power stored-memory recall and guide relevance. Configure a provider before connecting a real Agent so Aionis can retrieve facts, execution evidence, procedures, and source spans before governance compiles the final context.

First-run Provider


export EMBEDDING_PROVIDER="openai"
export OPENAI_API_KEY="your-openai-key"

MiniMax is also supported:


export EMBEDDING_PROVIDER="minimax"
export MINIMAX_API_KEY="your-minimax-key"

The guided installer asks for this during setup:


npx aionis setup

Operational Notes

Topic	Guidance
Provider choice	Better embeddings can improve candidate recall, especially for ordinary facts and long context.
Query vs document shape	Some providers distinguish query and document embeddings. Use the supported Runtime configuration.
Failures	Check provider API key, network access, and rate limits.
Cost	Embedding cost is usually lower than Agent LLM cost, but high write volume should still be measured.
Substrate	Add Substrate when you want stronger factual recall, durable evidence search, backup, or migration.

The Memory Firewall and Execution Memory layers still matter even with strong embeddings. Embeddings find related content; Aionis decides whether it is safe to use.

Recall Evidence

In the v0.3 MemoryData verification snapshot, adding Substrate to the Runtime guide path improved factual recall:

Metric	Runtime baseline	Runtime + Substrate
Exact answer hit	43/50	48/50
Evidence coverage	47/50	50/50
Substrate source trace	-	50/50

This is the intended layering: stronger candidate retrieval below, Aionis admission and receipt above.