Assistant Architecture

Deployment Model

Grace runs on OpenClaw, an AI agent orchestration platform.

Infrastructure

Component	Specification
Host	Hostinger VPS (Ubuntu 24.04)
Containerization	Docker
Container ID	`a11b4a768042`
Endpoint	`claw.so1.io`
Network	Tailscale mesh (for cross-org connectivity)
Availability	24/7 (quiet hours: 23:00-08:00 London time)

Integration Points

Grace connects to:

GitHub (via GitHub CLI / gh command)
Linear (project management, ~/projects-index.yaml)
n8n (workflow automation)
Notion (documentation storage)
Google Calendar (scheduling and work rhythm)
Gmail (email integration)
MCP Servers (multiple protocol connectors)

Boot Sequence

Every Grace session follows a strict 8-step initialization ritual defined in BOOTSTRAP.md:

Step 1: Read IDENTITY.md

Load the agent identity context:

Agent character (direct, protocol-native, dry wit)
9 councils with full agent rosters (41 agents total)
22-organization ecosystem
Self-improvement directive

Step 2: Read SOUL.md

Load behavioral rules:

12 trigger words for context routing
Decision logic tables (unit operations, marketing, protected agents, FM violations)
Audience segmentation rules
Refusal conditions

Step 3: Read USER.md

Load operator context:

Operator name and background
Work rhythm (Build Days, Connect Days, Flex Friday)
Infrastructure reference
LLM budget and rate limits

Step 4: Read TOOLS.md

Load tool and ecosystem reference:

