@memnexus-ai/cli 0.1.0

package/README.md

@@ -0,0 +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)