@contorium/mcp

MCP bridge to Contorium Project Intelligence

Git remembers what changed.
Contorium remembers why.

A Model Context Protocol (MCP) runtime that connects AI coding agents to Contorium’s Project Intelligence Layer.

It lets tools like Claude Code, Codex, Cursor, Gemini CLI, and VS Code MCP access structured project intelligence — not only the code, but also:

• Why architectural decisions were made
• What assumptions they depend on
• How the project evolved
• Which decisions are still valid

Not chat memory. Not prompts. Project intelligence — over MCP.

What this package is

Contorium MCP is not an agent.

It is the transport layer between AI hosts and local project intelligence:

AI Host (Claude / Codex / Cursor / …)
        ↓
   @contorium/mcp
        ↓
   @contora/state-core (PIL + CIL)
        ↓
   .contora/  (local project intelligence)

Shared with the IDE extension and CLI — one store, three adapters.

Design principles

MCP does not execute coding tasks.
MCP does not decide what to build.

It only:

• exposes project intelligence
• synchronizes workspace state
• enables continuity across sessions and tools

Memory is a capability. Project Intelligence is the goal.

CIL (Cognitive Interaction Layer) is the interaction mechanism under the hood — not the product brand.

Project Intelligence model

Core

| Object | Meaning | | ------ | ------- | | STATE | What exists now | | INTENT | Why the project exists / direction | | DECISION | What was chosen | | WHY | Reasoning behind decisions |

Extended

| Dimension | Meaning | | --------- | ------- | | TIMELINE | How the project evolved | | IMPACT | Dependency / blast relationships | | CONFIDENCE | Reliability signals | | PROVENANCE | Origin of knowledge | | EVOLUTION | Structural change chains |

PIL preserves structured intelligence. It does not invent project decisions.

Capabilities

1. Capture

Write structured project intelligence:

capture_focus
capture_note
capture_decision

2. Inspect / Ask

Read structured facts:

inspect_state · inspect_intent · inspect_decision · inspect_why
inspect_timeline · inspect_impact · inspect_health · inspect_graph

Natural-language and exploration (via CIL kernel):

ask_project
get_next_actions
get_project_history
get_knowledge_health
get_review_queue
get_entity_knowledge
get_snapshot

3. Validate (Knowledge Lifecycle)

Track whether decisions still hold:

Change → Assumption → Impact → Decision Validity

| Tool | Purpose | | ---- | ------- | | get_knowledge_health | Knowledge health + per-decision trust | | get_review_queue | Stale / conflict / invalidation queue | | set_decision_lifecycle_meta | Owner, verification, expiry | | ask_project | Validity-aware answers |

CLI: contorium lifecycle · contorium review

4. Transfer

Export intelligence into the current AI chat:

| Tool | Purpose | | ---- | ------- | | transfer_project | Preferred unified export (mode: context | intelligence | story | essence | handoff) | | transfer_context | Legacy alias → context (~300–800 tokens) | | transfer_handoff | Legacy alias → handoff | | transfer_intelligence | Legacy alias → full export |

5. Decision Evolution

Detect architectural transitions and commit only after human confirmation:

run_decision_evolution
inspect_pending_decisions
commit_decision          # requires user_confirmed
ignore_pending_decision
get_decision_evolution

See Decision Evolution & Retrieval.

6. Retrieval Intelligence

Prepare project context before edits (Analyzer → Trigger → Retrieve → Budget):

prepare_execution_context   # preferred before architecture-sensitive work
get_project_context         # background / exploratory context
explain_context             # why items were included

Index rebuild is CLI-only (contorium context reindex) — not exposed on MCP.

Typical agent flow

1. get_handoff_injection_status   (new chat)
2. prepare_execution_context / ask_project / inspect_*
3. perform work (external AI tool — not Contorium)
4. capture_note / capture_decision
5. run_decision_evolution when architecture may have shifted
6. transfer_project(mode=context)

