API reference · 14 endpoints

Memory

Retain, recall, and reflect — plus memory listing, decisions, tags, and the knowledge graph.

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

Retain memories

Retain memory items with automatic fact extraction.

This is the main endpoint for storing memories. It supports both synchronous and asynchronous processing via the async parameter.

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
  • Optional asynchronous processing

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

When async=true: Returns immediately after queuing. Use the operations endpoint to monitor progress.

When async=false (default): Waits for processing to complete.

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 recall.

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

How to scope observations during consolidation. 'per_tag' runs one consolidation pass per individual tag, creating separate observations 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 retain strategy for this item. Overrides the namespace's default strategy for this item only. Strategies are defined in the namespace config under 'retain_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"world" | "experience" | "decision"

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

asyncbooleandefault false

If true, process asynchronously in background. If false, wait for completion (default: false)

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/recall

Recall memory

Recall memory using semantic similarity and spreading activation.

The type parameter is optional and must be one of:

  • world: General knowledge about people, places, events, and things that happen
  • experience: Memories about experience, conversations, actions taken, and tasks performed

Parameters

namespace_idstringpathrequired

Request body · application/json

querystringrequired
typesstring[]

List of fact types to recall: 'world', 'experience', 'observation', 'decision'. Defaults to world, experience, observation, and decision if not specified on the public recall endpoint.

budgetBudgetdefault "mid"

Budget levels for recall/reflect 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 observations. Set to null to disable entity inclusion.

max_tokensintegerdefault 500

Maximum tokens for entity observations

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 observation-type results. Set to {} to enable, null to disable (default: disabled).

max_tokensintegerdefault 4096

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

max_tokens_per_observationintegerdefault -1

Maximum tokens of source facts per observation (-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.

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/recall" \
  -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",
      "observations": [
        {
          "mentioned_at": "2024-01-15T10:30:00Z",
          "text": "Alice works at Google on the AI team"
        }
      ]
    }
  },
  "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": "world"
    }
  ],
  "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}/reflect

Reflect and generate answer

Reflect and formulate an answer using namespace identity, world facts, and opinions.

This endpoint:

  1. Retrieves experience (conversations and events)
  2. Retrieves world facts relevant to the query
  3. Retrieves existing opinions (namespace's perspectives)
  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 recall/reflect operations.

contextstring | nulldeprecated

DEPRECATED: Additional context is now concatenated with the query. Pass context directly in the query field instead. If provided, it will be appended to the query for backward compatibility.

max_tokensintegerdefault 4096

Maximum tokens for the response

includeReflectIncludeOptions

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 reflection. 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"world" | "experience" | "observation" | "decision"[]

Filter which fact types are retrieved during reflect. None means all types (world, experience, observation, decision).

exclude_automationsbooleandefault false

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

exclude_automation_idsstring[]

Exclude specific automations by ID from the reflect loop.

curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/reflect" \
  -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": "world"
      },
      {
        "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"
      }
    ],
    "observations": [
      {
        "id": "obs-1",
        "name": "AI Technology",
        "subtype": "structural",
        "type": "concept"
      }
    ],
    "tool_calls": [
      {
        "duration_ms": 150,
        "input": {
          "query": "AI"
        },
        "tool": "recall"
      }
    ]
  },
  "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"world" | "experience" | "observation" | "decision"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": "world"
    }
  ],
  "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 (world, experience, observation, 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 (world, experience, observation, 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 (world/experience/observation/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": "world"
    },
    {
      "id": "2",
      "label": "Bob went hiking",
      "type": "world"
    }
  ],
  "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 retain-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 retain-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 observation history

Get the full history of an observation, 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}/observations

Clear observations for a memory

Delete all observations 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 observations on the next consolidation run.

Parameters

namespace_idstringpathrequired
memory_idstringpathrequired
curl -X DELETE "https://api.illumina.sh/v1/default/namespaces/demo/memories/mem_123/observations" \
  -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