OpenEarth AI Bridge — Transparent AI Observability

What it is

A family of bridge daemons that sit between an AI/ML/legal service and the user, recording every interaction as an foundation.protocols.* Matrix event. The daemons are transparent: the user continues to use the underlying service (Claude Code, Hopsworks, Ansvar MCP servers) with no workflow change; the bridge records everything as a side effect.

The AGPL-3.0 license is chosen, not forced — none of the bridge code links to AGPL dependencies. The choice is strategic: it prevents cloud providers from taking the bridge and offering it as a closed managed service without contributing back.

The two-level compliance architecture

Level 1 — HTTP API proxy (intention layer)

Sits between Claude Code and Anthropic's API. Observes every prompt sent, every completion received, every tool call requested. Records what the AI was instructed to do and what it proposed to do.

Events: foundation.protocols.ai.claude.* (42 types) + foundation.protocols.ai.claude.hook.* (5 types)

↕

Level 2 — System hook observer (action layer)

Hooks into Claude Code's tool execution (Read, Write, Bash, etc.) via gryph. Records what the AI actually did at the runtime boundary — which files were read/written, which commands were executed, what they returned.

Events: foundation.protocols.ai.observation.* (15 types) + foundation.protocols.ai.gryph.* (15 types)

↕

Correlation / certification layer

At session end, a correlation engine compares intention (Level 1) vs action (Level 2). Matches indicate a well-behaved session; divergences are audit signals (hallucination, silent action, transport failure). Emits certification verdicts.

Events: foundation.protocols.ai.certification.* (4 types) · correlation via foundation.protocols.verify.v1 rel_type

This two-level observation is the core design insight: no single observation point is sufficient. An API-only observer sees what Claude said it would do but not what happened after the API returned. A hook-only observer sees what happened but not what was asked for. Together they form a verifiable record.

Bridge families

Claude Bridge

Kotlin + Trixnity 4.22.7. HTTP proxy + MCP Bridge Proxy for intention capture. Correlation engine. 85 events (42 claude + 15 observation + 15 gryph + 5 hook + 4 certification + 4 adjacent).

Hopsworks Bridge

Python + matrix-nio + hopsworks-api. Monkey-patches the Hopsworks SDK to emit events on feature group writes, training runs, model registrations, deployments. 37 events, 44 unit tests.

Ansvar Bridge

Python MCP proxy. Observes Ansvar MCP server calls (Swedish law databases) and records queries + responses. 11 events. Apache-2.0 source, bridge daemon AGPL-3.0.

Governance events

foundation.protocols.ai.governance.* — 17 events for AI Act compliance (Article 9, 12, 13, 14, 50 mapping). Emitted by the bridge on detection of regulated flows.

How it works — walkthrough

User launches Claude Code on their laptop
       │
       ▼
Claude Code → HTTP Proxy (bridge daemon)  ──►  Anthropic API
                   │
                   ▼
       Emits foundation.protocols.ai.claude.session.start, request, response events
       to the user's Matrix room (E2EE, federated homeserver)
                   │
                   ▼
Claude Code proposes a tool call (e.g., Write /etc/hosts)
                   │
                   ▼
Gryph hook intercepts before execution → emits foundation.protocols.ai.gryph.*
                   │
                   ▼
If a policy Check blocks: hook returns exit 2, tool call aborts
If allowed: tool executes, hook records result as foundation.protocols.ai.observation.*
                   │
                   ▼
Session end → correlation engine runs → certification verdict emitted
                   │
                   ▼
Matrix room now contains full auditable timeline:
   intention (claude.*) + action (observation.* + gryph.*) + verdict (certification.*)

Design principles

Transparent to the user. The bridge doesn't change the Claude Code / Hopsworks / Ansvar user experience. Users continue their normal workflow; the bridge records as a side effect.
Two observation points. API boundary AND runtime boundary. Neither alone is sufficient.
E2EE by default. All events flow into end-to-end encrypted Matrix rooms. Only room members can read.
Consent-gated side effects. Tool calls with elevated impact (credential writes, network calls, etc.) emit approval events that require user click before execution.
Correlation as certification. Session verdicts are derived from intent-vs-action correlation, not from AI self-reports.
Sovereign storage. Events live on the user's homeserver. No bridge-owned cloud store. No telemetry.

Release status

OpenEarth AI Bridge is in active development. Source currently on GitLab (internal) during pre-release integration. Target: public release on Codeberg under AGPL-3.0.

☑ Claude Bridge core — intention capture via HTTP proxy + MCP Bridge Proxy
☑ Hopsworks Bridge — E2EE, 44 unit tests, production-ready appservice
☑ Ansvar Bridge — MCP proxy, 27 tests
☑ Gryph integration — 25/25 events landing on 3 homeservers
☑ Certification engine — correlation spec published as foundation.protocols.verify.v1
⏳ Phase 2 — HookHandler + ObservationRecorder + CorrelationEngine wiring into BridgeDaemon lifecycle
⏳ Codeberg public release — blocked on final sanitisation + installer script

OpenEarth Messenger — the Matrix client that renders bridge-emitted events natively
OpenEarth Gryph — the system-hook layer (Level 2 observer). Already released on Codeberg (Apache-2.0).
protocols.foundation — all event schemas the bridge emits
IAS — methodology protocols the bridge enforces (gates, DICSTAMACH, cost tracking)

Copyright 2026 VakeWorks AB and the OpenEarth contributors. Licensed under AGPL-3.0. Dual commercial licensing available — the bridge does not link to AGPL dependencies, so commercial re-use without AGPL is possible via VakeWorks.