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

$3

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

$3

#### Option 1: Install from npm (Recommended)

``bash


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)

`bash


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
`

$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 .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:

`bash
source .env
`

#### Option 2: Using CLI Commands

`bash


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
`

$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/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
`

$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.8

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

Search 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.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

$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 apiUrl

Get default output format

mx config get defaultFormat
`

#### Set Configuration

Update configuration values:

`bash


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:

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

`bash


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:

`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.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 - 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.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):

`bash


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:

`bash


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
`

$3

Query and manage conversation history.

#### List Conversations

View all conversations:

`bash


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:

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

`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.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 - 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.98

Update 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_abc123

Without 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 list

Get 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 --force

Discover 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.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:

`bash


List communities

mx communities list

Get 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 negative

Set 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 list

Get artifact details

mx artifacts get

Create artifact (interactive mode)

mx artifacts create --interactive

Create 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 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

Skip confirmation

mx apikeys delete --force
`

#### System Commands

Check system health and status:

`bash


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:

$3

Control how data is displayed:

`bash


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
`

$3

Handle large datasets efficiently:

`bash


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
`

$3

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

`bash


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

$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 --force

Merge 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 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"
`

$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 yaml

Export 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.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"
`

$3

`bash


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:

`bash


Global help

mx --help

Command-specific help

mx memories --help
mx memories create --help
mx auth --help
mx config --help
`

Development

$3

`bash


Run all tests

npm test

Run tests with coverage

npm test -- --coverage

Run specific test file

npm test -- tests/commands/memories.test.ts
`

$3

`bash


Check for linting errors

npm run lint

Auto-fix linting errors

npm run lint -- --fix
`

$3

`bash


Build TypeScript to JavaScript

npm run build

Watch 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 -g

Ensure it's in your PATH

echo $PATH

Re-link the package

npm unlink -g @memnexus-ai/cli
npm link
`

$3

If you get authentication errors:

`bash


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
`

$3

If you can't connect to the API:

`bash


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