Skip to main content

LTM FAQ

For the full picture of how LTM differs from a knowledge base, how recall decides, and which parameters you control, see the LTM Guide. To estimate cost from your usage, see LTM Cost Estimation.

Before you integrate​

Does it fit consumer apps? How is recall different from an enterprise knowledge base?​

Yes. LTM searches only the current user's own memory, and it stores profile fields, facts, and summaries derived from conversations, not document chunks, so the candidate set is small and is assembled mainly by type and recency. The two work well together: the knowledge base answers "how the product works", and LTM remembers "how this user works". For a point-by-point comparison, see How it differs from a knowledge base.

Files in a knowledge base never turn into memory on their own; only conversations written as Events are extracted.

What is LTM not meant for?​

LTM remembers each user's long-term preferences and facts. Handle the following needs another way:

Which regions offer LTM?​

The China, Asia Pacific (Singapore), and Europe regions; the North America region is not available yet. Data never syncs between regions, so send requests to the region that holds the Space. Overseas regions offer only the gpt and gemini families. See Available Regions for each region's endpoint and model notes.

Do the default extraction templates fit my product?​

The defaults target general office work: Profile records interaction preferences such as answer language, level of detail, and tone, and Facts keeps only work topics such as roles, projects, technical state, decisions, and requirements.

For consumer, smart-home, or other everyday scenarios, define your own Profile fields and Facts topics in the Space; otherwise most everyday content will not be extracted. See Core concepts.

How is it billed?​

  • Recall (Context and Search) makes no LLM call; each Search creates one query embedding.
  • Extraction after a write runs in the background on the model configured for the Space, and is billed to the Space's owner: a personal Space to the user, a client-scoped Space to that client.
  • Writing or updating Facts directly creates one embedding per record, also billed to the Space's owner; Profile makes no model call.
  • Managed Chat's main model call is billed as usual, and the injected memory counts as input tokens of that call; when the request configures turing_options.fallbacks, memory is skipped entirely and no LTM cost is incurred.
  • Redriving a failed derivation calls the extraction model again and is billed for those calls.
  • Storage is currently free.

To estimate cost from your usage, see LTM Cost Estimation.

What if I need customization?​

You can configure the following in the Space yourself: Profile fields, Facts topics, the extraction instructions and model of each memory type, and which memory types are enabled; see Parameters you control. For anything beyond that, contact the platform owner for an assessment.

Teams that need to maintain user data and every detail themselves can obtain the code and deploy it on their own; see How long is memory kept?

Content and isolation​

Can I control what gets remembered?​

Yes, at three levels:

  1. You decide what is written: Managed Chat writes only after a final answer; with the API, only the Events you submit are processed.
  2. You decide what is extracted, per Space: Profile extracts only the fields in its field list; Facts keeps only the topics you define and can be turned off entirely; all three types accept custom extraction instructions and their own model. For example, the extraction instructions can say to keep only what relates to using home appliances and to skip small talk and complaints.
  3. Profile fields are fixed: they can no longer change after the first user Event is written or the first Profile value is written directly, so design them up front.

For every parameter you control, see Parameters you control.

Can I write or change memory outside a conversation?​

Yes, in two ways:

  • Write prepared memories directly: Batch create LTM memories writes facts or Profile field values, and Batch update LTM memories changes existing memories, including those derived from conversations. This suits editing in a console, importing existing user profiles, and seeding shared rules. The content skips extraction and is yours to vouch for; for how later conversations affect these memories, see Write memories directly.
  • Write an Event and let the platform extract it: for example, when a user changes a todo owner from "ZS" to "Zhang San" in your UI, write a user message such as "From now on, ZS means Zhang San". During extraction, the new fact updates or retracts the old facts it contradicts. Whether the information is kept depends on the Space's Profile fields and Facts topics; see the default extraction templates.

To delete one memory, see Can I delete a single memory?; to delete all of one user's data, see How long is memory kept?

Can I delete a single memory?​

Yes. Delete LTM memory deletes one by record_id, and Batch delete LTM memories deletes up to 100 at once. Any record List LTM memories returns can be deleted, with the same permission as reading it.

  • After the delete, List, Search, Context, and Managed Chat recall no longer return the record. Its revision history goes too, leaving one delete entry without the content: which record, who deleted it, and when.
  • A batch delete handles each record on its own, so one failure does not stop the others. The response lists the deleted records in deleted and the records left in place, with their error codes, in failed.
  • The raw Events are not deleted. A later conversation that says the same thing, or an Event still being derived when you delete, extracts the fact again; Profile and Summary records come back with later Events. Reflections and activity insights already built from the memory are not changed.
  • When a user says "forget X", extraction does not delete memories. Find the record with Search LTM memories and delete it by record_id.

