"You can't really know anything if you just remember isolated facts and try and bang 'em back. If the facts don't hang together on a latticework of theory, you don't have them in a usable form."
An open-source, multidisciplinary knowledge base and decision-support system synthesizing foundational models across physics, evolutionary biology, economics, cognitive psychology, operations research, and mathematics.
Designed from first principles to serve both human decision-makers and autonomous AI agents without fragmentation.
flowchart TD
subgraph Truth ["1. Core Truth (Single Source)"]
M["models/**/*.md\n(Rigorous Markdown + YAML Frontmatter)"]
end
subgraph Tooling ["Tooling & Interface Layer"]
CLI["CLI Interface (cli/mm)\nFast terminal lookup & diagnosis"]
AGENT["AI Skill & MCP Server\n(skills/ & mcp/)\nChain-of-thought protocols"]
GRAPH["Interactive Knowledge Graph\n(docs/graph.html)\nD3.js & Obsidian Wikilinks"]
ANKI["Spaced Repetition (Anki)\n(scripts/export_anki.py)\nAutomated flashcard decks"]
MATRIX["Problem-to-Model Matrix\nActionable decision playbooks"]
end
subgraph Users ["End Beneficiaries"]
H["Human Decision Makers\n(Engineers, Founders, Leaders)"]
AI["Autonomous AI Agents\n(Antigravity, Claude, Cursor)"]
K["Knowledge Graphs\n(Obsidian, Logseq)"]
end
M --> CLI --> H
M --> MATRIX --> H
M --> AGENT --> AI
M --> GRAPH --> K & H
M --> ANKI --> H
Every model file contains a field-tested Diagnostic Checklist and Real-World Case Studies (Technology, Business, High-Stakes Decisions). When facing a dilemma, consult the matrix below:
| If You Are Facing... | Consult Primary Model | Complementary Pair | Counter-Balance |
|---|---|---|---|
| Deleting or refactoring legacy systems | [[Chesterton's Fence]] | [[First-Principles Thinking]] | [[Second-Order Thinking]] |
| Big-bang rewrites vs incremental evolution | [[Gall's Law]] | [[Theory of Constraints]] | [[Chesterton's Fence]] |
| High-stakes risk with asymmetric downside | [[Ergodicity & Absorbing Barriers]] | [[Inversion]] | [[Margin of Safety]] |
| Runaway positive or negative spirals | [[Feedback Loops]] | [[Network Effects]] | [[Theory of Constraints]] |
| Prioritizing roadmap or capital allocation | [[Opportunity Cost]] | [[Expected Value]] | [[Comparative Advantage]] |
| Resource allocation across fat tails | [[Power Laws & The Pareto Principle]] | [[Asymmetric Payoffs]] | [[Theory of Constraints]] |
| Slow organizational delivery & backlogs | [[Theory of Constraints]] | [[Feedback Loops]] | [[Leverage]] |
| Interpersonal friction or vendor breakages | [[Hanlon's Razor]] | [[Occam's Razor]] | [[Proximate vs Root Cause]] |
| Rapid competitor adaptation or arms race | [[The Red Queen Effect]] | [[The OODA Loop]] | [[Economic Moats]] |
| Hesitation to cut losses on failing projects | [[Sunk Cost Fallacy]] | [[Loss Aversion]] | [[Opportunity Cost]] |
| Uncertain forecasts or planning fallacies | [[Base Rate Fallacy]] | [[Map vs Territory]] | [[Anchoring & Adjustment]] |
| Designing systems under hostile volatility | [[Antifragility]] | [[Defense in Depth]] | [[Margin of Safety]] |
| Shared platform or multi-tenant degradation | [[Tragedy of the Commons]] | [[Goodhart's Law]] | [[Principal-Agent Problem]] |
| Navigating live crises under incomplete data | [[The Fog of War]] | [[The OODA Loop]] | [[Margin of Safety]] |
| Hiring, credentials, and counterfeit claims | [[Costly Signaling & The Handicap Principle]] | [[Circle of Competence]] | [[Principal-Agent Problem]] |
Models are machine-readable with strict YAML frontmatter and dedicated AI Agent Reasoning Protocols.
- Antigravity Skill: Located at
skills/mental-models/SKILL.md. Equip your agent to run multi-model debiasing passes before major refactors. - Model Context Protocol (MCP): Run
mcp/server.pyover stdio with Claude Desktop, Cursor, or Antigravity:{ "mcpServers": { "mental-models": { "command": "python3", "args": ["/path/to/mental-models/mcp/server.py"] } } }
Models do not exist in isolation. Every file connects to others via standard wikilinks ([[Model Name]]), compatible with Obsidian and Logseq.
- Interactive Force-Directed Graph: Open
docs/graph.htmldirectly in any browser for an interactive D3.js visualization showing 100 interconnected nodes and 235 cross-disciplinary links. - Regenerate Graph:
python3 scripts/generate_graph.py
Quickly search, diagnose, and review models from your terminal with zero external pip dependencies:
# List all 100 models organized by category
./cli/mm list
# Search models across titles, summaries, and triggers
./cli/mm search "uncertainty"
# Diagnose a strategic or technical problem statement
./cli/mm diagnose "Our team wants to replace a legacy billing service"
# Show complete details, checklist, and triggers for a model
./cli/mm show chestertons-fence
# Pull a random model for daily reflection
./cli/mm randomInternalize models into long-term intuition. The automated export script extracts conceptual mechanisms and diagnostic scenarios into ready-to-import Anki cards:
python3 scripts/export_anki.pyOutputs exports/mental_models_anki.tsv containing 200 flashcards ready for 1-click import into Anki Desktop / Mobile.
- Abductive Reasoning (Inference to the Best Explanation): The form of logical inference that starts with an incomplete set of observations and forms the most likely, parsimonious,...
- Chesterton's Fence: The principle that reforms, deletions, or removals of existing structures, rules, or code should never be made until the...
- Circle of Competence: The practice of identifying the realistic boundaries of your genuine knowledge and expertise, ruthlessly operating within...
- Falsifiability: The principle that for any hypothesis, theory, or statement to be considered genuinely scientific or predictive, it must be...
- First-Principles Thinking: The practice of deconstructing a problem down to its most fundamental, irreducible truths and building up a solution from...
- Hanlon's Razor: Never attribute to malice that which is adequately explained by carelessness, ignorance, incompetence, or cognitive overload.
- Inversion: The practice of approaching problems backwards, focusing on avoiding failure, catastrophe, and stupidity rather than...
- Lateral Thinking: The practice of solving problems through an indirect, non-linear, and creatively diagonal approach, deliberately stepping...
- The Lindy Effect: The theory that the future life expectancy of non-perishable entities (technologies, books, ideas, institutions) is...
- Map vs. Territory: The fundamental realization that an abstraction, model, diagram, or metric of reality is not the reality itself, and that...
- Necessary vs. Sufficient Conditions: The fundamental logical distinction between a condition that must be present for an event to occur (necessary) and a...
- Occam's Broom: The intellectually dishonest practice where an advocate or theorist subtly sweeps inconvenient, contradictory facts and...
- Occam's Razor: Among competing hypotheses or design solutions that predict or achieve identical outcomes, the one requiring the fewest...
- Proximate vs. Root Cause: The crucial distinction between the immediate, surface event that triggered a failure (proximate cause) and the deeper,...
- Reductio ad Absurdum: The method of disproving a proposition or architectural claim by demonstrating that its logical consequences, when followed...
- Second-Order Thinking: The discipline of evaluating decisions not just by their immediate, intended consequences, but by the subsequent ripple...
- Steelmanning (The Principle of Charity): The practice of constructing the strongest, most compelling possible version of your opponent's or alternative's argument...
- Thought Experiments (Gedankenexperiment): The practice of exploring the implications of an idea, hypothesis, or paradox using pure disciplined mental visualization...
- Antifragility: The property of systems that increase in capability, resilience, or robustness as a consequence of stressors, volatility,...
- Ashby's Law of Requisite Variety: The cybernetic law stating that for a control system or organization to maintain stability and deal effectively with...
- Braess's Paradox: The counter-intuitive observation that adding extra capacity, links, or routes to a congested, decentralized network can...
- The Bullwhip Effect: The phenomenon where small fluctuations in retail customer demand become progressively and exponentially amplified as...
- The Cobra Effect (Perverse Incentives): The systemic phenomenon where an attempted solution, reward, or incentive designed to solve a problem inadvertently rewards...
- Emergence & Self-Organization: The phenomenon where a collection of simple agents interacting according to basic local rules gives rise to complex,...
- Feedback Loops (Reinforcing & Balancing): The circular causality where the output of a system circles back to either amplify (reinforcing) or stabilize (balancing)...
- Gall's Law: The rule of thumb that a complex system that works is invariably found to have evolved from a simple system that worked;...
- Goodhart's Law: When a measure becomes a target, it ceases to be a good measure, because actors will optimize to maximize the target while...
- Homeostasis vs. Allostasis: The distinction between maintaining stability by holding internal states constant around a rigid setpoint (homeostasis)...
- Hysteresis & Path Dependence: The property of physical and human systems where the current state depends not only on the current environment and inputs,...
- Le Chatelier's Principle: The universal systems law that when a system at dynamic equilibrium is subjected to an external disturbance, stress, or...
- Local vs. Global Optima: The dilemma in optimization where a system reaches the peak of a low hill (a local optimum) where any immediate step in any...
- Theory of Constraints: The principle that any manageable system is limited in achieving more of its goals by a very small number of constraints...
- Tragedy of the Commons: The systemic dilemma where individuals acting independently and rationally according to their own self-interest deplete,...
- Adverse Selection & The Market for Lemons: The market failure where asymmetric information between buyers and sellers causes high-quality goods, healthy participants,...
- Asymmetric Payoffs: Situations where the potential upside of an action or investment dwarfs the strictly capped, finite downside, creating an...
- Comparative Advantage & Specialization: The economic principle that individuals, teams, or nations maximize collective and personal prosperity by specializing in...
- Creative Destruction: The process of industrial and technological mutation that incessantly revolutionizes the economic structure from within,...
- Economic Moats & Competitive Defensibility: The structural, sustainable competitive advantages that protect a business or platform from competitor encroachment,...
- Economies of Scale vs. Diseconomies of Scale: The cost advantage that arises with increased output of a product, where fixed costs are spread across more units (economies...
- Gresham's Law: The monetary principle that "bad money drives out good money" when legal tender laws mandate an equal face value between...
- Moral Hazard: The lack of incentive to guard against risk and loss when one is insulated from its negative consequences, typically because...
- Nash Equilibrium & Prisoner's Dilemma: A state in a game or competitive system where no player has an incentive to unilaterally change their chosen strategy, even...
- Network Effects: The economic dynamic where a product, platform, or service becomes exponentially more valuable to existing and prospective...
- Opportunity Cost: The true cost of any choice is not merely the financial outlay, but the lost value of the next best alternative that must be...
- Principal-Agent Problem: The structural conflict of interest that arises when one party (the agent) is authorized to make decisions on behalf of...
- Rent-Seeking & Tollbooth Economics: The practice of expending resources, political lobbying, or legal maneuvering to manipulate the social or economic...
- Sunk Cost Fallacy: The irrational cognitive bias of continuing an endeavor or allocating further resources based on the accumulated historical...
- Zero-Sum vs. Non-Zero-Sum Games: The distinction between interactions where one party's gain is strictly balanced by another party's exact loss (zero-sum,...
- Anchoring & Adjustment: The cognitive bias where an individual relies excessively on the first piece of information encountered (the "anchor") when...
- Availability Heuristic: The mental shortcut where people evaluate the frequency, probability, or importance of an event based on how easily...
- Commitment & Consistency: The deeply ingrained psychological desire to remain consistent with what we have previously said, done, or publicly...
- Confirmation Bias: The pervasive psychological tendency to search for, interpret, favor, and recall information in a way that confirms one's...
- The Curse of Knowledge: The cognitive bias where an individual, once they have acquired deep knowledge or mastery in a subject, finds it virtually...
- Dunning-Kruger Effect: The cognitive bias where individuals with low competence or knowledge in a specific domain drastically overestimate their...
- Framing Effect: The cognitive bias where people draw radically different conclusions and make divergent choices depending on how identical...
- Fundamental Attribution Error: The cognitive tendency to explain others' negative behaviors by citing internal character flaws or disposition, while...
- Hindsight Bias ("I Knew It All Along"): The psychological tendency for people to perceive past events as having been completely predictable and obvious before they...
- Hyperbolic Discounting & Present Bias: The cognitive tendency to place disproportionately high value on immediate rewards right now, while steeply and...
- Loss Aversion: The psychological phenomenon where the pain of losing something is cognitively experienced as roughly twice as intense as...
- The Scarcity Principle: The psychological heuristic where people assign significantly higher subjective value, urgency, and desirability to...
- Social Proof & Informational Cascades: The psychological phenomenon where people assume the actions, beliefs, and behaviors of others in an attempt to reflect...
- Base Rate Fallacy: The cognitive tendency to ignore general prior statistical distribution rates in favor of specific, vivid, but...
- Black Swan Theory: The theory of rare, unforeseen events that lie outside the realm of regular expectations, carry an extreme, catastrophic or...
- Combinatorial Explosion: The mathematical phenomenon where the number of possible states, combinations, permutations, or interactions in a system...
- Compounding & Exponential Growth: The mathematical process where the returns, gains, or outputs of an asset, knowledge base, or habit are reinvested to...
- Ergodicity & Absorbing Barriers: The critical distinction between the average outcome of a group across parallel worlds (ensemble average) and the average...
- Expected Value: The anticipated value of an investment, decision, or action calculated by multiplying each possible outcome by its...
- The Gambler's Fallacy & The Monte Carlo Fallacy: The erroneous belief that if a particular random event has occurred more frequently than normal in the past, it is somehow...
- The Kelly Criterion & Position Sizing: A mathematical formula for sizing a series of bets or capital investments to maximize the long-term compound geometric...
- Law of Large Numbers: The mathematical theorem stating that as the number of independent, identically distributed trials increases, the empirical...
- Power Laws & The Pareto Principle (80/20): The mathematical relationship where a tiny percentage of participants, causes, or inputs account for a vastly...
- Regression to the Mean: The statistical phenomenon that if an extreme, outlier measurement or performance is observed on a first trial, subsequent...
- Survivorship Bias: The logical error of focusing exclusively on the successful "survivors" of a selective process while completely ignoring the...
- Activation Energy & Catalysts: The initial threshold of energy required to initiate a chemical, physical, or behavioral process that, once overcome, allows...
- Conservation Laws & The First Law of Thermodynamics: The fundamental physical principle that in an isolated system, certain key quantities (mass, energy, momentum, electric...
- Critical Mass: The minimum amount of concentrated material, energy, or participation required to sustain a self-propagating chain reaction...
- Elasticity vs. Plastic Deformation (Hooke's Law): The physical distinction between a reversible deformation where a material absorbs stress and returns completely to its...
- Thermodynamics & Entropy: The fundamental physical law that in any isolated system, disorder, noise, and randomness tend naturally to increase over...
- Friction & Inertia (Newton's First Law): The fundamental physical law that an object at rest remains at rest, and an object in motion continues in motion at constant...
- Half-Life & Exponential Decay: The constant mathematical interval of time required for a quantity, radioactive isotope, memory, technical knowledge, or...
- Leverage (Physical & Conceptual): The principle where a small initial input force or asset applied at an advantageous pivot point (fulcrum) produces an...
- Margin of Safety: The practice of intentionally designing excess buffer capacity into a system, bridge, calculation, or financial allocation...
- The Observer Effect & The Measurement Tax: The physical and behavioral principle that the act of observing, measuring, profiling, or monitoring a system invariably...
- Resonance & Harmonic Amplification: The physical phenomenon where a system oscillates with maximum, explosive amplitude when subjected to periodic external...
- Surface Area-to-Volume Ratio & The Square-Cube Law: The mathematical geometric invariant that as an object, organism, or system scales in size linearly, its surface area grows...
- Carrying Capacity: The maximum population size or throughput that an environment or system can sustainably sustain without exhausting its...
- Co-evolution & Symbiosis: The process where two or more distinct species, technologies, or organizations reciprocally affect each other's evolution...
- Ecological Niches & The Competitive Exclusion Principle: The principle that two species competing for the exact same ecological niche and identical finite resources cannot coexist...
- Evolutionary Mismatch: The phenomenon where biological or behavioral traits that evolved to maximize fitness in an ancestral environment become...
- Natural Selection & Survival of the Fittest: The universal process where differential reproductive success driven by environmental selection pressure acts upon heritable...
- Punctuated Equilibrium: The evolutionary pattern where complex systems experience long periods of static stability (stasis) interrupted by brief,...
- The Red Queen Effect: The principle that in a co-evolving, competitive system, continuous adaptation, innovation, and exertion are required simply...
- Costly Signaling & The Handicap Principle: The principle that for a signal or communication to be credible and trusted between actors with conflicting incentives, it...
- Attrition vs. Maneuver: The fundamental strategic dichotomy between grinding down an opponent through brute mass and symmetric resource depletion...
- Center of Gravity (Schwerpunkt): The primary hub of power, cohesion, and movement upon which an entire system depends; concentrating overwhelming force...
- Defense in Depth: The strategy of employing multiple layered, independent, and redundant defensive controls so that the failure or compromise...
- The Fog of War & Epistemic Uncertainty: The profound uncertainty, ambiguity, misinformation, and cognitive confusion that invariably characterizes real-time...
- Interior vs. Exterior Lines: The geometric principle where a centrally positioned force (interior lines) moves resources, communicates, and concentrates...
- Mission Command (Auftragstaktik): A decentralized operational doctrine where leadership defines the overarching intent and constraints ("what" and "why"),...
- The OODA Loop: A four-step decision cycle (Observe, Orient, Decide, Act) emphasizing that the competitor or system capable of processing...
mental-models/
├── .github/workflows/ci.yml # Automated CI schema & CLI test suite
├── cli/
│ ├── mm # Executable CLI entrypoint (ANSI formatted)
│ └── mm_core.py # Core parsing, search, and diagnosis engine
├── docs/
│ └── graph.html # Standalone interactive D3.js knowledge graph
├── exports/
│ └── mental_models_anki.tsv # Generated Anki flashcard deck (200 cards)
├── mcp/
│ └── server.py # JSON-RPC Model Context Protocol server
├── models/ # THE SINGLE SOURCE OF TRUTH (100 models)
│ ├── core_thinking/ # 18 models
│ ├── economics_strategy/ # 15 models
│ ├── evolution_biology/ # 8 models
│ ├── operations_strategy/ # 7 models
│ ├── physics_engineering/ # 12 models
│ ├── probability_math/ # 12 models
│ ├── psychology_cognition/ # 13 models
│ └── systems_complexity/ # 15 models
├── scripts/
│ ├── export_anki.py # Generates Spaced Repetition decks
│ ├── generate_graph.py # Builds force-directed D3 graph
│ └── validate_models.py # Validates frontmatter & link schema
├── skills/
│ └── mental-models/SKILL.md # Antigravity / AI Agent skill specification
├── templates/
│ └── model-template.md # Standard schema for adding new models
├── CONTRIBUTING.md
├── LICENSE # MIT License
└── README.md
All model contributions must conform to the strict schema checked by our validation script:
python3 scripts/validate_models.pyChecks performed:
- Valid YAML frontmatter (
id,title,domain,category,summary,triggers,counter_models,paired_models). - Presence of all required sections: Core Intuition, Diagnostic Checklist, Real-World Case Studies, Failure Modes, The Latticework, AI Protocol.
- Integrity of inter-model references.
Contributions of new mental models or refinements to existing ones are warmly welcome! Please review CONTRIBUTING.md and use templates/model-template.md as the blueprint.
This project is licensed under the MIT License © 2026 Gabriel Rondon.