Skip to main content

Gateway and messaging adapters

The gateway design extends Aegis into real messaging platforms without creating a second cognition stack. The same memory, context, security, and planning substrate should continue to own the brain.

Design goals​

The adapter model is meant to:

  • keep one shared runtime path for CLI and messaging surfaces
  • make messaging adapters pluggable without cloning a second plugin stack
  • preserve session continuity across restart, interruption, and multi-turn chat
  • support multiple bot accounts and thread-aware routing
  • let Feishu land first without freezing the whole design around one vendor

Core principles​

Shared runtime first​

Messaging surfaces should reuse the same kernel, memory, context, and planning path as the main Aegis runtime. The gateway stays a communication and delivery hub, not a second brain.

Normalize once​

Each platform event should be normalized into one canonical inbound envelope before routing, session resolution, memory recording, or model execution.

Conversation-scoped sessions, account-scoped identity​

The session anchor should be the most specific active conversation surface for one bot account. That keeps direct chats, rooms, threads, and topic-style spaces distinct without hard-coding one platform's rules into the core.

Text-first canonical payload​

The first shared contract should optimize for text plus attachment metadata. Richer platform-native surfaces can extend the model later without redefining the core message envelope.

Platform policy hints, core security decisions​

Adapters may derive normalized trust or delivery hints from platform context, but the final allow-or-review decision still belongs to the shared security path.

Canonical message model​

Each inbound or outbound message should carry stable references for:

Account​

  • adapter_id
  • account_id
  • tenant or org scope when the platform exposes it
  • concrete surface such as webhook or websocket delivery

Conversation​

  • conversation_id
  • optional parent conversation
  • optional thread or topic identifier
  • chat type such as direct, group, channel, or topic
  • stable display labels and platform metadata

Sender​

  • external user identifier
  • display name and username when available
  • is_bot and is_self
  • platform metadata that should not be part of the routing key

Attachments and policy hints​

The first attachment model should stay metadata-first. It should carry stable IDs, kinds, MIME types, sizes, and fetch references. Adapters may also attach normalized delivery hints such as trust defaults, audience scope, and sensitivity tags.

What the first wave should not do​

The current design explicitly avoids overreaching in the first messaging wave. It does not require:

  • full platform-parity UI features
  • cards, buttons, reactions, or slash commands on day one
  • a brand-new cognition stack per adapter
  • a platform-specific rewrite of security, continuity, or retrieval behavior

Why this matters for continuity​

Messaging support only works if the same design rules still hold:

  • profile truth remains in ProfileGraph
  • active work remains in WorkGraph
  • recalled evidence remains in EvidenceGraph
  • reusable workflows remain in ProcedureLibrary
  • adapter and delivery metadata remain capability truth

That consistency is what allows the same Aegis clone to feel continuous across shell, API, and messaging surfaces.

Where to go next​

Some product surfaces may eventually add a motivational layer on top of this runtime. Continue with Derived progression.