Mimir

Your Self-Evolving Engineering Playbook

Mimir helps you work more effectively by providing structured playbooks that your AI assistant can access directly in your IDE. Get guidance, generate work plans, track progress, and continuously improve your development process.

For architecture and design details, see docs/architecture/SAO.md

Core Entities

Mimir organizes your playbooks using 7 core entities:

1. Playbook - Top-level methodology container (e.g., "FDD", "Scrum")
2. Workflow - Sequence of activities for a process (e.g., "Build Feature")
3. Phase (optional) - Grouping for activities within workflows (e.g., "Inception", "Construction")
4. Activity - Unit of work with guidance (e.g., "Create screen mockup")
5. Artifact - Inputs/outputs of activities (e.g., "Component Specification", "Unit Tests")
6. Role - Who performs activities (e.g., "Frontend Engineer", "UX Designer")
7. Howto - Specific implementation instructions (e.g., "Creating mockups with Figma")

What Can Mimir Do?

Answer Playbook Questions via MCP

Your AI assistant can query Mimir directly from your IDE (powered by FastMCP):

You: "How do I build a TSX component per FDD playbook?"
AI: → Queries Mimir → Returns activity guidance and relevant Howtos

Generate Work Plans

Automatically create task breakdowns in GitHub or Jira:

You: "Plan implementation of scenario LOG1.1 and Screen LOG per FDD"
AI: → Generates work orders from playbook → Creates GitHub issues

Assess Project Progress

Check if you've completed all required artifacts for a phase:

You: "I'm supposed to finish inception phase next week. Did I produce all required artifacts?"
AI: → Scans codebase and issues → Reports status and gaps

Evolve Through Experience

When AI encounters issues during work, it can propose playbook improvements:

AI: → Detects repeated corrections → Creates Playbook Improvement Proposal (PIP)
You: → Reviews PIP in web UI → Approves with notes → New playbook version created

Access Playbook Library

Download playbooks from HOMEBASE based on your access level:

• Family-based: Software Engineering, UX Design, Testing, etc.
• Version tiers: LITE (Basic), FULL (Standard), EXTENDED (Premium)

Quick Start with Docker

Just want to run Mimir? Pull the container:

# Pull the latest release from Azure Container Registry
docker pull acrmimir.azurecr.io/mimir:release-latest

# Run with persistent storage
docker run -d \
  --name mimir \
  -p 8000:8000 \
  -v ~/mimir-data:/app/data \
  -e MIMIR_USER=yourusername \
  -e MIMIR_EMAIL=you@example.com \
  acrmimir.azurecr.io/mimir:release-latest

# Access the web interface
open http://localhost:8000

Configure MCP in your IDE:

For Windsurf (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "mimir": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "-e",
        "MIMIR_MCP_MODE=1",
        "mimir",
        "python",
        "manage.py",
        "mcp_server",
        "--user=yourusername"
      ]
    }
  }
}

For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "mimir": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "-e",
        "MIMIR_MCP_MODE=1",
        "mimir",
        "python",
        "manage.py",
        "mcp_server",
        "--user=yourusername"
      ]
    }
  }
}

For Cursor (.cursorrules or workspace settings):

{
  "mcp": {
    "servers": {
      "mimir": {
        "command": "docker",
        "args": [
          "exec",
          "-i",
          "-e",
          "MIMIR_MCP_MODE=1",
          "mimir",
          "python",
          "manage.py",
          "mcp_server",
          "--user=yourusername"
        ]
      }
    }
  }
}

Important: Replace yourusername with the username you set in MIMIR_USER when starting the container.

That's it! Your data persists in ~/mimir-data across container updates.

Multi-platform support: Works on Intel (amd64) and Apple Silicon (arm64) Macs
Auto-updates: Pull latest image and restart container to update
Data safety: Database stored in mounted volume survives container restarts

See docs/DOCKER_QUICK_START.md for more details.

---

Installation (For Development)

Prerequisites

• Python 3.11 or higher
• IDE with MCP support (Claude Desktop, Cursor, Windsurf, etc.)
• Access credentials for HOMEBASE (optional, for syncing)

Setup Steps

1. Clone the repository

   git clone https://github.com/petelind/mimir.git
   cd mimir
   

2. Create virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies

   pip install -r requirements.txt
   

