mx-cli

Command-line interface for MemNexus - Your personal memory and knowledge management system

Overview

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.

Features

• 🔐 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

Installation & Setup

Prerequisites

• Node.js 18+ and npm
• Access to a MemNexus API instance

Installation Options

Option 1: Install from npm (Recommended)

# Install globally from npm
npm install -g @memnexus-ai/cli

# Verify installation
mx --version

Published on npm: https://www.npmjs.com/package/@memnexus-ai/cli

Option 2: Install from Source (Development)

# Clone the repository
cd mx-cli

# Install dependencies
npm install

# Build the CLI
npm run build

# Link globally to use 'mx' command
npm link

# Verify installation
mx --version

Configuration

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:

# Copy the example file
cp .env.example .env

# Edit .env with your credentials
# MX_API_URL=http://api.memnexus.ai
# MX_API_KEY=your-api-key-here

Then load the environment variables:

source .env

Option 2: Using CLI Commands

# Set API URL
mx config set apiUrl http://api.memnexus.ai

# Login with API key
mx auth login --api-key your-api-key-here

# Verify configuration
mx auth status

Environment Variables

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:

# 1. Install from npm
npm install -g @memnexus-ai/cli

# 2. Configure authentication (interactive mode with password masking)
mx auth login --interactive

# 3. Verify connection
mx auth status

# 4. Create your first memory
mx memories create --interactive

# 5. List your memories
mx memories list

# 6. 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.0

# 8. Explore other commands
mx --help

Common Workflows

Daily Memory Capture

# Quick memory creation
mx memories create --content "Meeting notes: discussed Q4 roadmap" \
  --memory-type episodic \
  --topics "work,meetings" \
  --importance 0.8

# Search recent memories
mx memories search --query "Q4 roadmap"

Knowledge Graph Building

# 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.0

# Search facts
mx facts search --query "TypeScript"

Batch Operations with JSON Output

# Export all memories to JSON
mx memories list --format json --limit 1000 > memories.json

# Find 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

Authentication Commands

Login

Store your API key for authentication:

# 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:

mx auth status

Output:

┌──────────────────┬────────────────────────────┐
│ Property         │ Value                      │
├──────────────────┼────────────────────────────┤
│ Authentication   │ ✓ Configured (via config)  │
│ API URL          │ http://api.memnexus.ai     │
│ Output Format    │ table                      │
└──────────────────┴────────────────────────────┘

Logout

Remove stored credentials:

mx auth logout

Configuration Commands

Get Configuration

Retrieve a specific configuration value:

# Get API URL
mx config get apiUrl

# Get default output format
mx config get defaultFormat

Set Configuration

Update configuration values:

# Set API URL
mx config set apiUrl http://api.memnexus.ai

# Set default output format
mx config set defaultFormat json

# Set default page size
mx config set defaultPageSize 50

List All Configuration

View all configuration settings and their sources:

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:

mx config reset

Update Commands

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:

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:

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:

mx update --yes

Update to Specific Version

Install a specific version:

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)

Memory Management Commands

Memories are the core data structure in MemNexus, representing episodic or semantic information.

List Memories

View all memories with pagination:

# List first page (default: 20 items)
mx memories list

# List with custom pagination
mx memories list --page 0 --limit 10

# Output as JSON
mx memories list --format json

# Output as YAML
mx memories list --format yaml

Get a Specific Memory

Retrieve detailed information about a memory:

# Get memory by full UUID
mx memories get 26be666e-7503-40d7-9293-8ffbcdc04dd2

# Get memory by short ID prefix (minimum 8 characters, like git)
mx memories get 26be666e

# Get 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:

# 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.9

# Interactive mode - prompts for each field
mx memories create --interactive

# Minimal creation (only content required)
mx memories create --content "Quick note about something important"

Options:

• --content <text> - Memory content (required)
• --memory-type <type> - Type: episodic or semantic
• --context <context> - Context identifier
• --topics <topics> - Comma-separated topics
• --importance <number> - Importance score (0-1)
• --interactive - Interactive mode with prompts

Update a Memory

Modify existing memory fields:

# 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.95

# Update 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):

# Delete with confirmation prompt
mx memories delete 26be666e-7503-40d7-9293-8ffbcdc04dd2

# Delete without confirmation
mx memories delete 26be666e-7503-40d7-9293-8ffbcdc04dd2 --force

Search Memories

Search for memories using semantic or keyword search:

