v2.2 · state-core

Shared workspace state layer

One state system in .contora/. IDE, MCP, and CLI are peer session views — not separate memory stores or integration adapters.

Architecture model

Workspace (filesystem) Contorium State Layer (.contora/) Session views (multi-client)

IDE windows MCP agents CLI processes AI tools

state.json is workspace truth. Each client observes the same state from a different perspective.

Dual-mode state engine

Event-driven — IDE writes events/*.jsonl
Scan-driven — MCP/CLI bootstrap from workspace scan
Merged — scan supplements git/paths; does not overwrite task/notes

v2.2 source metadata

Optional source block in state.json records mode, last writer, and timestamp.

Package layout

packages/state-core/
  scanner/ bootstrap/
  state-builder/ dualMode.ts
packages/cli/     CLI view
packages/mcp/     MCP view + sync
src/adapters/   IDE view bridge

Local-first: `.contora/`

<workspace-root>/
└── .contora/
    ├── state.json
    ├── events/
    ├── state-builder/
    ├── intelligence/
    ├── intent-graph/
    ├── state-engine/
    └── mcp/

Concept map

Term	v2 meaning
IDE / MCP / CLI	session view
Window / Agent	session view
`state.json`	workspace truth
`.contora/`	system root

Full architecture doc (Markdown) →

Install a session view

IDE extension, MCP server, or CLI — all read the same workspace state.

Documentation Install