---
sidebar_position: 1
---

# Getting Started

Your first steps with mem8.

## Set Up Your Workspace

### 1. Install mem8 CLI

Install mem8 to get CLI commands:

```bash
# Install with uv (fast, modern Python package manager)
uv tool install mem8
```

:::tip Install uv first
If you don't have uv installed:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
:::

### 2. Install Claude Code Plugin

Get workflow commands and specialized agents:

```bash
# In Claude Code, run:
/plugin install mem8@mem8-official
```

This provides:
- 8 workflow commands (`/mem8:research`, `/mem8:plan`, `/mem8:implement`, etc.)
- 6 specialized agents (codebase-analyzer, memory-locator, etc.)
- Integration with memory system

See the [plugin repository](https://github.com/killerapp/mem8-plugin) for full documentation.

### 3. Set Up Memory (Optional)

Create memory directory for persistent context:

```bash
cd your-project

# Create local memory structure
mkdir -p memory/shared/{research,plans,decisions}

# Or use a shared organizational repository
git submodule add https://github.com/your-org/shared-memory.git memory
```

### Using Organizational Plugins

Teams can create custom plugin versions. See the [mem8-plugin repository](https://github.com/killerapp/mem8-plugin) as a template.

## Your First Thought

### Research the Codebase

Start by understanding your project:

```bash
# In Claude Code, run:
/mem8:research "authentication system"
```

This creates a research document in `memory/shared/research/` with:
- Relevant code snippets
- Architecture notes
- Key findings

### Create a Plan

Design your implementation:

```bash
/mem8:plan "add OAuth2 support"
```

Generates a structured plan in `memory/shared/plans/` with:
- Requirements analysis
- Implementation steps
- Testing strategy

### Implement with Context

Execute your plan:

```bash
/mem8:implement memory/shared/plans/add-oauth2-support.md
```

Claude Code will:
- Load your plan for context
- Implement step-by-step
- Check off completed steps

### Commit Your Work

Create a conventional commit:

```bash
/mem8:commit
```

Generates a commit message based on your changes.

## Search Your Memory

Find information quickly:

```bash
# Basic search
mem8 search "authentication"

# Limit results
mem8 search "OAuth" --limit 5

# Search specific locations
mem8 search "database" --path memory/shared/research
```

## Check Workspace Status

Monitor your workspace health:

```bash
# Quick status
mem8 status

# Detailed view
mem8 status --detailed
```

Shows:
- âœ… Components installed
- ðŸ“Š Memory statistics
- ðŸ”— Git status
- âš ï¸ Issues found

## Sync with Team

Share memory with your team:

```bash
# Two-way sync
mem8 sync

# Push your changes
mem8 sync --direction push

# Pull team changes
mem8 sync --direction pull

# Preview changes
mem8 sync --dry-run
```

## Daily Workflow

### Morning Routine

```bash
# Pull latest memory
mem8 sync --direction pull

# Check for issues
mem8 doctor

# Review recent research
mem8 search "research" --limit 5
```

mem8 doctor reads the `.mem8/toolbelt.json` manifest generated by your template, checking workspace folders and required CLI tooling for your platform before you start working.


### During Development

1. **Research** - Understand the code
2. **Plan** - Design your approach
3. **Implement** - Execute with context
4. **Commit** - Document your changes

### End of Day

```bash
# Share your memory
mem8 sync --direction push

# Check workspace
mem8 status
```

## Tips & Tricks

### Keyboard Shortcuts

In Claude Code:
- `/` - List available commands
- `Ctrl+K` - Quick command palette
- `Tab` - Autocomplete

### Search Operators

```bash
# Exact phrase
mem8 search '"exact phrase"'

# Multiple terms
mem8 search "term1 term2"

# In specific directory
mem8 search "query" --path memory/shared/plans
```

### Backup Strategy

Memory is git repositories:

```bash
# Regular commits
cd memory
git add .
git commit -m "Update research"
git push
```

### Custom Plugins

Create organization-specific plugins:

1. Use the [mem8-plugin](https://github.com/killerapp/mem8-plugin) as a GitHub template
2. Customize commands and agents for your team
3. Share the plugin repository URL with team members
4. See [External Plugins](../external-templates) for detailed instructions

## Next Steps

- **[CLI Commands](./cli-commands)** - Full command reference
- **[Workflows](./workflows)** - Common development patterns
- **[External Plugins](../external-templates)** - Create custom workflows
- **[Troubleshooting](./troubleshooting)** - Solve common issues

## Common Tasks

### Add a New Agent

1. Create `agent-name.md` in `.claude/agents/`
2. Define the agent's purpose and tools
3. Test with Claude Code

### Add a Slash Command

1. Create `command-name.md` in `.claude/commands/`
2. Write the command prompt
3. Use in Claude Code with `/command-name`

### Share a Research Document

1. Create in `memory/shared/research/`
2. Commit to git
3. Team members pull with `mem8 sync`

### Find Old Decisions

```bash
mem8 search "decision" --path memory/shared/decisions
```

### Clean Up Old Memory

```bash
# Archive old memory
mkdir -p memory/archive/2024
mv memory/shared/research/old-* memory/archive/2024/
```

## Need Help?

- **Documentation** - You're reading it!
- **GitHub Issues** - https://github.com/killerapp/mem8/issues
- **Discussions** - https://github.com/killerapp/mem8/discussions
- **Diagnostics** - Run `mem8 doctor` for automated checks
