Memory

turing-cli memory is the local runtime channel for Agent Memory. The minimum supported version is 0.3.0.

First-time installation

Prepare two things first:

1. A personal API Key — create it in the Turing portal's API key management; the secret is shown only once. It is your own personal key, independent of project keys and root keys.
2. turing-agent-memory.json — use the template below, with api_base pointing to the target environment's API. Omit space_id for default personal memory, or enter the ID of a specific Space you can access.

Then run:

turing-cli memory login
turing-cli memory install --config ~/Downloads/turing-agent-memory.json
turing-cli memory doctor

• login reads the API Key from an interactive terminal and stores it with user-only permissions.
• install validates and saves the secret-free configuration locally and installs the Portable Skill. It does not call the default Space preparation endpoint.
• doctor checks configuration, authentication, Space, Context, Search, and the minimum version. It may create the default Space when space_id is omitted, but never writes an Event.

The minimum configuration for the default Personal Space is:

{"schema_version":1,"api_base":"https://<api-base>/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. Other agents using that ID access the same memory. A deleted default Space is not re-created automatically: later default preparation returns personal_space_binding_conflict, and the failure table below describes recovery.

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

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 at:

• ~/.claude/skills/turing-memory/SKILL.md
• ~/.codex/skills/turing-memory/SKILL.md
• ~/.codebuddy/skills/turing-memory/SKILL.md
• ~/.openclaw/skills/turing-memory/SKILL.md
• ~/.agents/skills/turing-memory/SKILL.md

Repeat --skill-dir <dir> to add another compatible location. It changes placement only, never behavior.

Keep secrets out of command arguments

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_version values are rejected.
• query and capsule are limited to 4096 Unicode characters; a project label is limited to 128 characters.
• Standard output from recall and remember is always exactly one JSON envelope for safe Skill parsing.
• Recall evidence is capped at 4096 UTF-8 bytes; source_record_ids contains 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 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.