CLI Reference

This file is auto-generated from @psraghuveer/memento-core/commands via pnpm docs:generate. Do not edit by hand.

Every command in the registry whose surfaces set includes cli is reachable through the memento binary.

The dotted command name maps to the subcommand path: memory.write is invoked as memento memory write.

Argument and flag definitions live in source; this reference lists invocations, descriptions, and side-effect class.

Invocation

memento [<global-flags>] <command> [<args>]

Global flags must appear before the subcommand. Registry commands read structured input via --input <json>, --input @file, --input - (stdin), or no flag at all (defaults to {}).

Global flags

Flag	Description
`--db <path>`	Database path. Env: `MEMENTO_DB`. Default: `$XDG_DATA_HOME/memento/memento.db` (POSIX: `~/.local/share/memento/memento.db`; Windows: `%LOCALAPPDATA%\memento\memento.db`).
`--format json\|text\|auto`	Output format. Env: `MEMENTO_FORMAT`. Default: `auto` (json on a pipe, text on a tty).
`--debug`	Print stack traces for unhandled errors.
`--version, -V`	Print the memento version and exit.
`--help, -h`	Print help and exit.

Lifecycle commands

Lifecycle commands sit outside the registry. They manage the CLI process itself (database initialization, MCP transport, runtime introspection) and do not have input/output schemas.

`memento backup`

Create a point-in-time copy of the database (uses SQLite VACUUM INTO)

`memento completions`

Emit a shell completion script (bash, zsh, or fish)

`memento context`

Print runtime context (db, version, registered commands, config snapshot)

Example. Print a JSON snapshot of the running CLI:

memento --db /tmp/example.db --format json context

The response is a Result envelope. On success, value carries the version, the resolved DB path, every registered command (with its surface set and side-effect class), and a snapshot of every config key. Truncated for readability:

{
  "ok": true,
  "value": {
    "version": "0.1.0",
    "dbPath": "/tmp/example.db",
    "registry": {
      "commands": [
        {
          "name": "memory.write",
          "sideEffect": "write",
          "surfaces": ["mcp", "cli"],
          "description": "Create a new memory in the given scope."
        }
      ]
    },
    "config": {
      "retrieval.vector.enabled": false,
      "embedder.local.model": "bge-small-en-v1.5",
      "embedder.local.dimension": 384
    }
  }
}

The full snapshot lists every command in the registry and every key in the config schema. --format text pretty-prints the same JSON; --format auto (the default) chooses based on whether stdout is a TTY.

`memento dashboard`

Launch the local web dashboard (browser UI for browsing and curating memory)

`memento doctor`

Run diagnostic checks (Node version, database access, optional dependencies)

Example. Verify a fresh install:

memento --db /tmp/example.db --format json doctor

The response is a Result envelope. On success, value.checks reports one entry per check (Node version, DB path, database open, embedder peer dep) with a stable name, a boolean ok, and a human-readable message. On failure, the same array ships in error.details so a bug report can include the full diagnostic without rerunning. DB-class failures map to STORAGE_ERROR (exit 5); other failures map to CONFIG_ERROR (exit 4).

`memento explain`

Print the catalogued meaning of an error code (e.g. STORAGE_ERROR)

`memento export`

Export the configured database to a portable memento-export/v1 JSONL artefact (ADR-0013)

`memento import`

Import a memento-export/v1 JSONL artefact into the configured database (ADR-0013, ADR-0019)

`memento init`

Initialise the database and print MCP client setup snippets

`memento pack`

Install, preview, uninstall, list, or author memento packs (curated YAML bundles, ADR-0020).

`memento ping`

Spawn memento serve, list tools over MCP stdio, exit

`memento serve`

Run the MCP server over stdio (blocks until the peer disconnects)

`memento skill-path`

Print the absolute path of the bundled Memento skill (for $(…) shell embedding)

`memento status`

Print a one-screen summary of the install (counts, last event, db size)

`memento store migrate`

Run pending database migrations against the configured store

`memento uninstall`

Print teardown instructions (config paths and database location)

`memento verify-setup`

Spawn the MCP server and round-trip a write/read to prove the wiring works

Registry commands

Total: 38 commands.

`memento compact run`

