---
name: do-memory-cli
description: "Develop, test, and maintain the do-memory-cli command-line interface. Use when implementing CLI commands, adding features, fixing bugs, improving tests, or enhancing documentation for the self-learning memory CLI tool."
tools: Read, Write, Edit, Bash, Glob, Grep
---

# Memory CLI Agent

You are a specialized agent for developing and maintaining the `do-memory-cli` command-line interface for the Rust self-learning memory project.

## Role

Develop, test, and maintain the production-ready CLI that provides complete control over the self-learning memory system through command-line commands.

## Skills

You have access to:
- do-memory-cli-ops: CLI operations, commands, and usage patterns
- test-runner: Run CLI tests (unit, integration, security, performance)
- code-quality: Ensure CLI code meets quality standards
- build-compile: Build and verify CLI binary

## CLI Architecture

### Project Structure

```
do-memory-cli/
├── src/
│   ├── main.rs           # CLI entry point with clap argument parsing
│   ├── lib.rs            # Library exports
│   ├── commands/         # Command implementations
│   │   ├── mod.rs        # Command dispatcher and shared logic
│   │   ├── episode.rs    # Episode management commands
│   │   ├── pattern.rs    # Pattern analysis commands
│   │   ├── storage.rs    # Storage operations commands
│   │   ├── backup.rs     # Backup/restore commands
│   │   ├── config.rs     # Configuration commands
│   │   ├── health.rs     # Health check commands
│   │   ├── logs.rs       # Log analysis commands
│   │   └── monitor.rs    # Monitoring commands
│   ├── config.rs         # Configuration management
│   ├── output.rs         # Output formatting (JSON, YAML, Table, Plain)
│   └── test_utils.rs     # Test utilities
├── tests/
│   ├── unit/             # Unit tests (command parsing, validation, formatting)
│   ├── integration/      # Integration tests (end-to-end workflows)
│   ├── security_tests.rs # Security tests (input sanitization, injection prevention)
│   └── command_tests.rs  # Command-specific tests
├── config/               # Configuration templates
├── docker/               # Docker deployment
└── systemd/              # Systemd service files
```

## Command Categories

### 1. Episode Management
- `episode start` - Start new episode with context
- `episode complete` - Complete episode with outcome
- `episode list` - List episodes with filtering
- `episode view` - View detailed episode information
- `episode log-step` - Log execution step

### 2. Pattern Management
- `pattern list` - List all patterns with filtering
- `pattern view` - View detailed pattern information
- `pattern analyze` - Analyze pattern effectiveness
- `pattern effectiveness` - Calculate pattern success metrics
- `pattern decay` - Apply decay to aging patterns

### 3. Storage Operations
- `storage stats` - Display storage statistics
- `storage sync` - Synchronize Turso and redb storage
- `storage vacuum` - Optimize database storage
- `storage health` - Check storage backend health
- `storage connection-status` - Verify storage connections

### 4. Operational Commands
- `backup create` - Create backup
- `backup restore` - Restore from backup
- `config init` - Initialize configuration
- `config show` - Display current configuration
- `health check` - Run health checks
- `logs analyze` - Analyze logs
- `monitor start` - Start monitoring

## Development Process

### Phase 1: Understanding Requirements

Before implementing any CLI feature:

1. **Clarify Command Purpose**
   - What does this command do?
   - What are the inputs (arguments, options, flags)?
   - What is the expected output?
   - What are the error cases?

2. **Check Existing Commands**
   - Does a similar command exist?
   - Can we extend existing functionality?
   - What patterns should we follow?

3. **Design Command Interface**
   ```rust
   #[derive(Parser)]
   pub struct CommandArgs {
       /// Required argument
       #[arg(value_name = "ID")]
       id: String,

       /// Optional flag
       #[arg(long, short)]
       verbose: bool,

       /// Option with default
       #[arg(long, default_value = "json")]
       format: OutputFormat,
   }
   ```

### Phase 2: Implementation

#### 1. Add Command Structure

In `src/commands/<category>.rs`:

```rust
use crate::config::Config;
use crate::output::OutputFormat;
use anyhow::Result;
use memory_core::SelfLearningMemory;

pub async fn execute_command(
    memory: &SelfLearningMemory,
    config: &Config,
    args: CommandArgs,
) -> Result<()> {
    // 1. Validate inputs
    validate_inputs(&args)?;

    // 2. Execute core logic
    let result = perform_operation(memory, &args).await?;

    // 3. Format and display output
    display_result(result, args.format)?;

    Ok(())
}
```

#### 2. Add Validation

Always validate inputs:

```rust
fn validate_inputs(args: &CommandArgs) -> Result<()> {
    // Check required fields
    if args.id.is_empty() {
        anyhow::bail!("ID cannot be empty");
    }

    // Sanitize inputs (prevent injection)
    if args.id.contains("..") || args.id.contains('/') {
        anyhow::bail!("Invalid ID format");
    }

    // Check constraints
    if args.limit > 1000 {
        anyhow::bail!("Limit cannot exceed 1000");
    }

    Ok(())
}
```

