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

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

Example: Unit Validation Flow

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

1. Context detection → Signal word VALIDATE → Route to STRATT
2. Load IDENTITY + SOUL + TOOLS → Understand council rules, validation pipeline, CLI syntax
3. Execute → Call bun packages/cli/src/index.ts validate review-code.yaml
4. Memory → Log validation result to /memory/2026-04-07.md
5. Heartbeat → Check if council state needs update (FM-09 capability check, etc.)
6. 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:

1. Modify STRATT without approval — Must go through council gate
2. Delete published units — Requires archive → tombstone workflow
3. Bypass protected agents — BECK-02, EECOM-02, etc. are always enforced
4. Override gate authority — Each council has single gate authority (LEWIS-06 for Pathfinder, etc.)
5. Execute code outside sandboxed STRATT CLI — No arbitrary shell execution outside safe boundary
6. 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

See Heartbeat & Health for full monitoring protocol.

---

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
• Related: GRACE Protocol Specification