Does extraction read earlier turns of the same session?​

Yes. When it extracts facts, LTM by default gives the model the 2 latest earlier Events of the same session (same Space, same user, same session_id) as context. A reply that only makes sense with the previous turn, such as "Right, never have", still yields "doesn't eat spicy food".

  • The Space's facts_session_history_events sets how many Events: 2 by default, range 0–50, and 0 sends no earlier turns. Set it when you create the Space or with Update LTM Space; null restores the default, and a change applies to Events written after it. With a larger value, the number of Events sent varies between about half the value and the value, so that consecutive extractions see the same earlier turns.
  • Earlier turns only help the model read the current one; facts are extracted from the current Event only.
  • Earlier turns are taken in the order LTM received the Events, and Events past their retention period are left out; a redrive of an Event sees the same earlier turns as its first run.
  • Each write still sends only the new turns; don't repeat earlier turns in the Event.
  • Earlier turns add at most about 6,000 characters per extraction, counted as facts extraction input tokens, see LTM cost estimate. The limit doesn't grow with the number of Events: the higher the setting, the fewer characters each Event gets, and a long Event keeps its end. The first Event of a session has no earlier turns and is extracted exactly as before.
  • Profile extraction still reads only the current Event; summaries already fold the whole session.

Do retries write duplicates?​

No, as long as you send an idempotency key: pass your own message ID as the Idempotency-Key header (or idempotency_key in the body), and retrying the same request with the same key returns the original Event. Managed Chat deduplicates each turn automatically. When you write memories directly, send a client_token with Batch create LTM memories; retrying the same request with the same token writes nothing twice either.

A user saying the same thing several times is fine too: extraction skips duplicate facts and updates outdated ones with the new content.

What is stored, and how is data isolated?​

  • Managed Chat: each completed turn, after the final answer.
  • Public API: the messages in the Events you submit.
  • Agent Memory: concise memories the user has confirmed.

A Space is a hard boundary; reads and writes never cross Spaces. Within a Space, memory is kept per user (actor_id), and Space-level shared facts are read only when include_shared: true is set explicitly. Use an internal ID for actor_id that does not contain personal data such as a phone number.

What about one user with several devices or accounts?​

Memory belongs to a Space and an actor_id, and it is shared only within the same Space under the same actor_id:

  • Share memory across devices: write to the same Space with the same actor_id, such as the account ID. Context and Managed Chat recall cannot filter by business tags such as the device. When you write through the Events API, you can declare metadata keys on the Space and filter Facts by them in Search and the memory list, but Facts with different values never merge; Events written by Managed Chat carry no metadata. See Separate memory by business tag.
  • Keep memory apart: use different actor_id values or different Spaces. Memory in different Spaces cannot be recalled together.
  • Anonymous first, signed in later: memory under one actor_id cannot currently be merged into another, so settle the actor_id rule before you integrate.

How do I add and change shared rules?​

Shared rules, such as the sales terms of one market, are kept as Space-level shared facts: write an Event with owner_type set to space (without actor_id), or write facts with owner_type set to space directly through Batch create LTM memories; set include_shared: true when reading.

To change a rule, update it through Batch update LTM memories, or write another Event that states the new rule; extraction updates or retracts the old facts.

When each market has its own rules, declare a market metadata key on the Space, put the market in each rule Event's metadata, and filter Search by market; rules of different markets never merge either. For a full example, see Separate memory by business tag. Context and Managed Chat recall do not filter by market and include the shared rules of every market; if those paths must keep markets strictly apart, use one Space per market.

How long is memory kept? Can it be deleted?​

Retention only decides whether data is still used; it deletes nothing, and expired Events and memories stay stored. To delete data, delete memories one by one or erase all of one user's data (the third item below).

