CLI

memoturn is a thin client over the REST API. It targets one node or gateway and prints JSON responses; the Memoturn-Txid of each response goes to stderr (txid: N), so output stays pipeable. See quickstart for getting a node running.

Global flags

Flag	Env var	Default	Purpose
--url	MEMOTURN_URL	http://127.0.0.1:8080	Base URL of a memoturnd node / gateway
--token	MEMOTURN_TOKEN	—	Per-database or namespace JWT (data-plane commands)
--platform-key	MEMOTURN_PLATFORM_KEY	—	Platform key (control-plane commands: db, token)

Control-plane commands authenticate with the platform key, data-plane commands with the token; either falls back to the other. With auth off (the dev default), neither is needed.

memory

Typed agent memory against /v1/memory/{ns}/{profile} — see memories and recall.

memoturn memory ingest <ns> <profile> --summary <gist> [--type fact|event|instruction|task]
                                      [--topic <key>] [--content <json>] [--keywords <terms>]
                                      [--session <id>] [--source <agent>] [--ttl <secs>]
memoturn memory recall  <ns> <profile> [<query>] [--topic <key>] [--k 8] [--type <t>]...
                                      [--source <agent>] [--include-superseded]
memoturn memory extract <ns> <profile> [--session <id>] [--source <agent>] [--dry-run]   # turns JSON on stdin
memoturn memory get     <ns> <profile> <id>
memoturn memory forget  <ns> <profile> <id>
memoturn memory erase   <ns> <profile> (--memory-id id | --topic key --type fact | --session sid [--turns])
memoturn memory erasures <ns> <profile> [id]
memoturn memory sessions <ns> <profile>
memoturn memory profiles <ns>

erase is verifiable erasure: a hard forget now, then a bounded-time object-storage history rewrite proven by a signed receipt — erasures shows the coupon and, once completed, the receipt.

# every agent serving acme's user "alice" shares one profile
memoturn memory ingest acme alice --type fact --topic user.diet \
  --summary "vegetarian since 2024" --keywords "food preference"

memoturn memory recall acme alice "what can this user eat?"
# ranked memories with channel attribution; superseded facts hidden

ingest stores one memory per invocation; --content defaults to {"summary": <summary>}, and the profile auto-creates on first ingest. --source tags the memory with which agent wrote it; on recall it filters to one agent’s memories. recall drives the keyword and topic channels; the vector channel needs an embedding, which the CLI does not compute — use the API or SDKs (or enable node-side auto-embedding, which embeds bare query strings at recall). extract reads a JSON array of {role, content} turns from stdin and needs a node with server-side extraction configured:

echo '[{"role": "user", "content": "I am vegan now"}]' \
  | memoturn memory extract acme alice --dry-run

profiles lists every profile under a namespace and requires a namespace token.

db

Control-plane database management (platform key when auth is on).

memoturn db create <name>
memoturn db list
memoturn db delete <name>

memoturn db create agent-42

db delete writes a deletion tombstone: write tokens minted before the deletion are rejected (403), so a stale token cannot write into a re-created database of the same name. See security.

branch

Copy-on-write branches, checkpoints, and rewind — see branching.

memoturn branch create <db> <name> [--from <branch>] [--ttl <secs>]
memoturn branch list <db>
memoturn branch delete <db> <name>
memoturn branch checkpoint <db> <branch> <name>
memoturn branch rewind <db> <branch> <to>          # checkpoint name or txid

memoturn branch checkpoint agent-42 main before-task
memoturn branch create agent-42 experiment --ttl 3600   # burner branch, auto-expires
memoturn branch rewind agent-42 main before-task

sql

Run SQL against a database. spec is name or name@branch; statements split on ;. Reads stdin when the query argument is omitted.

memoturn sql <spec> [<query>]

memoturn sql agent-42 "SELECT count(*) FROM orders WHERE status = 'open'"
memoturn sql agent-42@experiment < migration.sql

kv

KV namespaces with TTL inside a database.

memoturn kv put <spec> <ns> <key> <value> [--ttl <secs>]
memoturn kv get <spec> <ns> <key>
memoturn kv delete <spec> <ns> <key>
memoturn kv list <spec> <ns> [--prefix <p>]

memoturn kv put agent-42 scratch plan "step 1: fetch orders" --ttl 3600
memoturn kv list agent-42 scratch --prefix step:

sync

Ship a database’s state to object storage now — an explicit durability point.

memoturn sync agent-42

token

Mint JWTs (platform key required). Scopes: read, write, admin; default TTL 3600 s.

memoturn token create <db> [--scope write] [--ttl 3600]      # one database / profile
memoturn token create-ns <ns> [--scope write] [--ttl 3600]   # every profile under the namespace

The full auth flow against a node with auth enabled:

# start the node with auth on
MEMOTURN_AUTH=on MEMOTURN_PLATFORM_KEY=... memoturnd

# mint a per-database token, then use it for data-plane commands
memoturn --platform-key ... token create agent-1 --scope write
memoturn --token <jwt> kv put agent-1 scratch plan "..."

# orchestrator posture: one token for every acme profile
memoturn token create-ns acme --scope write

See security for token semantics and configuration for the node-side MEMOTURN_* variables.

policy

Data-governance policies: retention caps, memory aging, task-TTL ceilings, and AI egress rules per namespace, with tighten-only per-profile overrides. Namespace-level commands use the platform key; profile-level commands use a token (read to view, admin to set).

# set the namespace policy (JSON from --file or stdin)
memoturn policy set acme --file policy.json
echo '{"memory": {"task_ttl_max_secs": 600}}' | memoturn policy set acme

# tighten one profile, inspect what is actually enforced, then clear it
memoturn policy set acme --profile alice --file stricter.json
memoturn policy get acme --profile alice     # override + effective (env ceilings folded in)
memoturn policy clear acme --profile alice

A profile override that loosens the namespace policy is rejected (409) naming each offending field. See security for the policy document shape.

audit

Export a namespace’s audit stream as JSONL, oldest first, paginating through the whole range (platform key, or a namespace admin token via --token). Requires audit.enabled in the namespace policy.

memoturn audit export acme                              # last 24 h
memoturn audit export acme --from 7d --action memory.   # all memory mutations this week
memoturn audit export acme --action ai. --outcome denied > denials.jsonl

--from/--to accept unix milliseconds or a duration ago (30m, 24h, 7d).

ask

A natural-language question answered from a profile’s memories: server-side recall + answer synthesis with cited memory ids. Needs a node with MEMOTURN_ASSISTANT_API_KEY; unconfigured nodes return 503 unconfigured.

memoturn ask acme alice "what can this user eat?"          # answer; sources on stderr
memoturn ask acme alice "..." --json                       # full {answer, sources, memories}
memoturn ask acme alice "..." --source claude-code --k 12  # recall filters

init

First-run check: probes the node at MEMOTURN_URL, reports which credentials are set, and prints ready-to-paste export lines. With --db <name> (and the platform key) it also mints a write token for that database.

memoturn init                  # reachability + credential report
memoturn init --db agent-1     # + mint and print a write token

completions

Shell completions for bash, zsh, fish, elvish, and PowerShell:

memoturn completions zsh > "${fpath[1]}/_memoturn"   # zsh
memoturn completions bash > /etc/bash_completion.d/memoturn

Errors

Failures print the response (with its machine-readable code — see errors) plus an actionable hint on stderr, e.g. a 404 branch_not_found suggests memoturn branch list <db>.

Flag naming: CLI flags are idiomatic spellings of the wire fields — --topic sends topic_key, --session sends session_id, --memory-id sends memory_id.