Retain

POST /memories writes memory into a namespace. You send raw content; Illumina extracts the structure.

What happens on retain

1. Fact extraction — the content is decomposed into discrete semantic facts using an LLM with forced tool-use.
2. Entity recognition — people, systems, and concepts are extracted and linked to existing entities in the namespace.
3. Embedding — each fact is embedded for semantic retrieval.
4. Deduplication — near-duplicate facts merge instead of accumulating.
5. Linking — temporal, semantic, and entity links connect the new facts into the namespace's knowledge graph.

Retain is asynchronous: the response carries an operation_id you can track on the operations API. A duplicate retain of the same content collapses onto the in-flight operation, so retries are safe.

Shaping what gets retained

Each item accepts more than content:

• timestamp — when the fact happened (defaults to now). Drives temporal recall and recency scoring.
• context — a short hint about the setting ("standup", "support ticket").
• document_id — groups items into a document. Retaining the same document_id again upserts: old facts from that document are replaced (or appended, with update_mode: "append").
• tags — labels for filtering recall and reflect later.
• metadata — arbitrary string key-values carried on the memory.
• fact_type — force world, experience, or decision instead of LLM classification. See Fact types.
• entities — pre-extracted entities to link explicitly.

Files

POST /files/retain accepts uploads (PDF, DOCX, PPTX, XLSX, HTML, images). Documents are parsed — with OCR for scanned pages and images — chunked, and retained through the same extraction pipeline. Namespace directives and retain configuration apply to file content the same way they apply to text.

Steering extraction

Per-namespace configuration sets a retain mission, extraction mode, custom instructions, and chunk size. Directives add standing instructions that bias what extraction keeps and how it phrases facts.