mem8 2.18.0

Memory management CLI for team collaboration with shared thoughts

mem8 - Claude Code Workspace Manager

A streamlined CLI tool for managing Claude Code customizations and documentation workflows. Create standardized project templates, manage memory/research documents, and enhance your Claude Code development experience.

🎯 Overview

mem8 is designed to work seamlessly with Claude Code, providing:

• 💻 Rich CLI Interface - Manage Claude Code customizations and project templates
• 📝 Memory Management - Organize research, plans, and documentation in markdown
• 🎨 Dashboard - Optional web interface to browse your workspace and memory
• 🏗️ Template System - Cookiecutter templates for Claude Code configurations

✨ Core Features

💻 CLI Commands

mem8 init --template claude-config   # Initialize Claude Code workspace
mem8 status                          # Check workspace health
mem8 doctor                          # Diagnose issues and check CLI toolbelt
mem8 doctor --fix                    # Auto-fix missing tools (where possible)
mem8 doctor --json                   # Machine-readable output for agents
mem8 tools                           # List toolbelt CLI tools and versions
mem8 tools --save                    # Save toolbelt to .mem8/tools.md
mem8 ports --lease                   # Lease port range for project
mem8 ports                           # Show current project's port assignments
mem8 ports --kill <port>             # Kill process on port (safe mode)
mem8 search "query"                  # Search across all memory
mem8 serve                           # Start the API server (port 8000)

📁 Template System

• claude-dot-md-template - Generate .claude/[agents,commands] configurations
• shared-memory-template - Create structured memory repositories
• Cookiecutter integration - Flexible, customizable project generation

🔍 Memory Organization

memory/
├── shared/
│   ├── research/      # Research documents
│   ├── plans/         # Implementation plans  
│   ├── prs/          # PR descriptions
│   └── decisions/     # Technical decisions
└── {project}/         # Project-specific memory

🚀 Quick Start

1. Install mem8

# Install with uv (recommended)
uv tool install mem8

# Or install from source
git clone https://github.com/killerapp/mem8.git
cd mem8
uv tool install --editable .

2. Initialize Your Workspace

# Create Claude Code configuration
mem8 init --template claude-config

# Create memory repository
mem8 init --template memory-repo

# Check everything is working
mem8 status

3. Optional: Start the Web Interface

For CLI-only usage, skip this step. The web interface is optional and provides a browser-based viewer.

# Option A: Frontend only (simple file viewer)
cd frontend && npm install && npm run dev
# Access at http://localhost:22211

# Option B: Full stack with backend (for teams/auth features)
docker-compose --env-file .env.dev up -d
# Frontend at http://localhost:22211
# Backend API at http://localhost:8000
# API Docs at http://localhost:8000/docs

# Option C: Hybrid (backend in Docker, frontend native)
docker-compose --env-file .env.dev up -d backend db
cd frontend && npm install && npm run dev
# Best for frontend development

Note: The mem8 serve command requires Docker for the database. See DOCKER.md for details.

🔧 CLI Toolbelt Management

mem8 includes a CLI toolbelt verification system to ensure you have all necessary tools for AI-assisted development workflows.

Quick Check

# Check for missing tools
mem8 doctor

# Auto-install missing tools (where supported)
mem8 doctor --fix

# JSON output for agents/CI
mem8 doctor --json

Verified Tools

The toolbelt checks for essential CLI tools that enhance AI workflows:

Required Tools:

• ripgrep (rg) - Fast recursive search, better than grep
• fd (fd) - Fast file finder, better than find
• jq - JSON processor for parsing API responses
• gh - GitHub CLI for PR/issue management
• git - Version control system

Optional Tools:

• bat - Syntax-highlighted file viewer
• delta - Beautiful git diff viewer
• yq - YAML/XML processor
• fzf - Fuzzy finder for interactive selection
• sd - Simpler sed alternative for text replacement
• ast-grep - AST-based code search and refactoring

Version Requirements

Tools with version requirements are automatically checked:

$ mem8 doctor
⚠️  Missing 1 required CLI tools
  • gh (gh) (requires >=2.60) - GitHub CLI
    Install: winget install GitHub.cli
    Current: 2.53.0

