# Cognition OS

Cognition OS is an operating-system-adjacent framework that treats probabilistic inference, context, attention, and memory as schedulable, governable resources. It provides deterministic control, isolation, capability-based security, and provenance for non-deterministic computation, while keeping all learning and inference in userland services.

## What this is

- A **spec + reference design** for a “cognitive kernel” (control plane) and userland++ services.
- A place to define **contracts** (object model, syscalls/APIs, policy model, provenance) that can be implemented on top of classic OS kernels.

## What this is not

- **Not** “LLMs in kernel space.”
- **Not** an AGI project.
- **Not** a fork of FreeBSD/Linux (at least initially).

## Core principles

- Deterministic control plane; probabilistic workers.
- Capability-based security; no ambient authority.
- Explicit budgets (time, compute, context, risk).
- Provenance as a first-class output.
- Isolation domains for workers and tools.

## Repository layout

- `docs/` — narrative design docs (“why”).
- `spec/` — contracts and invariants (“must not change casually”).
- `freebsd/` — mapping to FreeBSD primitives (jails, Capsicum, kqueue, …).
- `linux/` — mapping to Linux primitives (namespaces, seccomp, LSM, epoll, …).
- `runtime/` — userland++ reference components (scheduler, tool broker, memory services).
- `examples/` — end-to-end flows and scenarios.

## Getting started

Start reading:
1. `docs/000-introduction.md`
2. `docs/010-design-goals.md`
3. `docs/030-architecture-overview.md`
4. `spec/cognitive-syscalls.md`

## Status

This repository is **pre-implementation**. The initial goal is to stabilize a minimal v0.1 contract for:
- cognitive object model
- cognitive syscalls/APIs
- provenance event model
- OS mapping notes (FreeBSD first, Linux mapping in parallel)

## CognitiveOS RFCs (Control-Plane / Kernel Primitives)

This repo includes a growing set of RFCs capturing the CognitiveOS design direction:
- RFC Index: `docs/RFC-INDEX.md`
- Kernel Roadmap: `docs/KERNEL-ROADMAP.md`
- RFC documents: `docs/rfcs/`

Key primitives covered so far:
- RFC-0007 Delegating Router (must-delegate invariant)
- RFC-0008 Capability & Guard framework
- RFC-0009 Event Ledger (append-only, hash-chained)
- RFC-0010 Guarded Emit syscall
- RFC-0011 Session Spawn primitive
- RFC-0012 Deterministic Retry controller