Compile knowledge for the machine. Distill understanding for the human.
A local-first knowledge operating system that ingests raw source material, compiles it into structured semantic knowledge, creates scoped research workspaces for hard questions, and generates durable artifacts. The key insight: compilation, not indexing. The deterministic control plane owns all state; the AI proposes, the system decides.
Links: GitHub · Releases · Docs
People accumulate source material — papers, articles, repos, notes, transcripts — faster than they can organize or use it. The standard tooling answer is search: index everything, embed it into vectors, retrieve on demand. But search returns fragments. It does not produce understanding.
RAG systems and chat-with-docs wrappers treat your knowledge base as a retrieval target. You ask a question, the system finds the closest embedding, and you get a plausible-sounding answer with no provenance chain, no contradiction detection, and no way to verify what was synthesized from what. The knowledge stays inert. You are doing the same cognitive work every time you revisit a topic.
There is no system that takes a corpus of raw material and turns it into a maintained, inspectable, compiled knowledge base — one where the structure is visible, the provenance is tracked, the contradictions are surfaced, and the outputs compound over time rather than being discarded after each session.
Intentional Cognition OS treats knowledge management as a compilation problem, not a search problem. Raw sources go in. Structured semantic knowledge comes out — summaries, concept pages, entity pages, topic syntheses, contradiction notes, backlinks. All of it stored as plain markdown files, all of it traceable back to source material, all of it recompilable when sources change.
The system enforces a hard boundary between deterministic and probabilistic operations. The kernel (TypeScript + SQLite + JSONL) owns all state: file storage, mount registry, task lifecycle, provenance chains, audit trails, promotion rules. The compiler (Claude API) proposes content. The kernel decides what gets stored, where, and under what conditions. The AI never writes directly to audit, policy, or promotion tables.
For hard questions, the system creates episodic research workspaces — temporary scoped environments with evidence, notes, drafts, and critiques. Multiple agents can work a single task. When the task completes, durable value is promoted back to the knowledge base and the temporary workspace is archived. Cognitive procfs views (_proc/status.md) provide computed, read-only task state for agent self-inspection and multi-agent coordination.
| Aspect | Details |
|---|---|
| Who | Researchers, analysts, engineers, and operators who accumulate source material and need compiled, auditable knowledge — not another chat interface |
| What | Knowledge operating system with six-layer architecture: raw corpus, semantic knowledge, episodic tasks, artifacts, recall, and audit |
| Where | Local-first on your machine (Node.js 22+). No infrastructure required. Remote/team mode planned for Phase 5 |
| When | When you need to build and maintain a knowledge base from source material — ongoing research, competitive analysis, technical due diligence, learning a new domain |
| Why | Compilation produces structured, inspectable, compounding knowledge. Search produces one-off answers with no audit trail |
| Layer | Technology | Purpose |
|---|---|---|
| Runtime | TypeScript / Node.js 22+ | Type-safe application logic, Claude SDK native |
| Package Manager | pnpm 10.x (monorepo) | Workspace management across 4 packages |
| State DB | better-sqlite3 (WAL mode) | Deterministic local state — mounts, sources, tasks, provenance |
| Audit Traces | JSONL + integrity chains | Append-only event log with SHA-256 tamper detection |
| AI | @anthropic-ai/sdk (Claude API) | 6 compiler passes + ask pipeline + report/slide rendering |
| Validation | Zod | Runtime schema checking for all domain types |
| Search | SQLite FTS5 | Full-text search over compiled wiki pages |
| CLI | Commander.js | 14 commands via ico binary |
| Testing | Vitest + V8 coverage | 878 tests across 61 test files |
| Build | tsup | TypeScript bundling per package, ESM-only |
| Linting | ESLint 10 + typescript-eslint | Strict type-checked linting with import sorting |
| CI/CD | GitHub Actions | Lint, typecheck, test, security audit, auto-release |
- Compilation, not indexing — Sources are compiled into structured pages (summaries, concepts, entities, topics, contradictions), not embedded into a vector store
- Deterministic control plane — The kernel owns all state and lifecycle. The model proposes content; it never directly mutates audit, policy, or promotion tables
- Semantic filesystem — Knowledge is mounted and operable (mount, index, compile, lint, diff, inspect), not hidden behind an API
- Episodic research workspaces — Hard questions get scoped task environments with collector, summarizer, skeptic, and integrator agents
- Full provenance chain — Every derived output traces back to its source through the audit layer. Recompilation is always possible from L1
- Cognitive procfs — Computed, read-only views over task state (
_proc/status.md) for agent self-inspection and multi-agent coordination
Skill: System Analysis / Version: v0.5.0 / Author: Jeremy Longshore / License: MIT
ICO is a local-first knowledge operating system that ingests raw documents, compiles semantic knowledge via Claude API, creates episodic research workspaces, and generates durable artifacts. Epics 1-8 are complete with Epic 9 (multi-agent research) in progress. The system ships 14 CLI commands, 6 compiler passes, a cognitive procfs module, and 878 tests across 4 packages — all ESM-only TypeScript on Node 22.
| Layer | Technology | Purpose |
|---|---|---|
| Runtime | Node.js 22+, TypeScript 5.x | ESM-only, strict mode |
| Package manager | pnpm 10.x workspaces | 4-package monorepo |
| CLI framework | Commander.js | 14 commands via ico binary |
| State DB | better-sqlite3 | Local SQLite — mounts, sources, tasks, provenance, audit |
| AI backend | @anthropic-ai/sdk (Claude) | 6 compiler passes, ask pipeline, report/slide rendering |
| Validation | Zod | Runtime schema checking for frontmatter, configs, events |
| Ingest | pdf-parse, turndown, gray-matter | PDF, Markdown, web-clip adapters |
| Search | SQLite FTS5 | Full-text search over compiled wiki pages |
| Build | tsup | TypeScript bundling, ESM output |
| Test | Vitest 4.x | 878 tests, 61 files, V8 coverage |
| Lint | ESLint 10 + typescript-eslint | simple-import-sort enforced |
| CI/CD | GitHub Actions | lint, typecheck, test; auto-release from conventional commits |
Six-layer storage model:
| Layer | Path | Mutability |
|---|---|---|
| L1 Raw Corpus | workspace/raw/ |
Append-only |
| L2 Semantic Knowledge | workspace/wiki/ |
Recompilable from L1 |
| L3 Episodic Tasks | workspace/tasks/<id>/ |
Per-task lifecycle |
| L4 Artifacts | workspace/outputs/ |
Promotable to L2 |
| L5 Recall | workspace/recall/ |
Adaptive (planned) |
| L6 Audit & Policy | workspace/audit/ |
Append-only JSONL |
Deterministic/probabilistic boundary — the single most important constraint. The kernel (SQLite, filesystem, JSONL traces) owns all durable state, policy, and control flow. The compiler (Claude API) proposes content. No model output writes directly to audit, policy, or promotion tables. Integrity chains (SHA-256 hash linking) protect trace tamper-evidence.
Cognitive procfs (_proc/) — read-only computed views (status.md, memory-map.md) materialized from SQLite state, inspired by Unix /proc. Agents read; none write.
| Decision | Trade-off | Rationale |
|---|---|---|
| SQLite over Postgres | No concurrent multi-process writes | Local-first, zero-config, deterministic |
| ESM-only, no CJS | Cannot require() from legacy code |
Clean module boundaries, verbatimModuleSyntax catches import bugs |
| Compilation over indexing | Higher latency on first ingest | Derived knowledge is inspectable markdown, not opaque vectors |
| Result<T,E> everywhere | More verbose call sites | Non-throwing error handling prevents silent failures |
| Atomic writes (.tmp, rename) | Slightly more disk IO | Prevents partial files on crash |
| 6 separate compiler passes | More API calls per source | Each pass is independently testable, cacheable, retriable |
| L4-to-L2 promotion gating | 7 validation rules + 3 anti-pattern checks | Prevents low-quality content from polluting semantic knowledge |
intentional-cognition-os/
packages/
types/ # Result<T,E>, Zod schemas, frontmatter types
kernel/ # Workspace, SQLite, mounts, sources, tasks, search, promotion, procfs
compiler/ # 6 passes, Claude client, ingest adapters, ask pipeline, renderers
cli/ # 14 commands, output formatting, workspace resolver
000-docs/ # Standards (008-021), epics, designs, specs, essays
.github/workflows/ # ci.yml, release.yml
| Command | Purpose |
|---|---|
pnpm install |
Install all workspace dependencies |
pnpm build |
Build all 4 packages (sequential, tsup) |
pnpm test |
Run 878 tests across all packages |
pnpm lint |
ESLint across all packages |
pnpm typecheck |
tsc --noEmit across all packages |
ico init <name> |
Create a new workspace |
ico mount <path> |
Register a source directory |
ico ingest |
Extract raw content from mounted sources |
ico compile |
Run 6-pass semantic compilation via Claude |
ico research <brief> |
Create scoped episodic task workspace |
ico ask <question> |
Query compiled knowledge with citations |
ico render |
Generate reports or slides from task output |
ico promote |
File L4 artifact into L2 wiki (gated) |
ico inspect task <id> |
View computed procfs views for a task |
ico status |
Show workspace state summary |
What's Working:
- Full ingest-compile-ask-render-promote loop operational end-to-end
- 878 tests passing (240 kernel, 332 compiler, 306 CLI) with V8 coverage
- Deterministic/probabilistic boundary enforced cleanly across all packages
- Promotion engine with 7 validation rules and 3 anti-pattern detectors
- FTS5 search with question-type-aware retrieval
- Cognitive procfs providing computed status views for agents
- Trace integrity chains with SHA-256 linking and secret redaction
- CI pipeline (lint + typecheck + test) green on every push
Areas Needing Attention:
| Area | Severity | Detail |
|---|---|---|
| Multi-agent orchestration | Medium | Epic 9 in progress — ico research creates workspaces but agent orchestration not yet wired |
| Recall layer (L5) | Low | Stub command only; spaced repetition not implemented |
| Eval framework | Low | Stub command; evaluation specs planned for Epic 10 |
| MCP server | Low | Design complete, not yet implemented |
| Field | Value |
|---|---|
| Repo | github.com/jeremylongshore/intentional-cognition-os |
| CI | GitHub Actions — lint, typecheck, test on push/PR to main |
| Release | Conventional-commit auto-versioning + CHANGELOG generation |
| License | MIT |
| Version | v0.5.0 |
| Tests | 878 across 61 files |
| Source LOC | ~23,227 TypeScript |
| Packages | 4 (types, kernel, compiler, cli) |
| CLI commands | 14 |
| Compiler passes | 6 |
| Author | Jeremy Longshore |