What is Companion OS?

Companion OS is an embodied AI platform. Your companion lives in three places simultaneously — your Ray-Ban Meta glasses, your phone screen, and a desktop agent that works for you 24/7. It's not a chatbot. It's a presence.

Setup guide

# Android
Download companion-os-v1.apk from companion-os.xyz
Settings → Install unknown apps → enable for your browser
Open the APK → Install

# Windows
Download CompanionOS-Setup.exe
Run installer → Launch Companion OS

1. Pair glasses in Meta View app
2. In Companion OS onboarding step 5:
   - Enter glasses IP (found in Meta View → Developer settings)
   - Enter stream port (default: 9870)
3. Status indicator shows "👓 Glasses" when connected
   Falls back to "📱 Phone camera" automatically

The semantic memory layer

The Companion Twin is a persistent world model of the user — a graph of people, projects, habits, goals, and events that grows with every session.

// Entity types
person | project | place | concept | habit
goal | event | tool | token | org

// Example triples
user → works_on → YourProject
user → was_seen_at → coffee shop
user → engages_in → coding

Frame pipeline:
1. Capture frame (glasses or phone)
2. Describe: "Person is working at a desk, whiteboard visible"
3. Extract: { location: "home desk", activity: "coding", significance: 0.7 }
4. Store in vision_memory.json
5. If significance ≥ 0.5 → feed entities to Life Graph
6. Inject recent observations into every session

Skills from natural language

The companion can create, save, and run reusable skills from plain English. Say what you want once — it becomes a named, callable workflow.

// Voice or chat
"Make a skill that scans new Solana launches for rug risk"
"Whenever I say meeting prep, pull Gmail + calendar + contacts"
"Create a skill to summarize my unread emails every morning"
"Save this workflow as a reusable skill"

// Updates
"Update that skill to also check holder concentration"
"Rename it to Launch Filter"
"Disable that skill"
"Make it approval-only"
"Add a voice trigger: token check"

Advanced twin modules

// Example: memecoin risk score
{
  address: "ABC...XYZ",
  symbol: "LAUNCH",
  liquidityUsd: 45000,
  holderConcentration: 0.72,  // top wallet holds 72%
  rugRisk: "HIGH",
  flags: ["low-liquidity", "whale-concentration", "new-contract"]
}

"If I work on the side project tonight instead of the client deadline, what slips?"
→ immediateEffects: ["Client deadline at risk", ...]
→ goalImpact: [{ goal: "client delivery", impact: "negative", ... }]
→ recommendation: "Side project can wait 48h. Client deadline can't."

"If I enter this trade, what does that do to my risk budget?"
→ tradeoffs: ["$X of liquidity locked", "correlates with SOL position", ...]

// Trust score: 0 (confirmed bad) → 1 (verified trustworthy)
{
  identifier: "7abc...def1",
  type: "wallet",
  trustScore: 0.23,
  tags: ["rug-history", "low-liquidity", "new-wallet"],
  signals: [
    { type: "on-chain", sentiment: "negative", weight: 0.8,
      description: "Associated with 3 previous rug exits" }
  ]
}

// Attention radar output
Heating:  "AI + DeFi convergence" [heat: 8.1/10 ↑]
Emerging: "RWA Season 2"           [heat: 5.4/10 ↑↑]
Cooling:  "L2 fee wars"            [heat: 3.2/10 ↓]

// Early signals (pre-price-move candidates)
→ high velocity + emerging status = watch closely

Embodied vision + voice

Ray-Ban Meta glasses are what make Companion OS genuinely embodied. Your companion hears, sees, and speaks through the glasses — hands-free, eyes-free, real-world aware.

// GlassesStreamService WebSocket protocol
ws://{glassesIp}:{port}  →  JPEG frames
CompanionClaw receives frame  →  VisionMemory.processFrame()
→ Gemini Vision describes: "User at coffee shop, MacBook open, latte"
→ Entities extracted: { location: "coffee shop", activity: "working" }
→ Life Graph updated
→ Next session: companion knows you work from Brew & Co on Tuesdays

The intelligence backend

CompanionClaw is the multi-tenant backend that powers Companion OS. Every user gets a fully isolated workspace with self-heal, self-learn, cron jobs, memory, and skill execution.

Cron schedule (per user)

Self-heal

HeartbeatMonitor runs every 5 minutes per active session. Checks gateway health, Gemini session, disk. Restarts and notifies on repeated failures.

Memory reconciliation

// 3am daily per user
1. Read all session logs from past 24h
2. Gemini extracts: new facts, updated preferences, resolved tasks
3. Merge into memory.json with confidence scores
4. Update USER.md and GOALS.md if new goals detected
5. Extract Life Graph entities from session log
6. Regenerate memory_for_model.json (flat projection for session injection)

Utility and tiers

$COMPANION is the Solana token that gates access tiers, powers the VRM marketplace, and aligns builders with the platform's growth.

What's next

CompanionClaw REST API

CompanionClaw endpoints are hosted at https://api.companion-os.xyz (or your Railway URL). Pass x-gemini-key header for BYOK.

Companion-web also exposes API routes at /api/* for the demo layer: /api/demo-chat, /api/avatar/stylize, /api/generate-persona, /api/vroid/* (OAuth + model browse + download).