@memnexus-ai/cli 0.1.1 → 0.1.4

package/README.md

@@ -1,986 +1,986 @@
-# 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
-- GitHub account with access to the memnexus-ai organization (for GitHub Packages installation)
-
-### Installation Options
-
-#### Option 1: Install from GitHub Packages (Recommended)
-
-```bash
-# Configure npm to use GitHub Packages for @memnexus-ai scope
-npm config set @memnexus-ai:registry https://npm.pkg.github.com
-
-# Authenticate with GitHub Packages (requires GitHub personal access token with read:packages scope)
-npm login --scope=@memnexus-ai --registry=https://npm.pkg.github.com
-
-# Install globally
-npm install -g @memnexus-ai/cli
-
-# Verify installation
-mx --version
-```
-
-**Note**: You'll need a GitHub personal access token with `read:packages` scope. Create one at: https://github.com/settings/tokens
-
-#### 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
-```
-
-### 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:
-
-```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
-```
-
-### Environment Variables
-
-The following environment variables are supported:
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `MX_API_URL` | MemNexus API base URL | `https://api.memnexus.io` |
-| `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 GitHub Packages
-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
-
-```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
-
-### Authentication Commands
-
-#### 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
-```
-
-### Configuration Commands
-
-#### 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
-```
-
-### Memory Management Commands
-
-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 ID
-mx memories get 26be666e-7503-40d7-9293-8ffbcdc04dd2
-
-# Get as JSON
-mx memories get 26be666e-7503-40d7-9293-8ffbcdc04dd2 --format json
-```
-
-#### 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 <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:
-
-```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
-```
-
-### Conversation Management Commands
-
-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.
-
-### Facts Management Commands
-
-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 <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:
-
-```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
-```
-
-### 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:
-
-```bash
-# 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:
-
-```bash
-# 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:
-
-```bash
-# 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:
-
-```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 <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 <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:
-
-```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 <key-id>
-
-# Skip confirmation
-mx apikeys delete <key-id> --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:
-
-### Output Formats
-
-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
-```
-
-### Pagination
-
-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
-```
-
-### Interactive Mode
-
-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
-
-### Force Flag
-
-Skip confirmation prompts for destructive operations:
-
-```bash
-# 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
-
-```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"
-```
-
-### Working with Different Output Formats
-
-```bash
-# 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
-
-```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"
-```
-
-### Batch Operations with Shell Scripting
-
-```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
-
-### Running Tests
-
-```bash
-# Run all tests
-npm test
-
-# Run tests with coverage
-npm test -- --coverage
-
-# Run specific test file
-npm test -- tests/commands/memories.test.ts
-```
-
-### Linting
-
-```bash
-# Check for linting errors
-npm run lint
-
-# Auto-fix linting errors
-npm run lint -- --fix
-```
-
-### Building
-
-```bash
-# 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`:
-
-```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
-```
-
-### Authentication Errors
-
-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
-```
-
-### API Connection Issues
-
-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](https://github.com/memnexus-ai/mx-cli/issues)
-- Documentation: [docs/prd.md](docs/prd.md)
+# 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
+- GitHub account with access to the memnexus-ai organization (for GitHub Packages installation)
+
+### Installation Options
+
+#### Option 1: Install from GitHub Packages (Recommended)
+
+```bash
+# Configure npm to use GitHub Packages for @memnexus-ai scope
+npm config set @memnexus-ai:registry https://npm.pkg.github.com
+
+# Authenticate with GitHub Packages (requires GitHub personal access token with read:packages scope)
+npm login --scope=@memnexus-ai --registry=https://npm.pkg.github.com
+
+# Install globally
+npm install -g @memnexus-ai/cli
+
+# Verify installation
+mx --version
+```
+
+**Note**: You'll need a GitHub personal access token with `read:packages` scope. Create one at: https://github.com/settings/tokens
+
+#### 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
+```
+
+### 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:
+
+```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
+```
+
+### Environment Variables
+
+The following environment variables are supported:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `MX_API_URL` | MemNexus API base URL | `https://api.memnexus.io` |
+| `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 GitHub Packages
+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
+
+```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
+
+### Authentication Commands
+
+#### 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
+```
+
+### Configuration Commands
+
+#### 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
+```
+
+### Memory Management Commands
+
+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 ID
+mx memories get 26be666e-7503-40d7-9293-8ffbcdc04dd2
+
+# Get as JSON
+mx memories get 26be666e-7503-40d7-9293-8ffbcdc04dd2 --format json
+```
+
+#### 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 <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:
+
+```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
+```
+
+### Conversation Management Commands
+
+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.
+
+### Facts Management Commands
+
+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 <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:
+
+```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
+```
+
+### 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:
+
+```bash
+# 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:
+
+```bash
+# 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:
+
+```bash
+# 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:
+
+```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 <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 <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:
+
+```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 <key-id>
+
+# Skip confirmation
+mx apikeys delete <key-id> --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:
+
+### Output Formats
+
+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
+```
+
+### Pagination
+
+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
+```
+
+### Interactive Mode
+
+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
+
+### Force Flag
+
+Skip confirmation prompts for destructive operations:
+
+```bash
+# 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
+
+```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"
+```
+
+### Working with Different Output Formats
+
+```bash
+# 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
+
+```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"
+```
+
+### Batch Operations with Shell Scripting
+
+```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
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests with coverage
+npm test -- --coverage
+
+# Run specific test file
+npm test -- tests/commands/memories.test.ts
+```
+
+### Linting
+
+```bash
+# Check for linting errors
+npm run lint
+
+# Auto-fix linting errors
+npm run lint -- --fix
+```
+
+### Building
+
+```bash
+# 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`:
+
+```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
+```
+
+### Authentication Errors
+
+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
+```
+
+### API Connection Issues
+
+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](https://github.com/memnexus-ai/mx-cli/issues)
+- Documentation: [docs/prd.md](docs/prd.md)