Skip to main content

LTM Guide

This page answers the questions asked most often during integration: how LTM differs from a knowledge base, what it recalls, how recall decides, what you can control, and how to separate memory by business tag. For troubleshooting, see the LTM FAQ; for cost estimates, see LTM Cost Estimation; for field-level contracts, see the LTM API reference.

How it differs from a knowledge base​

In one line: a knowledge base answers "how the product and the world work"; LTM remembers "how this user works".

Enterprise knowledge base (RAG)LTM
SourceDocuments imported by administratorsThe user's conversations (Events), derived in the background
What is storedDocument chunksProfile fields, facts, and session summaries
Who can see itShared by all usersOne copy per user (by actor_id); Space-level shared facts are read only when enabled explicitly
How it updatesRe-importDerived after each write: duplicates are skipped, outdated entries updated, contradicted ones retracted
How it recallsUsually hybrid retrieval over many chunks, then rerankingFew candidates, assembled by type and recency, with semantic search as a supplement

The two work well together: restore the user's background with LTM, then look up product and external facts in the knowledge base.

What is recalled​

  • Profile: extracted with the Space's field list; by default it records interaction preferences such as answer language, level of detail, and tone.
  • Facts: grouped by topic; with include_shared: true, Space-level shared facts are included.
  • Summaries: summaries of the most recent sessions.
  • Reflection and activity insights: Reflection is an overall portrait of the user; activity insights are behaviors that recur across sessions, each grounded in at least two different sessions. Both must be enabled in the Space and generated first, and Context returns them only when sections asks for them.

When the Space sets a memory retention period, memories past it are not recalled; see How long is memory kept?

How recall decides​

There is no separate rerank model. Recall has two paths, and Managed Chat uses both.

Context: no query​

Usually called once at the start of a session. It makes no model call and runs no vector search:

  • sections are assembled in a fixed order: profile, facts digest, summaries, Reflection, activity insights; you can request only some of them, but the order never changes;
  • within each section the newest entries come first;
  • the result is trimmed to the token budget, and the later sections are cut first when the budget runs short.

Called per turn as needed:

  • the question is embedded and matched by cosine similarity (top-k) within the scope filtered by user, memory type, topic, time, and metadata;
  • only facts and summaries are searched; the profile is not part of semantic search;
  • results carry confidence and abstain_recommended. When the top score is below the threshold (default 0.65, about 0.3 cosine), or does not clearly lead the other results, abstain_recommended is true and the results should not be used, so unrelated memory is not handed to the model.

If you need stronger ranking, pass the Search results through your own reranker.

Managed Chat​

Each turn recalls first, then calls the main model:

  • both Context and Search run, and the Search query is the original text of the user's latest message, with no model rewrite;
  • turns with only images, audio, or files use Context only;
  • how much is recalled follows the Space's managed_recall: by default a 2,048-token session briefing with the 3 most recent session summaries, 8 Search results, and at most 4,096 tokens injected in total; see Managed Chat recall settings;
  • one Event is written after the final answer; intermediate tool-call turns are not written.

recall and capture in the request turn reading and writing off separately, for example to read without writing for a guest conversation, or to keep evaluation runs out of memory.

Parameters you control​

Space settings: what gets extracted​

For all fields, see Create LTM Space; to change them later, see Update LTM Space.

ParameterPurposeNotes
profile_schemaThe Profile field list, with an extraction description for each fieldOmit it to use the platform's default fields; fixed after the first user Event is written, so design it up front
memory_strategiesThe extraction strategies for Profile, Facts, and SummaryAccept custom extraction instructions, Facts topics and Profile fields, and a model of their own; an empty enabled list turns that type off; omit it to use the platform defaults for all three
model_profileThe model family used for extractiondefault is the default family; stages overrides it per stage
embedding_modelThe embedding modelCannot change after creation
reflection_enabledWhether Reflection and activity insights can be generatedOmit it to use the platform default
event_retention_daysHow many days raw Events stay usable for extractionDefaults to 90, range 1–365; requires CLIENT_ADMIN; see How long is memory kept?
memory_retention_daysHow many days Profile, Facts, and Summary memories each stay usableNever expire by default, range 1–3650; requires CLIENT_ADMIN
metadata_keysEvent metadata keys carried onto Facts and usable as filtersAt most 5; keys can be added but never removed; see Separate memory by business tag
managed_recallHow much Managed Chat recalls each turnApplies to Managed Chat only; for defaults and ranges see Managed Chat recall settings
facts_session_history_eventsHow many earlier Events of the same session facts extraction readsDefaults to 2, range 0–50, 0 turns it off; see Does extraction read earlier turns?

Writes: what gets remembered​

For all fields, see Ingest LTM Event.

