@memnexus-ai/cli 0.1.0

package/USAGE.md

@@ -0,0 +1,1373 @@
+# mx-cli Usage Guide
+
+Complete reference for all mx-cli commands, options, and usage patterns.
+
+## Table of Contents
+
+- [Authentication Commands](#authentication-commands)
+- [Configuration Commands](#configuration-commands)
+- [Memory Commands](#memory-commands)
+- [Conversation Commands](#conversation-commands)
+- [Fact Commands](#fact-commands)
+- [Topic Commands](#topic-commands)
+- [Community Commands](#community-commands)
+- [Pattern Commands](#pattern-commands)
+- [GraphRAG Commands](#graphrag-commands)
+- [Artifact Commands](#artifact-commands)
+- [API Key Commands](#api-key-commands)
+- [System Commands](#system-commands)
+- [Global Options](#global-options)
+- [Output Formats](#output-formats)
+- [Best Practices](#best-practices)
+
+---
+
+## Authentication Commands
+
+### `mx auth login`
+
+Configure API key for authentication.
+
+**Options:**
+- `--api-key <key>` - API key to store
+- `--interactive` - Prompt for API key with password masking
+
+**Examples:**
+```bash
+# Direct login
+mx auth login --api-key cmk_live_abc123.xyz789
+
+# Interactive mode (recommended for security)
+mx auth login --interactive
+```
+
+**Notes:**
+- Interactive mode masks the API key input for security
+- API key is stored in `~/.mx-cli/config.json`
+- Can also be set via `MX_API_KEY` environment variable
+
+### `mx auth logout`
+
+Remove stored credentials.
+
+**Examples:**
+```bash
+mx auth logout
+```
+
+### `mx auth status`
+
+Show current authentication status.
+
+**Examples:**
+```bash
+mx auth status
+```
+
+**Output:**
+- Authentication status (configured/not configured)
+- API URL
+- Output format
+- Source of configuration (environment/config file)
+
+---
+
+## Configuration Commands
+
+### `mx config set <key> <value>`
+
+Set a configuration value.
+
+**Available Keys:**
+- `apiUrl` - MemNexus API base URL
+- `format` - Default output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx config set apiUrl https://api.memnexus.io
+mx config set format json
+```
+
+### `mx config get <key>`
+
+Get a configuration value.
+
+**Examples:**
+```bash
+mx config get apiUrl
+mx config get format
+```
+
+### `mx config list`
+
+List all configuration values.
+
+**Examples:**
+```bash
+mx config list
+```
+
+---
+
+## Memory Commands
+
+### `mx memories list`
+
+List memories with pagination.
+
+**Options:**
+- `--page <number>` - Page number (default: 0)
+- `--limit <number>` - Results per page (default: 20)
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+# List first page
+mx memories list
+
+# List with custom pagination
+mx memories list --page 2 --limit 50
+
+# Output as JSON
+mx memories list --format json
+```
+
+### `mx memories get <id>`
+
+Get a specific memory by ID.
+
+**Options:**
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx memories get 26be666e-7503-40d7-9293-8ffbcdc04dd2
+mx memories get 26be666e-7503-40d7-9293-8ffbcdc04dd2 --format json
+```
+
+### `mx memories create`
+
+Create a new memory.
+
+**Options:**
+- `--content <text>` - Memory content (required in direct mode)
+- `--memory-type <type>` - Type: episodic or semantic (default: episodic)
+- `--context <context>` - Context identifier
+- `--topics <topics>` - Comma-separated topics
+- `--importance <number>` - Importance score 0-1 (default: 0.5)
+- `--interactive` - Interactive mode with prompts
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+# Interactive mode (recommended)
+mx memories create --interactive
+
+# Direct mode
+mx memories create \
+  --content "Meeting notes: Q4 planning session" \
+  --memory-type episodic \
+  --context work \
+  --topics "meetings,planning,q4" \
+  --importance 0.8
+
+# Minimal creation
+mx memories create --content "Quick note"
+```
+
+### `mx memories update <id>`
+
+Update an existing memory.
+
+**Options:**
+- `--content <text>` - Updated content
+- `--memory-type <type>` - Updated memory type
+- `--context <context>` - Updated context
+- `--topics <topics>` - Updated topics (comma-separated)
+- `--importance <number>` - Updated importance (0-1)
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+# Update content
+mx memories update 26be666e-7503-40d7-9293-8ffbcdc04dd2 \
+  --content "Updated meeting notes"
+
+# Update multiple fields
+mx memories update 26be666e-7503-40d7-9293-8ffbcdc04dd2 \
+  --content "New content" \
+  --topics "updated,tags" \
+  --importance 0.9
+```
+
+### `mx memories delete <id>`
+
+Delete a memory.
+
+**Options:**
+- `--force` - Skip confirmation prompt
+
+**Examples:**
+```bash
+# With confirmation
+mx memories delete 26be666e-7503-40d7-9293-8ffbcdc04dd2
+
+# Skip confirmation
+mx memories delete 26be666e-7503-40d7-9293-8ffbcdc04dd2 --force
+```
+
+### `mx memories search`
+
+Search memories using semantic or keyword search.
+
+**Options:**
+- `--query <text>` - Search query (required)
+- `--limit <number>` - Maximum results (default: 20)
+- `--mode <mode>` - Search mode: unified|content|facts (default: unified)
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+# Basic search
+mx memories search --query "Q4 planning"
+
+# Search with limit
+mx memories search --query "meetings" --limit 10
+
+# Content-only search
+mx memories search --query "technical discussion" --mode content
+
+# Facts-only search
+mx memories search --query "TypeScript" --mode facts
+```
+
+---
+
+## Conversation Commands
+
+### `mx conversations list`
+
+List conversations with pagination.
+
+**Options:**
+- `--page <number>` - Page number (default: 0)
+- `--limit <number>` - Results per page (default: 20)
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx conversations list
+mx conversations list --page 1 --limit 50
+```
+
+### `mx conversations get <id>`
+
+Get conversation details.
+
+**Options:**
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx conversations get conv_abc123
+```
+
+### `mx conversations timeline <id>`
+
+Get chronological message history for a conversation.
+
+**Options:**
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx conversations timeline conv_abc123
+```
+
+### `mx conversations search`
+
+Search through conversation content.
+
+**Options:**
+- `--query <text>` - Search query (required)
+- `--limit <number>` - Maximum results (default: 20)
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx conversations search --query "authentication discussion"
+```
+
+### `mx conversations by-topic`
+
+Find conversations by topic.
+
+**Options:**
+- `--topic-id <id>` - Topic ID (required)
+- `--limit <number>` - Maximum results (default: 20)
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx conversations by-topic --topic-id topic_123
+```
+
+---
+
+## Fact Commands
+
+### `mx facts list`
+
+List facts with pagination.
+
+**Options:**
+- `--page <number>` - Page number (default: 0)
+- `--limit <number>` - Results per page (default: 20)
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx facts list
+mx facts list --page 1 --limit 50 --format json
+```
+
+### `mx facts get <id>`
+
+Get a specific fact by ID.
+
+**Options:**
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx facts get fact_abc123
+```
+
+### `mx facts create`
+
+Create a new fact (subject-predicate-object triple).
+
+**Options:**
+- `--subject <text>` - Subject of the fact (required in direct mode)
+- `--predicate <text>` - Predicate/relationship (required in direct mode)
+- `--object <text>` - Object of the fact (required in direct mode)
+- `--confidence <number>` - Confidence score 0-1 (default: 1.0)
+- `--memory-id <id>` - Associated memory ID
+- `--interactive` - Interactive mode with prompts
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+# Interactive mode
+mx facts create --interactive
+
+# Direct mode
+mx facts create \
+  --subject "TypeScript" \
+  --predicate "is_a" \
+  --object "Programming Language" \
+  --confidence 1.0
+
+# With memory association
+mx facts create \
+  --subject "mx-cli" \
+  --predicate "built_with" \
+  --object "TypeScript" \
+  --confidence 1.0 \
+  --memory-id mem_abc123
+```
+
+### `mx facts update <id>`
+
+Update an existing fact.
+
+**Options:**
+- `--subject <text>` - Updated subject
+- `--predicate <text>` - Updated predicate
+- `--object <text>` - Updated object
+- `--confidence <number>` - Updated confidence (0-1)
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx facts update fact_abc123 --confidence 0.9
+mx facts update fact_abc123 --predicate "uses" --confidence 0.95
+```
+
+### `mx facts delete <id>`
+
+Delete a fact.
+
+**Options:**
+- `--force` - Skip confirmation prompt
+
+**Examples:**
+```bash
+# With confirmation
+mx facts delete fact_abc123
+
+# Skip confirmation
+mx facts delete fact_abc123 --force
+```
+
+### `mx facts search`
+
+Search through facts.
+
+**Options:**
+- `--query <text>` - Search query (required)
+- `--limit <number>` - Maximum results (default: 20)
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx facts search --query "TypeScript"
+mx facts search --query "programming" --limit 10 --format json
+```
+
+---
+
+## Topic Commands
+
+### `mx topics list`
+
+List all topics.
+
+**Options:**
+- `--page <number>` - Page number (default: 0)
+- `--limit <number>` - Results per page (default: 20)
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx topics list
+mx topics list --limit 50 --format json
+```
+
+### `mx topics get <id>`
+
+Get topic details.
+
+**Options:**
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx topics get topic_abc123
+```
+
+### `mx topics merge`
+
+Merge two topics together.
+
+**Options:**
+- `--source-id <id>` - Source topic ID to merge from (required)
+- `--target-id <id>` - Target topic ID to merge into (required)
+- `--force` - Skip confirmation prompt
+
+**Examples:**
+```bash
+# With confirmation
+mx topics merge --source-id topic_123 --target-id topic_456
+
+# Skip confirmation
+mx topics merge --source-id topic_123 --target-id topic_456 --force
+```
+
+### `mx topics discover-related`
+
+Discover topics related to a given topic.
+
+**Options:**
+- `--topic-id <id>` - Topic ID (required)
+- `--limit <number>` - Maximum results (default: 10)
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx topics discover-related --topic-id topic_abc123
+mx topics discover-related --topic-id topic_abc123 --limit 20
+```
+
+### `mx topics similarity`
+
+Calculate similarity between two topics.
+
+**Options:**
+- `--topic-id-1 <id>` - First topic ID (required)
+- `--topic-id-2 <id>` - Second topic ID (required)
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx topics similarity --topic-id-1 topic_123 --topic-id-2 topic_456
+```
+
+### `mx topics find-similar`
+
+Find topics similar to a given topic.
+
+**Options:**
+- `--topic-id <id>` - Topic ID (required)
+- `--threshold <number>` - Similarity threshold 0-1 (default: 0.7)
+- `--limit <number>` - Maximum results (default: 10)
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx topics find-similar --topic-id topic_abc123
+mx topics find-similar --topic-id topic_abc123 --threshold 0.8 --limit 20
+```
+
+### `mx topics cluster`
+
+Cluster topics using various algorithms.
+
+**Options:**
+- `--algorithm <name>` - Algorithm: kmeans|hierarchical|dbscan (required)
+- `--num-clusters <number>` - Number of clusters (for kmeans, default: 5)
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+# K-means clustering
+mx topics cluster --algorithm kmeans --num-clusters 5
+
+# Hierarchical clustering
+mx topics cluster --algorithm hierarchical
+
+# DBSCAN clustering
+mx topics cluster --algorithm dbscan
+```
+
+### `mx topics detect-communities`
+
+Detect communities in the topic graph.
+
+**Options:**
+- `--algorithm <name>` - Algorithm: louvain|label-propagation|girvan-newman (required)
+- `--min-size <number>` - Minimum community size (default: 2)
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+# Louvain method
+mx topics detect-communities --algorithm louvain
+
+# Label propagation
+mx topics detect-communities --algorithm label-propagation --min-size 3
+
+# Girvan-Newman
+mx topics detect-communities --algorithm girvan-newman
+```
+
+---
+
+## Community Commands
+
+### `mx communities list`
+
+List all communities.
+
+**Options:**
+- `--page <number>` - Page number (default: 0)
+- `--limit <number>` - Results per page (default: 20)
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx communities list
+mx communities list --limit 50
+```
+
+### `mx communities get <id>`
+
+Get community details.
+
+**Options:**
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx communities get community_abc123
+```
+
+### `mx communities merge`
+
+Merge two communities.
+
+**Options:**
+- `--source-id <id>` - Source community ID (required)
+- `--target-id <id>` - Target community ID (required)
+- `--force` - Skip confirmation prompt
+
+**Examples:**
+```bash
+# With confirmation
+mx communities merge --source-id comm_123 --target-id comm_456
+
+# Skip confirmation
+mx communities merge --source-id comm_123 --target-id comm_456 --force
+```
+
+---
+
+## Pattern Commands
+
+### `mx patterns compile`
+
+Compile behavioral patterns from a context.
+
+**Options:**
+- `--context-id <id>` - Context ID (required)
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx patterns compile --context-id ctx_abc123
+```
+
+### `mx patterns feedback`
+
+Record feedback on a pattern.
+
+**Options:**
+- `--pattern-id <id>` - Pattern ID (required)
+- `--feedback <type>` - Feedback type: positive|negative (required)
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx patterns feedback --pattern-id pattern_123 --feedback positive
+mx patterns feedback --pattern-id pattern_456 --feedback negative
+```
+
+### `mx patterns set-state`
+
+Set the state of a behavioral pattern.
+
+**Options:**
+- `--pattern-id <id>` - Pattern ID (required)
+- `--state <state>` - State: active|inactive (required)
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx patterns set-state --pattern-id pattern_123 --state active
+mx patterns set-state --pattern-id pattern_456 --state inactive
+```
+
+---
+
+## GraphRAG Commands
+
+### `mx graphrag query`
+
+Execute a graph-based retrieval augmented generation query.
+
+**Options:**
+- `--query <text>` - Query text (required)
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx graphrag query --query "What are the main themes in my work memories?"
+mx graphrag query --query "Summarize technical discussions from last week"
+```
+
+### `mx graphrag explain`
+
+Generate an explanation for a specific memory using graph context.
+
+**Options:**
+- `--memory-id <id>` - Memory ID (required)
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx graphrag explain --memory-id mem_abc123
+```
+
+### `mx graphrag query-communities`
+
+Query across detected communities.
+
+**Options:**
+- `--query <text>` - Query text (required)
+- `--limit <number>` - Maximum communities to query (default: 5)
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx graphrag query-communities --query "technical discussions"
+mx graphrag query-communities --query "project planning" --limit 10
+```
+
+---
+
+## Artifact Commands
+
+### `mx artifacts list`
+
+List artifacts with pagination.
+
+**Options:**
+- `--page <number>` - Page number (default: 0)
+- `--limit <number>` - Results per page (default: 20)
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx artifacts list
+mx artifacts list --page 1 --limit 50
+```
+
+### `mx artifacts get <id>`
+
+Get artifact details.
+
+**Options:**
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx artifacts get artifact_abc123
+```
+
+### `mx artifacts create`
+
+Create a new artifact.
+
+**Options:**
+- `--name <text>` - Artifact name (required in direct mode)
+- `--type <text>` - Artifact type (required in direct mode)
+- `--context-id <id>` - Associated context ID
+- `--data <json>` - Artifact data as JSON string
+- `--metadata <json>` - Artifact metadata as JSON string
+- `--interactive` - Interactive mode with prompts
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+# Interactive mode (recommended)
+mx artifacts create --interactive
+
+# Direct mode
+mx artifacts create \
+  --name "Project Document" \
+  --type "pdf" \
+  --context-id ctx_123 \
+  --data '{"url": "https://example.com/doc.pdf"}' \
+  --metadata '{"author": "John Doe"}'
+```
+
+### `mx artifacts update <id>`
+
+Update an existing artifact.
+
+**Options:**
+- `--name <text>` - Updated name
+- `--type <text>` - Updated type
+- `--data <json>` - Updated data as JSON string
+- `--metadata <json>` - Updated metadata as JSON string
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx artifacts update artifact_abc123 --name "Updated Document"
+mx artifacts update artifact_abc123 --metadata '{"version": "2.0"}'
+```
+
+### `mx artifacts delete <id>`
+
+Delete an artifact.
+
+**Options:**
+- `--force` - Skip confirmation prompt
+
+**Examples:**
+```bash
+# With confirmation
+mx artifacts delete artifact_abc123
+
+# Skip confirmation
+mx artifacts delete artifact_abc123 --force
+```
+
+---
+
+## API Key Commands
+
+### `mx apikeys list`
+
+List API keys (metadata only, never shows actual keys).
+
+**Options:**
+- `--page <number>` - Page number (default: 0)
+- `--limit <number>` - Results per page (default: 20)
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx apikeys list
+mx apikeys list --format json
+```
+
+**Note:** For security, actual API keys are never displayed. Only metadata like ID, label, and creation date are shown.
+
+### `mx apikeys create`
+
+Create a new API key.
+
+**Options:**
+- `--label <text>` - Label for the API key (required)
+- `--expires-at <datetime>` - Expiration date (ISO 8601 format)
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+# Create key without expiration
+mx apikeys create --label "My CLI Key"
+
+# Create key with expiration
+mx apikeys create --label "Temporary Key" --expires-at "2024-12-31T23:59:59Z"
+```
+
+**Important:** The actual API key is only shown once during creation. Save it securely!
+
+### `mx apikeys delete <id>`
+
+Delete an API key.
+
+**Options:**
+- `--force` - Skip confirmation prompt
+
+**Examples:**
+```bash
+# With confirmation
+mx apikeys delete key_abc123
+
+# Skip confirmation
+mx apikeys delete key_abc123 --force
+```
+
+---
+
+## System Commands
+
+### `mx system health`
+
+Check system health status.
+
+**Options:**
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx system health
+mx system health --format json
+```
+
+### `mx system status`
+
+Get detailed system status.
+
+**Options:**
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx system status
+```
+
+### `mx system feature-flags`
+
+List available feature flags.
+
+**Options:**
+- `--format <format>` - Output format (json|table|yaml)
+
+**Examples:**
+```bash
+mx system feature-flags
+mx system feature-flags --format json
+```
+
+---
+
+## Global Options
+
+These options are available for most commands:
+
+### `--format <format>`
+
+Control output format.
+
+**Values:**
+- `table` - Human-readable table format (default)
+- `json` - JSON format for scripting and parsing
+- `yaml` - YAML format for human-readable structured data
+
+**Examples:**
+```bash
+mx memories list --format json
+mx facts list --format yaml
+mx topics list --format table
+```
+
+**Note:** Can also be set globally via:
+- Environment variable: `MX_OUTPUT_FORMAT=json`
+- Config command: `mx config set format json`
+
+### `--page <number>`
+
+Specify page number for paginated results (0-based).
+
+**Default:** 0
+
+**Examples:**
+```bash
+mx memories list --page 0  # First page
+mx memories list --page 1  # Second page
+mx memories list --page 5  # Sixth page
+```
+
+### `--limit <number>`
+
+Specify number of results per page.
+
+**Default:** 20
+
+**Examples:**
+```bash
+mx memories list --limit 10   # 10 items per page
+mx memories list --limit 50   # 50 items per page
+mx memories list --limit 100  # 100 items per page
+```
+
+### `--force`
+
+Skip confirmation prompts for destructive operations.
+
+**Applies to:**
+- Delete operations (memories, facts, artifacts, apikeys)
+- Merge operations (topics, communities)
+
+**Examples:**
+```bash
+mx memories delete mem_123 --force
+mx topics merge --source-id topic_1 --target-id topic_2 --force
+```
+
+**⚠️ Warning:** Use with caution! This bypasses safety confirmations.
+
+### `--interactive`
+
+Enable interactive mode with prompts.
+
+**Applies to:**
+- `mx auth login`
+- `mx memories create`
+- `mx facts create`
+- `mx artifacts create`
+
+**Examples:**
+```bash
+mx memories create --interactive
+mx facts create --interactive
+```
+
+**Benefits:**
+- Input validation
+- Helpful error messages
+- Default values
+- Password masking for sensitive inputs
+
+---
+
+## Output Formats
+
+### Table Format (Default)
+
+Human-readable table output, ideal for terminal viewing.
+
+**Example:**
+```bash
+mx memories list --format table
+```
+
+**Output:**
+```
+┌──────────────────────────────────────┬─────────────────────────┬──────────────┬────────────┐
+│ ID                                   │ Content                 │ Type         │ Importance │
+├──────────────────────────────────────┼─────────────────────────┼──────────────┼────────────┤
+│ 26be666e-7503-40d7-9293-8ffbcdc04dd2 │ Meeting notes: Q4...    │ episodic     │ 0.8        │
+│ 3f7a8b2c-1234-5678-90ab-cdef12345678 │ Technical discussion... │ episodic     │ 0.7        │
+└──────────────────────────────────────┴─────────────────────────┴──────────────┴────────────┘
+```
+
+**Best for:**
+- Interactive terminal use
+- Quick visual inspection
+- Human readability
+
+### JSON Format
+
+Machine-readable JSON output, ideal for scripting and parsing.
+
+**Example:**
+```bash
+mx memories list --format json
+```
+
+**Output:**
+```json
+{
+  "data": [
+    {
+      "id": "26be666e-7503-40d7-9293-8ffbcdc04dd2",
+      "content": "Meeting notes: Q4 planning",
+      "memoryType": "episodic",
+      "importance": 0.8,
+      "topics": ["meetings", "planning"],
+      "createdAt": "2024-01-15T10:30:00Z"
+    }
+  ],
+  "pagination": {
+    "page": 0,
+    "limit": 20,
+    "total": 1
+  }
+}
+```
+
+**Best for:**
+- Scripting and automation
+- Piping to tools like `jq`
+- Integration with other systems
+- Programmatic processing
+
+**Note:** Progress spinners are automatically disabled in JSON mode to prevent interference with output parsing.
+
+### YAML Format
+
+Human-readable structured data output.
+
+**Example:**
+```bash
+mx memories list --format yaml
+```
+
+**Output:**
+```yaml
+data:
+  - id: 26be666e-7503-40d7-9293-8ffbcdc04dd2
+    content: Meeting notes: Q4 planning
+    memoryType: episodic
+    importance: 0.8
+    topics:
+      - meetings
+      - planning
+    createdAt: 2024-01-15T10:30:00Z
+pagination:
+  page: 0
+  limit: 20
+  total: 1
+```
+
+**Best for:**
+- Configuration files
+- Human-readable structured data
+- Documentation
+- Debugging
+
+---
+
+## Best Practices
+
+### Authentication
+
+**✅ Do:**
+- Use interactive mode for login: `mx auth login --interactive`
+- Store API keys in environment variables for CI/CD
+- Verify authentication before operations: `mx auth status`
+- Use separate API keys for different environments
+
+**❌ Don't:**
+- Commit API keys to version control
+- Share API keys in plain text
+- Use production keys in development
+
+### Creating Resources
+
+**✅ Do:**
+- Use interactive mode for complex resources: `mx memories create --interactive`
+- Validate JSON before passing to `--data` or `--metadata` options
+- Use meaningful labels and descriptions
+- Set appropriate importance scores (0-1)
+
+**❌ Don't:**
+- Skip validation by forcing operations without review
+- Use generic or unclear content
+- Set all importance scores to 1.0
+
+### Destructive Operations
+
+**✅ Do:**
+- Review confirmation prompts carefully
+- Use `--force` only in scripts and automation
+- Test delete operations on non-critical data first
+- Keep backups of important data
+
+**❌ Don't:**
+- Use `--force` flag casually
+- Delete resources without verification
+- Merge topics/communities without understanding impact
+
+### Scripting and Automation
+
+**✅ Do:**
+- Use JSON format for parsing: `--format json`
+- Pipe JSON to `jq` for filtering and transformation
+- Check exit codes in scripts
+- Use `--force` to skip interactive prompts
+- Set environment variables for configuration
+
+**Example:**
+```bash
+#!/bin/bash
+set -e  # Exit on error
+
+# Export memories to file
+mx memories list --format json --limit 1000 > memories_backup.json
+
+# Find high-importance memories
+mx memories list --format json | \
+  jq '.data[] | select(.importance > 0.8)' > important_memories.json
+
+# Check if operation succeeded
+if [ $? -eq 0 ]; then
+  echo "Backup completed successfully"
+else
+  echo "Backup failed"
+  exit 1
+fi
+```
+
+**❌ Don't:**
+- Parse table format output in scripts
+- Ignore error codes
+- Hard-code credentials in scripts
+
+### Performance
+
+**✅ Do:**
+- Use pagination for large datasets
+- Adjust `--limit` based on your needs
+- Use specific search queries instead of listing all
+- Filter results with `jq` when using JSON format
+
+**Example:**
+```bash
+# Efficient: Search with limit
+mx memories search --query "Q4" --limit 10
+
+# Efficient: Paginate large results
+mx memories list --page 0 --limit 50
+mx memories list --page 1 --limit 50
+```
+
+**❌ Don't:**
+- Request all data at once without pagination
+- Use very large `--limit` values unnecessarily
+- List all resources when you need specific ones
+
+### Error Handling
+
+**✅ Do:**
+- Read error messages carefully - they include troubleshooting steps
+- Check authentication status when getting 401 errors
+- Verify API URL configuration for connection errors
+- Use `mx system health` to check API availability
+
+**Example Error Message:**
+```
+❌ Authentication Error: Invalid or missing API key
+
+💡 To fix this:
+   1. Check auth status: mx auth status
+   2. Login with your API key: mx auth login --api-key <your-key>
+   3. Or use interactive mode: mx auth login --interactive
+```
+
+**❌ Don't:**
+- Ignore error messages
+- Retry failed operations without addressing the root cause
+- Skip authentication verification
+
+### Output Format Selection
+
+**Use `table` format when:**
+- Working interactively in terminal
+- Quickly reviewing data
+- Presenting to humans
+
+**Use `json` format when:**
+- Scripting and automation
+- Piping to other tools
+- Programmatic processing
+- Storing data for later use
+
+**Use `yaml` format when:**
+- Creating configuration files
+- Debugging complex structures
+- Documentation purposes
+- Human-readable exports
+
+### Topic and Community Management
+
+**✅ Do:**
+- Use `discover-related` to explore topic connections
+- Set appropriate similarity thresholds (0.7-0.9)
+- Review merge operations carefully
+- Use clustering to organize large topic sets
+
+**❌ Don't:**
+- Merge topics without understanding relationships
+- Use very low similarity thresholds (<0.5)
+- Delete communities without reviewing members
+
+### GraphRAG Queries
+
+**✅ Do:**
+- Use specific, focused queries
+- Leverage community queries for broad topics
+- Use `explain` to understand memory context
+- Combine with regular search for comprehensive results
+
+**Example:**
+```bash
+# Specific query
+mx graphrag query --query "What technical decisions were made in Q4?"
+
+# Community-based query
+mx graphrag query-communities --query "project planning" --limit 5
+
+# Explain specific memory
+mx graphrag explain --memory-id mem_abc123
+```
+
+**❌ Don't:**
+- Use overly broad queries
+- Expect instant results for complex queries
+- Ignore regular search capabilities
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue: "Authentication Error: Invalid or missing API key"**
+
+**Solution:**
+```bash
+# Check current auth status
+mx auth status
+
+# Login with API key
+mx auth login --interactive
+```
+
+**Issue: "Connection refused" or "Network error"**
+
+**Solution:**
+```bash
+# Check API URL configuration
+mx config get apiUrl
+
+# Set correct API URL
+mx config set apiUrl https://api.memnexus.io
+
+# Check system health
+mx system health
+```
+
+**Issue: "Validation error" when creating resources**
+
+**Solution:**
+- Use interactive mode for guided input: `mx memories create --interactive`
+- Check that JSON strings are properly formatted
+- Verify confidence scores are between 0 and 1
+- Ensure required fields are provided
+
+**Issue: "Rate limit exceeded"**
+
+**Solution:**
+- Wait before retrying (check error message for retry-after time)
+- Reduce request frequency
+- Use pagination with smaller page sizes
+- Contact API administrator for rate limit increase
+
+### Getting Help
+
+```bash
+# General help
+mx --help
+
+# Command-specific help
+mx memories --help
+mx facts create --help
+mx topics cluster --help
+
+# Check version
+mx --version
+
+# System status
+mx system health
+mx system status
+```
+
+---
+
+## Environment Variables Reference
+
+| Variable | Description | Default | Example |
+|----------|-------------|---------|---------|
+| `MX_API_URL` | MemNexus API base URL | `https://api.memnexus.io` | `https://api.memnexus.io` |
+| `MX_API_KEY` | API authentication key | - | `cmk_live_abc123.xyz789` |
+| `MX_OUTPUT_FORMAT` | Default output format | `table` | `json`, `table`, `yaml` |
+| `MX_DEFAULT_PAGE_SIZE` | Default pagination size | `20` | `50`, `100` |
+
+**Setting Environment Variables:**
+
+```bash
+# Linux/macOS
+export MX_API_URL="https://api.memnexus.io"
+export MX_API_KEY="cmk_live_abc123.xyz789"
+export MX_OUTPUT_FORMAT="json"
+
+# Windows (PowerShell)
+$env:MX_API_URL="https://api.memnexus.io"
+$env:MX_API_KEY="cmk_live_abc123.xyz789"
+$env:MX_OUTPUT_FORMAT="json"
+
+# Windows (CMD)
+set MX_API_URL=https://api.memnexus.io
+set MX_API_KEY=cmk_live_abc123.xyz789
+set MX_OUTPUT_FORMAT=json
+```
+
+---
+
+## Additional Resources
+
+- **README**: Quick start and installation guide
+- **GitHub Repository**: https://github.com/memnexus-ai/mx-cli
+- **API Documentation**: https://docs.memnexus.io
+- **Issue Tracker**: https://github.com/memnexus-ai/mx-cli/issues
+
+---
+
+*Last updated: 2024-11-14*
+