Run a compaction pass to archive cold memories whose effective confidence has fallen below the decay threshold and have not been confirmed within the archive window. Idempotent.

Defaults to mode: "drain" — loops until a pass archives nothing or compact.run.maxBatches is reached. Pass mode: "batch" to perform exactly one pass (the legacy single-batch behaviour).

Side-effect: admin — Operational / introspection.

`memento config get`

Resolved value for one config key, with source / actor / timestamp.

Side-effect: read — Pure read; safe to call freely.

`memento config history`

All ConfigEvents for one key, oldest-first. Optional limit.

Side-effect: read — Pure read; safe to call freely.

`memento config list`

Enumerate all registered config keys with their resolved values and provenance. Optional dotted prefix filter.

Side-effect: read — Pure read; safe to call freely.

`memento config set`

Set a config key at runtime. Persists a ConfigEvent to the audit log and updates the in-memory store. Rejects keys marked mutable: false with IMMUTABLE.

Side-effect: write — Mutates state and emits an audit-log event.

`memento config unset`

Clear the runtime override for a config key. The key reverts to whichever lower layer (defaults / startup overrides) had it last. Persists a ConfigEvent with newValue: null.

Side-effect: write — Mutates state and emits an audit-log event.

`memento conflict events`

All events for one conflict, oldest first.

Side-effect: read — Pure read; safe to call freely.

`memento conflict list`

List conflicts. Filters AND together; ordering is opened_at desc, id desc.

Side-effect: read — Pure read; safe to call freely.

`memento conflict read`

Fetch a single conflict by id, or null if absent.

Side-effect: read — Pure read; safe to call freely.

`memento conflict resolve`

Resolve an open conflict. Writes a resolved event with the chosen resolution.

Side-effect: write — Mutates state and emits an audit-log event.

`memento conflict scan`

Run conflict detection. In memory mode, evaluates per-kind policies for one hydrated memory. In since mode, replays detection over every active memory created at or after the given timestamp — used to recover from missed post-write hooks.

Side-effect: write — Mutates state and emits an audit-log event.

`memento embedding rebuild`

Rebuild embeddings for active memories whose stored embedding does not match the configured provider. Page by re-invoking with the same options; per-row provider errors are recorded as skips and do not halt the batch.

Side-effect: admin — Operational / introspection.

`memento memory archive`

Move a memory to long-term storage. Idempotent on already-archived rows. Requires confirm: true.

Example:

{"id":"01HYXZ...","confirm":true}

Side-effect: destructive — Bulk or irreversible; the CLI requires --confirm to execute.

`memento memory archive_many`

Bulk-archive memories matching a filter. Idempotent on already-archived rows. Requires confirm: true. Defaults to dryRun=true (preview only); set dryRun=false to apply.

Example (dry run):

{"filter":{"kind":"snippet","pinned":false},"confirm":true}

Side-effect: destructive — Bulk or irreversible; the CLI requires --confirm to execute.

`memento memory confirm`

Re-affirm an active memory (bumps lastConfirmedAt, resetting confidence decay).

Example:

{"id":"01HYXZ..."}

Side-effect: write — Mutates state and emits an audit-log event.

`memento memory confirm_many`

Bulk-confirm multiple active memories in one call (resets confidence decay for each).

Example:

{"ids":["01HYXZ...","01HYXY..."]}

Side-effect: write — Mutates state and emits an audit-log event.

`memento memory context`

Load the most relevant memories for the current session without a search query. Uses ranked retrieval based on confidence, recency, scope, pinned status, and confirmation frequency.

Call at the start of a task to load context. No arguments required — returns the top memories from config-driven defaults.

Every result's memory carries an embeddingStatus field ("present" | "stale" | "pending" | "disabled") so callers can tell whether a row contributed via vector similarity at all. stale means the embedding exists but its model/dim mismatches the configured embedder (run embedding.rebuild to refresh).

Examples:

Default: {}
Scoped: {"scopes":[{"type":"repo","remote":"github.com/org/app"},{"type":"global"}]}
Filtered: {"kinds":["preference","decision"],"limit":10}
Side-effect: read — Pure read; safe to call freely.

`memento memory events`

Read the audit log: events for one memory (ascending) when id is given, otherwise recent events across all memories (descending).