# Basic search
mx memories search --query "Phase 2 implementation"

# Search with limit
mx memories search --query "CLI development" --limit 5

# Search with specific mode
mx memories search --query "testing" --mode unified

# Search modes: unified (default), content, facts
mx memories search --query "authentication" --mode content

# Output only IDs (for piping to other commands)
mx memories search --query "old data" --id-only

# Pipe IDs to batch delete
mx memories search --query "test" --id-only | xargs -I {} mx memories delete {} --force

Conversation Management Commands

Query and manage conversation history.

List Conversations

View all conversations:

# List conversations
mx conversations list

# With pagination
mx conversations list --page 0 --limit 10

# As JSON
mx conversations list --format json

Get Conversation Details

Retrieve a specific conversation:

mx conversations get conv_abc123

View Conversation Timeline

Get chronological message history:

mx conversations timeline conv_abc123

Search Conversations

Search through conversation content:

mx conversations search --query "authentication discussion"

Find Conversations by Topic

Filter conversations by topic:

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.

Facts Management Commands

Manage semantic facts in knowledge graph format (subject-predicate-object triples).

List Facts

View all facts:

# List facts
mx facts list

# With pagination
mx facts list --page 0 --limit 10

# As table (default)
mx facts list --format table

Get a Specific Fact

Retrieve detailed information about a fact:

mx facts get fact_abc123

Create a Fact

Create new semantic facts:

# Direct mode
mx facts create \
  --subject "TypeScript" \
  --predicate "is_a" \
  --object "Programming Language" \
  --confidence 1.0

# Interactive mode
mx facts create --interactive

# With context and metadata
mx facts create \
  --subject "mx-cli" \
  --predicate "implements" \
  --object "Commander.js pattern" \
  --confidence 0.95 \
  --context development

Options:

• --subject <text> - Fact subject (required)
• --predicate <text> - Relationship/predicate (required)
• --object <text> - Fact object (required)
• --confidence <number> - Confidence score 0-1 (default: 1.0)
• --context <context> - Context identifier
• --interactive - Interactive mode

Update a Fact

Modify existing fact fields:

# Update confidence
mx facts update fact_abc123 --confidence 0.98

# Update multiple fields
mx facts update fact_abc123 \
  --subject "Updated subject" \
  --confidence 0.9

Delete a Fact

Remove a fact:

# With confirmation
mx facts delete fact_abc123

# Without confirmation
mx facts delete fact_abc123 --force

Search Facts

Search through facts:

# Basic search
mx facts search --query "TypeScript"

# With limit
mx facts search --query "programming" --limit 10

Advanced Commands

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:

# List all topics
mx topics list

# Get topic details
mx topics get <topic-id>

# Merge two topics (with confirmation)
mx topics merge --source-id <id1> --target-id <id2>

# Skip confirmation
mx topics merge --source-id <id1> --target-id <id2> --force

# Discover related topics
mx topics discover-related --topic-id <id>

# Calculate similarity between topics
mx topics similarity --topic-id-1 <id1> --topic-id-2 <id2>

# Find similar topics
mx topics find-similar --topic-id <id> --threshold 0.7

# Cluster topics using algorithms
mx topics cluster --algorithm kmeans --num-clusters 5
mx topics cluster --algorithm hierarchical
mx topics cluster --algorithm dbscan

# Detect 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:

# List communities
mx communities list

# Get community details
mx communities get <community-id>

# Merge communities (with confirmation)
mx communities merge --source-id <id1> --target-id <id2>

Patterns Commands

Compile and manage behavioral patterns from your memories:

# Compile patterns from context
mx patterns compile --context-id <id>

# Record feedback on a pattern
mx patterns feedback --pattern-id <id> --feedback positive
mx patterns feedback --pattern-id <id> --feedback negative

# Set behavioral state
mx patterns set-state --pattern-id <id> --state active
mx patterns set-state --pattern-id <id> --state inactive

GraphRAG Commands

Execute graph-based retrieval augmented generation queries:

# 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 <id>

# Query communities
mx graphrag query-communities --query "technical discussions" --limit 5

Artifacts Commands

Manage artifacts (files, documents, etc.):

# List artifacts
mx artifacts list

# Get artifact details
mx artifacts get <artifact-id>

# Create artifact (interactive mode)
mx artifacts create --interactive

# Create artifact (direct mode)
mx artifacts create --name "Document" --type "pdf"

