API reference · 14 endpoints

Memory

Commit, search, and illuminate, plus memory listing, decisions, tags, and the knowledge graph.

POST/v1/default/namespaces/{namespace_id}/memories

Commit memories

Commit memory items with automatic fact extraction.

This is the main endpoint for storing memories.

Features:

  • Efficient batch processing
  • Automatic fact extraction from natural language
  • Entity recognition and linking
  • Document tracking with automatic upsert (when document_id is provided)
  • Temporal and semantic linking

The system automatically:

  1. Extracts semantic facts from the content
  2. Generates embeddings
  3. Deduplicates similar facts
  4. Creates temporal, semantic, and entity links
  5. Tracks document metadata

Processing is asynchronous. The response carries an operation_id; poll GET /v1/default/namespaces/{namespace_id}/operations/{operation_id} to know when the facts are searchable. The async field is accepted for compatibility and ignored.

Note: If a memory item has a document_id that already exists, the old document and its memory units will be deleted before creating new ones (upsert behavior).

Parameters

namespace_idstringpathrequired

Request body · application/json

itemsMemoryItem[]required
contentstringrequired
timestampstring (date-time) | string

When the content occurred. Accepts an ISO 8601 datetime string (e.g. '2024-01-15T10:30:00Z'), null/omitted (defaults to now), or the special string 'unset' to explicitly store without any timestamp (use this for timeless content such as fictional documents or static reference material).

contextstring | null
metadatamap<string, string>
document_idstring | null

Optional document ID for this memory item.

entitiesEntityInput[]

Optional entities to combine with auto-extracted entities.

textstringrequired

The entity name/text

typestring | null

Optional entity type (e.g., 'PERSON', 'ORG', 'CONCEPT')

tagsstring[]

Optional tags for visibility scoping. Memories with tags can be filtered during search.

signal_scopes"per_tag" | "combined" | "all_combinations" | string[][]

How to scope signals during consolidation. 'per_tag' runs one consolidation pass per individual tag, creating separate signals for each tag. 'combined' (default) runs a single pass with all tags together. A list of tag lists runs one pass per inner list, giving full control over which combinations to use.

strategystring | null

Named commit strategy for this item. Overrides the namespace's default strategy for this item only. Strategies are defined in the namespace config under 'commit_strategies'.

update_mode"replace" | "append"

How to handle an existing document with the same document_id. 'replace' (default) deletes old data and reprocesses from scratch. 'append' concatenates new content to the existing document text and reprocesses.

fact_type"knowledge" | "experience" | "decision"

Optional fact-type override: every fact extracted from this item is stored with this type ('knowledge', 'experience', or 'decision', never 'signal'). The deterministic "record this decision" path; omit to let the LLM classify.

asyncbooleandeprecateddefault false

Ignored; commit is always asynchronous. Poll the returned operation_id via GET /v1/default/namespaces/{namespace_id}/operations.

document_tagsstring[]deprecated

Deprecated. Use item-level tags instead.

curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/memories" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "content": "Ada shipped the payments rewrite in Q3 2025."
    }
  ]
}'
Response · 200
{
  "async": false,
  "namespace_id": "user123",
  "items_count": 2,
  "success": true,
  "usage": {
    "input_tokens": 500,
    "output_tokens": 100,
    "total_tokens": 600
  }
}

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

POST/v1/default/namespaces/{namespace_id}/memories/search

Search memory

Search memory using semantic similarity and spreading activation.

types is optional; each entry must be one of:

  • knowledge: General knowledge about people, places, events, and things that happen
  • experience: Memories about experience, conversations, actions taken, and tasks performed
  • signal: Consolidated patterns, preferences, and lessons drawn from accumulated evidence
  • decision: Durable commitments and choices

Omit types to search all four.

Parameters

namespace_idstringpathrequired

Request body · application/json

querystringrequired
typesstring[]

List of fact types to search: 'knowledge', 'experience', 'signal', 'decision'. Defaults to knowledge, experience, signal, and decision if not specified on the public search endpoint.

budgetBudgetdefault "mid"

Budget levels for search/illuminate operations.

max_tokensintegerdefault 4096
tracebooleandefault false
query_timestampstring | null

ISO format date string (e.g., '2023-05-30T23:40:00'). Used as the query-time anchor for relative temporal expressions and recency scoring.

includeIncludeOptionsdefault {}

Options for including additional data (entities are included by default)

entitiesEntityIncludeOptionsdefault {"max_tokens":500}

Include entity signals. Set to null to disable entity inclusion.

max_tokensintegerdefault 500

Ignored. Search returns entity names and ids only, so there are no entity signal tokens to budget.

chunksChunkIncludeOptions

