# MUMLA CLI User Guide

**Status**: Production Ready
**Last Updated**: December 2025

---

## Table of Contents

1. [Introduction](#introduction)
2. [Installation](#installation)
3. [Quick Start](#quick-start)
4. [Command Reference](#command-reference)
5. [Workflows](#workflows)
6. [Configuration](#configuration)
7. [Troubleshooting](#troubleshooting)
8. [Examples](#examples)

---

## Introduction

MUMLA CLI provides a command-line interface for interacting with MUMLA (Moorcheh Universal Memory Layer for Agentic AI). It enables you to:

- Create and manage AI agents
- Store and retrieve agent memories
- Perform semantic search across memories
- Ask questions using RAG (Retrieval-Augmented Generation)
- Manage agent sessions

The CLI uses the MUMLA API with session-based authentication and provides a beautiful terminal UI powered by Rich.

---

## Installation

### Prerequisites

- Python 3.10 or higher
- MUMLA server running (default: http://localhost:8000)
- Moorcheh API key

### Install Dependencies

```bash
cd mumla
pip install -e .
```

This installs:
- typer (CLI framework)
- rich (terminal UI)
- httpx (HTTP client)
- cryptography (secure key storage)
- pyyaml (configuration)
- All other MUMLA dependencies

### Verify Installation

```bash
python -m cli.main --help
```

You should see the main help screen with all available commands.

---

## Quick Start

### 1. Initialize the CLI

```bash
mumla
```

This will:
- Prompt for your Moorcheh API key
- Securely encrypt and store the key
- Test connection to the MUMLA server
- Create configuration file at `~/.mumla/config.yaml`

**Interactive Example:**
```
╭──────────────────────────────────────────╮
│ MUMLA CLI Initialization                 │
│ Setting up your MUMLA configuration...   │
╰──────────────────────────────────────────╯

Enter your Moorcheh API key: ********

Testing connection to MUMLA server...
✓ Connection successful!
Server version: 0.1.0

Configuration saved to: /home/user/.mumla/config.yaml

Next steps:
  1. Create an agent: mumla agent create my-agent
  2. Activate the agent: mumla agent activate my-agent
  3. Start storing memories: mumla remember 'your memory here'
```

### 2. Create an Agent

```bash
mumla agent create my-agent --pattern tool
```

### 3. Activate the Agent

```bash
mumla agent activate my-agent
```

This starts a session (default: 4 hours).

### 4. Store a Memory

```bash
mumla remember "Implemented authentication using JWT tokens" \
  --type decision \
  --tags "authentication,security" \
  --confidence 0.9
```

### 5. Search Memories

```bash
mumla recall "authentication" --limit 5
```

### 6. Ask a Question

```bash
mumla answer "How did we implement authentication?"
```

---

## Command Reference

### Global Commands

#### Use base command for Initialization
 
 ```bash
 mumla [OPTIONS]
 ```
 
 **Options:**
 - `--api-key TEXT` - Moorcheh API key (will prompt if not provided)
 - `--server-url TEXT` - MUMLA server URL (default: localhost)
 - `--server-port INT` - MUMLA server port (default: 8000)
 
 **Example:**
 ```bash
 mumla
 ```

---

### Agent Commands

#### `agent create` - Create New Agent

```bash
mumla agent create AGENT_ID [OPTIONS]
```

**Arguments:**
- `AGENT_ID` - Unique identifier for the agent

**Options:**
- `--pattern TEXT` - Agent pattern: tool, chat, research, or custom (default: tool)
- `--description TEXT` - Optional description

**Examples:**
```bash
# Create a tool-using agent
python -m cli.main agent create code-assistant --pattern tool

# Create a research agent with description
mumla agent create researcher \
  --pattern research \
  --description "Agent for literature review and research"
```

#### `agent list` - List All Agents

```bash
mumla agent list
```

**Output:**
```
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Agent ID        ┃ Pattern ┃ Description             ┃ Status   ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ code-assistant  │ tool    │ Code assistant          │ 🟢 Active│
│ researcher      │ research│ Literature review       │          │
└─────────────────┴─────────┴────────────────────────┴──────────┘
```

#### `agent activate` - Activate Agent

```bash
mumla agent activate AGENT_ID [OPTIONS]
```

**Arguments:**
- `AGENT_ID` - ID of agent to activate

**Options:**
- `--duration-hours INT` - Session duration in hours (default: 4)

**Examples:**
```bash
# Activate with default 4-hour session
python -m cli.main agent activate code-assistant

# Activate with 8-hour session
mumla agent activate code-assistant --duration-hours 8
```

#### `agent deactivate` - Deactivate Current Agent

```bash
mumla agent deactivate
```

Ends the current agent session.

---

### Memory Commands

#### `remember` - Store Memory

```bash
mumla remember CONTENT [OPTIONS]
```

**Arguments:**
- `CONTENT` - Memory content to store

**Options:**
- `--type, -t TEXT` - Memory type: fact, decision, instruction, commitment, event (default: fact)
- `--title TEXT` - Memory title (defaults to truncated content)
- `--confidence, -c FLOAT` - Confidence score 0.0-1.0 (default: 0.8)
- `--tags TEXT` - Comma-separated tags

**Examples:**
```bash
# Store a simple fact
python -m cli.main remember "User prefers dark mode"

# Store a decision with metadata
python -m cli.main remember "Switched to PostgreSQL for better JSON support" \
  --type decision \
  --title "Database Migration Decision" \
  --confidence 0.95 \
  --tags "database,architecture,postgresql"

# Store a commitment
python -m cli.main remember "Must complete security audit by end of month" \
  --type commitment \
  --tags "security,deadline"
```

**Output:**
```
✓ Memory stored successfully!
Memory ID: mem_abc123xyz
Type: decision | Confidence: 0.95
```

#### `recall` - Search Memories

```bash
mumla recall QUERY [OPTIONS]
```

**Arguments:**
- `QUERY` - Search query (semantic search)

**Options:**
- `--limit, -n INT` - Maximum results (default: 10)
- `--type, -t TEXT` - Filter by memory type
- `--min-confidence FLOAT` - Minimum confidence score
- `--tags TEXT` - Filter by tags (comma-separated)

**Examples:**
```bash
# Basic search
python -m cli.main recall "authentication"

# Search with filters
python -m cli.main recall "security" \
  --type decision \
  --min-confidence 0.8 \
  --limit 5

# Search by tags
python -m cli.main recall "architecture" \
  --tags "database,backend" \
  --limit 20
```

**Output:**
```
Found 3 memories:

╭─ Memory 1 ──────────────────────────────────────────╮
│ Database Migration Decision                         │
│                                                      │
│ Switched to PostgreSQL for better JSON support      │
│ and advanced indexing capabilities...               │
│                                                      │
│ Type: decision | Confidence: 0.95 | Score: 0.927    │
│ Created: 2025-12-27T14:30:00Z                       │
╰─────────────────────────────────────────────────────╯

╭─ Memory 2 ──────────────────────────────────────────╮
│ ...                                                  │
╰─────────────────────────────────────────────────────╯
```

#### `answer` - RAG Question Answering

```bash
mumla answer QUESTION [OPTIONS]
```

**Arguments:**
- `QUESTION` - Question to ask

**Options:**
- `--limit, -n INT` - Number of context memories to use (default: 5)

**Examples:**
```bash
# Ask about project decisions
mumla answer "Why did we choose PostgreSQL?"

# Ask with more context
mumla answer "What security measures have we implemented?" --limit 10
```

**Output:**
```
╭─ RAG Response ──────────────────────────────────────╮
│ Question: Why did we choose PostgreSQL?             │
│                                                      │
│ Answer:                                              │
│ We chose PostgreSQL because it provides better      │
│ JSON support and advanced indexing capabilities     │
│ compared to our previous database solution...       │
╰─────────────────────────────────────────────────────╯

Used 3 memories as context:
  1. Database Migration Decision (score: 0.927)
  2. Backend Architecture Review (score: 0.854)
  3. Performance Optimization Notes (score: 0.781)
```

---

### Session Commands

#### `session info` - Show Session Info

```bash
mumla session info
```

**Output:**
```
┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Property       ┃ Value                          ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Agent ID       │ code-assistant                 │
│ Session Token  │ eyJhbGciOiJIUzI1NiI...         │
└────────────────┴────────────────────────────────┘
```

#### `session extend` - Extend Session

```bash
mumla session extend [OPTIONS]
```

**Options:**
- `--hours, -h INT` - Hours to extend (default: 4)

**Example:**
```bash
python -m cli.main session extend --hours 6
```

---

### Configuration Commands

#### `config show` - Display Configuration

```bash
mumla config show
```

**Output:**
```
┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Setting          ┃ Value                        ┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Config File      │ /home/user/.mumla/config.yaml│
│ Server URL       │ localhost:8000               │
│ API Key          │ ***configured***             │
│ Active Agent     │ code-assistant               │
│ Session Active   │ yes                          │
│ Interactive Mode │ True                         │
│ Smart Parse      │ True                         │
└──────────────────┴──────────────────────────────┘
```

---

## Workflows

### Daily Development Workflow

```bash
# Morning: Activate your agent
mumla agent activate dev-assistant

# Throughout the day: Store important decisions and facts
mumla remember "Fixed authentication bug in login endpoint" \
  --type decision \
  --tags "bugfix,authentication"

mumla remember "User requested dark mode feature" \
  --type instruction \
  --tags "feature-request,ui"

# Review day's work
mumla recall "today" --limit 20

# End of day: Deactivate
mumla agent deactivate
```

### Project Knowledge Base

```bash
# Store architecture decisions
mumla remember "Using microservices architecture with API gateway" \
  --type decision \
  --title "Architecture Pattern" \
  --tags "architecture,microservices" \
  --confidence 1.0

# Store team guidelines
mumla remember "All PRs require 2 approvals before merge" \
  --type instruction \
  --tags "process,code-review"

# Query the knowledge base
mumla answer "What are our code review requirements?"
```

### Research Assistant

```bash
# Create research agent
mumla agent create research-assistant --pattern research

# Activate
mumla agent activate research-assistant

# Store research findings
mumla remember "Paper XYZ shows 30% improvement in model accuracy" \
  --type fact \
  --tags "research,ml,paper-xyz" \
  --confidence 0.9

# Search research by topic
mumla recall "model accuracy improvements" --limit 10

# Synthesize findings
mumla answer "What papers discuss model accuracy improvements?"
```

---

## Configuration

### Configuration File Location

- **Linux/Mac**: `~/.mumla/config.yaml`
- **Windows**: `C:\Users\<username>\.mumla\config.yaml`

### Configuration Structure

```yaml
version: "2.0"

server:
  url: "localhost"
  port: 8000
  auto_start: false

moorcheh:
  api_key_encrypted: "gAAAAABf..."  # Fernet encrypted

session:
  default_duration_hours: 4
  auto_extend: true

cli:
  interactive_mode: true
  smart_parse: true
  color_output: true
  compact_view: false

active_agent_id: "code-assistant"
active_session_token: "eyJhbGciOiJIUzI1NiI..."
```

### Security

- API keys are encrypted using Fernet (symmetric encryption)
- Encryption key stored in `~/.mumla/.key` with 0600 permissions
- Session tokens stored in config but require valid API key
- Never commit config files to version control

---

## Troubleshooting

### "MUMLA not initialized" Error

**Problem**: Running commands before initialization

**Solution**:
```bash
mumla init
```

### "No active agent" Error

**Problem**: Trying to use memory commands without active session

**Solution**:
```bash
# List available agents
mumla agent list

# Activate one
mumla agent activate <agent-id>
```

### Connection Failed

**Problem**: Cannot reach MUMLA server

**Check**:
1. Is the server running?
   ```bash
   curl http://localhost:8000/health
   ```

2. Is the port correct?
   ```bash
   mumla config show
   ```

3. Reinitialize with correct settings:
   ```bash
   mumla init --server-url localhost --server-port 8000
   ```

### API Key Issues

**Problem**: Invalid or expired API key

**Solution**:
```bash
# Get new API key from Moorcheh dashboard
# Reinitialize
python -m cli.main init --api-key <new-key>
```

### Session Expired

**Problem**: Session token expired

**Solution**:
```bash
# Reactivate the agent
mumla agent activate <agent-id>

# Or extend existing session (if still valid)
mumla session extend --hours 4
```

---

## Examples

### Complete Project Setup

```bash
# 1. Initialize
mumla

# 2. Create project-specific agent
mumla agent create project-alpha --pattern tool \
  --description "Agent for Project Alpha development"

# 3. Activate for long session
mumla agent activate project-alpha --duration-hours 8

# 4. Store initial context
mumla remember "Project uses Python 3.11, FastAPI, PostgreSQL" \
  --type fact \
  --title "Tech Stack" \
  --tags "project-setup,stack"

mumla remember "API versioning using /api/v2/ prefix" \
  --type decision \
  --tags "api,architecture"

# 5. Work session...
mumla remember "Implemented user authentication with JWT" \
  --type decision \
  --tags "auth,security"

# 6. Review progress
mumla recall "authentication security" --limit 5

# 7. Get context for next task
mumla answer "What have we implemented for security so far?"
```

### Multi-Agent Workflow

```bash
# Development agent
mumla agent create dev --pattern tool
mumla agent activate dev
mumla remember "Implemented feature X" --type fact

# Switch to research agent
mumla agent deactivate
mumla agent create research --pattern research
mumla agent activate research
mumla remember "Found paper on optimization technique Y" --type fact

# Switch back
mumla agent deactivate
mumla agent activate dev
```

### Bulk Knowledge Import

```bash
#!/bin/bash
# import-knowledge.sh

AGENT_ID="knowledge-base"

# Activate agent
mumla agent activate $AGENT_ID

# Import facts from file
while IFS='|' read -r title content tags; do
  mumla remember "$content" \
    --title "$title" \
    --type fact \
    --tags "$tags" \
    --confidence 1.0
done < knowledge.txt

echo "Import complete!"
```

---

## Advanced Usage

### Scripting with MUMLA CLI

```python
#!/usr/bin/env python3
import subprocess
import json

def mumla_cli(*args):
    """Helper to call MUMLA CLI"""
    cmd = ["mumla"] + list(args)
    result = subprocess.run(cmd, capture_output=True, text=True)
    return result.stdout

# Store multiple memories
memories = [
    ("Decision A", "fact", "tag1,tag2"),
    ("Decision B", "decision", "tag2,tag3"),
]

for title, mem_type, tags in memories:
    mumla_cli("remember", title, "--type", mem_type, "--tags", tags)

# Search and process
results = mumla_cli("recall", "decision", "--limit", 10)
print(results)
```

---

## Next Steps

1. **Integration**: Use MUMLA CLI in your development workflow
2. **Automation**: Create scripts for common tasks
3. **Team Adoption**: Share configuration patterns with team
4. **Monitoring**: Track memory growth and query patterns

For more information:
- [API Documentation](./API_REFERENCE.md)
- [Agent Patterns](./AGENT_RUNTIME_GUIDE.md)
- [Memory Best Practices](./AGENT_MEMORY_BEST_PRACTICES.md)

---

**Last Updated**: December 2025