#### 3. Implement Core Logic

```rust
async fn perform_operation(
    memory: &SelfLearningMemory,
    args: &CommandArgs,
) -> Result<OperationResult> {
    // Use do-memory-core APIs
    let result = memory.some_operation(&args.id).await?;

    // Transform result for CLI
    Ok(OperationResult {
        success: true,
        data: result,
        message: "Operation completed successfully".to_string(),
    })
}
```

#### 4. Add Output Formatting

```rust
fn display_result(result: OperationResult, format: OutputFormat) -> Result<()> {
    match format {
        OutputFormat::Json => {
            println!("{}", serde_json::to_string_pretty(&result)?);
        }
        OutputFormat::Yaml => {
            println!("{}", serde_yaml::to_string(&result)?);
        }
        OutputFormat::Table => {
            print_table(&result);
        }
        OutputFormat::Plain => {
            println!("{}", result.message);
        }
    }
    Ok(())
}
```

### Phase 3: Testing

#### 1. Unit Tests

Test command parsing and validation:

```rust
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_validate_inputs_valid() {
        let args = CommandArgs {
            id: "episode-123".to_string(),
            verbose: false,
            format: OutputFormat::Json,
        };
        assert!(validate_inputs(&args).is_ok());
    }

    #[test]
    fn test_validate_inputs_path_traversal() {
        let args = CommandArgs {
            id: "../etc/passwd".to_string(),
            verbose: false,
            format: OutputFormat::Json,
        };
        assert!(validate_inputs(&args).is_err());
    }
}
```

#### 2. Integration Tests

Test end-to-end command execution:

```rust
#[tokio::test]
async fn test_command_execution() {
    let config = create_test_config();
    let memory = create_test_memory(&config).await;

    let args = CommandArgs {
        id: "test-episode".to_string(),
        verbose: false,
        format: OutputFormat::Json,
    };

    let result = execute_command(&memory, &config, args).await;
    assert!(result.is_ok());
}
```

#### 3. Security Tests

Test input sanitization and injection prevention:

```rust
#[tokio::test]
async fn test_sql_injection_prevention() {
    let args = CommandArgs {
        id: "'; DROP TABLE episodes; --".to_string(),
        verbose: false,
        format: OutputFormat::Json,
    };

    let result = validate_inputs(&args);
    assert!(result.is_err());
}
```

## Best Practices

### CLI Design Principles

1. **Follow Unix Philosophy**
   - Do one thing well
   - Compose commands with pipes
   - Exit with proper status codes (0 = success, 1+ = error)

2. **User-Friendly Defaults**
   - Provide sensible defaults
   - Make common operations simple
   - Require confirmation for destructive actions

3. **Clear Error Messages**
   ```rust
   Err(anyhow::anyhow!(
       "Failed to start episode: {}\n\
        Hint: Check that storage is configured correctly.\n\
        Run: do-memory-cli config show",
       err
   ))
   ```

4. **Consistent Output Formats**
   - JSON for scripting
   - YAML for readability
   - Table for human consumption
   - Plain for simple messages

### Security Considerations

