CLI Reference

Source of truth: src/cli/index.ts. The topical sections below are hand-written narrative. The Command reference (generated) appendix at the bottom is regenerated by npm run docs:cli and checked in CI (roadmap P4-2). If the code and this page disagree, the code wins — run npm run docs:cli and commit the diff.

All commands emit pure JSON on stdout, logs on stderr — safe for piping, scripts, and MCP wrappers. Exit code is 0 on success, non-zero on error.

# Local dev
npx tsx src/cli/index.ts <command> [options]

# After npm run build + npm install -g
memory <command> [options]

Retrieval

`retrieve <query>`

Query memory for relevant entries. Returns a contract v1 envelope.

memory retrieve "how are invoices calculated?" \
  --layer 2 --budget 2000 --limit 10 --repository my-app

Option	Default	Notes
`--layer <n>`	`2`	`1` = index, `2` = summary, `3` = full details
`--budget <tokens>`	`2000`	max total token budget
`--limit <n>`	—	cap result count
`--low-trust`	off	include stale / low-score entries, marked in response
`--type <t>`	—	filter by memory type (repeatable)
`--repository <id>`	—	scope to one repository

Ingestion & Promotion

`ingest` — direct quarantined entry

One-shot: create → quarantine. Parity with mcp.memory_ingest.

memory ingest \
  --type architecture_decision \
  --title "Use event sourcing for order aggregate" \
  --summary "All order state changes go through domain events." \
  --repository my-app \
  --file src/order/aggregate.ts --symbol Order

Required: --type --title --summary --repository. Optional: --details --file --symbol --module --impact --knowledge-class --created-by.

`propose` — create with gate inputs

Like ingest but records proposal metadata used by promote.

memory propose --type bug_pattern --title "N+1 on invoice list" \
  --summary "..." --repository my-app \
  --source "incident-42" --confidence 0.7 \
  --scenario "paginated-list" --scenario "export"

Required: --type --title --summary --repository --source --confidence. Inherits --details --file --symbol --module --impact --knowledge-class --created-by from ingest.

Extra flags:

Option	Default	Notes
`--scenario <text>`	—	future-scenario citation (repeatable; ≥ 3 required for non-low impact)
`--gate-clean`	off	assert extraction-guard was clean at proposal time
`--gate-not-clean`	off	mark extraction-guard as failing — proposal will be rejected on `promote`

`promote <proposal-id>`

Move a quarantined proposal through gate criteria. The proposal ID is the id field returned by propose.

memory promote <proposal-id>
memory promote <proposal-id> --allowed-type architecture_decision --allowed-type coding_convention
memory promote <proposal-id> --skip-duplicate-check

Option	Default	Notes
`--allowed-type <type>`	—	consumer-policy allow-list (repeatable)
`--skip-duplicate-check`	off	caller accepts an existing sibling entry
`--triggered-by <actor>`	`cli:promote`	caller identifier for audit

Fails with a structured error if any gate is not satisfied (missing evidence, <3 future decisions, disallowed target type, duplicate without --skip-duplicate-check).

`validate <entry-id>`

Re-run file / symbol / diff / test validators against an entry. Does not change status unless all validators agree.

Invalidation & Rollback

`invalidate`

Mark an entry or a set of entries as stale (soft) or invalidated (hard). The git-diff sweep always compares the given ref (or date) against current HEAD — there is no --to-ref flag.

# Single entry, soft
memory invalidate --entry <uuid> --reason "superseded by ADR-019"

# Hard invalidation (fully wrong)
memory invalidate --entry <uuid> --hard --reason "function deleted"

# Bulk from git diff (ref-based: main..HEAD)
memory invalidate --from-git-diff --from-ref main

# Bulk from git diff (date-based: since date..HEAD)
memory invalidate --from-git-diff --since 2025-04-01

Option	Default	Notes
`--entry <id>`	—	invalidate a single entry
`--hard`	soft	entry is completely wrong (not just stale)
`--reason <text>`	`cli:invalidate`	human-readable reason for the audit log
`--from-git-diff`	off	sweep all entries affected by a git diff
`--from-ref <ref>`	—	git ref to compare from (with `--from-git-diff`)
`--since <date>`	—	ISO date alternative to `--from-ref`
`--triggered-by <actor>`	`cli:invalidate`	caller identifier

`poison <entry-id> <reason>`

Confirm entry is wrong. Triggers cascade review of every entry derived from it via evidence links. Writes a rollback report.

