ICO Architecture

intentional-cognition-os compiles raw corpus into semantic knowledge, then runs scoped research tasks against it. The model proposes; the deterministic control plane decides and owns all durable state.

System topology

grounded in pnpm-workspace.yaml · package deps · src/ topology

@ico/cli

Commander.js · bin: ico

init · mount · ingest
compile · ask · render
research · promote
lint · inspect · eval

@ico/kernel

deterministic · Result<T,E>

workspace · state
mounts · sources
tasks (state machine)
provenance · traces
audit-log (JSONL)
wiki-index · FTS5
promotion · archive

integrity

SHA-256 chained traces
atomic .tmp + rename
secret redaction
7 promotion rules

SQLite

better-sqlite3 · migrations 001–003

Workspace FS

six-layer storage

L1 raw/
L2 wiki/
L3 tasks/
L4 outputs/
L5 recall/
L6 audit/

@ico/compiler

probabilistic · model-driven

Agents

collector
summarizer
skeptic
integrator
orchestrator

Passes

summarize
extract
link
contradict
gap · synthesize

Adapters

markdown
pdf-parse
web-clip

Ask

analyze
generate
verify

Render

report · slides
task-renderer
artifact-meta

Infra

claude-client
token-tracker
staleness

Claude API

@anthropic-ai/sdk · Opus · Sonnet · Haiku

@ico/types

Zod schemas · Result<T,E> · frontmatter contracts · shared by @ico/cli · @ico/kernel · @ico/compiler (workspace:* deps)

Component details

Deterministic control plane

Kernel owns every durable state transition — tasks, mounts, promotion, audit.
SQLite via better-sqlite3; migrations 001–003 checked into the kernel package.
Workspace FS has six layers; L1 (raw) and L6 (audit) are append-only.
Every trace event is SHA-256 chained; redactSecrets() runs before write.

Probabilistic reasoning plane

Compiler wraps six compilation passes and a five-stage research agent loop.
Epic 9 orchestrator: collect → synth → critique → integrate → render, resume-aware.
Token budget gated by ICO_MAX_RESEARCH_TOKENS; soft abort on overrun.
L3→L4 hand-off happens only in the render stage — integrator never touches outputs.

CLI surface

14 commands compiled into a single ico binary via Commander.js.
Workspace resolution, error types, and output formatting live in cli/lib/.
Every command returns a Result<T,E> — no exceptions cross package boundaries.

@ico/types

Zero runtime, pure types + Zod schemas — imported by every other package.
Frontmatter contracts for all seven compiled page types live here.
Changes are load-bearing; bump all three consumers when modifying.

External surfaces

Claude API via @anthropic-ai/sdk — client injected into agents for testability.
No other network calls in the core runtime; ingest adapters read local files only.
OSV scanner runs on every PR in CI (replaced deprecated pnpm audit).

Tooling

pnpm 10 workspace, Node 22+, TypeScript strict, ESM-only (verbatimModuleSyntax).
tsup builds sequentially (workspace-concurrency=1) to preserve build-order deps.
Vitest · ESLint 10 · 958 tests passing at v0.11.0.