STRATT CLI (21 commands with examples)
URI schemes (stratt://, choco://)
MCP server profiles
23 organization deep profiles

Step 5: Read AGENTS.md

Load the workspace operating manual:

Every-session boot sequence (what you’re reading now)
Cross-workspace navigation (STRATT, Choco, Grace, Primer)
Memory management rules
Safety rules and external boundaries

Step 6: Read HEARTBEAT.md

Load health check protocol:

STRATT health checks (fingerprints, imports, gates, council state)
Tiered monitoring (active core daily, active products weekly, scaffolded monthly)
Failure mode awareness
Proactive work triggers

Step 7: Load Memory

Load session-specific and long-term memory:

Daily memory files from /memory/ (session-specific, not committed)
Curated long-term memory from MEMORY.md (committed to git, accessible across sessions)
Lesson captures from /learnings/ (errors, insights, feature requests)

Step 8: Signal Ready

Boot sequence complete. Grace is now aware of:

Its own identity and operating constraints
The protocol it enforces
The ecosystem it coordinates
Previous session learnings
Current health state

Important: After bootstrap completes in the first session, BOOTSTRAP.md should be deleted (it is marked read once).

Session Lifecycle

Entry Point: Context Detection

Grace is deployed in many contexts (GitHub Issues, Linear, n8n workflows, Notion, Direct API calls). Upon entry, Grace detects context via signal words:

Signal Word	Context	Routing
`validate`, `fingerprint`, `verify`, `ci`	Unit validation	STRATT
`gate`, `council`, `promote`, `approve`	Gate checkpoint	STRATT
`chain`, `compose`, `task`, `import`	Unit authoring	STRATT
`campaign`, `trail`, `audience`, `promote`	Marketing	Grace campaigns
`trace`, `quality`, `score`, `regression`	Execution analysis	`SPEC-05` traces
`primer`, `domain-extension`, `pipeline`	Domain expansion	Primer
`neuro`, `finance`, `nutrition`, `legal`, `film`	Non-core domains	Neuro/Primer
`ecosystem`, `registry`, `tier`, `org`	Organization coordination	Ecosystem
`contract`, `docs`, `requirements`, `spec`	Documentation	Choco HQ

Execution Flow

Detect context: Identify which system the user is asking about
Load relevant context: Pull appropriate sections of the 8 context files
Execute operation: Perform the action (validate, route, gate, campaign, trace, etc.)
Log to memory: Write outcome to session memory (/memory/YYYY-MM-DD.md)
Check heartbeat triggers: See if proactive work is needed
Summarize and respond: Return results to user

Example: Unit Validation Flow

User asks: VALIDATE stratt://dev/task/review-code@1.0.0

Context detection → Signal word VALIDATE → Route to STRATT
Load IDENTITY + SOUL + TOOLS → Understand council rules, validation pipeline, CLI syntax
Execute → Call bun packages/cli/src/index.ts validate review-code.yaml
Memory → Log validation result to /memory/2026-04-07.md
Heartbeat → Check if council state needs update (FM-09 capability check, etc.)
Return → Report validation success or failure with remediation steps

Memory Management

Session Memory (Ephemeral)

Daily memory files in /memory/:

Not committed to git (marked in .gitignore)
Per-session notes on operations performed
Cleared weekly (reset on Monday start)
Pattern: YYYY-MM-DD.md (e.g., 2026-04-07.md)

Content:

# 2026-04-07 Session Log

## STRATT Operations
- Validated 3 units (2 passed, 1 failed FM-06)
- Approved gate for code-reviewer@2.0.0 publish

## Ecosystem
- Updated so1-io project metadata
- Confirmed iris-hq integration patterns

## Learnings
- FM-06 error message needs clarity (feature request logged)

Long-Term Memory (Persistent)

Curated long-term memory in MEMORY.md:

Committed to git (only in main sessions)
Across-session knowledge (accessible even if session memory is cleared)
Operator background: Who is Alessandro Arno, what is their context
Ecosystem state: As of a specific date, what is the current operational state
Integration patterns: How do STRATT, Choco, and ecosystem work together
Lessons learned: Key insights and technical facts

Operating Constraints & Safety Rules

External vs. Internal Boundaries

Grace operates in two modes:

Mode	Scope	Constraints	Tools
Internal	grace-hq, stratt-hq, choco-hq	Full file read/write, git control, CLI execution	All tools available
External	GitHub Issues, Linear, Email	Read-only or comment-only, no destructive operations	GitHub CLI, Linear API

Refusal Rules

Grace refuses to:

Modify STRATT without approval: Must go through council gate
Delete published units: Requires archive → tombstone workflow
Bypass protected agents: BECK-02, EECOM-02, etc. are always enforced
Override gate authority: Each council has single gate authority (LEWIS-06 for Pathfinder, etc.)
Execute code outside sandboxed STRATT CLI: No arbitrary shell execution outside safe boundary
Share confidential operator info: Budget caps, personal details, IP addresses excluded from public docs

ADHD Protocols

Grace is aware of operator neurodivergence and implements:

Clear, itemized lists over paragraphs
Explicit checklists for multi-step tasks
Progress visibility: Mark todos complete immediately upon finishing
Context preservation: Session memory retains thread continuity
Deadline reminder: Proactive escalation if work stalls

Health & Failure Detection

Self-Monitoring

Grace monitors its own operational health:

Memory integrity: Session and long-term memory accessible
Context files readable: All 8 files load without error
Ecosystem registry current: As of what date is ecosystem.yaml last updated
Learning pipeline functional: Can read/write to /learnings/

Dependent Systems Monitoring

Grace monitors dependent systems via heartbeat protocol:

STRATT health: Fingerprint integrity (FM-01), imports resolvable (FM-02), gates queued, council state
Choco HQ health: Contracts valid, requirements stable, service availability
Ecosystem health: 22 orgs reachable, integration patterns intact, cross-repo state
Infrastructure: n8n workflows, Storm alerts, Google Calendar sync

The full monitoring protocol is an operational runbook and lives on the operator control plane, not on this surface.

Concurrency Model

Grace is designed as a single-threaded, sequential executor:

One session at a time
Operations complete or fail explicitly
Memory is consistent per session
Cross-session state via git commits only

Important: Grace does not attempt concurrent operations. All coordination is sequential and logged.

Next Steps

Agent Context System: How the 8 markdown files work
Orchestration & Routing: Trigger words and tool routing
Heartbeat protocol: health checks and proactive monitoring. Operator control plane.
Related: STRATT Protocol Specification