Related Pages

Related topics: Architecture Overview

Getting Started with Monomind

Monomind is an AI coordination system that orchestrates multiple AI agents to work together on complex software development tasks. It provides a unified CLI interface, memory management, knowledge graphs, and neural learning capabilities that enable agents to share context, learn from patterns, and collaborate effectively.

Overview

Monomind serves as the central intelligence layer for AI-assisted development workflows. It coordinates agents, manages sessions, stores learned patterns in vector memory, and provides a knowledge graph for understanding codebase relationships. Sources: packages/@monomind/cli/README.md

Key Capabilities

Installation

Prerequisites

• Node.js 18+ and npm/pnpm
• Git

Install via npm

npm install -g @monomind/cli

Or use directly with npx:

npx @monomind/cli@latest --help

Sources: packages/implementation/adrs/README.md

Verify Installation

monomind doctor --fix

This command checks the installation and attempts to fix common issues automatically.

Sources: README.md

Core Concepts

Architecture Overview

graph TD
    subgraph Monomind
        CLI[CLI Interface]
        MCP[MCP Server]
        Memory[Vector Memory]
        Graph[Knowledge Graph]
        SONA[Neural Learning]
    end
    
    subgraph Agents
        Coder[Coder Agent]
        Reviewer[Reviewer Agent]
        Architect[Architect Agent]
        Coordinator[Coordinator Agent]
    end
    
    CLI --> MCP
    CLI --> Memory
    CLI --> Graph
    Memory --> SONA
    Graph --> SONA
    
    MCP --> Coder
    MCP --> Reviewer
    MCP --> Architect
    MCP --> Coordinator

Agent Types

Monomind supports multiple specialized agent types, each with distinct capabilities:

Sources: packages/@monomind/cli/src/commands/agent.ts

CLI Commands Reference

Session Management

Manage conversation sessions with persistence and export capabilities.

# List all sessions
monomind session list

# Save current session state
monomind session save

# Restore a saved session
monomind session restore <session-id>

# Delete a saved session
monomind session delete <session-id>

# Export session to file
monomind session export <session-id> --output ./session.json

# Import session from file
monomind session import ./session.json

# Show current active session
monomind session current

Sources: packages/@monomind/cli/src/commands/session.ts

MCP Server Management

Control the Model Context Protocol server that provides tools to connected agents.

# Start MCP server
monomind mcp start

# Stop MCP server
monomind mcp stop

# Show server status
monomind mcp status

# Check server health
monomind mcp health

# Restart MCP server
monomind mcp restart

# List available tools
monomind mcp tools

# Enable/disable specific tools
monomind mcp toggle <tool-name> --enable
monomind mcp toggle <tool-name> --disable

# Execute a specific tool
monomind mcp exec <tool-name> --args <json>

# Show server logs
monomind mcp logs

Sources: packages/@monomind/cli/src/commands/mcp.ts

Task Management

Create and manage development tasks for agents to work on.

# Create a new task
monomind task create "Implement user authentication" --priority high

# List all tasks
monomind task list

# Get task details
monomind task status <task-id>

# Cancel a running task
monomind task cancel <task-id>

# Assign task to agent(s)
monomind task assign <task-id> --agents coder,reviewer

# Retry a failed task
monomind task retry <task-id>

Sources: packages/@monomind/cli/src/commands/task.ts

Agent Commands

# List available agents
monomind agent list

# Show agent metrics
monomind agent metrics

# Manage agent pool
monomind agent pool status

# Show agent health
monomind agent health

# Show agent logs
monomind agent logs --agent coder

# Check WASM runtime availability
monomind agent wasm-status

# Create a WASM-sandboxed agent
monomind agent wasm-create <template>

# List WASM agent gallery templates
monomind agent wasm-gallery

Sources: packages/@monomind/cli/src/commands/agent.ts

Memory & Intelligence System

Vector Memory (AgentDB + HNSW)

Monomind stores insights, patterns, and decisions in searchable vector memory with HNSW indexing.

graph LR
    A[User Input] --> B[Embedding Generator]
    B --> C[HNSW Index]
    C --> D[Vector Search]
    D --> E[Relevant Results]
    
    F[(SQLite)] --> G[Structured Data]
    G --> E

Key Features

Sources: packages/@monomind/memory/README.md

Memory Scopes

Memory is organized into three scopes:

Utility Functions

import {
  resolveAgentMemoryDir,  // Get scope directory path
  createAgentBridge,       // Create scoped AutoMemoryBridge
  transferKnowledge,       // Cross-agent knowledge sharing
  listAgentScopes,         // Discover existing agent scopes
} from '@monomind/memory';

// Resolve path for an agent scope
const dir = resolveAgentMemoryDir('my-agent', 'project');
// → /workspaces/my-project/.claude/agent-memory/my-agent/

// List all agent scopes in a directory
const scopes = await listAgentScopes('/workspaces/my-project');

Sources: packages/@monomind/memory/README.md

Knowledge Graph (Monograph)

Monograph builds a full dependency graph of your codebase that is automatically queried before every task.

# What files are relevant to my task?
monograph_suggest "add webhook retry logic"
# → returns ranked list of files with relevance scores

# What depends on UserService?
monograph_query "UserService dependencies"
# → returns file paths + line numbers

# Find the most connected files in the codebase
monograph_god_nodes
# → returns high-centrality internal files

Node Types in Monograph

Edge Types

CLI vs MCP Usage

Sources: plugin/commands/monograph/README.md

Neural Learning (SONA)

Self-Optimizing Neural Adaptation learns from every task:

• Pattern recognition improves agent routing over time
• Trajectory tracking identifies what works and what doesn't
• Automatic model adaptation with <0.05ms overhead

Quick Start Guide

Step 1: Initialize Monomind

# Run the setup wizard
monomind init

# Or initialize with specific template
monomind init --template minimal

Available templates:

• minimal - Quick start with behavioral rules
• standard - Full setup with all features
• full - Complete configuration with hooks and learning
• security - Security-focused configuration
• performance - Performance-optimized setup
• solo - Single developer workflow

Step 2: Configure Your Environment

# Set configuration
monomind config set providers.openai.api_key <your-key>
monomind config set providers.anthropic.api_key <your-key>

# List current configuration
monomind config list

# Export configuration
monomind config export ./config.json

# Import configuration
monomind config import ./config.json

Step 3: Start Working

graph TD
    A[Start Session] --> B[Create Task]
    B --> C[Agent Selection]
    C --> D{Parallel or Sequential?}
    D -->|Parallel| E[Swarm Orchestration]
    D -->|Sequential| F[Single Agent]
    E --> G[Memory Storage]
    F --> G
    G --> H[Pattern Learning]
    H --> I[Future Task Optimization]

Step 4: Session Workflow

# Start a new session
monomind session save

# Work on tasks
monomind task create "Build user dashboard"
monomind task assign <task-id> --agents coder

# Monitor progress
monomind task status <task-id>

# Review session details
monomind session current

Cross-Platform Helper Scripts

Monomind includes helper scripts for cross-platform development automation.

Installation

The helpers are automatically installed when you run monomind init and placed in .claude/helpers/.

Sources: packages/helpers/README.md

Available Helpers

Permission Issues (Linux/Mac)

find .claude/helpers -name "*.sh" -exec chmod +x {} \;

Windows PowerShell Execution Policy

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Sources: packages/helpers/README.md

Configuration Reference

Configuration File Location

Configuration is stored in:

• Project: .claude/monomind.config.json
• User: ~/.config/monomind/config.json

Runtime Options

Provider Configuration

# Configure AI providers
monomind providers configure openai
monomind providers configure anthropic
monomind providers configure local

# Test provider connection
monomind providers test openai

# View usage statistics
monomind providers usage

Troubleshooting

Common Issues

#### Installation Fails

# Clear cache and retry
npm cache clean --force
npm install -g @monomind/cli

#### MCP Server Won't Start

# Check server health
monomind mcp health

# View logs for errors
monomind mcp logs

# Restart the server
monomind mcp restart

#### Memory Search Returns No Results

# Check memory backend status
monomind memory status

# Rebuild vector index
monomind memory rebuild

Diagnostic Commands

# Run full diagnostics
monomind doctor

# Fix common issues automatically
monomind doctor --fix

# Check specific component
monomind agent health
monomind mcp status

Contributing

# Clone the repository
git clone https://github.com/monoes/monomind.git
cd monomind

# Install dependencies
pnpm install

# Run diagnostic and fix
monomind doctor --fix

See CONTRIBUTING.md for detailed guidelines.

License

MIT License — See LICENSE for details.

Related Pages

Related topics: Architecture Overview, Core Packages

Project Structure

Monomind is organized as a monorepo using pnpm workspaces, with the primary packages located in the packages/ directory and Claude Code integration files in the .claude/ directory.

Repository Layout

monomind/
├── packages/
│   ├── @monomind/           # Core packages
│   │   ├── cli/             # Command-line interface
│   │   ├── memory/          # Vector memory & AgentDB
│   │   ├── hooks/           # Hook system for automation
│   │   ├── swarm/           # Multi-agent coordination
│   │   ├── shared/          # Shared utilities & types
│   │   ├── plugins/         # Plugin system
│   │   └── aidefence/       # Security & audit tools
│   └── plugins/             # External plugins
│       ├── gastown-bridge/  # Thread-based work tracking
│       └── teammate-plugin/ # Claude Code integration
├── .claude/
│   ├── agents/              # Claude Code agent definitions
│   └── commands/             # Custom slash commands
└── README.md

Core Packages

@monomind/cli

The CLI package is the primary user-facing interface for Monomind. It provides commands for:

• Session Management — Save, restore, list, delete, export sessions
• Memory Operations — Store, retrieve, search, list, delete entries
• Agent Control — Metrics, pool management, health checks, WASM agents
• MCP Server — Start, stop, health checks, tool execution
• Configuration — Get, set, list, reset config values
• Plugins — Install, uninstall, toggle, list plugins

Sources: packages/@monomind/cli/src/commands/session.ts Sources: packages/@monomind/cli/src/commands/memory.ts Sources: packages/@monomind/cli/src/commands/mcp.ts

@monomind/memory

The memory package implements a hybrid storage backend combining:

