Skip to main content

CLI Commands

Complete reference for all mem8 CLI commands.

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:

  1. Check .mem8/ports.md first - This file contains the project's leased port range and specific assignments
  2. Read the Project Notes section - Contains project-specific port assignments for different services
  3. Use assigned ports - Always use ports from the leased range instead of defaults (3000, 8000, etc.)
  4. 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 logging
  • MEM8_CONFIG_DIR - Override config directory
  • MEM8_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 - Success
  • 1 - General error
  • 2 - Configuration error
  • 3 - Network error
  • 4 - Permission error

Next Steps