Governance-first TypeScript runtime for AI assistants and autonomous agents.

AgentBigBrain is built for teams that want an agent runtime where the model can plan, explain, and propose work, but the runtime still decides what is allowed to happen. It supports governed CLI runs, bounded autonomous loops, Telegram and Discord interfaces, HTTP federation, audited local execution, and multiple model backends under one control model.

At the npm runtime package level, the project depends on ws and onnxruntime-node. In practice, the full runtime also depends on your chosen backend, auth state, and any optional services you enable, such as Telegram, Discord, or Ollama.

Start here:

• Setup and environment wiring
• Architecture reference
• Command examples
• Runtime error and env map

Most agent systems are good at proposing work. Fewer are good at proving that the work was safe, allowed, and actually executed. AgentBigBrain is built around that gap.

The model stays flexible. The runtime stays strict.

What the runtime enforces:

• deterministic hard constraints before model judgment
• layered governance for risky actions
• proof gates for certain completion claims
• durable governance records and execution receipts
• bounded, privacy-aware memory and continuity
• governed local live runs instead of ad hoc shell behavior

npm run dev:federation starts the inbound HTTP surface. Outbound federation is separate. The orchestrator can delegate a task to another agent before local planning when federation policy and target config allow it.

Daemon mode is intentionally guarded. It will not start unless all of these are set:

BRAIN_ALLOW_DAEMON_MODE=true
BRAIN_MAX_AUTONOMOUS_ITERATIONS=...
BRAIN_MAX_DAEMON_GOAL_ROLLOVERS=...

• Node.js 22.x or later
• npm

npm install
npm run build
npm test

cp .env.example .env

For a dry-run starting point with no external model calls:

BRAIN_MODEL_BACKEND=mock
BRAIN_RUNTIME_MODE=isolated

npm run dev -- "summarize current repo status"
npm run dev -- --autonomous "stabilize runtime wiring plan execution"

OpenAI-compatible endpoints can use OPENAI_BASE_URL. The openai alias maps to openai_api.

Codex auth commands:

npm run dev -- auth codex login
npm run dev -- auth codex status
npm run dev -- auth codex logout

Optional profile-aware login:

npm run dev -- auth codex login --profile work
npm run dev -- auth codex status --profile work

Optional embeddings:

npm run setup:embeddings

If you skip embeddings, set:

BRAIN_ENABLE_EMBEDDINGS=false

The runtime path is ordered on purpose:

1. The planner proposes typed actions.
2. Preflight checks budget, deadlines, path rules, shell rules, stage rules, and idempotency.
3. Connector and network preflight checks approval scope for side-effecting egress when needed.
4. Governance runs through a reduced fast path for low-risk work or the full council for sensitive work.
5. A verification gate can block respond if the runtime does not have enough proof to claim the task is done.
6. Approved work executes through the executor or a governed runtime action.
7. Governance outcomes and execution receipts are written as durable evidence, including connector receipts for approved external writes.

That order is part of the runtime contract.

The interface layer is not a thin wrapper around the CLI. It has its own session store, queueing, worker lifecycle, draft flows, slash commands, memory review paths, and media ingress reduction.

Supported providers:

• Telegram
• Discord
• both in one shared runtime

Start it with:

npm run dev:interface

Common interface settings:

BRAIN_INTERFACE_PROVIDER=telegram
BRAIN_INTERFACE_SHARED_SECRET=...
BRAIN_INTERFACE_ALLOWED_USERNAMES=...

Important defaults:

• interface-side autonomous execution is off by default
• Telegram and Discord can share one runtime core when both are enabled
• long-lived profile continuity across both providers still depends on profile memory being enabled
• the optional local intent model is separate from the main planner backend

Example local intent-model settings:

BRAIN_LOCAL_INTENT_MODEL_ENABLED=true
BRAIN_LOCAL_INTENT_MODEL_PROVIDER=ollama
BRAIN_LOCAL_INTENT_MODEL_NAME=gemma4:latest

AgentBigBrain uses separate memory systems with different jobs instead of pushing everything into one growing prompt.

Profile memory is the long-lived personal-memory layer. It lives in an encrypted store and uses a graph-backed model so the runtime can track people, claims, timing, and whether something is current, historical, resolved, or conflicting.

Stage 6.86 continuity is different. It owns the live conversation stack, entity graph, open loops, and pulse state for the active interaction.

Memory access is brokered. The runtime supports bounded review, correction, forgetting, and continuity-linked recall instead of treating memory as write-only.

When policy allows it, the executor can:

• start managed processes
• prove localhost readiness
• verify a page in a real browser
• stop the process when the mission is complete

This is governed runtime behavior. It is not just free-form shell scripting.

npm run check:repo
npm run audit:governors
npm run audit:claims
npm run audit:ledgers
npm run audit:traces

The repository also includes stage-specific tests and evidence scripts for runtime maturity, conversation behavior, live-run proof, and interface flows.

• Architecture reference
• Setup and environment wiring
• Command examples
• Runtime error and env map
• Contributing
• Security
• Support
• Changelog

Report vulnerabilities privately to [email protected] or through GitHub Security Advisories. Do not open public issues for security reports.

Apache License 2.0. See LICENSE and NOTICE.