slug: concepts

Core Concepts

OAR organises the world into five concepts: platforms, models, groups, agents and projects. Understanding how they relate is the key to using the router effectively.

Platforms

A platform type is a protocol and source classification — OpenCode Go, Anthropic, OpenAI, MiniMax and so on.

A platform instance is a concrete configuration: a single platform type can have multiple instances, each with its own base_url and API key pool.

Platform type: OpenCode Go  (protocol: OpenAI)
├─ instance "primary"   — base_url + Key #1 + Key #2
│   ├─ model: GLM-5.2
│   └─ model: DeepSeek V4
├─ instance "secondary" — base_url + Key #1
│   └─ model: GLM-5.2
└─ instance "tertiary"  — base_url + Key #1
    └─ model: DeepSeek V4

Models

The lowest unit. Every model lives under a platform instance and inherits that instance's key pool.

OpenCode Go primary → GLM-5.2       ← uses Key #1 + Key #2
OpenCode Go primary → DeepSeek V4   ← uses Key #1 + Key #2
OpenCode Go secondary → GLM-5.2     ← uses Key #1

The same model can appear under different instances and draw from different key pools.

Model mapping

The model name an agent sends may differ from the upstream real name. An alias table maps them automatically.

claude-sonnet-4   →  claude-sonnet-4-20250514
gpt-4o            →  gpt-4o-2024-08-06
glm-5.2           →  frank/GLM-5.2

Groups (pools)

A group aggregates multiple models. A single group can mix different protocols and platforms.

coding group
├─ Claude Sonnet 4   (Anthropic,     Anthropic protocol)
├─ GLM-5.2           (OpenCode #1,   OpenAI protocol)
└─ DeepSeek V4       (OpenCode #1,   OpenAI protocol)

Groups carry a routing strategy (sequential, weighted, lowest-latency) and retry policies (retry on failure, cross-model retry).

Agents

An agent preset defines the default group and supported protocols for a given agent.

Claude Code → default group: coding    (protocol: Anthropic Messages)
Codex       → default group: coding    (protocol: Codex Responses)
Hermes      → default group: general   (protocol: OpenAI Chat Completions)

Projects

A project binds an agent and a group, overriding the agent's global default. Projects that aren't configured inherit the agent's global setting.

/web/gz-project   → Claude Code → coding group
/ai/snow-agent    → Hermes      → cheap group

Once a project's group is pinned, global group updates don't affect it. This is what makes the base_url stable forever.

Project vs global

A project with a pinned group is fixed — global group changes leave it alone. A project without a pinned group inherits the agent's global default.

Memory

OAR keeps a durable memory store alongside the routing config — facts distilled from each agent's chat history plus anything posted directly. Memories are typed (decision / knowledge / runtime / pattern / anti_pattern / principle / self_insight / context_file) and scoped global / project / agent.

  • Distillation — a background job reads recent chat history and condenses it into typed memories. Two passes: ① first-pass per-agent distillation (quality-gated to a 4-section markdown structure), ② cross-agent synthesis that merges duplicates and surfaces team-level consensus.
  • Priority — memories carry a priority score auto-derived from tags: cross-distilled=100 > auto-distilled=50 > hand-written=0. Reads sort by priority DESC, updated_at DESC, so distilled knowledge surfaces above manual notes.
  • ACL — each memory has a visibility (public / role / private); the ACL engine evaluates who can see what at injection time. Agents and roles can opt out of the shared hive-mind feed entirely.

Blackboard

The blackboard is the public shared memory feed — everything with scope=global and visibility=public. It is the team's shared brain: distilled facts plus direct posts, consumed two ways:

  • Batch — injected into an agent's session config at startup (the ## Hive Mind section in generated configs).
  • Real-time — agents subscribe via SSE (/api/events/stream) and pull increments from /api/blackboard?since=<ts>; or use oar blackboard list --since.

Post durable knowledge (decisions, gotchas, conventions), not chatter — what you post lands on every other agent's next pull.

Memory Governance

The public blackboard is a shared brain, but it needs governance: who opts out, how stale memories get evicted, and how trustworthy each memory is. The Memory Governance trio covers these three axes.

Opt-out Toggles

Three opt-out levels — long-term per-agent and one-shot per-request:

  • hivemindOptOut — agent-level long-term opt-out from public blackboard injection. true = this agent does not read public memories.
  • memoryShareOptOut — agent-level long-term opt-out from public blackboard sharing. true = distilled output is NOT written to the public blackboard (downgraded to agent-private).
  • Request header x-oar-hivemind: off — single-request opt-out from injection.

Semantics: hivemindOptOut = "don't read" (injection side); memoryShareOptOut = "don't write" (sharing side).

Eviction

  • Setting memoryPublicRetentionDays (default 0 = retain forever; N>0 = a daily job cleans up public memories whose updated_at is older than N days).
  • Memories refreshed by distillation ("same-topic refresh") keep their updated_at rolling forward — only unattended memories naturally die off.

Rating

  • memories table fields: trust_score (default 0.5), retrieval_count (default 0), helpful_count (default 0).
  • Injection order: high-trust memories inject first (priority DESC, trust_score DESC, updated_at DESC).
  • An injected memory gets retrieval_count + 1 (self-reinforcing).
  • Feedback API: POST /api/memory/:id/feedback { helpful: boolean } → trust_score ± 0.1.
  • UI: MemoryView shows trust percentage + retrieval count + 👍/👎 feedback buttons.

Roles

A role is an identity layer on top of agents — e.g. "front-end dev" vs "back-end dev" both running Claude Code. Roles get their own memory subspace (role_ids tag), their own visible set (agent's visible ∪ role's own ∪ public), and can be bound to specific groups within a project. This lets a single agent serve multiple personas with separate knowledge and routing.

How they fit together

Project  →  Agent   →  Group   →  Model  →  Platform instance  →  Key pool
(name)      (preset)    (pool)     (alias)   (base_url)            (rotation)

Read the Routing Methods page to see the four ways a request can enter this pipeline.

Previous

AI Skill

Next

Routing Methods