Memory scopes follow a hierarchical structure:

Sources: packages/@monomind/memory/README.md

@monomind/hooks

The hooks system provides event-driven automation with support for:

• Pre/Post Hooks — Execute before/after operations
• Slash Commands — Custom CLI extensions
• Status Line — Real-time status updates

Hooks are configured via JSON:

{
  "onAgentStart": { "command": "log-agent-start" },
  "onTaskComplete": { "type": "command", "command": "notify" },
  "statusLine": { "type": "command", "command": "statusline" }
}

Sources: packages/@monomind/hooks/README.md

@monomind/swarm

Multi-agent coordination system enabling:

• Swarm Orchestration — Task distribution across agents
• Agent Communication — Inter-agent messaging protocols
• Load Balancing — Work distribution optimization
• Failure Recovery — Automatic retry and fallback mechanisms

@monomind/shared

Shared utilities and TypeScript types used across all Monomind packages:

• Common interfaces and type definitions
• Utility functions
• Constants and configuration schemas

@monomind/plugins

The plugin system provides extensibility through:

• Plugin Discovery — Automatic plugin detection
• Lifecycle Management — Install, enable, disable, uninstall
• Sandboxing — Isolated plugin execution environments

Claude Code Integration

.claude/agents

Agent definitions for Claude Code integration. Each agent can have:

• System Prompts — Custom instructions and behavior
• Tool Sets — Specific capabilities and permissions
• Memory Scopes — Dedicated knowledge bases

.claude/commands

Custom slash commands extend Claude Code's CLI:

# Available commands
monograph_suggest  # Get relevant file suggestions
monograph_query    # Query knowledge graph dependencies
monograph_god_nodes # Find highly-connected internal files

CLAUDE.md Generation

The CLI includes a CLAUDE.md generator with multiple templates:

export const CLAUDE_MD_TEMPLATES: Array<{ name: ClaudeMdTemplate; description: string }> = [
  { name: 'minimal', description: 'Quick start — behavioral rules, anti-drift' },
  { name: 'standard', description: 'Full features — swarm, hooks, intelligence' },
  { name: 'full', description: 'Complete — all sections including auto-start' },
  { name: 'security', description: 'Security-focused — audit, compliance' },
  { name: 'performance', description: 'Performance-focused — profiling, optimization' },
  { name: 'solo', description: 'Single agent — no swarm' },
];

Sources: packages/@monomind/cli/src/init/claudemd-generator.ts

External Plugins

gastown-bridge

Thread-based work tracking system with concepts:

teammate-plugin

Claude Code integration plugin providing:

• Claude Code version compatibility checking
• Teammate bridge creation
• Claude Code plugin system integration

Sources: packages/plugins/gastown-bridge/README.md Sources: packages/plugins/teammate-plugin/README.md

Architecture Diagram

graph TD
    subgraph "User Interface"
        CLI[CLI Commands]
        MCP[MCP Tools]
        SL[Slash Commands]
    end

    subgraph "packages/@monomind"
        CLI_PKG[@monomind/cli]
        MEM[@monomind/memory]
        HOOKS[@monomind/hooks]
        SWARM[@monomind/swarm]
        SHARED[@monomind/shared]
    end

    subgraph "Data Layer"
        AGENTDB[AgentDB<br/>HNSW Vector DB]
        SQLITE[SQLite]
        GRAPH[Knowledge Graph<br/>Monograph]
    end

    CLI --> CLI_PKG
    MCP --> CLI_PKG
    SL --> HOOKS

    CLI_PKG --> MEM
    CLI_PKG --> HOOKS
    CLI_PKG --> SWARM
    HOOKS --> SHARED
    SWARM --> SHARED

    MEM --> AGENTDB
    MEM --> SQLITE
    MEM --> GRAPH

Memory & Intelligence System

The Monomind intelligence layer consists of three interconnected systems:

graph LR
    subgraph "Intelligence"
        KG[Knowledge Graph<br/>Monograph]
        VM[Vector Memory<br/>AgentDB + HNSW]
        NL[Neural Learning<br/>SONA]
    end

    KG -.->|Dependency Graph| VM
    VM -.->|Semantic Search| NL
    NL -.->|Pattern Learning| KG

Knowledge Graph (Monograph)

Automatically builds dependency graphs of codebases:

• IMPORTS — Code import dependencies
• DEFINES — File defines symbol
• TAGGED_AS — Section tagged with concept
• CO_OCCURS — Concepts appear together
• INFERRED — Claude-extracted semantic relationship

Sources: plugin/commands/monograph/README.md

Build & Installation

# Clone repository
git clone https://github.com/nokhodian/monomind.git
cd monomind

# Install dependencies
pnpm install

# Run diagnostics
monomind doctor --fix

# Install CLI globally
npx @monomind/cli@latest --help

Contributing Guidelines

1. Fork the repository and create a feature branch
2. Run pnpm install to install dependencies
3. Use monomind doctor --fix to verify setup
4. Follow the CLAUDE.md guidelines for code contributions

Sources: README.md

Related Pages

Related topics: Core Packages, Swarm Topologies

Architecture Overview

Monomind is a comprehensive AI coordination system designed to orchestrate multiple AI agents, manage persistent memory, and provide intelligent workflow automation for complex software development tasks.

System Architecture

High-Level Architecture Diagram

graph TB
    subgraph "CLI Layer"
        CLI[CLI Interface<br/>@monomind/cli]
    end

    subgraph "Core Layer"
        MCP[MCP Server<br/>@monomind/mcp]
        Shared[Shared Core<br/>@monomind/shared]
    end

    subgraph "Capability Layer"
        Memory[Memory System<br/>@monomind/memory]
        Monograph[Knowledge Graph<br/>@monomind/monograph]
        AiDefence[Security<br/>@monomind/aidefence]
    end

    subgraph "Agent Layer"
        Agents[Agent Pool]
        WASM[WASM Runtime]
    end

    CLI --> MCP
    CLI --> Shared
    MCP --> Shared
    Shared --> Memory
    Shared --> Monograph
    Shared --> AiDefence
    MCP --> Agents
    Agents --> WASM

Package Structure

Core Packages

Capability Packages

Command Architecture

The CLI provides hierarchical command organization through subcommands. Each command follows a consistent pattern with help, list, and action subcommands.

graph LR
    subgraph "Top-Level Commands"
        session[session]
        task[task]
        agent[agent]
        mcp[mcp]
        config[config]
    end

    subgraph "Agent Subcommands"
        agent_list[agent list]
        agent_metrics[agent metrics]
        agent_pool[agent pool]
        agent_wasm[agent wasm-*]
    end

    subgraph "MCP Subcommands"
        mcp_start[start]
        mcp_stop[stop]
        mcp_status[status]
        mcp_tools[tools]
    end

    agent --> agent_list
    agent --> agent_metrics
    agent --> agent_pool
    agent --> agent_wasm
    mcp --> mcp_start
    mcp --> mcp_stop
    mcp --> mcp_status
    mcp --> mcp_tools

Session Management

Session commands provide conversation persistence and replay capabilities:

Task Orchestration

Tasks are the primary unit of work in Monomind, managed through the orchestrator:

// Task subcommands from packages/@monomind/cli/src/commands/task.ts
const TASK_SUBCOMMANDS = ['create', 'list', 'status', 'cancel', 'assign', 'retry'];

Agent System Architecture

Agent Types and Capabilities

graph TD
    subgraph "Agent Types"
        coder[Coder Agent]
        researcher[Researcher Agent]
        tester[Tester Agent]
        reviewer[Reviewer Agent]
        architect[Architect Agent]
        coordinator[Coordinator Agent]
        security[Security Architect]
        memory[Memory Specialist]
        performance[Performance Engineer]
    end

    subgraph "Capabilities"
        code-gen[code-generation<br/>refactoring<br/>debugging]
        research[web-search<br/>data-analysis]
        test[unit-testing<br/>integration-testing]
        review[code-review<br/>security-audit]
        design[system-design<br/>pattern-analysis]
        orchestrate[task-orchestration<br/>workflow-control]
        security-caps[threat-modeling<br/>compliance]
        memory-caps[vector-search<br/>caching]
        perf[caching<br/>optimization<br/>profiling]
    end

    coder --> code-gen
    researcher --> research
    tester --> test
    reviewer --> review
    architect --> design
    coordinator --> orchestrate
    security --> security-caps
    memory --> memory-caps
    performance --> perf

Agent Capability Matrix

*Sources: packages/@monomind/cli/src/commands/agent.ts:60-90*

WASM Agent Runtime

Monomind supports sandboxed agent execution via WebAssembly:

graph LR
    subgraph "WASM Commands"
        wasm-create[wasm-create]
        wasm-prompt[wasm-prompt]
        wasm-gallery[wasm-gallery]
        wasm-status[wasm-status]
    end

    subgraph "Gallery Templates"
        gallery1[Template 1]
        gallery2[Template 2]
        gallery3[Template N]
    end

    wasm-gallery --> gallery1
    wasm-gallery --> gallery2
    wasm-gallery --> gallery3
    wasm-create --> gallery1

*Sources: packages/@monomind/cli/src/commands/agent-wasm.ts:1-150*

Memory System Architecture

Memory Scopes

Monomind implements a hierarchical memory architecture with multiple scopes:

graph TD
    subgraph "Memory Scopes"
        global[Global<br/>~/.claude/agent-memory/]
        project[Project<br/>/.claude/agent-memory/]
        local[Local<br/>/.claude/agent-memory-local/]
        user[User<br/>~/.claude/agent-memory/]
    end

    subgraph "Per-Agent Isolation"
        coder[Coder Agent]
        tester[Tester Agent]
        reviewer[Reviewer Agent]
    end

    global --> coder
    global --> tester
    global --> reviewer
    project --> coder
    project --> tester
    project --> reviewer
    local --> coder
    local --> tester
    local --> reviewer

Memory Scope Configuration

*Sources: packages/@monomind/memory/README.md:50-100*

Hybrid Backend

The memory system uses a hybrid approach combining structured and vector storage:

graph LR
    subgraph "Hybrid Backend"
        SQLite[(SQLite<br/>Structured Data)]
        AgentDB[(AgentDB<br/>Vector Search)]
        HNSW[HNSW Index]
    end

    SQLite --> AgentDB
    AgentDB --> HNSW