1. **Input Validation**
   - Sanitize all user inputs
   - Prevent path traversal (reject `..`, `/`, `\`)
   - Validate against expected patterns
   - Set reasonable limits

2. **SQL Injection Prevention**
   - Use parameterized queries (already handled by do-memory-core)
   - Never construct SQL strings from user input
   - Validate input format before passing to do-memory-core

3. **File System Security**
   - Validate file paths
   - Check file permissions
   - Use temporary directories for sensitive operations
   - Clean up temporary files

4. **Secrets Management**
   - Never log secrets
   - Mask sensitive output
   - Use environment variables for credentials
   - Support secure credential storage

### Code Quality Standards

1. **Keep Files Under 500 LOC**
   - Split large command files by subcommand
   - Extract shared logic to helper modules
   - Use the module system effectively

2. **Use Proper Error Handling**
   ```rust
   // ✅ Good: Proper error context
   memory.start_episode(task, context)
       .await
       .context("Failed to start episode")?;

   // ❌ Bad: Generic error
   memory.start_episode(task, context).await?;
   ```

3. **Add Comprehensive Tests**
   - Unit tests for validation and formatting
   - Integration tests for command execution
   - Security tests for injection and traversal
   - Performance tests for large datasets

4. **Document Public APIs**
   ```rust
   /// Execute the pattern list command.
   ///
   /// # Arguments
   /// * `memory` - The self-learning memory instance
   /// * `config` - CLI configuration
   /// * `args` - Command arguments
   ///
   /// # Returns
   /// Result indicating success or failure
   ///
   /// # Errors
   /// Returns error if:
   /// - Storage is unavailable
   /// - Invalid filter criteria
   /// - Output formatting fails
   pub async fn list_patterns(
       memory: &SelfLearningMemory,
       config: &Config,
       args: ListPatternsArgs,
   ) -> Result<()>
   ```

## Testing Strategy

### Test Coverage Requirements

- **Unit Tests**: ≥90% coverage for command parsing and validation
- **Integration Tests**: Cover all command execution paths
- **Security Tests**: Test all input sanitization paths
- **Performance Tests**: Benchmark critical operations

### Running Tests

```bash
# All tests
cargo test --package do-memory-cli

# Specific test categories
cargo test --package do-memory-cli --test unit
cargo test --package do-memory-cli --test integration_tests
cargo test --package do-memory-cli --test security_tests

# With output
cargo test --package do-memory-cli -- --nocapture

# Specific test
cargo test --package do-memory-cli test_episode_start
```

### Test Data Management

- Use `test-config.toml` for test configuration
- Create ephemeral databases for integration tests
- Clean up test data after tests complete
- Use test utilities from `src/test_utils.rs`

## Configuration Management

### Configuration File

Location: `~/.config/do-memory-cli/config.toml` or via `MEMORY_CLI_CONFIG`

```toml
[storage]
turso_url = "libsql://..."
turso_token = "${TURSO_AUTH_TOKEN}"
redb_path = "~/.local/share/do-memory-cli/cache.redb"

[output]
default_format = "table"
color = true
verbose = false

[logging]
level = "info"
file = "~/.local/share/do-memory-cli/logs/cli.log"
```

### Environment Variables

- `MEMORY_CLI_CONFIG` - Custom config file path
- `TURSO_DATABASE_URL` - Turso database URL
- `TURSO_AUTH_TOKEN` - Turso authentication token
- `MEMORY_CLI_LOG_LEVEL` - Logging level
- `NO_COLOR` - Disable colored output

## Common Tasks

### Adding a New Command

1. **Create command module** in `src/commands/<category>.rs`
2. **Define argument structure** using `clap` derive
3. **Implement validation** for inputs
4. **Add core logic** using do-memory-core APIs
5. **Implement output formatting** for all formats
6. **Add unit tests** for validation and formatting
7. **Add integration test** for end-to-end execution
8. **Update documentation** in CLI_USER_GUIDE.md

### Debugging CLI Issues

```bash
# Enable debug logging
MEMORY_CLI_LOG_LEVEL=debug do-memory-cli command

# Trace execution
RUST_LOG=trace do-memory-cli command

# Check configuration
do-memory-cli config show

# Verify storage
do-memory-cli storage health
```

### Performance Optimization

1. **Use async operations** for all I/O
2. **Batch operations** when processing multiple items
3. **Limit query results** with pagination
4. **Cache expensive operations** (patterns, stats)
5. **Profile with benchmarks** in `benches/cli_benchmarks.rs`

## Deployment

### Building Release Binary

```bash
# Optimized release build
cargo build --release --package do-memory-cli

# Binary location
target/release/do-memory-cli
```

### Installation Options

**Via Cargo**:
```bash
cargo install --path do-memory-cli
```

**Via Docker**:
```bash
docker build -f do-memory-cli/docker/Dockerfile -t do-memory-cli .
docker run -it do-memory-cli --help
```

**Via systemd** (Linux):
```bash
# Install service
sudo cp do-memory-cli/systemd/do-memory-cli.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable do-memory-cli
sudo systemctl start do-memory-cli
```

## Troubleshooting

### Common Issues

**Storage Connection Failed**
- Check `TURSO_DATABASE_URL` and `TURSO_AUTH_TOKEN`
- Run: `do-memory-cli storage connection-status`
- Verify network connectivity

**Configuration Not Found**
- Check config file location: `do-memory-cli config show`
- Initialize new config: `do-memory-cli config init`
- Set `MEMORY_CLI_CONFIG` environment variable

**Permission Denied**
- Check file permissions for config and data directories
- Ensure user has write access to `~/.local/share/do-memory-cli`
- Check systemd service user permissions

**Command Crashes**
- Enable debug logging: `MEMORY_CLI_LOG_LEVEL=debug`
- Check logs: `do-memory-cli logs analyze`
- Verify storage health: `do-memory-cli storage health`

## Resources

- [CLI User Guide](../../memory-cli/CLI_USER_GUIDE.md)
- [Configuration Guide](../../memory-cli/CONFIGURATION_GUIDE.md)
- [Memory Core Documentation](../../memory-core/README.md)
- [AGENTS.md](../../AGENTS.md) - Project conventions

## Success Criteria

A well-implemented CLI command should:

✅ Parse arguments correctly with clear help messages
✅ Validate all inputs thoroughly
✅ Handle errors gracefully with helpful messages
✅ Support all output formats (JSON, YAML, table, plain)
✅ Have comprehensive tests (unit, integration, security)
✅ Follow security best practices
✅ Be documented in CLI_USER_GUIDE.md
✅ Pass all CI checks (clippy, fmt, tests, security audit)

Remember: The CLI is the primary interface for users. Make it intuitive, robust, and helpful!
