Understanding BEE — The Cognitive Architecture

This page is an Explanation. It is for understanding — not for doing. It answers "why does VECTOR learn?" and "how does belief sharing actually work?" If you want to install BEE, see Getting Started. If you want to look up belief formats and API details, consult the Memory Reference.

The Problem BEE Was Built to Solve

Every AI agent begins a session knowing nothing about what worked before. It makes the same mistakes. It misses the same edge cases. It rediscovers, at compute cost, lessons that were learned three sprints ago by a different agent in a different context.

This is not a model capability problem. It is a memory architecture problem.

When FORGE discovers that a missing node_modules directory in a worktree causes tsc to fail silently with exit code 0 — returning success when nothing compiled — that discovery has value. The question is whether that value dissipates when the session ends or accumulates into something the next FORGE session can use.

BEE (Belief Extraction Engine) is the system that makes it accumulate.

What a Belief Is

In BEE's model, a belief is a structured, attributed claim about how the system works — not a conversational memory, not a log entry, but a distilled, confidence-scored assertion that a PM has made based on direct observation during task execution.

A belief looks like this:

"Missing node_modules in worktree causes tsc to fail silently with exit code 0"
  scope: shared
  type: engineering
  confidence: 0.95
  source: TASK-20260226-010
  evidence: "Observed in 3 separate FORGE sessions"

The key elements are the source (a traceable ticket ID, not a guess), the confidence score (based on how many times this has been observed and whether contradicting evidence exists), and the scope (which agents should receive this belief when they spawn).

Beliefs are not summaries of what happened. They are generalized claims about how things work — claims that would be useful to a future PM even if that PM has never seen the task that generated the belief.

The Lifecycle: From Observation to Institutional Knowledge

BEE's belief lifecycle has four stages. Understanding why each stage exists is more important than understanding the mechanics.

stateDiagram-v2 [*] --> Provisional: PM outputs belief_updates at session end Provisional --> Review: VECTOR reads pending_shared queue Review --> Active: VECTOR validates and promotes Review --> Rejected: Fails quality check (sourcing, scope, confidence) Active --> Deprecated: Superseded by newer contradicting belief Deprecated --> Archived: Never deleted — contradictions are data Active --> Active: Confidence reinforced by recurrence

Why provisional? A PM's observations during a single task might be wrong. The PM might have encountered an edge case. The belief might be true for one configuration but not another. Provisional status means the belief exists but hasn't been validated by a second source — VECTOR.

Why VECTOR review? The single-writer rule is not bureaucracy. It is poisoning protection. If PMs could write directly to the beliefs table, a malfunctioning PM could inject beliefs that redirect future PM behavior in harmful ways. Every belief write goes through VECTOR, which validates source attribution, scope appropriateness, and confidence calibration before any belief becomes active.

Why deprecation instead of deletion? A deprecated belief — one superseded by a newer, contradicting belief — is itself useful data. If FORGE learned in sprint 3 that "worktree isolation requires explicit npm install" and then learned in sprint 8 that "the new setup script handles npm install automatically," the deprecation of the first belief by the second is a record of how the system evolved. Deleting it would erase that history.

The Three Scopes: Why Isolation Matters

BEE's three belief scopes exist because different beliefs have different audiences, and injecting the wrong beliefs into the wrong agents causes more problems than it solves.

graph LR subgraph Private["private scope"] P["Visible to:\nWriting PM only\n\nExample: 'FORGE: check for\nnode_modules before tsc'"] end subgraph Shared["shared scope"] S["Visible to:\nAll PMs of same domain\n\nExample: 'Engineering: worktree\nisolation requires npm install'"] end subgraph Global["global scope"] G["Visible to:\nAll agents + VECTOR\n\nExample: 'Gateway port\nchanged to 18789'"] end Writing["FORGE\nobservation"] --> Private Private -->|VECTOR promotes| Shared Shared -->|VECTOR promotes| Global

Private scope is where a belief lives when it's a PM-specific observation. FORGE might learn something about its own workflow that doesn't generalize — a quirk of how it handles a particular task type. That belief shouldn't go to SAGE.

Shared scope is where a belief lives when it describes something that any PM of the same domain would benefit from knowing. Engineering beliefs about worktree isolation, content beliefs about platform character limits — these belong in shared scope.

Global scope is reserved for system-wide facts: port numbers changed, a tool is deprecated, a credential rotated. These are things every agent needs to know.

The critical constraint: a PM cannot self-escalate a belief. It can request escalation — mark a belief as "suggested: promote to shared" — but VECTOR makes the final decision. This prevents scope creep from becoming a security surface.

Cross-PM Knowledge Transfer: The Emergent Property

The most significant capability BEE enables is not belief storage — it is cross-PM knowledge transfer.

Consider this sequence:

  1. GHOST runs a sync cycle and discovers that authentication-related patches consistently conflict with a custom patch file maintained by the team (CUSTOM_PATCHES.md line 47).
  2. At session end, GHOST outputs this as a shared-scope engineering belief: "Auth patches conflict with CUSTOM_PATCHES.md:47 — always review before merge."
  3. VECTOR validates the belief (source: two observed merge conflicts) and promotes it to active.
  4. Three days later, FORGE spawns to implement a new auth feature. At boot, this belief is injected.
  5. FORGE checks CUSTOM_PATCHES.md:47 before writing any auth code.
  6. The conflict that would have taken two hours to debug never happens.

GHOST learned something. FORGE benefited. No human explained anything to anyone. No meeting was held. The knowledge transferred through the belief system, and the result was a prevented defect.

At scale — across six PMs, hundreds of tasks, months of operation — this compounds into a system that is genuinely smarter than the sum of its parts. Not because the models changed, but because the institutional memory accumulated.

What BEE Is Not

This distinction matters because misusing BEE degrades its value.

BEE is not a real-time coordination mechanism. When GHOST needs to tell FORGE to review a specific PR right now, that is a task handoff — it goes through vector_inbox, which VECTOR routes as a new task spawn. Using BEE for this would mean waiting for a belief to be validated, promoted, and injected at some future spawn. By then, the PR might be stale.

BEE is not a chat log. Beliefs are generalized claims, not event records. "PR #47 was merged on Feb 26" is a log entry. "Auth patches from upstream should be reviewed against CUSTOM_PATCHES.md before merge" is a belief. Only the second form is useful to inject into a future session that knows nothing about PR #47.

BEE is not automatic learning without oversight. Provisional beliefs are inert. They sit in the queue until VECTOR reviews them. A PM that outputs confident but wrong beliefs doesn't corrupt the system — VECTOR's review is the firewall.

Why This Matters for Enterprise Deployments

Enterprise AI deployments have a knowledge retention problem that individual agent sessions can't solve.

When an organization runs AI operations for a year, the accumulated knowledge of what works, what breaks, what the edge cases are, and how the organization's specific environment behaves — that is competitive infrastructure. It should not evaporate when a session ends or a context window fills.

BEE is the mechanism by which VECTOR becomes more valuable the longer it runs in a specific environment. A VECTOR deployment at month one has generic engineering beliefs. A VECTOR deployment at month twelve has beliefs about the specific codebase, the specific deployment environment, the specific patterns that work in that organization's context.

That accumulated specificity is the moat. It cannot be replicated by starting a new session. It cannot be purchased by switching to a different model. It is owned by the organization that has been running VECTOR.

Further Reading