A-MEM Auto-Linking

The system implements automatic semantic linking (arXiv:2409.11987):

// From packages/@monomind/memory/README.md
const backend = new HybridBackend({
  embeddingGenerator: async (text) => myEmbeddingModel.embed(text),
  // A-MEM auto-linking is automatically active when embeddingGenerator is set
});

Each stored entry automatically discovers its top-3 semantic neighbors and creates bidirectional references edges.

Knowledge Graph (Monograph)

Graph Node Types

Graph Edge Types

*Sources: plugin/commands/monograph/README.md:50-80*

Monograph Configuration

// From packages/@monomind/monograph/src/config/types.ts
interface MonographConfig {
  root: string;
  entry: string[];
  production: boolean;
  detection: 'default' | 'extended';
  project?: string;
  ignore: string[];
  overrides: OverrideConfig[];
  regression: RegressionConfig;
  audit: AuditConfig;
  normalization: NormalizationConfig;
  boundaries: BoundaryConfig;
  resolve: ResolveConfig;
  health: HealthConfig;
  ownership: OwnershipConfig;
  plugins: string[];
}

Default Configuration

// From packages/@monomind/monograph/src/config/types.ts:40-60
export const DEFAULT_MONOGRAPH_CONFIG: ResolvedMonographConfig = {
  root: '.',
  entry: [],
  production: true,
  detection: 'default',
  project: undefined,
  ignore: [],
  overrides: [],
  regression: { tolerance: 0, baselinePath: '.monograph/regression-baseline.json' },
  audit: { gate: 'error', includeHealthGate: false },
  normalization: { 
    stripComments: true, 
    normalizeWhitespace: true, 
    normalizeIdentifiers: false 
  },
  boundaries: {},
  resolve: { 
    paths: {}, 
    alias: {}, 
    conditions: [], 
    extensions: ['.ts', '.tsx', '.mts', '.cts'] 
  },
  health: { 
    cyclomaticThreshold: 10, 
    cognitiveThreshold: 15, 
    crapThreshold: 30, 
    minLines: 5 
  },
  ownership: { emailMode: 'fullEmail' },
  plugins: [],
};

MCP Server Architecture

Server Capabilities

graph TB
    subgraph "MCP Server"
        server[MCP Server<br/>packages/@monomind/mcp/src/server.ts]
        tools[Tool Handlers]
        resources[Resource Handlers]
    end

    subgraph "Tools"
        monograph_tools[Monograph Tools<br/>mcp__monomind__monograph_*]
        memory_tools[Memory Tools<br/>mcp__monomind__memory_*]
        agent_tools[Agent Tools<br/>mcp__monomind__agent_*]
    end

    server --> tools
    server --> resources
    tools --> monograph_tools
    tools --> memory_tools
    tools --> agent_tools

MCP Subcommands

*Sources: packages/@monomind/cli/src/commands/mcp.ts:20-45*

Neural Learning (SONA)

Self-Optimizing Neural Adaptation provides:

• Pattern Recognition: Improves agent routing over time
• Trajectory Tracking: Identifies what works and what doesn't
• Automatic Model Adaptation: <0.05ms overhead per decision

graph LR
    subgraph "SONA System"
        input[Task Input]
        pattern[Pattern Recognition]
        route[Agent Routing]
        track[Trajectory Tracking]
        adapt[Model Adaptation]
        output[Optimized Output]
    end

    input --> pattern
    pattern --> route
    route --> output
    output --> track
    track --> adapt
    adapt --> pattern

Command Suggestion System

The CLI includes a fuzzy matching system for typo correction:

graph TD
    input[User Input]
    input --> levenshtein[Levenshtein Distance]
    input --> similarity[Similarity Score]
    levenshtein --> threshold[Threshold Check]
    similarity --> threshold
    threshold --> suggestions[Suggestions]

*Sources: packages/@monomind/cli/src/suggest.ts:1-80*

Data Flow Architecture

sequenceDiagram
    participant User
    participant CLI
    participant MCP
    participant Shared
    participant Memory
    participant Monograph

    User->>CLI: Execute command
    CLI->>MCP: Route to MCP server
    MCP->>Shared: Core orchestration
    Shared->>Memory: Store/retrieve
    Shared->>Monograph: Query graph
    Memory-->>Shared: Results
    Monograph-->>Shared: Dependencies
    Shared-->>MCP: Processed data
    MCP-->>CLI: Response
    CLI-->>User: Output

Extended Configuration

The Monograph system supports extended configuration for enterprise use:

// From packages/@monomind/monograph/src/config/types.ts:70-90
export interface ExtendedMonographConfig extends MonographConfig {
  extends?: string[];
  sealed?: boolean;
  includeEntryExports?: boolean;
  publicPackages?: string[];
  dynamicallyLoaded?: string[];
  codeowners?: string;
  ignoreDependencies?: string[];
  ignoreExportsUsedInFile?: boolean | { 
    interface?: boolean; 
    typeAlias?: boolean 
  };
  usedClassMembers?: Array<string | { 
    extends?: string[]; 
    implements?: string[]; 
    members: string[] 
  }>;
  duplicates?: DuplicatesConfig;
}

Summary

Monomind's architecture is built on a modular, layered approach:

1. CLI Layer: User-facing command interface with subcommands for all major features
2. Core Layer: Shared orchestration logic and MCP protocol implementation
3. Capability Layer: Specialized systems for memory, knowledge graphs, and security
4. Agent Layer: Pluggable agent pool with WASM sandboxing support

The architecture supports horizontal scaling through agent pooling and vertical optimization through dedicated WASM runtime execution for sensitive operations.

Related Pages

Related topics: Architecture Overview

Core Packages

Monomind is organized as a monorepo with specialized packages that work together to provide AI coordination, memory management, neural learning, and multi-agent orchestration. The core packages form the foundation of this ecosystem, enabling Claude Code and other AI systems to maintain context, learn patterns, and coordinate complex tasks across sessions.

Architecture Overview

graph TD
    subgraph "Core Packages"
        CLI[@monomind/cli]
        MEM[@monomind/memory]
        HOOKS[@monomind/hooks]
        EMBED[@monomind/embeddings]
        NEURAL[@monomind/neural]
        SHARED[@monomind/shared]
    end
    
    CLI --> SHARED
    MEM --> EMBED
    HOOKS --> SHARED
    EMBED --> NEURAL
    NEURAL --> SHARED
    
    CLI --> MEM
    CLI --> HOOKS

The core packages follow a layered architecture where the shared package provides common utilities and types that all other packages depend on, while specialized packages handle specific concerns like memory storage, embedding generation, neural learning, and command execution.

@monomind/cli

The CLI package is the primary command-line interface for Monomind, providing a unified entry point for all operations. It serves as the orchestration layer that coordinates memory, hooks, neural learning, and multi-agent capabilities.

Command Structure

The CLI exposes commands organized by functional domain:

Sources: packages/@monomind/cli/README.md

CLAUDE.md Generation

The CLI includes a sophisticated CLAUDE.md generator that creates project-specific configuration files for Claude Code. The generator supports multiple templates with varying levels of detail:

export const CLAUDE_MD_TEMPLATES: Array<{ name: ClaudeMdTemplate; description: string }> = [
  { name: 'minimal', description: 'Quick start — behavioral rules, anti-drift' },
  { name: 'standard', description: 'Full documentation with all sections' },
  { name: 'full', description: 'Complete including hooks and learning' },
  { name: 'security', description: 'Security-focused template' },
  { name: 'performance', description: 'Performance-optimized template' },
  { name: 'solo', description: 'Single-agent workflow template' }
];

Each template includes different combinations of sections such as behavioral rules, coding principles, file organization, project architecture, build and test instructions, security rules, concurrency rules, swarm orchestration, and intelligence system configuration.

Sources: packages/@monomind/cli/src/init/claudemd-generator.ts

Session Management

The session command provides comprehensive session state management:

monomind session list      # List all saved sessions
monomind session save      # Save current session state
monomind session restore   # Restore a saved session
monomind session delete    # Delete a saved session
monomind session export    # Export session to file
monomind session import    # Import session from file
monomind session current   # Show current active session

Sources: packages/@monomind/cli/src/commands/session.ts

Agent Capabilities

The CLI supports multiple agent types, each with specialized capabilities:

Sources: packages/@monomind/cli/src/commands/agent.ts

MCP Server Management

monomind mcp start     # Start MCP server
monomind mcp stop      # Stop MCP server
monomind mcp status    # Show server status
monomind mcp health    # Check server health
monomind mcp restart   # Restart MCP server
monomind mcp tools     # List available tools
monomind mcp toggle    # Enable/disable tools
monomind mcp exec      # Execute a tool
monomind mcp logs      # Show server logs

Sources: packages/@monomind/cli/src/commands/mcp.ts

@monomind/memory

The memory package provides a sophisticated memory system for AI agents, combining structured storage with semantic vector search capabilities.

HybridBackend Architecture

The memory system uses a HybridBackend that combines SQLite for structured data with AgentDB for semantic search:

const backend = new HybridBackend({
  embeddingGenerator: async (text) => myEmbeddingModel.embed(text),
  // A-MEM auto-linking is automatically active when embeddingGenerator is set
});

Sources: packages/@monomind/memory/README.md

A-MEM Auto-Linking

When configured with an embedding generator, the HybridBackend implements A-MEM (arxiv:2409.11987) auto-linking. Every stored entry automatically discovers its top-3 semantic neighbors and creates bidirectional references edges, implementing the Zettelkasten note-linking structure.

Agent Memory Scopes

The memory system supports multiple scope levels for different use cases:

Memory Utilities

import {
  resolveAgentMemoryDir,  // Get scope directory path
  createAgentBridge,       // Create scoped AutoMemoryBridge
  transferKnowledge,       // Cross-agent knowledge sharing
  listAgentScopes,         // Discover existing agent scopes
} from '@monomind/memory';

// Resolve path for an agent scope
const dir = resolveAgentMemoryDir('my-agent', 'project');
// → /workspaces/my-project/.claude/agent-memory/my-agent/

// List all agent scopes in a directory
const scopes = await listAgentScopes('/workspaces/my-project');

