apprentice-labs/activegraph-gbrain-bridge: thin compatibility bridge between ActiveGraph and GBrain

Thin compatibility bridge between ActiveGraph and GBrain.

GBrain is the durable knowledge and ontology layer: markdown/Git source of truth, retrieval indexes, typed links, facts, takes, timelines, MCP operations, ingestion, and jobs. ActiveGraph is the runtime-causality layer: event log, graph projection, replay, branching, policy gates, and provenance.

The bridge keeps those responsibilities separate:

GBrain stores durable world knowledge.
ActiveGraph records and governs how an agent uses or proposes changes to it.

For a publication-facing explanation of why dynamic context graphs matter for workflow automation, see docs/launch_post.md.

For the current implementation status, read STATUS.md first.

What Works Today

• Installable Python package: activegraph-gbrain.
• Import path and ActiveGraph pack entry point: activegraph_gbrain.
• Typed GBrain client surface for read, schema, job, and dry-run writeback proposal operations.
• Fixture and recorded-fixture clients that never call live GBrain.
• Read-only MCP/HTTP client boundary with test transport injection.
• ActiveGraph object and relation projections for GBrain evidence and schema metadata.
• Redaction-aware request, completion, failure, and replay fixture helpers.
• Fixture-mode lookup behaviors for question and goal objects.
• Policy-gated dry-run writeback proposal helpers.
• Disposable/local read-only trace demo with replay fixture generation.

What Does Not Work Yet

• No pack-local ActiveGraph tools are exposed yet; activegraph_gbrain.tools.TOOLS is intentionally empty.
• The default lookup behavior does not call live GBrain.
• Production live writeback is not supported.
• GBrain versions not listed in the compatibility matrix are unverified.
• The project does not claim endorsement by either upstream project.

Quickstart

Install development dependencies:

python -m pip install -e '.[dev]'

Run the core validation path:

python -m pytest -q
python examples/import_smoke.py
python examples/brain_first_qa_demo.py
python examples/live_readonly_trace_demo.py

These commands do not call private GBrain data, a live LLM, Slack, GitHub, a deployment, or production writeback.

Stable API

Use activegraph_gbrain.api for documented imports:

from activegraph_gbrain.api import (
    ActiveGraphGBrainSettings,
    FixtureGBrainClient,
    RecordedGBrainFixtureClient,
    pack,
)

The package root still exports a broad early-development surface for compatibility with existing tests and demos. New user-facing examples should prefer activegraph_gbrain.api.

Documentation

• STATUS.md is the current support and maturity ledger.
• docs/demos.md lists every committed demo and what each one proves.
• docs/gbrain_compatibility_matrix.md records exact GBrain versions, commits, operation families, and caveats.
• docs/integration_guide.md provides the longer architecture and safety guide.

Development Checks

Before opening a PR, run:

python -m pytest -q
python examples/import_smoke.py
python examples/brain_first_qa_demo.py
python examples/live_readonly_trace_demo.py
python scripts/check_gbrain_compatibility_matrix.py
git diff --check

If a change touches the GBrain client, live compatibility smoke, or schema mutation contract, update the compatibility matrix or explicitly mark the refresh deferred in the PR checklist.