Right Reasons

Structured business ontology that gives AI agents deterministic access to institutional reasoning.

AI agents using Markdown + RAG score 0% recall on "why?" questions. The same agents using Right Reasons score 100%. Tested across 48 sessions with 2 independent judges. Full experiment results →

Experiment results

Tested on a real business domain (48 runs, 8 task types, 2 independent LLM judges):

Metric	Markdown + RAG	Right Reasons	Delta
Entity recall	0.514	0.976	+90%
"Why?" question recall	0.000	1.000	0% → 100%
Reasoning quality	1.96 / 5	4.33 / 5	+121%
Stability (variance)	1.457	0.472	3× more stable
Latency	284.6s	183.8s	-35% faster
Pairwise wins	0	20	(4 ties)

Full methodology and results →

What it does

Right Reasons maps your business knowledge into a four-layer ontology:

LORE      (beliefs, worldview)
  ↓ interpreted_into
VISION    (goals, theses, priorities, boundaries)
  ↓ operationalized_into
RULES     (policies, decision rules, tactical concepts)
  ↓ applied_to
OPERATIONS (initiatives, decisions, tasks, events)

Every connection between layers carries an assertion — an explicit explanation of why that relationship exists. This means an AI agent can trace from any operational decision back to the foundational beliefs that justify it.

Key concepts

Deterministic retrieval: SQL queries, not vector search. No probabilistic hallucination.
Reifiable relations: Every edge can carry a versioned "why?" explanation.
Human validation: Every AI-proposed change goes through diff-based approval (Dolt = Git for data).
OPS Contracts: Reasoning envelopes that attach institutional context to work in external systems.
EPICAL pipeline: Extract → Ponder → Interrogate → Calibrate → Authenticate → Load.

Quick start

Prerequisites

Docker and Docker Compose
Python 3.11+

1. Start the database

docker compose up -d

This initializes Dolt with the schema and example seed data (11 objects, 8 relations across all 4 layers).

2. Install the MCP server

cd mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -e .

3. Connect your AI agent

Add to your Claude Desktop / Claude Code MCP config:

{
  "mcpServers": {
    "right-reasons": {
      "command": "/path/to/mcp-server/.venv/bin/right-reasons-mcp",
      "env": {
        "RR_DOLT_HOST": "127.0.0.1",
        "RR_DOLT_PORT": "3307",
        "RR_DOLT_DATABASE": "right_reasons"
      }
    }
  }
}

4. Try it

Ask your agent:

Why did we choose Provider A over Provider B for identity?
Use the get_explanation_packet tool with object ID "ex_ops_02".

The agent will trace the reasoning chain:

OPERATIONS: Chose Provider A (affordable, OIDC compatible)
RULES: Start with affordable identity provider, plan migration later
VISION: Build self-service tools for micropreneurs
LORE: Small business owners want to handle accounting themselves

MCP Tools (18)

Query tools (9)

Tool	Description
`list_objects`	List objects filtered by layer, type, search, validation status
`get_object`	Full details of a single object
`list_relations`	List relations with assertion explanations
`get_relation_assertion`	Full assertion history for a relation
`traverse_graph`	Navigate the ontology graph — trace "why?" chains
`get_schema_info`	All object types (14) and relation types (20)
`get_authentication_trail`	Audit trail: who proposed, confirmed, validated
`get_explanation_packet`	Complete context for an object in one call
`query_sql`	Read-only SQL for advanced queries

Mutation tools (4)

Tool	Description
`create_session`	Start an EPICAL intake session
`propose_object`	Stage a candidate object (requires authentication before promotion)
`propose_relation`	Stage a candidate relation
`promote_candidate`	Promote authenticated candidate to canonical

OPS Contract tools (3)

Tool	Description
`generate_ops_contract`	Auto-generate reasoning envelope from ontology for external work
`get_ops_contract`	Retrieve contract with resolved references
`list_ops_contracts`	List contracts by status or kind

Dolt tools (2)