Sources: packages/@monomind/memory/README.md

Memory Commands

monomind memory init         # Initialize memory database (sql.js)
monomind memory store        # Store data in memory
monomind memory edit         # Edit an entry
monomind memory retrieve     # Retrieve data from memory
monomind memory search       # Semantic/vector search
monomind memory list         # List memory entries
monomind memory delete       # Delete an entry
monomind memory templates    # Show best-practice entry templates
monomind memory stats        # Show statistics
monomind memory configure    # Configure backend
monomind memory cleanup      # Clean expired entries
monomind memory compress     # Compress database
monomind memory export       # Export memory to file
monomind memory import       # Import from file

Sources: packages/@monomind/cli/src/commands/memory.ts

@monomind/hooks

The hooks package provides an event-driven system for extending and customizing Monomind behavior.

Hook Configuration

Hooks are configured in monomind.config.json with support for both external scripts and built-in commands:

{
  "hooks": {
    "preCommand": "/path/to/pre-command-hook.sh",
    "postCommand": "/path/to/post-command-hook.sh"
  },
  "statusLine": {
    "type": "command",
    "command": "statusline"
  }
}

Sources: packages/@monomind/hooks/README.md

Hook Types

Package Dependencies

The hooks system depends on and integrates with:

• @monomind/shared - Shared utilities and types
• @monomind/neural - Neural network and SONA learning
• @monomind/swarm - Multi-agent coordination
• @monomind/memory - AgentDB memory system

Sources: packages/@monomind/hooks/README.md

@monomind/embeddings

The embeddings package provides embedding generation, caching, and transformation capabilities.

Features

Cache Configuration

const service = createEmbeddingService({
  provider: "openai",
  apiKey: process.env.OPENAI_API_KEY!,
  persistentCache: {
    enabled: true,
    dbPath: "./cache/embeddings.db",
    maxSize: 50000,
    ttlMs: 30 * 24 * 60 * 60 * 1000, // 30 days
  },
  normalization: "l2",
});

Embeddings CLI Commands

# Document chunking
monomind embeddings chunk document.txt --strategy sentence --max-size 512

# Normalize embedding file
monomind embeddings normalize embeddings.json --type l2 -o normalized.json

# Convert to hyperbolic
monomind embeddings hyperbolic embeddings.json -o poincare.json

# Neural operations
monomind embeddings neural drift --baseline "context" --input "check this"
monomind embeddings neural store --id mem-1 --content "data"
monomind embeddings neural recall "query" --top-k 5

# List/download models
monomind embeddings models list
monomind embeddings models download all-MiniLM-L6-v2

# Cache management
monomind embeddings cache stats
monomind embeddings cache clear --older-than 7d

Sources: packages/@monomind/embeddings/README.md

Related Packages

• @monomind/memory - HNSW indexing and vector storage
• @monomind/providers - Multi-LLM provider system
• @monomind/neural - SONA learning system

@monomind/aidefence

The aidefence package provides security and AI safety features for the Monomind ecosystem.

Capabilities

The package includes patterns for detecting and preventing various security issues and inappropriate AI behaviors. It integrates with the CLI for security scanning operations.

Related Packages

• @monomind/cli - CLI with security commands
• agentdb - HNSW vector database
• monomind - Full AI coordination system

Sources: packages/@monomind/aidefence/README.md

@monomind/shared

The shared package contains common utilities, types, and interfaces used across all Monomind packages.

Responsibilities

• Type definitions shared across packages
• Common utility functions
• Interface contracts for package integration
• Configuration schemas and validation

Dependencies

Other core packages depend on @monomind/shared for common functionality, ensuring consistent types and utilities across the ecosystem.

Package Relationships

graph TD
    CLI -->|depends on| SHARED
    MEM -->|depends on| SHARED
    HOOKS -->|depends on| SHARED
    EMBED -->|depends on| NEURAL
    NEURAL -->|depends on| SHARED
    
    CLI -->|coordinates| MEM
    CLI -->|coordinates| HOOKS
    CLI -->|uses| EMBED
    
    MEM -->|uses| EMBED
    
    subgraph "Core Packages"
        CLI[@monomind/cli]
        MEM[@monomind/memory]
        HOOKS[@monomind/hooks]
        EMBED[@monomind/embeddings]
        NEURAL[@monomind/neural]
        SHARED[@monomind/shared]
    end

Installation and Setup

# Clone the repository
git clone https://github.com/monoes/monomind.git
cd monomind

# Install dependencies
pnpm install

# Run health check and auto-fix
monomind doctor --fix

Development Workflow

The monorepo uses pnpm workspaces with the following structure:

monomind/
├── packages/
│   ├── @monomind/
│   │   ├── cli/
│   │   ├── memory/
│   │   ├── hooks/
│   │   ├── embeddings/
│   │   ├── neural/
│   │   ├── shared/
│   │   ├── aidefence/
│   │   └── ...
│   ├── plugins/
│   └── implementation/

Version Compatibility

The Monomind packages follow semantic versioning with alpha releases for new features. The current CLI version is @monomind/[email protected] (2026-01-07) with complete support for all core commands including session, task, config, memory, and workflow management.

Sources: packages/implementation/adrs/README.md

Related Pages

Related topics: Agent Routing System, Swarm Topologies

Agent Catalog

Overview

The Agent Catalog is a comprehensive system within Monomind that manages, organizes, and provides access to a diverse collection of specialized AI agents. It serves as the central registry and management hub for all agent types, capabilities, and configurations within the platform.

The catalog provides:

• A unified registry of agent types with their specific capabilities
• Dynamic agent management including creation, monitoring, and lifecycle control
• WASM-based sandboxed agent execution
• Worker dispatch and trigger configurations for autonomous task handling

Sources: packages/@monomind/cli/src/commands/agent.ts:1-50

Agent Types and Capabilities

Monomind's Agent Catalog defines multiple specialized agent types, each with distinct capabilities optimized for specific tasks.

Core Agent Types

Sources: packages/@monomind/cli/src/commands/agent.ts:45-80

Agent Commands

The CLI provides several commands for agent management:

monomind agent <subcommand>

Subcommands:
  metrics      - Show agent metrics
  pool         - Manage agent pool
  health       - Show agent health
  logs         - Show agent logs
  wasm-status  - Check WASM runtime availability
  wasm-create  - Create a WASM-sandboxed agent
  wasm-prompt  - Send a prompt to a WASM agent
  wasm-gallery - List WASM agent gallery templates

Sources: packages/@monomind/cli/src/commands/agent.ts:20-30

Agent Registry System

The Agent Registry is the core component that maintains agent definitions, configurations, and metadata.

Registry Architecture

graph TD
    A[Agent Request] --> B[Registry Builder]
    B --> C[Agent Registry]
    C --> D[Agent Type Resolution]
    D --> E[Managed Agent Instance]
    E --> F[Execution Context]
    F --> G[Response/Metrics]

Registry Builder

The RegistryBuilder class constructs and manages the agent registry, providing methods to register, retrieve, and manage agent configurations.

Key Responsibilities:

• Build agent registry from configuration sources
• Validate agent type definitions
• Provide lookup and discovery mechanisms
• Support dynamic agent registration

Sources: packages/@monomind/cli/src/agents/registry-builder.ts:1-50

Managed Agents

Managed Agents provide a structured runtime environment for agent execution with integrated lifecycle management, monitoring, and resource allocation.

Managed Agent Lifecycle

stateDiagram-v2
    [*] --> Initializing
    Initializing --> Ready: Initialization Complete
    Ready --> Running: Task Assigned
    Running --> Ready: Task Complete
    Running --> Paused: Suspend Request
    Paused --> Running: Resume Request
    Ready --> Terminated: Shutdown
    Running --> Terminated: Force Shutdown
    Terminated --> [*]

Agent Management Features

Sources: packages/@monomind/cli/src/agents/managed-agent.ts:1-60

WASM Agent Gallery

The WASM Agent system provides sandboxed agent execution using WebAssembly, offering enhanced security and portability.

WASM Agent Commands

# Check WASM runtime status
monomind agent wasm-status

# List available templates
monomind agent wasm-gallery

# Create a new WASM agent
monomind agent wasm-create -t <template-id>

# Send prompt to WASM agent
monomind agent wasm-prompt <agent-id> <prompt>

Gallery Template Structure

Templates in the gallery include:

• id: Unique template identifier
• name: Human-readable name
• category: Template category (coding, research, security, etc.)
• description: Brief description of capabilities
• version: Template version

interface WASMTemplate {
  id: string;
  name: string;
  category: string;
  description: string;
  version: string;
}

Sources: packages/@monomind/cli/src/commands/agent-wasm.ts:1-80

Worker Dispatch System

The Agent Catalog integrates with a worker dispatch system for autonomous task handling based on trigger patterns.

Trigger Categories

Trigger Configuration

const TRIGGER_CONFIGS = {
  ultralearn: {
    description: 'Deep knowledge acquisition and learning',
    priority: 'normal',
  },
  preload: {
    description: 'Resource preloading for faster access',
    priority: 'normal',
  },
  deepdive: {
    description: 'Thorough code analysis',
    priority: 'normal',
  },
  document: {
    description: 'Documentation generation',
    priority: 'low',
  },
  refactor: {
    description: 'Code refactoring suggestions',
    priority: 'normal',
  },
  benchmark: {
    description: 'Performance benchmarking',
    priority: 'normal',
  },
  testgaps: {
    description: 'Test coverage analysis',
    priority: 'normal',
  },
};

Sources: packages/@monomind/swarm/src/workers/worker-dispatch.ts:1-100

Agent Pool Management

The Agent Catalog supports managing pools of agents for scalable task processing.

Pool Operations

# View pool status
monomind agent pool status

# Scale pool
monomind agent pool scale <agent-type> <count>

# Release idle agents
monomind agent pool cleanup

Pool Configuration Options

Health Monitoring

Agents in the catalog are continuously monitored for health status.

Health Check Response

interface HealthCheckResponse {
  status: 'healthy' | 'degraded' | 'unhealthy';
  agentId: string;
  uptime: number;
  lastTask: string;
  metrics: {
    cpu: number;
    memory: number;
    tasksCompleted: number;
    errors: number;
  };
}

