Mental Model Integration

Auto-Skill integrates with @mentalmodel/cli to provide semantic understanding of your codebase beyond file structure and tool sequences.

What is Mental Model?

Mental Model is a tool that captures the semantic architecture of your codebase:

Domains

What existsCore entities like User, Order, Payment

Capabilities

What it doesActions like Checkout, ProcessPayment, SendNotification

Aspects

How it’s governedCross-cutting concerns like Auth, Validation, Logging

Decisions

Why decisions were madeArchitecture decisions with rationale and context

Installation

Install @mentalmodel/cli

npm install -g @mentalmodel/cli

# Verify installation
mental --version

Auto-Skill automatically detects if mental is available and gracefully degrades if not installed.

Mental Analyzer API

Auto-Skill provides a Mental Model analyzer:

Mental Analyzer

import { createMentalAnalyzer } from '@matrixy/auto-skill';

const analyzer = createMentalAnalyzer('/path/to/project');

// Check if Mental CLI is available
if (analyzer.isMentalAvailable()) {
  // Load the Mental Model
  const model = analyzer.loadModel();
  console.log(model);
  // {
  //   domains: [...],
  //   capabilities: [...],
  //   aspects: [...],
  //   decisions: [...]
  // }
}

Mental Model Structure

Domains
Capabilities
Aspects
Decisions

Core entities and their file references:

MentalDomain

interface MentalDomain {
  name: string;          // e.g., 'User'
  description: string;   // 'User account and profile management'
  refs: string[];        // ['src/models/user.ts', 'src/api/users.ts']
}

Example:

{
  "name": "Order",
  "description": "E-commerce order processing and fulfillment",
  "refs": [
    "src/models/order.ts",
    "src/services/order-service.ts",
    "src/api/orders.ts"
  ]
}

Actions that operate on domains:

MentalCapability

interface MentalCapability {
  name: string;          // e.g., 'ProcessPayment'
  description: string;   // 'Handle payment transactions via Stripe'
  operatesOn: string[];  // ['Order', 'Payment']
}

Example:

{
  "name": "Checkout",
  "description": "Complete order checkout and payment",
  "operatesOn": ["Cart", "Order", "Payment", "Inventory"]
}

Cross-cutting concerns:

MentalAspect

interface MentalAspect {
  name: string;          // e.g., 'Authentication'
  description: string;   // 'JWT-based auth with refresh tokens'
  appliesTo: string[];   // ['CreateOrder', 'UpdateProfile']
}

Example:

{
  "name": "Validation",
  "description": "Input validation using Zod schemas",
  "appliesTo": ["CreateUser", "CreateOrder", "ProcessPayment"]
}

Architecture decisions with rationale:

MentalDecision

interface MentalDecision {
  id: string;            // e.g., 'ADR-001'
  what: string;          // 'Use PostgreSQL for transactional data'
  why: string;           // 'ACID guarantees for payment processing'
  relatesTo: string[];   // ['domain:Order', 'domain:Payment']
  docs: string[];        // ['docs/adr/001-database.md']
}

Example:

{
  "id": "ADR-003",
  "what": "Microservices architecture with event-driven communication",
  "why": "Enable independent scaling and deployment of services",
  "relatesTo": ["domain:Order", "domain:Inventory", "domain:Shipping"],
  "docs": ["docs/adr/003-microservices.md"]
}

Using Mental Context

Auto-Skill uses Mental Model to enhance pattern detection:

Detect Relevant Domains

When a pattern is detected, find domains related to the files involved:

const filePaths = [
  'src/models/order.ts',
  'src/services/payment-service.ts'
];

const domains = analyzer.getRelevantDomains(filePaths);
console.log(domains);
// [{ name: 'Order', ... }, { name: 'Payment', ... }]

Find Capabilities

Discover what capabilities operate on these domains:

const capabilities = analyzer.getCapabilitiesForDomains(domains);
console.log(capabilities);
// [
//   { name: 'ProcessPayment', operatesOn: ['Order', 'Payment'] },
//   { name: 'RefundOrder', operatesOn: ['Order', 'Payment'] }
// ]

Suggest Skills

Generate skill suggestions based on capabilities:

