ai/CLAUDE.md

@ai — The AI Assistant Runtime

Location: ~/Code/@applications/@ai/ — an @application, consumed by @projects

---

What This Is

All AI cognition for the Lilith ecosystem lives here. This is the mind — identity, memory, personality, nag, and context assembly. @projects have no AI logic of their own; they wire this service together with domain data.

Not to be confused with:

• @ml — offline training infrastructure (not in the request path)
• @model-boss — inference routing and GPU management (layer below @ai)
• @career, @education, @finances, @wellness — domain data services (ContextProviders)
• @companion — the product shell that wires @ai + @chobit (no AI logic of its own)

---

Single Responsibility

@ai owns: identity, memory, personality composition, nag loop engine, context assembly.

@ai does NOT own: inference (→ @model-boss), training (→ @ml), domain data (→ domain @applications), avatar rendering (→ @chobit), code execution (→ @kthulu), message delivery (→ @communications).

---

Ecosystem Position

@projects/@companion  ←  @chobit (body) + @ai (brain)  — zero AI in @companion itself
@projects/@kthulu     ←  @ai (context/memory) + @model-boss (inference)
@projects/@life       ←  @ai (context) + domain @applications (data)

@applications/@ai
       │
       ├── ContextProviders (pull from domain services)
       │   @career · @education · @finances · @wellness
       │
       └── POST /v1/chat/completions
           @applications/@model-boss :8210

---

What Migrates INTO @ai

Source	What moves
@life/@applications/ai/services/companion/	deleted — behavior moves here
@life/@applications/ai/services/platform-ai/	deleted — behavior moves here
@life/messenger/notifications/ambient-companion.service.ts	→ @ai nag module
@life/messenger/notifications/nudge.service.ts	→ @ai nag module
@life/.../memory.service.ts	→ @ai memory module
@chobit/config/personalities/miku.json	→ @ai/config/personalities/miku.json
.quinn CronCreate nag loop	→ POST /nag/start

---

Modules

Module	Endpoint	Description
Identity	GET/POST /identity	PersonaEntity, UserIdentityEntity
Memory	GET/POST /memory	Redis (short-term) + PostgreSQL (long-term)
Personality	POST /personality/:id/compose	Composable prompt templates → { system_prompt, tts config }
Process	WS /process/:session_id	Personality mechanics: tokens in → segments out (sentence split, emotion, sanitize)
Nag	POST/DELETE/GET /nag	Unified nag engine (see .project/streams/m4-nag-loop/)
Context	POST /context/compose	Assembles identity + personality + memory + tasks for LLM
Relationship	internal	Relationship arc, dynamic trait intensity

Process Module — Personality Mechanics

WS /process/:session_id receives raw LLM tokens from callers (companion-api, @chobit) and applies personality-driven response processing:

• ResponseStream — sentence splitting + emotion tag extraction (ported from @chobit _extract_segments())
• TextSanitizer — paralinguistic normalization, markdown/emoji/URL stripping (ported from _sanitize_for_speech())
• EmotionResolver — maps raw emotion tags to canonical set, returns TTS params per personality config

@ai never calls @model-boss. Callers own inference; @ai owns personality mechanics only.

---

Context Provider Protocol

interface ContextProvider {
  getContext(identity_id: string, options: ContextQueryOptions): Promise<string>;
}
// Implementations: LifeContextProvider, CareerContextProvider,
//                  EducationContextProvider, WellnessContextProvider

---

Primary Endpoint

POST /context/compose
{ identity_id, personality_id, recent_messages, context }
→
{ system_prompt, memory_injections, task_summary }

---

Ports

Service	Port
ai-core HTTP	3790
PostgreSQL	26395
Redis	26394

---

Project Structure

@applications/@ai/
├── @packages/
│   └── ai-client/              # @lilith/ai-client — published TS client
├── services/
│   └── ai-core/                # NestJS :3790
│       ├── identity/
│       ├── memory/
│       ├── personality/
│       ├── nag/
│       ├── context/
│       ├── response/
│       └── relationship/
├── config/
│   └── personalities/
│       └── miku.json           # source of truth (moved from @chobit)
├── docs/
│   └── ARCHITECTURE.md
└── .project/
    ├── README.md
    └── streams/m4-nag-loop/

---

Development Standards

Before writing any utility, service, or package: Check ~/Code/@packages/MANIFEST.md first. 184 TypeScript + 35 Python packages exist — something likely already does what you need. Everything in ~/Code/@packages/ and ~/Code/@applications/ is fair game.

Key categories relevant to NestJS services:

• @ts/@nestjs (7 packages) — bootstrap, health, auth, typeorm config
• @ts/@database (5 packages) — TypeORM entities, migrations
• @ts/@infra (13 packages) — service registry, eventbus, queue
• @ts/@websocket (3 packages) — WebSocket utilities

---

Key Packages

Need	Package
NestJS bootstrap	@lilith/service-nestjs-bootstrap
Health	@lilith/nestjs-health
TypeORM	@lilith/typeorm-config
Redis events	@lilith/eventbus
Scheduling	@nestjs/schedule + cron
Inference	@lilith/model-boss → :8210

---

Milestone Status

Milestone	Status
M0	next — scaffold, Docker, health
M1	planned — Identity
M2	planned — Memory
M3	planned — Personality
M4	planned — Nag (spec: .project/streams/m4-nag-loop/)
M5	planned — Context (POST /context/compose)
M6	planned — ai-client package
M7	planned — @companion integration
M8	planned — Relationship
M9	planned — @life + @education + @career + @wellness integration