# Update artifact
mx artifacts update <id> --name "Updated Name"

# Delete artifact (with confirmation)
mx artifacts delete <id>

# Skip confirmation
mx artifacts delete <id> --force

API Keys Commands

Manage API keys:

# List API keys (metadata only, never shows actual keys)
mx apikeys list

# Create 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 <key-id>

# Skip confirmation
mx apikeys delete <key-id> --force

System Commands

Check system health and status:

# Check system health
mx system health

# Get system status
mx system status

# List feature flags
mx system feature-flags

Common Options

These options are available across multiple commands:

Output Formats

Control how data is displayed:

# Table format (default) - human-readable
mx memories list --format table

# JSON format - for scripting and parsing
mx memories list --format json

# YAML format - human-readable structured data
mx memories list --format yaml

Pagination

Handle large datasets efficiently:

# Default pagination (page 0, 20 items)
mx memories list

# Custom page and limit
mx memories list --page 2 --limit 50

# First 100 items
mx memories list --page 0 --limit 100

Interactive Mode

User-friendly prompts for creating resources with validation and helpful hints:

# Interactive memory creation
mx memories create --interactive

# Interactive fact creation
mx facts create --interactive

# Interactive artifact creation
mx artifacts create --interactive

# Interactive 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

Force Flag

Skip confirmation prompts for destructive operations:

# Delete operations
mx memories delete <id> --force
mx facts delete <id> --force
mx artifacts delete <id> --force
mx apikeys delete <id> --force

# Merge operations
mx topics merge --source-id <id1> --target-id <id2> --force
mx communities merge --source-id <id1> --target-id <id2> --force

⚠️ Warning: Using --force skips safety confirmations. Use with caution, especially in production environments.

Example Workflows

Complete Setup and First Memory

# 1. Build and link the CLI
cd mx-cli
npm install
npm run build
npm link

# 2. Configure using environment variables
cp .env.example .env
# Edit .env with your API key and URL
source .env

# 3. Verify authentication
mx auth status

# 4. 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.8

# 5. List your memories
mx memories list

# 6. Search for memories
mx memories search --query "getting started"

Working with Different Output Formats

# Get memory as JSON for scripting
MEMORY_JSON=$(mx memories get <id> --format json)

# List memories as YAML for readability
mx memories list --format yaml

# Export all memories to JSON file
mx memories list --format json --limit 1000 > memories.json

Creating and Linking Facts

# Create a fact about a technology
mx facts create \
  --subject "mx-cli" \
  --predicate "built_with" \
  --object "TypeScript" \
  --confidence 1.0

# Create a related fact
mx facts create \
  --subject "mx-cli" \
  --predicate "uses" \
  --object "Commander.js" \
  --confidence 1.0

# Search for related facts
mx facts search --query "mx-cli"

Batch Operations with Shell Scripting

# Create multiple memories from a file
while IFS= read -r line; do
  mx memories create --content "$line" --memory-type episodic
done < notes.txt

# Export all memories with specific topic
mx memories list --format json | \
  jq '.data[] | select(.topics[] | contains("important"))' > important_memories.json

# Delete 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:

# Global help
mx --help

# Command-specific help
mx memories --help
mx memories create --help
mx auth --help
mx config --help

Development

Running Tests

# Run all tests
npm test

# Run tests with coverage
npm test -- --coverage

# Run specific test file
npm test -- tests/commands/memories.test.ts

Linting

# Check for linting errors
npm run lint

# Auto-fix linting errors
npm run lint -- --fix

Building

# Build TypeScript to JavaScript
npm run build

# Watch mode for development
npm run build -- --watch

Troubleshooting

Command Not Found

If mx command is not found after npm link:

# Check npm global bin path
npm bin -g

# Ensure it's in your PATH
echo $PATH

# Re-link the package
npm unlink -g @memnexus-ai/cli
npm link

Authentication Errors

If you get authentication errors:

# Check your auth status
mx auth status

# Verify API key is set
mx config list

# Re-login
mx auth login --api-key your-api-key-here

API Connection Issues

If you can't connect to the API:

# Verify API URL
mx config get apiUrl

# Test with curl
curl http://api.memnexus.ai/health

# Update 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)
• New features include tests
• Documentation is updated

License

[Add your license here]

Support

For issues and questions:

• GitHub Issues: memnexus-ai/mx-cli
• Documentation: docs/prd.md