CLI details.

Full command reference for memory operations, workspace management, OAuth token flows, and connectivity checks.

Query memories

Search durable context by natural language. Use this first when you need to recall existing project knowledge.

empirical memory query --match "oauth preferences" --top-k 3 --category build --pretty

Retrieval pathways

A query normally lets Empirical choose how to answer it. Use --path when you want a specific shape of answer instead. Use semantic for a ranked answer to a question, list for the complete set of matching records, graph for memories connected to the best matches by explicit relationships, and hebbian for memories that have been recalled together with them. Add --hops 1 or --hops 2 to set how far the graph and hebbian walks travel. Leave --path off to keep the default, where Empirical decides.

empirical memory query --match "deployment constraints" --tags project --path list --top-k 20 --pretty
empirical memory query --match "deployment constraints" --path graph --hops 2 --pretty

Get one memory

Retrieve a memory by exact ID when you need deterministic automation.

empirical memory get --memory-id <id> --pretty

List memories

Browse memories with filters and an opaque cursor for stable pagination.

empirical memory list --category project --limit 20 --cursor <cursor> --pretty

Record a memory

Save a new durable preference, decision, or project constraint.

empirical memory record --category preference --summary "Use compact JSON by default" --tags json,style --node-type observation

Append a note

Add context to an existing memory, resolved by fuzzy search.

empirical memory note --match "compact JSON" --text "confirmed in monorepo setup" --min-score 0.35

Update a memory

Patch a memory's summary or fields. Use an ID or a precise match for deterministic edits.

empirical memory update --match "compact JSON" --patch-json '{"summary":"Use compact JSON, 2-space indent"}' --min-score 0.35

Delete a memory

Deletion is a dry run until you pass --confirm.

empirical memory delete --match "old preference" --confirm --min-score 0.35

Find or merge duplicates

Review duplicate candidates before merging a secondary memory into its canonical record.

empirical memory duplicates --memory-id <id>
empirical memory merge --canonical-id <canonical-id> --duplicate-id <duplicate-id>

Export memories

Write portable JSON for backup, migration, or continuity workflows.

empirical memory export --scope personal --out ./empirical-memories.json

Workspace commands

List available workspaces, check which is active, switch context, manage invites, or create and remove team workspaces.

empirical workspace list
empirical workspace current
empirical workspace select [<number|name>]
empirical workspace use <number|name|id>
empirical workspace create <name> [--description <text>]
empirical workspace invite create [--role reader|writer|manager]
empirical workspace invite list
empirical workspace invite revoke <token>
empirical workspace delete <number|name|id> [--confirm]

OAuth commands

Use browser login for an interactive local session. Use headless bootstrap and refresh for CI, bots, and containers. The optional client helpers are only for advanced credential overrides.

empirical auth login

Headless OAuth

Bootstrap once on a trusted machine, then refresh the cached token in automation. The CLI can self-provision the account credential when no client details are cached.

empirical oauth bootstrap headless --write-env

empirical oauth refresh headless --write-env

Docker OAuth

Use the Docker target when the container runtime should receive a printed token instead of a local env file.

empirical oauth bootstrap docker --print-access-token
empirical oauth refresh docker --print-access-token

Advanced client helpers

Inspect, set, or clear cached client credentials. Most users do not need these commands.

empirical oauth client set --client-id <id> --client-secret <secret>
empirical oauth client show
empirical oauth client clear

Doctor & update

Run doctor to verify token presence, API connectivity, and workspace status in one pass. Run update --check to see if a newer CLI build is available.

empirical doctor
# -> [OK] token_presence    Access token found.
# -> [OK] api_connectivity  Connected. User: you@example.com.
# -> [OK] workspace         Workspace ID: ws_personal_...
# -> Overall: OK

empirical update --check   # prints install command if a newer version exists

Last updated: July 21, 2026