Skip to main content

​
Mental Analyzer API

The Mental Analyzer integrates with @mentalmodel/cli to provide semantic understanding of your codebase. It goes beyond file structure and tool sequences to capture what exists (domains), what it does (capabilities), how it’s governed (aspects), and why decisions were made (decisions).

​
Overview

Mental model provides four key layers of codebase understanding:
  • Domains: Core entities (User, Order, Payment)
  • Capabilities: Actions/verbs (Checkout, ProcessPayment)
  • Aspects: Cross-cutting concerns (Auth, Validation)
  • Decisions: Architecture decisions with rationale
Auto-Skill uses this semantic layer to suggest more context-aware skills.

​
Functions

​
createMentalAnalyzer

Create a Mental model analyzer. The Mental model provides semantic understanding that goes beyond file structure and tool sequences. It captures what exists (domains), what it does (capabilities), how it is governed (aspects), and why decisions were made (decisions). 
function createMentalAnalyzer(projectPath?: string): {
  isMentalAvailable(): boolean;
  loadModel(): MentalModel | null;
  getRelevantDomains(filePaths: string[]): MentalDomain[];
  getCapabilitiesForDomains(domains: MentalDomain[]): MentalCapability[];
  suggestSkillsForCapability(capability: MentalCapability): SkillHint[];
  getAspectsForCapability(capability: MentalCapability): MentalAspect[];
  getDecisionsForDomain(domain: MentalDomain): MentalDecision[];
  toDict(): Record<string, unknown>;
}
​
projectPath
string
Path to project with Mental model. Defaults to current working directory.
Returns: Analyzer object exposing Mental model queries

​
Example

import { createMentalAnalyzer } from "auto-skill/core/mental-analyzer";

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

if (!analyzer.isMentalAvailable()) {
  console.log("mental CLI not installed");
  process.exit(1);
}

// Load the Mental model
const model = analyzer.loadModel();
if (!model) {
  console.log("Failed to load Mental model");
  process.exit(1);
}

// Find relevant domains based on file paths
const domains = analyzer.getRelevantDomains([
  "src/payment/processor.ts",
  "src/payment/refund.ts"
]);

// Get capabilities that operate on these domains
const capabilities = analyzer.getCapabilitiesForDomains(domains);

// Suggest skills for each capability
for (const cap of capabilities) {
  const hints = analyzer.suggestSkillsForCapability(cap);
  console.log(`${cap.name}: ${hints.map(h => h.name).join(", ")}`);
}

​
Methods

The object returned by createMentalAnalyzer has the following methods:

​
isMentalAvailable

Check if the mental CLI is installed and accessible. 
function isMentalAvailable(): boolean
Returns: boolean - True if mental command is available

​
loadModel

Load Mental model from project using mental show --json. 
function loadModel(): MentalModel | null
Returns: MentalModel | null - Parsed Mental model or null if unavailable/failed

​
getRelevantDomains

Get domains relevant to given file paths. Uses a simple heuristic: matches domain names in file paths (case-insensitive). 
function getRelevantDomains(filePaths: string[]): MentalDomain[]
​
filePaths
string[]
required
List of file paths from tool calls
Returns: MentalDomain[] - List of relevant domains

​
getCapabilitiesForDomains

Get capabilities that operate on given domains. 
function getCapabilitiesForDomains(
  domains: MentalDomain[]
): MentalCapability[]
​
domains
MentalDomain[]
required
Domains to find capabilities for
Returns: MentalCapability[] - Capabilities operating on these domains

​
suggestSkillsForCapability

Suggest potential skills for a capability using keyword matching. 
function suggestSkillsForCapability(
  capability: MentalCapability
): SkillHint[]
​
capability
MentalCapability
required
Capability to suggest skills for
Returns: SkillHint[] - List of skill hints with metadata

​
Built-in Keyword Mappings