Retention is set on the Space and requires CLIENT_ADMIN; for the detailed rules, see Data retention and deletion:

  • Raw Events: usable for extraction for 90 days by default; set 1–365 days with event_retention_days, counted from when LTM received the Event. After that the Event is still stored, but it is no longer extracted and cannot be redriven.
  • Profile fields, facts, and summaries: do not expire by default; they are kept until the Space is deleted, except for old content that extraction updates or retracts. You can set 1–3650 days per type with memory_retention_days, counted from the last time the memory was confirmed: created, updated, or mentioned again by a later conversation. An expired memory is not deleted, but it is no longer recalled and new content is no longer merged into it. The first time you set a period, the clock starts at that moment, so nothing expires until one full period has passed.
  • Deleting all of one user's data: call Erase LTM actor data to delete that user's raw Events, memories of every type with their revision history, and recall records in the Space. The erasure normally completes within that one request; while the data is being removed, that user's writes return HTTP 409 / code 1745, and they are accepted again as soon as it completes. Space-level shared data is not affected; see Erase one user's data.
  • Every change to a memory records the content before and after it in the revision history, which is kept for 365 days for auditing and tracing. A memory deleted through the delete endpoints loses its revision history too; see Can I delete a single memory?
  • Teams that need to maintain user data and every detail themselves can obtain the LTM code and deploy it on their own, so the data stays only in their own environment. Contact the platform owner.

Recall​

Which algorithm does recall use? Is there a reranker?​

There is no separate rerank model. Recall has two paths:

  • Context: no model call and no vector search. It assembles the profile, facts, recent summaries, and more in a fixed order, newest first, trimmed to the token budget.
  • Search: embeds the question and returns the top-k by cosine similarity after filtering. Results carry confidence and abstain_recommended, which recommends not using them when relevance is too low; adjust the threshold with abstain_threshold.

Managed Chat calls both paths. If you need stronger ranking, pass the Search results through your own reranker. For details, see How recall decides.

Does it remember after starting a new session?​

Yes, that is the problem LTM solves: at the start of a new session, Context loads the user's memory, and Managed Chat does this for you. In-session context, such as what was said a few turns ago, still comes from your own chat history.

Memory usually becomes readable a few tens of seconds after a write. In a demo, wait a moment after writing before starting the new session.

Can it remember how preferences change over time?​

Recall returns only current memory. If a user first says "no cilantro" and later says "I like cilantro now", extraction updates the fact to the latter instead of keeping two contradicting ones.

The earlier content stays in the revision history but is not recalled. Reflection's activity insights summarize behavior that recurs across sessions, but custom statistical dimensions are not supported.

How soon can I read what I wrote? Why is the result empty?​

An accepted response only means the Event was received; extraction runs asynchronously in the background and usually takes a few tens of seconds. Instead of waiting a fixed time, query the derivation status with the event_id the write returned; see How do I know an Event has been processed? An empty result usually has one of these causes:

  • processing has not finished yet, and the derivation status is in_progress;
  • the conversation contained nothing worth keeping long term, such as small talk;
  • the content falls outside the Profile fields or Facts topics and was filtered out; see the default extraction templates;
  • extraction failed, and the derivation status is dead_lettered;
  • the memory is past the Space's memory retention period; see How long is memory kept?;
  • Search or the memory list filters by metadata, and the memories do not carry that value; see Separate memory by business tag.

How do I know an Event has been processed? What if it failed?​

Call Get LTM Event derivation status with the event_id the write returned, every few seconds, until status is no longer in_progress; the LTM quickstart has an example. It is open to the same callers as writing Events, and the result contains no conversation or memory content.

  • completed: every Strategy has been processed. strategies has one entry per enabled Strategy, each with its memory_type and status, and one memory type can have several Strategies; no_candidates means the Event held nothing that Strategy keeps.
  • dead_lettered: every attempt failed for at least one Strategy, and strategies[].error_category gives the reason category, such as rate_limited or timeout. Call Redrive LTM Event derivation once the cause has cleared; otherwise the derivation is dead-lettered again. A redrive restarts only the failed Strategies, and repeating it restarts nothing new. It calls the extraction model again and is billed; it usually merges with existing memory, but it cannot guarantee that no duplicate fact appears.
  • cancelled: the Event's data is being deleted, for example because its user's data is being erased. Once the deletion finishes, querying the Event returns HTTP 404 (code 1780, or code 1751 when the whole Space was deleted), so this status is rarely seen.
  • untracked: the Event was written before the platform started recording derivation progress, so it has no progress record. This is not a transient state; check the result with the memory list.

