intentional-cognition-osICO Architecture

v0.11.0 · Local-first knowledge OS · deterministic control plane + probabilistic reasoning planev0.11.0 · local-first knowledge OS · two-plane architecture

ICO system architecture Monorepo with four TypeScript packages — cli, compiler, kernel, types. CLI orchestrates calls into the deterministic kernel (SQLite + workspace filesystem) and the probabilistic compiler (Claude API). Shared types sit beneath both planes. Deterministic Control Plane Kernel · SQLite · Workspace FS · JSONL audit Probabilistic Reasoning Plane Compiler · Claude API · agents & passes stdin kernel ops compile · ask · research reads state · writes traces atomic writes reads raw · writes wiki TLS Operator running ico CLI commands Operator terminal @ico/cli — Commander.js entry point with 14 commands @ico/cli Commander · bin: ico init · mount · ingest compile · ask · render research · promote lint · inspect · eval @ico/kernel — deterministic state, tasks, audit, promotion @ico/kernel deterministic · Result<T,E> • workspace / state • mounts / sources • tasks (state machine) • provenance / traces • audit-log (JSONL) • wiki-index · FTS5 • promotion / unpromote • archive / artifacts • logger / config / procfs Integrity features: • SHA-256 chained traces • atomic .tmp + rename • secret redaction • dual-write provenance • 7 promotion rules • 3 anti-pattern detectors proposes ✗ · decides ✓ owns durable state SQLite via better-sqlite3 — state, tasks, provenance tables SQLite better-sqlite3 migrations 001–003 Workspace filesystem — six-layer storage Workspace FS six-layer storage L1 raw/ L2 wiki/ L3 tasks/ L4 outputs/ L5 recall/ L6 audit/ append-only where provenance demands .tmp + rename @ico/compiler — Claude-powered reasoning passes and multi-agent research @ico/compiler probabilistic · model-driven Agents (Epic 9): • collector (FTS5, pure) • summarizer • skeptic (adversarial) • integrator • orchestrator (5-stage FSM) Passes (6): • summarize · extract • link · contradict • gap · synthesize Adapters: • markdown · pdf-parse • web-clip (turndown) Ask pipeline: • analyze · generate · verify Render: • report · slides • task-renderer · artifact-meta Infra: • api/claude-client (injected) • ingest-pipeline · token-tracker • staleness · validation proposes ✓ · decides ✗ @ico/types — Zod schemas, Result types, frontmatter schemas shared across packages @ico/types Zod schemas · Result<T,E> · frontmatter contracts implicitly imported by @ico/cli · @ico/kernel · @ico/compiler (workspace:* deps) Claude API via @anthropic-ai/sdk — Opus / Sonnet / Haiku Claude API @anthropic-ai/sdk Opus · Sonnet · Haiku CLI service persistence external API shared deterministic lane (amber) probabilistic lane (emerald) cross-plane read

pinch to zoom · tap and drag to pan

Architectural invariant

  • • Model proposes, system decides
  • • Kernel owns durable state
  • • Compiler never writes audit/policy
  • • All ops return Result<T,E>
  • • Writes are atomic (.tmp + rename)

Epic 9 research loop

  • • 5 stages: collect → synth → critique → integrate → render
  • • FSM with per-stage failure states
  • • Resume-aware orchestrator
  • • Token budget via ICO_MAX_RESEARCH_TOKENS
  • • L3→L4 hand-off in render stage only

Observability + integrity

  • • JSONL traces with SHA-256 hash chain
  • • Dual-write provenance (SQLite + JSONL)
  • • redactSecrets() on every trace payload
  • • FTS5 search over compiled wiki
  • • 958 tests passing at v0.11.0

Tooling surface

  • • pnpm 10 workspace · TS strict · ESM-only
  • • tsup builds (sequential workspace-concurrency=1)
  • • Vitest · ESLint 10 + typescript-eslint
  • • CI: lint · typecheck · test · osv-scanner
  • • Release: conventional-commits → auto-bump

intentional-cognition-os v0.11.0 · generated 2026-04-19 · grounded in pnpm-workspace.yaml + package deps + src/ topology