const hints = analyzer.suggestSkillsForCapability(capabilities[0]);
console.log(hints);
// [
//   { name: 'stripe-integration', source: 'mental-hint', confidence: 0.6 },
//   { name: 'payment-retry', source: 'mental-hint', confidence: 0.6 }
// ]

Enrich Pattern Metadata

Attach Mental context to detected patterns:

pattern.mentalContext = {
  domains: domains.map(d => d.name),
  capabilities: capabilities.map(c => c.name),
  aspects: analyzer.getAspectsForCapability(capabilities[0]),
  decisions: analyzer.getDecisionsForDomain(domains[0])
};

Skill Hint Keywords

Auto-Skill maps capability keywords to suggested skills:

Skill Hints Map

const SKILL_HINTS: Record<string, string[]> = {
  checkout: ['payment-processing', 'cart-management', 'order-validation'],
  payment: ['stripe-integration', 'payment-retry', 'refund-processing'],
  auth: ['jwt-validation', 'oauth-flow', 'session-management'],
  notification: ['email-sending', 'push-notifications', 'sms-gateway'],
  search: ['elasticsearch-query', 'full-text-search', 'faceted-search'],
  upload: ['file-upload', 'image-processing', 's3-upload'],
  export: ['csv-export', 'pdf-generation', 'report-builder'],
  import: ['csv-import', 'data-validation', 'bulk-insert'],
  sync: ['data-sync', 'webhook-handler', 'event-bus']
};

Example matching:

const capability = { name: 'ProcessPayment', ... };
const hints = analyzer.suggestSkillsForCapability(capability);

// Matches keyword 'payment' in capability name
// Returns: ['stripe-integration', 'payment-retry', 'refund-processing']

Mental-Enhanced Pattern Detection

When Mental Model is available, patterns include semantic context:

{
  "id": "abc123",
  "toolSequence": ["Read", "Edit", "Bash"],
  "suggestedName": "read-and-run",
  "description": "Workflow pattern: Read, Edit, Bash",
  "confidence": 0.85,
  "mentalContext": null
}

Proactive Discovery with Mental Model

Mental context powers smarter skill recommendations:

Mental-Enhanced Recommendations

import {
  createMentalAnalyzer,
  createExternalSkillLoader,
  createSkillRecommendationEngine
} from '@matrixy/auto-skill';

const analyzer = createMentalAnalyzer();
const loader = createExternalSkillLoader();
const engine = createSkillRecommendationEngine(loader);

await loader.start();

// Detect pattern with Mental context
const pattern = {
  toolSequence: ['Read', 'Edit', 'Bash'],
  mentalContext: {
    capabilities: ['ProcessPayment']
  }
};

// Get recommendations
const recommendations = await engine.recommendForPattern(pattern);

// Mental context influences search queries:
// - Searches for 'payment' skills
// - Boosts results matching Stripe (from decisions)
// - Filters by validation aspect

console.log(recommendations);
// [
//   {
//     type: 'external',
//     externalSkill: {
//       title: 'Stripe Payment Integration',
//       matchReason: 'Matches capability: ProcessPayment',
//       confidence: 0.9
//     }
//   }
// ]

await loader.stop();

Mental Model CLI

Create and manage Mental Models using the CLI:

Initialize
Define Domains
Define Capabilities
View Model

# Create .mental/mental.yml
mental init

mental add domain User "User accounts and authentication"
mental add domain Order "Order processing and fulfillment"
mental add domain Payment "Payment transactions"

mental add capability ProcessPayment "Handle Stripe payments" --operates-on Order,Payment
mental add capability Checkout "Complete order checkout" --operates-on Cart,Order,Payment

# Human-readable output
mental show

# JSON output for tools
mental show --json

Benefits of Mental Model Integration

Semantic Skill Matching

Match patterns to skills based on intent rather than just tool sequences.Without Mental Model:

Pattern: [Read, Edit, Bash]
Suggestion: Generic “read-and-run” skill

With Mental Model:

Pattern: [Read, Edit, Bash] + Capability: ProcessPayment
Suggestion: “stripe-integration” skill from community

Context-Aware Recommendations

Recommendations consider:

Which domains are involved
What capabilities are being performed
What aspects apply (auth, validation, etc.)
Why decisions were made (ADRs)

Skill Discovery Hints

Mental Model suggests what skills might exist before you even search:

