Right Reasons

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

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 ofwhythat relationship exists. This means an AI agent can trace from any operational decision back to the foundational beliefs that justify it.

- 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.

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

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

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" } } } }

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

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

The epistemic boundary is strict:promote_candidaterequires statusauthenticatedorcalibrated. 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 isnota 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 │ └──────────────────┘

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

The contract tells the executing agentwhythis task matters,what rulesapply, andwhich boundariesmust not be crossed — without the agent needing to query the full ontology itself.

- 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

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

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

Structural— within-layer relationships:

Reasoning— justification and prioritization:

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

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

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

- Clausesderived from RULES-layer objects
- Constraintsfrom policies
- Success criteriafrom decision rules and tactical concepts
- Referencesto all relevant objects across all 4 layers
- Reasoning chainshowing the full LORE → VISION → RULES → OPS trace

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

MCP memory server with Hebbian learning — concept connections strengthen through co-activation and weaken through disuse.

A knowledge graph server that provides persistent, multi-context memory for AI models.

Provides persistent memory for AI models using a local knowledge graph.

Neo4j graph database server (schema + read/write-cypher) and separate graph database backed memory

Provides AI assistants with persistent memory using ChromaDB vector storage.

Query and interact with FalkorDB graph databases using AI models.

Query a Neo4j graph database containing a knowledge graph of German family businesses.

Deterministic O(1) memory for AI agents — local-first, MCP-native, with multi-agent speaker attribution and millisecond recall.

A framework for building and querying temporally-aware knowledge graphs for AI agents.