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:

[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:

---
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:

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.