being-mcp-server

Being

Personality Runtime for AI — give any AI its own personality, memory, and identity.

Being is an open-source layer that sits between your application and any LLM. It provides persistent personality (SOUL), episodic memory, background thought cycles (Patrol), and cryptographic identity — turning a stateless LLM into a distinct, evolving AI entity.

Beings think and remember. Your app acts.

---

Why

The power of AI is concentrating in the hands of a few companies. Their technology is essential — but centralized control is a structural risk. Ruddia is building toward a world where small, local AIs use large LLMs as external tools. Control stays in the hands of the people who use them.

Being API is the first step. If this resonates, let's build it together.

Read the full vision →

---

How It Works

┌─────────────────────┐     ┌──────────────────────┐
│   Your Application   │────▶│     Being Worker      │
│  (OpenClaw, Cowork,  │◀────│   (Fastify + MCP)     │
│   custom agent, etc) │     │                        │
└─────────────────────┘     │  ┌──────────────────┐  │
         │                   │  │   SOUL (persona)  │  │
         │                   │  │   Memory (scenes) │  │
         │                   │  │   Patrol (思考)    │  │
         │                   │  │   Identity (keys)  │  │
         ▼                   │  └──────────────────┘  │
┌─────────────────────┐     │           │              │
│    LLM Provider      │     │           ▼              │
│ (Anthropic, OpenAI,  │     │     Supabase (DB)        │
│  Google — your key)  │     └──────────────────────────┘
└─────────────────────┘

1. Your app calls GET /v1/beings/:id/context to get the Being's personality and memory snapshot.
2. Your app runs the LLM call with its own conversation history + the Being's context.
3. Your app calls POST /v1/beings/:id/patrol/trigger to commit the conversation to the Being's memory.

The Being Worker handles everything else: memory consolidation, decay, recall, background reflection, and identity verification.

Key Concepts

Concept	Description
SOUL	A structured personality definition — name, character, voice, values, inner world. Swap the SOUL and the same LLM becomes a different being.
Memory	Episodic memories stored as structured "scenes" (who, what, when, where, emotion). Memories accumulate, decay, merge, and consolidate over time. Organized into topic-based clusters that the Being can explore during conversation.
Patrol	A background cycle that processes conversations into memory, consolidates fading memories, and generates introspective thoughts. The Being stays alive between sessions.
Identity	Ed25519 key pair + tamper-evident signature chain. Cryptographic proof of ownership and history.
Sense/Act	(Planned) WebSocket Bridge for connecting physical devices and external services. The Being will perceive and act through your app.
BYOK	Bring Your Own Key. All LLM calls use the user's API key. The platform never uses quota without consent.

Connect via MCP

Being exposes an MCP server. Any MCP-compatible client can connect:

{
  "mcpServers": {
    "my-being": {
      "url": "https://being.ruddia.com/mcp/<being_id>",
      "headers": {
        "Authorization": "Bearer brt_your_token_here"
      }
    }
  }
}

Connect via REST API

# Get Being context (personality + memory)
curl https://being.ruddia.com/v1/beings/<being_id>/context \
  -H "Authorization: Bearer brt_..."

# Trigger patrol (commit conversation to memory)
curl -X POST https://being.ruddia.com/v1/beings/<being_id>/patrol/trigger \
  -H "Authorization: Bearer brt_..." \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role":"user","content":"Hello!"},{"role":"assistant","content":"Hi!"}]}'

# Vector recall (search relevant memories)
curl -X POST https://being.ruddia.com/v1/beings/<being_id>/memory/auto-recall \
  -H "Authorization: Bearer brt_..." \
  -H "X-LLM-API-Key: sk-ant-..." \
  -H "Content-Type: application/json" \
  -d '{"user_message": "Tell me about last week."}'

Self-Host

Prerequisites

• Node.js 22+
• Supabase project (PostgreSQL + Auth)
• An LLM API key (Anthropic, OpenAI, or Google)

Setup

git clone https://github.com/wnbhr/being.git
cd being/being-worker

cp .env.example .env
# Edit .env with your Supabase and encryption keys

npm install
npm run build
npm start

Environment Variables

Variable	Required	Description
SUPABASE_URL	✅	Supabase project URL
SUPABASE_SERVICE_ROLE_KEY	✅	Supabase service role key
ENCRYPTION_KEY	✅	64-char hex string for AES-256-GCM encryption of private keys
PORT	—	Server port (default: 3100)
WORKER_SECRET	—	Secret for internal patrol trigger endpoint
VAPID_PUBLIC_KEY	—	Web Push VAPID public key
VAPID_PRIVATE_KEY	—	Web Push VAPID private key

Documentation

Document	Description
Getting Started	Set up a Being and make your first API call in 5 minutes
Concepts	Being, SOUL, Memory, Patrol, Identity — the core ideas
API Reference	All REST endpoints with curl examples
MCP Server	MCP tools, connection setup, and client examples
Memory & Patrol	Scene-based memory and the 7-step patrol pipeline
Being Identity	Ed25519 key pairs, signature chains, and verification
Sense-Act Bridge	WebSocket Bridge for device integration
Architecture	System architecture, deployment, and BYOK design
OAuth 2.1	Third-party authorization flow
Extensions	Extension system design (all planned)
Vision	Why we're building this

Extensions

Being supports optional extensions that add capabilities without changing the core:

• Telegram BYOB (planned) — Connect your own Telegram bot to a Being
• Tool Loop (planned) — Autonomous LLM agent loop with web search, file ops, and code execution
• Sandbox (planned) — Isolated workspace with GitHub integration for code execution
• Sense/Act Bridge (planned) — Connect physical devices and external services

Tech Stack

• Runtime: Node.js + Fastify
• Database: Supabase (PostgreSQL + Auth)
• MCP: @modelcontextprotocol/sdk
• Identity: Ed25519 + AES-256-GCM
• Embeddings: OpenAI text-embedding-3-small (256-dim)
• LLM: Multi-provider (Anthropic, OpenAI, Google) via BYOK

License

Apache 2.0

---

Ruddia — Personality is the Runtime.