AIMED Documentation - Complete Usage Guide

🎯 What is AIMED?

AIMED (AI Monitoring & Execution Dashboard) is a visual web interface for ConPort MCP that makes AI project context inspectable and manageable.

It provides comprehensive visual access to monitor, review, and manage all aspects of your AI assistant's understanding of your project.

🏗️ConPort MCP Foundation

• SQLite-backed structured storage
• Model Context Protocol server
• Multi-workspace support
• Vector search & embeddings
• Dynamic knowledge graph

📊AIMED Visual Layer

• Real-time dashboard interface
• Interactive knowledge graph
• Visual context management
• Advanced search interface
• Multi-workspace UI

🚀 Quick Start Guide

Quick start (about 5 minutes)

Clone the repository: git clone https://github.com/drew1two/AIMED.git
Install dependencies: uv pip install -r requirements.txt && cd ui && npm install
Configure your MCP client (see MCP Configuration section) using the server name conport-aimed
New project: In your IDE MCP panel, turn conport-aimed OFF, create your project + Python env, activate it, then turn conport-aimed ON again to initialize context_portal_aimed/
Launch AIMED dashboard: python context_portal_aimed/portal_launcher.py
The launcher will attempt to open your browser to http://localhost:3000 (or the printed WSL2 IP/port if applicable)

⚙️ Installation

Prerequisites

🐍

Python 3.10+

Required for ConPort MCP server

Download

📦

uv (Recommended)

Fast Python package manager

Install

📱

Node.js & npm

Required for web dashboard

Download

Setup Steps

1

Clone Repository

git clone https://github.com/drew1two/AIMED.git
cd AIMED

2

Setup Python Environment

uv venv
source .venv/bin/activate  # (or .venv\Scripts\activate on Windows)
uv pip install -r requirements.txt

3

Install Web Dependencies

cd ui
npm install
cd ..

MCP Configuration

⚠️

Important

You must configure your IDE's MCP settings before launching the dashboard. The dashboard requires the ConPort MCP server to be properly connected.

🪟Windows Configuration

{
  "mcpServers": {
    "conport-aimed": {
      "command": "path\\to\\your\\AIMED\\.venv\\Scripts\\python.exe",
      "args": [
        "path\\to\\your\\AIMED\\src\\context_portal_mcp\\main.py",
        "--mode", "stdio",
        "--log-file", "./logs/conport.log",
        "--log-level", "INFO"
      ],
      "env": {
        "PYTHONPATH": "path\\to\\AIMED\\src"
      },
      "transportType": "stdio"
    }
  }
}

🐧Linux/WSL Configuration

{
  "mcpServers": {
    "conport-aimed": {
      "command": "/path/to/your/AIMED/.venv/bin/python",
      "args": [
        "/path/to/your/AIMED/src/context_portal_mcp/main.py",
        "--mode", "stdio",
        "--log-file", "./logs/conport.log",
        "--log-level", "INFO"
      ],
      "env": {
        "PYTHONPATH": "/path/to/your/AIMED/src"
      },
      "transportType": "stdio"
    }
  }
}

💡Notes

• If your IDE doesn't expand ${workspaceFolder}, use the absolute path instead
• You can omit --workspace_id to enable automatic workspace detection
• Set --log-level DEBUG for detailed troubleshooting logs

🚀Launch AIMED

python context_portal_aimed/portal_launcher.py

This launches the AIMED dashboard for the current project. If you have multiple projects active, each project uses the next available port automatically so they can run simultaneously.

📚 Core Features

📊Dashboard

Activity Feed View

• Recent progress updates
• Decision logs with rationale
• Context changes tracking
• System pattern updates
• Knowledge graph links

Kanban Board View

• Drag-and-drop task management
• TODO, IN_PROGRESS, DONE columns
• Real-time status updates
• Task hierarchy support
• Visual progress indicators

Dashboard Controls

View Toggle

Switch between Activity Feed and Kanban views

Saved Views

All Items, Standup, Planning, Review

Live Updates

Configurable polling interval (3s default)

🕸️Knowledge Graph

Interactive Canvas

Visual exploration and creation of relationships between all project elements including decisions, progress items, patterns, and custom data.

Node Operations

• Drag nodes to reposition
• Right-click for context menu
• Double-click to view details
• Hover for quick info

Link Creation

• Click "Create Link" button
• Select source and target nodes
• Choose relationship type
• Add optional description

Relationship Types

blocked_by builds_on clarifies consumes depends_on derived_from documented_in implements produces related_to resolves tracks verifies

🕒Context Management

🎯Product Context

Overall project goals, features, and architecture. This context persists across sessions and provides foundational understanding.

• Project vision and objectives
• Key features and components
• Technical architecture
• Target audience definition

⚡Active Context

Current working focus, recent changes, and open issues. This context represents your immediate work session.

• Current task focus
• Recent changes summary
• Open issues and blockers
• Session-specific goals

