How Frege works.

Overview

A Frege brain stores institutional knowledge as versioned pages with sources, links, and trust zones. Agents never read raw files or the database directly. Instead they request scoped context, and Frege resolves org, role, and source permissions before returning anything. The backend supports login and bootstrap, org management, per-user API keys, hosted brain pages, agent sessions, memory proposals, context builds, model routing, telemetry, and MCP access.

Customers do not run the Frege database themselves. They connect agents to the hosted Frege API through the Frege CLI and MCP client.

Product shape

Frege is a hosted company brain for AI agents. The primary integration surface is MCP. REST APIs remain the internal implementation boundary used by MCP, the admin UI, and tests. Two kinds of caller reach the platform: human admins, who authenticate with a session cookie, and agents, which authenticate with a bearer API key.

• Control plane: the hosted app, admin UI, REST APIs, and model-gateway orchestration.
• Brain database: the canonical store of governed pages, sources, sessions, and proposals.
• Thin client: the local frege CLI and MCP server, which only ever call REST APIs.

Request flow

Admins drive the control plane through the protected admin surface; agents reach governed memory through versioned APIs. Both paths resolve identity and org scope on the server before any data is returned.

  Human admin                         Agent
     │                                  │
     │  /setup · /login · /admin        │  frege mcp serve
     │  session cookie                  │  bearer API key
     ▼                                  ▼
  ┌──────────────────┐            ┌──────────────────┐
  │  /api/v1/admin/* │            │   /api/v1/*      │
  └────────┬─────────┘            └────────┬─────────┘
           │                               │
           ▼                               ▼
  org · users · roles            brain · context gateway
  keys · models · proposals      model gateway · telemetry

+-- FREGE / BOUNDED SUBSYSTEM LATTICE --------------------------------------+
|                                                                           |
|  org / actor                                                              |
|     +-- identity + control  ------ users / roles / keys                    |
|     +-- hosted brain       -------- pages / sources / revisions            |
|     +-- session ledger     -------- events / tools / signals               |
|     +-- memory proposals  --------- review / accept / revise               |
|     +-- context gateway    -------- scope / cite / withhold                 |
|     +-- model gateway      -------- route / invoke / record                |
|     +-- telemetry + audit  -------- receipt / cost / provenance            |
|     +-- trust + tenancy    -------- green / red / deny                     |
|                                                                           |
+----------------------------------------------- one governed system / eight -+

..  .    .   :      .        .      :     .        .     .       .      ..
  ..  .    :::.      ..   .    .:::.   .    ..      .:.    .       .:.
 .  :..::--==++**##%%@@%%##**++==--::..:.  .::--==++**##%%@@%%##**++==--
    ..::--==++**##%%@@%%##**++==--::..     ..::--==++**##%%@@%%##**++==
       .::--==++**##%%@@%%##**++==--::.       .::--==++**##%%@@%%##**++
          ..:--==++**##%%%%##**++==--:..          ..:--==++**##%%%%##**
             .::--==++**####**++==--::.              .::--==++**####**
                ..:--==++****++==--:..                   ..:--==++****
                   .::--==++++==--::.                        .::--==++
                      ..:--====--:..                             ..:--
                         .::----::.                                  .
                            ..::..
                               .

identitymemorycontextaudit

04 / system lattice

Backend subsystems

Frege is composed of focused subsystems. Each one is org-scoped and governed by the same identity and trust rules.

next / 05Identity & control plane ↓

Identity & control plane

Users, sessions, memberships, invites, roles, and per-user API keys. Org scope is always derived from the session or key, never from client input.

Hosted brain

Institutional knowledge stored as versioned pages with sources, revisions, trust zones, tags, and extracted links. The database is canonical; markdown is the human and agent representation.

Session ledger

Durable per-task context: user and assistant messages, tool calls, tool results, context builds, model invocations, memory signals, and notes. Secrets are redacted before any write.

Memory proposals

Agents do not silently rewrite canonical knowledge. Durable updates land as reviewable proposals; an accepted page proposal creates a new brain revision and refreshes links.

Context gateway

Context builds resolve org, role, sensitivity labels, and trust zones, then return allowed chunks with citations and withheld counts.

Model gateway

Pluggable, model-agnostic routing. Frege assembles context, enforces gates, routes to a configured provider, and records model telemetry. It does not require a model to live inside the app.

Telemetry & audit

Supported context, model, and run paths record actor, action, outcome, latency, provider, token counts, estimated cost, and trust zone alongside a separate audit trail.

Trust & tenancy

Green and red trust zones gate context before any packet reaches an agent or model. Denied counts can be reported, but denied titles and bodies never leak.

Identity & control plane

Human users authenticate with password login and hashed sessions. Agents authenticate with bearer API keys only, and each key is owned by a human user. All org scoping comes from the user session or API key; a client-provided org is never trusted. Roles control document access, session access, memory proposals, source management, and audit access.

Hosted brain

Brain pages are markdown-like records stored in Postgres. They include slugs, titles, trust zones, tags, frontmatter-style metadata, revision history, and extracted page links. The database is canonical. Markdown is the human and agent representation and the future export format, not the customer-facing storage system.

Session ledger

The session ledger stores durable task context for agents: user messages, assistant messages, tool calls, tool results, context builds, model invocations, memory signals, and notes. This is where task context belongs, kept separate from telemetry metadata. Hard secret protection runs before every ledger write, redacting obvious API keys, passwords, authorization headers, cookies, and provider tokens.

Memory proposals

Agents do not directly rewrite the canonical brain. They create proposals for page creation, page updates, and source creation. Admins review proposals in the console. Accepting a page proposal creates or updates a brain page, writes a new revision, and refreshes extracted links, so agent observations stay auditable before they become trusted org memory.

Model gateway

Frege keeps model invocation pluggable. Its backend responsibility is to assemble governed context, enforce org and trust-zone gates, route to configured providers, record model telemetry, and optionally append model events to the session ledger. The default product assumption is model-agnostic orchestration: user agents and user-selected providers supply most of the reasoning power, while Frege supplies governed memory, prompt and context assembly, and observability.

The hosted app is a control plane, not an inference host. The current hosted-run worker is beta and performs one provider completion using a governed context packet. A policy-controlled multi-step tool loop is planned, not presented as available today.

  Frege app (hosted control plane)
    -> creates run / session / context packet
    -> queues Frege Agent Runtime

  Frege Agent Runtime (beta worker)
    -> performs one configured provider completion
    -> uses the governed context packet created by Frege
    -> writes run steps, session events, and telemetry

  Model router (same runtime network)
    -> organization-configured OpenAI-compatible endpoint or Ollama
    -> serves the configured chat-completions interface

Current routing supports an organization-configured OpenAI-compatible endpoint and an optional Ollama development endpoint.

Telemetry & audit

Telemetry is the metrics and observability spine for supported product paths. It records actor, user or key, request, route action, outcome, latency, provider and model, token counts, estimated cost, trust zone, and redacted metadata, and links to sessions, session events, context builds, and proposals. Compliance history lives in a separate audit trail, while raw task memory stays in the brain and session ledger.

Trust & tenancy

Frege uses two trust zones. Green covers normal public and internal context; red covers restricted context. Public and internal sensitivities map to green; restricted maps to red.

• Every protected query filters by organization.
• Agents inherit org, owner user, role, labels, and capabilities from their API key.
• Humans inherit org access from their session membership.
• Agents without red-zone permission cannot receive red-zone pages, documents, session events, or context chunks.
• Denied counts can be reported, but denied titles and bodies do not leak.

MCP surface

The Frege CLI and MCP server call REST APIs only; they never read the database directly. Agents use MCP tools to check status, search and read brain pages and documents, build governed context, manage sessions, propose memory, and run hosted agents. The recommended workflow is to start or attach to a session, append important events, search the brain, build governed context before answering, cite slugs and source IDs, and create proposals for durable updates.