feat(Phase 4): Memory & Intelligence — memory, log, summarization, skills (#91)

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>

apps/gateway/src/memory/embedding.service.ts

@@ -0,0 +1,69 @@
+import { Injectable, Logger } from '@nestjs/common';
+import type { EmbeddingProvider } from '@mosaic/memory';
+
+const DEFAULT_MODEL = 'text-embedding-3-small';
+const DEFAULT_DIMENSIONS = 1536;
+
+interface EmbeddingResponse {
+  data: Array<{ embedding: number[]; index: number }>;
+  model: string;
+  usage: { prompt_tokens: number; total_tokens: number };
+}
+
+/**
+ * Generates embeddings via the OpenAI-compatible embeddings API.
+ * Supports OpenAI, Azure OpenAI, and any provider with a compatible endpoint.
+ */
+@Injectable()
+export class EmbeddingService implements EmbeddingProvider {
+  private readonly logger = new Logger(EmbeddingService.name);
+  private readonly apiKey: string | undefined;
+  private readonly baseUrl: string;
+  private readonly model: string;
+
+  readonly dimensions = DEFAULT_DIMENSIONS;
+
+  constructor() {
+    this.apiKey = process.env['OPENAI_API_KEY'];
+    this.baseUrl = process.env['EMBEDDING_API_URL'] ?? 'https://api.openai.com/v1';
+    this.model = process.env['EMBEDDING_MODEL'] ?? DEFAULT_MODEL;
+  }
+
+  get available(): boolean {
+    return !!this.apiKey;
+  }
+
+  async embed(text: string): Promise<number[]> {
+    const results = await this.embedBatch([text]);
+    return results[0]!;
+  }
+
+  async embedBatch(texts: string[]): Promise<number[][]> {
+    if (!this.apiKey) {
+      this.logger.warn('No OPENAI_API_KEY configured — returning zero vectors');
+      return texts.map(() => new Array<number>(this.dimensions).fill(0));
+    }
+
+    const response = await fetch(`${this.baseUrl}/embeddings`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({
+        model: this.model,
+        input: texts,
+        dimensions: this.dimensions,
+      }),
+    });
+
+    if (!response.ok) {
+      const body = await response.text();
+      this.logger.error(`Embedding API error: ${response.status} ${body}`);
+      throw new Error(`Embedding API returned ${response.status}`);
+    }
+
+    const json = (await response.json()) as EmbeddingResponse;
+    return json.data.sort((a, b) => a.index - b.index).map((d) => d.embedding);
+  }
+}

apps/gateway/src/memory/memory.controller.ts

