Memory
turing-cli memory is the local runtime channel for Agent Memory. The minimum supported version is 0.3.0; choosing agents during installation, --yes, --project, and --config-only below require 0.4.0 or later.
First-time installation
Prepare two things first:
- A personal API Key — create it in the Turing portal's API key management; the secret is shown only once. See Get an API Key. It is your own personal key, independent of project keys and root keys.
turing-agent-memory.json— create this file with the minimum configuration below. Setapi_baseto your region's API address; for the China region it ishttps://live-turing.cn.llm.tcljd.com/api/v1. Omitspace_idfor default personal memory, or enter the ID of a specific Space you can access.
Then run in your own terminal:
turing-cli memory login
turing-cli memory install --config ~/turing-agent-memory.json
turing-cli memory doctor
loginreads the API Key from an interactive terminal and stores it with user-only permissions. You must run it yourself in a terminal; called from an agent, a pipe, or a script, it fails and asks you to run it by hand.installvalidates and saves the secret-free configuration locally and installs the Portable Skill for the agents you choose. It does not call the default Space preparation endpoint. In a terminal, it shows the same agent picker asturing-cli skills install, with detected agents preselected, and lists the target directories before asking for confirmation. With--yes, or when it runs non-interactively, it asks nothing and installs only for detected agents; if none is detected it fails withinvalid_input. When an agent runs it for you, always pass--yes.doctorchecks configuration, authentication, Space, Context, Search, and the minimum version. It may create the default Space whenspace_idis omitted, but never writes an Event. With--strict, any warn or fail returns a non-zero exit code, so a script or agent can tell whether setup is complete.
If you already installed turing-memory with turing-cli skills install, run turing-cli memory install --config ~/turing-agent-memory.json --config-only instead. It imports the configuration without touching agent directories.
Memory commands use only the key saved by login, or the TURING_MEMORY_API_KEY environment variable (for non-interactive environments such as CI; never give it to an agent). They do not read api_key from the general Turing CLI configuration ~/.turing-cli.yaml, nor TURING_API_KEY.
The minimum configuration for the default Personal Space is:
{"schema_version":1,"api_base":"https://live-turing.cn.llm.tcljd.com/api/v1"}
On the first doctor, recall, or remember call, the CLI creates or reuses the current Portal user's default Space in that environment through POST /api/v1/ltm/personal-space:prepare and saves the ID in local configuration. Every agent on this machine reads and writes the same memory through this CLI configuration, so there is nothing to configure per agent. The default Personal Space cannot be deleted: DELETE /api/v1/ltm/spaces/{space_id} returns HTTP 403 / code 1308 for it. Custom personal Spaces can still be deleted.
For a custom personal Space or a client-scoped Space, set space_id explicitly:
{"schema_version":1,"api_base":"https://<api-base>/api/v1","space_id":"ltmspace_..."}
An explicit ID skips default preparation. Creating or selecting a custom Space does not replace the default binding. Non-Portal clients require an explicit ID. The API Key determines the client, environment, and access permissions. Legacy client and environment configuration fields are still accepted but do not switch identity or environment. Unknown fields are still rejected.
Installation and binding failures
| Error | Meaning and recovery |
|---|---|
personal_space_binding_conflict | Default preparation returned HTTP 409 / code 1750, typically for an account whose default Space was deleted before the default became undeletable. A deleted default Space is not re-created automatically. Give the trace ID to the platform owner to inspect ownership or deletion state. You can also create or select another Space you can access and configure its ID explicitly; this does not repair or replace the original default binding. |
configuration_write_failed | Local configuration could not be saved. Check that TURING_MEMORY_CONFIG_PATH names a file and the target directory is writable, then retry installation. |
invalid_input: no supported Agent detected | The command ran non-interactively or with --yes, and no supported agent was detected. Name the agents with --agent, or give a Skills directory with --skill-dir. |
conflict | A chosen directory already holds a turing-memory that turing-cli did not install, such as one you wrote or edited. The CLI does not overwrite it; move it aside and retry, or leave that agent out. |
These errors occur at different steps. A local install failure cannot be attributed directly to a backend default-binding conflict.
Local files
Configuration and credentials are stored in ~/.turing-cli/memory.json and ~/.turing-cli/memory-credentials.json.
The identical Skill is installed into the Skills directory of each agent you choose, for example ~/.claude/skills/turing-memory/SKILL.md for Claude Code and ~/.agents/skills/turing-memory/SKILL.md for Codex. See Supported agents for each agent's directory.
- It installs for the current user by default;
--projectinstalls into the current project. - Repeat
--agentto name agents directly. - Repeat
--skill-dir <dir>to add another compatible location, such as the Skills directory of an agent that is not in the list, like WorkBuddy. It changes placement only, never behavior.
Every copy carries a receipt, so turing-cli skills update and skills remove manage it afterwards. A copy turing-cli already manages is replaced only when it is unmodified and its recorded version is older than the running CLI; otherwise it is left as it is. In the output of install, installed_skills lists every directory the chosen agents read that now holds Memory, unchanged_skills lists the ones left as they were, and removed_legacy_skills lists old copies that were deleted, if any.
Before 0.4.0, memory install always wrote ~/.claude/skills, ~/.codex/skills, ~/.codebuddy/skills, ~/.openclaw/skills, and ~/.agents/skills, without a receipt. See Copies left by an older memory install for how those copies are handled.
Never put an API Key in argv, that configuration file, a Skill, or an agent prompt. recall and remember read JSON only from standard input.
Recall
turing-cli memory recall <<'JSON'
{"schema_version":1,"query":"Which durable decisions are relevant to this task?","scope":{"kind":"global"}}
JSON
A project hint is not an ACL or hard filter. Use a label already established by the user and retain it in the query:
{
"schema_version": 1,
"query": "In project turing-backend, which durable constraints apply to the current task?",
"scope": { "kind": "project", "label": "turing-backend" }
}
The CLI concurrently performs exactly one public Context request and one public Search request. Search is not retried, so one Recall triggers at most one query embedding and one fresh KNN operation. A transient failure in one read leg may return degraded; authentication, permission, and binding errors fail explicitly.
Remember
turing-cli memory remember <<'JSON'
{"schema_version":1,"capsule":"The user prefers concise implementation plans with explicit compatibility boundaries.","scope":{"kind":"global"}}
JSON
Remember submits one compact, user-confirmed capsule. The CLI generates an operation UUID and retries the public Event write with identical serialized bytes and the same idempotency key. If final acceptance is unknown, the error response returns operation_id; do not blindly replay it with a new ID.
Machine protocol
- Standard input must contain exactly one strict JSON object. Unknown fields, trailing JSON, and unsupported
schema_versionvalues are rejected. queryandcapsuleare limited to 4096 Unicode characters; a project label is limited to 128 characters.- Standard output from
recallandrememberis always exactly one JSON envelope for safe Skill parsing. - Recall evidence is capped at 4096 UTF-8 bytes;
source_record_idscontains only records that entered the evidence. - Daily Recall and Remember do not fetch the release manifest; incompatible schemas fail fast.
A success envelope contains only data; a failure envelope contains only error. A v1 Recall result is:
{"schema_version":1,"status":"ok","data":{"read_status":"used","evidence":"<bounded evidence>","evidence_bytes":123,"source_record_ids":["ltmmem_..."],"truncated":false,"warnings":[]}}
read_status is exactly used, empty, or degraded. A v1 Remember result is:
{"schema_version":1,"status":"ok","data":{"acceptance_status":"accepted","event_id":"memevent_...","operation_id":"<UUIDv4>"}}
accepted only means the Event was received. Memory is derived asynchronously, which usually takes a few tens of seconds, and becomes available to Recall once derivation completes.
Doctor sets data.overall_status to ready or degraded. Its ordered checks are configuration, authentication, release_minimum, binding, context, and search; every check has status pass, warn, or fail.
{"schema_version":1,"status":"ok","data":{"overall_status":"ready","cli_version":"0.3.0","supported_schema_versions":[1],"checks":[{"name":"configuration","status":"pass"}]}}
Failures return a non-zero process status. acceptance_unknown preserves the original operation ID, and callers must not replay with a newly generated ID:
{"schema_version":1,"status":"error","error":{"code":"acceptance_unknown","message":"Event acceptance is unknown; do not automatically retry or create a new operation","trace_id":"<when available>","operation_id":"<UUIDv4>"}}
See Agent Memory for trigger and storage boundaries.