CLI
Help text for each command, generated from Meaning Memory 3.20.0. Run meaning-memory <command> --help for the same output on your install.
meaning-memory init
Section titled “meaning-memory init”Scaffold an agent workspace: configuration, consolidation bridge and README.
usage: meaning-memory init [-h] [--check | --doctor] [--agent-id AGENT_ID] [--backend {file,postgres}] [--dsn DSN] [--skip-pg-migration] [--workspace WORKSPACE] [--provider {stub,openai,anthropic,ollama,fleet}] [--non-interactive] [--budget-preset {lean,balanced,rich,max-context,default}] [--cron-schedule CRON_SCHEDULE] [--no-cron] [--force] [--skip-validate]
Quickstart wizard — generate a working agent workspace in <5 min.
options: -h, --help show this help message and exit --check Pre-flight environment check (terse). Exits 0 / 1 / 2 by severity; doesn't generate a workspace. --doctor Pre-flight environment check (verbose explainer). Lists each check + status + remediation hint. --agent-id AGENT_ID Agent identifier (alphanumeric + dashes/underscores, lowercase). Will be used as agents/<agent-id>.toml filename. REQUIRED for workspace generation; OMITTED in --check / --doctor mode. --backend {file,postgres} Storage backend. 'file' = FileBackend (SQLite + maildir journal; 30s setup). 'postgres' = PostgresBackend (production; requires --dsn or MM_POSTGRES_DSN env, runs alembic migration to head on init). --dsn DSN PostgreSQL DSN (required when --backend postgres unless MM_POSTGRES_DSN env is set). Format: postgresql://user:pass@host:port/dbname --skip-pg-migration Skip the alembic schema apply step when --backend postgres. Useful when the DB is already at the wheel's expected head (CI / re-runs). --workspace WORKSPACE Workspace directory to create. Defaults to ./<agent-id>-mm/ --provider {stub,openai,anthropic,ollama,fleet} LLM provider for the generated bridge handler. 'stub' = fixed-response stub (Phase 1A default; smoke-runnable without real LLM). 'openai' = OpenAI SDK (OPENAI_API_KEY env). 'anthropic' = Anthropic SDK (ANTHROPIC_API_KEY env). 'ollama' = local Ollama at OLLAMA_HOST. 'fleet' = fleet_llm.py router (MM_FLEET_LLM_PATH env). --non-interactive Use flag values + defaults; don't prompt. Phase 1A required this; Phase 2+ (v3.11.0) makes interactive the default when --agent-id is omitted or flags are partial. --budget-preset {lean,balanced,rich,max-context,default} Budget preset shorthand (v3.11.0). 'lean' (12K chars, small models), 'balanced' (25K, typical fleet agents; CLI default when omitted), 'rich' (40K, high-volume or 32K+ context), 'max-context' (60K, frontier models + per-type budgets ON). 'default' is a DEPRECATED alias for 'balanced'. Note the engine's own fallback — used only when neither preset nor TOML nor env chooses — is 40000 chars. Preset expands to explicit [budget] + [significance].pinned values in the generated mm-base.toml with a preset-name comment — no runtime magic. Sweet spot: 70-85% sustained utilization. Customers re-tune via direct TOML edits later. --cron-schedule CRON_SCHEDULE Cron schedule for consolidation runs (5-field syntax). Default: '0 5 * * *' (daily at 5 AM local time). Pass 'none' to skip cron file generation. --no-cron Skip cron file generation entirely. Equivalent to --cron-schedule none. --force Overwrite existing workspace files. Default: error if workspace exists. --skip-validate Skip the post-init `config validate` smoke check. Useful for tests.meaning-memory doctor
Section titled “meaning-memory doctor”Check an installation and explain anything that needs attention.
usage: meaning-memory doctor [-h] [--check CHECK] [--category CATEGORY] [--format {text,json}] [--strict-otlp] [--compliance] [--agent AGENT] [--workspace WORKSPACE] [--config-dir CONFIG_DIR] [--fix] [--preflight] [--profile {quickstart,prod,airgap}] [--profiles-toml PROFILES_TOML]
Meaning Memory deployment health diagnostic. Cron-friendly exit codes: 0=ok,1=degraded, 2=critical.
options: -h, --help show this help message and exit --check CHECK Run only the named check (e.g. 'conformance-harness'). --category CATEGORY Run only checks in the given category (schema, service, cron, backlog, config, audit). --format {text,json} Output format. Default: text (human-readable). --strict-otlp Upgrade OTLP-unreachable warnings to critical (exit 2). Off by default — partners with compliance-critical OTLP should opt in. --compliance (Stub) compliance attestation mode is tracked in; not in v3.7.0 scope. Use this flag in v3.8.0+. --agent AGENT Agent slug to validate (else $MM_AGENT). Required by 7-tier config-chain checks; without it those checks skip with OK. --workspace WORKSPACE Workspace root override (else read from config / $MM_WORKSPACE). --config-dir CONFIG_DIR Directory containing mm-base.toml + agents/<agent>.toml. --fix Advisory mode: print exact remediation commands for any failing check. NEVER auto-modifies — operator runs the commands. --preflight Preflight orchestration mode. Run a profile-bound suite of checks for deployment-readiness validation. Pair with --profile {quickstart|prod|airgap}. --profile {quickstart,prod,airgap} Preflight profile (requires --preflight). quickstart = minimal install validation; prod = full production readiness; airgap = prod minus network-egress checks. --profiles-toml PROFILES_TOML Override preflight profile definitions file. Default: customer-kit/docs/preflight-profiles.toml shipped with kit.meaning-memory schema
Section titled “meaning-memory schema”Apply or inspect the Postgres schema.
usage: meaning-memory schema [-h] (--apply | --check) [--dsn DSN] [--skip-pgvector-check] [-y] [--json]
Apply or check Meaning Memory PostgreSQL schema migrations.
options: -h, --help show this help message and exit --apply Apply migrations to head (idempotent if already at head) --check Show current vs target revision; exit 1 if apply needed --dsn DSN PostgreSQL DSN (overrides MM_POSTGRES_DSN env var) --skip-pgvector-check Bypass pgvector extension pre-flight check (for testing only) -y, --yes Skip the interactive confirmation prompt for --apply --json Emit machine-readable JSON for --check (no effect on --apply)meaning-memory consolidate
Section titled “meaning-memory consolidate”Run consolidation for an agent; --drain-only runs just the queue drain.
usage: meaning-memory consolidate [-h] --agent-id AGENT_ID [--workspace WORKSPACE] [--tenant-id TENANT_ID] [--workspace-root WORKSPACE_ROOT] [--team-id TEAM_ID] [--scope-visibility {private,team,tenant,public}] [--scope-subject-id SCOPE_SUBJECT_ID] [--reprocess-dates REPROCESS_DATES] [--force-advance-from FORCE_ADVANCE_FROM] [--dry-run] [--drain-only] [--promote-only] [--run-id RUN_ID] [--config-dir CONFIG_DIR] [--strict]
Run the Meaning Memory consolidation pipeline (Phase 0 drain → Phase 2snapshot → Phase 3 LLM extraction → Phase 4 compile → Phase 5 finalize).
options: -h, --help show this help message and exit --agent-id AGENT_ID Agent identifier slug (^[A-Za-z0-9_-]{1,64}$). Used as the agent name for config TOML lookup AND as the ConsolidationConfig.agent_id field. --workspace WORKSPACE Override workspace root (legacy single-tenant flag). Overrides MeaningMemoryConfig.workspace_root after TOML load. --tenant-id TENANT_ID multi-tenant identity slug. Requires --workspace-root. --workspace-root WORKSPACE_ROOT parent directory holding mm_tenant_<id>/ subdirs. --team-id TEAM_ID sub-tenant team scope. --scope-visibility {private,team,tenant,public} write-time scope tag. --scope-subject-id SCOPE_SUBJECT_ID subject ID (team or tenant) for non-private scope_visibility values. --reprocess-dates REPROCESS_DATES Comma-separated ISO dates (YYYY-MM-DD,...) to forcibly reprocess. --force-advance-from FORCE_ADVANCE_FROM Watermark rescue: advance the consolidation watermark past this date. Use to break out of a stuck-watermark loop. --dry-run Read journal + run extraction + report counts; do NOT mutate the ledger. Safe to invoke against a live workspace. --drain-only Run only Phase 0 (journal drain). Skip Phase 3/4/5. Used for journal clearing without LLM cost. --promote-only Run Phase 0 (journal drain) + the deterministic working promote-or-evaporate phase, then stop (skip Phases 2-5). Needs NO LLM handler — the lane for heartbeat-driven agents that never run a full nightly consolidation. Mutually exclusive with --drain-only. --run-id RUN_ID Explicit run identifier. Default: pipeline auto-generates. --config-dir CONFIG_DIR Override config directory (default: bundled config/). --strict Fail loud on unknown TOML keys.meaning-memory seed
Section titled “meaning-memory seed”Load an existing knowledge corpus into memory.
usage: meaning-memory seed [-h] --corpus-id CORPUS_ID [--format {jsonl,csv,auto}] [--dsn DSN] [--default-category DEFAULT_CATEGORY] [--default-source DEFAULT_SOURCE] [--default-significance DEFAULT_SIGNIFICANCE] [--default-decay-curve {none,step,exponential,inherit}] [--default-party DEFAULT_PARTY] [--auto-stare | --no-auto-stare] [--writer-agent-id WRITER_AGENT_ID] [--writer-tenant-id WRITER_TENANT_ID] [--writer-role {admin,agent,human,system}] [--dry-run] [--verbose] [--config-dir CONFIG_DIR] corpus_file
Bulk-ingest a customer seed corpus into the Meaning Memory ledger.
positional arguments: corpus_file Path to JSONL or CSV file with one memory per row.
options: -h, --help show this help message and exit --corpus-id CORPUS_ID Batch identifier for this seed corpus (e.g. 'product-catalog-2026-q3'). Indexed; enables 'show all my seeded memories' + re-seed workflows. --format {jsonl,csv,auto} Input file format. 'auto' (default) detects from extension. --dsn DSN Postgres DSN (overrides MM_POSTGRES_DSN env var). Omit for FileBackend deployments — backend autodetected via MM_BACKEND. --default-category DEFAULT_CATEGORY Applied when a row omits 'category' (default: fact). --default-source DEFAULT_SOURCE Applied when a row omits 'source' (default: seed). --default-significance DEFAULT_SIGNIFICANCE Applied when a row omits 'significance' (default: 0.80). --default-decay-curve {none,step,exponential,inherit} Applied when a row omits 'decay_curve' (default: 'none' — seed corpora survive consolidation decay). Pass 'inherit' to leave decay_curve unset (entries inherit category default). --default-party DEFAULT_PARTY Applied when a row omits 'party' (default: unset). --auto-stare, --no-auto-stare When a row omits STARE scores, auto-extract via the bundled distilled scorer (default: enabled). Use --no-auto-stare to leave dims NULL (consolidation can fill later). Bundled extras (meaning-memory[stare-bundled]) required. --writer-agent-id WRITER_AGENT_ID Writer agent ID for the whole batch (default: from MM_AGENT env). --writer-tenant-id WRITER_TENANT_ID Writer tenant ID for the whole batch (default: 'default'). --writer-role {admin,agent,human,system} Sig RBAC writer role for the whole batch. Omit the flag to inherit the per-entry default ('agent'). One of: admin, agent, human, system. --dry-run Parse + validate input without writing to the backend. --verbose, -v Print per-row progress. --config-dir, --workspace CONFIG_DIR Directory holding mm-base.toml + agents/<agent>.toml — i.e. the workspace scaffolded by `meaning-memory init --workspace <dir>`. Lets seed compose with init for a custom --writer-agent-id. Omit to use the packaged default config (example-agent).meaning-memory capture-session
Section titled “meaning-memory capture-session”Store a session transcript as working memory for Throughline.
usage: meaning-memory capture-session [-h] --agent AGENT --session-id SESSION_ID --channel CHANNEL --source-kind {chat,cron,heartbeat} [--surface SURFACE] (--transcript PATH | --plain PATH) [--raw-session PATH] [--conversation-id CONVERSATION_ID] [--episode-id EPISODE_ID] [--scope-groups SCOPE_GROUPS] [--sig-summary SIG_SUMMARY] [--sig-keyline SIG_KEYLINE] [--sig-event SIG_EVENT] [--max-keylines MAX_KEYLINES] [--dry-run] [--config-dir CONFIG_DIR]
Distill a session/cron transcript into working-stage memory entries(Throughline capture — deterministic, no LLM).
options: -h, --help show this help message and exit --agent AGENT Capturing agent slug (workspace + config identity). --session-id SESSION_ID Stable session identifier (idempotency scope). --channel CHANNEL Where the session happened, e.g. 'telegram:dm', 'slack:support', 'cron:morning-briefing'. --source-kind {chat,cron,heartbeat} Producer class. cron/heartbeat get the machine-source significance clamp. --surface SURFACE Optional coarse surface label (telegram, slack, cron, …). --transcript PATH JSONL transcript {role, content, ts?, author?}; '-' reads stdin. --plain PATH Plain-text blob (no role attribution → summary artifact only, no key-lines; '-' reads stdin). --raw-session PATH Raw gateway session JSONL for the observation-archive dual-write (full fidelity — the --transcript stream is the adapter-reduced keyline feed and lacks tool payloads/receipts). Only honored with MM_OBSERVATIONS_CAPTURE=1 on a Postgres backend. Incompatible with --plain (unattributed blobs must never become human-attributed archive events). --conversation-id CONVERSATION_ID Conversation identity for the observation-archive dual-write (the gateway's session key, e.g. agent:support-bot:telegram:direct:<id>). Direct-shaped values also yield the counterpart in audience when the envelope prescan derives none. Ignored without --raw-session. --episode-id EPISODE_ID Optional episode UUID to stamp (E-dim stitch). --scope-groups SCOPE_GROUPS Comma-separated scope groups (default: private). --sig-summary SIG_SUMMARY Significance of the session summary (default 0.55). --sig-keyline SIG_KEYLINE Significance of each key line (default 0.65). --sig-event SIG_EVENT Significance of each recorded tool action (default 0.55). --max-keylines MAX_KEYLINES Most key lines kept per session (default 4). --dry-run Print the artifact plan; write nothing. --config-dir, --workspace CONFIG_DIR Directory holding mm-base.toml + agents/<agent>.toml.meaning-memory export
Section titled “meaning-memory export”Export memories to backend-agnostic JSONL.
usage: meaning-memory export [-h] --backend {file,postgres} --output OUTPUT [--dsn DSN] [--workspace WORKSPACE] [--agent AGENT] [--tenant-id TENANT_ID] [--include-embeddings]
options: -h, --help show this help message and exit --backend {file,postgres} --output OUTPUT Output directory path --dsn DSN Postgres DSN (when --backend postgres) --workspace WORKSPACE Workspace path (when --backend file) --agent AGENT Agent identity (any backend) --tenant-id TENANT_ID Scope export to a single tenant (default: 'default') --include-embeddings Include embedding vectors in the export (significantly larger, PG only)meaning-memory import
Section titled “meaning-memory import”Import a JSONL export into a deployment.
usage: meaning-memory import [-h] --target {file,postgres} --input INPUT [--dsn DSN] [--workspace WORKSPACE] [--agent AGENT]
options: -h, --help show this help message and exit --target {file,postgres} --input INPUT Input directory path (must contain manifest.json) --dsn DSN Postgres DSN (when --target postgres — Phase 2) --workspace WORKSPACE Workspace path (when --target file) --agent AGENT Agent identity for the target backendmeaning-memory serve
Section titled “meaning-memory serve”Run the REST API server.
usage: meaning-memory serve [-h] [--dsn DSN | --ledger LEDGER] [--events EVENTS] [--host HOST] [--port PORT] [--token TOKEN | --token-env TOKEN_ENV | --no-auth] [--reload] [--workers WORKERS]
Launch the REST/OpenAPI server. Bearer-token auth via--token / --token-env / --no-auth.
options: -h, --help show this help message and exit --dsn DSN Postgres DSN. Mutually exclusive with --ledger. Explicit CLI arg wins over MM_POSTGRES_DSN env. --ledger LEDGER Path to ledger.md (FileBackend). Mutually exclusive with --dsn. Explicit CLI arg wins over MM_POSTGRES_DSN env. --events EVENTS Path to events.jsonl (default: alongside ledger). --host HOST Bind address (default: 127.0.0.1; use 0.0.0.0 to expose). --port PORT Bind port (default: 8890). --token TOKEN Bearer token (literal). Inadvisable for prod (visible in process list). --token-env TOKEN_ENV Env var to read the bearer token from (default: MM_REST_TOKEN). --no-auth Disable auth. ONLY for localhost dev probes — never bind to non-localhost without auth. --reload uvicorn --reload (dev mode). --workers WORKERS uvicorn worker count (default 1; >1 requires gunicorn-style deployment).meaning-memory config
Section titled “meaning-memory config”Inspect and validate configuration.
usage: meaning-memory config [-h] {validate,inspect,generate,explain} ...
positional arguments: {validate,inspect,generate,explain} validate Validate agent config inspect Print resolved config generate Generate mm.conf explain Show resolved value + each contributing layer for a config key
options: -h, --help show this help message and exitmeaning-memory version
Section titled “meaning-memory version”Print the engine version.
usage: meaning-memory version [-h]
options: -h, --help show this help message and exitAdministration
Section titled “Administration”meaning-memory-admin manages a Postgres deployment. Global options such as --config come before the command.
meaning-memory-admin group sync
Section titled “meaning-memory-admin group sync”Make the scope groups and memberships in the database match the access policy. See Scoping and sharing memory.
usage: meaning-memory-admin group sync [-h] [--tenant TENANT] [--dry-run] [--actor ACTOR]
options: -h, --help show this help message and exit --tenant TENANT Only this tenant_id. --dry-run Show the changes without making them. --actor ACTOR Name recorded as the operator on each change (default: group-sync).