Understanding the VECTOR Architecture

This page is an Explanation. It is for understanding — not for doing. It answers "why does the system work this way?" If you want to install VECTOR, see Getting Started. If you want to look up specific component behavior, see Enforcement or Project Managers.

The Central Design Question

Before describing what VECTOR is, it helps to understand what problem it solves.

Multi-agent AI systems fail in predictable ways. Agents work in parallel on the same files and corrupt each other's work. An agent completes a task and self-reports success — but nothing was actually verified. Context windows fill up, the session ends, and the next session starts with no memory of what came before. One agent makes a decision that contradicts another agent's assumptions, and nobody notices until something breaks in production.

The VECTOR architecture exists to make these failure modes structurally impossible, not just discouraged.

Why Three Tiers?

The three-tier hierarchy — Conductor, Project Managers, Workers — is the central architectural choice. Understanding why three (not two, not four) is the right number requires understanding what each tier is actually doing.

Tier 0 exists because something must hold the global picture. Every ticket, every running task, every piece of cross-cutting context — this belongs to one agent, not six. VECTOR is that agent. It does not execute code. It does not write content. It routes, coordinates, enforces, and synthesizes.

Tier 1 exists because domain expertise matters. An engineering PM brings different context, different skills, and different verification logic than a content PM. Running everything through one general PM would mean every spawn is general-purpose — losing the accumulated domain knowledge that makes specialists valuable. Six PMs with isolated memory partitions means FORGE's engineering lessons don't contaminate SAGE's content judgment, and vice versa.

Tier 2 exists because execution should be scoped and disposable. Workers run in isolated git worktrees. When they complete — or fail — the PM reviews via git diff, not via the worker's self-report. The worker's session ends. Its context disappears. Only the verified diff persists. This is how you prevent a worker's confusion from becoming the system's confusion.

Two tiers would collapse either the strategic and tactical layers (VECTOR doing PM work, losing global coherence) or the tactical and execution layers (PMs executing code directly, losing verification isolation). Four tiers would add bureaucracy without adding a genuine functional boundary.

Three is the right number.

Why Memory is Infrastructure

Most agent systems treat memory as optional — a nice-to-have that makes responses feel more contextual. VECTOR treats memory as infrastructure, with the same criticality as the database that backs a production application.

The reason is compounding value. An AI system that operates continuously learns patterns that a new session cannot access. It discovers that a particular auth patch always conflicts with a custom patch file. It learns that a specific deployment step requires a workaround that took three engineers two hours to figure out. It builds a model of how the Chief makes decisions, what matters and what doesn't.

If none of that survives the session boundary, the system is not accumulating value — it is executing the same startup cost every time.

The four layers serve four different time horizons. L4 is permanent — it holds identity and long-term mission that never changes unless the Chief changes it. L3 is operational — it holds running state, task history, and the compaction anchor that lets VECTOR survive a context reset. L2 is per-PM and persistent — each PM's accumulated domain knowledge, isolated so PMs cannot corrupt each other's memory. L1 is ephemeral — the worker's task context, assembled fresh from the layers above, dies when the worker session ends.

The compaction anchor (state/active-sprint.json) deserves specific attention. When a very long context session is compacted — summarized by the model to free context window space — VECTOR could lose track of in-flight work. The sprint file is the anchor: it contains enough structured state that VECTOR can read it cold and resume from where it left off. Without this anchor, compaction would be catastrophic. With it, compaction is an invisible maintenance event.

Why the Plugin Architecture?

The core VECTOR runtime is intentionally minimal. Capabilities are added as plugins — independently versioned, independently installable, independently testable.

The plugin architecture serves two purposes. First, it keeps the core stable — changes to BEE do not require changes to the runtime, and vice versa. Second, it makes the system extensible for enterprise deployments. A customer can install VECTOR, add only the plugins their environment supports, and leave out what their security posture doesn't permit.

The MCP bridge is particularly significant. MCP (Model Context Protocol) servers expose external tools in a standardized format. VECTOR's bridge gives any agent access to 75 tools — GitHub APIs, web search, browser automation, filesystem operations — without those tools being baked into the core runtime. New tools can be added by dropping in a new MCP server configuration. No runtime changes required.

Why Task Flow Looks the Way It Does

A task arriving at VECTOR travels through a specific path before anything is executed, and a specific verification path before anything is accepted as done.

The pre-execution risk scan ("10-steps-ahead") is not a formality. It is where VECTOR asks: what could this change break? Who else is working in these files? What happens if this fails halfway through? Does this touch auth, database schema, or config — categories that require additional care? The answers shape the task spec before any PM sees it.

The gate chain on the back end is where the quality promise is made real. Gate A validates the plan before any code is written. Gate B validates the actual code change — not the PM's description of the code change. Gate C validates that the change integrates cleanly before merge. A task that skips any gate is not accepted as complete.

This is the operational model that makes "done" mean something.

Why OS Residency Matters

VECTOR runs as an OS-resident agent on macOS. It has access to the browser, the terminal, macOS UI state via Peekaboo, and system configuration. This is not a web application responding to API calls — it is a process with real access to the machine it runs on.

This capability is, explicitly, VECTOR-only. No PM, no worker, no scheduled cron ever receives OS control. The reason is not paranoia — it is containment. When an agent has OS access, a mistake is no longer contained to files or memory. It can affect running processes, network configuration, or application state. The blast radius of an OS-level mistake is the entire machine.

By restricting OS access to Tier 0 — the one agent with full memory, full audit trail, and direct accountability to the Chief — the system maintains the capability while bounding the risk.

The Communication Model

VECTOR is the single voice to the Chief. Project managers do not send messages. Workers do not surface output. All external communication is routed through Tier 0.

This is not about control — it is about coherence. If six PMs can each send status updates, the Chief receives six partial pictures. VECTOR synthesizes the full picture from all PM outputs and surfaces one coherent view: what shipped, what's blocked, what needs a decision.

The constraint on the Daily Chai channel is absolute: only the 7am cron posts there. No ad-hoc posts, no spillover from other operations, no manual posts. The Chief relies on that channel for one specific thing — the morning brief — and that contract is maintained by architectural constraint, not by convention.