ParameterNotes
owner_typeDefaults to actor, which writes for one user; space writes shared memory for the whole Space (facts only), without actor_id
actor_idThe user ID, required when owner_type is actor; use an internal ID without personal data
session_idRequired; reuse it for later messages in the same session. Session summaries are grouped by it, and fact extraction reads the session's earlier turns as context, see Does extraction read earlier turns?
messagesThe turns added since the last write, never the whole history again; only text is processed, and extraction reads only user and assistant turns
metadataScalar business fields, at most 32; the metadata keys the Space declares are carried onto the derived Facts; see Separate memory by business tag
event_timestampWhen the conversation happened; optional, defaults to the time it was received
Idempotency-Key header or idempotency_keyOptional but recommended; retrying the same request with the same key returns the original Event instead of writing twice; the same key with different content returns 409

Reads: what gets recalled​

Context (Get context)

ParameterNotes
actor_id / include_sharedWhich user to read; include_shared: true alone reads only shared facts; at least one is required
token_budgetDefaults to 4000, range 512–16000
sectionsDefaults to profile, facts digest, and summaries; Reflection and activity insights must be requested
summary_limitHow many sessions' summaries to include; defaults to 5, at most 10
strategy_idsWhen a memory type has several strategies, which ones to read; defaults to the primary strategy

Search (Search LTM memories)

ParameterNotes
queryThe question to search for
actor_id / include_sharedSame as Context
memory_typefacts or summary; omit it to search both
topicExact topic filter; pass several to match any of them
created_at / updated_atTime range (gte / lte); filtering by updated_at excludes records that have never been updated, such as session summaries
metadataExact filter on metadata keys the Space declares, at most 5 keys, all of which must match; with it set, only Facts match
top_kDefaults to 10, at most 50
abstain_thresholdDefaults to 0.65
strategy_idsSame as Context

Managed Chat (turing_options.memory in Chat Completions)

ParameterNotes
enabledtrue turns it on; false turns it off, and the rest of the configuration can stay in place
space_idRequired; the Space to use
owner_type / actor_idSame as writes; include_shared cannot be set when owner_type is space
session_idRequired
turn_idOptional; identifies the turn. When omitted, it is derived from the conversation, so retrying the same turn does not write twice
include_sharedInclude shared facts in recall
strategy_idsSame as Context
recallDefaults to true; false skips recall and injection, and the turn is still written
captureDefaults to true; false recalls as usual and does not write the turn

recall and capture cannot both be false; to turn memory off, send enabled: false. Recall counts and budgets are not request parameters; see the next section. A request that also configures turing_options.fallbacks skips memory entirely; see Why is there no effect?

Managed Chat recall settings​

How much Managed Chat recalls each turn is set by the Space's managed_recall. Pass it when creating the Space, or change it with Update LTM Space; unset values use the defaults below. These values apply to Managed Chat only; direct Context and Search calls keep using their per-request parameters.

FieldDefaultRangePurpose
search_top_k81–50How many Search results are retrieved for the question each turn
abstain_threshold0.650–1The Search abstention threshold; when Search recommends abstaining (see Search), no Search results are injected for the turn
context_token_budget2048512–16000Token budget for the session briefing
summary_limit31–10How many recent session summaries the briefing includes at most
evidence_token_budget4096512–16000Cap on all memory injected into the model, counted on the whole message added for the model, including its wrapper and record IDs; above it the last Search results are dropped first, then the whole session briefing

context_token_budget cannot exceed evidence_token_budget; otherwise the request returns HTTP 400 / code 1004. The briefing also carries the message wrapper, so with the two set close together a full briefing is dropped whole; keep evidence_token_budget at least 1.5 times context_token_budget (the defaults use 2 times). Updates merge per field: send only the fields to change, null for a field restores its default, and null for the whole managed_recall restores all defaults.

curl -X PUT "$TURING_BASE_URL/ltm/spaces/$SPACE_ID" \
-H "Authorization: Bearer $TURING_API_KEY" \
-H "Content-Type: application/json" \
-d '{"managed_recall": {"search_top_k": 12, "evidence_token_budget": 6000}}'

Larger budgets add input tokens to the main model call. Reading a Space returns the five values in effect; the defaults are also published as defaults.space.managed_recall by List LTM model families.

Separate memory by business tag​

When one Space serves several markets, stores, or product lines, declare up to 5 metadata keys on the Space. Put those keys' values in each Event's metadata, and the Facts derived from that Event carry the values unchanged. Then:

  • Search and the memory list can filter by those values exactly;
  • Facts with different values never merge, so the return rules of two markets stay separate.

The example below separates after-sales rules by market.

1. Declare the metadata key. Pass metadata_keys when you create the Space, or call Update LTM Space on an existing one:

curl -X PUT "$TURING_BASE_URL/ltm/spaces/$SPACE_ID" \
-H "Authorization: Bearer $TURING_API_KEY" \
-H "Content-Type: application/json" \
-d '{"metadata_keys": ["market"]}'