Tool	Description
`dolt_status`	Working set status (like `git status`)
`dolt_diff`	Row-level diffs between commits (like `git diff`)
`dolt_commit`	Commit changes with message

EPICAL: How knowledge enters the ontology

Right Reasons does not allow AI agents to write directly into the canonical ontology. All knowledge passes through the EPICAL pipeline:

Source docs ──▶ EXTRACT ──▶ PONDER ──▶ INTERROGATE ──▶ CALIBRATE ──▶ AUTHENTICATE ──▶ LOAD
                  │           │            │               │              │              │
               raw text    identify     challenge       adjust        human           promote to
               intake      candidate    claims &        confidence    validates       canonical
                           objects &    assumptions     scores        via Dolt        ontology
                           relations                                 diff review

Stage	What happens	Who
Extract	Source documents parsed into fragments	Agent
Ponder	Candidate objects and relations identified	Agent
Interrogate	Claims challenged, gaps surfaced	Agent
Calibrate	Confidence and durability scores adjusted	Agent
Authenticate	Human reviews Dolt diff, approves or rejects	Human
Load	Authenticated candidates promoted to canonical status	Agent

The epistemic boundary is strict: promote_candidate requires status authenticated or calibrated. An agent cannot bypass human validation.

OPS Contracts: Reasoning envelopes for external work

OPS Contracts solve the "last mile" problem: how does institutional reasoning reach the systems where work actually happens (Jira, CI/CD, planning tools)?

An OPS Contract is not a task manager. It is a reasoning envelope — a paperclip that attaches scoped institutional context to a work item in an external system.

External work item          OPS Contract                    Ontology
(Jira, GitHub, etc.)        (reasoning envelope)            (4 layers)
┌──────────────┐     ┌─────────────────────┐     ┌──────────────────┐
│ TASK-123:    │────▶│ Clauses (from RULES)│◀────│ RULES: policies, │
│ Prepare      │     │ Constraints         │     │ decision rules   │
│ annual       │     │ Success criteria    │     ├──────────────────┤
│ report       │     │ References (31)     │     │ VISION: goals,   │
│              │     │ Reasoning chain (13)│     │ boundaries       │
└──────────────┘     └─────────────────────┘     ├──────────────────┤
                                                  │ LORE: beliefs,   │
                                                  │ worldview        │
                                                  └──────────────────┘

The agent generates it in one call:

generate_ops_contract(
    external_work_ref="jira://TASK-123",
    description="Prepare annual report for submission",
    contract_kind="annual_reporting"
)

The contract tells the executing agent why this task matters, what rules apply, and which boundaries must not be crossed — without the agent needing to query the full ontology itself.

Schema

The full schema is in schema/LOAD1st_bootstrap.sql.

Core tables:

rr_object — canonical business objects with layer, confidence, validation status
rr_relation — typed edges between objects
rr_relation_assertion — versioned "why?" explanations (reifiable relations)
rr_object_type — 14 types across 4 layers
rr_relation_type — 20 relation types in 5 families
ops_contract — reasoning envelopes for external work items
src_session, src_candidate_object, src_candidate_relation — EPICAL intake pipeline
src_authentication_event, rr_validation_record — audit trail

Object types (14)

Layer	Type	Description
LORE	`lore_item`	Foundational belief or worldview element
VISION	`strategic_goal`	Desired longer-horizon outcome
VISION	`strategic_thesis`	Directional belief about how success is created
VISION	`strategic_priority`	Relative weighting among strategic directions
VISION	`strategic_boundary`	Strategic no-go area or explicit limit
RULES	`policy`	Operational policy derived from higher-layer strategy
RULES	`decision_rule`	Discrete action-shaping logic
RULES	`escalation_rule`	Trigger for upward traversal or human review
RULES	`tactical_concept`	Reusable applied operational pattern
OPERATIONS	`initiative`	Bounded effort or program
OPERATIONS	`situation`	Live context requiring interpretation
OPERATIONS	`decision`	Chosen or recommended course of action
OPERATIONS	`task`	Concrete action unit
OPERATIONS	`event`	Observed outcome or signal