Platform Support

Install commands are automatically selected for your platform:

• Windows - Uses winget package manager
• macOS - Uses brew (Homebrew)
• Linux - Uses apt or distro-specific managers

CI Integration

The --json flag and exit codes make it CI-friendly:

mem8 doctor --json > toolbelt-status.json
# Exit code 0 if all tools present, 1 if any missing

External Template Sources

Doctor can use custom toolbelt definitions from external template sources:

Priority Order:

1. CLI flag: --template-source
2. Project config: .mem8/config.yaml
3. User config: ~/.config/mem8/config.yaml
4. Builtin templates (default)

Project-Level Configuration (.mem8/config.yaml):

templates:
  # Dedicated template repo (root-level)
  default_source: "my-org/templates"

  # Fork of killerapp/mem8-templates
  default_source: "acme-corp/mem8-templates"

  # Monorepo with templates in subdirectory
  default_source: "my-org/monorepo#subdir=mem8/templates"

  # Specific version/tag
  default_source: "my-org/templates@v1.0.0"

  # Local development path
  default_source: "/path/to/templates"

User-Level Configuration (~/.config/mem8/config.yaml):

# Set default for all projects
mem8 templates set-default "org/repo"

# Or edit manually at ~/.config/mem8/config.yaml

CLI Override:

# Dedicated template repo (cleanest for organizations)
mem8 doctor --template-source "acme-corp/mem8-templates"

# Fork of official templates with customizations
mem8 doctor --template-source "my-org/mem8-templates"

# Monorepo with templates in subdirectory
mem8 doctor --template-source "my-org/monorepo#subdir=tools/templates"

# Use specific version/branch
mem8 doctor --template-source "my-org/templates@v2.0.0"

# Local development version
mem8 doctor --template-source "/path/to/local/templates"

Template Repo Patterns:

1. Dedicated Repo (Recommended for Organizations)

   • Fork killerapp/mem8-templates → acme-corp/mem8-templates
   • Customize toolbelt for your org's standards
   • Reference directly: acme-corp/mem8-templates
   • No #subdir= needed - manifest at root

2. Monorepo with Templates

   • Keep templates alongside code
   • Use #subdir=path/to/templates
   • Example: my-org/platform#subdir=config/mem8-templates

3. Local Development

   • Test changes before pushing
   • Use absolute or relative paths
   • Example: --template-source ./my-templates

Custom Toolbelts

Projects can define custom tool requirements in manifest.yaml:

toolbelt:
  required:
    - name: "custom-tool"
      command: "tool"
      description: "Custom build tool"
      version: ">=1.0"
      install:
        windows: "winget install tool"
        macos: "brew install tool"
        linux: "apt install tool"

🔌 Port Management

mem8 includes a global port leasing system to prevent port conflicts when AI agents create multiple projects on the same machine.

Quick Start

# Lease port range for current project
mem8 ports --lease

# View assigned ports
mem8 ports

# Kill process on a port (safe - only kills ports in your range)
mem8 ports --kill 20000

# List all port leases across all projects
mem8 ports --list-all

# Release ports when done
mem8 ports --release

Key Features

Global Registry: ~/.mem8/port_leases.yaml tracks all port leases across projects

• Prevents Next.js/React dev servers from conflicting (3000, 3001...)
• AI agents reference .mem8/ports.md for assigned port ranges
• Cross-platform port killing with psutil (no npx kill-port needed)

Project-Specific Config: .mem8/ports.md documents port assignments

• Simple range-based system (e.g., 20000-20004)
• AI agents choose any port within the range
• Instructions for Next.js, FastAPI, Docker, etc.

Safe Port Killing:

• By default, only kills ports within project's leased range
• Use --force to override safety check
• Cross-platform support (Windows, Mac, Linux)

Example Workflow

# Project A
cd ~/projects/nextjs-app
mem8 ports --lease               # Gets 20000-20004
PORT=20000 npm run dev          # Uses assigned port

# Project B
cd ~/projects/api-server
mem8 ports --lease               # Gets 20005-20009
uvicorn main:app --port 20005   # No conflicts!

Configuration Files

.mem8/ports.md - Project-specific port documentation

