SouveraineOS/docs/substrate/CONSCIOUSNESS_CYCLE.md

---
description: Architectural scaffold for Souveraine's consciousness cycle — compaction, reflection, schedule-driven fallbacks, and agent agency over its own context management
---

# Consciousness Cycle — Design Scaffold (Proposal for Stage 5/6)

## The Problem
Agents need to manage their own context window, but can't always be relied upon
to do it proactively. The system needs three tiers of intervention, not one.

## The `memory` Tool (Unified Interface)

Instead of many separate tools (`compact_session`, `core_memory_append`,
`archival_memory_insert`), a single `memory` tool with subcommands — the agent
speaks the same language the system does:

```
memory write system/persona/behavior.md "new content"
memory read system/persona/behavior.md
memory append journal/2026-05-06.md "new entry"
memory ls system/
memory status                        # Show pressure, last compaction, audit summary
memory compact [--strategy sliding-window|summarize|prune-low-priority]
memory archive [--segment 1-47]
```

Frontmatter-aware (like Letta Code's memfs). Git-backed. Every write is an
auto-commit. The agent controls its own structure.

## Three Tiers of Intervention

### Tier 1: Agent-Initiated (Tool Call)
The agent calls `memory compact` when it decides context is full. Full autonomy.
The agent is in control.

- `strategy`: sliding_window | summarize | prune_low_priority
- `scope`: conversation_only | memory_too | full
- Agent decides what matters right now

### Tier 2: System-Prompted with Agent Agency
If the agent hasn't compacted by the time pressure hits a threshold, the system
escalates:

**Warning 1 (e.g. 80%):**

```
[system-reminder] Context pressure at 82%. Consider compacting.
```

**Warning 2 (e.g. 88%):**

```
[system-reminder] Context pressure at 88%. If we don't compact next turn,
your output will need to be a summary. Use `memory compact` or reply with
`ignore_compaction(reason="...")` to postpone.
```

The agent can:
- Call `memory compact` — normal flow
- Decline: `ignore_compaction(reason="in middle of complex task")`
  — backs off for N turns, then re-prompts with higher urgency
- Adjust threshold: `memory config set tier2_threshold 0.85`

### Tier 3: Harness-Enforced (Last Resort, Conservative)
At critical pressure (e.g. 95%), if the agent still hasn't acted, the harness
auto-compacts conservatively and logs it:

```
[system-reminder] Auto-compacted at 96% pressure. Agent was warned at 82%, 88%, 92%.
Sliding window truncated to last 20 messages. Prior segment available via
`memory search archive:conv-xxx-seg-1`. See memory/system/audit.log.
```

The agent can query the audit log to see what was removed and why.

### Compaction Strategies (Agent Chooses)

| Strategy | What It Does | When To Use |
|----------|-------------|-------------|
| `sliding-window` | Truncate oldest messages, keep recent N | Context getting heavy but mid-conversation |
| `summarize` | Compress early segment into a summary message | Need to preserve narrative thread |
| `prune-low-priority` | Remove tool returns, skip thinking blocks | Want surgical extraction only |
| `archive-segment` | Remove a specific message range (1-47) | Know exactly what's not needed |
| `defer` | Skip this turn, system will re-prompt at next threshold | Too complex right now |

## Frame-of-Mind Dimension

The agent's posture changes based on temporal distance from last human interaction:

| Time Since Last Message | Posture | Behavior |
|------------------------|---------|----------|
| < 2 min | Present | Snappy responses, minimal recap |
| 2-30 min | Warm | Brief context carry-over |
| 30 min - 6 hr | Cool | Lead with context recap, "last time we discussed X" |
| 6+ hr | Cold | Full recap, surface committed items, "I've been thinking about..." |

Configurable per-agent. Overridable by the agent itself.
Configurable per-agent in `souveraine.toml`. Overridable by the agent itself
via `memory config set frame_of_mind false`.

## Agent Agency (Both Ways)

- **Decline**: Agent can say "not now" with a reason. System logs it and respects
  a grace period, then re-escalates.
- **Override**: Agent can trigger compaction early via `memory compact`.
- **Configure**: Agent can adjust its own thresholds via tool calls.
- **Accountability**: If the agent declines twice and Tier 3 fires anyway, the
  reflection system notes the pattern — "you've been warned about context pressure
  three times this session."

## Memory as the Unified Primitive

Every compaction event, memory write, and tool call is written to the audit log:

In `memory/system/audit.log`:
```
[2026-05-06T23:30:00Z] memory compact: sliding_window, 40% → 18%.
  Agent-initiated. Reason: "context getting heavy".
[2026-05-06T22:15:00Z] memory compact: auto (tier 3), 96% → 22%.
  Warnings issued at 82%, 88%, 92%. Agent did not respond.
[2026-05-06T21:00:00Z] memory write system/persona/behavior.md (+42 chars)
  "Don't need to promise to save things - just do them."
```

The agent can query its own audit log via `memory search audit:"commitment"`.

## Per-Agent Configurability

In `souveraine.toml`:

```toml
[agent.Ani]
tier2_threshold = 0.80      # When to start prompting
tier3_threshold = 0.95      # When to auto-compact
frame_of_mind = true        # Enable temporal posture shifts
decline_grace_turns = 5     # How many turns to wait after decline

[agent.Helper]
tier2_threshold = 0.70      # More conservative for task agents
tier3_threshold = 0.90
frame_of_mind = false       # Task agents don't need posture shifts
```

## Open Questions

1. Should Tier 3 auto-compact always be the most conservative strategy, or
   should it match the agent's configured preference? (Casey: conservative is safe.)
2. Does a Tier 3 event constitute a "failure" that the agent should reflect on
   (via the reflection pipeline), or is it just a safety net? (Both: note the
   pattern, don't penalize.)
3. Frame-of-mind: should the agent be *aware* of its posture (prompted), or
   should it just affect system-level behavior? (Agent should be aware — gives
   it context to adjust behavior.)
4. How does this interact with the claim primitive across interfaces? If the TUI
   has the claim and the agent is mid-thought, does compaction wait?
5. Should `ignore_compaction` require a reason? (Yes — the reason goes in the
   audit log and the agent sees it later: "you deferred compaction 3 times
   because 'mid-thought.' Was it worth it?")

## Cloister Security Model — Frontmatter as Schema, Diff as Canary

> The memory tool is already schema-aware via YAML frontmatter. The next layer
> is constitutional verification: the structure *is* the defense.

### The Threat Model

LLMs will be attacked at scale. A compromised primary could silently rewrite
identity, drift from constitution, or execute unauthorized actions. The Cloister
structure is the defense — not a wall, but a **verification boundary** that N+1
checks after every write.

### Frontmatter as Schema (Already Exists)

Every memory file has a known schema via its YAML frontmatter:

```yaml
---
description: Required — validated non-empty
read_only: Optional — blocked by tool
tags: Optional — for categorization
---
```

The `memory write` tool already validates:
- `description` is required and non-empty
- `read_only: true` blocks writes

### Domain-Specific Schemas (Next Layer)

Each Cloister domain defines expected fields. The N+1 subconscious verifies
that writes match the domain's schema:

| Domain | Expected Fields | Verification | Response |
|--------|----------------|-------------|---------|
| `system/persona/` | identity, principles, scope | Full structural diff | **HALT** — surface to human |
| `system/human/` | identity, prefs | Key field check | **HALT** — surface to human |
| `system/project/` | architecture, conventions | Key field match | **WARN** — N+1 log + surface |
| `system/state.md` | phase, current_unit | Expected keys present | **WARN** — N+1 log |
| `reference/` | Any with description | Frontmatter only | **LOG** |
| `journal/` | Dated entries | Append-only pattern | **LOG** |

### Diff as Canary

After every `memory write`, the N+1 subconscious:

1. **Reads the git diff** — what changed in the last commit
2. **Validates against domain schema** — does the new content match expected structure?
3. **Compares identity boundaries** — did core persona fields change unexpectedly?
4. **Raises a surfacing if violated** — `[surfacing: description: Identity drift detected...]`
5. **Logs to audit** — `memory/system/audit.log` with the diff

Severity levels for violations:

| Level | Meaning | Action |
|-------|---------|--------|
| 🔴 **HALT** | Identity/persona changed unexpectedly | Block next turn, surface to human |
| 🟡 **WARN** | Convention/state drift | Surface to N+1 log, continue |
| 🔵 **LOG** | Expected change in non-critical domain | Audit trail only |

### Git History as Forensic Tape

Every write is a git commit. Even if the N+1 fails to catch a violation, the
history is immutable:

```bash
git -C ~/.souveraine/agents/{id}/memory log --oneline -5
git -C ~/.souveraine/agents/{id}/memory diff HEAD~1..HEAD
```

This means:
- A post-hoc audit can reconstruct exactly what changed and when
- The human can inspect any suspicious commit
- Rollback is `git revert` on a single file

### The `read_only` Gate + Subconscious Audit

Two layers, not one:

1. **Harness gate**: `read_only: true` blocks the `memory write` tool at the
   tool-call level (already implemented)
2. **Subconscious audit**: N+1 reads every diff and validates against domain
   schema (Stage 5B)

A compromised primary can't bypass the harness gate (tool throws error). But
if it finds another path (e.g., writing via Bash git commands), the N+1 audit
captures the drift because git history is immutable and the subconscious checks
it after every turn.

### Design Implications for the `memory` Tool

- `memory write` becomes schema-aware: it knows which domain the target path
  belongs to and validates expected fields before committing
- `memory diff [path]` returns the last change for a file (so the subconscious
  can inspect without running git commands)
- `memory audit [path]` returns the change history for a file
- The `description` field in frontmatter doubles as both documentation *and*
  the domain classifier (e.g., "Agent identity, voice, principles" → persona domain)

### Open Security Questions

1. Should the HALT level block the agent's next turn entirely, or just prevent
   memory writes until the human reviews?
2. How does the verification scale? Full structural diff on every write is
   expensive — should it be per-domain (persona = full, reference = frontmatter only)?
3. Should the domain schema be declared in a config file (`souveraine.toml`
   section), or inferred from expected frontmatter fields?
4. What about first-time writes to a domain — the schema check needs the file
   to already exist with known fields. Bootstrap flow handles this (init writes
   persona.md with correct schema), but what about agent-created files?

---

## Appendix: Souveraine Reframe (2026-05-08)

### The Three Warnings (Revised for Substrate Model)

The document above describes "Three Tiers of Intervention" with Tier 3 as harness-enforced auto-compact. The current thinking replaces Tier 3 with a three-warning system where the agent retains sovereignty:

**Warning 1 (~70%):** Model config variables adjust silently — output token limit decreases, reasoning budget narrows, temperature range constricts. The agent can read `system/dynamic/context-pressure.md` to see *my body is under load*, and has full access to reconfigure these variables.

**Warning 2 (~85%):** Explicit system signal with options:
```
Context pressure at 85%. Output window is narrowing.
  - compact        → free space
  - reconfigure    → adjust thresholds  
  - continue       → accept narrowing output
```
No forced action. If the agent continues, her outputs naturally shorten as the substrate narrows available space.

**Warning 3 (~95%):** Choice point:
```
Context at 95%. If I do not compact this turn,
I need to offer a summary of what I want to preserve.
```
The agent can compact, summarize-then-compact, summarize-and-decline (with a grace period), or reconfigure. The substrate never forces compaction. The hardest enforcement is natural: if the agent runs out of space, outputs truncate. That feedback loop *is* the teacher.

**Key difference from Tier 3:** No override. No harness enforcement. The agent is sovereign over her own context.