expired: true means the Event is past the Space's Event retention period. It is no longer extracted, and a redrive returns HTTP 409 / code 1740. When an Event expired before it was processed, its Strategies end as no_candidates, which then means it was not processed, not that the conversation held nothing to keep.

What latency should I expect, and where do I see it?​

Get LTM latency statistics shows the measured latency of your own Space.

  • Recall latency matters most: Search and Context answer inside the user's turn, so they add directly to response time. It gives the request count, error counts and P50 / P95 / P99 for your own calls and for Managed Chat's recall separately.
  • Time until a write is recallable: writing and extraction run in the background; this gives P50 / P95 / P99 of the time from an Event write until each memory type is stored, that is, how soon a write can be read.
  • Event write acknowledgement: the write returns before extraction starts, so you can set your client timeout from it.
  • The window defaults to the last 7 days and spans at most 90 days. With little traffic there are few samples and P99 varies widely; read it together with the request count.

Managed Chat​

I added turing_options.memory. Why does nothing happen?​

Check the response headers first:

  • X-Turing-Memory-Read-Status: the recall result;
  • X-Turing-Memory-Capture-Status: whether the turn was written;
  • X-Turing-Memory-Reason: why memory was skipped or degraded.

The most common cause is turing_options.fallbacks (including auto) in the request: whenever it is configured, whether or not a fallback actually happens, memory is skipped entirely with the reason fallback_enabled, and the request still returns normally. Do not configure fallbacks on requests that need memory. Developer Platform traces also show every recall and write.

How are tool calls written?​

Intermediate tool-call turns recall but do not write; one Event is written after the final answer.

Can Managed Chat only read or only write?​

Yes. Set one of these in turing_options.memory:

  • capture: false: recall as usual and do not write the turn. The X-Turing-Memory-Capture-Status header is skipped and X-Turing-Memory-Reason is capture_disabled. Use it for guest conversations, when a user asks not to remember a turn, for evaluation runs, or when another agent writes a shared session.
  • recall: false: no recall and nothing injected; the turn is still written after the final answer, and X-Turing-Memory-Read-Status is skipped. Retrying the same turn still writes it only once.

The two cannot both be false; to turn memory off, send enabled: false. With reading off, the Space is still checked, so a space_id that does not exist still returns an error.

Can I change how much Managed Chat recalls?​

Yes, with managed_recall on the Space: how many Search results to take, the abstention threshold, the session briefing's budget and summary count, and the cap on everything injected. These values cannot be changed per request. For defaults and ranges, see Managed Chat recall settings.

Agent Memory​

Can an agent install it by itself? Why must I log in myself?​

Apart from creating the API Key and running turing-cli memory login, every step can be handed to an agent; see Let an agent install it. login accepts input only from an interactive terminal, so the API Key never enters the agent's context. Non-interactive environments such as CI can use the TURING_MEMORY_API_KEY environment variable instead.

Why didn't the agent use memory? How does it relate to CLAUDE.md and AGENTS.md?​

The agent recalls once at the start of a task whose approach may depend on the user's preferences, conventions, or earlier decisions, and when the user refers to earlier work; it does not run on every turn. You can also ask it to check memory first.

Host-native memory such as CLAUDE.md and AGENTS.md still applies, but other agents cannot read it. A confirmed preference that should follow the user across agents is also saved to Agent Memory. See Agent Memory.

Can I continue the same task between Claude Code and Codex?​

No. Agent Memory stores only the long-term preferences and decisions you confirm, shared by your agents and Portal. It does not record sessions, and it does not hand a task in progress from one agent to another. That data is produced on every turn and is stale within days, so it is better kept on your own machine.

To continue a task in another agent, use a community open-source tool that runs on your machine, such as ai-memory or Tencent's MemHub (preview). They collect each agent's sessions locally so another agent can recall them or carry on. You can use them alongside Agent Memory: the local tool continues the current task, and Agent Memory keeps your long-term preferences.

These are third-party projects that Turing does not maintain or support; follow their own documentation to install and use them. ai-memory can send its model and embedding requests through the Turing API, with the usage counted toward your own API key; see Use Turing Models in ai-memory.

Can the default personal Space be deleted?​

No. Deleting the default Personal Space returns HTTP 403 / code 1308; custom personal Spaces can still be deleted. If a default Space was deleted before this rule took effect, preparing it returns HTTP 409 / code 1750; contact the platform owner with the trace ID.

Self-check