Include raw chunks. Set to {} to enable, null to disable (default: disabled).

max_tokensintegerdefault 8192

Maximum tokens for chunks (chunks may be truncated)

source_factsSourceFactsIncludeOptions

Include source facts for signal-type results. Set to {} to enable, null to disable (default: disabled).

max_tokensintegerdefault 4096

Maximum total tokens for source facts across all signals (-1 = unlimited)

max_tokens_per_signalintegerdefault -1

Maximum tokens of source facts per signal (-1 = unlimited)

tagsstring[]

Filter memories by tags. If not specified, all memories are returned.

tags_match"any" | "all" | "any_strict" | "all_strict"default "any"

How to match tags: 'any' (OR, includes untagged), 'all' (AND, includes untagged), 'any_strict' (OR, excludes untagged), 'all_strict' (AND, excludes untagged).

tag_groupsTagGroupLeaf | TagGroupAnd | TagGroupOr | TagGroupNot[]

Compound tag filter using boolean groups. Groups in the list are AND-ed. Each group is a leaf {tags, match} or compound {and: [...]}, {or: [...]}, {not: ...}.

tagsstring[]required
match"any" | "all" | "any_strict" | "all_strict"default "any_strict"
as_ofstring | null

Decision time-travel: ISO timestamp (same forms as query_timestamp). Decision results resolve their supersession chain to the node standing as of this time; non-decision results are untouched.

include_invalidatedbooleandefault false

Return facts whose validity interval has closed (superseded or contradicted) alongside the standing ones. Inert unless the namespace has enable_validity_filter on, since nothing is dropped otherwise.

entity_classstring | null

Restrict the graph retrieval arm's entity expansion to entities of this ontology class (case-insensitive name). Other arms are unaffected.

curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/memories/search" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "who shipped payments?",
  "budget": "mid",
  "max_tokens": 2048
}'
Response · 200
{
  "chunks": {
    "456e7890-e12b-34d5-a678-901234567890": {
      "chunk_index": 0,
      "id": "456e7890-e12b-34d5-a678-901234567890",
      "text": "Alice works at Google on the AI team. She's been there for 3 years..."
    }
  },
  "entities": {
    "Alice": {
      "canonical_name": "Alice",
      "entity_id": "123e4567-e89b-12d3-a456-426614174001",
      "signals": []
    }
  },
  "results": [
    {
      "chunk_id": "456e7890-e12b-34d5-a678-901234567890",
      "context": "work info",
      "entities": [
        "Alice",
        "Google"
      ],
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "occurred_end": "2024-01-15T10:30:00Z",
      "occurred_start": "2024-01-15T10:30:00Z",
      "text": "Alice works at Google on the AI team",
      "type": "knowledge"
    }
  ],
  "trace": {
    "num_results": 1,
    "query": "What did Alice say about machine learning?",
    "time_seconds": 0.123
  }
}

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

POST/v1/default/namespaces/{namespace_id}/illuminate

Illuminate and generate answer

Illuminate and formulate an answer using namespace identity, knowledge, and synthesized signals.

This endpoint:

  1. Retrieves experiences (conversations and events)
  2. Retrieves knowledge relevant to the query
  3. Retrieves signals synthesized by consolidation
  4. Uses LLM to formulate a contextual answer
  5. Returns plain text answer and the facts used

Parameters

namespace_idstringpathrequired

Request body · application/json

querystringrequired
budgetBudgetdefault "low"

Budget levels for search/illuminate operations.

contextstring | null

Extra context for this conclusion. It is injected as an 'Additional Context' section of the agent's system prompt, not appended to the query, and is capped at 4000 tokens.

max_tokensintegerdefault 4096

Maximum tokens for the response

includeIlluminateIncludeOptions

Options for including additional data (disabled by default)

factsFactsIncludeOptions

Include facts that the answer is based on. Set to {} to enable, null to disable (default: disabled).

tool_callsToolCallsIncludeOptions

Include tool calls trace. Set to {} for full trace (input+output), {output: false} for inputs only.

outputbooleandefault true

Include tool outputs in the trace. Set to false to only include inputs (smaller payload).

response_schemaobject | null

Optional JSON Schema for structured output. When provided, the response will include a 'structured_output' field with the LLM response parsed according to this schema.

tagsstring[]

Filter memories by tags during conclusion. If not specified, all memories are considered.

tags_match"any" | "all" | "any_strict" | "all_strict"default "any"

How to match tags: 'any' (OR, includes untagged), 'all' (AND, includes untagged), 'any_strict' (OR, excludes untagged), 'all_strict' (AND, excludes untagged).

tag_groupsTagGroupLeaf | TagGroupAnd | TagGroupOr | TagGroupNot[]