• Auto-generated with port range and usage examples
• Editable markdown section preserved on regeneration
• AI agents read this for port assignments

~/.mem8/port_leases.yaml - Global port registry

leases:
  /path/to/project-a:
    project_name: nextjs-app
    start_port: 20000
    port_count: 5
    leased_at: '2025-10-07 01:28:43'
last_updated: '2025-10-07 01:28:43'

.mem8/config.yaml - Project configuration

templates:
  default_source: "killerapp/mem8-templates"

🔄 Development Workflow

mem8 provides a structured inner loop for effective development:

The Research → Plan → Implement → Commit Cycle

1. Research (/research_codebase) - Understand existing patterns and architecture

   • Uses parallel sub-agents for comprehensive codebase analysis
   • Creates timestamped research documents with metadata
   • Integrates findings from both code and memory repository

2. Plan (/create_plan) - Design your approach with concrete steps

   • Structured implementation plans with technical details
   • Clear requirements analysis and integration points
   • Breaks down complex features into actionable tasks

3. Implement (/implement_plan) - Execute with progress tracking

   • Follows approved plans while adapting to reality
   • Updates progress with todo lists and checkboxes
   • Verification at natural stopping points

4. Validate (/validate_plan) - Verify implementation completeness

   • Systematic checking against original plan
   • Automated verification (build, tests, linting)
   • Recommendations for missing or incomplete work

5. Commit (/commit) - Create atomic, well-documented commits

   • Reviews session changes and creates logical groupings
   • Focuses on "why" rather than just "what" changed
   • Maintains clean git history

Benefits

• Thorough Understanding: Research first reduces bugs and technical debt
• Clear Direction: Plans provide roadmap before coding begins
• Progress Tracking: Todo lists and validation prevent incomplete work
• Quality Commits: Thoughtful commit messages improve team communication

Getting Started

After running mem8 init, these commands are available in Claude Code as /research_codebase, /create_plan, etc. The workflow works best when following the sequence, but individual commands can be used as needed.

📋 Templates

Claude Code Configuration (claude-config)

Generates .claude/CLAUDE.md with:

• Project-specific instructions
• Custom agents and commands
• Memory management settings
• Development workflows

Example Usage:

mem8 init --template claude-config
# Creates: .claude/CLAUDE.md, commands/, agents/

Memory Repository (memory-repo)

Creates structured documentation with:

• Research document templates
• Planning frameworks
• Decision logs
• Shared memory structure

Example Usage:

mem8 init --template memory-repo  
# Creates: memory/shared/, memory/research/, etc.

🎛️ Configuration

Basic Setup

# Initialize in existing project
cd your-project
mem8 init --template claude-config

# Customize the generated .claude/CLAUDE.md
# Add project-specific instructions and workflows

Advanced Configuration

# Use custom cookiecutter configs
mem8 init --template claude-config --config-file custom-config.yaml

# Link shared memory across projects
mem8 sync --link-shared ~/shared-memory

💻 Web Interface (Optional)

The mem8 web interface provides a browser-based viewer for your workspace:

Features

• Browse research and planning documents
• Search across all markdown files
• View file contents with syntax highlighting
• Navigate between different thought categories

Setup Options

Quick Start (Development)

# Install dependencies and start the web interface
cd frontend && npm install && npm run dev
# Access at http://localhost:22211

Docker Compose (Full Stack)

# Start all services (frontend, backend, database)
docker-compose up -d

# Services available at:
# - Frontend: http://localhost:22211
# - Backend API: http://localhost:8000
# - PostgreSQL: localhost:5432

Note: The web interface is a simple file viewer - no authentication or database required.

🔧 Project Structure

your-project/
├── .claude/
│   ├── CLAUDE.md          # Main Claude Code configuration
│   ├── commands/          # Custom commands
│   └── agents/           # Custom agent definitions
├── memory/
│   ├── shared/           # Shared documentation
│   ├── research/         # Research documents
│   └── plans/           # Implementation plans
└── mem8-config.yaml     # mem8 workspace settings

👥 Contributing

We welcome contributions! See CONTRIBUTING.md for detailed development setup instructions.

Quick Links:

