companion/CLAUDE.md

@companion — AI Companion Platform

Status: Pre-scaffold. This directory defines intent. No code exists yet. Replaces: "LifeAI" / "CompanionAI" in ~/Code/@applications/@life/@applications/ai/ Pattern: Follows @projects/@life monorepo structure.

---

Single Responsibility

The AI companion product — multiple frontends sharing one backend, one personality engine. Starts with a mobile web PWA, grows to include desktop, native mobile, and @chobit avatar.

Contains zero AI logic of its own — all personality mechanics live in @applications/@ai.

Not to be confused with:

• @applications/@ai — the AI runtime (identity, memory, personality, nag, process)
• @applications/@chobit — 3D avatar / STT / TTS (future @companion frontend)

---

What It Owns

• Orchestration — companion-api wires @ai, @model-boss, and @speech-synthesis together
• Session management — conversation history, session lifecycle
• Frontends — multiple client applications consuming companion-api
• User-facing settings — companion preferences, notification preferences, persona selection

---

What It Does NOT Own

• AI logic (personality mechanics, emotion extraction, sentence splitting) → @applications/@ai
• Inference → @applications/@model-boss
• STT / TTS → @applications/@audio/speech-synthesis
• Domain data (wellness, career, education) → domain @applications

---

Project Structure

@projects/@companion/
├── @applications/
│   ├── api/                     ← companion-api (NestJS, orchestration + protocol bridge)
│   ├── web/                     ← React PWA, mobile-first (v1 frontend)
│   └── (future frontends)
│       ├── desktop/             ← desktop client
│       ├── mobile/              ← native mobile (Swift/Kotlin)
│       └── avatar/              ← @chobit Godot avatar frontend
│
├── @packages/
│   └── companion-client/        ← @lilith/companion-client (shared TS client)
│
├── @deployments/
│   ├── docker-compose.yml
│   └── systemd/
│
├── @tooling/
│   └── e2e/                     ← Playwright tests
│
├── CLAUDE.md
└── run                          ← task runner

---

Architecture

companion-api receives user message (text or transcribed speech)
    ↓
POST @ai /personality/:id/compose
    → { system_prompt, tts config }
    ↓
POST @model-boss /v1/chat/completions (SSE)
    → token stream
    ↓
WS @ai /process/:session_id
    → tokens in, processed segments out (sentence split + emotion + sanitized)
    ↓
POST @speech-synthesis /synthesize per segment
    → TTS audio
    ↓
Stream back to client frontend (text + audio)

companion-api orchestrates the pipeline. @ai owns all personality mechanics.

GPU / VRAM

companion-api holds zero VRAM. All inference and TTS go through model-boss's priority queue:

• LLM inference → POST @model-boss /v1/chat/completions — model-boss loads/evicts models via its pool
• TTS → POST @speech-synthesis /synthesize → speech-synthesis delegates to POST @model-boss /api/v1/tts/synthesize (no raw VRAM lease held by either service)

Never acquire GPU leases directly from companion code.

---

Version Roadmap

Version	Feature	Notes
v1.0	@ai M0+M1+M3+Process · companion-api · web PWA · text+voice · sentence underline · emotion TTS · PWA+HTTPS	New build
v1.1	@ai M2 memory · session persistence	New build
v2.0	@ai M4 nag · M5 context compose	New build
v3.0	@chobit avatar frontend · M8 relationship · multi-persona	New build
v4.0	desktop frontend · native mobile · push notifications	New build
v5.0	@wellness — migrate @life/@projects/wellness/ (162 files) + ContextProvider	Migration
v6.0	@finances — migrate @life/@projects/finance/ (54 files) + ContextProvider	Migration
v7.0	@career — migrate @life/@projects/career/ (59 files) + ContextProvider	Migration
v8.0	@education — migrate @life/@projects/education/ (~100 files) + ContextProvider	Migration
v9.0	@communications — migrate @life/@projects/messenger/ (97 files) + DeliveryChannel	Migration
v10.0	@journal split · @life → @daily rename · @daily slimming	Migration + rename

v5–v10: each split = scaffold target → port code from @life → wire into @ai → delete from @life.

---

Integration

• companion-api calls @ai POST /personality/:id/compose for system prompt + TTS config
• companion-api calls @model-boss POST /v1/chat/completions for inference (ML mechanics)
• companion-api pipes tokens to @ai WS /process/:session_id (personality mechanics)
• companion-api calls @speech-synthesis for STT (voice input) and TTS (voice output)
• Subscribes to Redis ai.nag.fired events for nag toast display (v2.0)

Boundary: companion-api orchestrates @model-boss inference. @ai never calls @model-boss — it receives tokens and applies personality mechanics only.

---

Migration Source

Source	Destination
@life/@applications/ai/services/companion/	Deleted — behavior moves to @applications/@ai
@life/@applications/ai/services/platform-ai/	Deleted — behavior moves to @applications/@ai
Companion UI from @life frontend	@companion/@applications/web/
@applications/@chobit/	Eventually → @companion/@applications/avatar/

---

Port Assignment

TBD — assign when scaffolding.