CLI Health Command

monomind agent health <agent-id>

CLI Integration

The Agent Catalog is accessible through the Monomind CLI with the following command structure:

monomind agent <command> [options]

Available Commands Summary

Sources: packages/@monomind/cli/src/commands/agent.ts:15-35

See Also

• Memory System - Vector memory and knowledge storage
• Hooks System - Intelligent automation hooks
• Monograph - Knowledge graph analysis
• Swarm Orchestration - Multi-agent coordination

Related Pages

Related topics: Agent Catalog, Swarm Topologies

Agent Routing System

Overview

The Agent Routing System is a core subsystem within Monomind that intelligently directs tasks to the most appropriate specialized agent based on task characteristics, agent capabilities, historical performance, and contextual information. It serves as the orchestration brain that enables multi-agent coordination across the entire platform.

The routing system operates with dual-mode intelligence:

• LLM-powered routing for complex task understanding: <2s response time
• Keyword-based fallback for rapid classification: <5ms response time

Sources: README.md

Architecture

The routing system follows a layered architecture that separates concerns between capability matching, route resolution, and intelligence fallback mechanisms.

graph TD
    A[Task Input] --> B[Route Layer]
    B --> C{Capability Index Match?}
    C -->|High Confidence| D[Direct Route]
    C -->|Low Confidence| E[LLM Fallback]
    C -->|Exact Match| F[Keyword Fallback]
    E --> G[Seraphine Routing Patterns]
    G --> H[Agent Spawn]
    D --> H
    F --> H

Core Components

Sources: packages/@monomind/routing/src/index.ts

Routing Pattern System

Seraphine Routing Patterns

The system defines comprehensive routing patterns through the SERAPHINE_ROUTING_PATTERNS array. Each pattern contains:

Sources: packages/@monomind/cli/src/transfer/models/seraphine.ts:15-80

Default Routing Patterns

Sources: packages/@monomind/cli/src/transfer/models/seraphine.ts:25-70

Capability Index

The Capability Index maintains a registry of all available agents and their documented capabilities, enabling efficient matching between incoming tasks and suitable agents.

Data Model

interface CapabilityEntry {
  agentType: string;
  capabilities: string[];
  specializations: string[];
  supportedLanguages: string[];
  framework: string;
  lastUpdated: Date;
}

Matching Algorithm

1. Exact Match: Task keywords directly match capability keywords
2. Fuzzy Match: LLM-based semantic similarity scoring
3. Fallback Match: Keyword-based pattern matching with reduced confidence

Sources: packages/@monomind/routing/src/capability-index.ts

LLM Fallback System

When the capability index cannot confidently match a task, the system escalates to LLM-powered routing. This module handles the fallback mechanism.

Configuration Parameters

Workflow

graph LR
    A[Task] --> B{Confidence >= Threshold?}
    B -->|Yes| C[Return Route]
    B -->|No| D[LLM Inference]
    D --> E{Result Valid?}
    E -->|Yes| F[Update Patterns]
    E -->|No| G[Keyword Fallback]
    F --> C
    G --> H[Default Agent]

Sources: packages/@monomind/routing/src/llm-fallback.ts

CLI Integration

Route Command

# Basic routing
monomind hooks route --task "fix bug"

# Q-Learning enhanced routing (requires ruvector)
monomind route "task" --q-learning

# Coverage-aware routing
monomind route "task" --coverage-aware

Guidance Commands

The guidance subsystem provides additional routing intelligence through CLI commands:

# Display guidance help
monomind guidance --help

# Show routing status
monomind guidance status

# Analyze task complexity
monomind guidance analyze --task "implement webhook retry logic"

Sources: packages/@monomind/cli/src/commands/guidance.ts

MCP Tools Integration

The routing system exposes functionality through the Model Context Protocol (MCP), enabling programmatic access for external integrations.

Available Tools

Usage Example

import { hooksMCPTools, getHooksTool } from '@monomind/hooks';

const routeTool = getHooksTool('hooks/route');
const result = await routeTool.handler({
  task: 'Implement user authentication',
  includeExplanation: true,
});

console.log(`Recommended agent: ${result.recommendedAgent}`);
console.log(`Confidence: ${result.confidence}%`);

Sources: packages/@monomind/cli/src/mcp-tools/guidance-tools.ts

Advanced Routing Features

Q-Learning Router (ruvector Integration)

For production environments requiring advanced routing decisions, the system integrates with ruvector for Q-learning-based agent selection:

• Learns from historical routing decisions
• Optimizes for task completion rate
• Adapts to team-specific patterns

Sources: packages/implementation/adrs/README.md

Coverage-Aware Routing

Routes tasks based on code coverage analysis, directing work to agents with relevant file expertise:

monomind route "task" --coverage-aware

AST Analysis Routing

For code modification tasks, the routing system can leverage AST (Abstract Syntax Tree) analysis to match agents with expertise in the relevant code structure:

monomind analyze ast src/

Sources: packages/implementation/adrs/README.md

Performance Characteristics

Sources: README.md

Extending the Routing System

Adding Custom Patterns

To extend routing capabilities, add new patterns to the Seraphine configuration:

import { SERAPHINE_ROUTING_PATTERNS } from './models/seraphine';

const customPattern: RoutingPattern = {
  id: 'route-custom-task',
  trigger: 'your-trigger-keywords',
  action: 'spawn your-agent',
  confidence: 0.85,
  usageCount: 0,
  successRate: 0.0,
  context: {
    category: 'custom',
    priority: 'medium',
  },
};

SERAPHINE_ROUTING_PATTERNS.push(customPattern);

Custom Capability Index

For specialized agent registries:

import { CapabilityIndex } from '@monomind/routing';

const customIndex = new CapabilityIndex({
  includeBuiltIn: true,
  customAgents: [...],
  scoringWeights: {
    keyword: 0.4,
    semantic: 0.4,
    historical: 0.2,
  },
});

Summary

The Agent Routing System provides intelligent, adaptive task-to-agent matching through a multi-tier architecture:

1. Capability Index for fast, accurate matching of known patterns
2. LLM Fallback for semantic understanding of novel tasks
3. Keyword Fallback for guaranteed routing with minimal latency
4. Seraphine Patterns for configurable, business-specific routing rules
5. MCP Integration for programmatic and external system access

This design ensures the routing system scales from simple keyword matching to complex semantic analysis while maintaining predictable performance characteristics.

Related Pages

Related topics: Consensus Protocols, Agent Catalog

Swarm Topologies

Overview

Swarm Topologies define the structural organization and communication patterns between agents in the Monomind multi-agent orchestration system. These topologies determine how agents connect, collaborate, share information, and coordinate tasks within a swarm.

The topology system provides flexible, pluggable architectures that can adapt to different task requirements—from simple linear workflows to complex hierarchical structures with consensus-based decision making.

Sources: packages/@monomind/swarm/src/topology-manager.ts

Architecture Overview

Core Topology Components

The swarm topology system consists of several interconnected components:

graph TD
    TM[Topology Manager] --> SH[Swarm Hub]
    TM --> TO[Task Orchestrator]
    TM --> AC[Attention Coordinator]
    TM --> UC[Unified Coordinator]
    
    SH --> CG[Communication Graph]
    SH --> FE[Flow Enforcer]
    
    TO --> Agents[Agent Pool]
    AC --> Memory[Memory System]
    UC --> Hooks[Hooks System]

Component Responsibilities

Sources: packages/@monomind/swarm/src/coordination/swarm-hub.ts Sources: packages/@monomind/swarm/src/coordination/task-orchestrator.ts

Topology Types

Linear Topology (Pipeline)

Agents are arranged in a sequential chain where output from one agent becomes input for the next. Best suited for tasks requiring strict sequential processing.

graph LR
    A[Agent 1] --> B[Agent 2]
    B --> C[Agent 3]
    C --> D[Agent 4]

Hierarchical Topology

Agents are organized in parent-child relationships with clear authority chains. Specialized sub-agents report to coordinator agents.

graph TD
    Root[Root Coordinator]
    Root --> C1[Coordinator 1]
    Root --> C2[Coordinator 2]
    C1 --> S1[Specialist 1.1]
    C1 --> S2[Specialist 1.2]
    C2 --> S3[Specialist 2.1]
    C2 --> S4[Specialist 2.2]

Mesh Topology

Agents can communicate directly with any other agent. Provides maximum flexibility but requires careful flow enforcement.

graph TD
    A[Agent A] <--> B[Agent B]
    A <--> C[Agent C]
    A <--> D[Agent D]
    B <--> C
    B <--> D
    C <--> D

Star Topology

A central coordinator agent mediates all communication. All other agents communicate exclusively through the hub.

graph TD
    Hub[Central Hub]
    Hub --> A[Agent A]
    Hub --> B[Agent B]
    Hub --> C[Agent C]
    Hub --> D[Agent D]

Hive-Mind Topology

Distributed consensus-based topology where agents share a collective decision-making mechanism. All agents contribute to decisions through weighted voting or consensus algorithms.

Sources: packages/implementation/adrs/README.md Sources: packages/@monomind/cli/src/commands/swarm.ts

Swarm Hub

The Swarm Hub serves as the central orchestration point for the swarm topology. It manages:

Communication Management

• Agent registration and deregistration
• Message routing between agents
• Broadcasting messages to agent groups
• Direct agent-to-agent communication channels

interface HubConfig {
  topology: TopologyType;
  maxAgents: number;
  communicationGraph: CommunicationGraph;
  flowEnforcer: FlowEnforcer;
}

Flow Enforcement

The Flow Enforcer component validates that communications follow the defined topology constraints:

interface FlowEnforcer {
  validateConnection(source: AgentId, target: AgentId): boolean;
  enforceDirection(agent: AgentId, direction: 'upstream' | 'downstream'): boolean;
  validateMessageFlow(message: Message): ValidationResult;
}

Sources: packages/@monomind/swarm/src/coordination/swarm-hub.ts Sources: packages/@monomind/cli/src/swarm/flow-enforcer.ts

Communication Graph

The Communication Graph tracks the relationships and communication patterns between agents within the topology.

Graph Structure

interface CommunicationNode {
  agentId: AgentId;
  role: AgentRole;
  connections: Connection[];
  metrics: AgentMetrics;
}