Optional types, since, until, and limit narrow the result set; since/until filter on the event at timestamp (half-open: at >= since AND at < until). There is no scope / kind / tag filter — events are not denormalised by those dimensions.

Side-effect: read — Pure read; safe to call freely.

`memento memory extract`

Batch-extract candidate memories from a conversation. The server handles dedup, scrubbing, and writing. The assistant's job is reduced to dumping "what seemed worth remembering."

Candidate shape (ADR-0027) — memory.extract and memory.write share one shape. kind is a discriminated-union object: {"type":"fact"}, {"type":"preference"}, {"type":"decision","rationale":"..."}, {"type":"todo","due":null}, {"type":"snippet","language":"typescript"}. The per-kind fields (rationale, language) live INSIDE the kind object — not as top-level siblings.

Topic-line rule — for preference and decision candidates, the content MUST start with a topic: value line followed by a blank line and prose. The conflict detector parses that first line; the server rejects offending writes with INVALID_INPUT (gated by safety.requireTopicLine, default true). The whole batch is rejected on the first offending candidate, not just the bad item.

Dedup runs at two scopes: (1) in-batch — byte-identical candidates within the same call collapse to a single memory (kind-aware fingerprint); (2) cross-batch — embeddings are compared against existing active memories via the configured similarity thresholds (≥extraction.dedup.identicalThreshold skips, between that and extraction.dedup.threshold supersedes, below writes new). When in doubt, include the candidate.