KeywordSuggested Skills
checkoutpayment-processing, cart-management, order-validation
paymentstripe-integration, payment-retry, refund-processing
authjwt-validation, oauth-flow, session-management
notificationemail-sending, push-notifications, sms-gateway
searchelasticsearch-query, full-text-search, faceted-search
uploadfile-upload, image-processing, s3-upload
exportcsv-export, pdf-generation, report-builder
importcsv-import, data-validation, bulk-insert
syncdata-sync, webhook-handler, event-bus

​
getAspectsForCapability

Get aspects (cross-cutting concerns) that apply to a capability. 
function getAspectsForCapability(
  capability: MentalCapability
): MentalAspect[]
​
capability
MentalCapability
required
Capability to find aspects for
Returns: MentalAspect[] - Applicable aspects

​
getDecisionsForDomain

Get architecture decisions related to a domain. 
function getDecisionsForDomain(
  domain: MentalDomain
): MentalDecision[]
​
domain
MentalDomain
required
Domain to find decisions for
Returns: MentalDecision[] - Related decisions

​
toDict

Convert loaded Mental model to a plain dictionary. 
function toDict(): Record<string, unknown>
Returns: Record<string, unknown> - Mental model as plain object (empty if not loaded)

​
Types

​
MentalModel

Complete Mental model of the codebase. 
interface MentalModel {
  domains: MentalDomain[];
  capabilities: MentalCapability[];
  aspects: MentalAspect[];
  decisions: MentalDecision[];
}

​
MentalDomain

A domain from Mental model (core entity). 
interface MentalDomain {
  name: string;
  description: string;
  refs: string[];
}
​
name
string
required
Domain name (e.g., “User”, “Payment”)
​
description
string
required
Description of what this domain represents
​
refs
string[]
required
File paths or identifiers that reference this domain

​
MentalCapability

A capability from Mental model (action/verb). 
interface MentalCapability {
  name: string;
  description: string;
  operatesOn: string[];
}
​
name
string
required
Capability name (e.g., “ProcessPayment”, “SendNotification”)
​
description
string
required
Description of what this capability does
​
operatesOn
string[]
required
Domain names this capability operates on

​
MentalAspect

A cross-cutting aspect from Mental model. 
interface MentalAspect {
  name: string;
  description: string;
  appliesTo: string[];
}
​
name
string
required
Aspect name (e.g., “Authentication”, “Validation”)
​
description
string
required
Description of this cross-cutting concern
​
appliesTo
string[]
required
Capability names this aspect applies to

​
MentalDecision

An architecture decision from Mental model. 
interface MentalDecision {
  id: string;
  what: string;
  why: string;
  relatesTo: string[];
  docs: string[];
}
​
id
string
required
Decision identifier
​
what
string
required
What decision was made
​
why
string
required
Rationale for the decision
​
relatesTo
string[]
required
References to related domains/capabilities (e.g., “domain:Payment”)
​
docs
string[]
required
Links to related documentation

​
SkillHint

A skill suggestion hint derived from a capability. 
interface SkillHint {
  name: string;
  source: string;
  capability: string;
  confidence: number;
}
​
name
string
required
Suggested skill name (kebab-case)
​
source
string
required
Source of the hint (always “mental-hint”)
​
capability
string
required
Capability name this hint is derived from
​
confidence
number
required
Confidence score (currently always 0.6)

​
Installation

To use the Mental Analyzer, you need to install the @mentalmodel/cli package: 
npm install -g @mentalmodel/cli
Then initialize Mental model in your project: 
cd /path/to/project
mental init
mental analyze

​
Integration with Auto-Skill

The Mental Analyzer enhances Auto-Skill’s pattern detection by:
  1. Providing semantic context for detected patterns
  2. Suggesting skills based on codebase capabilities
  3. Enriching skill metadata with domain and capability information
  4. Guiding skill naming based on domain vocabulary
When Mental model is available, Auto-Skill automatically uses it to improve skill generation quality.

Build docs developers (and LLMs) love

Get started for freeTalk to us