Command-line interface for MemNexus Core API
npm install @memnexus-ai/cli> Command-line interface for MemNexus - Your personal memory and knowledge management system
mx-cli is a powerful command-line tool for interacting with the MemNexus API. It provides comprehensive commands for managing memories, conversations, facts, and more, with support for multiple output formats, interactive modes, and flexible configuration.
- š Authentication Management - Secure API key storage with password masking
- āļø Flexible Configuration - Environment variables and config file support
- š¾ Memory Management - Full CRUD operations for episodic and semantic memories
- š¬ Conversation Tracking - Query and manage conversation history
- š§ Fact Management - Create and manage semantic knowledge graphs
- šØ Topics & Communities - Graph-based topic clustering and community detection
- š GraphRAG Queries - Advanced graph-based retrieval augmented generation
- š Multiple Output Formats - JSON, table, and YAML output
- š Interactive Mode - User-friendly prompts with validation for creating resources
- š Pagination Support - Handle large datasets efficiently
- ā” Progress Indicators - Visual feedback for long-running operations
- ā
Comprehensive Testing - 128 tests with >80% coverage
- š”ļø Input Validation - Helpful error messages with actionable troubleshooting steps
- šÆ Confirmation Prompts - Safety checks for destructive operations
- Node.js 18+ and npm
- Access to a MemNexus API instance
#### Option 1: Install from npm (Recommended)
``bashInstall globally from npm
npm install -g @memnexus-ai/cli
> Published on npm: https://www.npmjs.com/package/@memnexus-ai/cli
#### Option 2: Install from Source (Development)
`bash
Clone the repository
cd mx-cliInstall dependencies
npm installBuild the CLI
npm run buildLink globally to use 'mx' command
npm linkVerify installation
mx --version
`$3
You can configure the CLI using either environment variables or the CLI commands.
#### Option 1: Using Environment Variables (Recommended)
Create a
.env file in the mx-cli directory:`bash
Copy the example file
cp .env.example .envEdit .env with your credentials
MX_API_URL=http://api.memnexus.ai
MX_API_KEY=your-api-key-here
`Then load the environment variables:
`bash
source .env
`#### Option 2: Using CLI Commands
`bash
Set API URL
mx config set apiUrl http://api.memnexus.aiLogin with API key
mx auth login --api-key your-api-key-hereVerify configuration
mx auth status
`$3
The following environment variables are supported:
| Variable | Description | Default |
|----------|-------------|---------|
|
MX_API_URL | MemNexus API base URL | http://api.memnexus.ai |
| MX_API_KEY | API authentication key | - |
| MX_OUTPUT_FORMAT | Default output format (json\|table\|yaml) | table |
| MX_DEFAULT_PAGE_SIZE | Default pagination size | 20 |Quick Start
Get up and running with mx-cli in 5 minutes:
`bash
1. Install from npm
npm install -g @memnexus-ai/cli2. Configure authentication (interactive mode with password masking)
mx auth login --interactive3. Verify connection
mx auth status4. Create your first memory
mx memories create --interactive5. List your memories
mx memories list6. Search for memories
mx memories search --query "your search term"7. Create a fact (knowledge graph triple)
mx facts create \
--subject "mx-cli" \
--predicate "is_a" \
--object "CLI tool" \
--confidence 1.08. Explore other commands
mx --help
`$3
#### Daily Memory Capture
`bash
Quick memory creation
mx memories create --content "Meeting notes: discussed Q4 roadmap" \
--memory-type episodic \
--topics "work,meetings" \
--importance 0.8Search recent memories
mx memories search --query "Q4 roadmap"
`#### Knowledge Graph Building
`bash
Create related facts
mx facts create --subject "TypeScript" --predicate "is_a" --object "Programming Language" --confidence 1.0
mx facts create --subject "mx-cli" --predicate "built_with" --object "TypeScript" --confidence 1.0
mx facts create --subject "mx-cli" --predicate "uses" --object "Commander.js" --confidence 1.0Search facts
mx facts search --query "TypeScript"
`#### Batch Operations with JSON Output
`bash
Export all memories to JSON
mx memories list --format json --limit 1000 > memories.jsonFind specific memories and process with jq
mx memories list --format json | jq '.data[] | select(.importance > 0.8)'Delete test memories (use with caution!)
mx memories list --format json | \
jq -r '.data[] | select(.content | contains("test")) | .id' | \
while read id; do mx memories delete "$id" --force; done
`Usage
$3
#### Login
Store your API key for authentication:
`bash
Direct login with API key
mx auth login --api-key cmk_live_abc123...Interactive login (prompts for API key with masked input)
mx auth login --interactive
`#### Check Status
View current authentication and configuration status:
`bash
mx auth status
`Output:
`
āāāāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā Property ā Value ā
āāāāāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāāāāāāāāāāāāāāāāā¤
ā Authentication ā ā Configured (via config) ā
ā API URL ā http://api.memnexus.ai ā
ā Output Format ā table ā
āāāāāāāāāāāāāāāāāāāā“āāāāāāāāāāāāāāāāāāāāāāāāāāāāā
`#### Logout
Remove stored credentials:
`bash
mx auth logout
`$3
#### Get Configuration
Retrieve a specific configuration value:
`bash
Get API URL
mx config get apiUrlGet default output format
mx config get defaultFormat
`#### Set Configuration
Update configuration values:
`bash
Set API URL
mx config set apiUrl http://api.memnexus.aiSet default output format
mx config set defaultFormat jsonSet default page size
mx config set defaultPageSize 50
`#### List All Configuration
View all configuration settings and their sources:
`bash
mx config list
`Output shows whether values come from environment variables or config file:
`
āāāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāāāāāāāā¬āāāāāāāāā
ā Key ā Value ā Source ā
āāāāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāāāāāāāāāāāāā¼āāāāāāāāā¤
ā apiUrl ā http://api.memnexus.ai ā config ā
ā defaultFormat ā table ā config ā
ā defaultPageSize ā 20 ā config ā
āāāāāāāāāāāāāāāāāāā“āāāāāāāāāāāāāāāāāāāāāāāāā“āāāāāāāāā
`#### Reset Configuration
Reset all settings to defaults:
`bash
mx config reset
`$3
Keep your CLI up to date with the latest features and bug fixes.
#### Check for Updates
Check if a newer version is available without installing:
`bash
mx update --check
`Output:
`
Current version: 0.1.7
Latest version: 0.1.8
Update available! Run 'mx update' to install.
`#### Update to Latest Version
Install the latest version with confirmation:
`bash
mx update
`The CLI will:
1. Auto-detect your package manager (npm, pnpm, or yarn)
2. Check if the CLI is globally installed
3. Prompt for confirmation before updating
4. Show progress during installation
5. Display the changelog URL
#### Update Without Confirmation
Skip the confirmation prompt:
`bash
mx update --yes
`#### Update to Specific Version
Install a specific version:
`bash
mx update --version 0.1.7
`Notes:
- The CLI must be installed globally for updates to work
- Updates require appropriate permissions (may need
sudo on Linux/macOS)
- Your package manager must be available in PATH
- Update notifications are shown automatically when running commands (can be disabled with mx config set updateNotifications false)$3
Memories are the core data structure in MemNexus, representing episodic or semantic information.
#### List Memories
View all memories with pagination:
`bash
List first page (default: 20 items)
mx memories listList with custom pagination
mx memories list --page 0 --limit 10Output as JSON
mx memories list --format jsonOutput as YAML
mx memories list --format yaml
`#### Get a Specific Memory
Retrieve detailed information about a memory:
`bash
Get memory by full UUID
mx memories get 26be666e-7503-40d7-9293-8ffbcdc04dd2Get memory by short ID prefix (minimum 8 characters, like git)
mx memories get 26be666eGet as JSON
mx memories get 26be666e-7503-40d7-9293-8ffbcdc04dd2 --format json
`Short ID Prefix Support:
- Minimum 8 characters required for prefix matching
- If the prefix matches exactly one memory, it's returned
- If the prefix is ambiguous (matches multiple memories), you'll see a list of matching IDs
- If no memory matches the prefix, an error is displayed
#### Create a Memory
Create new memories using direct mode or interactive prompts:
`bash
Direct mode - provide all details via flags
mx memories create \
--content "Completed Phase 2 of mx-cli implementation" \
--memory-type episodic \
--context work \
--topics "cli,development,milestone" \
--importance 0.9Interactive mode - prompts for each field
mx memories create --interactiveMinimal creation (only content required)
mx memories create --content "Quick note about something important"
`Options:
-
--content - Memory content (required)
- --memory-type - Type: episodic or semantic
- --context - Context identifier
- --topics - Comma-separated topics
- --importance - Importance score (0-1)
- --interactive - Interactive mode with prompts#### Update a Memory
Modify existing memory fields:
`bash
Update content
mx memories update 26be666e-7503-40d7-9293-8ffbcdc04dd2 \
--content "Updated content"Update importance
mx memories update 26be666e-7503-40d7-9293-8ffbcdc04dd2 \
--importance 0.95Update multiple fields
mx memories update 26be666e-7503-40d7-9293-8ffbcdc04dd2 \
--content "New content" \
--topics "updated,tags" \
--importance 0.8
`#### Delete a Memory
Remove a memory (with confirmation):
`bash
Delete with confirmation prompt
mx memories delete 26be666e-7503-40d7-9293-8ffbcdc04dd2Delete without confirmation
mx memories delete 26be666e-7503-40d7-9293-8ffbcdc04dd2 --force
`#### Search Memories
Search for memories using semantic or keyword search:
`bash
Basic search
mx memories search --query "Phase 2 implementation"Search with limit
mx memories search --query "CLI development" --limit 5Search with specific mode
mx memories search --query "testing" --mode unifiedSearch modes: unified (default), content, facts
mx memories search --query "authentication" --mode contentOutput only IDs (for piping to other commands)
mx memories search --query "old data" --id-onlyPipe IDs to batch delete
mx memories search --query "test" --id-only | xargs -I {} mx memories delete {} --force
`$3
Query and manage conversation history.
#### List Conversations
View all conversations:
`bash
List conversations
mx conversations listWith pagination
mx conversations list --page 0 --limit 10As JSON
mx conversations list --format json
`#### Get Conversation Details
Retrieve a specific conversation:
`bash
mx conversations get conv_abc123
`#### View Conversation Timeline
Get chronological message history:
`bash
mx conversations timeline conv_abc123
`#### Search Conversations
Search through conversation content:
`bash
mx conversations search --query "authentication discussion"
`#### Find Conversations by Topic
Filter conversations by topic:
`bash
mx conversations by-topic --topic-id topic_123
`Note: Some conversation endpoints are placeholders and will display a message indicating the feature is coming soon.
$3
Manage semantic facts in knowledge graph format (subject-predicate-object triples).
#### List Facts
View all facts:
`bash
List facts
mx facts listWith pagination
mx facts list --page 0 --limit 10As table (default)
mx facts list --format table
`#### Get a Specific Fact
Retrieve detailed information about a fact:
`bash
mx facts get fact_abc123
`#### Create a Fact
Create new semantic facts:
`bash
Direct mode
mx facts create \
--subject "TypeScript" \
--predicate "is_a" \
--object "Programming Language" \
--confidence 1.0Interactive mode
mx facts create --interactiveWith context and metadata
mx facts create \
--subject "mx-cli" \
--predicate "implements" \
--object "Commander.js pattern" \
--confidence 0.95 \
--context development
`Options:
-
--subject - Fact subject (required)
- --predicate - Relationship/predicate (required)
- --object - Fact object (required)
- --confidence - Confidence score 0-1 (default: 1.0)
- --context - Context identifier
- --interactive - Interactive mode#### Update a Fact
Modify existing fact fields:
`bash
Update confidence
mx facts update fact_abc123 --confidence 0.98Update multiple fields
mx facts update fact_abc123 \
--subject "Updated subject" \
--confidence 0.9
`#### Delete a Fact
Remove a fact:
`bash
With confirmation
mx facts delete fact_abc123Without confirmation
mx facts delete fact_abc123 --force
`#### Search Facts
Search through facts:
`bash
Basic search
mx facts search --query "TypeScript"With limit
mx facts search --query "programming" --limit 10
`$3
The CLI includes powerful advanced features for graph analysis, pattern detection, and AI-powered queries.
#### Topics Commands
Manage and analyze topics in your knowledge graph:
`bash
List all topics
mx topics listGet topic details
mx topics get Merge two topics (with confirmation)
mx topics merge --source-id --target-id Skip confirmation
mx topics merge --source-id --target-id --forceDiscover related topics
mx topics discover-related --topic-id Calculate similarity between topics
mx topics similarity --topic-id-1 --topic-id-2 Find similar topics
mx topics find-similar --topic-id --threshold 0.7Cluster topics using algorithms
mx topics cluster --algorithm kmeans --num-clusters 5
mx topics cluster --algorithm hierarchical
mx topics cluster --algorithm dbscanDetect communities in topic graph
mx topics detect-communities --algorithm louvain
mx topics detect-communities --algorithm label-propagation --min-size 3
`#### Communities Commands
Manage communities detected in your knowledge graph:
`bash
List communities
mx communities listGet community details
mx communities get Merge communities (with confirmation)
mx communities merge --source-id --target-id
`#### Patterns Commands
Compile and manage behavioral patterns from your memories:
`bash
Compile patterns from context
mx patterns compile --context-id Record feedback on a pattern
mx patterns feedback --pattern-id --feedback positive
mx patterns feedback --pattern-id --feedback negativeSet behavioral state
mx patterns set-state --pattern-id --state active
mx patterns set-state --pattern-id --state inactive
`#### GraphRAG Commands
Execute graph-based retrieval augmented generation queries:
`bash
Execute GraphRAG query
mx graphrag query --query "What are the main themes in my work memories?"Generate explanation for a memory
mx graphrag explain --memory-id Query communities
mx graphrag query-communities --query "technical discussions" --limit 5
`#### Artifacts Commands
Manage artifacts (files, documents, etc.):
`bash
List artifacts
mx artifacts listGet artifact details
mx artifacts get Create artifact (interactive mode)
mx artifacts create --interactiveCreate artifact (direct mode)
mx artifacts create --name "Document" --type "pdf"Update artifact
mx artifacts update --name "Updated Name"Delete artifact (with confirmation)
mx artifacts delete Skip confirmation
mx artifacts delete --force
`#### API Keys Commands
Manage API keys:
`bash
List API keys (metadata only, never shows actual keys)
mx apikeys listCreate new API key
mx apikeys create --label "My CLI Key"Create with expiration
mx apikeys create --label "Temp Key" --expires-at "2024-12-31T23:59:59Z"Delete API key (with confirmation)
mx apikeys delete Skip confirmation
mx apikeys delete --force
`#### System Commands
Check system health and status:
`bash
Check system health
mx system healthGet system status
mx system statusList feature flags
mx system feature-flags
`Common Options
These options are available across multiple commands:
$3
Control how data is displayed:
`bash
Table format (default) - human-readable
mx memories list --format tableJSON format - for scripting and parsing
mx memories list --format jsonYAML format - human-readable structured data
mx memories list --format yaml
`$3
Handle large datasets efficiently:
`bash
Default pagination (page 0, 20 items)
mx memories listCustom page and limit
mx memories list --page 2 --limit 50First 100 items
mx memories list --page 0 --limit 100
`$3
User-friendly prompts for creating resources with validation and helpful hints:
`bash
Interactive memory creation
mx memories create --interactiveInteractive fact creation
mx facts create --interactiveInteractive artifact creation
mx artifacts create --interactiveInteractive authentication (with password masking)
mx auth login --interactive
`The interactive mode will prompt you for each field with:
- Input validation
- Helpful error messages
- Default values where applicable
- Password masking for sensitive inputs
$3
Skip confirmation prompts for destructive operations:
`bash
Delete operations
mx memories delete --force
mx facts delete --force
mx artifacts delete --force
mx apikeys delete --forceMerge operations
mx topics merge --source-id --target-id --force
mx communities merge --source-id --target-id --force
`ā ļø Warning: Using
--force skips safety confirmations. Use with caution, especially in production environments.Example Workflows
$3
`bash
1. Build and link the CLI
cd mx-cli
npm install
npm run build
npm link2. Configure using environment variables
cp .env.example .env
Edit .env with your API key and URL
source .env3. Verify authentication
mx auth status4. Create your first memory
mx memories create \
--content "Started using mx-cli for memory management" \
--memory-type episodic \
--context personal \
--topics "getting-started,mx-cli" \
--importance 0.85. List your memories
mx memories list6. Search for memories
mx memories search --query "getting started"
`$3
`bash
Get memory as JSON for scripting
MEMORY_JSON=$(mx memories get --format json)List memories as YAML for readability
mx memories list --format yamlExport all memories to JSON file
mx memories list --format json --limit 1000 > memories.json
`$3
`bash
Create a fact about a technology
mx facts create \
--subject "mx-cli" \
--predicate "built_with" \
--object "TypeScript" \
--confidence 1.0Create a related fact
mx facts create \
--subject "mx-cli" \
--predicate "uses" \
--object "Commander.js" \
--confidence 1.0Search for related facts
mx facts search --query "mx-cli"
`$3
`bash
Create multiple memories from a file
while IFS= read -r line; do
mx memories create --content "$line" --memory-type episodic
done < notes.txtExport all memories with specific topic
mx memories list --format json | \
jq '.data[] | select(.topics[] | contains("important"))' > important_memories.jsonDelete old test memories (be careful!)
mx memories list --format json | \
jq -r '.data[] | select(.content | contains("test")) | .id' | \
while read id; do
mx memories delete "$id" --force
done
`Help and Documentation
Every command has built-in help:
`bash
Global help
mx --helpCommand-specific help
mx memories --help
mx memories create --help
mx auth --help
mx config --help
`Development
$3
`bash
Run all tests
npm testRun tests with coverage
npm test -- --coverageRun specific test file
npm test -- tests/commands/memories.test.ts
`$3
`bash
Check for linting errors
npm run lintAuto-fix linting errors
npm run lint -- --fix
`$3
`bash
Build TypeScript to JavaScript
npm run buildWatch mode for development
npm run build -- --watch
`Troubleshooting
$3
If
mx command is not found after npm link:`bash
Check npm global bin path
npm bin -gEnsure it's in your PATH
echo $PATHRe-link the package
npm unlink -g @memnexus-ai/cli
npm link
`$3
If you get authentication errors:
`bash
Check your auth status
mx auth statusVerify API key is set
mx config listRe-login
mx auth login --api-key your-api-key-here
`$3
If you can't connect to the API:
`bash
Verify API URL
mx config get apiUrlTest with curl
curl http://api.memnexus.ai/healthUpdate API URL if needed
mx config set apiUrl http://api.memnexus.ai
`Contributing
Contributions are welcome! Please ensure:
- All tests pass (
npm test)
- Code is linted (npm run lint`)[Add your license here]
For issues and questions:
- GitHub Issues: memnexus-ai/mx-cli
- Documentation: docs/prd.md