memory poison <uuid> "root-cause turned out to be a misread stack trace"

Both the entry ID and a reason are required positional arguments. Optional: --triggered-by <actor> (default cli:poison).

`rollback <entry-id>`

Report + invalidate every task influenced by a poisoned entry. See src/invalidation/rollback.ts for the report shape.

memory rollback <uuid> --reason "cascading from poison(<uuid>)"

Optional: --reason <text> (default cli:rollback), --triggered-by <actor> (default cli:rollback).

`verify <entry-id>`

Trace an entry back to its source evidence. Returns a provenance chain: entry → evidence refs → upstream entries that cite the same ref.

Observability

`health`

Backend health probe. Returns contract v1 envelope with status, features[], backend_version. Exit code 0 = healthy, non-zero = fail. Use in CI to gate deploys.

memory health --timeout 2000

`status`

Lightweight liveness check for consumers. Prints present | absent | misconfigured.

memory status               # exit 0, stdout = one word
memory status --json        # full envelope, always exits 0

`diagnose`

List stale entries, low-trust entries, and known contradictions.

memory diagnose --max-results 20

`doctor`

Self-diagnosing environment check. Verifies DATABASE_URL is reachable, the pgvector extension is installed, all migrations are applied, and (optionally) @event4u/agent-config symlinks are intact.

Writes a human-readable summary to stderr and a JSON report to stdout. Exit code: 0 if healthy or warnings-only, 1 if any check fails.

memory doctor                 # human summary on stderr + JSON on stdout
memory doctor --json          # JSON only (no stderr summary)
memory doctor | jq '.status'  # → "healthy" | "warnings" | "unhealthy"

Checks:

env.DATABASE_URL — explicit env var vs. dev default
db.connect — TCP + auth against Postgres
db.pgvector — extension present and version
db.migrations — every migration in memory_migrations
agent-config — optional; symlinks under .augment/commands/

Pattern: piping

Every command emits JSON — compose with jq:

memory retrieve "auth flow" --layer 3 | jq '.data.entries[].title'
memory health | jq -e '.data.status == "ok"'   # 0 if healthy

Command reference (generated)

This appendix is regenerated by npm run docs:cli from the Commander program in src/cli/index.ts. It lists every command, argument, flag, default, and required-ness the real CLI accepts. If this section and the code disagree, the code wins — the CI drift guard will fail the build.

`audit`

Run audits across memory stores (subcommands)

memory audit

`contradictions`

List unresolved memory contradictions (B3 · runtime-trust)

memory contradictions [options]

Options

Flag	Required	Default	Description
`--repository <repo>`	no	—	Filter to entries whose scope.repository matches
`--since <ts>`	no	—	ISO-8601 timestamp — only contradictions created at or after
`--limit <n>`	no	`50`	Max rows to return
`--json`	no	—	Emit JSON list instead of human output

`diagnose`

Identify issues: stale entries, low-trust entries

memory diagnose [options]

Options

Flag	Required	Default	Description
`--max-results <n>`	no	`10`	Max entries per category
`--entry <id>`	no	—	Show trust-audit event-count breakdown for a single entry (B4)

`doctor`

Diagnose environment: DATABASE_URL, pgvector, migrations, agent-config

memory doctor [options]

Options

Flag	Required	Default	Description
`--json`	no	off	Emit JSON only (no human summary on stderr)
`--fix`	no	off	Auto-repair pgvector + pending migrations, then re-diagnose

`explain`

Explain how a memory entry's trust_score was calculated (B1 · runtime-trust)

memory explain <id> [options]

Arguments

Name	Required	Description
`<id>`	yes	—

Options

Flag	Required	Default	Description
`--json`	no	—	Emit explain-v1 JSON envelope instead of human output

`export`

Export memory entries + events + evidence as JSONL (D1 · runtime-trust)

memory export [options]

Options

Flag	Required	Default	Description
`--since <iso>`	no	—	Only entries with updated_at >= ISO timestamp
`--repository <id>`	no	—	Only entries scoped to this repository

`health`

Probe backend health — returns contract v1 envelope as JSON

memory health [options]

Options

Flag	Required	Default	Description
`--timeout <ms>`	no	`2000`	Timeout in ms

`history`

Print the trust-transition timeline for a memory entry (B2 · runtime-trust)

memory history <id> [options]

Arguments

Name	Required	Description
`<id>`	yes	—

Options

