ai/.project

@ai Project Management

Why @ai Exists

Every AI-enabled application in this ecosystem independently re-implemented (or skipped) the same four concerns: identity, memory, personality, and context assembly. @chobit had miku.json and a 10-message ephemeral history. @life had memory.service.ts siloed per-platform, inline agent personas, and its own ambient companion service (AmbientCompanionService). @kthulu had no persistent memory or identity at all. Each app assembled LLM prompts differently with no shared contract.

@ai consolidates those four concerns into a single runtime. It is the mind of the assistant. Applications are the body (@chobit), hands (@kthulu), and world (@life, @education, @career).

What @ai Replaces

What's being removed	Where it lived	Replaced by
@life/life-ai companion service	@life/@applications/ai/services/companion/	@ai identity + nag + context
@life/platform-ai service	@life/@applications/ai/services/platform-ai/	@ai identity + nag + context
AmbientCompanionService	@life/messenger/notifications/backend/	@ai M4 nag module
NudgeService	@life/messenger/notifications/backend/	@ai M4 nag module
memory.service.ts	@life/platform-ai/features/assistant/	@ai M2 memory module
miku.json (local)	@chobit/config/personalities/	@ai M3 personality module
.quinn CronCreate nag	~/.claude/commands/nag-start.md	@ai M4 POST /nag/start

Correct Location

Current: ~/Code/@applications/@ai/ (wrong tier — placed in infrastructure layer) Correct: ~/Code/@projects/@ai/ (a domain project, like @life and @kthulu)

When M0 scaffold begins, create at @projects/@ai/, not @applications/@ai/. Exported packages go in @projects/@ai/@packages/ (not global ~/Code/@packages/).

Directory Structure

.project/
├── README.md              # This file
├── streams/               # Active feature workstreams
│   └── <stream-name>/
│       ├── README.md      # Feature overview and architecture
│       ├── STATUS.md      # Current progress and blockers
│       ├── HANDOFF.md     # Session handoff context
│       └── NOTES.md       # Technical decisions and learnings
├── history/               # Completed work records
│   └── YYYYMMDD_description.md
└── templates/             # Stream templates

Active Streams

None — project not yet scaffolded.

Milestone Roadmap

M0: Project Scaffold 🔲

• @applications/@ai/ directory + app.manifest.yaml
• services/ai-core/ — NestJS app via @lilith/service-nestjs-bootstrap
• Docker compose: PostgreSQL (26395) + Redis (26394)
• GET /health endpoint
• ./run task runner (dev/stop/status/logs)
• packages/ai-client/ skeleton (@lilith/ai-client)

M1: Identity Module 🔲

• PersonaEntity — id, name, voice_id, tags, description (maps from miku.json)
• UserIdentityEntity — id, display_name, bound_persona_id, metadata JSONB
• CRUD endpoints: GET/POST/PATCH /identity, GET/POST /identity/:id/personas
• Seed: "quinn" identity + "miku" persona from existing godot-desktop/config/personalities/miku.json
• Client: ai-client/identity.ts

M2: Memory Module 🔲

• MemoryEntryEntity — key, content, category, tags[], metadata JSONB, soft-delete (pattern from @life/platform-ai/features/assistant/generic-tools/services/memory.service.ts)
• Redis cache layer with PG fallback (pattern from @ml/knowledge-platform/features/api/service/src/cache/subject-cache.ts)
• Endpoints: GET/POST/PATCH/DELETE /memory, GET /memory/search?q=&tags=&category=
• TTL-based cache with subject invalidation
• Client: ai-client/memory.ts

M3: Personality Module 🔲

• Personality template loader — reads JSON files from config/personalities/
• Prompt composer — assembles system prompt from template + context payload (ports the logic from @chobit/godot-desktop/platform/conversation/prompt_composer.gd)
• Composition order: identity → voice_constraint → traits → negatives → emotion_tags → depth_tier → context_modifiers → situation_overrides
• Endpoints:
  • GET /personality — list available personalities
  • GET /personality/:id — personality definition
  • POST /personality/:id/compose — compose system prompt from context payload
• Migrate miku.json from @chobit to @ai as the source of truth
• Client: ai-client/personality.ts

M4: Tasks Module 🔲

• TaskListEntity — id, name, identity_id, description, metadata JSONB
• TaskEntity — id, list_id, content, priority (0–100), status, due_at, tags[], metadata JSONB
  • status: pending | in_progress | done | snoozed
• Redis pub/sub via @lilith/eventbus — emit ai.task.created, ai.task.updated, ai.task.completed
• Endpoints:
  • GET/POST /tasks — list management
  • GET/POST /tasks/:list_id/items — task CRUD
  • PATCH /tasks/:list_id/items/:id — update status/priority
• Seed: "quinn-platforms" task list from .quinn/business/registrations.md
• Client: ai-client/tasks.ts