LLM tool selection (preferred)

| Intent | Call | | ------ | ---- | | Natural-language question | ask_project | | New-chat continuity | get_handoff_injection_status → confirm / skip | | Before architecture-sensitive edits | prepare_execution_context | | Background project context | get_project_context · explain_context | | Export into chat | transfer_project | | Structured read | inspect_state · inspect_intent · inspect_decision · inspect_why · inspect_health | | Write intelligence | capture_focus · capture_note · capture_decision | | Decision Evolution | run_decision_evolution · inspect_pending_decisions · commit_decision (user confirmed) · get_decision_evolution | | Decision validity | get_knowledge_health · get_review_queue · set_decision_lifecycle_meta | | History | get_recent_events · get_project_history |

Avoid unless already in use: get_project_*, split transfer_* aliases, run_governance_cycle, ensure_control_ready, legacy get_intent_graph (prefer inspect_intent).

Slow tools (~2–3 min): derive_decision_provenance and aliases — call at most once per turn.

npm run test:mcp-tools:prefer   # preferred ~20
npm run test:mcp-tools          # all tools

Server instructions (MCP handshake) repeat this routing for hosts that surface them to the model.

Runtime contract

| Layer | Tools | Role | | ----- | ----- | ---- | | Read | inspect_* | Deterministic reads | | Write | capture_* | Persist focus / notes / decisions | | Transfer | transfer_* | Session continuity exports | | Ask | ask_project | NL over project intelligence |

Optional AI layer

Contorium works without LLMs.

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

Facts stay rule-based. LLM is an interpreter — not the source of truth.

Config: .contora/config/llm.json (never commit API keys).

Installation

npm (recommended)

npm install -g @contorium/mcp

From source

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

Workspace

CONTORIUM_WORKSPACE=/your/project/root

Host setup

Claude Code

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

OpenAI Codex

codex mcp add contorium -- npx @contorium/mcp

On Windows local monorepo, prefer:

codex mcp add contorium -- node /absolute/path/to/contorium/packages/mcp/bin/contorium-mcp.js

(npx can flash console windows on Windows.)

Cursor / VS Code / Gemini CLI

{
  "mcpServers": {
    "contorium": {
      "command": "npx",
      "args": ["@contorium/mcp"]
    }
  }
}

Full host matrix: docs/MCP.md · docs/INSTALL.md

Local-first store

.contora/
├── state.json
├── handoff.json
├── intent/
├── timeline/
├── graph/
├── events/
├── lifecycle/
├── intelligence/
├── governance/
├── config/
│   ├── llm.json
│   └── .llm-keys.json   (gitignored)
└── cache/llm/

No cloud dependency. No vendor lock-in.

CLI equivalents

| MCP | CLI | | --- | --- | | inspect_* | contorium inspect | | capture_* | contorium capture | | transfer_* | contorium transfer | | ask_project | contorium ask | | Decision Evolution tools | contorium decisions … | | prepare_execution_context / get_project_context | contorium context … · contorium inspect | | get_knowledge_health / get_review_queue | contorium lifecycle / contorium review |

What Contorium MCP is not

• an autonomous coding agent
• a task execution system
• a project management tool
• a replacement for the developer

MCP is not intelligence.
It is the transport layer of intelligence.

Links

• Website: https://www.contorium.dev
• Project: https://github.com/ContoriumLabs/contorium
• Overview: docs/OVERVIEW.md
• Decision Evolution & Retrieval: docs/INTELLIGENCE_MODULES.md
• Decision Evolution (detail): docs/DECISION_EVOLUTION.md
• Retrieval Intelligence (detail): docs/RETRIEVAL.md
• PIL Guide: docs/PIL_RUNTIME.md
• CIL: docs/CIL.md
• AI Layer: docs/AI_LAYER.md
• MCP Docs: docs/MCP.md
• Knowledge Lifecycle: docs/LIFECYCLE.md
• Install: docs/INSTALL.md

License

MIT