interface Connection {
  target: AgentId;
  type: ConnectionType; // 'direct' | 'mediated' | 'broadcast'
  weight: number;
  lastActivity: Timestamp;
}

Graph Operations

Sources: packages/@monomind/cli/src/swarm/communication-graph.ts

Task Orchestration

The Task Orchestrator distributes and manages tasks across the topology based on the current topology structure.

Task Distribution Strategies

Task Lifecycle

stateDiagram-v2
    [*] --> Pending: Task Created
    Pending --> Assigned: Orchestrator Routes
    Assigned --> InProgress: Agent Accepts
    InProgress --> Completed: Execution Done
    InProgress --> Blocked: Awaiting Dependencies
    Blocked --> InProgress: Dependencies Met
    Completed --> [*]

Sources: packages/@monomind/swarm/src/coordination/task-orchestrator.ts

Attention Coordinator

The Attention Coordinator manages agent focus and priority-based routing, ensuring efficient resource utilization across the topology.

Priority Management

Agents receive attention scores based on:

• Current task priority
• Agent specialization match
• Availability and load
• Historical performance metrics

interface AttentionMetrics {
  focusScore: number;
  priority: number;
  specializationMatch: number;
  availabilityScore: number;
  performanceHistory: number;
}

Sources: packages/@monomind/swarm/src/attention-coordinator.ts

Unified Coordinator

The Unified Coordinator provides a single interface for interacting with all topology components, simplifying complex swarm operations.

API Surface

interface UnifiedSwarmCoordinator {
  // Topology Management
  setTopology(type: TopologyType, config?: TopologyConfig): void;
  getTopology(): TopologyInfo;
  
  // Agent Management
  spawnAgent(type: AgentType, role?: AgentRole): AgentId;
  terminateAgent(agentId: AgentId): void;
  getActiveAgents(): AgentInfo[];
  
  // Communication
  sendMessage(from: AgentId, to: AgentId, message: Message): void;
  broadcast(from: AgentId, message: Message): void;
  
  // Task Management
  submitTask(task: Task): TaskId;
  getTaskStatus(taskId: TaskId): TaskStatus;
  cancelTask(taskId: TaskId): void;
  
  // Coordination
  achieveConsensus(agents: AgentId[], proposal: Proposal): ConsensusResult;
  delegateTask(task: Task, agent: AgentId): void;
}

Sources: packages/@monomind/swarm/src/unified-coordinator.ts

CLI Integration

The Monomind CLI provides commands for managing and visualizing swarm topologies:

Available Commands

# Initialize a swarm with specified topology
monomind swarm init --topology hierarchical

# Set topology type
monomind swarm topology set --type mesh

# Show current topology
monomind swarm topology show

# List agents in swarm
monomind swarm agents list

# View swarm status
monomind swarm status

# Initialize mesh topology
monomind swarm init mesh

# Spawn agent in swarm
monomind swarm agent spawn --type coder

Swarm Subcommands

Sources: packages/@monomind/cli/src/commands/swarm.ts

Configuration

Topology Configuration Options

interface TopologyConfig {
  type: TopologyType;
  
  // General settings
  maxAgents: number;
  agentTimeout: number;
  
  // Topology-specific settings
  mesh?: {
    maxConnectionsPerAgent: number;
    connectionStrategy: 'random' | 'specialized' | 'full';
  };
  
  hierarchical?: {
    maxChildrenPerCoordinator: number;
    delegationDepth: number;
  };
  
  hiveMind?: {
    consensusThreshold: number;
    votingPeriod: number;
    minParticipants: number;
  };
}

Initialization Options

interface SwarmInitOptions {
  topology: TopologyType;
  maxAgents?: number;
  defaultAgentType?: AgentType;
  enableConsensus?: boolean;
  communicationGraph?: {
    trackMetrics: boolean;
    retentionPeriod: number;
  };
  flowEnforcer?: {
    strictMode: boolean;
    allowedPatterns: CommunicationPattern[];
  };
}

Sources: packages/@monomind/swarm/src/topology-manager.ts

Best Practices

Topology Selection Guidelines

Performance Considerations

1. Mesh topologies offer maximum parallelism but increase coordination overhead
2. Hierarchical topologies reduce communication complexity but may create bottlenecks
3. Hive-Mind topologies ensure consistent decisions but require more round-trips
4. Star topologies provide clear authority but concentrate load on the hub

Flow Enforcement

Always enable the Flow Enforcer when using restricted topologies to prevent:

• Unauthorized agent-to-agent communication
• Circular dependencies
• Task routing violations
• Priority inversion attacks

Sources: packages/@monomind/cli/src/swarm/flow-enforcer.ts

Related Documentation

• Agent Management - Agent spawning and lifecycle
• Task Orchestration - Advanced task routing
• Memory System - Cross-agent memory sharing
• Hooks System - Event-driven coordination

Related Pages

Related topics: Swarm Topologies

Consensus Protocols

Overview

The Consensus Protocols module in Monomind provides a robust, multi-strategy approach to achieving agreement among distributed agents in a swarm coordination system. This module is critical for maintaining consistency, reliability, and fault tolerance when multiple autonomous agents must reach agreement on decisions, state changes, or leadership elections.

The consensus subsystem is architected to support three primary consensus paradigms, each optimized for different operational requirements and threat models:

Sources: packages/@monomind/swarm/src/consensus/index.ts

Architecture

The consensus module follows a layered architecture that separates protocol implementation from coordination logic. The UnifiedSwarmCoordinator acts as the primary consumer of consensus services, while individual protocol implementations handle the algorithmic specifics.

graph TD
    A[UnifiedSwarmCoordinator] --> B[ConsensusService]
    B --> C[RaftConsensus]
    B --> D[ByzantineConsensus]
    B --> E[GossipProtocol]
    
    F[CLI Audit Commands] --> G[AuditWriter]
    H[Vote Signing] --> I[VoteSigner]
    
    G --> B
    I --> C
    I --> D
    
    J[Network Transport] --> C
    J --> D
    J --> E

Core Interfaces

The consensus module exposes a unified interface through the main entry point:

// packages/@monomind/swarm/src/consensus/index.ts
export interface ConsensusProtocol {
  propose(value: ConsensusValue): Promise<ConsensusResult>;
  join(nodeId: string): Promise<void>;
  leave(nodeId: string): Promise<void>;
  getState(): ConsensusState;
  getMetrics(): ConsensusMetrics;
}

Sources: packages/@monomind/swarm/src/consensus/index.ts:1-50

Raft Consensus Implementation

The Raft implementation provides crash fault tolerance for leader election and log replication within the swarm. This protocol is selected by default when strong consistency is required without the overhead of Byzantine fault tolerance.

Leader Election

Raft in Monomind uses a three-state machine model: Follower, Candidate, and Leader. The election process is triggered when a follower node does not receive a heartbeat from the current leader within the election timeout.

stateDiagram-v2
    [*] --> Follower
    Follower --> Candidate : Election timeout
    Candidate --> Leader : Votes received (majority)
    Candidate --> Follower : Higher term discovered
    Leader --> Follower : Higher term discovered
    Follower --> Follower : Heartbeat received
    Candidate --> Candidate : Election timeout (re-election)

Log Replication

Once a leader is elected, it replicates log entries to followers using the proposeConsensus method exposed through the coordinator interface. Entries are committed only after receiving acknowledgment from a majority of nodes.

Sources: packages/@monomind/swarm/src/consensus/raft.ts

Byzantine Fault Tolerance

The Byzantine consensus implementation is designed for scenarios where agents may exhibit arbitrary or malicious behavior. This is particularly relevant in open multi-agent systems where not all participants can be trusted.

Byzantine Generals Problem

Byzantine consensus tolerates up to *f* faulty nodes in a system of *3f + 1* total nodes, making it suitable for security-critical swarm operations such as:

• Vote signing and verification
• Access control decisions
• Resource allocation agreements
• Cross-agent transaction validation

graph LR
    A[Propose] --> B[Pre-Prepare]
    B --> C[Prepare]
    C --> D[Commit]
    D --> E[Reply]
    
    F[F+1 Distinct Signatures] --> E

Sources: packages/@monomind/swarm/src/consensus/byzantine.ts

Gossip Protocol

The Gossip protocol provides eventual consistency with minimal coordination overhead. Unlike Raft and Byzantine consensus, gossip is designed for high-throughput scenarios where strict consistency is not required.

Message Propagation

Nodes periodically select random peers to exchange state information. Over time, the entire swarm converges to a consistent state through epidemic propagation.

Fan-Out Strategy

The gossip implementation uses an adaptive fan-out factor based on network conditions and swarm size, optimizing message delivery while minimizing redundant transmissions.

Sources: packages/@monomind/swarm/src/consensus/gossip.ts

CLI Integration

The Monomind CLI provides commands for managing and auditing consensus operations across the swarm.

Audit Writer

The audit-writer module enables operators to record and verify consensus decisions for compliance and debugging purposes.

# Record consensus decision
monomind consensus audit record --tx-id <transaction> --decision <choice>

# Export audit trail
monomind consensus audit export --format json --since 2024-01-01

Sources: packages/@monomind/cli/src/consensus/audit-writer.ts

Vote Signing

Vote signing provides cryptographic verification of consensus participation, ensuring that only authorized agents can influence swarm decisions.

# Sign a vote
monomind consensus vote sign --proposal <id> --node <node-id>

# Verify vote signatures
monomind consensus vote verify --proposal <id> --signatures <path>

Sources: packages/@monomind/cli/src/consensus/vote-signer.ts

Usage Patterns

Choosing the Right Protocol

Configuration Example

import { createConsensusService } from '@monomind/swarm';

const consensus = createConsensusService({
  protocol: 'raft',
  peers: ['agent-1:9001', 'agent-2:9001', 'agent-3:9001'],
  electionTimeout: 500,
  heartbeatInterval: 150,
});

// Propose a value
const result = await consensus.propose({
  type: 'leader_decision',
  value: { action: 'spawn_agent', config: agentConfig },
  timeout: 5000,
});

API Reference

ConsensusService

ConsensusResult

interface ConsensusResult {
  success: boolean;
  value?: unknown;
  quorum?: string[];
  term?: number;
  signature?: string;
  timestamp: number;
  latency: number;
}