Keys can be added but never removed: a later update must list every key already declared, or it returns HTTP 400 / code 1749.

2. Write the market with each Event. Write each market's rules as Space-level shared Events, and put the user's market in the metadata of the user's own conversations too:

curl "$TURING_BASE_URL/ltm/spaces/$SPACE_ID/events" \
-H "Authorization: Bearer $TURING_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"owner_type": "space",
"session_id": "market-rules",
"metadata": {"market": "US"},
"messages": [
{"role": "user", "content": "The standard return window in the US market is 30 days."}
]
}'

Write the Europe market's rules the same way, with metadata set to {"market": "EU"}.

3. Search by market:

curl "$TURING_BASE_URL/ltm/spaces/$SPACE_ID/memories/search" \
-H "Authorization: Bearer $TURING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "How long is the return window?",
"actor_id": "user-123",
"include_shared": true,
"metadata": {"market": "US"}
}'

The results contain only Facts whose market is US: the user's facts from the US market and the US market's shared rules. To browse records, filter List LTM memories with the query parameter metadata=market:US, repeated for several keys.

Before you rely on it
  • Only Facts carry the values: with a metadata filter, Search and the memory list return only Facts; Profile and Summary are left out.
  • Context and Managed Chat do not filter: they include the memory of every market. If those paths must keep markets strictly apart, use one Space per market.
  • Events written by Managed Chat carry no metadata: the Facts derived from those conversations carry no key values, never match a metadata filter, and never merge with tagged Facts. To separate memory by tag, write through the Events API.
  • No backfill: Facts written before the key was declared, and Facts from Events without the key, never match the filter.
  • A new key starts separate merging: after you add a key, new Facts that carry it no longer merge with earlier Facts, so the same content may appear twice.
  • Values match exactly as strings: numbers are converted from the parsed value (1.0 is stored as "1.0", which differs from 1), booleans become "true" / "false", and null means the key has no value, so send these values as strings.
  • Filtering on a key the Space does not declare returns HTTP 400 / code 1749.

Write memories directly​

To store prepared content as memories without building a conversation, for example to add or fix records from a console, import existing user profiles, or seed rules shared across a Space, use Batch create LTM memories and Batch update LTM memories. Each call takes up to 100 records and reports a result for each one.

1. Create. Give each record its type, owner, topic, content and time. For Facts, topic is one of the Strategy's topics; for Profile, it is the field name:

curl "$TURING_BASE_URL/ltm/spaces/$SPACE_ID/memories:batchCreate" \
-H "Authorization: Bearer $TURING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"client_token": "crm-import-0001",
"records": [
{"request_identifier": "r1", "owner_type": "actor", "actor_id": "user-123",
"memory_type": "facts", "topic": "project_context",
"content": "Owns the payments on-call rotation this quarter", "timestamp": "2026-11-09T11:00:00+08:00"},
{"request_identifier": "r2", "owner_type": "actor", "actor_id": "user-123",
"memory_type": "profile", "topic": "preferred_language",
"content": "Chinese", "timestamp": "2026-11-09T11:00:00+08:00"}
]
}'

In the response, created lists each record's record_id under its request_identifier, and failed lists the records that were not written with their error codes. Retrying the same request with the same client_token writes nothing twice, and a record the first attempt wrote stays deleted if it was deleted since.

2. Update. Change the content, a Fact's topic, or its metadata by record_id, including memories derived from conversations:

curl "$TURING_BASE_URL/ltm/spaces/$SPACE_ID/memories:batchUpdate" \
-H "Authorization: Bearer $TURING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"records": [
{"record_id": "<record_id>", "content": "Owns the payments and settlement on-call rotation",
"timestamp": "2026-11-09T15:00:00+08:00"}
]
}'
Before you use it
  • timestamp decides whether later conversations can change the record: it is when the information held or was stated, and it becomes the record's time. A statement extracted later that is older than it, such as a conversation written before your update but not yet extracted, cannot change the record; newer statements update or retract it as usual. timestamp may be in the past but not more than 5 minutes ahead of the server clock.
  • Each Profile field holds one value: if the field already holds another value, that record fails (code 1746) and returns the existing record_id; update that record instead.
  • You own the content: directly written content skips extraction, so extraction rules such as "keep only what was stated, store nothing sensitive" do not apply. The platform checks only that the topic or field belongs to the Strategy and that metadata keys are declared.
  • Reads return them together: List, Search, Context and Managed Chat recall all return these records with source_type api; once a later conversation updates such a Fact, it reads as event again. The revision history records who changed it.
  • A deleted memory can come back: after a delete, it is extracted again when a later conversation mentions the same thing.
  • Retention counts from the write: an imported memory does not expire early because its timestamp is old.
Self-check