// Detect you're working on email notifications
const capability = { name: 'SendWelcomeEmail', operatesOn: ['User'] };

// Auto-Skill suggests searching for:
// - email-sending
// - notification-service
// - sendgrid-integration

Architecture Decision Context

Skills can reference architecture decisions:

SKILL.md

---
name: stripe-payment-processing
description: Process payments using Stripe API
relates_to:
  - ADR-005: Use Stripe for payment processing
---

This skill implements the payment processing workflow
following our architecture decision to use Stripe (ADR-005).

Limitations

Mental Model integration is optional and gracefully degrades:

If mental CLI is not installed, isMentalAvailable() returns false
If .mental/mental.yml doesn’t exist, loadModel() returns null
Pattern detection works fine without Mental Model, just with less semantic context

Example: Full Integration

Complete Mental + Auto-Skill Workflow

import {
  createMentalAnalyzer,
  createPatternDetector,
  createEventStore,
  createExternalSkillLoader,
  createSkillRecommendationEngine
} from '@matrixy/auto-skill';

// 1. Load Mental Model
const analyzer = createMentalAnalyzer('/path/to/project');
const model = analyzer.loadModel();

if (model) {
  console.log('Mental Model loaded:', model.domains.length, 'domains');
}

// 2. Detect patterns from events
const store = createEventStore();
const detector = createPatternDetector();
const sessions = store.getRecentSessions(7);
const patterns = detector.detectPatterns(sessions);

// 3. Enhance patterns with Mental context
for (const pattern of patterns) {
  // Extract file paths from tool events
  const filePaths = extractFilePathsFromPattern(pattern);
  
  // Find relevant domains
  const domains = analyzer.getRelevantDomains(filePaths);
  
  // Find capabilities
  const capabilities = analyzer.getCapabilitiesForDomains(domains);
  
  // Suggest skills
  const hints = capabilities.flatMap(cap =>
    analyzer.suggestSkillsForCapability(cap)
  );
  
  // Attach to pattern
  pattern.mentalContext = {
    domains: domains.map(d => d.name),
    capabilities: capabilities.map(c => c.name),
    suggestedSkills: hints.map(h => h.name)
  };
}

// 4. Get external skill recommendations
const loader = createExternalSkillLoader();
const engine = createSkillRecommendationEngine(loader);

await loader.start();

for (const pattern of patterns) {
  const recommendations = await engine.recommendForPattern(pattern);
  console.log(`Pattern: ${pattern.suggestedName}`);
  console.log(`Mental context: ${pattern.mentalContext?.capabilities}`);
  console.log(`Recommendations:`, recommendations.map(r => r.externalSkill?.title));
}

await loader.stop();

Next Steps

Skill Providers

Learn how Mental hints feed into skill discovery

Configuration

Configure Mental Model integration settings

@mentalmodel/cli

Official Mental Model CLI documentation

Get Started

Core Modules

Features

CLI Reference

Guides

Mental Model Integration

What is Mental Model?

Domains

Capabilities

Aspects

Decisions

Installation

Mental Analyzer API

Mental Model Structure

Using Mental Context

Skill Hint Keywords

Mental-Enhanced Pattern Detection

Proactive Discovery with Mental Model

Mental Model CLI

Benefits of Mental Model Integration

Limitations

Example: Full Integration

Next Steps

Skill Providers

Configuration

@mentalmodel/cli

Build docs developers (and LLMs) love

Get Started

Core Modules

Features

CLI Reference

Guides

​What is Mental Model?

Domains

Capabilities

Aspects

Decisions

​Installation

​Mental Analyzer API

​Mental Model Structure

​Using Mental Context

​Skill Hint Keywords

​Mental-Enhanced Pattern Detection

​Proactive Discovery with Mental Model

​Mental Model CLI

​Benefits of Mental Model Integration

​Limitations

​Example: Full Integration

​Next Steps

Skill Providers

Configuration

@mentalmodel/cli

Build docs developers (and LLMs) love

What is Mental Model?

Installation

Mental Analyzer API

Mental Model Structure

Using Mental Context

Skill Hint Keywords

Mental-Enhanced Pattern Detection

Proactive Discovery with Mental Model

Mental Model CLI

Benefits of Mental Model Integration

Limitations

Example: Full Integration

Next Steps