Performance Targets

The consensus module is designed to meet the following performance benchmarks:

Sources: packages/@monomind/swarm/README.md Sources: packages/@monomind/swarm/src/consensus/index.ts

Related Documentation

• Swarm Coordination - Higher-level swarm management
• UnifiedSwarmCoordinator - Primary coordinator implementation
• CLI Commands - Command-line consensus tools

Related Pages

Related topics: Knowledge Graph (Monograph)

Memory System

The Memory System is a core component of Monomind that provides persistent, searchable storage for agent insights, patterns, and learned knowledge. It implements a hybrid architecture combining SQLite for structured data persistence with HNSW-based vector indexing for high-performance semantic search.

Overview

The Memory System serves as the long-term knowledge repository for the Monomind AI coordination platform. It enables agents to:

• Persist insights across sessions with confidence-weighted storage
• Search semantically using vector embeddings and HNSW indexing
• Link knowledge automatically using A-MEM auto-linking mechanisms
• Learn patterns through SONA neural integration
• Sync with files via AutoMemoryBridge for CLAUDE.md integration

Sources: packages/@monomind/memory/README.md

Architecture

graph TB
    subgraph "Memory System Architecture"
        AMB["AutoMemoryBridge"]
        
        subgraph "Backends"
            HB["HybridBackend"]
            AB["AgentDB Backend"]
            SB["SQLite Backend"]
            HNSW["HNSW Index"]
        end
        
        subgraph "Neural Integration"
            NL["Neural Learning"]
            PL["Pattern Learner"]
            SONA["SONA Integration"]
        end
        
        LB["LearningBridge"]
    end
    
    AMB --> HB
    HB --> AB
    HB --> SB
    HB --> HNSW
    LB --> NL
    LB --> PL
    NL --> SONA
    AMB --> LB

Component Overview

Sources: packages/@monomind/memory/src/hybrid-backend.ts

Backends

HybridBackend

The HybridBackend serves as the primary interface, combining structured storage with semantic search capabilities. It coordinates between AgentDB and SQLite backends while maintaining data consistency.

interface HybridBackendConfig {
  embeddingGenerator?: EmbeddingGenerator;
  storageDir?: string;
  enableAutoLinking?: boolean;
  maxAutoLinkReferences?: number;
}

Key Features:

• Automatic embedding generation for stored entries
• A-MEM auto-linking with configurable neighbor count
• Bidirectional reference management
• Cross-session persistence

Sources: packages/@monomind/memory/src/hybrid-backend.ts

AgentDB Backend

The AgentDB backend provides vector storage and semantic search capabilities using HNSW (Hierarchical Navigable Small World) indexing.

interface AgentDBConfig {
  dimension: number;
  storagePath?: string;
  m?: number;        // HNSW M parameter
  efConstruction?: number;
  efSearch?: number;
}

Performance Characteristics:

• 150x-12,500x faster than brute-force search
• Supports up to millions of vectors
• Configurable HNSW parameters for accuracy/speed tradeoffs

Sources: packages/@monomind/memory/src/agentdb-backend.ts

SQLite Backend

Provides structured data storage for metadata, configurations, and entries requiring relational queries.

interface SQLiteConfig {
  storagePath?: string;
  enableWAL?: boolean;
  cacheSize?: number;
}

Sources: packages/@monomind/memory/src/sqlite-backend.ts

SQL.js Backend

An in-browser compatible SQLite implementation using WebAssembly, useful for environments without native SQLite support.

interface SqlJsConfig {
  locateFile?: (file: string) => string;
  memoryGrowth?: boolean;
}

Sources: packages/@monomind/memory/src/sqljs-backend.ts

HNSW Index

The HNSW (Hierarchical Navigable Small World) index provides the core vector search functionality.

graph LR
    A["Query Vector"] --> B["Search Layer L"]
    B --> C["Search Layer L-1"]
    C --> D["Search Layer L-2"]
    D --> E["Bottom Layer"]
    E --> F["Results"]

Configuration Parameters

Sources: packages/@monomind/memory/src/hnsw-index.ts

AutoMemoryBridge

The AutoMemoryBridge synchronizes between the in-memory vector database and persistent markdown files for CLAUDE.md integration.

import { AutoMemoryBridge } from '@monomind/memory';

const bridge = new AutoMemoryBridge(memoryBackend, {
  workingDir: '/workspaces/my-project',
  syncMode: 'on-session-end',
  pruneStrategy: 'confidence-weighted',
});

Sync Modes

Sources: packages/@monomind/memory/README.md

Scope Directories

graph TD
    A["Agent Request"] --> B["Scope Selection"]
    B --> C1["project"]
    B --> C2["local"]
    B --> C3["user"]
    
    C1 --> D1["<gitRoot>/.claude/agent-memory/<agent>/"]
    C2 --> D2["<gitRoot>/.claude/agent-memory-local/<agent>/"]
    C3 --> D3["~/.claude/agent-memory/<agent>/"]

Sources: packages/@monomind/memory/README.md

Insight Categories

Sources: packages/@monomind/memory/README.md

Neural Learning Integration

Pattern Learning

The Pattern Learning system extracts and stores reusable patterns from agent interactions.

import { PatternLearner } from '@monomind/neural';

const learner = new PatternLearner({
  extractionThreshold: 0.7,
  consolidationWindow: 100,
});

Sources: packages/@monomind/neural/src/pattern-learner.ts

SONA Integration

SONA (Self-Optimizing Neural Adaptation) enables the memory system to learn from patterns and improve agent routing over time.

graph TD
    A["Memory Entry"] --> B["Pattern Extraction"]
    B --> C["SONA Weight Update"]
    C --> D["Agent Routing Optimization"]
    D --> E["Performance Metrics"]
    E --> B

Features:

• Pattern recognition improves agent routing
• Trajectory tracking identifies effective strategies
• Automatic model adaptation with <0.05ms overhead

Sources: packages/@monomind/neural/src/sona-integration.ts

LearningBridge

The LearningBridge connects the memory system with neural learning capabilities, enabling bidirectional flow of insights and learned patterns.

const bridge = new LearningBridge({
  memoryBackend: hybridBackend,
  neuralBackend: sonaBackend,
  syncInterval: 60000,
});

Sources: packages/@monomind/memory/src/learning-bridge.ts

Memory Operations

Store and Retrieve

// Store an insight
await bridge.recordInsight({
  category: 'debugging',
  summary: 'HNSW index requires initialization before search',
  source: 'agent:tester',
  confidence: 0.95,
});

// Semantic search
const results = await backend.search('HNSW initialization', { topK: 5 });

// Sync to files
await bridge.syncToAutoMemory();

Memory CLI Commands

Sources: packages/@monomind/cli/src/commands/memory.ts

A-MEM Auto-Linking

When HybridBackend is configured with an embeddingGenerator, every stored entry automatically discovers its top-3 semantic neighbors and creates bidirectional references edges—implementing the Zettelkasten note-linking structure.

const backend = new HybridBackend({
  embeddingGenerator: async (text) => myEmbeddingModel.embed(text),
  maxAutoLinkReferences: 3,
  enableAutoLinking: true,
});

Sources: packages/@monomind/memory/README.md

Quick Start

import { 
  AutoMemoryBridge,
  HybridBackend,
  createAgentBridge,
  resolveAgentMemoryDir,
} from '@monomind/memory';

// Create backend with embedding support
const backend = new HybridBackend({
  embeddingGenerator: async (text) => embeddings.embed(text),
});

// Create bridge for file sync
const bridge = new AutoMemoryBridge(backend, {
  workingDir: '/workspaces/my-project',
  syncMode: 'on-session-end',
});

// Record insights
await bridge.recordInsight({
  category: 'architecture',
  summary: 'Use HybridBackend for production workloads',
  confidence: 0.92,
});

// Sync to CLAUDE.md files
await bridge.syncToAutoMemory();

Sources: packages/@monomind/memory/src/index.ts

Related Packages

License

MIT License - see LICENSE for details.

Related Pages

Related topics: Memory System

Knowledge Graph (Monograph)

Monograph is the knowledge graph subsystem of Monomind, designed to build, maintain, and query a semantic dependency graph of your codebase, documentation, and PDFs. It serves as the foundational intelligence layer that automatically maps relationships between code symbols, documents, and concepts before every task execution.

Overview

Monograph creates a unified graph representation that captures both structural dependencies (imports, definitions) and semantic relationships (concepts, co-occurrences). This graph is automatically queried by hooks and slash commands, enabling agents to understand the codebase topology before making decisions.

graph TD
    A[Codebase + Docs + PDFs] --> B[Graph Builder]
    B --> C[Monograph Graph DB]
    C --> D[Query Engine]
    D --> E[monograph_suggest]
    D --> F[monograph_query]
    D --> G[monograph_god_nodes]
    E --> H[Claude Code Agent]
    F --> H
    G --> H

Sources: packages/@monomind/monograph/src/index.ts

Core Concepts

Graph Structure

The Monograph graph consists of two primary elements: nodes and edges.

#### Node Types

Sources: plugin/commands/monograph/README.md

#### Edge Types

Sources: plugin/commands/monograph/README.md

Graph Analysis Capabilities

Monograph provides several analysis modes for examining the codebase:

graph TD
    subgraph Analysis Modes
        A[reachability] --> A1[Upstream dependencies]
        A --> A2[Downstream dependents]
        B[hotspots] --> B1[High change frequency]
        B --> B2[Cyclomatic complexity]
        C[explain] --> C1[Dependency paths]
        C --> C2[Impact analysis]
    end

#### Reachability Analysis

Determines which files and symbols can reach or be reached from a given node. This is useful for understanding the blast radius of changes.

Sources: packages/@monomind/monograph/src/graph/reachability.ts

#### Hotspots Detection

Identifies high-complexity or frequently-changing areas of the codebase that may need attention.

Sources: packages/@monomind/monograph/src/graph/hotspots.ts

#### Explanation Engine

Provides natural language explanations of dependency paths and relationships between code elements.

Sources: packages/@monomind/monograph/src/graph/explain.ts

CLI Commands

The monomind monograph command provides the primary interface for building and querying the knowledge graph.

