CLI Reference

The remember command ships in the dependency-light base wheel. Query, ingest, connector management, and MCP all talk to the deployment API at REMEMBERSTACK_API_URL (default http://127.0.0.1:8000). Set REMEMBERSTACK_API_AUTHORIZATION to the complete Authorization header value when the deployment has an auth perimeter. The CLI carries no provider adapters: connector execution and E0 processing stay in the deployment. One deployment is one trust domain.

remember --version
# RememberStack 0.2.0

remember query

Because query renders the same recipe surface the API and MCP do, all three are always in lockstep.

remember query list

remember query list

Prints the deployment's recipe tool list — one JSON object per line, each with name, description, input_schema, output_grain, and answer_intent. This is exactly the API's GET /recipes.

remember query run

remember query run relation_current \
  --arg subject_entity_id=<entity-uuid> \
  --arg predicate=works_for

Runs one recipe by name over key=value arguments and prints the envelope as JSON. Arguments are coerced by the recipe's declared types. An unknown recipe or a missing required argument prints the API's error to stderr and exits nonzero.

remember ingest

remember ingest ./notes/project.md \
  --source-kind custom-feeder \
  --source-ref workspace/project \
  --source-version-ref revision-17 \
  --source-modified-at 2026-07-20T10:30:00+00:00 \
  --versioning-mode living

Pushes the file's bytes through the deployment's E0 ingress. --mime is optional when it can be inferred from the filename. --source-kind and --source-ref must be supplied together: reusing that pair for changed bytes creates a new immutable version of the same document lineage; replaying the same bytes is a no-op. Omit the pair for a one-shot upload lineage.

remember connectors

remember connectors add watched-directory \
  --name notes \
  --config path=/sources/notes \
  --credential-ref deployment-secret://notes
remember connectors list
remember connectors status <connector-uuid>
remember connectors pause <connector-uuid>

These commands configure connectors on a deployment that composes connector management. They never execute a connector in the client process. A --credential-ref names a secret already held by the deployment; raw credentials are not connector configuration. This package layer defines the typed client/API composition port; a deployment must supply its persistent connector manager.

remember mcp

Runs the base wheel's MCP stdio server. It discovers recipes from the remote deployment and proxies tools/call to the same HTTP recipe endpoint used by remember query.

remember budget inspect

Budget inspection requires the [server] extra and connects directly to the deployment's PostgreSQL spine through REMEMBERSTACK_DATABASE_URL:

remember budget inspect --deployment <deployment-uuid>

Each output line is one configured route ceiling with its aligned window, current spend, remaining amount, exhaustion state, parked-work count, and spend grouped by the recorded cascade tier. Both enforcement and inspection read the same processing_state and cost_ledger rows; the CLI is not a billing system or a second source of pipeline truth.

Ceilings are optional typed configuration in REMEMBERSTACK_WORK_BUDGETS. The value is a JSON list; each item explicitly names the deployment, stage, lane, window size, and USD ceiling:

export REMEMBERSTACK_WORK_BUDGETS='[{"deployment_id":"<deployment-uuid>","stage":"extract_claims","lane":"steady","window_seconds":86400,"ceiling_usd":"10.00"}]'

Use null for an unlaned K/P route. A route absent from the list is unlimited. When spend reaches its ceiling, due work is parked until the aligned window ends without consuming a handler attempt or becoming a failure; the same row then resumes normally.

remember ops

Operational commands require the [server] extra and REMEMBERSTACK_DATABASE_URL. They are direct, local admin tools over the durable PostgreSQL state — not a dashboard or hosted control plane.

remember ops inspect

remember ops inspect --deployment <deployment-uuid>

Prints one typed JSON report containing route/status counts, DLQ totals and groups, a poison-target summary, the current P2/P3 snapshot pointers, and a currency-ledger audit. Variable-size evidence is returned as a bounded sample; its complete total is reported separately. REMEMBERSTACK_OPERATIONAL_SAMPLE_LIMIT sets the shared cap (default 20, maximum 1000).

remember ops replay

remember ops replay <processing-uuid> \
  --deployment <deployment-uuid> \
  --attempts 1 \
  [--lane steady|backfill] \
  [--not-before 2026-07-22T08:00:00+00:00]

Reopens exactly one row whose current status is dead_letter. Attempts already consumed and the full previous traceback remain intact; --attempts grants only that many additional handler executions. The stage is immutable, an optional lane must be valid for it, and the committed row is then announced through the normal delivery port. Replaying a non-DLQ row fails rather than silently duplicating work.

remember ops rebuild

remember ops rebuild \
  --plane p2 \
  --deployment <deployment-uuid> \
  --snapshot-root ./snapshots \
  --workdir ./rebuild-work \
  --version drill-2026-07-21

--plane p2 invokes the production full graph rebuild; --plane p3 invokes the production corpus-filesystem builder. Both publish immutable snapshots through the same validation and pointer-swap path used normally. The command adds no separate recovery implementation. --workdir is consumed by P2 and accepted uniformly for P3.

remember review

The review commands require the [server] extra. They connect directly to the deployment's PostgreSQL spine via REMEMBERSTACK_DATABASE_URL (a SQLAlchemy/psycopg URL); the deployment id is an explicit argument.

remember review list

remember review list --deployment <deployment-uuid>

Prints the deployment's open review items — one JSON object per line — ranked by expected_impact (blast radius × (1 − confidence)): the highest-stakes item first. Items come from two sources:

• merge_cluster — an entity merge whose blast radius exceeded the auto-merge cap (hub merges never auto-merge); the candidate carries the proposed survivor and absorbed entity ids.
• support_withdrawn — a fact whose sole supporting claim was not re-derived after a toolchain upgrade re-read the unchanged source; no mechanical verdict is derivable, so a reviewer decides.

remember review decide

remember review decide <review-id> \
  --deployment <deployment-uuid> \
  --verdict <verdict> \
  --reviewer <handle> \
  [--note "free-text rationale"]

Applies one verdict. Every verdict appends the designed reversible rows — nothing is edited in place:

A verdict that does not fit the item's kind, or targets an already-decided item, fails with an error and exit code 1.