Relation types (20)

Organized in 5 families. Reifiable relations (✓) can carry versioned assertion explanations.

Transition — cross-layer links that form the reasoning spine:

Code	Description	Reifiable
`interpreted_into`	LORE → VISION interpretive transition	✓
`operationalized_into`	VISION → RULES operationalization	✓
`applied_to`	RULES → OPERATIONS application	✓

Structural — within-layer relationships:

Code	Description	Reifiable
`supports`	Positive contribution
`constrains`	Limiting relation
`conflicts_with`	Tension or conflict
`depends_on`	Dependency
`affects`	Material effect
`relevant_to`	Contextual relevance

Reasoning — justification and prioritization:

Code	Description	Reifiable
`justified_by`	Explicit reasoning support	✓
`validated_against`	Validation against another object	✓
`prioritized_over`	Relative ranking	✓
`escalates_to`	Escalation target	✓

Governance — ownership and authority:

Code	Description	Reifiable
`owned_by`	Ownership
`reviewed_by`	Review relation
`authorized_by`	Authorization
`overridden_by`	Override (with explanation)	✓

Feedback — observations and outcomes:

Code	Description	Reifiable
`observed_in`	Observation in context
`resulted_in`	Causal result	✓
`evaluated_by`	Evaluation	✓

Architecture

┌─────────────┐     ┌──────────────┐     ┌──────────┐
│  AI Agent   │────▶│  MCP Server  │────▶│   Dolt   │
│ (Claude,    │     │  (Python /   │     │  (Git    │
│  GPT, etc.) │◀────│   FastMCP)   │◀────│  for     │
│             │     │  18 tools    │     │  data)   │
└─────────────┘     └──────────────┘     └──────────┘
                           │
                    stdio / SSE / HTTP

Dolt provides Git semantics for data: branch, commit, diff, merge, PR-style validation
MCP is the de facto standard for agent-tool communication (97M+ SDK downloads)
Python / FastMCP keeps the server simple (~700 lines across 7 files)

Example: OPS Contract generation

generate_ops_contract(
    external_work_ref="jira://TASK-123",
    description="Prepare annual report for submission",
    contract_kind="annual_reporting"
)

Returns a reasoning envelope with:

Clauses derived from RULES-layer objects
Constraints from policies
Success criteria from decision rules and tactical concepts
References to all relevant objects across all 4 layers
Reasoning chain showing the full LORE → VISION → RULES → OPS trace

License

Business Source License 1.1 — see LICENSE.

Contributing

Right Reasons is in early development. If you're interested in contributing or using it for your business, open an issue or reach out.

Name		Name	Last commit message	Last commit date
docker		docker
examples		examples
experiments		experiments
mcp-server		mcp-server
schema		schema
seed-data		seed-data
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml

Navigation Menu

Uh oh!

Repository files navigation

Right Reasons

Experiment results

What it does

Key concepts

Quick start

Prerequisites

1. Start the database

2. Install the MCP server

3. Connect your AI agent

4. Try it

MCP Tools (18)

Query tools (9)

Mutation tools (4)

OPS Contract tools (3)

Dolt tools (2)

EPICAL: How knowledge enters the ontology

OPS Contracts: Reasoning envelopes for external work

Schema

Object types (14)

Relation types (20)

Architecture

Example: OPS Contract generation

License

Contributing

About

Releases

Packages

Used by

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Right Reasons

Experiment results

What it does

Key concepts

Quick start

Prerequisites

1. Start the database

2. Install the MCP server

3. Connect your AI agent

4. Try it

MCP Tools (18)

Query tools (9)

Mutation tools (4)

OPS Contract tools (3)

Dolt tools (2)

EPICAL: How knowledge enters the ontology

OPS Contracts: Reasoning envelopes for external work

Schema

Object types (14)

Relation types (20)

Architecture

Example: OPS Contract generation

License

Contributing

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages