M.I.M.I.R - Multi-agent Intelligent Memory & Insight Repository
AI-Powered Memory Bank + Task Management Orchestration with Knowledge Graphs
Give your AI agents a persistent memory with relationship understanding.
Imagine your AI assistant that can remember every task you've discussed, understand how they relate to each other, and recall relevant context from weeks ago. Mimir makes this possible by combining Neo4j's powerful graph database with AI embeddings and the Model Context Protocol. Your AI doesn't just store isolated facts—it builds a living knowledge graph that grows smarter with every conversation. Perfect for developers managing complex projects where tasks depend on each other, contexts overlap, and you need an AI that truly understands your work.
Mimir is a Model Context Protocol (MCP) server that provides AI assistants (Claude, ChatGPT, etc.) with a persistent graph database to store tasks, context, and relationships. Instead of forgetting everything between conversations, your AI can remember, learn, and build knowledge over time.
📖 Table of Contents
- Why Mimir? - What problems does it solve?
- Quick Start - Get running in 5 minutes
- Configuration - Environment setup
- Usage - How to use with AI agents
- File Indexing - Index your codebase for RAG
- Architecture - How it works
- Features - What can it do?
- PCTX Integration - 98% token reduction with Code Mode
- Troubleshooting - Common issues
- Documentation - Learn more
🎯 Why Mimir?
Without Mimir:
- AI forgets context between conversations
- No persistent task tracking
- Can't see relationships between tasks
- Limited to current conversation context
With Mimir:
- AI remembers all tasks and context
- Persistent Neo4j graph database
- Discovers relationships automatically
- Multi-agent coordination
- Semantic search with AI embeddings
Perfect for:
- Long-term software projects
- Multi-agent AI workflows
- Complex task orchestration
- Knowledge graph building
⚡ Quick Start (3 Steps)
💡 New to Mimir? Check out the 5-minute Quick Start Guide for a step-by-step walkthrough.
🔌 Connecting to IDE? See the IDE Integration Guide for VS Code, Cursor, and Windsurf setup!
🎯 VS Code Users? Try the Dev Container setup for instant environment with zero configuration!
1. Prerequisites
- Docker Desktop - Download here
- Node.js 18+ - Download here
- Git - Download here
2. Install & Start
# Clone the repository
git clone https://github.com/orneryd/Mimir.git
cd Mimir
# Copy environment template
cp env.example .env
# Start all services (automatically detects your platform)
npm run start
# Or manually: docker compose up -d
That's it! Services will start in the background. The startup script automatically detects your platform (macOS ARM64, Linux, Windows) and uses the optimized docker-compose file.
⚠️ IMPORTANT - Configure Workspace Access:
The ONLY required configuration is HOST_WORKSPACE_ROOT in .env:
# Your main source code directory (default: ~/src)
# This gives Mimir access to your code for file indexing
HOST_WORKSPACE_ROOT=~/src # ✅ Tilde (~) works automatically!
What this does:
- Mounts your source directory to the container (default: read-write)
- You manually choose which folders to index via UI or VSCode plugin
- Don't panic! Indexing is per-folder and requires your explicit action
- Tilde expansion:
~/srcautomatically expands to your home directory (e.g.,/Users/john/src)
For read-only access, edit docker-compose.yml:
volumes:
- ${HOST_WORKSPACE_ROOT:-~/src}:${WORKSPACE_ROOT:-/workspace}:ro # Add :ro flag
3. Verify It's Working
# Check that all services are running
npm run status
# Or manually: docker compose ps
# View logs
npm run logs
# Open Mimir Web UI (includes file indexing, orchestration studio, and portal)
# Visit: http://localhost:9042
# Open Neo4j Browser (default password: "password")
# Visit: http://localhost:7474
# Check MCP server health
curl http://localhost:9042/health
Available Commands:
npm run start- Start all servicesnpm run stop- Stop all servicesnpm run restart- Restart servicesnpm run logs- View logsnpm run status- Check service statusnpm run rebuild- Full rebuild without cache
See scripts/START_SCRIPT.md for more details.
You're ready! The Mimir Web UI is now available at http://localhost:9042
What you get:
- 🎯 Portal: Main hub with navigation and file indexing http://localhost:9042/portal
- 🎨 Orchestration Studio: Visual workflow builder (beta) http://localhost:9042/studio
- 🔌 MCP API: RESTful API at
http://localhost:9042/mcp - 💬 Chat API: OpenAI-compatible endpoints at
http://localhost:9042/v1/chat/completionsand/v1/embeddings
⚙️ Configuration
Environment Variables
Edit the .env file to customize your setup. Most users can use the defaults.
Core Settings (Required)
# Neo4j Database
NEO4J_PASSWORD=password # Change in production!
# Docker Workspace Mount
HOST_WORKSPACE_ROOT=~/src # Your main workspace area
LLM Configuration (For Chat API & Orchestration)
# Provider Selection
MIMIR_DEFAULT_PROVIDER=openai # Options: openai, copilot, ollama, llama.cpp
# LLM API Configuration
MIMIR_LLM_API=http://copilot-api:4141 # Base URL (required)
MIMIR_LLM_API_PATH=/v1/chat/completions # Optional (default: /v1/chat/completions)
MIMIR_LLM_API_MODELS_PATH=/v1/models # Optional (default: /v1/models)
MIMIR_LLM_API_KEY=dummy-key # Optional (use for OpenAI API)
# Model Selection
MIMIR_DEFAULT_MODEL=gpt-4.1 # Default: gpt-4.1
# Embeddings Configuration
MIMIR_EMBEDDINGS_MODEL=bge-m3 # Default: bge-m3
MIMIR_EMBEDDINGS_API=http://llama-server:8080 # Embeddings endpoint
MIMIR_EMBEDDINGS_API_PATH=/v1/embeddings # Optional (default: /v1/embeddings)
MIMIR_EMBEDDINGS_DIMENSIONS=1024 # Default: 1024
MIMIR_EMBEDDINGS_CHUNK_SIZE=768 # Default: 768
Provider Options:
openaiorcopilot: OpenAI-compatible endpoints (GitHub Copilot, OpenAI API, or any compatible service)ollamaorllama.cpp: Local LLM providers (Ollama or llama.cpp - interchangeable)
Configuration Examples:
Example 1: Copilot API (GitHub Copilot license, recommended for development):
MIMIR_DEFAULT_PROVIDER=openai
MIMIR_LLM_API=http://copilot-api:4141
MIMIR_DEFAULT_MODEL=gpt-4.1
MIMIR_EMBEDDINGS_MODEL=bge-m3
MIMIR_EMBEDDINGS_DIMENSIONS=1024
MIMIR_EMBEDDINGS_CHUNK_SIZE=768
Example 2: Local Ollama (offline, fully local):
MIMIR_DEFAULT_PROVIDER=ollama
MIMIR_LLM_API=http://ollama:11434
MIMIR_DEFAULT_MODEL=qwen2.5-coder
MIMIR_EMBEDDINGS_MODEL=bge-m3
Example 3: OpenAI API (cloud-based, requires API key):
MIMIR_DEFAULT_PROVIDER=openai
MIMIR_LLM_API=https://api.openai.com
MIMIR_LLM_API_PATH=/v1/chat/completions
MIMIR_LLM_API_KEY=sk-...
MIMIR_DEFAULT_MODEL=gpt-4
MIMIR_EMBEDDINGS_MODEL=text-embedding-3-small
MIMIR_EMBEDDINGS_DIMENSIONS=1536
Available Models (Dynamic):
Models are fetched dynamically from your configured LLM provider at runtime. To see available models:
# Query Mimir's models endpoint
curl http://localhost:9042/api/models
# Or query your LLM provider directly
curl $LLM_API_URL/v1/models
All models from the LLM provider's /v1/models endpoint are automatically available - no hardcoded list!
Switching Providers: Change MIMIR_DEFAULT_PROVIDER and MIMIR_LLM_API in .env, then restart:
docker compose restart mimir-server
Existing conversations remain unchanged - the new provider is used for subsequent messages.
Embeddings (Optional - for semantic search)
# Enable vector embeddings for AI semantic search
MIMIR_EMBEDDINGS_ENABLED=true
MIMIR_FEATURE_VECTOR_EMBEDDINGS=true
# Embedding provider (uses same endpoints as LLM by default)
MIMIR_EMBEDDINGS_API=http://llama-server:8080
MIMIR_EMBEDDINGS_MODEL=nomic-embed-text
MIMIR_EMBEDDINGS_DIMENSIONS=1024
Embeddings can use the same endpoint as your LLM, or a separate specialized service (like llama.cpp for embeddings only).
Supported Embedding Models:
nomic-embed-text(default - lightweight, 768 dims)bge-m3(higher quality, 1024 dims)text-embedding-3-small(OpenAI, 1536 dims - requires OpenAI LLM provider)
Advanced Settings (Optional)
# Auto-index Mimir documentation on startup (default: true)
# Allows users to immediately query Mimir's docs via semantic search
MIMIR_AUTO_INDEX_DOCS=true
# Per-agent model overrides (optional - defaults to MIMIR_DEFAULT_MODEL)
MIMIR_PM_MODEL=gpt-4.1 # PM agent model
MIMIR_WORKER_MODEL=gpt-4o-mini # Worker agent model
MIMIR_QC_MODEL=gpt-4.1 # QC agent model
# Corporate Proxy (if needed)
HTTP_PROXY=http://proxy.company.com:8080
HTTPS_PROXY=http://proxy.company.com:8080
# Custom CA Certificates (if needed)
SSL_CERT_FILE=/path/to/corporate-ca.crt
Documentation Auto-Indexing:
By default, Mimir automatically indexes its own documentation (/app/docs) on startup. This allows you to immediately query Mimir's documentation using semantic search:
"How do I configure embeddings?"
"Show me the IDE integration guide"
"Explain the multi-agent architecture"
To disable auto-indexing, set in .env:
MIMIR_AUTO_INDEX_DOCS=false
See env.example or docker-compose.yml for complete list of configuration options.
Optional Services
By default, only the core services run (Mimir Server, Neo4j, Copilot API). You can enable additional services by uncommenting them in docker-compose.yml:
Enable Ollama (Local LLM Provider)
Why enable? Run LLMs completely offline, no external dependencies.
# 1. Edit docker-compose.yml - uncomment the ollama service
# 2. Update .env file:
MIMIR_DEFAULT_PROVIDER=ollama
MIMIR_LLM_API=http://ollama:11434
MIMIR_DEFAULT_MODEL=qwen2.5-coder
# 3. Restart services
docker compose up -d
Using External Ollama Instead:
If you already have Ollama running on your host or another machine:
# In .env file:
MIMIR_LLM_API=http://192.168.1.100:11434 # Your Ollama server
# Restart Mimir
docker compose restart mimir-server
Enable Open-WebUI (Alternative Chat Interface)
Why enable? Alternative web UI for chatting with Ollama models, useful for testing.
# 1. Edit docker-compose.yml - uncomment the open-webui service and volumes
# 2. Restart services
docker compose up -d
# 3. Access Open-WebUI at http://localhost:3000
Configuration:
- Uses Copilot API by default for models
- Can be configured to use Ollama instead
- See
docker/open-webui/README.mdfor details
🎯 Usage
VSCode Extension (⭐ NEW!)
Mimir Chat Assistant brings Graph-RAG directly into VSCode with native chat integration.
Installation
-
Package the extension:
cd vscode-extension npm install npm run compile npm run package # Creates mimir-chat-0.1.0.vsix -
Install in VSCode:
Cmd+Shift+P→ "Extensions: Install from VSIX..."- Select
mimir-chat-0.1.0.vsix - Reload VSCode
Usage
Type @mimir in the VSCode Chat window:
@mimir what is Neo4j?
@mimir -u research how does graph RAG work?
@mimir -m gpt-4.1 -d 3 explain multi-agent orchestration
Flags (Per-Message Overrides)
| Flag | Short | Description | Example |
|---|---|---|---|
--use | -u | Preamble/chatmode | @mimir -u research ... |
--model | -m | Model override | @mimir -m gpt-4o ... |
--depth | -d | Graph depth (1-3) | @mimir -d 3 ... |
--limit | -l | Max results | @mimir -l 20 ... |
--similarity | -s | Threshold (0-1) | @mimir -s 0.7 ... |
--max-tools | -t | Max tool calls | @mimir -t 5 ... |
--no-tools | Disable tools | @mimir --no-tools ... |
Extension Settings
Configure via Preferences > Settings > Mimir:
{
"mimir.apiUrl": "http://localhost:9042",
"mimir.defaultPreamble": "mimir-v2",
"mimir.model": "gpt-4.1",
"mimir.vectorSearch.depth": 1,
"mimir.vectorSearch.limit": 10,
"mimir.vectorSearch.minSimilarity": 0.5,
"mimir.enableTools": true,
"mimir.maxToolCalls": 3
}
Model Selection:
- The extension respects the VS Code Chat dropdown (the "Claude Sonnet 4.5" selector in Chat UI)
- Override with
-mflag:@mimir -m gpt-4.1 ... - Fallback to
mimir.modelsetting if dropdown not available
Chatmode/Preamble Behavior:
- First message: Uses
mimir.defaultPreamblesetting - Follow-ups: Keeps existing preamble from conversation
- Switch with
-uflag:@mimir -u hackerman analyze this
See Also
- vscode-extension/README.md - Detailed extension documentation
- vscode-extension/TESTING.md - Testing and development
Using with AI Agents (MCP)
Mimir works as an MCP server - AI assistants can call it to store and retrieve information.
Example conversation with Claude/ChatGPT:
You: "Create a TODO for implementing user authentication"
AI: [Uses create_todo tool]
✓ Created TODO: "Implement user authentication" (todo-123)
You: "Add context about which files are involved"
AI: [Uses update_todo_context tool]
✓ Added context: src/auth.ts, src/middleware/auth.ts
You: "Show me all pending tasks"
AI: [Uses list_todos tool]
Found 3 pending tasks:
1. Implement user authentication
2. Set up database migrations
3. Write API documentation
Available Tools
Mimir provides 13 MCP tools for AI agents:
Memory Operations (6 tools):
memory_node- Create/read/update nodes (tasks, files, concepts)memory_edge- Create relationships between nodesmemory_batch- Bulk operations for efficiencymemory_lock- Multi-agent coordinationmemory_clear- Clear data (use carefully!)get_task_context- Get filtered context by agent type
File Indexing (3 tools):
index_folder- Index code files into graphremove_folder- Stop watching folderlist_folders- Show watched folders
Vector Search (2 tools):
vector_search_nodes- Semantic search with AI embeddingsget_embedding_stats- Embedding statistics
Todo Management (2 tools):
todo- Manage individual taskstodo_list- Manage task lists
File Indexing
Mimir can automatically index your codebase for semantic search and RAG (Retrieval-Augmented Generation). Files are watched for changes and re-indexed automatically.
Quick Start
Add a folder to index:
# Using local path (recommended)
npm run index:add /path/to/your/project
# Or using workspace mount path (if local path fails)
npm run index:add /workspace/my-project
# With embeddings (slower but enables semantic search)
npm run index:add /path/to/your/project --embeddings
List indexed folders:
npm run index:list
Remove a folder:
npm run index:remove /path/to/your/project
⚠️ Note: Large folders may take several minutes to index. Don't kill the process! Watch the logs to see chunking progress. The script will show "✨ Done!" when complete.
Supported File Types
✅ Fully Supported (with syntax highlighting):
- Languages: TypeScript (.ts, .tsx), JavaScript (.js, .jsx), Python (.py), Java (.java), Go (.go), Rust (.rs), C/C++ (.c, .cpp), C# (.cs), Ruby (.rb), PHP (.php)
- Markup: Markdown (.md), HTML (.html), XML (.xml)
- Data: JSON (.json), YAML (.yaml, .yml), SQL (.sql)
- Styles: CSS (.css), SCSS (.scss)
- Documents: PDF (.pdf), DOCX (.docx) - text extraction
✅ Generic Support (plain text indexing):
- Any text file not in the skip list below
❌ Automatically Skipped:
- Images: .png, .jpg, .jpeg, .gif, .bmp, .ico, .svg, .webp, .tiff
- Videos: .mp4, .avi, .mov, .wmv, .flv, .webm, .mkv
- Audio: .mp3, .wav, .ogg, .m4a, .flac, .aac
- Archives: .zip, .tar, .gz, .rar, .7z, .bz2
- Binaries: .exe, .dll, .so, .dylib, .bin, .wasm
- Compiled: .pyc, .pyo, .class, .o, .obj
- Databases: .db, .sqlite, .sqlite3
- Lock files: package-lock.json, yarn.lock, pnpm-lock.yaml
.gitignore Respect
Mimir automatically respects your .gitignore file:
# Your .gitignore
node_modules/
dist/
.env
*.log
# These will NOT be indexed ✅
Additional patterns:
- Hidden files (
.git/,.DS_Store) - Build artifacts (
build/,dist/,out/) - Dependencies (
node_modules/,venv/,vendor/)
Indexing Examples
Index a single project:
npm run index:add ~/projects/my-app
Index multiple projects:
# Bash/Zsh
for dir in ~/projects/*/; do
npm run index:add "$dir"
done
# PowerShell
Get-ChildItem ~/projects -Directory | ForEach-Object {
npm run index:add $_.FullName
}
Check what's indexed:
# List all indexed folders
npm run index:list
# Or query Neo4j directly for file count
curl -u neo4j:password -X POST http://localhost:7474/db/neo4j/tx/commit \
-H "Content-Type: application/json" \
-d '{"statements":[{"statement":"MATCH (f:File) RETURN count(f) as file_count"}]}'
How It Works
- Scan: Walks directory tree, respecting
.gitignore - Parse: Extracts text content (or from PDF/DOCX)
- Chunk: Splits large files into 1000-char chunks
- Embed: Generates vector embeddings for semantic search (optional)
- Store: Creates File nodes and FileChunk nodes in Neo4j
- Watch: Monitors for changes and re-indexes automatically
Storage Details
File Node Properties:
path: Relative path from workspace rootabsolute_path: Full filesystem pathname: Filenameextension: File extensionlanguage: Detected language (typescript, python, etc.)content: Full file contentsize_bytes: File sizeline_count: Number of lineslast_modified: Last modification timestamp
FileChunk Node Properties:
text: Chunk content (max 1000 chars)chunk_index: Position in file (0, 1, 2...)embedding: Vector embedding (1024 dimensions)
Relationships:
File -[:HAS_CHUNK]-> FileChunk
Performance
- Small projects (<100 files): ~5-10 seconds
- Medium projects (100-1000 files): ~30-60 seconds
- Large projects (1000+ files): ~2-5 minutes
With embeddings enabled: Add ~50% more time for vector generation.
Troubleshooting
Problem: Local path fails to index
# If local machine path fails, use workspace mount path instead
npm run index:add /workspace/my-project/subfolder
# The workspace mount path matches the internal Docker mount
# Check your docker-compose.yml for the workspace mount location
Problem: Files not being indexed
# Check .gitignore patterns
cat .gitignore
# Verify file is not in skip list (see "Automatically Skipped" section above)
# Check file is readable
ls -la /path/to/file
Problem: Process seems stuck
# Don't kill it! Large folders take time to index.
# Watch the logs to see progress:
docker compose logs -f mimir-server
# You should see:
# - "📄 Indexing file: ..." (scanning)
# - "📝 Created chunk X for file Y" (chunking)
# - "✨ Done!" (complete)
Problem: Too many files indexed
# Add patterns to .gitignore
echo "node_modules/" >> .gitignore
echo "dist/" >> .gitignore
# Re-index (will respect new .gitignore)
npm run index:remove /path/to/project
npm run index:add /path/to/project
Problem: Embeddings not working
# Check Ollama is running
curl http://localhost:11434/api/tags
# Verify model is available
docker exec -it ollama_server ollama list | grep mxbai
# If Ollama is running but the embedding model isn't present (or you see
# embedding errors at runtime), you can pull the model using the helper
# script. Default model for code embeddings: `nomic-embed-text`
./scripts/pull-model.sh nomic-embed-text
# Or pull embedding model manually
docker exec -it ollama_server ollama pull nomic-embed-text
Web UI
Access Mimir through your browser at http://localhost:9042:
🎯 Portal (Main Hub)
- File indexing management (add/remove folders)
- Navigation to other features
- System status and health
🎨 Orchestration Studio (Coming Soon)
- Visual workflow builder
- Agent coordination
- Task dependency graphs
HTTP APIs
Mimir provides multiple APIs for different use cases:
1. MCP API - For AI assistants (Claude, ChatGPT, etc.)
# Initialize MCP session
curl -X POST http://localhost:9042/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {},
"clientInfo": {"name": "my-app", "version": "1.0.0"}
},
"id": 1
}'
# Call a tool (create TODO)
curl -X POST http://localhost:9042/mcp \
-H "Content-Type: application/json" \
-H "Mcp-Session-Id: YOUR_SESSION_ID" \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "todo",
"arguments": {
"operation": "create",
"title": "My Task",
"priority": "high"
}
},
"id": 2
}'
2. Chat API - OpenAI-compatible chat completions
# Send a message (OpenAI-compatible format)
curl -X POST http://localhost:9042/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4.1",
"messages": [
{"role": "user", "content": "Create a todo for implementing authentication"}
],
"stream": false
}'
Chat API with MCP Tools & RAG
The Chat API (/v1/chat/completions) provides OpenAI-compatible chat completions with built-in MCP tool support and Retrieval-Augmented Generation (RAG).
Features
- Full MCP Tool Support: Access all 13 Mimir tools (memory, file indexing, semantic search, todos)
- Semantic Search: Automatically retrieves relevant context from indexed files
- Conversation Memory: Persists conversations with thread IDs
- Multi-Provider LLM Support: Switch between Ollama, OpenAI, copilot-api with one config
LLM Configuration
The Chat API uses a unified LLM configuration - switch providers by changing environment variables only:
# Provider Selection
MIMIR_DEFAULT_PROVIDER=openai # Options: openai, ollama
# API Endpoint
MIMIR_LLM_API=http://copilot-api:4141
# Model Selection
MIMIR_DEFAULT_MODEL=gpt-4.1 # Default: gpt-4.1
# Embedding Model
MIMIR_EMBEDDINGS_MODEL=bge-m3
Provider Examples
Using Copilot API (GitHub Copilot license - recommended for development)
MIMIR_DEFAULT_PROVIDER=openai
MIMIR_LLM_API=http://copilot-api:4141
MIMIR_DEFAULT_MODEL=gpt-4.1
MIMIR_EMBEDDINGS_MODEL=bge-m3
Using Local Ollama
MIMIR_DEFAULT_PROVIDER=ollama
MIMIR_LLM_API=http://ollama:11434
MIMIR_DEFAULT_MODEL=qwen2.5-coder
MIMIR_EMBEDDINGS_MODEL=bge-m3
Using OpenAI API
MIMIR_DEFAULT_PROVIDER=openai
MIMIR_LLM_API=https://api.openai.com
MIMIR_LLM_API_KEY=sk-...
MIMIR_DEFAULT_MODEL=gpt-4-turbo
Chat API Request Format
POST /v1/chat/completions
Content-Type: application/json
{
"message": "Create a TODO and index my project",
"conversationId": "my-session-123",
"enable_tools": true, # Enable MCP tool access (default: true)
"enable_rag": true, # Enable semantic search context (default: true)
"system_prompt": "You are a helpful AI assistant..." # Optional custom system prompt
}
Request Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
message | string | ✅ | - | The user's message |
conversationId | string | ✅ | new UUID | Conversation thread identifier |
enable_tools | boolean | ✅ | true | Enable MCP tools (memory, todos, semantic search) |
enable_rag | boolean | ✅ | true | Enable Retrieval-Augmented Generation |
system_prompt | string | ✅ | default | Custom system prompt for this conversation |
Response Format (Streaming)
{
"type": "message",
"content": "I've created a TODO and indexed your project...",
"conversationId": "my-session-123",
"toolCalls": [
{
"tool": "todo",
"operation": "create",
"result": "todo-456"
},
{
"tool": "index_folder",
"path": "/workspace/my-project",
"result": "✓ Indexed 127 files"
}
]
}
Switching Providers at Runtime
To switch providers, update .env and restart:
# Switch from copilot-api to Ollama
MIMIR_DEFAULT_PROVIDER=ollama
MIMIR_LLM_API=http://ollama:11434
docker compose restart mimir-server
All existing conversations and chat history remain intact. The new provider is used for subsequent messages.
Embedding Models
The embedding model determines semantic search quality. bge-m3 is the default (high quality, efficient):
| Model | Dimensions | Speed | Notes |
|---|---|---|---|
bge-m3 | 1024 | Fast | Default - recommended |
nomic-embed-text | 768 | Fast | Lightweight alternative |
text-embedding-3-small | 1536 | Fast | OpenAI-compatible, excellent quality |
Change in .env:
MIMIR_EMBEDDINGS_MODEL=text-embedding-3-small # For OpenAI providers
MIMIR_EMBEDDINGS_DIMENSIONS=1536
3. Orchestration API - For workflow execution
# Execute a plan with multiple tasks
curl -X POST http://localhost:9042/api/orchestrate/execute \
-H "Content-Type: application/json" \
-d '{
"plan": {
"tasks": [
{"id": "1", "title": "Setup project", "dependencies": []}
]
}
}'
Architecture
What's Running?
When you run docker compose up -d, you get these services:
| Service | Port | Purpose | URL |
|---|---|---|---|
| Mimir Server | 9042 | Web UI + MCP API + Chat API | http://localhost:9042 |
| Neo4j | 7474, 7687 | Graph database storage | http://localhost:7474 |
| Copilot API | 4141 | AI model access (OpenAI-compatible) | http://localhost:4141 |
Optional Services (commented out by default):
| Service | Port | Purpose | Enable With |
|---|---|---|---|
| Ollama | 11434 | Local LLM embeddings | Uncomment in docker-compose.yml |
| Open-WebUI | 3000 | Alternative chat UI | Uncomment in docker-compose.yml |
Unified LLM Configuration: The Chat API supports any OpenAI-compatible endpoint:
- Copilot API (GitHub Copilot license) - Default provider
- Ollama (local, offline)
- OpenAI API (cloud-based)
Switch providers by changing
MIMIR_DEFAULT_PROVIDERandMIMIR_LLM_APIin.env
Embeddings: Semantic search uses
MIMIR_EMBEDDINGS_MODEL(default:bge-m3@ 1024 dimensions):
- Set
MIMIR_EMBEDDINGS_APIto match your embeddings provider- Can use same endpoint as LLM or separate specialized service
- See embeddings configuration section above for details
Open-WebUI: Optional alternative chat interface. Useful for testing Ollama models locally. To enable, uncomment the
open-webuiservice in docker-compose.yml and restart.
Optional Services (commented out by default):
| Service | Port | Purpose | Enable With |
|---|---|---|---|
| Ollama | 11434 | Local LLM embeddings | Uncomment in docker-compose.yml |
| Open-WebUI | 3000 | Alternative chat UI | Uncomment in docker-compose.yml |
� Embeddings: For semantic search, you need embeddings. Options:
- Use external Ollama server (recommended - set
OLLAMA_BASE_URLin .env)- Enable built-in Ollama service (uncomment in docker-compose.yml)
- Use Copilot embeddings (experimental - set
MIMIR_EMBEDDINGS_PROVIDER=copilot)- Use any OpenAI-compatible embeddings endpoint
� Copilot API: Required for orchestration workflows. Provides OpenAI-compatible API using your GitHub Copilot license. Any OpenAI-compatible API also works.
� Open-WebUI: Optional alternative chat interface. Useful for testing Ollama models locally. To enable, uncomment the
open-webuiservice in docker-compose.yml and restart.
How It Works
┌─────────────────────────────────────────┐
│ Mimir Server (Port 9042) │
│ ┌─────────────────────────────────┐ │
│ │ Frontend (React + Vite) │ │ ← Web UI
│ │ - Portal with file indexing │ │
│ │ - Orchestration Studio │ │
│ └─────────────────────────────────┘ │
│ ┌─────────────────────────────────┐ │
│ │ Backend (Node.js) │ │
│ │ - MCP API (/mcp) │ │ ← AI Assistants
│ │ - Chat API (/v1/chat/completions) │ │ ← OpenAI-compatible
│ │ - Orchestration API (/api/...) │ │ ← Workflows
│ └─────────────────────────────────┘ │
└───────────────┬─────────────────────────┘
│
▼
┌───────────────────────────────────────┐
│ Neo4j DB (Ports 7474, 7687) │ ← Persistent Storage
│ - Tasks, files, relationships │
│ - Vector embeddings (semantic) │
└───────────────────────────────────────┘
Key Points:
- Mimir Server provides both Web UI and APIs on port 9042
- Neo4j stores everything (tasks, relationships, files, embeddings)
- Copilot API provides AI models for orchestration (optional)
- Ollama provides embeddings for semantic search (optional, can be external)
- All data persists between restarts in
./data/neo4j/
Data Persistence
Your data is stored in local directories:
./data/neo4j/ # Database files (tasks, relationships, etc.)
./logs/ # Application logs
./copilot-data/ # GitHub authentication tokens
✅ Stopping containers doesn't delete data! Your tasks and knowledge graph persist.
🔧 Troubleshooting
Common Issues
Services won't start:
# Check Docker is running
docker info
# Check for port conflicts
docker compose ps
docker compose logs
# Restart services
docker compose down
docker compose up -d
Can't connect to Neo4j:
# Wait for Neo4j to fully start (takes 30-60 seconds)
docker compose logs neo4j
# Check it's responding
curl http://localhost:7474
# Reset Neo4j data (⚠️ deletes everything!)
docker compose down
rm -rf ./data/neo4j
docker compose up -d
Embeddings not working:
# Check your .env file
cat .env | grep EMBEDDINGS
# If using Ollama, start it with profile
docker compose --profile ollama up -d
# Check Ollama is responding
curl http://localhost:11434/api/tags
# If using Copilot, verify authentication
docker compose logs copilot-api
Port conflicts:
If ports are already in use, edit docker-compose.yml:
services:
mimir-server:
ports:
- "9043:3000" # Change 9043 to any available port
neo4j:
ports:
- "7475:7474" # Change 7475 to any available port
- "7688:7687" # Change 7688 to any available port
copilot-api:
ports:
- "4142:4141" # Change 4142 to any available port
Need Help?
- Check logs:
docker compose logs [service-name] - Service status:
docker compose ps - Health checks:
- Mimir Web UI: http://localhost:9042
- Mimir API Health: http://localhost:9042/health
- Neo4j Browser: http://localhost:7474
- GitHub Issues: Report a problem
💡 Usage Examples
Basic Task Management
Create a task:
{
"operation": "create",
"title": "Implement user authentication",
"description": "Add JWT-based auth to API",
"priority": "high",
"status": "pending"
}
Add context to task:
{
"operation": "update",
"id": "todo-123",
"context": {
"files": ["src/auth.ts", "src/middleware/auth.ts"],
"apiEndpoint": "/api/auth/login"
}
}
List all tasks:
{
"operation": "list",
"status": "pending" // Filter by status
}
Knowledge Graph Features
Create relationships:
// Link a task to a project
{
"operation": "add",
"source": "todo-123",
"target": "project-456",
"type": "part_of"
}
Find related items:
// Get all tasks related to a project
{
"operation": "neighbors",
"node_id": "project-456",
"edge_type": "part_of"
}
Search with AI:
// Semantic search using embeddings
{
"query": "authentication and security tasks",
"limit": 5,
"types": ["todo", "file"]
}
📚 Documentation
Getting Started:
- 🧠 Memory Guide - How to use the memory system
- 🕸️ Knowledge Graph Guide - Understanding graph relationships
- 🐳 Docker Deployment - Production deployment
- 🎨 Portal UI User Guide - Complete web interface tutorial ⭐
- 🔌 Model Provider Guide - Use Mimir in Cursor, Continue.dev, and more 🆕
For AI Agent Developers:
- 🤖 AGENTS.md - Complete agent workflow guide
- 🔧 Configuration Guide - VSCode, Cursor, Claude Desktop setup
- 🧪 Testing Guide - Test suite overview
- 📖 Server API Documentation - Complete TypeScript API reference
Advanced Topics:
- 🏗️ Multi-Agent Architecture - System architecture
- 🛣️ Implementation Roadmap - Development roadmap
- 📊 Research - Academic research and analysis
🔧 Development
Start services:
docker compose up -d # Start all services
docker compose down # Stop all services
docker compose logs # View logs
Local development:
npm install # Installs dependencies for all workspaces including frontend
npm run build # Compile TypeScript
npm test # Run tests
Project structure:
src/
├── index.ts # MCP server entry point
├── managers/ # Core business logic
├── tools/ # MCP tool definitions
└── orchestrator/ # Multi-agent system
✨ Key Features
Core Capabilities:
- ✅ Persistent Memory - Tasks and context stored in Neo4j graph database
- ✅ Knowledge Graph - Connect tasks, files, and concepts with relationships
- ✅ AI Semantic Search - Find tasks by meaning, not just keywords
- ✅ Multi-Agent Support - Multiple AI agents can work together safely
- ✅ File Indexing - Automatically track and index your codebase
- ✅ MCP Standard - Works with any MCP-compatible AI assistant
Advanced Features:
- 🔐 Task Locking - Prevent conflicts when multiple agents work simultaneously
- 📊 Context Enrichment - Automatic relationship discovery
- 🔍 Vector Embeddings - Optional semantic search with AI embeddings
- 📈 Graph Visualization - View your task network in Neo4j Browser
🚀 PCTX Integration (Code Mode)
NEW: Mimir now supports PCTX for Code Mode execution, reducing token usage by up to 98%!
Instead of sequential tool calls, AI agents can write TypeScript code that executes in a sandboxed environment:
// Traditional MCP: 3 separate calls, 50K+ tokens
// With PCTX Code Mode: Single execution, ~2K tokens (96% reduction!)
async function run() {
const results = await Mimir.vectorSearchNodes({
query: "authentication tasks",
types: ["todo"],
limit: 10
});
const pending = results.results.filter(r => r.properties.status === "pending");
await Mimir.memoryBatch({
operation: "update_nodes",
updates: pending.map(r => ({id: r.id, properties: {status: "in_progress"}}))
});
return {updated: pending.length};
}
Benefits:
- ✅ 98% token reduction for complex operations
- ✅ Type-safe TypeScript with instant feedback
- ✅ Secure sandbox execution (Deno)
- ✅ All 13 Mimir tools available via
Mimir.*namespace - ✅ Multi-server workflows (combine Mimir + GitHub + Slack)
Quick Start:
# Install PCTX
brew install portofcontext/tap/pctx
# Start PCTX (Mimir must be running)
cd Mimir
pctx start
# Connect your AI to: http://localhost:8080/mcp
Documentation:
- 📖 PCTX Integration Guide - Complete usage guide with examples
- 🔬 Integration Analysis - Architecture and rationale
🗺️ Roadmap
Current Status (v1.0): Production ready with core features
Coming Soon:
- Multi-agent orchestration patterns (PM/Worker/QC)
- Enhanced context deduplication
- Agent performance monitoring
- Distributed task execution
See full roadmap for details.
📋 Quick Reference
Common Commands
# Start/stop services
docker compose up -d # Start all services
docker compose down # Stop all services
docker compose restart # Restart all services
# View logs
docker compose logs # All services
docker compose logs neo4j # Neo4j only
docker compose logs mimir-server # Mimir server only
# Check status
docker compose ps # Container status
curl http://localhost:9042/health # MCP health
curl http://localhost:7474 # Neo4j browser
Important URLs
- Mimir Web UI: http://localhost:9042 (Portal, file indexing, APIs)
- Neo4j Browser: http://localhost:7474 (user:
neo4j, pass:password) - Copilot API: http://localhost:4141 (AI model access)
- Ollama (if external): http://localhost:11434 (embeddings)
- Open-WebUI (if enabled): http://localhost:3000 (alternative chat UI)
Data Locations
- Neo4j data:
./data/neo4j/ - Logs:
./logs/ - Config:
.env(100% ENV-based, no config files needed)
🏆 Why Choose Mimir?
Mimir is the only open-source solution that combines Graph-RAG (graph relationships + vector embeddings) with multi-agent orchestration and AI assistant integration.
Feature Comparison
| Feature | Mimir | Pinecone | Weaviate | Milvus | Qdrant |
|---|---|---|---|---|---|
| Graph Relationships | ✅ Native | ❌ None | ⚠️ Limited | ❌ None | ❌ None |
| Vector Search | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |
| ACID Transactions | ✅ Full | ❌ None | ❌ None | ❌ None | ❌ None |
| Graph Algorithms | ✅ Built-in | ❌ None | ❌ None | ❌ None | ❌ None |
| MCP Integration | ✅ Native | ❌ None | ❌ None | ❌ None | ❌ None |
| Multi-Agent Support | ✅ Built-in | ❌ None | ❌ None | ❌ None | ❌ None |
| Self-Hosting | ✅ Free | ❌ Cloud-only | ✅ Yes | ✅ Yes | ✅ Yes |
| Open Source | ✅ Yes | ❌ No | ✅ Yes | ✅ Yes | ✅ Yes |
| Starting Cost | 💰 Free | 💰 $70/mo | 💰 $25/mo | 💰 Free | 💰 Free |
Mimir's Unique Advantages:
- 🕸️ Only solution with native graph traversal + vector search - Understand relationships, not just similarity
- 🤖 Built-in multi-agent orchestration - PM → Worker → QC workflows out of the box
- 🔌 Direct AI assistant integration - Works with Claude, ChatGPT via MCP protocol
- 💾 ACID transactions - Your data is always consistent and reliable
- 🆓 100% open-source and free - No vendor lock-in, full control
Perfect for developers building AI agents that need to understand how tasks relate to each other, not just find similar items.
🤝 Contributing
Contributions welcome! Please:
- Fork the repository
- Create a feature branch
- Submit a pull request
See CONTRIBUTING.md for guidelines.
📄 License
MIT License with additional terms for AI/ML systems - see LICENSE for details
🙏 Acknowledgments
Built on research from Anthropic, Microsoft, and the Graph-RAG community.
Questions? Open an issue or check the documentation