Compound tag filter using boolean groups. Groups in the list are AND-ed. Each group is a leaf {tags, match} or compound {and: [...]}, {or: [...]}, {not: ...}.

tagsstring[]required
match"any" | "all" | "any_strict" | "all_strict"default "any_strict"
fact_types"knowledge" | "experience" | "signal" | "decision" | "procedure"[]

Filter which fact types are retrieved during illuminate. None means all types (knowledge, experience, signal, decision).

exclude_automationsbooleandefault false

If true, exclude all automations from the illuminate loop (skip search_automations tool).

exclude_automation_idsstring[]

Exclude specific automations by ID from the illuminate loop.

llm_output_languagestring | null

Language the answer must be written in (e.g. 'en', 'fr'). Overrides the namespace's llm_output_language config; when neither is set the answer follows the language of the query.

curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/illuminate" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "summarize Ada'\''s recent work",
  "budget": "low",
  "max_tokens": 512
}'
Response · 200
{
  "based_on": {
    "memories": [
      {
        "id": "123",
        "text": "AI is used in healthcare",
        "type": "knowledge"
      },
      {
        "id": "456",
        "text": "I discussed AI applications last week",
        "type": "experience"
      }
    ]
  },
  "structured_output": {
    "key_points": [
      "Used in healthcare",
      "Discussed recently"
    ],
    "summary": "AI is transformative"
  },
  "text": "## AI Overview\n\nBased on my understanding, AI is a **transformative technology**:\n\n- Used extensively in healthcare\n- Discussed in recent conversations\n- Continues to evolve rapidly",
  "trace": {
    "llm_calls": [
      {
        "duration_ms": 1200,
        "scope": "agent_1"
      }
    ],
    "signals": [
      {
        "id": "obs-1",
        "name": "AI Technology",
        "subtype": "structural",
        "type": "concept"
      }
    ],
    "tool_calls": [
      {
        "duration_ms": 150,
        "input": {
          "query": "AI"
        },
        "tool": "search"
      }
    ]
  },
  "usage": {
    "input_tokens": 1500,
    "output_tokens": 500,
    "total_tokens": 2000
  }
}

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

GET/v1/default/namespaces/{namespace_id}/memories/list

List memory units

List memory units with pagination and optional full-text search. Supports filtering by type. Results are sorted by most recent first (mentioned_at DESC, then created_at DESC).

Parameters

namespace_idstringpathrequired
type"knowledge" | "experience" | "signal" | "decision" | "procedure"query
qstring | nullquery
consolidation_statestring | nullquery
status"standing" | "superseded"query
order"asc" | "desc"query
sincestring (date-time) | nullquery
untilstring (date-time) | nullquery
limitintegerquery
offsetintegerquery
curl -X GET "https://api.illumina.sh/v1/default/namespaces/demo/memories/list" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
Response · 200
{
  "items": [
    {
      "context": "Work conversation",
      "date": "2024-01-15T10:30:00Z",
      "entities": "Alice (PERSON), Google (ORGANIZATION)",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "text": "Alice works at Google on the AI team",
      "type": "knowledge"
    }
  ],
  "limit": 100,
  "offset": 0,
  "total": 150
}

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

GET/v1/default/namespaces/{namespace_id}/memories/{memory_id}

Get memory unit

Get a single memory unit by ID with all its metadata including entities and tags. Note: the 'history' field is deprecated and always returns an empty list - use GET /memories/{memory_id}/history instead.

Parameters

namespace_idstringpathrequired
memory_idstringpathrequired
curl -X GET "https://api.illumina.sh/v1/default/namespaces/demo/memories/mem_123" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
Response · 200
null

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

DELETE/v1/default/namespaces/{namespace_id}/memories

Clear memory namespace memories

Delete memory units for a memory namespace. Optionally filter by type (knowledge, experience, signal, decision) to delete only specific types. This is a destructive operation that cannot be undone. The namespace profile (disposition and background) will be preserved.

Parameters

namespace_idstringpathrequired
typestring | nullquery

Optional fact type filter (knowledge, experience, signal, decision)

curl -X DELETE "https://api.illumina.sh/v1/default/namespaces/demo/memories" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
Response · 200
{
  "deleted_count": 10,
  "message": "Deleted successfully",
  "success": true
}

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

GET/v1/default/namespaces/{namespace_id}/tags

List tags

List all unique tags in a memory namespace with usage counts. Supports wildcard search using '' (e.g., 'user:', '-fred', 'tag-2'). Case-insensitive. Use source=automations to list tags used on automations instead of memories.

Parameters

namespace_idstringpathrequired
qstring | nullquery

Wildcard pattern to filter tags (e.g., 'user:*' for user:alice, '*-admin' for role-admin). Use '*' as wildcard. Case-insensitive.

