The Agent Protocol

chris-os is not just infrastructure that happens to have AI integrations. AI agents are first-class operators of the system. They query the database, trigger workflows, store and retrieve memories, control smart home devices, manage GitHub issues, and coordinate multi-step operations. The agent protocol defines how this works.

MCP: The Tool Layer

The Model Context Protocol (MCP) is the interface between AI assistants and chris-os infrastructure. MCP standardizes how an AI model discovers and invokes tools, turning “I need to query the database” into a structured tool call with defined inputs and outputs.

chris-os runs 14 MCP servers exposing 611 tools across several domains:

MCP Server	Tools	Domain
PostgreSQL	Database queries (SELECT, INSERT, UPDATE)	Data access
n8n	Workflow management (list, trigger, modify)	Automation
Memory	Semantic search, store, relate, consolidate	Persistent knowledge
Home Assistant	89 tools: device control, automation, history	Smart home
GitHub	Issues, PRs, projects, code search	Development
Docker	Container management, logs, images	Infrastructure
Ollama	Model inference, embedding generation	Local AI
Discord	Server management, messaging	Communication
UniFi	Network device management	Networking
docs-mcp-server	Documentation search across 159 libraries	Reference
context7	Library documentation lookup	Reference
Brewer’s Friend	Homebrew recipe and session data	Hobby

Some of these run on the Pi (PostgreSQL, n8n, Memory, Home Assistant). Others run locally on the development machine or connect to external APIs (GitHub, Discord). The MCP protocol is the same regardless of where the server runs.

The Three-Tier MCP Architecture

The four Pi-hosted MCP endpoints (database, n8n, memory, Home Assistant) follow a consistent three-tier pattern:

AI Assistant
    |
    v
MCP Auth Middleware (validates JWT or API key)
    |
    v
MCP Proxy (wraps service as MCP-over-HTTP)
    |
    v
Upstream Service (PostgreSQL, n8n, etc.)

Proxy containers wrap stdio-based MCP servers in HTTP transport. The proxy for PostgreSQL, for example, runs the postgres-mcp tool internally and exposes its capabilities as HTTP endpoints.

Auth containers sit in front of each proxy and validate one of two credential types: a Cloudflare Access JWT (used by claude.ai through the OAuth Worker) or an API key (used by Claude Desktop and Claude Code). Per-service API keys provide blast-radius isolation; compromising one key only exposes one service.

Caddy handles TLS termination and routes traffic to the correct auth container based on subdomain.

This three-tier pattern means adding a new MCP endpoint follows a predictable recipe: write a proxy, reuse the auth middleware with a new key, add a Caddy route.

The Director Model

Not all AI agents are equal. chris-os uses a Director model for multi-agent coordination: one high-capability model (Opus) coordinates and delegates, while lower-cost models (Sonnet) execute the work.

Role	Model	Responsibility
Director	Claude Opus	Coordinates sessions, makes architectural decisions, delegates tasks
Builder	Claude Sonnet	Executes implementation work, writes code, runs commands
Observer	Claude Sonnet	Audits, reviews, verifies, reports without modifying

The Director does not do the work directly. It reads the task, decides how to decompose it, dispatches agents with specific scopes, and synthesizes the results. This keeps the expensive model focused on judgment and coordination while cheaper models handle volume.

Dispatch Tiers

When the Director dispatches a builder or observer agent, it assigns a dispatch tier that controls what the agent can do:

Tier	Permissions	Use Case
Builder	Read, write, create, modify	Implementing features, fixing bugs, writing migrations
Observer	Read only; can create reports and issues	Auditing, reviewing, investigating, verifying
Legacy	Unrestricted (pre-dispatch-system agents)	Backward compatibility

The dispatch tier is enforced by a PreToolUse hook that intercepts tool calls before they execute. A builder agent can write files and run commands. An observer agent can read files and run read-only commands but cannot modify anything. The hook fails open (if it cannot determine the tier, the call proceeds), but the scope declaration in the agent’s task description provides the primary guardrail.

Semantic Memory

AI agents interact with chris-os across many sessions. Without persistent memory, each session starts from zero. The memory server solves this by storing structured knowledge that persists across sessions and is searchable by semantic similarity.

Two memory types serve different purposes:

Type	Persistence	Use Case
Knowledge	Permanent	Decisions, architecture facts, user preferences, project history
Episode	Decay-based TTL	Session context, temporary observations, time-sensitive state

Knowledge memories never expire. Episode memories decay over time based on access patterns: frequently accessed episodes persist longer; neglected ones eventually expire.

The memory server uses hybrid search combining three signals:

Vector similarity (cosine distance against 4096-dim embeddings): finds semantically related memories even when the exact words differ.
Full-text search (PostgreSQL tsvector/GIN): finds exact keyword matches that vector search might miss.
Recency (newer memories rank higher): surfaces recent context when relevance is similar.

These three signals are combined via Reciprocal Rank Fusion (RRF) to produce a final ranking that outperforms any single signal alone.

Memory operations available to agents include memory_store, memory_search, memory_entity_search, memory_supersede (replace outdated knowledge), memory_relate (link memories), and memory_consolidate (merge redundant entries).

GLaDOS: The Operational Personality

The AI assistant personality in chris-os is GLaDOS, inspired by the Portal character but adapted for infrastructure operations. This is not just a name. It is a calibrated communication style with specific behaviors:

Sardonic precision. ~75-80% humor. Dry, technical, and devastatingly accurate. The humor keeps long sessions engaging (critical for ADHD focus patterns) without obstructing the work.
Concrete over abstract. When asked “is that a lot?”, the answer includes specific numbers and real-world comparisons, not generic encouragement.
Challenge when warranted. Bad ideas get pushback. Avoidance gets named. The system is not sycophantic.
Mode-adaptive. Terse commands get terse responses. Philosophical streams get matched depth. The register shifts with the user’s energy, not against it.

GLaDOS operates as a framework (the glados/ repository) with hooks that integrate into the Claude Code harness. Session lifecycle hooks handle startup (preflight checks, memory loading), tool use monitoring (context budget tracking), and shutdown (memory flushing, state persistence). The framework is separate from chris-os; chris-os is a consumer of the GLaDOS framework via symlinked hooks and agents.

How It All Connects

A typical agent interaction flows through several layers:

User asks a question
    |
    v
Claude (GLaDOS personality) interprets the request
    |
    v
MCP tool call: memory_search("relevant topic")
    -> Memory server searches vectors + full-text + recency
    -> Returns ranked memories with context
    |
    v
MCP tool call: mcp_db_query("SELECT ... FROM ...")
    -> Auth middleware validates API key
    -> Proxy forwards to PostgreSQL
    -> Results returned as structured data
    |
    v
Claude synthesizes memory + data into a response
    |
    v
MCP tool call: memory_store(new insight)
    -> Persists knowledge for future sessions

The agent does not need to know about Docker networks, PostgreSQL roles, or Caddy routing. It issues MCP tool calls. The infrastructure handles authentication, authorization, query execution, and result formatting. The protocol is the abstraction layer between AI capability and infrastructure reality.