Skip to main content

Installation

Get mem8 installed and running on your system.

Prerequisites​

  • uv - Fast Python package installer (recommended)
  • Git - For template cloning, version control, and shared memory features

uv is the fastest way to install mem8:

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install mem8
uv tool install mem8

mem8 is now available in your PATH:

mem8 --version
mem8 --help

Install from Source​

For development or to get the latest features:

# Clone the repository
git clone https://github.com/killerapp/mem8.git
cd mem8

# Install in editable mode
uv tool install --editable .

Verify Installation​

Check that mem8 is installed correctly:

# Check version
mem8 --version

# View available commands
mem8 --help

# Run diagnostics
mem8 doctor

If your project template includes a .mem8/toolbelt.json file, mem8 doctor will also confirm that the declared core CLI tools are installed for your operating system and suggest installs for any missing recommendations.

Shared Memory (Git Submodules)​

mem8 supports shared organizational memory through git submodules. This allows teams to maintain a centralized knowledge base that multiple projects can reference.

Setup​

The mem8 CLI automatically works with memory/ directories, whether they're regular directories or git submodules. To set up shared organizational memory:

# Add your organization's memory repository as a submodule
git submodule add https://github.com/your-org/shared-memory.git memory
git submodule update --init --recursive

# Or clone the mem8 plugin which includes memory structure
# See https://github.com/killerapp/mem8-plugin for plugin installation

Working with Shared Memory​

All mem8 commands automatically work with the memory/ directory, whether it's a regular directory or a git submodule:

# Search works across all memory including submodules
mem8 search "authentication"

# Find commands discover all memory
mem8 find plans
mem8 find research

# Sync operations respect git submodule structure
mem8 sync

Updating Shared Memory​

Use standard git submodule commands to update the shared memory:

# Update to latest from remote
cd memory
git pull origin main
cd ..
git add memory
git commit -m "chore: update shared memory"

# Or update all submodules
git submodule update --remote --merge

Benefits:

  • Share organizational knowledge across projects
  • Version-controlled team memory with git history
  • Searchable with mem8 search and mem8 find
  • Automatic detection by mem8 commands
  • Standard git workflow for updates

Note: The shared memory is stored as a git submodule in the memory/ directory at your project root. mem8 automatically detects and preserves git submodules during initialization.

Optional: GitHub CLI​

For GitHub integration features, install the GitHub CLI:

# macOS
brew install gh

# Windows
winget install GitHub.cli

# Linux
# See https://github.com/cli/cli#installation

Authenticate with GitHub:

gh auth login

Optional: Docker (for Web Interface)​

The web interface requires Docker:

  • Docker Desktop - Install Docker
  • Docker Compose - Included with Docker Desktop
# Verify Docker installation
docker --version
docker-compose --version

Update mem8​

To update to the latest version:

# With uv
uv tool install mem8 --upgrade

# From source
cd mem8
git pull
uv tool install --editable . --force

Uninstall​

To remove mem8:

# With uv
uv tool uninstall mem8

# Cleanup config (optional)
rm -rf ~/.config/mem8
rm -rf ~/.local/share/mem8

Next Steps​

Troubleshooting​

Command not found​

If mem8 command is not found after installation:

# Check if uv's bin directory is in PATH
echo $PATH | grep uv

# Add to PATH (bash/zsh)
export PATH="$HOME/.local/bin:$PATH"

# Add to PATH (fish)
fish_add_path ~/.local/bin

Permission errors​

On Unix systems, you may need to adjust permissions:

chmod +x ~/.local/bin/mem8

Python version​

Ensure you have Python 3.12 or higher:

python --version
# or
python3 --version

If you need to upgrade Python, use pyenv or your system's package manager.