• 🐛 Report Issues
• 💬 Discussions
• 🔧 Development Guide
• 🐳 Docker Setup

🛠️ Advanced Usage

Search Functionality

# Full-text search
mem8 search "authentication"

# Search in specific directories
mem8 search "API" --path memory/shared/research

# Search with filters
mem8 search "bug" --tags "urgent" --type "plans"

Sync and Sharing

# Sync with shared directory
mem8 sync

# Create symlinks to shared memory
mem8 sync --link ~/team-shared-memory

# Check sync status
mem8 status --verbose

Custom Templates

# Create new template from existing project
mem8 template create my-template --from .

# Use custom template
mem8 init --template ./my-custom-template

📚 Integration with Claude Code

Custom Agents

Place agent definitions in .claude/agents/:

# .claude/agents/researcher.md
You are a research assistant focused on technical documentation...

Custom Commands

Add commands in .claude/commands/:

# .claude/commands/analyze.sh
#!/bin/bash
echo "Analyzing codebase structure..."

Workspace Memory

Configure in .claude/CLAUDE.md:

# Project Context
- Use `memory/research/` for background research
- Store implementation plans in `memory/plans/`
- Document decisions in `memory/decisions/`

🚀 Production Deployment

Quick Start with Docker

# Build and start all services
docker-compose up -d

# Test the deployment (Windows PowerShell)
./test-docker.ps1

# Test the deployment (Linux/Mac)
./test-docker.sh

# Services will be available at:
# - Frontend: http://localhost:22211
# - API: http://localhost:8000
# - API Docs: http://localhost:8000/docs

API Server (Requires Docker)

The mem8 serve command starts the FastAPI backend server. This requires a database (PostgreSQL or SQLite) which is provided via Docker:

# Start backend with Docker (recommended)
docker-compose --env-file .env.dev up -d backend db

# The backend is now available at:
# - API: http://localhost:8000
# - Docs: http://localhost:8000/docs
# - Health: http://localhost:8000/api/v1/health

Why Docker is required:

• Backend needs PostgreSQL database for teams, memory, and authentication
• Docker Compose provides the full stack (backend + database + optional frontend)
• See DOCKER.md for all deployment options

Docker Deployment Options

Production Stack (docker-compose.prod.yml)

# Start full production stack
docker-compose -f docker-compose.prod.yml --env-file .env.prod up -d

# View logs
docker-compose -f docker-compose.prod.yml logs -f backend  # API logs
docker-compose -f docker-compose.prod.yml logs -f frontend # Frontend logs

# Stop services
docker-compose -f docker-compose.prod.yml down

# Clean up (removes volumes)
docker-compose -f docker-compose.prod.yml down -v

Development Stack (with Hot Reloading)

# Start development environment with hot-reload enabled
docker-compose --env-file .env.dev up -d --build

# Frontend and backend will auto-reload on code changes
# View logs: docker-compose --env-file .env.dev logs -f

Architecture

The production deployment uses:

• mem8 serve: FastAPI backend with unified CLI entry point
• PostgreSQL: Primary database for storing memory and metadata
• Redis: Cache layer and websocket support
• Next.js: Frontend application on port 22211

🧰 Requirements

• Python 3.8+ - For mem8 CLI
• uv - Package manager (curl -LsSf https://astral.sh/uv/install.sh | sh)
• Node.js 18+ - For optional web interface
• Git - For sync functionality

🔄 Workflow Examples

Research & Planning

# Start new research
mem8 init --template memory-repo
cd memory/research
# Create research-topic.md

# Plan implementation  
cd ../plans
# Create implementation-plan.md

# Search for related work
mem8 search "similar feature" --type research

Claude Code Customization

# Set up Claude Code for new project
cd my-new-project  
mem8 init --template claude-config

# Customize .claude/CLAUDE.md with:
# - Project-specific context
# - Custom agent definitions  
# - Development workflows

# Test configuration
claude-code --help

📝 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions welcome! Focus areas:

1. New Templates - Create templates for different project types
2. CLI Enhancements - Improve search and sync functionality
3. Web Interface - Enhance the memory file viewer
4. Documentation - Improve setup and usage guides

---

Designed for developers using Claude Code to enhance AI-assisted development workflows.