Right Reasons

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.