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 stdio and Streamable HTTP) — plus a React 19 + Vite + Tailwind v4 + Three.js spatial dashboard rendering a force-directed 3D knowledge graph.

The core ships multi-agent orchestration (TaskGraph DAG scheduler, SwarmOrchestrator, ConflictResolver) with 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. 233 commits on develop as of 2026-10-21.

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. GitHub Releases stop at v1.6.1 and the newest CHANGELOG.md entry is 1.13.1.

@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 preferred entry point that assembles the container, though the CLI and MCP server skip it, using core's module-level singletons or direct construction. 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 a security boundary through core's validatePath: 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/); 6 of the 13 are read-only for agents.

How It Works

An agent talks to ContextOS over the MCP server's stdio or Streamable HTTP transport.

1. Path resolution. validatePath canonicalizes the path and checks it against the Allowed-Bucket whitelist — a rejected path never reaches storage — and workspace_write refuses the read-only buckets.
2. Write. The tool writes the file and, on develop, commits it every time. No capability token or schema is checked here: governance is a separate set of MCP tools, and validation runs afterwards.
3. Orchestration. For multi-agent work, the swarm_* tools drive SwarmOrchestrator and TaskScheduler; workspace_lock_* gives agents per-file locks.
4. Resilience. The circuit breaker and CUSUM detector are library primitives that nothing in core, the CLI or the MCP server feeds. The Merkle-linked audit log records task failures, quarantines, expired messages and tool-set drift, not file writes.
5. Live repair. The Sentinel watches the allowed buckets via chokidar and validates a changed SOUL.md, CONTEXT.md, memory.md or decisions.md; failures get a rule-based fix, then the Janitor Agent (v1.11.0), capped at three attempts per file. The Janitor calls gemini-1.5-pro, which Google shut down on 2025-09-29, so that fallback cannot succeed.
6. Retrieval. Queries are embedded through a Gemini → Ollama → local failover chain (@xenova/transformers, 384-dim MiniLM by default) and matched via sqlite-vec in better-sqlite3. If embedding fails or returns the wrong width, the query degrades to keyword-only FTS5 results, still labelled hybrid, with no notice.