CLI Commands
Complete reference for all mem8 CLI commands.
Search
mem8 search
Search through your thoughts and documentation.
# Basic search
mem8 search "authentication"
# With filters
mem8 search "OAuth" --limit 5 --path memory/research
Options:
--limit
- Maximum number of results (default: 10)--path
- Search only in specific directory--category
- Filter by category:plans
,research
,decisions
,shared
--method
- Search method:fulltext
,semantic
Status
mem8 status
Check workspace health and configuration.
# Quick status
mem8 status
# Detailed view
mem8 status --detailed
Shows:
- ✅ Installed components (.claude, thoughts)
- 📊 Thought statistics
- 🔗 Git repository status
- ⚠️ Issues and warnings
Sync
mem8 sync
Synchronize thoughts with remote repository.
# Two-way sync
mem8 sync
# Push only
mem8 sync --direction push
# Pull only
mem8 sync --direction pull
# Preview changes
mem8 sync --dry-run
Options:
--direction
- Sync direction:push
,pull
,both
--dry-run
- Show what would happen without making changes--force
- Override local changes
Doctor
mem8 doctor
Run diagnostics and fix common issues.
# Check for issues
mem8 doctor
# Auto-fix problems
mem8 doctor --fix
Checks:
- Directory structure
.mem8/toolbelt.json
manifest (core tooling availability)- Git configuration
- Template integrity
- Dependencies
When a project template ships a .mem8/toolbelt.json
manifest, mem8 doctor
reads it to verify that required CLI tools are on your PATH
for the current operating system. Missing core tools are flagged as issues, while recommended tools appear as actionable suggestions.
Tools
mem8 tools
List toolbelt CLI tools and OS details for AI system prompts.
# List tools
mem8 tools
# Save toolbelt to .mem8/tools.md
mem8 tools --save
Options:
--save
- Save toolbelt to.mem8/tools.md
--verbose
- Enable verbose output
Ports
mem8 ports
Manage project port assignments to prevent conflicts across projects.
# Show current project's port assignments
mem8 ports --show
# Lease new ports for this project
mem8 ports --lease
# Release this project's port lease
mem8 ports --release
# List all port leases across all projects
mem8 ports --list-all
# Check for port conflicts
mem8 ports --check-conflicts
# Kill process using specified port
mem8 ports --kill 8080
Options:
--lease
- Lease new ports for this project--start
- Starting port number (auto-assign if not specified)--count
- Number of ports to lease--release
- Release this project's port lease--list-all
- List all port leases across all projects--check-conflicts
- Check for port conflicts--kill
- Kill process using specified port--force
- Force kill port outside project range--show
- Show current project's port assignments--verbose
- Enable verbose output
For AI Agents
When starting any service, AI agents should:
- Check
.mem8/ports.md
first - This file contains the project's leased port range and specific assignments - Read the Project Notes section - Contains project-specific port assignments for different services
- Use assigned ports - Always use ports from the leased range instead of defaults (3000, 8000, etc.)
- Update Project Notes - When adding new services, document the port assignment in the Project Notes section
Example workflow:
# Agent checks ports.md and sees Docusaurus should use port 20000
cd documentation && npm start -- --port 20000
# Agent sees FastAPI backend should use port 20001
uvicorn main:app --port 20001 --reload
The Project Notes section in .mem8/ports.md
is preserved when regenerating, making it the single source of truth for port assignments in your project.
Version
mem8 version
Show version information.
mem8 version
Help
mem8 --help
Show help for any command.
# General help
mem8 --help
# Command-specific help
mem8 search --help
mem8 status --help
Global Options
All commands support:
--verbose
- Show detailed output--quiet
- Minimal output--help
- Show command help--version
- Show version
Examples
Daily Workflow
# Morning: Pull team updates
mem8 sync --direction pull
# Check workspace
mem8 status
# Search for relevant info
mem8 search "authentication" --limit 5
# End of day: Push your changes
mem8 sync --direction push
Project Setup
# New project
cd my-project
# Create memory directory
mkdir -p memory/{research,plans,decisions,prs}
# Verify setup
mem8 status --detailed
mem8 doctor
Troubleshooting
# Run diagnostics
mem8 doctor
# Check what's wrong
mem8 status --detailed
# Search for solutions
mem8 search "error message"
Environment Variables
MEM8_DEBUG
- Enable debug loggingMEM8_CONFIG_DIR
- Override config directoryMEM8_DATA_DIR
- Override data directory
Example:
export MEM8_DEBUG=1
mem8 status
Configuration File
mem8 looks for configuration in:
~/.config/mem8/config.yaml
(global)
Example config:
sync:
auto: true
direction: both
search:
default_limit: 10
Exit Codes
0
- Success1
- General error2
- Configuration error3
- Network error4
- Permission error
Next Steps
- Workflows - Common development patterns
- Getting Started - Your first steps
- Troubleshooting - Solve common issues