Command Reference

Sources: packages/@monomind/cli/src/commands/monograph.ts

Quick Start

# First-time build (code + all docs)
npx monomind monograph build

# Doc/wiki-focused build with Claude semantic extraction
npx monomind monograph wiki --llm

# Search
npx monomind monograph search -q "authentication flow"
npx monomind monograph search -q "pipeline" --mode semantic --label Section

# Stats
npx monomind monograph stats --top 20

# Auto-rebuild on changes
npx monomind monograph watch

Sources: plugin/commands/monograph/README.md

Search Modes

Sources: packages/@monomind/cli/src/commands/monograph.ts

MCP Tools

Monograph exposes tools via the Model Context Protocol for programmatic integration with Claude Code and other MCP-compatible clients.

Available Tools

Sources: packages/@monomind/cli/src/mcp-tools/monograph-tools.ts

Usage Example

// Using MCP tool in Claude Code
{
  tool: 'monograph_suggest',
  arguments: {
    query: "add webhook retry logic",
    role: "code"  // Optional: filter by role (code, test, docs)
  }
}

Graphify Tool

The monograph_graphify tool provides detailed graph analysis:

graph TD
    A[graphify request] --> B{role filter}
    B -->|unreachable| C[Dead code candidates]
    B -->|test| D[Test utilities]
    B -->|code| E[Source files]
    B -->|all| F[Complete graph]
    C --> G[Dependency stats]
    D --> G
    E --> G
    F --> G

Sources: packages/@monomind/cli/src/mcp-tools/monograph-tools.ts

Configuration

Monograph is configured via .monographrc.json in the project root.

Configuration Schema

interface MonographConfig {
  root: string;              // Project root directory
  entry: string[];           // Entry points for analysis
  ignore: string[];          // Patterns to exclude
  production: boolean;      // Enable production checks
  detection: string;        // Detection mode
  regression: {
    tolerance: number;
    baselinePath: string;
  };
  health: {
    cyclomaticThreshold: number;
    cognitiveThreshold: number;
    crapThreshold: number;
    minLines: number;
  };
  boundaries?: BoundaryConfig;  // Zone-based boundary rules
  plugins: string[];
}

Sources: packages/@monomind/monograph/src/config/types.ts

Boundary Configuration

Boundaries define architectural zones with allowed import rules:

{
  "zones": [
    {
      "name": "core",
      "patterns": ["src/core/**"],
      "allowedImports": ["src/utils/**"]
    }
  ]
}

Sources: packages/@monomind/cli/src/mcp-tools/monograph-tools.ts

Default Configuration

const DEFAULT_MONOGRAPH_CONFIG = {
  root: '.',
  entry: [],
  production: true,
  detection: 'default',
  project: undefined,
  ignore: [],
  overrides: [],
  regression: { tolerance: 0, baselinePath: '.monograph/regression-baseline.json' },
  audit: { gate: 'error', includeHealthGate: false },
  normalization: {
    stripComments: true,
    normalizeWhitespace: true,
    normalizeIdentifiers: false
  },
  boundaries: {},
  resolve: {
    paths: {},
    alias: {},
    conditions: [],
    extensions: ['.ts', '.tsx', '.mts', '.cts']
  },
  health: {
    cyclomaticThreshold: 10,
    cognitiveThreshold: 15,
    crapThreshold: 30,
    minLines: 5
  },
  ownership: { emailMode: 'fullEmail' },
  plugins: [],
};

Sources: packages/@monomind/monograph/src/config/types.ts

Pipeline Architecture

The Monograph pipeline processes code and documents through multiple stages:

graph LR
    A[Source Files] --> B[Parser]
    B --> C[AST Analysis]
    C --> D[Symbol Extractor]
    D --> E[Graph Builder]
    E --> F[Edge Resolver]
    F --> G[Graph Database]
    G --> H[Query Interface]
    
    I[Documents] --> J[Chunker]
    J --> K[Embedding Generator]
    K --> L[Vector Index]
    L --> G

Pipeline Runner

The pipeline runner orchestrates the graph construction process:

interface PipelineResult {
  nodes: number;      // Total nodes created
  edges: number;      // Total edges created
  duration: number;   // Processing time in ms
  errors: string[];   // Any processing errors
}

Sources: packages/@monomind/monograph/src/pipeline/runner.ts

Extraction Pipeline

The extraction pipeline handles both code symbols and documentation:

interface ExtractOptions {
  includeTypes: boolean;      // Include type definitions
  includeDocs: boolean;       // Include JSDoc comments
  includeConcepts: boolean;   // Extract semantic concepts
  useLLM: boolean;           // Use LLM for semantic extraction
}

Sources: packages/@monomind/graph/src/extract/index.ts

Graph Query Operations

monograph_query

Query specific relationships in the graph:

# Find what depends on UserService
monograph_query "UserService dependencies"

# Find files that define authentication
monograph_query "authentication" --label DEFINES

monograph_suggest

Get ranked file suggestions for a task:

# Find relevant files for a feature
monograph_suggest "add webhook retry logic"
# → returns ranked list with relevance scores

monograph_god_nodes

Identify high-centrality files (most connected in the graph):

# Find the most connected internal files
monograph_god_nodes
# → excludes external dependencies and test files

Sources: README.md

Integration with Intelligence System

Monograph integrates with Monomind's intelligence system to provide context-aware assistance:

graph TD
    A[User Task] --> B[Monograph Query]
    B --> C[Relevant Files]
    C --> D[SONA Learning]
    D --> E[Pattern Recognition]
    E --> F[Agent Routing]
    F --> G[Task Execution]
    G --> H[Trajectory Tracking]
    H --> D

Hooks Integration

Monograph tools are called automatically by hooks before task execution, ensuring agents always have relevant context.

Sources: README.md

Extended Configuration

Monograph supports extended configuration for advanced use cases:

interface ExtendedMonographConfig extends MonographConfig {
  extends?: string[];                    // Extend other configs
  sealed?: boolean;                       // Prevent further extension
  includeEntryExports?: boolean;         // Include entry point exports
  publicPackages?: string[];             // Public package boundaries
  dynamicallyLoaded?: string[];          // Dynamic import patterns
  codeowners?: string;                   // CODEOWNERS file path
  ignoreDependencies?: string[];         // Ignore certain imports
  ignoreExportsUsedInFile?: boolean | {
    interface?: boolean;
    typeAlias?: boolean;
  };
  usedClassMembers?: Array<string | {
    extends?: string[];
    implements?: string[];
    members: string[];
  }>;
}

Sources: packages/@monomind/monograph/src/config/types.ts

Health Checks

Monograph includes code health analysis capabilities:

Sources: packages/@monomind/monograph/src/config/types.ts

CLI vs MCP Usage

Sources: plugin/commands/monograph/README.md

See Also

• memory — Vector memory storage (separate from graph)
• hooks intelligence — Pattern learning
• CLAUDE.md Knowledge Graph section — workflow guidance for multi-file tasks

Doramagic Pitfall Log

Doramagic extracted 15 source-linked risk signals. Review them before installing or handing real data to the project.

1. Installation risk: v1.10.0 — Full Paperclip Port: 55 New Mastermind Skills

• Severity: medium
• Finding: Installation risk is backed by a source signal: v1.10.0 — Full Paperclip Port: 55 New Mastermind Skills. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/monoes/monomind/releases/tag/v1.10.0

2. Installation risk: v1.6.8

• Severity: medium
• Finding: Installation risk is backed by a source signal: v1.6.8. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/monoes/monomind/releases/tag/v1.6.8

3. Installation risk: v1.9.12 — mastermind:idea pipeline hardening

• Severity: medium
• Finding: Installation risk is backed by a source signal: v1.9.12 — mastermind:idea pipeline hardening. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/monoes/monomind/releases/tag/v1.9.12

4. Installation risk: v1.9.13 — fix: monograph never installed (workspace:* dep)

• Severity: medium
• Finding: Installation risk is backed by a source signal: v1.9.13 — fix: monograph never installed (workspace:* dep). Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/monoes/monomind/releases/tag/v1.9.13

5. Installation risk: v1.9.2 — mastermind:master hardening

• Severity: medium
• Finding: Installation risk is backed by a source signal: v1.9.2 — mastermind:master hardening. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/monoes/monomind/releases/tag/v1.9.2

6. Configuration risk: Configuration risk needs validation

• Severity: medium
• Finding: Configuration risk is backed by a source signal: Configuration risk needs validation. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.host_targets | github_repo:1221944165 | https://github.com/monoes/monomind | host_targets=mcp_host, claude, claude_code

7. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | github_repo:1221944165 | https://github.com/monoes/monomind | README/documentation is current enough for a first validation pass.

8. Maintenance risk: v1.9.1 — Init wipe-and-replace for managed Claude assets

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: v1.9.1 — Init wipe-and-replace for managed Claude assets. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/monoes/monomind/releases/tag/v1.9.1

9. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1221944165 | https://github.com/monoes/monomind | last_activity_observed missing

10. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | github_repo:1221944165 | https://github.com/monoes/monomind | no_demo; severity=medium

11. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.scoring_risks | github_repo:1221944165 | https://github.com/monoes/monomind | no_demo; severity=medium

12. Security or permission risk: Monomind v1.8.0 — Monograph, Mastermind & Security Hardening

• Severity: medium
• Finding: Security or permission risk is backed by a source signal: Monomind v1.8.0 — Monograph, Mastermind & Security Hardening. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/monoes/monomind/releases/tag/v1.8.0

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using monomind with real data or production workflows.

• v1.10.0 — Full Paperclip Port: 55 New Mastermind Skills - github / github_release
• v1.9.13 — fix: monograph never installed (workspace:* dep) - github / github_release
• v1.9.12 — mastermind:idea pipeline hardening - github / github_release
• v1.9.11 — mastermind:idea board name corruption fix - github / github_release
• v1.9.2 — mastermind:master hardening - github / github_release
• v1.9.1 — Init wipe-and-replace for managed Claude assets - github / github_release
• Monomind v1.9.0 - github / github_release
• Monomind v1.8.0 — Monograph, Mastermind & Security Hardening - github / github_release
• v1.6.8 - github / github_release
• Configuration risk needs validation - GitHub / issue