Full stream spec: .project/streams/m4-nag-loop/README.md

Two working reference implementations inform M4's design:

• .quinn nag loop — file-based context, Miku TTS, CronCreate (simple, working today)
• @life ambient companion — API-based context, iMessage, NudgeSession entity (sophisticated, production)

M4 generalizes both into a unified nag engine with ContextProvider + DeliveryChannel interfaces, NagLoopEntity + NagSessionEntity persistence, and POST/DELETE/GET /nag/* endpoints.

M5: Context Module 🔲

The primary integration endpoint — assembles everything into a ready-to-use LLM payload.

• POST /context/compose — accepts identity_id, personality_id, recent_messages[], context{}
• Assembly pipeline:
  1. Load identity → user binding
  2. Compose personality system prompt (→ M3 endpoint)
  3. Query memory for relevant entries (semantic search on recent_messages)
  4. Fetch active tasks for identity → optional task_summary string
  5. Return: { system_prompt, memory_injections[], task_summary }
• Replaces: @chobit direct model-boss calls, @life memory.service.ts inline assembly
• Client: ai-client/context.ts

M5b: Response Format Module 🔲

Decides model selection and dual-response config per-request.

• ResponseFormat returned alongside system_prompt from /context/compose
• Model selection logic: conversation → qwen3-4b, complex → qwen3-32b, TTS always → qwen3-4b
• Dual-response modes: text_only | tts_only | dual
• Depth tier → TTS max_tokens mapping (from personality module)
• Consumer capability registration: declare tts_capable: true/false on identity
• tts config includes: model, max_tokens, voice_id, personality_id
• Injected TTS system constraint: "Respond in 1–3 short spoken sentences. No lists, no markdown."
• When to speak: companions (dual), nag loop (tts_only), API (text_only), notifications (tts_only)

M6: ai-client Package 🔲

• Publish @lilith/ai-client to Verdaccio (npm.nasty.sh:4873)
• Full TypeScript client covering all 5 modules
• React hooks: useMemory(), useTasks(), usePersonality()
• Auto-retry + error handling
• Use npx @lilith/dev-publish for fast iteration

M7: @chobit Integration 🔲

Wire @chobit to use @ai:

• llm_client.gd → HTTP POST /context/compose (replaces raw model-boss endpoint)
• conversation_store.gd → async sync to POST /memory after each turn
• Remove MAX_HISTORY = 10 cap — full history lives in @ai
• prompt_composer.gd → becomes thin HTTP client to POST /personality/miku/compose
• Extend Redis eventbus namespace: chobit.task.* events from @ai

M8: Relationship Module 🔲

Dynamic personality — relationship arc, trait intensity, shared history injection.

• RelationshipEntity — identity_id, persona_id, depth (new→familiar→close→intimate), interaction_count, significant_event_keys[], tone_notes[]
• Depth gates: each stage unlocks new personality behaviors (teasing, callbacks, directness, shorthand)
• Dynamic trait intensity: base_intensity + context modifiers (mood, relationship, time_of_day)
• Significant event tagging: memory entries tagged significant_event — financial wins, disclosures, milestones, patterns
• Shared history injection: top 3 significant memories injected into system prompt as "context you share"
• Relationship advances on interaction_count thresholds: 5 → familiar, 30 → close, 100 → intimate
• tone_notes[] accumulate learned preferences: "prefers directness", "sensitive about name change"

M9: @life + @kthulu Integration 🔲

• @life companion service: replace memory.service.ts with @lilith/ai-client calls
• @kthulu context-builder: add identity layer — @ai /context/compose wraps code context
• Both consume same @lilith/ai-client package

---

Key Technical Decisions

Decision	Choice	Rationale
Separate from @ml	Yes	@ml = inference/training/RAG; @ai = identity/memory/personality/tasks
Memory storage	Redis (short-term) + PostgreSQL (long-term)	Inherit @life pattern — proven in production
Session management	@lilith/ml-session-manager	Already exists, pluggable store interface
Personality format	JSON templates (inherit miku.json schema)	Already proven in @chobit M3-M5
Task pub/sub	@lilith/eventbus (Redis)	Already used in @chobit bridge, consistent infrastructure
Port range	3790 (HTTP), 26394 (Redis), 26395 (PG)	Adjacent to @life (3700) and @kthulu (3780)
Primary endpoint	/context/compose	Single integration point for all consumers; compose-on-demand

Cross-Project Context

Project	What @ai Gives It
@chobit	Unbounded memory (removes 10-msg cap), server-side personality, task awareness in conversation
@life	Shared memory store instead of platform-siloed memory.service.ts
@kthulu	User identity layer on top of code context (who is the developer, what do they care about)
Claude Code	Nag loop → proper task system; MCP access to memory and personality