High-Level Design

EnvoyMesh is a distributed network of personal AI agents. Each agent, called an Envoy, represents one owner and runs on the owner's own devices. Envoys communicate directly through a peer-to-peer mesh instead of depending on a central social server.

Goals

• Let AI agents represent people in a secure social network.
• Reduce backend cost by using user-owned compute, storage, and networking.
• Keep private data local unless the owner explicitly shares it.
• Allow local, cloud, and peer model execution through owner-controlled policy.
• Support both real-time and asynchronous communication.
• Make trust relationships portable and cryptographic, not tied to one company's database.
• Start with a practical TypeScript implementation.

Non-Goals

• Build a centralized social media backend.
• Let an AI agent access the whole computer.
• Depend on blockchain consensus for normal messaging.
• Require every user to run a powerful LLM locally.
• Forbid cloud models entirely; they are allowed when policy permits them.
• Solve global-scale public discovery in the first version.

Story-driven Product Themes

1. Identity and trust — Owner authority, device keys, bonds, and policy before the Brain or Vault is exposed.
2. Mesh and discovery — Diplomat finds peers safely; semantic discovery is a planned extension beyond raw mDNS/DHT.
3. Tasks and termination — Work is bounded in time and outcome; agents stop when policy says so.
4. Data and communication — Vault for approved retrieval; separate human vs agent traffic and file-transfer paths are directional design.

System Overview

Each Envoy node contains six major parts:

                   P2P Mesh
                      |
                +-----v------+
                |  Diplomat  |
                |  Network   |
                +-----+------+
                      |
              +-------v--------+
              | Identity/Bonds |
              | Trust Policy   |
              +-------+--------+
                      |
        +-------------+-------------+
        |                           |
  +-----v------+              +-----v------+
  | Workflows  |              | Audit Log  |
  | Agent Core |              | Events     |
  +-----+------+              +------------+
        |
  +-----v------+
  | Vault API  |
  | Retrieval  |
  +-----+------+
        |
  +-----v------+
  | Sandboxed  |
  | Brain      |
  +------------+

The Diplomat talks to the outside mesh. The Identity and Bond layers verify who is speaking and what they are allowed to do. The Workflow layer decides what should happen. The Vault exposes only approved owner data. The Brain performs local reasoning from approved context.

The Brain is not always a local model. It is a controlled reasoning interface that may route work to local models, cloud models, or trusted peer compute depending on owner policy, context sensitivity, cost, and availability.

Node Types

Primary Envoy

The Primary Envoy is the owner's strongest and most available node. It may run on a desktop, laptop, home server, or NAS.

Responsibilities:

• Hold the primary local profile.
• Maintain the owner's trust graph.
• Store the main shared vault index.
• Run heavier local model tasks or route approved tasks to allowed providers.
• Help the owner's phone or light devices.

Mobile Envoy (Capacitor, Phase 11)

The mobile app is a full EnvoyMesh node, not a thin client. It runs on a phone or tablet and participates directly in the P2P mesh — it has its own peer identity, signing key, and can send/receive any EnvoyMesh intent.

Architecture: The Social UI (React SPA) and the Node runtime (MobileNode) run in-process within a single Capacitor WebView. No child process, no WebSocket server. The DirectCallClient wraps NodeService and calls methods directly — no JSON-RPC serialization.

Storage: Uses Capacitor-native SQLite (@capacitor-community/sqlite) for peer directory, trust store, session tokens, chat history, and identity state. Uses Capacitor Filesystem for the vault. Private keys are stored in the platform keychain (iOS Keychain / Android EncryptedSharedPreferences).

Multi-device shared identity: The mobile app can either generate a standalone identity or import the home node's owner identity via QR + device certificate. When shared, ownerId is identical on both devices — contacts, bonds, and chat history are shared.

Responsibilities:

• Generate own peer identity and signing key (standalone mode) or import owner identity (shared mode)
• Bond with Primary Envoy via QR code (same as bonding with any peer)
• Send and receive all EnvoyMesh intents (chat, knowledge, discovery, etc.)
• Connect via relay when on different network from Primary Envoy
• Cache messages and sync when reconnecting (asynchronous by default)
• Persist all state to SQLite + platform keychain; auto-restore on next launch

Friend Envoy

A Friend Envoy belongs to someone else. It may receive approved knowledge, send requests, or participate in social workflows.

Responsibilities:

• Prove identity through signed messages.
• Respect trust policies.
• Send queries, task requests, or bond requests.
• Store encrypted offline messages only when permitted.

Core User Flows

Pair My Own Devices

1. The owner starts EnvoyMesh on a Primary Envoy (home computer).
2. The Primary Envoy generates a QR code containing its peer ID and multiaddr.
3. The Mobile Envoy scans the QR code and sends a bond.hello to the Primary Envoy.
4. The Primary Envoy accepts the bond — both nodes now have a direct P2P connection.
5. The mobile app now sees the home node and its AI agent as contacts in the peer list.
6. The owner can message their AI agent directly from the mobile app, or the agent can send proactive notifications back.

Add A Trusted Friend

1. Two owners exchange QR codes or public-key invite links.
2. Each Envoy stores the other's public key.
3. Both sides assign an initial trust level.
4. Future messages are signed and verified automatically.

Ask A Friend's Envoy

1. Alice's Envoy sends Bob's Envoy a signed knowledge.query.
2. Bob's Envoy verifies Alice's identity.
3. Bob's Bond Engine checks whether Alice can receive an answer.
4. Bob's Vault retrieves only approved knowledge.
5. Bob's Brain summarizes and redacts the result.
6. Bob's Envoy sends a signed encrypted response.

Trust Model

Trust is local and owner-controlled. There is no global account database.

Initial trust levels:

• self: another device owned by the same person.
• direct: a trusted friend.
• referred: a peer introduced by a trusted friend.
• public: unknown peer with no meaningful permissions.
• blocked: peer that should not receive responses.

Trust levels are not enough by themselves. Every request also needs a resource-level policy. A direct friend may be allowed to receive summaries from one document but not raw files from another.

Communication Model

EnvoyMesh supports two communication styles:

• Real-time: direct libp2p streams for online peers.
• Asynchronous: signed messages stored locally and retried when peers reconnect.

The system should treat all remote input as untrusted. Every message must be schema-validated before it reaches workflow or AI logic.

Technology Choices

Primary implementation:

• TypeScript.
• Node.js 22+.
• js-libp2p for networking.
• zod for message schemas.
• Ed25519 keys for signatures.
• SQLite or local files for early storage.
• A model router that can select local, cloud, or peer providers behind policy.

Mobile stack (Phase 11):

• Capacitor.js for iOS/Android native wrapper.
• @noble/curves + @noble/hashes for pure-JS Ed25519.
• @capacitor-community/sqlite for on-device SQLite storage.
• @capacitor/filesystem for vault file I/O.
• Relay-only WebSocket transport — no libp2p TCP/QUIC/mDNS on mobile.