CLI Reference
Complete command reference for the mx CLI.
Full command reference for @memnexus-ai/cli. Install with:
npm install -g @memnexus-ai/cli
Global options
| Option | Description |
|---|---|
--no-color | Disable colored output |
--version | Show CLI version |
--help | Show help for any command |
auth
Manage authentication and API keys
mx auth login
Configure API key for authentication
| Option | Description | Default |
|---|---|---|
--api-key <key> | API key to store | — |
--interactive | Prompt for API key (mask input) | — |
mx auth logout
Remove stored credentials
mx auth status
Show current authentication status
| Option | Description | Default |
|---|---|---|
--format <format> | Output format (json|table|yaml) | — |
config
Manage CLI configuration
mx config get <key>
Get a configuration value
mx config set <key> <value>
Set a configuration value
mx config list
List all configuration values
mx config reset
Reset configuration to defaults
mx config agent
Show AI agent detection status and effective defaults
| Option | Description | Default |
|---|---|---|
--format <format> | Output format (json|table) | table |
mx config env
Show all supported environment variables and their current values
memories
Manage memories
mx memories list
List memories
| Option | Description | Default |
|---|---|---|
--page <number> | Page number | 0 |
--limit <number> | Results per page | 20 |
--last <number> | Get N most recent memories (shortcut for --limit N --sort createdAt:desc) | — |
--sort <field> | Sort by field (createdAt:asc, createdAt:desc, eventTime:asc, eventTime:desc) | — |
--named | List only named memories | — |
--recent <duration> | Filter: memories from last duration (e.g., 7d, 2w, 1h, 30m) | — |
--after <date> | Filter: memories created after this date (ISO 8601) | — |
--before <date> | Filter: memories created before this date (ISO 8601) | — |
--topics <topics> | Filter: comma-separated list of topics (matches ANY) | — |
--topic <topics> | Alias for --topics | — |
--exclude-topics <topics> | Filter: exclude memories with these topics (comma-separated) | — |
--format <format> | Output format (json|table|yaml) | — |
mx memories get [id] [moreIds]
Get one or more memories by ID (supports piping with --stdin)
| Option | Description | Default |
|---|---|---|
--format <format> | Output format (json|table|yaml) | — |
--name <name> | Get memory by name instead of ID | — |
--detail <level> | Detail level: minimal, standard (default), full | standard |
--similar | Find semantically similar memories (single ID only) | — |
--conversation | Find memories from the same conversation (single ID only) | — |
--related | Find memories with shared topics (single ID only) | — |
--limit <number> | Maximum number of related results | 5 |
--stdin | Read memory IDs from stdin (one per line or space-separated) | — |
mx memories create
Create a new memory
| Option | Description | Default |
|---|---|---|
--conversation-id <id> | Conversation ID (REQUIRED - use "NEW" to create a new conversation) | — |
--content <text> | Memory content | — |
--name <name> | Assign a kebab-case name for deterministic retrieval | — |
--memory-type <type> | Memory type (episodic|semantic|procedural) | — |
--context <context> | Context identifier | — |
--topics <topics> | Comma-separated topics | — |
--role <role> | Role (user|assistant|system) | — |
--importance <number> | Importance score (0-1) | — |
--supersedes <id> | ID of memory this supersedes (auto-creates SUPERSEDES relationship) | — |
--interactive | Interactive mode | — |
--format <format> | Output format (json|table|yaml) | — |
mx memories update [id]
Update an existing memory (by ID or --name)
| Option | Description | Default |
|---|---|---|
--name <name> | Update a named memory (creates new version via SUPERSEDES chain) | — |
--assign-name <name> | Assign a name to an existing memory (kebab-case, 2-64 chars) | — |
--rename <newName> | Rename a named memory (use with --name or an ID that has a name) | — |
--content <text> | Updated content | — |
--memory-type <type> | Updated memory type | — |
--context <context> | Updated context | — |
--topics <topics> | Updated topics (comma-separated) | — |
--importance <number> | Updated importance (0-1) | — |
--format <format> | Output format (json|table|yaml) | — |
mx memories history <name>
Show version history for a named memory
| Option | Description | Default |
|---|---|---|
--format <format> | Output format (json|table|yaml) | — |
--limit <number> | Maximum versions to show | 20 |
mx memories delete <id>
Delete a memory
| Option | Description | Default |
|---|---|---|
--force | Skip confirmation prompt | — |
mx memories search
Search memories (keyword, semantic, hybrid; see also: graphrag query)
| Option | Description | Default |
|---|---|---|
--query <text> | Search query | — |
--limit <number> | Maximum results | 20 |
--mode <mode> | Search mode (unified|content|facts) | — |
--method <method> | Search method: keyword (TF-IDF), semantic (vector), hybrid (both) | — |
--threshold <number> | Minimum score threshold for semantic search (0-1) | 0.5 |
--vector-weight <number> | Weight for vector search in hybrid mode (0-1) | 0.7 |
--fulltext-weight <number> | Weight for fulltext search in hybrid mode (0-1) | 0.3 |
--event-from <datetime> | Filter: event time start (ISO 8601) | — |
--after <datetime> | Alias for --event-from: event time start (ISO 8601) | — |
--event-to <datetime> | Filter: event time end (ISO 8601) | — |
--before <datetime> | Alias for --event-to: event time end (ISO 8601) | — |
--recent <duration> | Filter: memories from last duration (e.g., 7d, 2w, 1h, 30m) | — |
--topics <topics> | Filter: comma-separated list of topics (matches ANY) | — |
--topic <topics> | Alias for --topics | — |
--exclude-topics <topics> | Filter: exclude memories with these topics (comma-separated) | — |
--type <type> | Filter: memory type (episodic|semantic|procedural) | — |
--conversation-id <id> | Filter: conversation ID | — |
--preview <number> | Content preview length in characters | 200 |
--format <format> | Output format (json|table|yaml|llm|compact) | — |
--compact | Compact output: ID, date, first line (shorthand for --format compact) | — |
--id-only | Output only memory IDs (newline-separated, for piping) | — |
--explain | Include search scoring explanation | — |
--brief | Quick lookup preset: --limit 5 --preview 80 --format json | — |
--timeline | Timeline mode: sort chronologically with timestamps and state indicators. Use --preview <N> (N>100) to show inline content | — |
--group-by <field> | Group results by field (conversation). Shows memories organized by conversation. | — |
--expand-entities | Enable entity graph traversal branch in hybrid search | — |
--expand-topics | Enable topic graph traversal branch in hybrid search | — |
--expand-facts | Enable fact graph traversal branch in hybrid search | — |
--include-superseded | Include superseded/contradicted memories in results | — |
--content-only | Strip output to minimal fields: {id, createdAt, topics, content} (JSON output only) | — |
--effective-only | Exclude superseded/contradicted memories (passes includeSuperseded: false to API) | — |
--sort <field> | Sort results by field: score (default), createdAt, updatedAt, eventTime | — |
--order <dir> | Sort direction: asc | desc (default: desc) | — |
--strict | High-precision mode: fulltext-only, no semantic blending. Use for status/incident/deployment queries where exact-token match matters (sets --mode content --method keyword) | — |
mx memories relationships
Manage memory relationships (SUPERSEDES, FOLLOWS, RESOLVES, etc.)
mx memories relationships list <id>
List relationships for a memory
| Option | Description | Default |
|---|---|---|
--direction <dir> | Direction: outgoing (from this memory), incoming (to this memory), both | both |
--format <format> | Output format (json|table|yaml) | — |
mx memories relationships create <id>
Create a relationship from this memory to another
| Option | Description | Default |
|---|---|---|
--target <id> | Target memory ID | — |
--type <type> | Relationship type (SUPERSEDES|FOLLOWS|RESOLVES|CONTRADICTS|REFERENCES) | — |
--confidence <number> | Confidence score (0-1) | 1.0 |
--reason <text> | Explanation for the relationship | — |
--interactive | Interactive mode | — |
--format <format> | Output format (json|table|yaml) | — |
mx memories relationships delete <id> <relationshipId>
Delete a relationship
| Option | Description | Default |
|---|---|---|
--force | Skip confirmation prompt | — |
mx memories timeline <id>
Get timeline context for a memory (related memories before and after)
| Option | Description | Default |
|---|---|---|
--before <number> | Number of memories before | 5 |
--after <number> | Number of memories after | 5 |
--format <format> | Output format (json|table|yaml) | — |
mx memories detect-relationships <id>
Auto-detect potential relationships for a memory
| Option | Description | Default |
|---|---|---|
--auto-create | Automatically create high-confidence relationships | — |
--min-confidence <number> | Minimum confidence threshold (0-1) | 0.7 |
--format <format> | Output format (json|table|yaml) | — |
mx memories digest
AI-synthesized summary for humans — reports, handoffs, Slack updates (alias: recall | see also: recap)
| Option | Description | Default |
|---|---|---|
--query <text> | Search query for the digest (required) | — |
--recent <duration> | Time window (e.g., 24h, 7d, 2w) | — |
--topics <topics> | Filter by topics (comma-separated) | — |
--digest-format <format> | Digest format (structured|narrative|timeline|status-report) | structured |
--max-sources <number> | Maximum source memories to consider | 100 |
--show-sources | Display source memory IDs | — |
--format <format> | Output format (json|yaml|llm) | — |
mx memories status
Project status: Done / In Progress / Remaining — AI synthesis of memory corpus (alias for: digest --digest-format status-report)
| Option | Description | Default |
|---|---|---|
--query <text> | Topic or project to get status for (required) | — |
--recent <duration> | Time window (e.g., 24h, 7d, 2w) | — |
--topics <topics> | Filter by topics (comma-separated) | — |
--max-sources <number> | Maximum source memories to consider | 100 |
--show-sources | Display source memory IDs | — |
--format <format> | Output format (json|yaml|llm) | — |
mx memories recap
Quick raw recap of recent work — fast, agent-friendly (see also: digest / recall)
| Option | Description | Default |
|---|---|---|
--recent <duration> | Time window (e.g., 24h, 7d, 2w) | 24h |
--query <text> | Optional search query to filter results | — |
--limit <number> | Maximum memories to fetch | 200 |
--exclude-topics <topics> | Exclude memories with these topics (comma-separated) | auto-saved |
--format <format> | Output format (json|table|yaml) | — |
mx memories build-context
Get contextual briefing before starting work
| Option | Description | Default |
|---|---|---|
--context <text> | What you are about to work on | — |
--files <paths...> | File paths you will be touching | — |
--recent <hours> | How far back to look in hours (default: 24) | 24 |
--format <format> | Output format (json|table|yaml) | — |
mx memories stats
Aggregated memory analytics (group by day, week, month, or topic)
| Option | Description | Default |
|---|---|---|
--group-by <dimension> | Group by: day, week, month, topic (required) | — |
--after <date> | Start date filter (ISO 8601 or YYYY-MM-DD) | — |
--before <date> | End date filter | — |
--recent <duration> | Time window (e.g. 1w, 2w, 1mo) | — |
--topic <topic> | Filter to a specific topic before grouping | — |
--limit <n> | Max groups to return | 20 |
--format <fmt> | Output format: table (default), json, csv | — |
conversations
Query and manage conversations
mx conversations list
List conversations
| Option | Description | Default |
|---|---|---|
--page <number> | Page number | 0 |
--limit <number> | Results per page | 20 |
--recent <duration> | Time window (e.g., 24h, 7d, 2w) | — |
--min-memories <n> | Only show conversations with at least N memories (filters empty init conversations) | — |
--format <format> | Output format (json|table|yaml) | — |
mx conversations summary <id>
Get conversation summary
| Option | Description | Default |
|---|---|---|
--format <format> | Output format (json|table|yaml) | — |
mx conversations timeline <id>
Get conversation timeline
| Option | Description | Default |
|---|---|---|
--format <format> | Output format (json|table|yaml) | — |
mx conversations search
Search conversations
| Option | Description | Default |
|---|---|---|
--query <text> | Search query | — |
--limit <number> | Maximum results | 20 |
--format <format> | Output format (json|table|yaml) | — |
--brief | Quick lookup preset: --limit 5 --format json | — |
mx conversations by-topic
Find conversations by topic
| Option | Description | Default |
|---|---|---|
--topic <id> | Topic ID | — |
--topic-id <id> | Topic ID (alias for --topic) | — |
--format <format> | Output format (json|table|yaml) | — |
facts
Manage semantic facts
mx facts list
List facts
| Option | Description | Default |
|---|---|---|
--page <number> | Page number | 0 |
--limit <number> | Results per page | 20 |
--format <format> | Output format (json|table|yaml) | — |
mx facts get <id>
Get a specific fact
| Option | Description | Default |
|---|---|---|
--format <format> | Output format (json|table|yaml) | — |
mx facts create
Create a new fact
| Option | Description | Default |
|---|---|---|
--subject <text> | Fact subject (entity name) | — |
--predicate <text> | Relationship type | — |
--object <text> | Fact object (related entity) | — |
--confidence <number> | Confidence score (0-1) | 1.0 |
--memory-id <id> | Associated memory ID | — |
--interactive | Interactive mode | — |
--format <format> | Output format (json|table|yaml) | — |
mx facts update <id>
Update an existing fact
| Option | Description | Default |
|---|---|---|
--subject <text> | Updated subject | — |
--predicate <text> | Updated predicate | — |
--object <text> | Updated object | — |
--confidence <number> | Updated confidence (0-1) | — |
--format <format> | Output format (json|table|yaml) | — |
mx facts delete <id>
Delete a fact
| Option | Description | Default |
|---|---|---|
--force | Skip confirmation prompt | — |
mx facts search
Search facts
| Option | Description | Default |
|---|---|---|
--query <text> | Search query | — |
--limit <number> | Maximum results | 20 |
--format <format> | Output format (json|table|yaml) | — |
--brief | Quick lookup preset: --limit 5 --format json | — |
topics
Manage topics and graph operations
mx topics list
List topics
| Option | Description | Default |
|---|---|---|
--page <number> | Page number | 0 |
--limit <number> | Results per page | 20 |
--context-id <id> | Filter by context | — |
--format <format> | Output format (json|table|yaml) | — |
mx topics get <id>
Get topic details
| Option | Description | Default |
|---|---|---|
--format <format> | Output format (json|table|yaml) | — |
mx topics merge
Merge two topics
| Option | Description | Default |
|---|---|---|
--source-id <id> | Source topic ID | — |
--target-id <id> | Target topic ID | — |
--force | Skip confirmation | — |
--format <format> | Output format (json|table|yaml) | — |
mx topics discover-related
Discover related topics via graph traversal (see also: search)
| Option | Description | Default |
|---|---|---|
--topic <id> | Topic ID (required) | — |
--topic-id <id> | Topic ID (alias for --topic) | — |
--context-id <id> | Filter by context | — |
--limit <number> | Max results | 20 |
--format <format> | Output format (json|table|yaml) | — |
mx topics similarity
Calculate similarity between topics
| Option | Description | Default |
|---|---|---|
--topic-id-1 <id> | First topic ID (required) | — |
--topic-id-2 <id> | Second topic ID (required) | — |
--format <format> | Output format (json|table|yaml) | — |
mx topics find-similar
Find similar topics
| Option | Description | Default |
|---|---|---|
--topic-id <id> | Topic ID (required) | — |
--threshold <number> | Similarity threshold (0-1) | 0.7 |
--limit <number> | Max results | 20 |
--format <format> | Output format (json|table|yaml) | — |
mx topics cluster
Cluster topics using graph algorithms
| Option | Description | Default |
|---|---|---|
--algorithm <type> | Clustering algorithm (kmeans|hierarchical|dbscan) | kmeans |
--num-clusters <number> | Number of clusters | — |
--context-id <id> | Filter by context | — |
--format <format> | Output format (json|table|yaml) | — |
mx topics detect-communities
Detect communities in topic graph
| Option | Description | Default |
|---|---|---|
--algorithm <type> | Community detection algorithm (louvain|label-propagation) | louvain |
--context-id <id> | Filter by context | — |
--min-size <number> | Minimum community size | 2 |
--format <format> | Output format (json|table|yaml) | — |
mx topics search
Search topics by query string (see also: discover-related)
| Option | Description | Default |
|---|---|---|
--query <text> | Search query (required) | — |
--limit <number> | Maximum results | 20 |
--format <format> | Output format (json|table|yaml) | — |
patterns
Manage behavioral patterns
mx patterns list
List patterns
| Option | Description | Default |
|---|---|---|
--page <number> | Page number | 0 |
--limit <number> | Results per page | 20 |
--type <type> | Pattern type (behavioral|temporal|semantic) | — |
--format <format> | Output format (json|table|yaml) | — |
mx patterns compile
Compile patterns from memories
| Option | Description | Default |
|---|---|---|
--force | Force recompilation | — |
--pattern-types <types> | Comma-separated pattern types to compile | — |
mx patterns update <id>
Update a pattern
| Option | Description | Default |
|---|---|---|
--description <text> | Updated description | — |
--active <boolean> | Enable/disable pattern | — |
--metadata <json> | Updated metadata | — |
--format <format> | Output format (json|table|yaml) | — |
mx patterns feedback
Record pattern feedback
| Option | Description | Default |
|---|---|---|
--pattern-id <id> | Pattern ID (required) | — |
--feedback-type <type> | Feedback type (positive|negative|neutral) (required) | — |
--comment <text> | Feedback comment | — |
mx patterns behavior-state
Get behavioral state
| Option | Description | Default |
|---|---|---|
--format <format> | Output format (json|table|yaml) | — |
mx patterns set-behavior-state
Set behavioral state
| Option | Description | Default |
|---|---|---|
--state <json> | Behavioral state JSON (required) | — |
--merge | Merge with existing state instead of replacing | — |
mx patterns detect
Detect recurring behavioral patterns from memories
| Option | Description | Default |
|---|---|---|
--context-filter <context> | Filter patterns by context | — |
--timeframe-start <date> | Start of detection timeframe (ISO 8601) | — |
--timeframe-end <date> | End of detection timeframe (ISO 8601) | — |
--min-confidence <number> | Minimum confidence threshold (0-1) | 0.5 |
--max-results <number> | Maximum patterns to return | 20 |
--auto-store | Automatically store detected patterns | — |
--format <format> | Output format (json|table|yaml) | — |
mx patterns analyze
Analyze pattern trends, correlations, and generate insights
| Option | Description | Default |
|---|---|---|
--time-range <days> | Analysis time range in days | 30 |
--group-by <criteria> | Group analysis by criteria (type|context|time) | — |
--include-details | Include detailed breakdown | — |
--format <format> | Output format (json|table|yaml) | — |
mx patterns compile-instructions
Compile stored behavioral patterns into actionable AI context instructions
| Option | Description | Default |
|---|---|---|
--context <tags> | Comma-separated topic tags matching current conversation topics (boosts patterns with matching metadata) | — |
--token-budget <n> | Maximum tokens to use for instructions (50-2000) | 200 |
--min-confidence <n> | Minimum pattern confidence threshold (0-1) | 0.6 |
--max-instructions <n> | Maximum number of instructions to return (1-10) | 5 |
--format <format> | Output format (json|table) | table |
graphrag
Execute GraphRAG queries
mx graphrag query
Execute GraphRAG query (see also: memories search)
| Option | Description | Default |
|---|---|---|
--query <text> | Query text (required) | — |
--context-id <id> | Context ID | — |
--mode <mode> | Query mode (local|global|hybrid) | hybrid |
--max-depth <number> | Graph traversal depth | 3 |
--limit <number> | Max results | 20 |
--format <format> | Output format (json|table|yaml) | — |
mx graphrag explain <result-id>
Explain query result
| Option | Description | Default |
|---|---|---|
--format <format> | Output format (json|table|yaml) | — |
mx graphrag query-communities
Query communities
| Option | Description | Default |
|---|---|---|
--query <text> | Query text (required) | — |
--context-id <id> | Context ID | — |
--limit <number> | Max communities | 10 |
--format <format> | Output format (json|table|yaml) | — |
artifacts
Manage artifacts
mx artifacts list
List artifacts
| Option | Description | Default |
|---|---|---|
--page <number> | Page number | 0 |
--limit <number> | Results per page | 20 |
--context-id <id> | Filter by context | — |
--type <type> | Filter by artifact type | — |
--format <format> | Output format (json|table|yaml) | — |
mx artifacts get <id>
Get artifact details
| Option | Description | Default |
|---|---|---|
--format <format> | Output format (json|table|yaml) | — |
mx artifacts create
Create artifact
| Option | Description | Default |
|---|---|---|
--name <name> | Artifact name | — |
--type <type> | Artifact type | — |
--context-id <id> | Context ID | — |
--data <json> | Artifact data as JSON | — |
--metadata <json> | Artifact metadata as JSON | — |
--interactive | Interactive mode | — |
--format <format> | Output format (json|table|yaml) | — |
mx artifacts update <id>
Update artifact
| Option | Description | Default |
|---|---|---|
--name <name> | Updated name | — |
--data <json> | Updated data | — |
--metadata <json> | Updated metadata | — |
--format <format> | Output format (json|table|yaml) | — |
mx artifacts delete <id>
Delete artifact
| Option | Description | Default |
|---|---|---|
--force | Skip confirmation | — |
apikeys
Manage API keys
mx apikeys list
List API keys
| Option | Description | Default |
|---|---|---|
--page <number> | Page number | 0 |
--limit <number> | Results per page | 20 |
--format <format> | Output format (json|table|yaml) | — |
mx apikeys create
Create API key
| Option | Description | Default |
|---|---|---|
--label <label> | Key label (optional) | — |
--expires-at <date> | Expiration date (ISO 8601 format, optional) | — |
mx apikeys delete <id>
Delete API key
| Option | Description | Default |
|---|---|---|
--force | Skip confirmation | — |
system
System health and statistics
mx system health
Check system health
| Option | Description | Default |
|---|---|---|
--format <format> | Output format (json|table|yaml) | — |
mx system status
Get system status
| Option | Description | Default |
|---|---|---|
--format <format> | Output format (json|table|yaml) | — |
mx system features
Get feature flags
| Option | Description | Default |
|---|---|---|
--format <format> | Output format (json|table|yaml) | — |
update
Check for and install CLI updates
mx update
Check for and install CLI updates
| Option | Description | Default |
|---|---|---|
--check | Check for updates without installing | — |
--version <version> | Install a specific version | — |
--yes | Skip confirmation prompt | — |
narratives
Manage narrative threads (group related memories into storylines)
mx narratives list
List narrative threads
| Option | Description | Default |
|---|---|---|
--page <number> | Page number | 0 |
--limit <number> | Results per page | 20 |
--state <state> | Filter by state (open|resolved|reopened|superseded) | — |
--topics <topics> | Filter by topics (comma-separated) | — |
--format <format> | Output format (json|table|yaml) | — |
mx narratives get <id>
Get a specific narrative
| Option | Description | Default |
|---|---|---|
--format <format> | Output format (json|table|yaml) | — |
mx narratives create
Create a new narrative thread
| Option | Description | Default |
|---|---|---|
--title <text> | Narrative title | — |
--root-memory-id <id> | ID of the first memory in this narrative | — |
--topics <topics> | Comma-separated topics | — |
--interactive | Interactive mode | — |
--format <format> | Output format (json|table|yaml) | — |
mx narratives update <id>
Update a narrative
| Option | Description | Default |
|---|---|---|
--title <text> | Updated title | — |
--state <state> | Updated state (open|resolved|reopened|superseded) | — |
--topics <topics> | Updated topics (comma-separated) | — |
--format <format> | Output format (json|table|yaml) | — |
mx narratives delete <id>
Delete a narrative (memories are preserved)
| Option | Description | Default |
|---|---|---|
--force | Skip confirmation prompt | — |
mx narratives timeline <id>
Get timeline of memories in a narrative
| Option | Description | Default |
|---|---|---|
--limit <number> | Maximum memories to return | 20 |
--page <number> | Page number | 0 |
--format <format> | Output format (json|table|yaml) | — |
Environment variables
| Variable | Description | Default |
|---|---|---|
MX_API_URL | API base URL | https://api.dev.memnexus.ai |
MX_API_KEY | Authentication key | — |
MX_OUTPUT_FORMAT | Default output format | table |
MX_DEFAULT_PAGE_SIZE | Pagination size | 20 |