Contorium

Name: contorium
Author: ContoriumLabs

Project Intelligence Layer for AI-assisted development.

AI can read your code.

But it doesn't always know why your project became what it is.

Contorium gives AI coding tools a persistent layer of project intelligence — preserving decisions, reasoning, constraints, structure, history, and evolving project state across sessions, tools, and models.

Not chat history. Not prompts. Project intelligence.

Website · Documentation · Overview

Git remembers what changed.
Contorium remembers why.

Why Contorium?

AI coding agents are getting better at writing and modifying code.

But long-lived projects have another problem:

The codebase contains what the project is — but not always why it became that way.

Important knowledge gets lost between:

AI sessions
different coding tools
model switches
experiments and failed approaches
architectural decisions
long development cycles

Eventually, developers end up explaining the same project to AI again and again.

You should be building the project — not repeatedly explaining it.

What is Project Intelligence?

A project is more than its files.

It has:

Intent
  ↓
Decisions
  ↓
Reasoning
  ↓
Implementation
  ↓
Outcomes
  ↓
Evolution
  ↓
Current State

Contorium preserves and connects this information so AI tools can work from the project's accumulated understanding instead of reconstructing it from scratch every session.

Project Intelligence includes

Decisions
What was chosen, rejected, or changed?

Reasoning
Why was a particular approach taken?

Constraints
What must remain true, and why?

Structure
How are the project's modules, files, and functions connected?

History
How did the project evolve?

Current State
What matters now, and what should happen next?

One Project. One Intelligence Layer. Every AI Tool.

Your AI tools can change.

Your project's accumulated understanding shouldn't have to.

                 Your Project
                      │
                      ▼
          ┌──────────────────────┐
          │      Contorium       │
          │                      │
          │ Project Intelligence │
          │        Layer         │
          └──────────┬───────────┘
                     │
          ┌──────────┼──────────┐
          ▼          ▼          ▼
       Cursor     Claude      Codex
          │        Code         │
          │          │          │
          └──────────┼──────────┘
                     ▼
             Shared Understanding

Use the tools you prefer without forcing each one to reconstruct the project from zero.

Contorium currently integrates with:

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

What Contorium Actually Does

1. Persistent Project Understanding

Keep project intelligence across:

sessions
tools
model switches
long development cycles

The goal is not to remember everything.

The goal is to preserve what matters.

2. Project Knowledge Graph

Contorium builds structured relationships across the project:

Intent
  ↓
Module
  ↓
File
  ↓
Function
  ↓
Dependency

Instead of treating a repository as a collection of disconnected files, Contorium builds a queryable representation of how the project fits together.

3. Project History

Understand how the project evolved.

Track the changes that matter and connect them to the project's broader state.

4. Decision & Reasoning

Preserve the knowledge that is usually lost after a conversation ends:

what was decided
what alternatives were considered
why an approach was chosen
what happened afterward

This helps future AI sessions understand not only what exists, but why.

5. Decision Validity

Projects evolve. Knowledge becomes outdated.

Contorium tracks whether decisions still hold:

Change → Assumption → Impact → Decision Validity

Lifecycle states include:

VALID → WARNING → DECAYING → SUSPECTED_INVALID → NEEDS_REVALIDATION → INVALIDATED

Ask:

contorium ask "What decisions need review?"

6. AI-ready Project State

Generate a compact representation of the project's current state for AI handoff.

Instead of:

New session
    ↓
Read everything again
    ↓
Reconstruct context
    ↓
Start working

Contorium enables:

New session
    ↓
Read project intelligence
    ↓
Understand current state
    ↓
Continue working

Ask Your Project

Contorium makes project intelligence accessible to both developers and AI agents.

contorium ask "Why was MCP added?"
contorium ask "What changed recently?"
contorium ask "What do we know about authentication?"
contorium ask "Is this decision still valid?"

The goal is not simply retrieving text.

It is connecting the relevant pieces of project knowledge.

How It Works

Workspace Activity
        ↓
    Collection
        ↓
     Parsing
        ↓
 Project Structure
        ↓
 Knowledge Graph
        ↓
 Intent & State
        ↓
 Project Intelligence
        ↓
 AI-ready Context / Handoff
        ↓
 Any AI Tool

Contorium stores project intelligence locally inside:

.contora/

The project carries its own accumulated understanding instead of tying it to a particular AI provider or session.

Architecture

Contorium separates project intelligence from the AI tool using a local, structured architecture.

AI Tools (Cursor · Claude · Codex · …)
    │
    ▼
