Core System Architecture

This document explains what OGL Cortex is made of, how the parts relate, and how one request travels from the owner's phone to an agent and back. Document 02 covers the execution engine, 03 the configuration files, and 04 the guardrails.

Conventions

These placeholders appear in every OGL Cortex document:

OGL Cortex uses neutral role names: orchestrator, specialist, auditor, analyst and sentinel. Seat names in config examples (for example boss) are placeholders you choose.

1. Overview

OGL Cortex runs a fleet of Claude Code sessions on one host. A background program, the OGL Cortex daemon, keeps each agent session alive, feeds it the owner's Telegram messages and its scheduled jobs, and restarts it when it exits. Each agent, called a seat, is a folder of text files (rules, memory, skills) plus one Claude Code terminal session.

One seat is the orchestrator. The owner talks to it. It hands work to other seats over a file-based message bus, or to short-lived helper agents (subagents) inside its own session. Small scripts called hooks check each seat's actions before they happen, for example blocking an outgoing Telegram message that breaks the writing rules. Memory is spread across layers, from the live conversation to a vector database.

OGL Cortex has two parts:

• The framework (MIT, upstream github.com/grandamenium/cortextos): the daemon, PTY layer, bus CLI, Telegram integration, cron scheduler, dashboard and seat templates.
• The OGL layer: guard hooks, the compaction kit, memory protocol, approval gates, the ship gate, operating tools and additional skills. Sentinel scripts are an optional pattern you add yourself.

2. Component glossary

2.1 Memory

"Memory" means anything an agent can read later to recall a fact. Each layer has its own writer, reader and lifespan.

• Short-term: lives inside the current conversation or until the next restart.
• Episodic: a dated record of what happened.
• Long-term: distilled facts and rules meant to hold for months.

The command-line tool is named cortextos.

Short-term: layers 1 to 4. Episodic: 5, 6, 7, 15, 16, 17. Long-term: 8 to 14.

2.2 Skills

A skill is a folder with a SKILL.md file: written instructions for one kind of job, for example a morning review. Claude Code lists skill names and one-line descriptions at session start. The full text loads only when the agent invokes the skill, or when a cron prompt tells it to read the file ("Read .claude/skills/morning-review/SKILL.md and ...").

cortextos bus list-skills --format json lists the seat skills it can parse. A SKILL.md without name and description frontmatter does not appear.

2.3 Tools

Manage crons through cortextos bus list-crons, add-cron, update-cron and remove-cron. These commands always use the path the scheduler reads (src/bus/crons-schema.ts).

2.4 Rules

Rules come in two strengths:

• Prose rules: text the model reads and weighs.
• Mechanical rules: hooks that run code and can block a tool call.

Claude Code loads every CLAUDE.md from the working folder up to the home folder. The bootstrap files load because the boot prompt tells the seat to read them.

Mechanical rules live in the hooks object of <seat>/.claude/settings.json and ~/.claude/settings.json. The reference orchestrator hook set:

Specialist seats carry a subset: the Telegram hooks, the send guard and the shared-surface guard. An infrastructure seat can run the shared-surface guard in strict mode by omitting SURFACE_CODE_MODE=warn. The framework templates also ship cortextos bus hook-loop-detector as a PreToolUse hook (src/hooks/hook-loop-detector.ts).

A hook script on disk does nothing until a settings file registers it.

3. Roles

3.1 Seats

A seat folder lives at orgs/<org>/agents/<seat>. cortextos bus list-agents lists registered seats. cortextos status shows which are running. A seat can exist on disk while disabled.

3.2 Non-seat actors

4. Surfaces

Bind every control surface to localhost or the tailnet address and require auth on each.

5. Lifecycle of one request

This trace follows a common request: the owner sends a voice note and then a text message asking the orchestrator to produce a set of documents. Times are typical offsets from the voice note arriving.

5.1 Hop by hop

5.2 Sequence diagram

5.3 Component map

6. Known limitations

1. Heartbeats show daemon liveness, not reasoning. The fast-checker writes an "alive" heartbeat every 50 minutes whether or not the session is working (src/daemon/fast-checker.ts). Pair it with a check on recent tool activity or transcript growth. Any process that calls cortextos bus update-heartbeat without CTX_AGENT_NAME set writes under a default name.
2. The default transcription model is English-only. src/telegram/transcribe.ts defaults to ggml-tiny.en.bin, which ignores the language setting. Install a multilingual whisper model for other languages (the framework ships scripts/install-whisper-model.sh). The inbound log stores voice notes with empty text; the transcript appears only in the session.
3. last-telegram-<chat_id>.txt holds one message. send-telegram overwrites it on each send (src/telegram/logging.ts). Audits that need every send must read outbound-messages.jsonl.
4. Seat hooks run inside subagents. A subagent working in a seat folder inherits that seat's hooks. A hook that reads the parent transcript reports the parent's state to the subagent. Scope such hooks to the main session, or tell subagents in their brief to ignore state-file instructions.
5. The auto-memory index loads at most 200 lines. Lines past the cap are dropped without error. Keep MEMORY.md files as indexes of short lines.
6. Several files can describe the same thing. CLAUDE.md, AGENTS.md and the daemon's boot prompt each touch boot behaviour; FLEET-style indexes duplicate enabled-agents.json. Document 03 lists one owner file per setting.
7. The framework's facts hook writes nothing. hook-extract-facts runs at PreCompact and reads a summary field that Claude Code does not send at PreCompact. The harness writes session facts from PostCompact instead (session_facts.py).
8. A plist on disk is not a loaded job. LaunchAgents run only after launchctl load. Check launchctl list for each sentinel and backup job.

Source files

• src/daemon/agent-manager.ts
• src/daemon/fast-checker.ts
• src/telegram/poller.ts, src/telegram/media.ts, src/telegram/transcribe.ts, src/telegram/logging.ts
• src/cli/bus.ts
• src/bus/crons.ts, src/bus/crons-schema.ts, src/bus/knowledge-base.ts
• src/hooks/hook-loop-detector.ts, src/hooks/hook-idle-flag.ts, src/hooks/hook-extract-facts.ts
• src/types/index.ts
• dashboard/src/middleware.ts
• ecosystem.config.js
• templates/orchestrator/, templates/analyst/, templates/agent/