Flag	Required	Default	Description
`--json`	no	—	Emit history-v1 JSON envelope instead of human output
`--since <ts>`	no	—	ISO-8601 timestamp — only events at or after this time

`import`

Import a JSONL export back into the store (D1 · runtime-trust)

memory import <file> [options]

Arguments

Name	Required	Description
`<file>`	yes	—

Options

Flag	Required	Default	Description
`--on-conflict <mode>`	no	`fail`	What to do when an entry id already exists: fail
`--from <format>`	no	`agent-memory-v1`	Source format: agent-memory-v1
`--repository <id>`	no	—	Target repository scope (required for non-native formats)
`--initial-trust <score>`	no	—	Initial trust score for non-native imports (0..1, default 0.5)
`--quarantine`	no	—	Import non-native records as quarantine instead of validated

`ingest`

Create a memory entry in quarantine (one-shot; parity with mcp.memory_ingest)

memory ingest [options]

Options

Flag	Required	Default	Description
`--type <type>`	yes	—	Memory type (e.g., architecture_decision)
`--title <title>`	yes	—	Short title
`--summary <summary>`	yes	—	One-paragraph summary
`--details <details>`	no	—	Optional long-form details
`--repository <repository>`	yes	—	Repository identifier
`--file <path>`	no	—	File in scope (repeatable)
`--symbol <symbol>`	no	—	Symbol in scope (repeatable)
`--module <module>`	no	—	Module in scope (repeatable)
`--impact <level>`	no	`normal`	Impact level (critical
`--knowledge-class <class>`	no	`semi_stable`	Knowledge class (evergreen
`--created-by <actor>`	no	`cli:ingest`	Caller identifier

`init`

Bootstrap a consumer project: docker-compose.agent-memory.yml, .env.agent-memory, .gitignore marker

memory init [options]

Options

Flag	Required	Default	Description
`--yes`	no	off	Non-interactive mode (assume yes to prompts)
`--force`	no	off	Overwrite existing files instead of skipping

`invalidate`

Mark entries as stale or rejected (soft/hard or git-diff sweep)

memory invalidate [options]

Options

Flag	Required	Default	Description
`--entry <id>`	no	—	Invalidate a specific entry
`--hard`	no	—	Hard invalidation (entry is completely wrong)
`--reason <text>`	no	`cli:invalidate`	Reason for invalidation
`--from-git-diff`	no	—	Run git-diff invalidation orchestrator (sweeps all affected entries)
`--from-ref <ref>`	no	—	Git ref to compare from (with --from-git-diff)
`--since <date>`	no	—	Alternative to --from-ref — ISO date (with --from-git-diff)
`--triggered-by <actor>`	no	`cli:invalidate`	Caller identifier

`mcp`

Start the MCP server (stdio by default; --transport sse exposes HTTP/SSE)

memory mcp [options]

Options

Flag	Required	Default	Description
`--transport <kind>`	no	`stdio`	Transport: stdio (default)
`--port <n>`	no	—	SSE port (only when --transport=sse; default 7078)
`--host <host>`	no	`0.0.0.0`	SSE bind host (only when --transport=sse; default 0.0.0.0)

`migrate`

Database migrations — up (default) applies pending, status prints applied/pending as JSON

memory migrate

`poison`

Mark an entry as poisoned — cascade review + rollback report

memory poison <id> <reason> [options]

Arguments

Name	Required	Description
`<id>`	yes	Memory entry ID
`<reason>`	yes	Why this entry is wrong

Options

Flag	Required	Default	Description
`--triggered-by <actor>`	no	`cli:poison`	Caller identifier

`policy`

Project policy engine (C2) — gate PRs on memory-state violations.

memory policy

`promote`

Promote a quarantined proposal through gate criteria

memory promote <proposal-id> [options]

Arguments

Name	Required	Description
`<proposal-id>`	yes	Proposal ID returned by `propose`

Options

Flag	Required	Default	Description
`--allowed-type <type>`	no	—	Allowed target type (repeatable; consumer policy)
`--skip-duplicate-check`	no	off	Skip non-duplication gate (caller accepts the sibling)
`--triggered-by <actor>`	no	`cli:promote`	Caller identifier

`propose`

Propose a new memory entry (lands in quarantine; not served until promoted)

memory propose [options]

Options

Flag	Required	Default	Description
`--type <type>`	yes	—	Memory type (e.g., architecture_decision)
`--title <title>`	yes	—	Short title
`--summary <summary>`	yes	—	One-paragraph summary
`--details <details>`	no	—	Optional long-form details
`--repository <repository>`	yes	—	Repository identifier
`--file <path>`	no	—	File in scope (repeatable)
`--symbol <symbol>`	no	—	Symbol in scope (repeatable)
`--module <module>`	no	—	Module in scope (repeatable)
`--impact <level>`	no	`normal`	Impact level (critical
`--knowledge-class <class>`	no	`semi_stable`	Knowledge class (evergreen
`--source <source>`	yes	—	Source ref (incident id, PR, ADR)
`--confidence <n>`	yes	`0.6`	Initial confidence 0.0–1.0
`--scenario <text>`	no	—	Future scenario (repeat 3+ times for non-low impact)
`--gate-clean`	no	off	Assert extraction-guard was clean at proposal time
`--gate-not-clean`	no	off	Mark extraction-guard as failing (will cause rejection on promote)
`--created-by <actor>`	no	`cli:propose`	Caller identifier

`retrieve`

Query memory for relevant knowledge (contract v1 envelope)

memory retrieve <query> [options]

Arguments

Name	Required	Description
`<query>`	yes	Natural language query

Options

Flag	Required	Default	Description
`--layer <n>`	no	`2`	Disclosure layer (1
`--budget <tokens>`	no	`2000`	Max token budget
`--limit <n>`	no	—	Max result count
`--low-trust`	no	—	Include low-trust entries (lower threshold, marked)
`--type <type>`	no	—	Filter by memory type (repeatable)
`--repository <id>`	no	—	Filter by repository

`review`

Triage open memory cases: accept/defer/skip (B3 · runtime-trust)

memory review [options]

Options

Flag	Required	Default	Description
`--weekly`	no	—	Non-interactive digest of open cases
`--format <fmt>`	no	`json`	Output format for --weekly: json
`--actor <actor>`	no	`human:review-cli`	Audit actor for accept/defer/skip writes

`rollback`

Roll back a poisoned entry — report affected tasks + cascaded entries

memory rollback <id> [options]

Arguments

Name	Required	Description
`<id>`	yes	Memory entry ID to roll back

Options

Flag	Required	Default	Description
`--reason <text>`	no	`Rolled back via CLI`	Why this entry is being rolled back
`--triggered-by <actor>`	no	`cli:rollback`	Caller identifier

`serve`

Long-running supervisor for container deployments — runs migrations, then idles until SIGTERM (see ADR-0002)

memory serve

`status`

Feature detection for consumers — prints present | absent | misconfigured

memory status [options]

Options

Flag	Required	Default	Description
`--timeout <ms>`	no	`2000`	Timeout in ms
`--json`	no	—	Emit full JSON envelope (always exits 0)

`validate`

Run validators against a quarantined entry

memory validate <id> [options]

Arguments

Name	Required	Description
`<id>`	yes	Memory entry ID

Options

Flag	Required	Default	Description
`--triggered-by <actor>`	no	`cli:validate`	Caller identifier

`verify`

Trace a memory entry to its evidence, contradictions, and audit trail

memory verify <id>

Arguments

Name	Required	Description
`<id>`	yes	Memory entry ID

FilesExpand file tree

cli-reference.md

Latest commit

History

cli-reference.md

File metadata and controls

CLI Reference

Retrieval

retrieve <query>

Ingestion & Promotion

ingest — direct quarantined entry

propose — create with gate inputs

promote <proposal-id>

validate <entry-id>

Invalidation & Rollback

invalidate

poison <entry-id> <reason>

rollback <entry-id>

verify <entry-id>

Observability

health

status

diagnose

doctor

Pattern: piping

Command reference (generated)

audit

contradictions

diagnose

doctor

explain

export

health

history

import

ingest

init

invalidate

mcp

migrate

poison

policy

promote

propose

retrieve

review

rollback

serve

status

validate

verify

`retrieve <query>`

`ingest` — direct quarantined entry

`propose` — create with gate inputs

`promote <proposal-id>`

`validate <entry-id>`

`invalidate`

`poison <entry-id> <reason>`

`rollback <entry-id>`

`verify <entry-id>`

`health`

`status`

`diagnose`

`doctor`

`audit`

`contradictions`

`diagnose`

`doctor`

`explain`

`export`

`health`

`history`

`import`

`ingest`

`init`

`invalidate`

`mcp`

`migrate`

`poison`

`policy`

`promote`

`propose`

`retrieve`

`review`

`rollback`

`serve`

`status`

`validate`

`verify`