Skip to main content

Core Concepts

Understanding mem8's key concepts and architecture.

Overview​

mem8 is built around three core concepts:

  1. Memory - Structured markdown documentation for persistent context
  2. CLI Tools - Commands for searching, syncing, and managing memory
  3. Claude Code Integration - AI-assisted development workflows via plugin

Memory​

What is Memory?​

Memory consists of structured markdown documents that capture:

  • Research - Codebase analysis and investigation
  • Plans - Implementation designs and steps
  • Decisions - Technical choices and rationale
  • PRs - Pull request descriptions and context
  • Notes - General observations and ideas

Memory Structure​

memory/
├── research/        # Research documents
├── plans/           # Implementation plans
├── prs/             # PR descriptions
├── decisions/       # Technical decisions
└── searchable/      # Symlinks for fast search

Memory Lifecycle​

  1. Create - Use slash commands (/mem8:research, /mem8:plan)
  2. Edit - Modify markdown files directly
  3. Search - Find with mem8 search "query"
  4. Sync - Share with team via mem8 sync

Setting Up Memory​

Create a memory directory manually or use git submodules for team sharing:

# Local memory
mkdir -p memory/{research,plans,decisions,prs}

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

Claude Code Integration​

What is Claude Code?​

Claude Code is Anthropic's AI-powered development environment. mem8 enhances it with:

Agents​

Specialized AI assistants for:

  • codebase-analyzer - Deep code analysis
  • thoughts-locator - Find relevant thoughts
  • web-search-researcher - Research online
  • github-workflow-agent - GitHub automation

Commands​

Workflow automation:

  • /mem8:research - Analyze existing code
  • /mem8:plan - Design implementation
  • /mem8:implement - Execute with context
  • /mem8:commit - Create conventional commits
  • /mem8:describe-pr - Generate PR descriptions

Workflow Integration​

mem8 connects Claude Code to:

  • GitHub - Issues, PRs, workflows
  • Memory - Research and plans
  • Plugins - Standardized workflows

Workspace​

Workspace Structure​

A mem8 workspace contains:

project/
├── .mem8/            # Workspace metadata
│   └── toolbelt.json # CLI toolbelt manifest
├── .claude/          # Claude Code customizations
│   ├── agents/      # AI agent definitions
│   ├── commands/    # Slash command scripts
│   └── CLAUDE.md    # Workspace configuration
├── memory/         # Thought repository
│   ├── shared/      # Team thoughts
│   └── username/    # Personal thoughts
└── README.md         # Project documentation

The .mem8 directory stores lightweight workspace metadata. By default it contains toolbelt.json, a manifest generated by your template that lists core, recommended, and optional CLI tools for Windows, macOS, and Linux. mem8 doctor reads this file to highlight missing tooling without installing anything automatically.

Workspace Setup​

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

# Check workspace status
mem8 status

# Run diagnostics
mem8 doctor

Workspace Health​

Check workspace status:

# Quick check
mem8 status

# Detailed diagnostics
mem8 status --detailed

# Auto-fix issues
mem8 doctor --auto-fix

Configuration​

Config Locations​

mem8 uses platformdirs for config storage:

  • Config - ~/.config/mem8/config.yaml
  • Data - ~/.local/share/mem8/
  • Cache - ~/.cache/mem8/

Config File​

Example ~/.config/mem8/config.yaml:

workspace:
  auto_sync: true

discovery:
  cross_repo: false

workflow:
  provider: github
  automation_level: standard

Environment Variables​

Override config with environment variables:

# Override config directory
export MEM8_CONFIG_DIR=/custom/path

# Override data directory
export MEM8_DATA_DIR=/custom/data

Search and Discovery​

Search System​

mem8 provides fast full-text search:

# Basic search
mem8 search "authentication"

# Limit results
mem8 search "query" --limit 10

# Specific locations
mem8 search "query" --path memory/shared/plans

Search Indexing​

  • Automatic - Indexes thoughts on creation
  • Incremental - Updates on file changes
  • Fast - Uses searchable symlinks

Discovery Modes​

  • Single-repo - Search current workspace only
  • Cross-repo - Search across all workspaces (opt-in)

Sync and Collaboration​

Sync Strategies​

# Two-way sync
mem8 sync --direction both

# Push only
mem8 sync --direction push

# Pull only
mem8 sync --direction pull

# Dry run
mem8 sync --dry-run

Conflict Resolution​

  • Prompt - Ask user (default)
  • Local - Prefer local changes
  • Shared - Prefer shared changes
  • Newest - Use newest timestamp

Team Workflows​

  1. Setup - Install mem8 CLI and Claude Code plugin
  2. Share - Commit memory/ to git (or use git submodule)
  3. Clone - Team members clone repo
  4. Sync - Use mem8 sync for memory sharing
  5. Search - Everyone can search shared memory

Architecture​

CLI Layer​

Built with Typer:

  • Command-line interface
  • Interactive prompts
  • Rich output formatting

Core Layer​

Python modules:

  • config.py - Configuration management
  • template_source.py - Template resolution
  • discovery.py - Thought discovery
  • sync.py - Synchronization logic

Storage Layer​

  • Local - Markdown files on filesystem
  • Database - Optional PostgreSQL for web interface
  • Git - Version control for thoughts

Optional Web Layer​

  • Backend - FastAPI server
  • Frontend - Next.js dashboard
  • Database - PostgreSQL for persistence

Design Principles​

CLI-First​

Everything accessible via command line. Web interface is optional enhancement.

Plain Text​

Thoughts are markdown files. No lock-in, works with any editor.

Git-Native​

Leverages git for versioning, sync, and collaboration.

Extensible​

Templates and workflows are customizable. External sources supported.

Team-Friendly​

Shared thoughts and standardized workflows for collaboration.

Next Steps​