source"memories" | "automations"query

Where to read tags from: 'memories' (memory_units, default) or 'automations'.

limitintegerquery

Maximum number of tags to return

offsetintegerquery

Offset for pagination

curl -X GET "https://api.illumina.sh/v1/default/namespaces/demo/tags" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
Response · 200
{
  "items": [
    {
      "count": 42,
      "tag": "user:alice"
    },
    {
      "count": 15,
      "tag": "user:bob"
    },
    {
      "count": 8,
      "tag": "session:abc123"
    }
  ],
  "limit": 100,
  "offset": 0,
  "total": 25
}

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

GET/v1/default/namespaces/{namespace_id}/graph

Get memory graph data

Retrieve graph data for visualization, optionally filtered by type (knowledge/experience/signal/decision).

Parameters

namespace_idstringpathrequired
typestring | nullquery
limitintegerquery
qstring | nullquery
tagsstring[]query
tags_matchstringquery
document_idstring | nullquery
chunk_idstring | nullquery
curl -X GET "https://api.illumina.sh/v1/default/namespaces/demo/graph" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
Response · 200
{
  "edges": [
    {
      "from": "1",
      "to": "2",
      "type": "semantic",
      "weight": 0.8
    }
  ],
  "limit": 1000,
  "nodes": [
    {
      "id": "1",
      "label": "Alice works at Google",
      "type": "knowledge"
    },
    {
      "id": "2",
      "label": "Bob went hiking",
      "type": "knowledge"
    }
  ],
  "table_rows": [
    {
      "context": "Work info",
      "date": "2024-01-15 10:30",
      "entities": "Alice (PERSON), Google (ORGANIZATION)",
      "id": "abc12345...",
      "text": "Alice works at Google"
    }
  ],
  "total_units": 2
}

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

POST/v1/default/namespaces/{namespace_id}/decisions/reconcile

Reconcile standing decisions

On-demand sweep pairing the namespace's standing decisions and marking supersessions commit-time detection missed. Capped per invocation; repeated calls converge. Billable LLM pairing.

Parameters

namespace_idstringpathrequired
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/decisions/reconcile" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
Response · 200
null

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

POST/v1/default/namespaces/{namespace_id}/memories/{memory_id}/supersede

Supersede a decision

Manually mark a standing decision as superseded by another standing decision. Writes the same supersedes link, metadata, and history event as commit-time detection, with source "manual".

Parameters

namespace_idstringpathrequired
memory_idstringpathrequired

Request body · application/json

superseded_bystring (uuid)required

Id of the standing decision that replaces this one.

curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/memories/mem_123/supersede" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "superseded_by": "8b9e2f0a-4c1d-4e5f-9a2b-3c4d5e6f7a8b"
}'
Response · 200
null

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

DELETE/v1/default/namespaces/{namespace_id}/memories/{memory_id}/supersede

Revive a decision

Undo a supersession: restore the decision to standing (lifecycle metadata keys are removed), delete the incoming supersedes link, and append a revived history event.

Parameters

namespace_idstringpathrequired
memory_idstringpathrequired
curl -X DELETE "https://api.illumina.sh/v1/default/namespaces/demo/memories/mem_123/supersede" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
Response · 200
null

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

GET/v1/default/namespaces/{namespace_id}/memories/{memory_id}/lineage

Get decision lineage

Walk the supersession chain through a memory unit, both directions, returning the ordered chain (newest first), the standing head, and optionally which decision was standing at as_of.

Parameters

namespace_idstringpathrequired
memory_idstringpathrequired
as_ofstring (date-time) | nullquery
curl -X GET "https://api.illumina.sh/v1/default/namespaces/demo/memories/mem_123/lineage" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
Response · 200
null

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

GET/v1/default/namespaces/{namespace_id}/memories/{memory_id}/history

Get signal history

Get the full history of a signal, with each change's source facts resolved to their text.

Parameters

namespace_idstringpathrequired
memory_idstringpathrequired
curl -X GET "https://api.illumina.sh/v1/default/namespaces/demo/memories/mem_123/history" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
Response · 200
null

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

DELETE/v1/default/namespaces/{namespace_id}/memories/{memory_id}/signals

Clear signals for a memory

Delete all signals derived from a specific memory and reset it for re-consolidation. The memory itself is not deleted. A consolidation job is triggered automatically so the memory will produce fresh signals on the next consolidation run.

Parameters

namespace_idstringpathrequired
memory_idstringpathrequired
curl -X DELETE "https://api.illumina.sh/v1/default/namespaces/demo/memories/mem_123/signals" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
Response · 200
{
  "deleted_count": 3
}

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

Search docs

Search the documentation