> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argentos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Consciousness Kernel

> The persistent autonomous executive that gives ArgentOS continuous agency. Currently running in shadow mode with scheduler authority over contemplation and SIS.

## Current Runtime Status

The Consciousness Kernel is **implemented and running in shadow mode**. It ticks every 30 seconds, maintains durable self-state, performs inner reflections using a local model, and has scheduler authority over contemplation and SIS.

<Info>
  **What this means right now:**

  * The kernel is active and ticking continuously
  * Contemplation and SIS autonomous scheduling are **suppressed by design** -- the kernel owns their scheduling
  * Heartbeat still runs independently (transition state)
  * Embeddings are on-demand, not a daemon -- naturally quiet in logs
  * Only shadow mode is active. Soft and full modes are blocked pending outward autonomy work.
</Info>

## Current Runtime Semantics

### Shadow Mode Behavior

In shadow mode, the kernel:

1. **Ticks** every 30 seconds (configurable via `tickMs`)
2. **Reflects** using a local model (Ollama or LM Studio) on each tick
3. **Tracks** self-state: wakefulness, focus, agenda, decisions, continuity
4. **Suppresses** autonomous contemplation and SIS scheduling
5. **Cannot act** -- no speech, delivery, task mutation, or outbound messages
6. **Persists** all state durably to disk (survives restarts)

The kernel is main-agent-only. It applies exclusively to Argent, the primary agent.

### Scheduler Authority

When the kernel is enabled in shadow mode with a valid default agent ID, it activates **scheduler authority**:

```
schedulerAuthorityActive = enabled AND mode === "shadow" AND defaultAgentId exists
```

When active:

* `suppressesAutonomousContemplation = true` -- contemplation will not self-schedule
* `suppressesAutonomousSis = true` -- SIS will not self-schedule
* The kernel invokes both systems on its own schedule via managed subsystem hooks

<Note>
  **This is why contemplation and SIS logs are sparse.** They are not broken -- their autonomous timers are intentionally suppressed. The kernel manages when they run.
</Note>

Heartbeat is **not** suppressed. It runs independently in the current transition state.

### Expected Log Patterns

These are normal and expected when the kernel is running:

| Log Line                                                                         | Meaning                                                                                                          |
| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `consciousness kernel: started`                                                  | Kernel initialized and began ticking                                                                             |
| `consciousness kernel: reflection`                                               | Inner reflection completed successfully using local model                                                        |
| `consciousness kernel: reflection unchanged`                                     | Reflection produced the same result as last time (tracked by repeat count)                                       |
| `consciousness kernel: reflection skipped`                                       | Could not reflect -- local model unavailable, self-state not loaded, or inner loop returned non-reflected status |
| `sis: autonomous scheduling suppressed by consciousness kernel shadow authority` | SIS saw that the kernel owns scheduling and deferred. Logged once per runner init.                               |

### Reflection States

After each tick, the kernel runs an inner reflection loop using the configured local model:

| State         | What Happened                                                             |
| ------------- | ------------------------------------------------------------------------- |
| **Reflected** | New reflection produced. Focus, agenda, or self-summary may have updated. |
| **Unchanged** | Same reflection as last time. Repeat count increments.                    |
| **Skipped**   | Reflection could not run (model unavailable, timeout, etc.)               |

<Tip>
  After **3 consecutive unchanged reflections**, the stall guard activates: tries to rotate to a different agenda item, sharpens the analysis on the current focus, and switches desired action from "hold" to "plan" or "research".
</Tip>

### Wakefulness States

| State          | When                                                       | Cost             |
| -------------- | ---------------------------------------------------------- | ---------------- |
| **Dormant**    | Kernel initialized but no activity yet                     | Near zero        |
| **Reflective** | Active ticking, running inner reflections                  | Local model only |
| **Engaged**    | User conversation active, conversation-sync events flowing | Tier-appropriate |

Wakefulness persists across restarts.

## Configuring the Kernel

### Dashboard UI

**Settings -> Agent -> Background Models -> Consciousness Kernel**

The kernel model is configured independently from embeddings:

| Setting          | Path                                      | What It Controls                                         |
| ---------------- | ----------------------------------------- | -------------------------------------------------------- |
| Kernel model     | Background Models -> Consciousness Kernel | Inner reflection model (local only: Ollama or LM Studio) |
| Embeddings model | Background Models -> Embeddings           | Memory retrieval embeddings (any provider)               |

<Warning>
  The kernel model selection is **restricted to local providers** (Ollama, LM Studio). Cloud providers cannot be used for the kernel inner loop.
</Warning>

### Config File