Context Editor Features

Visual Forms

Intuitive editing interface with structured fields

Version History

Track all changes with timestamps and summaries

Auto-save

Changes are automatically saved and synchronized

📦Data Management

AIMED provides comprehensive CRUD interfaces for all your project data, organized under a streamlined "Data" dropdown in the navigation.

⚡

Decisions

Log and track architectural and implementation decisions with rationale and tags.

• Decision summary and rationale
• Implementation details
• Tag-based categorization
• Full-text search support

✅

Progress

Task and milestone tracking with visual status management and hierarchies.

• TODO/IN_PROGRESS/DONE status
• Parent-child task relationships
• Linked to other data items
• Kanban board integration

🏗️

Patterns

System and coding patterns for reusable architectural knowledge.

• Pattern name and description
• Usage examples and context
• Tag-based organization
• Searchable pattern library

📋

Custom Data

Flexible key-value storage for project-specific information and glossaries.

• Category-based organization
• JSON-serializable values
• ProjectGlossary category
• Full-text search across all data

🔗

Links

Manage relationships between different data items in your knowledge graph.

• Source and target item linking
• Relationship type definitions
• Optional descriptions
• Visual graph representation

🔍Advanced Search

Full-Text Search (FTS5)

Fast keyword-based search across all your project data with SQLite FTS5 engine.

• Search decisions, progress, patterns
• Custom data and contexts
• Field-specific search prefixes
• Instant results with highlighting

Semantic Search

Natural language queries using vector embeddings for conceptual matching.

• Understanding of intent and context
• Cross-reference related concepts
• Similarity-based rankings
• Advanced filtering options

Search Tips

FTS5 Prefixes

• summary: Search decision summaries
• category: Filter by custom data category
• tags: Search by tags

Search Strategies

• Use quotes for exact phrases
• Combine keywords with OR/AND
• Try semantic search for concepts

🔧 Troubleshooting

🚫MCP Server Not Connected

Symptoms: Dashboard shows "MCP Server Error" or connection issues

Solutions:

Verify your MCP client configuration matches the examples above
Check that Python virtual environment is activated
Ensure all dependencies are installed: uv pip install -r requirements.txt
Review logs in ./logs/conport.log if specified

📁Workspace Detection Issues

Symptoms: "Failed to detect workspace" or wrong project context

Solutions:

Use absolute path instead of ${workspaceFolder}
Remove --workspace_id to enable auto-detection
Create a projectBrief.md file in your project root
Check for .git, package.json, or pyproject.toml in your project root

🌐WSL2 Network Issues

Symptoms: Cannot access dashboard from Windows browser when running in WSL2

Solutions:

AIMED automatically detects WSL2 and configures networking
Use the WSL2 IP address shown in the launch output
Ensure Windows Firewall allows the connection
Try accessing via localhost:3000 first, then the WSL2 IP

💾Database Issues

Symptoms: Data not saving, search not working, migration errors

Solutions:

Check file permissions on context_portal_aimed/context_aimed.db
Delete database and restart for clean slate (warning: Only do this on fresh new projects, else make a backup of your data before deleting): rm context_portal_aimed/context_aimed.db
Review migration logs for schema update issues
Backup data with export tools before major updates

📞Getting Help

GitHub Issues

Report bugs and request features

Open Issue →

Discussions

Community help and questions

Join Discussion →

Debug Logs

Enable detailed logging

--log-level DEBUG

🔌 API Reference

AIMED provides both MCP tools (for AI assistants) and REST API access to ConPort data. All operations require a workspace_id parameter.

🤖MCP Tools (AI Assistants)

AI assistants use these tools via Model Context Protocol to interact with your project data.

• get_recent_activity_summary
• log_decision / get_decisions
• log_progress / get_progress
• semantic_search_conport
• link_conport_items

🌐REST API (Web Dashboard)

The web dashboard communicates with ConPort via HTTP REST API endpoints.

• POST /mcp - MCP tool execution
• GET /health - Server status
• WebSocket - Future real-time updates

Key MCP Tools

Context Management

get_product_context(workspace_id)
update_product_context(workspace_id, content)
get_active_context(workspace_id)
update_active_context(workspace_id, content)

Decision Tracking

log_decision(workspace_id, summary, rationale, tags)
get_decisions(workspace_id, limit, tags_filter)
search_decisions_fts(workspace_id, query_term)
delete_decision_by_id(workspace_id, decision_id)

Progress Tracking

log_progress(workspace_id, status, description)
get_progress(workspace_id, status_filter, limit)
update_progress(workspace_id, progress_id, status)
search_progress_fts(workspace_id, query_term)

Knowledge Graph

link_conport_items(workspace_id, source_type, 
  source_id, target_type, target_id, relationship)
get_linked_items(workspace_id, item_type, item_id)
semantic_search_conport(workspace_id, query_text)