Storage defaults — extracted memories are written at storedConfidence: 0.8 (lower than memory.write's 1.0) so they decay faster and get pruned if never confirmed.

Processing mode — the response carries a mode field. extraction.processing defaults to auto (sync for batches ≤ extraction.syncThreshold, async above); explicit sync and async overrides remain. When mode: "sync" the written / skipped / superseded arrays are authoritative and you can report them directly. When mode: "async" those arrays are intentionally empty — the server accepted the batch and is processing in background; the hint field explains what to expect. Do not retry on async receipts.

Example (note the nested kind on every variant):

{"candidates":[
  {"kind":{"type":"preference"},"content":"editor-theme: dark\n\nUser prefers dark mode in all editors."},
  {"kind":{"type":"fact"},"content":"The production database is PostgreSQL 15."},
  {"kind":{"type":"decision","rationale":"Single-file, no daemon, FTS5 built in."},"content":"storage-engine: SQLite\n\nChosen for the local-first story."},
  {"kind":{"type":"snippet","language":"shell"},"content":"memento read <id>"}
]}

Side-effect: write — Mutates state and emits an audit-log event.

`memento memory forget`

Soft-remove an active memory; reversible via memory.restore.

Example:

{"id":"01HYXZ...","reason":"No longer relevant","confirm":true}

Side-effect: destructive — Bulk or irreversible; the CLI requires --confirm to execute.

`memento memory forget_many`

Bulk-soft-remove active memories matching a filter. Requires confirm: true. Defaults to dryRun=true (preview only); set dryRun=false to apply.

Example (dry run):

{"filter":{"kind":"todo"},"reason":"Completed sprint","confirm":true}

Side-effect: destructive — Bulk or irreversible; the CLI requires --confirm to execute.

`memento memory list`

List memories matching the given filter, newest first.

Examples:

All active: {}
Only facts: {"kind":"fact"}
Pinned in a repo: {"pinned":true,"scope":{"type":"repo","remote":"github.com/acme/app"}}
Side-effect: read — Pure read; safe to call freely.

`memento memory read`

Fetch a single memory by id, or null if absent. By default the embedding vector is stripped (callers almost never need 768 floats); pass includeEmbedding: true for the raw vector.

Side-effect: read — Pure read; safe to call freely.

`memento memory restore`

Move a forgotten or archived memory back to active. Treated as an implicit confirm: lastConfirmedAt is bumped to now so the restored memory is not immediately re-eligible for compaction.

Example:

{"id":"01HYXZ..."}

Side-effect: write — Mutates state and emits an audit-log event.

`memento memory search`

Search memories by free text using FTS5 + the configured linear ranker.

Query text is treated as a term bag: FTS5 syntax (AND / OR / NOT / NEAR / phrase / prefix) is NOT parsed — sigils are stripped and tokens are ranked via BM25 + vector similarity.

Every result's memory carries an embeddingStatus field ("present" | "stale" | "pending" | "disabled") so a vector score of 0 can be distinguished between "the row has no embedding yet" (pending), "the embedding exists but the model/dim mismatches the configured embedder so the vector arm skipped it" (stale — run embedding.rebuild to fix), and "the content was not similar" (present).

Examples:

Simple: {"text":"database migration"}
With filters: {"text":"auth","kinds":["decision","fact"],"limit":5}
Side-effect: read — Pure read; safe to call freely.

`memento memory set_embedding`

Attach or replace the embedding for an active memory; appends a reembedded event.

Side-effect: admin — Operational / introspection.

`memento memory supersede`

Replace an existing memory with a new one in a single transaction. Use this instead of update when the content changes.

History is preserved: the old memory transitions to superseded and its supersededBy field links to the new memory. The transaction emits a superseded audit event on the old id and a matching created event on the new id, so memory.events shows the chain from either side.

Example:

{"oldId":"01HYXZ...","next":{"scope":{"type":"global"},"kind":{"type":"fact"},"tags":["corrected"],"pinned":false,"content":"Updated fact content.","summary":null,"storedConfidence":0.9}}

Side-effect: write — Mutates state and emits an audit-log event.

`memento memory update`

Update non-content fields (tags / kind / pinned / sensitive) of an active memory. Does NOT change content — use memory.supersede for that.

kind patches: same-type edits (e.g. updating a snippet's language in place, updating a decision's rationale) succeed. Cross-type kind changes (snippet → fact, decision → preference, etc.) are rejected with INVALID_INPUT — route them through memory.supersede so kind-specific metadata stays in the audit chain.

Example:

{"id":"01HYXZ...","patch":{"tags":["updated-tag"],"pinned":true}}

Side-effect: write — Mutates state and emits an audit-log event.

`memento memory write`

Create a new memory in the given scope.

Workflow: search first to avoid duplicates. If a similar memory exists, use memory.supersede to update it instead. Use memory.update for non-content changes (tags, kind, pinned, sensitive).

For preference and decision kinds, start the content with a single topic: value line followed by free prose. Conflict detection parses that first line — without it two contradictory preferences silently coexist. Example: node-package-manager: pnpm\n\nRaghu prefers pnpm over npm for Node projects.

Minimal example (pinned, storedConfidence, summary, owner all have defaults):

{"scope":{"type":"global"},"kind":{"type":"fact"},"tags":["project:memento"],"content":"Memento uses SQLite for storage."}

Full example:

{"scope":{"type":"global"},"kind":{"type":"fact"},"tags":["project:memento"],"pinned":false,"content":"Memento uses SQLite for storage.","summary":"Storage engine choice","storedConfidence":0.95}

Side-effect: write — Mutates state and emits an audit-log event.

`memento memory write_many`

Atomically create multiple memories in a single transaction. Per-item clientToken idempotency is honoured; on any failure the whole batch rolls back.

Programmatic / operator surface — AI assistants typically do NOT reach for this. For multiple explicit user statements ("remember A, B, and C"), prefer N sequential write_memory calls so one bad item does not roll the others back. For end-of-session sweeps over things the user mentioned in passing, use extract_memory (server dedups + scrubs + lowers confidence). Use write_many_memories only when you genuinely need all-or-nothing transactional semantics — e.g. importing a curated batch from a doc.

Side-effect: write — Mutates state and emits an audit-log event.

`memento pack export`

Build a memento pack manifest (YAML) from memories matching a filter. Read-only. The CLI lifecycle wraps this with memento pack create for file IO; assistants and the dashboard call it directly.

Side-effect: read — Pure read; safe to call freely.

`memento pack install`

Install a memento pack — a curated YAML bundle of memories — from the bundled registry, a local file, or an HTTPS URL. Stamps pack:<id>:<version> provenance on every memory; idempotent on unchanged content; refuses with PACK_VERSION_REUSED on content drift without a version bump (ADR-0020).

Side-effect: write — Mutates state and emits an audit-log event.

`memento pack list`

List installed packs — every active memory's pack:<id>:<version> tag is grouped, returning the pack id, version, scope, and memory count.

Side-effect: read — Pure read; safe to call freely.

`memento pack preview`

Preview what pack.install would write. Resolves the manifest, classifies the install state (fresh / idempotent / drift), and returns the items without persisting. Read-only.

Side-effect: read — Pure read; safe to call freely.

`memento pack uninstall`

Forget every active memory installed by a pack — single version (default) or allVersions: true. Composes with the bulk-destructive contract from ADR-0014: dry-run defaults true, confirm: true is required, the safety.bulkDestructiveLimit cap applies on apply.

Side-effect: destructive — Bulk or irreversible; the CLI requires --confirm to execute.

`memento system info`

Server health and capability snapshot. Returns version, schema version, db path, vector retrieval status, configured embedder model + dimension, per-status memory counts, open-conflict count, runtime info (Node version, modules ABI, native-binding state), scrubber state (write-path redaction master switch), and user.preferredName (the name an assistant should use when authoring memory content; falls back to "The user" when null). Read-only; safe to call freely — call once at session start to learn the user's name and the store's capabilities.

Tip: call system.list_scopes to discover valid scopes for memory.write.

Side-effect: read — Pure read; safe to call freely.

`memento system list_scopes`

List every scope that has at least one active memory, with per-scope count and most-recent write timestamp. Sorted by count desc. Read-only; safe to call freely.

Call this before writing to discover valid scopes. If the response is empty, use {"type":"global"} as a safe default scope for memory.write. The returned scope objects can be passed directly to memory.write or memory.search.

Side-effect: read — Pure read; safe to call freely.

`memento system list_tags`

List all tags in use across memories, with per-tag counts sorted by frequency descending. Defaults to active memories only. Read-only; safe to call freely.

Use this to discover valid tags before calling memory.list or memory.search with a tags filter.

Side-effect: read — Pure read; safe to call freely.

FilesExpand file tree

cli.md

Latest commit

History

cli.md

File metadata and controls

CLI Reference

Invocation

Global flags

Lifecycle commands

memento backup

memento completions

memento context

memento dashboard

memento doctor

memento explain

memento export

memento import

memento init

memento pack

memento ping

memento serve

memento skill-path

memento status

memento store migrate

memento uninstall

memento verify-setup

Registry commands

memento compact run

memento config get

memento config history

memento config list

memento config set

memento config unset

memento conflict events

memento conflict list

memento conflict read

memento conflict resolve

memento conflict scan

memento embedding rebuild

memento memory archive

memento memory archive_many

memento memory confirm

memento memory confirm_many

memento memory context

memento memory events

memento memory extract

memento memory forget

memento memory forget_many

memento memory list

memento memory read

memento memory restore

memento memory search

memento memory set_embedding

memento memory supersede

memento memory update

memento memory write

memento memory write_many

memento pack export

memento pack install

memento pack list

memento pack preview

memento pack uninstall

memento system info

memento system list_scopes

memento system list_tags

`memento backup`

`memento completions`

`memento context`

`memento dashboard`

`memento doctor`

`memento explain`

`memento export`

`memento import`

`memento init`

`memento pack`

`memento ping`

`memento serve`

`memento skill-path`

`memento status`

`memento store migrate`

`memento uninstall`

`memento verify-setup`

`memento compact run`

`memento config get`

`memento config history`

`memento config list`

`memento config set`

`memento config unset`

`memento conflict events`

`memento conflict list`

`memento conflict read`

`memento conflict resolve`

`memento conflict scan`

`memento embedding rebuild`

`memento memory archive`

`memento memory archive_many`

`memento memory confirm`

`memento memory confirm_many`

`memento memory context`

`memento memory events`

`memento memory extract`

`memento memory forget`

`memento memory forget_many`

`memento memory list`

`memento memory read`

`memento memory restore`

`memento memory search`

`memento memory set_embedding`

`memento memory supersede`

`memento memory update`

`memento memory write`

`memento memory write_many`

`memento pack export`

`memento pack install`

`memento pack list`

`memento pack preview`

`memento pack uninstall`

`memento system info`

`memento system list_scopes`

`memento system list_tags`