ContextOS

ContextOS is a context + resilience layer for autonomous AI agents, shipped as three published npm packages — @context-os/core (a DI-container engine), @context-os/cli (Commander surface), and @context-os/mcp (an MCP server over dual stdio + HTTP/SSE transport) — plus a React 19 + Vite + Tailwind v4 + Three.js spatial dashboard rendering a force-directed 3D knowledge graph.

The core wires multi-agent orchestration (TaskGraph DAG scheduler, SwarmOrchestrator, ConflictResolver) with genuinely hard resilience primitives: Merkle-linked tamper-evident audit logs, sliding-window circuit breakers with auto-quarantine, and CUSUM predictive-failure detection. Retrieval uses better-sqlite3 + sqlite-vec with local @xenova/transformers embeddings and tree-sitter parsing.

• 3 real npm packages + an MCP server
• Merkle audit logs · circuit breakers · DAG orchestration
• sqlite-vec vector search · local embeddings

Clean, shipped, and complementary to Agent-Forge. 190 commits.

Architecture

The repo is a TypeScript monorepo (Turborepo + npm workspaces, ESM-only) with four workspaces, all locked at v1.13.2: @context-os/core, @context-os/cli, @context-os/mcp, and a private workspace-dashboard.

@context-os/core's DI container (src/container/) is the spine everything else plugs into: tokens.ts defines ~45 typed Symbol keys and defaults.ts wires the default service graph, both inside src/container/; one level up, src/factory.ts#createContextOS() is the single public entry point that assembles the container. Beyond the orchestration/resilience primitives above, core also ships cognitive/, governance/ (capability tokens, trust scoring, a policy engine), and streaming/ subsystems, plus service modules for git-intelligence, graph-rag, temporal-graph, knowledge-graph, embedding, locking, mission, and repair.

@context-os/mcp enforces its own security boundary: an Allowed-Bucket whitelist. Paths are canonicalized via fs.realpathSync/path.resolve — defeating symlink and traversal escapes — and must resolve inside one of 13 fixed buckets (projects/, knowledge/, schemas/, archive/, log/, orgs/, root/, docs/, prompts/, daily/, packages/, workspace-cli/, workspace-dashboard/); 7 of the 13 are read-only for agents. Every document crossing this boundary is Ajv-validated against six schemas: soul, context, decision, memory, mission, capabilities.

How It Works

An agent talks to ContextOS over the MCP server's stdio or HTTP/SSE transport, which routes into core through createContextOS()'s DI graph.

1. Path resolution. The file path is canonicalized and checked against the Allowed-Bucket whitelist — a rejected path never reaches governance or storage.
2. Governance & validation. governance/ checks the caller's capability token and trust score, then the document is Ajv-validated against its schema (soul, context, decision, memory, mission, or capabilities) — an unauthorized or malformed write never reaches shared state.
3. Orchestration. For multi-agent work, TaskGraph and SwarmOrchestrator sequence the run; ConflictResolver settles competing writes.
4. Resilience. Every write lands in the Merkle-linked audit log; the circuit breaker and CUSUM detector watch for cascade-preceding patterns and auto-quarantine before one happens.
5. Live repair. The Sentinel watches the workspace via native fsevents and triggers immediate re-validation on change; a corrupted context.md or project file gets a Gemini 1.5 Pro repair from the Janitor Agent (v1.11.0), capped at three attempts per file.
6. Retrieval. Queries are embedded locally (@xenova/transformers, 384-dim MiniLM) and matched via sqlite-vec in better-sqlite3. A degraded, keyword-only result now says so in-band — in SearchResult.type, CLI text, --json output, and the MCP tool response — instead of failing silently.