Contorium Runtime MCP

Runtime continuity layer MCP for AI coding agents, providing persistent workspace state and session context across tools and runs.

GitHub

Documentation

Contorium

Project Intelligence Runtime for AI Coding Tools

Contorium is a local-first system that preserves and reconstructs software project intelligence across AI coding environments.

It works with:

Cursor
Claude Code
Codex
Gemini CLI
VS Code
Any MCP-compatible runtime

Instead of repeatedly re-explaining architecture, decisions, and project state in every session, Contorium maintains a shared Project Intelligence Layer that all tools can access.

Core Idea

Git stores code history
Contorium stores project intelligence history

It captures not just what changed, but:

Why it changed
What decisions were made
What the project is trying to become
How it evolved over time

CIL — Cognitive Interaction Layer (v3)

CIL is the user-facing intelligence system.

It does not execute tasks.

It answers questions.

User Query
   ↓
Query Router
   ↓
Cognitive Kernel
   ↓
Engines (Event · Decision · State · Graph)
   ↓
Formatter
   ↓
Response

What CIL Can Answer

Question	System
What happened?	History Engine
Why was this done?	Decision Center
What should I do next?	Action Engine (suggestions only)
What is this project?	Story / Essence
What was state at a time?	Time Travel (Snapshot)
What is MCP?	Knowledge Graph
Is the project healthy?	Cognitive Health + Knowledge Lifecycle
What needs review?	Review Queue (Lifecycle)
Is this decision still valid?	Decision Center + Lifecycle trust

Knowledge Lifecycle (v3.2 — Validity-Aware)

Living Project Intelligence tracks whether decisions are still trustworthy — not only when they were recorded, but why they may have decayed.

ADR + Events → Lifecycle Engine → Knowledge Health + Review Queue
                      ↓
         Validity state + decay signals (v2)
                      ↓
              Ask / IDE / Dashboard / MCP

Core ideas:

Concept	What it means
Validity state	`VALID` · `DECAYING` · `NEEDS_REVALIDATION` · `INVALIDATED`
Decay triggers	Code/architecture drift, dependency change, owner change, assumption failure, superseded ADR
Review queue	Stale, expired, conflict, missing owner, and invalidation triggers
Ask overlay	Decision answers show validity, why, suggested action, and adjusted confidence

Artifacts: .contora/lifecycle/ — see docs/LIFECYCLE_V1.md.

contorium lifecycle
contorium review
contorium lifecycle owner adr-001 --owner platform-team
contorium lifecycle verify adr-001 --type manual

Ask examples:

contorium ask "Why was MCP added?"
contorium ask "What needs review?"
contorium ask "Is this decision still valid?"

Example Commands

contorium ask "Why was MCP added?"
contorium ask "What happened this week?"
contorium ask "What was the state on 2024-06-18?"

Other tools:

contorium health
contorium lifecycle
contorium review
contorium entity mcp
contorium dna --copy
contorium questions

PIL — Project Intelligence Layer

PIL is the storage layer (source of truth).

It is deterministic and fully local.

It stores:

STATE (current project state)
INTENT (project goals)
DECISION (architectural decisions)
WHY (decision rationale)
TIMELINE (evolution history)
IMPACT (dependency relationships)
PROVENANCE (origin tracking)
CONFIDENCE (reliability signals)

All data is stored under:

.contora/

PIL is NOT interactive

It does not answer questions.

It only stores structured intelligence.

Core Design Principle

Separation of Responsibilities

PIL → facts (deterministic)
CIL → cognition (interpretation)
LLM → optional explanation layer

Three Core Actions

Contorium is built around three unified operations:

1. Capture

Record project intelligence.

contorium capture focus
contorium capture note
contorium capture decision

2. Inspect

Read project intelligence.

contorium inspect state
contorium inspect decision
contorium inspect timeline
contorium inspect graph
contorium inspect health

3. Transfer

Export intelligence for AI continuity.

contorium transfer context
contorium transfer intelligence
contorium transfer handoff

Transfer Modes

Mode	Purpose	Size
Context	Resume in new AI chat	small
Handoff	Continue active session	compact
Intelligence	Full project export	deep analysis

Architecture

                Query Layer (Ask)
                        │
                 Query Router
                        │
              Cognitive Kernel (CIL)
                        │
     ┌──────────────┬──────────────┬──────────────┐
     ▼              ▼              ▼
 Event Engine   Decision Engine   State Engine
     │              │              │
     └───────┬──────┴──────┬──────┘
             ▼             ▼
        Action Engine   Knowledge Graph
             │
             ▼
        IDE · MCP · CLI · Dashboard
             │
             ▼
         PIL (.contora/)

Three Runtimes

Contorium runs across three equal environments:

Runtime	Role
IDE	Workspace intelligence
MCP	AI agent interface
CLI	Terminal operations

All share:

@contora/state-core
.contora/ local intelligence repository

Cognitive Dimensions

Contorium structures project intelligence across dimensions:

STATE → what exists now
INTENT → what is the goal
DECISION → what was chosen
WHY → reasoning behind decisions
TIMELINE → when things changed
IMPACT → what is affected
PROVENANCE → where data came from
CONFIDENCE → reliability level

Cognitive Features (CIL)

Project History Exploration
Decision Center (ADR + conflicts)
Time Travel (snapshot replay)
Entity Knowledge Graph
Cognitive Health Analysis
Project Story / Essence
Project DNA
Suggested Questions

Local-First Design

All intelligence is stored locally:

.contora/

Example structure:

.contora/
├── state.json
├── intent/
├── timeline/
├── graph/
├── events/
├── decisions/
├── health.json
├── config/
│   └── llm.json

No cloud dependency. No vendor lock-in.

LLM Layer (Optional)

Contorium does NOT require LLMs.

But supports optional enhancement for:

Why explanation
Story generation
Essence compression
DNA summarization
Suggested questions

Configuration

{
  "provider": "openai",
  "model": "gpt-5",
  "enabled_modules": [
    "why",
    "story",
    "essence",
    "dna"
  ]
}

What Contorium Is NOT

Contorium is not:

an autonomous coding agent
a task execution system
a project manager
a recommendation engine

It does not execute actions.

It preserves and explains project intelligence.

Quick Start

MCP

npm install -g @contorium/mcp
claude mcp add --scope project contorium -- npx @contorium/mcp

CLI

git clone https://github.com/ContoriumLabs/contorium.git
cd contorium
npm install
npm run compile

npx contorium init .
npx contorium ask "What is this project?"

IDE

Install extension
Open workspace
Set Focus
Use Ask Contorium
Transfer Context when switching AI sessions

Dashboard

Cognitive runtime dashboard includes:

Live cognition view
Decision governance
Debug trace
Project history
Health stream

Supported Platforms

Cursor
Claude Code
Codex
Gemini CLI
VS Code
MCP-compatible tools

Links

Website: https://www.contorium.dev

GitHub: https://github.com/ContoriumLabs/contorium

License

MIT / See LICENSE