Overview | MACHINE-MEMORY by JFA

Machine commands are designed to be composed by agents and scripts. Unless noted otherwise, every database-backed command requires exactly one of --local or --remote. In this repository, use --remote.

machine-memory query "backend" (--local|--remote) --json-min

Output modes

Database-backed commands return JSON. Unless a page states otherwise, every command accepts:

Flag	Use
`--brief`	Human-readable one-line summaries or compact ack payloads.
`--json-min`	Compact JSON with stable identifiers and minimal summaries.
`--quiet`	The smallest machine-oriented response available for the command.

All machine commands also accept the global --pretty flag. It renders a human-readable result instead of JSON. Existing explicit output flags take precedence, so --json-min, --brief, and --quiet remain safe for scripts.

Both placements are supported:

machine-memory --pretty query "backend" --remote
machine-memory query "backend" --remote --pretty

Commands

CLI and memory lifecycle

Command	Purpose
`help`	Print the command catalog and enum values as JSON.
`version`	Print the installed CLI version.
`add`	Create a memory, optionally upserting a strong match.
`size`	Preflight the embedding budget without writing.
`get`	Fetch one or more memories by ID.
`update`	Change memory content or metadata.
`deprecate`	Mark memories deprecated or superseded.
`delete`	Permanently delete memories.

Search and analysis

Command	Purpose
`query`	Search memories with full-text, semantic, or hybrid relevance.
`list`	List memories using filters and recency order.
`suggest`	Find memories related to a set of file paths.
`sweep`	Combine file suggestions, text search, and filtered listing.
`verify`	Compare a proposed fact with an existing memory.
`diff`	Explain how proposed content differs from an existing memory.
`coverage`	Find directories that are not represented by memory tags.
`stats`	Summarize repository memory health and distribution.
`doctor`	Detect duplicates, stale status, tag, reference, and type issues.

Maintenance and interchange

Command	Purpose
`export`	Export active memories as JSON.
`import`	Import a JSON memory export with duplicate and conflict checks.
`migrate`	Apply pending database schema migrations.
`gc`	Preview memories whose expiry window has elapsed.
`tag-map`	Manage path-to-tag mappings used during memory writes.
`reindex`	Backfill existing remote memories into Vectorize embeddings.