IDE · MCP · CLI  (adapters)
    │
    ▼
CIL — Cognitive Interaction Layer
    │
    ▼
PIL — Project Intelligence Layer
    │
    ▼
.contora/

CIL — Cognitive Interaction Layer

CIL is the interaction layer between AI agents, developers, and project intelligence.

It provides the mechanisms needed to query, capture, and transfer project knowledge.

It is architecture — not the product brand.

PIL — Project Intelligence Layer

The deterministic local store of structured project intelligence:

STATE · INTENT · DECISION · WHY
TIMELINE · IMPACT · PROVENANCE · CONFIDENCE

PIL does not reason. It preserves.

`.contora/`

The intelligence stays with the project.

Local-first. Project-centric. Portable.

Deeper guides: docs/OVERVIEW.md · docs/PIL_RUNTIME.md · docs/CIL.md

Three Unified Operations

Operation	Meaning
Capture	Record focus, notes, decisions
Inspect	Explore state, decisions, timeline, health
Transfer	Export compact context into a new AI session

contorium capture decision
contorium inspect state
contorium transfer context
contorium ask "What is this project becoming?"

Not Another AI Memory System

Contorium is related to AI memory — but it is not intended to be just another chat-memory or retrieval system.

System	Primarily preserves
Chat Memory	Conversations
RAG	Retrieved information
Git	Code and file history
Context Files	Explicit instructions
Contorium	Project intelligence

The goal is to connect:

What changed
     ↓
Why it changed
     ↓
What happened
     ↓
What remains true
     ↓
What comes next

Memory is a capability. Project Intelligence is the goal.

What Contorium Is Not

Contorium is not:

an autonomous coding agent
a replacement for your AI coding tool
a task generator
a system that decides what you should build
a replacement for Git

The developer remains in control.

Contorium preserves project understanding so humans and AI can work from the same evolving state.

Quick Start

Requirements

Node.js 18+
npm
VS Code / Cursor for the IDE extension
An MCP-compatible AI tool for MCP integration

Clone and build

git clone https://github.com/ContoriumLabs/contorium.git
cd contorium

npm install
npm run compile

VS Code / Cursor

npm run vsix

Then:

Open Extensions
Select Install from VSIX
Choose the generated .vsix
Reload the window
Open your project
Set the current focus
Transfer AI-ready project context when needed

Full guide: docs/IDE_EXTENSION.md · docs/INSTALL.md

MCP

Expose project intelligence to MCP-compatible AI tools:

npm install -g @contorium/mcp

claude mcp add --scope project contorium -- npx @contorium/mcp

codex mcp add contorium -- npx @contorium/mcp

Set the workspace when needed:

CONTORIUM_WORKSPACE=/path/to/project

Preferred agent operations include:

ask_project
transfer_project
inspect_state · inspect_intent · inspect_decision
capture_focus · capture_note · capture_decision
get_knowledge_health · get_review_queue

Full guide: docs/MCP.md · packages/mcp/README.md

CLI

npx contorium init .
npx contorium sync .
npx contorium ask "What is this project?"
npx contorium transfer context
npx contorium lifecycle
npx contorium review
npx contorium status .

Full guide: docs/CLI.md

Clear Project Intelligence

To remove the local project intelligence store:

macOS / Linux

rm -rf .contora

Windows PowerShell

Remove-Item -Recurse -Force .contora

Design Principles

Project-centric

The project is the source of truth.

Persistent

Project understanding should survive sessions, tools, and model changes.

Structured

Relationships between decisions, code, intent, and history matter more than isolated text.

Human-led

AI can understand the project. Humans decide what the project becomes.

Local-first

Project intelligence should stay close to the project and remain portable.

Optional AI Layer

Contorium works without LLMs.

Optional AI improves explanation, story, essence, and suggested questions.

AI is an interpreter — not the source of truth.

See docs/AI_LAYER.md.

Vision

AI coding is moving beyond one-shot code generation toward long-running, multi-agent development.

As agents become more capable, another layer becomes increasingly important:

the project's own intelligence.

The future of AI-assisted development may not be:

Human → AI → Code

but:

                    Project Intelligence
                   ↙        ↓        ↘
               Agent A    Agent B    Agent C
                   ↘        ↓        ↙
                     Project

Different models and tools can change.

The project's accumulated understanding should not have to.

AI can write the code.
Contorium helps it understand the project.

Links

Documentation: docs/README.md · Install · Overview

Website: https://www.contorium.dev

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

License: MIT