4. Initialize database

   python manage.py migrate
   

   Note: The default database (mimir.db) includes the FeatureFactory playbook, which was used to build Mimir itself. This playbook provides a complete feature development workflow with 8 activities covering planning, implementation, testing, and finalization.

5. Create admin user (or use default)

   The database comes with a default admin account:

   • Username: admin
   • Password: admin

   For production or shared environments, create your own user:

   python manage.py createsuperuser
   

   You'll be prompted for:

   • Username (required)
   • Email (optional, for password reset)
   • Password (minimum 8 characters)

6. Run tests

   Run unit and integration tests:

   pytest tests/
   

   Note: BDD feature files in docs/features/act-*/ serve as comprehensive UI specifications (46 files covering Acts 0-15). Step definitions will be implemented during development.

Quick Reference

Running the Application

# Start web UI (keep running in terminal)
python manage.py runserver 8000
# → Open http://localhost:8000

# Test MCP server manually (different terminal)
python manage.py mcp_server --user=admin
# → Press Ctrl+C to stop

# Run all tests
pytest tests/
# → Should see: 250 passed, 1 skipped

# Create a new user
python manage.py createsuperuser

MCP Configuration Files

• Windsurf: ~/.codeium/windsurf/mcp_config.json
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• Cursor: Workspace .cursorrules or settings

See configuration details in section 2 below.

---

How to Use

Mimir runs as two processes that work together:

1. Start the Web Interface

python manage.py runserver 8000

Open http://localhost:8000 in your browser and log in with your credentials.

Once logged in, you can:

• Browse playbooks: View activities, workflows, phases, artifacts, roles, and howtos
• Review PIPs: Approve or reject Playbook Improvement Proposals
• Compare versions: See what changed between playbook versions
• Edit locally: Customize playbooks for your team

2. Configure MCP in Your IDE

Add Mimir to your MCP client configuration.

For Windsurf (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "mimir": {
      "command": "/absolute/path/to/mimir/venv/bin/python",
      "args": [
        "/absolute/path/to/mimir/manage.py",
        "mcp_server",
        "--user=admin"
      ],
      "env": {
        "DJANGO_SETTINGS_MODULE": "mimir.settings",
        "PYTHONPATH": "/absolute/path/to/mimir",
        "MIMIR_MCP_MODE": "1"
      },
      "disabled": false
    }
  }
}

For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "mimir": {
      "command": "/absolute/path/to/mimir/venv/bin/python",
      "args": [
        "/absolute/path/to/mimir/manage.py",
        "mcp_server",
        "--user=admin"
      ],
      "env": {
        "DJANGO_SETTINGS_MODULE": "mimir.settings",
        "PYTHONPATH": "/absolute/path/to/mimir",
        "MIMIR_MCP_MODE": "true"
      }
    }
  }
}

For Cursor (.cursorrules or workspace settings):

{
  "mcp": {
    "servers": {
      "mimir": {
        "command": "/absolute/path/to/mimir/venv/bin/python",
        "args": [
          "/absolute/path/to/mimir/manage.py",
          "mcp_server",
          "--user=admin"
        ],
        "env": {
          "DJANGO_SETTINGS_MODULE": "mimir.settings",
          "PYTHONPATH": "/absolute/path/to/mimir",
          "MIMIR_MCP_MODE": "true"
        }
      }
    }
  }
}

Important Notes:

• Replace /absolute/path/to/mimir with your actual project path
• Replace admin with your username (created in step 5 above)
• Use the full path to your virtual environment's Python binary
• The MIMIR_MCP_MODE environment variable disables console logging for Windsurf

Restart your IDE after configuration.

3. Use MCP Tools in Your IDE

Once configured, your AI assistant has access to 16 Mimir MCP tools for managing playbooks, workflows, and activities:

Playbook Management (5 tools)

• create_playbook - Create new draft playbooks
• list_playbooks - List playbooks (filter by status: draft/released/all)
• get_playbook - Get detailed playbook info with nested workflows
• update_playbook - Update playbook details (auto-increments version)
• delete_playbook - Delete draft playbooks

Workflow Management (5 tools)

• create_workflow - Add workflows to playbooks
• list_workflows - List workflows for a playbook
• get_workflow - Get workflow details with activities
• update_workflow - Update workflow details
• delete_workflow - Delete workflows from playbooks

Activity Management (6 tools)

• **