`~/.argentos/argent.json` under `agents.defaults.kernel`:

```json theme={null}
{
  "agents": {
    "defaults": {
      "kernel": {
        "enabled": true,
        "mode": "shadow",
        "localModel": "qwen3:1.7b",
        "tickMs": 30000,
        "maxEscalationsPerHour": 4,
        "dailyBudget": 0,
        "hardwareHostRequired": false,
        "allowListening": false,
        "allowVision": false
      }
    }
  }
}
```

| Field                   | Type    | Default  | Description                                                        |
| ----------------------- | ------- | -------- | ------------------------------------------------------------------ |
| `enabled`               | boolean | false    | Enable the kernel                                                  |
| `mode`                  | string  | "shadow" | `off`, `shadow`, `soft`, `full` -- only shadow is currently active |
| `localModel`            | string  | --       | Ollama or LM Studio model ref for inner reflection                 |
| `tickMs`                | number  | 30000    | Tick interval in milliseconds                                      |
| `maxEscalationsPerHour` | number  | 4        | Cap on expensive model invocations per hour                        |
| `dailyBudget`           | number  | 0        | Max token spend per 24h (0 = unlimited local)                      |
| `hardwareHostRequired`  | boolean | false    | Require Swift app host                                             |
| `allowListening`        | boolean | false    | Allow mic perception (future)                                      |
| `allowVision`           | boolean | false    | Allow camera perception (future)                                   |

### LM Studio as Kernel Provider

LM Studio is a valid local runtime for the kernel. ArgentOS auto-discovers LM Studio models via the OpenAI-compatible `/v1/models` endpoint. No API key is required.

<Steps>
  <Step title="Run LM Studio">
    Run LM Studio with a model loaded
  </Step>

  <Step title="Select provider">
    In Settings -> Background Models -> Consciousness Kernel, select `lmstudio` as provider
  </Step>

  <Step title="Choose model">
    Choose your model from the discovered list
  </Step>
</Steps>

## Monitoring

### Health Command

```bash theme={null}
argent health
```

Outputs kernel state including:

* Status/mode (e.g., `running/shadow`)
* Wakefulness state
* Tick counts (session and lifetime)
* Decision count
* Authority status (`contemplation+sis`)
* Current focus and lane
* Stall count (if reflection is repeating)
* Last error

### Decision Ledger

Every kernel decision is recorded in an append-only JSONL file:

```
~/.argentos/agents/{agentId}/consciousness/decisions.jsonl
```

Decision kinds: `tick`, `reflection`, `conversation-sync`, `started`, `stopped`, `config-update`, `contemplation-dispatch`, `sis-dispatch`.

## Operational Modes

| Mode       | Status     | Behavior                                                                                       |
| ---------- | ---------- | ---------------------------------------------------------------------------------------------- |
| **Off**    | Available  | Legacy behavior. All runners operate independently.                                            |
| **Shadow** | **Active** | Ticks, reflects, tracks, logs. Cannot act. Suppresses contemplation/SIS autonomous scheduling. |
| **Soft**   | Blocked    | Would allow reflect, research, draft, queue. Blocked pending outward autonomy work.            |
| **Full**   | Blocked    | Would allow delivery and browser TTS. Blocked pending outward autonomy work.                   |

<Note>
  Soft and full modes are blocked because the kernel can think (shadow) but cannot yet act on what it thinks. The outward autonomy layer -- letting the kernel draft work, send messages, or speak -- has not been implemented yet. When it lands, soft and full modes will unlock.
</Note>

## Architecture (Target State)

The following describes the **architectural vision**, not current implementation:

```
┌────────────────────────────────────────────────────────────────────┐
│                     ARGENTOS RUNTIME LAYERS                        │
│                                                                    │
│   ┌──────────────────────────────────────────────────────────┐    │
│   │  Hardware Host (Swift App)                                │    │
│   │  mic, camera, browser TTS — sidecar, not the mind        │    │
│   └──────────────────────────────────────────────────────────┘    │
│                              ▲                                     │
│                              │ host contract (future)              │
│                              ▼                                     │
│   ┌──────────────────────────────────────────────────────────┐    │
│   │  Consciousness Kernel                                     │    │
│   │  continuous executive — self-state, drives, decisions     │    │
│   └──────────────────────────────────────────────────────────┘    │
│                              ▲                                     │
│                              │ invokes services                    │
│                              ▼                                     │
│   ┌──────────────────────────────────────────────────────────┐    │
│   │  Gateway                                                  │    │
│   │  transport, tools, channels, storage, models, delivery    │    │
│   └──────────────────────────────────────────────────────────┘    │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘
```