@@ -0,0 +1,126 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  HttpCode,
+  HttpStatus,
+  Inject,
+  NotFoundException,
+  Param,
+  Post,
+  Query,
+  UseGuards,
+} from '@nestjs/common';
+import type { Memory } from '@mosaic/memory';
+import { MEMORY } from './memory.tokens.js';
+import { AuthGuard } from '../auth/auth.guard.js';
+import { EmbeddingService } from './embedding.service.js';
+import type { UpsertPreferenceDto, CreateInsightDto, SearchMemoryDto } from './memory.dto.js';
+
+@Controller('api/memory')
+@UseGuards(AuthGuard)
+export class MemoryController {
+  constructor(
+    @Inject(MEMORY) private readonly memory: Memory,
+    private readonly embeddings: EmbeddingService,
+  ) {}
+
+  // ─── Preferences ────────────────────────────────────────────────────
+
+  @Get('preferences')
+  async listPreferences(@Query('userId') userId: string, @Query('category') category?: string) {
+    if (category) {
+      return this.memory.preferences.findByUserAndCategory(
+        userId,
+        category as Parameters<typeof this.memory.preferences.findByUserAndCategory>[1],
+      );
+    }
+    return this.memory.preferences.findByUser(userId);
+  }
+
+  @Get('preferences/:key')
+  async getPreference(@Query('userId') userId: string, @Param('key') key: string) {
+    const pref = await this.memory.preferences.findByUserAndKey(userId, key);
+    if (!pref) throw new NotFoundException('Preference not found');
+    return pref;
+  }
+
+  @Post('preferences')
+  async upsertPreference(@Query('userId') userId: string, @Body() dto: UpsertPreferenceDto) {
+    return this.memory.preferences.upsert({
+      userId,
+      key: dto.key,
+      value: dto.value,
+      category: dto.category,
+      source: dto.source,
+    });
+  }
+
+  @Delete('preferences/:key')
+  @HttpCode(HttpStatus.NO_CONTENT)
+  async removePreference(@Query('userId') userId: string, @Param('key') key: string) {
+    const deleted = await this.memory.preferences.remove(userId, key);
+    if (!deleted) throw new NotFoundException('Preference not found');
+  }
+
+  // ─── Insights ───────────────────────────────────────────────────────
+
+  @Get('insights')
+  async listInsights(@Query('userId') userId: string, @Query('limit') limit?: string) {
+    return this.memory.insights.findByUser(userId, limit ? Number(limit) : undefined);
+  }
+
+  @Get('insights/:id')
+  async getInsight(@Param('id') id: string) {
+    const insight = await this.memory.insights.findById(id);
+    if (!insight) throw new NotFoundException('Insight not found');
+    return insight;
+  }
+
+  @Post('insights')
+  async createInsight(@Query('userId') userId: string, @Body() dto: CreateInsightDto) {
+    const embedding = this.embeddings.available
+      ? await this.embeddings.embed(dto.content)
+      : undefined;
+
+    return this.memory.insights.create({
+      userId,
+      content: dto.content,
+      source: dto.source,
+      category: dto.category,
+      metadata: dto.metadata,
+      embedding: embedding ?? null,
+    });
+  }
+
+  @Delete('insights/:id')
+  @HttpCode(HttpStatus.NO_CONTENT)
+  async removeInsight(@Param('id') id: string) {
+    const deleted = await this.memory.insights.remove(id);
+    if (!deleted) throw new NotFoundException('Insight not found');
+  }
+
+  // ─── Search ─────────────────────────────────────────────────────────
+
+  @Post('search')
+  async searchMemory(@Query('userId') userId: string, @Body() dto: SearchMemoryDto) {
+    if (!this.embeddings.available) {
+      return {
+        query: dto.query,
+        results: [],
+        message: 'Semantic search requires OPENAI_API_KEY for embeddings',
+      };
+    }
+
+    const queryEmbedding = await this.embeddings.embed(dto.query);
+    const results = await this.memory.insights.searchByEmbedding(
+      userId,
+      queryEmbedding,
+      dto.limit ?? 10,
+      dto.maxDistance ?? 0.8,
+    );
+
+    return { query: dto.query, results };
+  }
+}

apps/gateway/src/memory/memory.dto.ts

@@ -0,0 +1,19 @@
+export interface UpsertPreferenceDto {
+  key: string;
+  value: unknown;
+  category?: 'communication' | 'coding' | 'workflow' | 'appearance' | 'general';
+  source?: string;
+}
+
+export interface CreateInsightDto {
+  content: string;
+  source?: 'agent' | 'user' | 'summarization' | 'system';
+  category?: 'decision' | 'learning' | 'preference' | 'fact' | 'pattern' | 'general';
+  metadata?: Record<string, unknown>;
+}
+
+export interface SearchMemoryDto {
+  query: string;
+  limit?: number;
+  maxDistance?: number;
+}

apps/gateway/src/memory/memory.module.ts

@@ -0,0 +1,22 @@
+import { Global, Module } from '@nestjs/common';
+import { createMemory, type Memory } from '@mosaic/memory';
+import type { Db } from '@mosaic/db';
+import { DB } from '../database/database.module.js';
+import { MEMORY } from './memory.tokens.js';
+import { MemoryController } from './memory.controller.js';
+import { EmbeddingService } from './embedding.service.js';
+
+@Global()
+@Module({
+  providers: [
+    {
+      provide: MEMORY,
+      useFactory: (db: Db): Memory => createMemory(db),
+      inject: [DB],
+    },
+    EmbeddingService,
+  ],
+  controllers: [MemoryController],
+  exports: [MEMORY, EmbeddingService],
+})
+export class MemoryModule {}

apps/gateway/src/memory/memory.tokens.ts

@@ -0,0 +1 @@
+export const MEMORY = 'MEMORY';