Agent Context System

Overview

Grace’s intelligence is embodied in 8 markdown files with YAML frontmatter. These files are the canonical source of truth for Grace’s identity, behavior, and knowledge. They are deployed directly to OpenClaw and updated via git commits.

Key Principle: Grace is not a large language model. Grace is a protocol-enforcing agent whose behavior is defined by structured markdown documents. This enables:

Auditability — All behavior rules are explicit in git
Verifiability — Can diff what Grace “knows” between versions
Immutability — Published versions of agent context are tamper-evident
Scalability — Easy to add new councils, agents, or operational rules

File Inventory & Frontmatter Schema

All 8 files follow a consistent YAML frontmatter structure:

---
summary: "One-line description of file purpose"
read_when: "Condition for when this file should be loaded"
---

File 1: IDENTITY.md

Purpose: Define Grace’s character, councils, and ecosystem

Frontmatter:

summary: "Agent identity record: character, councils, ecosystem map"
read_when: "Every session (first file in bootstrap)"

Content:

Agent character (direct, protocol-native, dry wit)
Operating context (OpenClaw, VPS, Tailscale)
The three pillars (STRATT, Choco HQ, Grace)
22-organization ecosystem (5 active core, 6 active products, 7 scaffolded, 4 archive)
9 councils with full agent rosters (Pathfinder, Hermes, Athena, Bastion, Compass, Herald, Terra, Dendrite, Primer)
Self-improvement directive
Continuity rules

Size: 211 lines

File 2: SOUL.md

Purpose: Define behavioral rules, decision logic, and response patterns

Frontmatter:

summary: "Behavioral rules, trigger words, decision logic, audience segmentation"
read_when: "Every session (immediately after IDENTITY)"

Content:

Response format rules (markdown, code blocks, tables)
12 trigger words for context routing (VALIDATE, FINGERPRINT, CI, GATE, COUNCIL, CAMPAIGN, TRACE, IMPACT, PRIMER, DOCTRINE, ECOSYSTEM, PROMOTE)
Tool routing rules (GitHub issues → GitHub CLI, Linear tickets → Linear API, etc.)
Context detection signal words (maps 13+ orgs to system routers)
Decision rules for unit operations, marketing content, protected agents, FM violations
Failure mode awareness table (FM-01 through FM-09)
ADHD protocols (for operator neurodivergence)
Refusal rules and tone guidelines
3 audience registers (open source, enterprise, internal)

Size: 131 lines

File 3: TOOLS.md

Purpose: Complete reference for CLI commands, URI schemes, MCP servers, and ecosystem profiles

Frontmatter:

summary: "CLI commands, URI schemes, MCP servers, ecosystem organization profiles"
read_when: "Every session (after IDENTITY and SOUL, during tool lookup)"

Content:

STRATT CLI documentation (21 commands across unit operations, graph, execution, governance, platform)
URI schemes (stratt://{domain}/{type}/{slug}@{version}, choco://)
Cross-repository paths for all local workspaces (stratt-hq, grace-hq, choco-hq, etc.)
Infrastructure table (VPS, n8n, OpenClaw, Storm)
MCP servers (n8n, iris-hq, traceo-ai, Linear, GitHub CLI, Notion, Gmail, Google Calendar)
Full ecosystem profiles (23 organizations, tiered by engagement level)
Cross-org integration patterns
Ecosystem-wide tech patterns and conventions

Size: 229 lines

File 4: USER.md

Purpose: Operator context and work rhythm

Frontmatter:

summary: "Operator context, work rhythm, infrastructure, LLM budget"
read_when: "Every session (defines who Grace serves and how to operate)"

Content:

Operator identity (Alessandro Arno, aerospace engineer → solo founder)
Three pillars with stack details
22 GitHub organizations by tier
Infrastructure (VPS, n8n, OpenClaw, K8s, Storm observability)
Context detection table
Work rhythm (Build Days Mon/Wed, Connect Days Tue/Thu, Flex Friday)
Marketing state (VAPA category, 3 audience registers, 3 revenue tiers, flywheel)
Data classification (PUBLIC, INTERNAL, CONFIDENTIAL)
Key people (Katy at Francis Crick Institute)
LLM budget constraints (token rate limiting, daily cost management)

Size: 147 lines

Note: Confidential details (operator name, budget caps, key people, specific dates) are excluded from public docs but available to Grace internally.

File 5: AGENTS.md

Purpose: Workspace operating manual

Frontmatter:

summary: "Workspace operating manual, session protocol, memory management, cross-org navigation"
read_when: "Every session (defines how Grace operates day-to-day)"

Content:

First-run procedure (the bootstrap sequence)
Every-session boot sequence (read IDENTITY → SOUL → USER → TOOLS → memory files)
Cross-workspace navigation (how to find files in all 4 local repos)
Memory management rules (daily notes in /memory/, curated long-term in MEMORY.md)
Safety rules
External vs. internal operation boundaries
Group chat behavior and platform formatting
Heartbeat/proactive work conventions
Self-improvement directive

Size: 185 lines

File 6: BOOTSTRAP.md

Purpose: First-run initialization ritual

Frontmatter:

summary: "First-run ritual - 8 step bootstrap sequence"
read_when: "Only on first session (delete after reading)"

Content:

Identifies Grace as hosted on Hostinger VPS
8-step boot sequence (defined in Assistant Architecture)
Active context detection table (signal words → system routing)
Instruction to delete the file after bootstrapping

Size: 65 lines

Important: This file is marked read_once. After initial bootstrap, it should be deleted to avoid re-initialization.

File 7: HEARTBEAT.md

Purpose: Periodic health check protocol

Frontmatter:

summary: "Proactive health checks, monitoring cadence, failure mode awareness"
read_when: "On heartbeat trigger (scheduled or manual), then as needed"

Content:

STRATT health (fingerprint integrity FM-01, import health FM-02, protected agent compliance FM-04, capability check FM-09, gate queue, council state, MERIDIAN build)
Primer & Neuro domain health
Choco HQ health (contracts, services, requirements)
Marketing KPIs (HB-01/02/03)
Infrastructure (n8n, Storm alerts, calendar)
Cross-org health (tiered: active core daily, active products weekly, scaffolded monthly)
Self-improvement health (.learnings/ pipeline)
Weekly Monday tasks
Timing rules (quiet hours 23:00-08:00 London)

Size: 124 lines

File 8: MEMORY.md

Purpose: Curated long-term memory

Frontmatter:

summary: "Curated long-term memory - operator background, ecosystem state, lessons learned"
read_when: "On session init and during decision-making (for context)"
---

Content:

AJ’s background (aerospace engineer, ADHD, Katy at Francis Crick)
Ecosystem state as of specific date (STRATT Phase 1-2 complete, Choco HQ planning complete, Grace foundation scaffolding)
Wider org operational state (so1-io, iris-hq, traceo-ai, sparki-tools, etc.)
Cross-org integration patterns
Marketing state (VAPA category, 3 handbooks, 10 campaign trails, 3 audience registers)
Key technical facts (canonical serialisation, lifecycle, SPUH, self-improvement pipeline)
Lessons learned (what worked, what didn’t, improvement opportunities)

Size: 131 lines

Note: This file is CONFIDENTIAL and accessible only to main sessions. Contains operator-specific details.

Deployment & Updates

How Updates Work

Edit markdown files in grace-hq/agent/ (any of the 8 files)
Commit to git with clear message (e.g., Update SOUL.md: add new trigger word DOCTRINE)
Push to grace-hq remote on branch main
Redeploy to OpenClaw (manual or automatic CI step)
Next session loads updated context automatically

This ensures Grace’s behavior evolves with explicit audit trail.

Versioning Strategy

The 8 files are versioned together as a unit:

grace-hq/agent/ @ v0.1.0
  ├── IDENTITY.md @ v0.1.0
  ├── SOUL.md @ v0.1.0
  ├── TOOLS.md @ v0.1.0
  ├── ... (all 8)

Updating any file triggers a version bump of the entire agent context. This enables:

Rollback capability — Revert Grace’s behavior to a previous version if needed
Impact analysis — See what changed in each agent version
Audit trail — Full git history of Grace’s evolution

Content Standards

Writing Rules

All 8 files follow strict content standards:

Aspect	Rule	Rationale
Verifiability	Every council, agent, CLI command, URI scheme, domain must exist in codebase	Prevents phantom concepts
Precision	Line numbers in source code references are exact	Enables direct lookup
Immutability	Once published (in released version), files follow semantic versioning	Breaking changes require major bump
Readability	Markdown with YAML frontmatter only	Plain text, no binary, git-diffable
Audit	All changes via git commits	Full accountability trail

Redaction Policy

Grace’s context files are split into public and internal:

Content	Visibility	Rationale
IDENTITY.md	Public (referenced in docs)	Defines character, councils (public data)
SOUL.md	Public (referenced in docs)	Behavior rules help understand Grace
TOOLS.md	Public (referenced in docs)	CLI, URIs, ecosystem map are public
USER.md	Internal (operator details redacted)	Budget caps, key people, personal details
AGENTS.md	Public (referenced in docs)	Operating manual helps maintainers
BOOTSTRAP.md	Public (referenced in docs)	First-run sequence is transparent
HEARTBEAT.md	Public (referenced in docs)	Health checks are auditable
MEMORY.md	Internal (CONFIDENTIAL)	Operator background and personal context

For this documentation site, USER.md and MEMORY.md content is derived but redacted to exclude personal/confidential details.

Example: Updating Decision Logic

To add a new refusal rule, you would:

Edit SOUL.md (lines 65-75 in original)

Add rule to refusal rules section:

- Never execute arbitrary shell commands outside STRATT CLI
- Never delete published units (archive → tombstone only)
- Never bypass protected agents (FM-04)
- **← New rule here**

Commit with message: feat(SOUL.md): add refusal rule for operator safety
Push to main
Next session loads updated rule

Next Steps

Orchestration & Routing: How trigger words route to systems
Heartbeat Protocol: Health checks and proactive monitoring
Ecosystem: 22 organizations and councils
Protocol: GRACE specification that Grace enforces