This PR implements a Command-Line Interface (CLI) tool for PowerMem, enabling developers and system administrators to interact with PowerMem directly from the command line without writing Python scripts.

close #136

Solution Description

Features Implemented

1. Memory Operations (pmem add/search/get/update/delete/list/delete-all)

• Add new memories with user/agent/run ID support
• Search memories with filters and similarity threshold
• Get, update, and delete individual memories
• List all memories with pagination and sorting
• Batch delete with safety confirmation

2. Configuration Management (pmem config show/validate/test)

• Display current configuration (with secret masking)
• Validate configuration files with strict mode
• Test connectivity to database, LLM, and embedder

3. Statistics (pmem stats)

• View memory statistics filtered by user/agent ID
• Support detailed statistics with --detailed flag

4. Management Commands (pmem manage backup/restore/cleanup/migrate)

• Export memories to JSON backup files
• Restore memories from backup with dry-run support
• Clean up forgotten memories based on retention scores
• Migrate data between stores

5. Interactive Mode (pmem interactive or pmem shell)

• REPL-like experience for quick operations
• Session-level default user/agent ID settings
• Built-in help and command history

Technical Implementation

• CLI Framework: Uses click (existing dependency)
• Output Formats: JSON (--json), Table (default), Plain text
• Configuration: Reuses existing .env and auto_config() system
• Shell Completion: Supports bash, zsh, fish, and PowerShell (--install-completion)
• Entry Points: pmem and powermem-cli commands

File Structure

src/powermem/cli/
├── init.py # CLI package entry
├── main.py # Main command group + completion
├── commands/
│ ├── memory.py # Memory operations
│ ├── config.py # Configuration commands
│ ├── stats.py # Statistics command
│ ├── manage.py # Management commands
│ └── interactive.py # Interactive mode
└── utils/
└── output.py # Output formatting utilities

Usage Examples

Memory operations

pmem add "User prefers dark mode" --user-id user123
pmem search "user preferences" --user-id user123 --json
pmem list --user-id user123 --limit 50

Configuration

pmem config show
pmem config validate --strict
pmem config test --verbose

Statistics

pmem stats --user-id user123

Management

pmem manage backup --output backup.json
pmem manage restore --input backup.json --dry-run
pmem manage cleanup --threshold 0.1 --dry-run

Interactive mode

pmem interactive

Shell completion

pmem --install-completion bash