diff --git a/package.json b/package.json index 423c24a..56bdcf3 100644 --- a/package.json +++ b/package.json @@ -30,6 +30,7 @@ "eval:tournament": "node --import tsx src/eval/cli.ts tournament", "eval:tournament:moderation": "node --import tsx src/eval/cli.ts tournament --skill=moderation", "eval:tournament-results": "node --import tsx src/eval/cli.ts tournament-results", + "ingest:knowledge": "node --import tsx scripts/ingest-knowledge.ts", "review:list": "node --import tsx src/operations/cli.ts review:list", "review:show": "node --import tsx src/operations/cli.ts review:show", "review:resolve": "node --import tsx src/operations/cli.ts review:resolve", diff --git a/scripts/ingest-knowledge.ts b/scripts/ingest-knowledge.ts new file mode 100644 index 0000000..fa0254f --- /dev/null +++ b/scripts/ingest-knowledge.ts @@ -0,0 +1,67 @@ +import { loadEnvironmentFromNodeEnv } from "../src/common/env-loader.js"; + +loadEnvironmentFromNodeEnv(); + +const { initLogger, getLogger } = await import("../src/observability/logger.js"); +initLogger(); +const logger = getLogger(); +const { GarnetClient } = await import("../src/common/garnet.js"); +const { getRawSecret } = await import("../src/common/secret-manager.js"); +const { initMongoDB, closeMongoDB } = await import("../src/common/mongodb.js"); +const { createMemoryService } = await import("../src/memory/memory-service.js"); +const { ingestMarkdownResources } = await import("../src/memory/knowledge-ingest.js"); + +function firstNonEmpty( + ...values: Array +): string | undefined { + for (const value of values) { + if (value?.trim()) { + return value.trim(); + } + } + return undefined; +} + +const dryRun = process.argv.includes("--dry-run"); +const mongoConnectionString = firstNonEmpty( + getRawSecret("MONGODB_CONNECTION_STRING"), + process.env["MONGODB_CONNECTION_STRING"], +); + +if (!mongoConnectionString) { + throw new Error("MONGODB_CONNECTION_STRING is required for knowledge ingest"); +} + +const garnetClient = new GarnetClient(); +await garnetClient.connect(); + +try { + const mongoConnection = await initMongoDB(mongoConnectionString); + const memoryService = createMemoryService({ + garnetClient, + mongooseConnection: mongoConnection, + }); + + const [onboarding, moderation] = await Promise.all([ + ingestMarkdownResources(memoryService, { + baseDir: "src/skills/onboarding/resources", + category: "onboarding-step", + dryRun, + skill: "onboarding", + }), + ingestMarkdownResources(memoryService, { + baseDir: "src/skills/moderation/resources", + category: "rule", + dryRun, + skill: "moderation", + }), + ]); + + logger.info( + { dryRun, moderation, onboarding }, + "✓ Knowledge ingest completed", + ); +} finally { + await closeMongoDB(); + await garnetClient.close(); +} diff --git a/src/config.test.ts b/src/config.test.ts index bbd2667..a512ab5 100644 --- a/src/config.test.ts +++ b/src/config.test.ts @@ -5,8 +5,11 @@ import { getAlertThresholdEvalScoreDropPct, getAlertThresholdLlmErrorRate, getAlertThresholdP95LatencyMs, + getEmbeddingModel, + getEmbeddingProvider, getPhoenixLogPrompts, getPhoenixOtlpEndpoint, + getRagEnabled, getSlackAlertWebhookUrl, getSlackWebhookTimeoutMs, getSupervisorLlmResponseEnabled, @@ -21,6 +24,9 @@ const ENV_KEYS = [ "ALERT_THRESHOLD_LLM_ERROR_RATE_ONBOARDING", "ALERT_THRESHOLD_P95_LATENCY_MS", "ALERT_THRESHOLD_P95_LATENCY_MS_ONBOARDING", + "AGENT_RAG_ENABLED", + "EMBEDDING_MODEL", + "EMBEDDING_PROVIDER", "PHOENIX_LOG_PROMPTS", "PHOENIX_OTLP_ENDPOINT", "SLACK_ALERT_WEBHOOK_URL", @@ -77,6 +83,20 @@ describe("config", () => { expect(getPhoenixLogPrompts()).toBe(true); }); + it("reads RAG and embedding configuration", () => { + expect(getRagEnabled()).toBe(true); + expect(getEmbeddingProvider()).toBe("openrouter"); + expect(getEmbeddingModel()).toBe("openai/text-embedding-3-small"); + + vi.stubEnv("AGENT_RAG_ENABLED", "false"); + vi.stubEnv("EMBEDDING_PROVIDER", "openai"); + vi.stubEnv("EMBEDDING_MODEL", "custom-embedding"); + + expect(getRagEnabled()).toBe(false); + expect(getEmbeddingProvider()).toBe("openai"); + expect(getEmbeddingModel()).toBe("custom-embedding"); + }); + it("enables supervisor LLM user messages by default with env override", () => { expect(getSupervisorLlmResponseEnabled()).toBe(true); diff --git a/src/config.ts b/src/config.ts index 491363e..5ac65ea 100644 --- a/src/config.ts +++ b/src/config.ts @@ -129,6 +129,47 @@ export function getPhoenixLogPrompts(): boolean { return getBoolean("PHOENIX_LOG_PROMPTS", false); } +export function getRagEnabled(): boolean { + return getBoolean("AGENT_RAG_ENABLED", true); +} + +export function getEmbeddingProvider(): "openrouter" | "openai" { + const raw = process.env["EMBEDDING_PROVIDER"]?.trim().toLowerCase(); + return raw === "openai" ? "openai" : "openrouter"; +} + +export function getEmbeddingModel(provider = getEmbeddingProvider()): string { + const configured = process.env["EMBEDDING_MODEL"]?.trim(); + if (configured) { + return configured; + } + return provider === "openai" + ? "text-embedding-3-small" + : "openai/text-embedding-3-small"; +} + +export function getEmbeddingApiUrl(provider = getEmbeddingProvider()): string { + const configured = process.env["EMBEDDING_API_URL"]?.trim(); + if (configured) { + return configured; + } + return provider === "openai" + ? "https://api.openai.com/v1" + : "https://openrouter.ai/api/v1"; +} + +export function getEmbeddingDimensions(): number { + return getPositiveNumber("EMBEDDING_DIMENSIONS", 1536); +} + +export function getEmbeddingRequestTimeoutMs(): number { + return getPositiveNumber("EMBEDDING_REQUEST_TIMEOUT_MS", 30_000); +} + +export function getKnowledgeSearchCandidateLimit(): number { + return getPositiveNumber("KNOWLEDGE_SEARCH_CANDIDATE_LIMIT", 500); +} + export function getRequestSubject(): string { return ( process.env["AGENT_REQUEST_SUBJECT"]?.trim() || "lolympus-agent.request" diff --git a/src/eval/runner.ts b/src/eval/runner.ts index 9db9fc8..e96b172 100644 --- a/src/eval/runner.ts +++ b/src/eval/runner.ts @@ -49,6 +49,7 @@ import type { EvalReportSummary, EvalSummaryDelta, } from "./types.js"; +import { createMemoryService } from "../memory/memory-service.js"; const DEFAULT_REPORTS_DIR = "eval-reports"; const LEGACY_BASELINE_FILE = `${DEFAULT_REPORTS_DIR}/baseline.json`; @@ -67,13 +68,19 @@ interface SkillRunnerDeps { } const SKILL_RUNNER_FACTORIES: Record Skill> = { - moderation: (deps) => new ModerationSkill(deps.llm), + moderation: (deps) => + new ModerationSkill( + deps.llm, + createMemoryService({ garnetClient: deps.garnet }), + ), onboarding: (deps) => new OnboardingSkill( deps.garnet, deps.llm, deps.room, noopShadowEvalPublisher, + undefined, + createMemoryService({ garnetClient: deps.garnet }), ), supervisor: (deps) => new SupervisorSkill(deps.garnet, { diff --git a/src/main.ts b/src/main.ts index c1f1f4c..ce77289 100644 --- a/src/main.ts +++ b/src/main.ts @@ -30,6 +30,7 @@ const { ShadowEvalBus } = await import("./eval/shadow-bus.js"); const { LlmClient } = await import("./llm/index.js"); const { getRawSecret, getSecret } = await import("./common/secret-manager.js"); const { initMongoDB, closeMongoDB } = await import("./common/mongodb.js"); +const { createMemoryService } = await import("./memory/memory-service.js"); const { RoomContextService } = await import("./room-context/index.js"); const { startMetricsServer, stopMetricsServer } = await import( "./observability/metrics-server.js" @@ -201,13 +202,14 @@ async function bootstrap(): Promise { } // MongoDB + RoomContextService setup (optional) + let mongoConnection: Awaited> | undefined; let roomContextService: InstanceType | undefined; const mongoConnectionString = firstNonEmpty( getSecret("MONGODB_CONNECTION_STRING"), process.env["MONGODB_CONNECTION_STRING"], ); if (mongoConnectionString) { - await initMongoDB(mongoConnectionString); + mongoConnection = await initMongoDB(mongoConnectionString); // 시크릿의 projectId를 환경변수로 전파 (config.ts에서 참조) const mongoProjectId = firstNonEmpty( getSecret("MONGODB_PROJECT_ID"), @@ -222,6 +224,11 @@ async function bootstrap(): Promise { logger.warn("[MongoDB] No connection string configured — room context disabled"); } + const memoryService = createMemoryService({ + garnetClient, + mongooseConnection: mongoConnection, + }); + // Agent setup const conversationStore = new ConversationStore(garnetClient); const skillRegistry = SkillRegistry.load(resolve(process.cwd(), "src", "skills")); @@ -259,6 +266,7 @@ async function bootstrap(): Promise { factory({ garnetClient, llmClient, + memoryService, natsClient, roomContextService, shadowEvalBus, diff --git a/src/memory/cosine.test.ts b/src/memory/cosine.test.ts new file mode 100644 index 0000000..f975ac4 --- /dev/null +++ b/src/memory/cosine.test.ts @@ -0,0 +1,28 @@ +import { describe, expect, it } from "vitest"; + +import { cosineSimilarity, rankByCosineSimilarity } from "./cosine.js"; + +describe("cosineSimilarity", () => { + it("scores identical vectors above unrelated vectors", () => { + expect(cosineSimilarity([1, 0], [1, 0])).toBeCloseTo(1); + expect(cosineSimilarity([1, 0], [0, 1])).toBeCloseTo(0); + }); + + it("ranks documents by cosine score", () => { + const ranked = rankByCosineSimilarity( + [1, 0], + [ + { embedding: [0, 1], id: "b" }, + { embedding: [1, 0], id: "a" }, + ], + 1, + ); + + expect(ranked).toEqual([ + expect.objectContaining({ + id: "a", + score: 1, + }), + ]); + }); +}); diff --git a/src/memory/cosine.ts b/src/memory/cosine.ts new file mode 100644 index 0000000..e230957 --- /dev/null +++ b/src/memory/cosine.ts @@ -0,0 +1,40 @@ +export function cosineSimilarity(a: number[], b: number[]): number { + if (a.length === 0 || a.length !== b.length) { + return 0; + } + + let dot = 0; + let magnitudeA = 0; + let magnitudeB = 0; + for (let index = 0; index < a.length; index += 1) { + const left = a[index] ?? 0; + const right = b[index] ?? 0; + dot += left * right; + magnitudeA += left * left; + magnitudeB += right * right; + } + + if (magnitudeA === 0 || magnitudeB === 0) { + return 0; + } + + return dot / (Math.sqrt(magnitudeA) * Math.sqrt(magnitudeB)); +} + +export function rankByCosineSimilarity( + query: number[], + docs: T[], + topK: number, +): Array { + if (topK <= 0) { + return []; + } + + return docs + .map((doc) => ({ + ...doc, + score: cosineSimilarity(query, doc.embedding), + })) + .sort((left, right) => right.score - left.score) + .slice(0, topK); +} diff --git a/src/memory/embedding-client.ts b/src/memory/embedding-client.ts new file mode 100644 index 0000000..98c3129 --- /dev/null +++ b/src/memory/embedding-client.ts @@ -0,0 +1,146 @@ +import { getRawSecret } from "@common/secret-manager"; +import { getLogger } from "@obs/logger"; +import { + getEmbeddingApiUrl, + getEmbeddingDimensions, + getEmbeddingModel, + getEmbeddingProvider, + getEmbeddingRequestTimeoutMs, +} from "../config.js"; + +export interface EmbeddingClient { + embed(text: string): Promise; + embedBatch(texts: string[]): Promise; + readonly model: string; + readonly dimensions: number; +} + +interface EmbeddingResponse { + data?: Array<{ + embedding?: number[] | undefined; + index?: number | undefined; + }> | undefined; + model?: string | undefined; +} + +abstract class HttpEmbeddingClient implements EmbeddingClient { + constructor( + readonly model: string, + readonly dimensions: number, + private readonly apiKey: string | undefined, + private readonly baseUrl: string, + ) {} + + async embed(text: string): Promise { + const [embedding] = await this.embedBatch([text]); + if (!embedding) { + throw new Error("Embedding response did not include an embedding"); + } + return embedding; + } + + async embedBatch(texts: string[]): Promise { + const input = texts.map((text) => text.trim()).filter(Boolean); + if (input.length === 0) { + return []; + } + if (!this.apiKey) { + throw new Error(`${this.constructor.name} requires an embedding API key`); + } + + const response = await fetch(`${this.baseUrl.replace(/\/+$/u, "")}/embeddings`, { + body: JSON.stringify({ + dimensions: this.dimensions, + input, + model: this.model, + }), + headers: { + Authorization: `Bearer ${this.apiKey}`, + "Content-Type": "application/json", + }, + method: "POST", + signal: AbortSignal.timeout(getEmbeddingRequestTimeoutMs()), + }); + + if (!response.ok) { + const body = (await response.text()).slice(0, 500); + throw new Error(`Embedding request failed (${response.status}): ${body}`); + } + + const payload = (await response.json()) as EmbeddingResponse; + const rows = payload.data ?? []; + return rows + .sort((left, right) => (left.index ?? 0) - (right.index ?? 0)) + .map((row) => row.embedding ?? []); + } +} + +export class OpenRouterEmbeddingClient extends HttpEmbeddingClient { + constructor() { + super( + getEmbeddingModel("openrouter"), + getEmbeddingDimensions(), + getRawSecret("EMBEDDING_API_KEY") ?? getRawSecret("OPENROUTER_API_KEY"), + getEmbeddingApiUrl("openrouter"), + ); + } +} + +export class OpenAIEmbeddingClient extends HttpEmbeddingClient { + constructor() { + super( + getEmbeddingModel("openai").replace(/^openai\//u, ""), + getEmbeddingDimensions(), + getRawSecret("EMBEDDING_API_KEY") ?? getRawSecret("OPENAI_API_KEY"), + getEmbeddingApiUrl("openai"), + ); + } +} + +class FallbackEmbeddingClient implements EmbeddingClient { + readonly model: string; + readonly dimensions: number; + private readonly logger = getLogger(); + + constructor( + private readonly primary: EmbeddingClient, + private readonly fallback: EmbeddingClient, + ) { + this.model = primary.model; + this.dimensions = primary.dimensions; + } + + embed(text: string): Promise { + return this.embedBatch([text]).then((embeddings) => { + const [embedding] = embeddings; + if (!embedding) { + throw new Error("Embedding response did not include an embedding"); + } + return embedding; + }); + } + + async embedBatch(texts: string[]): Promise { + try { + return await this.primary.embedBatch(texts); + } catch (error) { + this.logger.warn( + { err: error, provider: "openrouter" }, + "[Memory] Primary embedding provider failed; falling back", + ); + return this.fallback.embedBatch(texts); + } + } +} + +export function createEmbeddingClient(): EmbeddingClient { + const provider = getEmbeddingProvider(); + if (provider === "openai") { + return new OpenAIEmbeddingClient(); + } + + return new FallbackEmbeddingClient( + new OpenRouterEmbeddingClient(), + new OpenAIEmbeddingClient(), + ); +} diff --git a/src/memory/garnet-session-memory.test.ts b/src/memory/garnet-session-memory.test.ts new file mode 100644 index 0000000..ef5c3e4 --- /dev/null +++ b/src/memory/garnet-session-memory.test.ts @@ -0,0 +1,52 @@ +import { describe, expect, it } from "vitest"; + +import { GarnetSessionMemory, getSessionBlackboardKey } from "./garnet-session-memory.js"; + +class MemoryGarnet { + readonly records = new Map(); + + getJson(key: string): Promise { + return Promise.resolve((this.records.get(key) as T | undefined) ?? null); + } + + setJson(key: string, value: unknown): Promise { + this.records.set(key, value); + return Promise.resolve(); + } + + getString(): Promise { + return Promise.resolve(null); + } + + setString(): Promise { + return Promise.resolve(); + } +} + +describe("GarnetSessionMemory", () => { + it("keeps onboarding blackboard namespace backward compatible", async () => { + const garnet = new MemoryGarnet(); + const memory = new GarnetSessionMemory(garnet as never); + + await memory.setBlackboard("onboarding", "room-1", "user-1", { ok: true }); + + expect(getSessionBlackboardKey("onboarding", "room-1", "user-1")).toBe( + "lolympus-agent:bb:room-1:user-1", + ); + expect(garnet.records.get("lolympus-agent:bb:room-1:user-1")).toEqual({ + ok: true, + }); + }); + + it("separates non-onboarding blackboards by skill", async () => { + const garnet = new MemoryGarnet(); + const memory = new GarnetSessionMemory(garnet as never); + + await memory.setBlackboard("moderation", "room-1", "user-1", { ok: true }); + + expect(getSessionBlackboardKey("moderation", "room-1", "user-1")).toBe( + "lolympus-agent:bb:moderation:room-1:user-1", + ); + expect(garnet.records.has("lolympus-agent:bb:room-1:user-1")).toBe(false); + }); +}); diff --git a/src/memory/garnet-session-memory.ts b/src/memory/garnet-session-memory.ts new file mode 100644 index 0000000..d1a8a22 --- /dev/null +++ b/src/memory/garnet-session-memory.ts @@ -0,0 +1,75 @@ +import type { ConversationMessage } from "@agent/types"; +import type { GarnetClient } from "@common/garnet"; +import { ConversationStore } from "@conv/conversation-store"; +import { getBlackboardTtlSeconds } from "../config.js"; +import type { SessionMemory } from "./memory-types.js"; + +export function getSessionBlackboardKey( + skill: string, + chatroomId: string, + userId: string, +): string { + const normalizedSkill = skill.trim() || "unknown"; + if (normalizedSkill === "onboarding") { + return `lolympus-agent:bb:${chatroomId}:${userId}`; + } + return `lolympus-agent:bb:${normalizedSkill}:${chatroomId}:${userId}`; +} + +export class GarnetSessionMemory implements SessionMemory { + private readonly conversationStore: ConversationStore; + + constructor(private readonly garnetClient: GarnetClient) { + this.conversationStore = new ConversationStore(garnetClient); + } + + getBlackboard( + skill: string, + chatroomId: string, + userId: string, + ): Promise { + return this.garnetClient.getJson( + getSessionBlackboardKey(skill, chatroomId, userId), + ); + } + + setBlackboard( + skill: string, + chatroomId: string, + userId: string, + value: T, + ): Promise { + return this.garnetClient.setJson( + getSessionBlackboardKey(skill, chatroomId, userId), + value, + getBlackboardTtlSeconds(), + ); + } + + getConversationHistory( + chatroomId: string, + userId: string, + ): Promise { + return this.conversationStore.getHistory(chatroomId, userId); + } + + appendMessage( + chatroomId: string, + userId: string, + message: ConversationMessage, + ): Promise { + return this.conversationStore.appendMessage(chatroomId, userId, message); + } + + getSummary(chatroomId: string, userId: string): Promise { + return this.conversationStore.getSummary(chatroomId, userId); + } + + setSummary( + chatroomId: string, + userId: string, + summary: string, + ): Promise { + return this.conversationStore.setSummary(chatroomId, userId, summary); + } +} diff --git a/src/memory/knowledge-ingest.ts b/src/memory/knowledge-ingest.ts new file mode 100644 index 0000000..c3646e1 --- /dev/null +++ b/src/memory/knowledge-ingest.ts @@ -0,0 +1,167 @@ +import { createHash } from "node:crypto"; +import { readdir, readFile } from "node:fs/promises"; +import { basename, join, relative } from "node:path"; +import type { MemoryService } from "./memory-types.js"; + +export interface IngestOptions { + skill?: string | undefined; + category: string; + baseDir: string; + dryRun?: boolean | undefined; +} + +export interface IngestResult { + inserted: number; + updated: number; + skipped: number; +} + +interface Chunk { + id: string; + sectionTitle: string; + sourceFile: string; + text: string; +} + +interface LongTermWithLookup { + hasDocument(id: string): Promise; +} + +function hasDocumentLookup(value: unknown): value is LongTermWithLookup { + return ( + typeof value === "object" && + value !== null && + "hasDocument" in value && + typeof (value as { hasDocument?: unknown }).hasDocument === "function" + ); +} + +function normalizeTitle(value: string, fallback: string): string { + const trimmed = value + .replace(/^#+\s*/u, "") + .replace(/^\[/u, "") + .replace(/\]$/u, "") + .trim(); + return trimmed || fallback; +} + +function stableChunkId(input: { + category: string; + sectionTitle: string; + skill?: string | undefined; + sourceFile: string; +}): string { + const hash = createHash("sha256") + .update(JSON.stringify(input)) + .digest("hex") + .slice(0, 24); + return `knowledge_${hash}`; +} + +function splitMarkdown(filePath: string, content: string, options: IngestOptions): Chunk[] { + const sourceFile = relative(process.cwd(), filePath); + const headingPattern = /^##\s+(.+)$/gmu; + const headings = [...content.matchAll(headingPattern)]; + + if (headings.length === 0) { + const firstLine = content.split(/\r?\n/u)[0] ?? basename(filePath); + const sectionTitle = normalizeTitle(firstLine, basename(filePath, ".md")); + return [ + { + id: stableChunkId({ + category: options.category, + sectionTitle, + skill: options.skill, + sourceFile, + }), + sectionTitle, + sourceFile, + text: content.trim(), + }, + ].filter((chunk) => chunk.text.length > 0); + } + + return headings.flatMap((heading, index) => { + const start = heading.index + heading[0].length; + const nextHeading = headings[index + 1]; + const end = nextHeading ? nextHeading.index : content.length; + const sectionTitle = normalizeTitle(heading[1] ?? "", basename(filePath, ".md")); + const body = content.slice(start, end).trim(); + if (!body) { + return []; + } + + return [ + { + id: stableChunkId({ + category: options.category, + sectionTitle, + skill: options.skill, + sourceFile, + }), + sectionTitle, + sourceFile, + text: `## ${sectionTitle}\n${body}`, + }, + ]; + }); +} + +export async function ingestMarkdownResources( + memoryService: MemoryService, + options: IngestOptions, +): Promise { + const files = (await readdir(options.baseDir)) + .filter((file) => file.endsWith(".md")) + .sort(); + const result: IngestResult = { + inserted: 0, + skipped: 0, + updated: 0, + }; + + for (const file of files) { + const filePath = join(options.baseDir, file); + const content = await readFile(filePath, "utf8"); + const chunks = splitMarkdown(filePath, content, options); + + for (const chunk of chunks) { + if (!chunk.text.trim()) { + result.skipped += 1; + continue; + } + + const existed = hasDocumentLookup(memoryService.longTerm) + ? await memoryService.longTerm.hasDocument(chunk.id) + : false; + + if (options.dryRun) { + if (existed) { + result.updated += 1; + } else { + result.inserted += 1; + } + continue; + } + + await memoryService.longTerm.upsertDocument({ + id: chunk.id, + category: options.category, + metadata: { + sectionTitle: chunk.sectionTitle, + sourceFile: chunk.sourceFile, + }, + skill: options.skill, + text: chunk.text, + }); + + if (existed) { + result.updated += 1; + } else { + result.inserted += 1; + } + } + } + + return result; +} diff --git a/src/memory/memory-service.test.ts b/src/memory/memory-service.test.ts new file mode 100644 index 0000000..3b58134 --- /dev/null +++ b/src/memory/memory-service.test.ts @@ -0,0 +1,50 @@ +import { describe, expect, it } from "vitest"; + +import { DefaultMemoryService } from "./memory-service.js"; +import type { LongTermMemory, SessionMemory } from "./memory-types.js"; + +const session: SessionMemory = { + appendMessage: () => Promise.resolve(), + getBlackboard: () => + Promise.resolve({ flaggedIssues: ["x"] } as T), + getConversationHistory: () => + Promise.resolve([{ role: "user", content: "hi", timestamp: "t" }]), + getSummary: () => Promise.resolve("summary"), + setBlackboard: () => Promise.resolve(), + setSummary: () => Promise.resolve(), +}; + +const longTerm: LongTermMemory = { + deleteDocument: () => Promise.resolve(), + loadUserProfile: () => Promise.resolve(null), + search: () => + Promise.resolve([ + { + category: "rule", + id: "doc-1", + score: 0.9, + text: "rule text", + }, + ]), + updateUserProfile: () => Promise.resolve(), + upsertDocument: () => Promise.resolve("doc-1"), +}; + +describe("DefaultMemoryService", () => { + it("assembles working memory from session and long-term layers", async () => { + const memory = new DefaultMemoryService(session, longTerm); + + const working = await memory.assembleWorkingMemory({ + skill: "onboarding", + chatroomId: "room-1", + userId: "user-1", + includeBlackboard: true, + retrieval: { query: "rule" }, + }); + + expect(working.summary).toBe("summary"); + expect(working.blackboard?.flaggedIssues).toEqual(["x"]); + expect(working.conversationHistory).toHaveLength(1); + expect(working.retrievedKnowledge?.[0]?.text).toBe("rule text"); + }); +}); diff --git a/src/memory/memory-service.ts b/src/memory/memory-service.ts new file mode 100644 index 0000000..14c183f --- /dev/null +++ b/src/memory/memory-service.ts @@ -0,0 +1,95 @@ +import type mongoose from "mongoose"; +import type { GarnetClient } from "@common/garnet"; +import type { Blackboard } from "@skills/onboarding/types"; +import { createEmbeddingClient } from "./embedding-client.js"; +import { GarnetSessionMemory } from "./garnet-session-memory.js"; +import { + MongoLongTermMemory, + NoopLongTermMemory, +} from "./mongo-long-term-memory.js"; +import type { + LongTermMemory, + MemoryService, + SearchOptions, + SessionMemory, + WorkingMemory, +} from "./memory-types.js"; + +interface CreateMemoryServiceOptions { + garnetClient: GarnetClient; + mongooseConnection?: mongoose.Connection | undefined; +} + +function defaultBlackboard(): Blackboard { + return { + flaggedIssues: [], + openQuestions: [], + recentNicknameAttempts: [], + toneMemory: {}, + }; +} + +export class DefaultMemoryService implements MemoryService { + constructor( + readonly session: SessionMemory, + readonly longTerm: LongTermMemory, + ) {} + + async assembleWorkingMemory(input: { + skill: string; + chatroomId: string; + userId: string; + includeBlackboard?: boolean; + includeProfile?: boolean; + retrieval?: { query: string; options?: SearchOptions | undefined } | undefined; + }): Promise { + const [ + conversationHistory, + summary, + blackboard, + userProfile, + retrievedKnowledge, + ] = await Promise.all([ + this.session.getConversationHistory(input.chatroomId, input.userId), + this.session.getSummary(input.chatroomId, input.userId), + input.includeBlackboard + ? this.session.getBlackboard( + input.skill, + input.chatroomId, + input.userId, + ) + : Promise.resolve(null), + input.includeProfile + ? this.longTerm.loadUserProfile(input.userId) + : Promise.resolve(null), + input.retrieval + ? this.longTerm.search(input.retrieval.query, input.retrieval.options ?? {}) + : Promise.resolve(undefined), + ]); + + return { + conversationHistory, + ...(summary ? { summary } : {}), + ...(input.includeBlackboard + ? { blackboard: blackboard ?? defaultBlackboard() } + : {}), + ...(userProfile ? { userProfile } : {}), + ...(retrievedKnowledge ? { retrievedKnowledge } : {}), + }; + } +} + +export function createMemoryService( + options: CreateMemoryServiceOptions, +): MemoryService { + const session = new GarnetSessionMemory(options.garnetClient); + const longTerm = options.mongooseConnection + ? new MongoLongTermMemory( + options.garnetClient, + options.mongooseConnection, + createEmbeddingClient(), + ) + : new NoopLongTermMemory(options.garnetClient); + + return new DefaultMemoryService(session, longTerm); +} diff --git a/src/memory/memory-types.ts b/src/memory/memory-types.ts new file mode 100644 index 0000000..54c5095 --- /dev/null +++ b/src/memory/memory-types.ts @@ -0,0 +1,71 @@ +import type { ConversationMessage } from "@agent/types"; +import type { Blackboard } from "@skills/onboarding/types"; +import type { UserProfile } from "@skills/onboarding/state/user-memory"; + +export interface RetrievedDocument { + id: string; + text: string; + category: string; + skill?: string | undefined; + score: number; + metadata?: Record | undefined; +} + +export interface KnowledgeDocument { + id?: string | undefined; + skill?: string | undefined; + category: string; + text: string; + embedding?: number[] | undefined; + metadata?: Record | undefined; + embeddingModel?: string | undefined; +} + +export interface WorkingMemory { + conversationHistory: ConversationMessage[]; + summary?: string | undefined; + blackboard?: Blackboard | undefined; + userProfile?: UserProfile | undefined; + retrievedKnowledge?: RetrievedDocument[] | undefined; +} + +export interface SessionMemory { + getBlackboard(skill: string, chatroomId: string, userId: string): Promise; + setBlackboard( + skill: string, + chatroomId: string, + userId: string, + value: T, + ): Promise; + getConversationHistory(chatroomId: string, userId: string): Promise; + appendMessage(chatroomId: string, userId: string, message: ConversationMessage): Promise; + getSummary(chatroomId: string, userId: string): Promise; + setSummary(chatroomId: string, userId: string, summary: string): Promise; +} + +export interface SearchOptions { + skill?: string | undefined; + category?: string | undefined; + topK?: number | undefined; +} + +export interface LongTermMemory { + loadUserProfile(userId: string): Promise; + updateUserProfile(userId: string, patch: Partial): Promise; + search(query: string, options: SearchOptions): Promise; + upsertDocument(doc: KnowledgeDocument): Promise; + deleteDocument(id: string): Promise; +} + +export interface MemoryService { + session: SessionMemory; + longTerm: LongTermMemory; + assembleWorkingMemory(input: { + skill: string; + chatroomId: string; + userId: string; + includeBlackboard?: boolean; + includeProfile?: boolean; + retrieval?: { query: string; options?: SearchOptions | undefined } | undefined; + }): Promise; +} diff --git a/src/memory/mongo-long-term-memory.ts b/src/memory/mongo-long-term-memory.ts new file mode 100644 index 0000000..77b8d00 --- /dev/null +++ b/src/memory/mongo-long-term-memory.ts @@ -0,0 +1,266 @@ +import { createHash } from "node:crypto"; +import type mongoose from "mongoose"; +import { Schema } from "mongoose"; +import { anonymizeIdentifier } from "@eval/anonymize"; +import { withSpan } from "@obs/spans"; +import { getAgentUserMemoryTtlDays, getKnowledgeSearchCandidateLimit } from "../config.js"; +import type { UserProfile } from "@skills/onboarding/state/user-memory"; +import { USER_MEMORY_KEY_PREFIX } from "@skills/onboarding/state/user-memory"; +import type { GarnetClient } from "@common/garnet"; +import { rankByCosineSimilarity } from "./cosine.js"; +import type { + KnowledgeDocument, + LongTermMemory, + RetrievedDocument, + SearchOptions, +} from "./memory-types.js"; +import type { EmbeddingClient } from "./embedding-client.js"; + +export const KNOWLEDGE_COLLECTION = "knowledge_documents"; + +interface KnowledgeDocumentRecord { + _id: string; + skill?: string | undefined; + category: string; + text: string; + embedding: number[]; + embeddingModel: string; + metadata?: Record | undefined; + createdAt: Date; + updatedAt: Date; +} + +const KnowledgeSchema = new Schema( + { + _id: { type: String, required: true }, + skill: { type: String, index: true }, + category: { type: String, required: true, index: true }, + text: { type: String, required: true }, + embedding: { type: [Number], required: true }, + embeddingModel: { type: String, required: true }, + metadata: { type: Schema.Types.Mixed }, + createdAt: { type: Date, default: Date.now }, + updatedAt: { type: Date, default: Date.now, index: true }, + }, + { versionKey: false }, +); + +function userProfileKey(userId: string): string { + return `${USER_MEMORY_KEY_PREFIX}:${anonymizeIdentifier("user", userId) ?? "unknown"}`; +} + +function userProfileTtlSeconds(): number { + return getAgentUserMemoryTtlDays() * 24 * 60 * 60; +} + +function nowIso(): string { + return new Date().toISOString(); +} + +function emptyProfile(userId: string, now = nowIso()): UserProfile { + return { + firstSeenAt: now, + flaggedIssues: [], + lastSeenAt: now, + pastIntents: [], + preferredStyle: "neutral", + totalTurns: 0, + userId: anonymizeIdentifier("user", userId) ?? "user_unknown", + }; +} + +function stableDocumentId(doc: KnowledgeDocument): string { + const hash = createHash("sha256") + .update(JSON.stringify({ + category: doc.category, + metadata: doc.metadata ?? {}, + skill: doc.skill ?? "", + text: doc.text, + })) + .digest("hex") + .slice(0, 24); + return `knowledge_${hash}`; +} + +function buildFilter(options: SearchOptions): Record { + const filter: Record = {}; + if (options.skill?.trim()) { + filter["skill"] = options.skill.trim(); + } + if (options.category?.trim()) { + filter["category"] = options.category.trim(); + } + return filter; +} + +export class MongoLongTermMemory implements LongTermMemory { + private readonly model: mongoose.Model; + + constructor( + private readonly garnetClient: Pick, + connection: mongoose.Connection, + private readonly embeddingClient: EmbeddingClient, + ) { + this.model = + (connection.models["KnowledgeDocument"] as mongoose.Model | undefined) ?? + connection.model( + "KnowledgeDocument", + KnowledgeSchema, + KNOWLEDGE_COLLECTION, + ); + } + + loadUserProfile(userId: string): Promise { + return this.garnetClient.getJson(userProfileKey(userId)); + } + + async updateUserProfile( + userId: string, + patch: Partial, + ): Promise { + const current = (await this.loadUserProfile(userId)) ?? emptyProfile(userId); + const next: UserProfile = { + ...current, + ...patch, + firstSeenAt: patch.firstSeenAt ?? current.firstSeenAt, + flaggedIssues: patch.flaggedIssues ?? current.flaggedIssues, + lastSeenAt: patch.lastSeenAt ?? nowIso(), + pastIntents: patch.pastIntents ?? current.pastIntents, + preferredStyle: patch.preferredStyle ?? current.preferredStyle, + totalTurns: patch.totalTurns ?? current.totalTurns, + userId: current.userId, + }; + await this.garnetClient.setJson( + userProfileKey(userId), + next, + userProfileTtlSeconds(), + ); + } + + async search( + query: string, + options: SearchOptions = {}, + ): Promise { + const trimmed = query.trim(); + if (!trimmed) { + return []; + } + + return withSpan( + "memory.retrieval", + { + "memory.retrieval.category": options.category, + "memory.retrieval.skill": options.skill, + "memory.retrieval.top_k": options.topK ?? 5, + }, + async (span) => { + const startedAt = Date.now(); + const queryEmbedding = await this.embeddingClient.embed(trimmed); + const docs = (await this.model + .find(buildFilter(options)) + .sort({ updatedAt: -1 }) + .limit(getKnowledgeSearchCandidateLimit()) + .lean() + .exec()) as KnowledgeDocumentRecord[]; + const ranked = rankByCosineSimilarity( + queryEmbedding, + docs.filter((doc) => + Array.isArray(doc.embedding) && + doc.embedding.length === queryEmbedding.length + ), + options.topK ?? 5, + ); + + span.setAttributes({ + "memory.retrieval.candidate_count": docs.length, + "memory.retrieval.duration_ms": Math.max(0, Date.now() - startedAt), + "memory.retrieval.top_score": ranked[0]?.score, + }); + + return ranked.map((doc) => ({ + id: doc._id, + category: doc.category, + metadata: doc.metadata, + score: doc.score, + skill: doc.skill, + text: doc.text, + })); + }, + ); + } + + async upsertDocument(doc: KnowledgeDocument): Promise { + const id = doc.id?.trim() || stableDocumentId(doc); + const embedding = doc.embedding ?? await this.embeddingClient.embed(doc.text); + if (embedding.length !== this.embeddingClient.dimensions) { + throw new Error( + `Embedding dimension mismatch: expected ${this.embeddingClient.dimensions}, got ${embedding.length}`, + ); + } + + const updatedAt = new Date(); + await this.model.updateOne( + { _id: id }, + { + $set: { + category: doc.category, + embedding, + embeddingModel: doc.embeddingModel ?? this.embeddingClient.model, + metadata: doc.metadata, + skill: doc.skill, + text: doc.text, + updatedAt, + }, + $setOnInsert: { + createdAt: updatedAt, + }, + }, + { upsert: true }, + ).exec(); + return id; + } + + async hasDocument(id: string): Promise { + return Boolean(await this.model.exists({ _id: id }).exec()); + } + + async deleteDocument(id: string): Promise { + await this.model.deleteOne({ _id: id }).exec(); + } +} + +export class NoopLongTermMemory implements LongTermMemory { + constructor(private readonly garnetClient: Pick) {} + + loadUserProfile(userId: string): Promise { + return this.garnetClient.getJson(userProfileKey(userId)); + } + + async updateUserProfile( + userId: string, + patch: Partial, + ): Promise { + const current = (await this.loadUserProfile(userId)) ?? emptyProfile(userId); + await this.garnetClient.setJson( + userProfileKey(userId), + { ...current, ...patch, userId: current.userId }, + userProfileTtlSeconds(), + ); + } + + search(): Promise { + return Promise.resolve([]); + } + + upsertDocument(doc: KnowledgeDocument): Promise { + return Promise.reject( + new Error( + `Knowledge memory is unavailable; cannot upsert ${doc.id ?? doc.category}`, + ), + ); + } + + deleteDocument(): Promise { + return Promise.resolve(); + } +} diff --git a/src/skills/moderation/index.ts b/src/skills/moderation/index.ts index 8846028..034938e 100644 --- a/src/skills/moderation/index.ts +++ b/src/skills/moderation/index.ts @@ -5,5 +5,5 @@ import { ModerationSkill } from "./skill.js"; export { ModerationSkill } from "./skill.js"; export function createModerationSkill(deps: SkillDeps): Skill { - return new ModerationSkill(deps.llmClient); + return new ModerationSkill(deps.llmClient, deps.memoryService); } diff --git a/src/skills/moderation/skill.ts b/src/skills/moderation/skill.ts index 084ca5e..dae90af 100644 --- a/src/skills/moderation/skill.ts +++ b/src/skills/moderation/skill.ts @@ -5,9 +5,12 @@ import type { } from "@agent/types"; import type { LlmClient } from "@llm/llm-client"; import type { ChatMessage } from "@llm/types"; +import type { MemoryService, RetrievedDocument } from "../../memory/memory-types.js"; +import { getRequestLogger } from "@obs/context"; import type { Skill } from "@skills/skill"; import type { SkillCapabilityCard } from "@skills/skill-loader"; import { lookupRuleTool } from "@tools/moderation/lookup-rule"; +import { getRagEnabled } from "../../config.js"; import { classifyModerationIntent, type ModerationIntent } from "./intents.js"; import { MODERATION_PROMPT_DATA } from "./prompt-data.js"; import { createModerationToolRegistry } from "./tools.js"; @@ -137,18 +140,50 @@ function resolveRuleTopic(message: string): RuleTopic | null { async function lookupReferenceText( intent: ModerationIntent, message: string, + memoryService?: MemoryService, ): Promise { if (intent.kind !== "rule-question") { return undefined; } + + if (memoryService && getRagEnabled()) { + try { + const docs = await memoryService.longTerm.search(message, { + category: "rule", + skill: "moderation", + topK: 3, + }); + if (docs.length > 0) { + return formatRetrievedReference(docs); + } + } catch (error) { + getRequestLogger().warn( + { err: error }, + "[ModerationSkill] Knowledge retrieval failed; using local rules", + ); + } + } + const topic = resolveRuleTopic(message); if (!topic) { return undefined; } - const result = await lookupRuleTool.execute({ topic }, {}); + const result = await lookupRuleTool.execute( + { topic }, + { memoryService }, + ); return result.text; } +function formatRetrievedReference(docs: RetrievedDocument[]): string { + return docs + .map((doc, index) => { + const score = Number.isFinite(doc.score) ? doc.score.toFixed(3) : "0.000"; + return [`#${index + 1} score=${score}`, doc.text.trim()].join("\n"); + }) + .join("\n\n"); +} + function templateForIntent(intent: ModerationIntent): string { switch (intent.kind) { case "appeal": @@ -169,7 +204,10 @@ export class ModerationSkill implements Skill { readonly priority = 50; private readonly toolRegistry = createModerationToolRegistry(); - constructor(private readonly llmClient: LlmClient) {} + constructor( + private readonly llmClient: LlmClient, + private readonly memoryService?: MemoryService | undefined, + ) {} canHandle(request: AgentRequest): boolean { return request.skill === this.name; @@ -187,6 +225,7 @@ export class ModerationSkill implements Skill { const referenceText = await lookupReferenceText( classified.intent, request.userMessage ?? "", + this.memoryService, ); const metadata = { intent: classified.intent.kind, diff --git a/src/skills/onboarding/index.ts b/src/skills/onboarding/index.ts index b97f3a1..914e3e9 100644 --- a/src/skills/onboarding/index.ts +++ b/src/skills/onboarding/index.ts @@ -15,5 +15,6 @@ export function createOnboardingSkill(deps: SkillDeps): Skill { deps.roomContextService, deps.shadowEvalBus, deps.natsClient, + deps.memoryService, ); } diff --git a/src/skills/onboarding/prompts/layers.ts b/src/skills/onboarding/prompts/layers.ts index d17c370..c53f7a2 100644 --- a/src/skills/onboarding/prompts/layers.ts +++ b/src/skills/onboarding/prompts/layers.ts @@ -123,6 +123,27 @@ function formatUserProfile(profile: UserProfile | null | undefined): string { ].join('\n'); } +function formatRetrievedKnowledge(context: PromptContext): string[] { + const docs = context.retrievedKnowledge ?? []; + if (docs.length === 0) { + return []; + } + + return [ + '', + '[reference]', + docs + .map((doc, index) => { + const score = Number.isFinite(doc.score) ? doc.score.toFixed(3) : '0.000'; + return [ + `#${index + 1} (${doc.category}, score=${score})`, + doc.text.trim(), + ].join('\n'); + }) + .join('\n\n'), + ]; +} + export function personaLayer(): string { return ONBOARDING_PROMPT_DATA.persona; } @@ -201,5 +222,6 @@ export function contextLayer(context: PromptContext): string { formatUserProfile(context.userProfile), ] : []), + ...formatRetrievedKnowledge(context), ].join('\n'); } diff --git a/src/skills/onboarding/runtime/message-builder.ts b/src/skills/onboarding/runtime/message-builder.ts index 065e3b8..7f3bb40 100644 --- a/src/skills/onboarding/runtime/message-builder.ts +++ b/src/skills/onboarding/runtime/message-builder.ts @@ -2,12 +2,14 @@ import type { AgentRequest, ConversationMessage } from '@agent/types'; import type { GarnetClient } from '@common/garnet'; import { getConversationSummaryKey } from '@conv/conversation-store'; import type { ChatMessage } from '@llm/types'; +import type { MemoryService } from '../../../memory/memory-types.js'; import { getRequestLogger } from '@obs/context'; import type { RoomContextService } from '@room/room-context-service'; import { meetsTrustTier } from '../../../eval/governance/trust.js'; import { getAgentTrustMinTier, getAgentUserMemoryEnabled, + getRagEnabled, getPromptVariantId, } from '../../../config.js'; import { @@ -22,6 +24,7 @@ import type { OnboardingSession, PromptContext } from '../types.js'; interface MessageBuilderDeps { blackboardStore: OnboardingBlackboardStore; garnetClient: GarnetClient; + memoryService?: MemoryService | undefined; roomContextService?: RoomContextService | undefined; userMemoryStore: UserMemoryStore; } @@ -67,6 +70,32 @@ async function loadConversationSummary( return (await garnetClient.getString(key)) ?? undefined; } +function shouldRetrieve(derived: DerivedState): boolean { + return ( + getRagEnabled() && + ( + derived.intent.kind === 'help-how' || + derived.intent.kind === 'help-where' || + derived.intent.kind === 'nickname-question' || + derived.intent.kind === 'discord-question' || + derived.intent.kind === 'age-question' + ) + ); +} + +function buildRetrievalQuery( + request: AgentRequest, + derived: DerivedState, +): string { + return [ + request.userMessage?.trim(), + derived.intent.kind, + derived.phase.kind, + ] + .filter(Boolean) + .join('\n'); +} + export async function buildLlmMessages( deps: MessageBuilderDeps, input: MessageBuilderInput, @@ -85,7 +114,34 @@ export async function buildLlmMessages( return undefined; }) : Promise.resolve(undefined); - const userProfilePromise = getAgentUserMemoryEnabled() + const workingMemoryPromise = deps.memoryService + ? deps.memoryService + .assembleWorkingMemory({ + skill: 'onboarding', + chatroomId: request.chatroomId, + userId: request.userId, + includeBlackboard: true, + includeProfile: getAgentUserMemoryEnabled(), + retrieval: shouldRetrieve(derived) + ? { + query: buildRetrievalQuery(request, derived), + options: { + category: 'onboarding-step', + skill: 'onboarding', + topK: 2, + }, + } + : undefined, + }) + .catch((error) => { + logger.warn( + { err: error }, + '[OnboardingSkill] Failed to assemble working memory', + ); + return null; + }) + : Promise.resolve(null); + const legacyUserProfilePromise = getAgentUserMemoryEnabled() ? deps.userMemoryStore.load(request.userId).catch((error) => { logger.warn( { err: error }, @@ -94,20 +150,40 @@ export async function buildLlmMessages( return null; }) : Promise.resolve(null); - const [blackboard, summary, roomContext, userProfile] = await Promise.all([ - deps.blackboardStore.load(request.chatroomId, request.userId), - loadConversationSummary(deps.garnetClient, request.chatroomId, request.userId), + const [ + workingMemory, + legacyBlackboard, + legacySummary, + roomContext, + legacyUserProfile, + ] = await Promise.all([ + workingMemoryPromise, + deps.memoryService + ? Promise.resolve(undefined) + : deps.blackboardStore.load(request.chatroomId, request.userId), + deps.memoryService + ? Promise.resolve(undefined) + : loadConversationSummary(deps.garnetClient, request.chatroomId, request.userId), roomContextPromise, - userProfilePromise, + deps.memoryService ? Promise.resolve(null) : legacyUserProfilePromise, ]); + const blackboard = workingMemory?.blackboard ?? legacyBlackboard; + if (!blackboard) { + throw new Error('Failed to load onboarding blackboard'); + } + const context: PromptContext = { blackboard, - conversationHistory, + conversationHistory: + workingMemory && workingMemory.conversationHistory.length > 0 + ? workingMemory.conversationHistory + : conversationHistory, roomContext, - summary, + retrievedKnowledge: workingMemory?.retrievedKnowledge, + summary: workingMemory?.summary ?? legacySummary, userMessage: buildPromptUserMessage(request, derived), - userProfile, + userProfile: workingMemory?.userProfile ?? legacyUserProfile, }; const builder = PromptBuilder.forDerived(derived, session, context); diff --git a/src/skills/onboarding/skill.ts b/src/skills/onboarding/skill.ts index f56390c..f7de0b6 100644 --- a/src/skills/onboarding/skill.ts +++ b/src/skills/onboarding/skill.ts @@ -1,6 +1,7 @@ import type { AgentRequest, AgentResponse, ConversationMessage } from '@agent/types'; import type { GarnetClient } from '@common/garnet'; import type { NatsClient } from '@common/nats'; +import type { MemoryService } from '../../memory/memory-types.js'; import { getContext, getRequestLogger } from '@obs/context'; import type { LlmClient } from '@llm/llm-client'; import type { RoomContextService } from '@room/room-context-service'; @@ -112,10 +113,17 @@ export class OnboardingSkill implements Skill { private readonly roomContextService?: RoomContextService, shadowEvalPublisher?: ShadowEvalPublisher, private readonly natsClient?: Pick, + private readonly memoryService?: MemoryService, ) { this.classifier = new OnboardingIntentClassifier(llmClient); - this.blackboardStore = new OnboardingBlackboardStore(garnetClient); - this.userMemoryStore = new UserMemoryStore(garnetClient); + this.blackboardStore = new OnboardingBlackboardStore( + garnetClient, + memoryService?.session, + ); + this.userMemoryStore = new UserMemoryStore( + garnetClient, + memoryService?.longTerm, + ); this.orchestrator = new OnboardingOrchestrator(llmClient); this.shadowEvalPublisher = shadowEvalPublisher ?? new ShadowEvalBus(garnetClient); this.toolRegistry = createOnboardingToolRegistry(); @@ -381,6 +389,7 @@ export class OnboardingSkill implements Skill { { blackboardStore: this.blackboardStore, garnetClient: this.garnetClient, + memoryService: this.memoryService, roomContextService: this.roomContextService, userMemoryStore: this.userMemoryStore, }, @@ -474,6 +483,7 @@ export class OnboardingSkill implements Skill { userId: request.userId, session, garnetClient: this.garnetClient, + memoryService: this.memoryService, roomContextService: this.roomContextService, toolRegistry: this.toolRegistry, }; diff --git a/src/skills/onboarding/state/blackboard.ts b/src/skills/onboarding/state/blackboard.ts index 794fc51..e27a314 100644 --- a/src/skills/onboarding/state/blackboard.ts +++ b/src/skills/onboarding/state/blackboard.ts @@ -1,4 +1,5 @@ import type { GarnetClient } from "@common/garnet"; +import type { SessionMemory } from "../../../memory/memory-types.js"; import { getBlackboardTtlSeconds } from "../../../config.js"; import type { Blackboard } from "../types.js"; @@ -37,9 +38,21 @@ function mergeBlackboard( } export class OnboardingBlackboardStore { - constructor(private readonly garnetClient: GarnetClient) {} + constructor( + private readonly garnetClient: GarnetClient, + private readonly sessionMemory?: SessionMemory | undefined, + ) {} async load(chatroomId: string, userId: string): Promise { + if (this.sessionMemory) { + const saved = await this.sessionMemory.getBlackboard( + "onboarding", + chatroomId, + userId, + ); + return mergeBlackboard(saved, {}); + } + const key = getBlackboardKey(chatroomId, userId); const saved = await this.garnetClient.getJson(key); return mergeBlackboard(saved, {}); @@ -50,6 +63,16 @@ export class OnboardingBlackboardStore { userId: string, value: Blackboard, ): Promise { + if (this.sessionMemory) { + await this.sessionMemory.setBlackboard( + "onboarding", + chatroomId, + userId, + value, + ); + return; + } + const key = getBlackboardKey(chatroomId, userId); await this.garnetClient.setJson( key, diff --git a/src/skills/onboarding/state/user-memory.ts b/src/skills/onboarding/state/user-memory.ts index 03bcfba..8681d7b 100644 --- a/src/skills/onboarding/state/user-memory.ts +++ b/src/skills/onboarding/state/user-memory.ts @@ -4,6 +4,7 @@ import { anonymizeText, } from "@eval/anonymize"; import { getAgentUserMemoryTtlDays } from "../../../config.js"; +import type { LongTermMemory } from "../../../memory/memory-types.js"; import type { DerivedState, Intent } from "./onboarding-state.js"; export type PreferredStyle = "concise" | "neutral" | "warm"; @@ -86,9 +87,16 @@ function emptyProfile(userId: string, now = nowIso()): UserProfile { } export class UserMemoryStore { - constructor(private readonly garnetClient: UserMemoryGarnetClient) {} + constructor( + private readonly garnetClient: UserMemoryGarnetClient, + private readonly longTermMemory?: LongTermMemory | undefined, + ) {} async load(userId: string): Promise { + if (this.longTermMemory) { + return this.longTermMemory.loadUserProfile(userId); + } + return this.garnetClient.getJson(profileKey(userId)); } @@ -125,7 +133,11 @@ export class UserMemoryStore { userId: current.userId, }; - await this.garnetClient.setJson(profileKey(userId), next, ttlSeconds()); + if (this.longTermMemory) { + await this.longTermMemory.updateUserProfile(userId, next); + } else { + await this.garnetClient.setJson(profileKey(userId), next, ttlSeconds()); + } return next; } } diff --git a/src/skills/onboarding/types.ts b/src/skills/onboarding/types.ts index cfbf584..c5dc47c 100644 --- a/src/skills/onboarding/types.ts +++ b/src/skills/onboarding/types.ts @@ -1,4 +1,5 @@ import type { ConversationMessage } from "@agent/types"; +import type { RetrievedDocument } from "../../memory/memory-types.js"; import type { RoomMessage } from "@room/types"; import type { UserProfile } from "./state/user-memory.js"; @@ -27,6 +28,7 @@ export interface PromptContext { blackboard: Blackboard; conversationHistory: ConversationMessage[]; roomContext?: RoomMessage[] | undefined; + retrievedKnowledge?: RetrievedDocument[] | undefined; summary?: string | undefined; userMessage: string; userProfile?: UserProfile | null | undefined; diff --git a/src/skills/skill-factory.ts b/src/skills/skill-factory.ts index ddb21f1..b567ebc 100644 --- a/src/skills/skill-factory.ts +++ b/src/skills/skill-factory.ts @@ -2,6 +2,7 @@ import type { GarnetClient } from "@common/garnet"; import type { NatsClient } from "@common/nats"; import type { ShadowEvalBus } from "@eval/shadow-bus"; import type { LlmClient } from "@llm/llm-client"; +import type { MemoryService } from "../memory/memory-types.js"; import type { RoomContextService } from "@room/room-context-service"; import type { Skill } from "./skill.js"; import type { SkillRegistry } from "./skill-loader.js"; @@ -9,6 +10,7 @@ import type { SkillRegistry } from "./skill-loader.js"; export interface SkillDeps { garnetClient: GarnetClient; llmClient: LlmClient; + memoryService?: MemoryService | undefined; natsClient: NatsClient; roomContextService?: RoomContextService | undefined; shadowEvalBus: ShadowEvalBus; diff --git a/src/tools/moderation/lookup-rule.test.ts b/src/tools/moderation/lookup-rule.test.ts index 488b78c..ecbcb67 100644 --- a/src/tools/moderation/lookup-rule.test.ts +++ b/src/tools/moderation/lookup-rule.test.ts @@ -1,6 +1,13 @@ import { describe, expect, it } from "vitest"; +import type { MemoryService } from "../../memory/memory-types.js"; import { lookupRuleTool } from "./lookup-rule.js"; +const failingMemoryService = { + longTerm: { + search: () => Promise.reject(new Error("retrieval failed")), + }, +} as unknown as MemoryService; + describe("lookupRuleTool", () => { it("returns the matching community rule section", async () => { const result = await lookupRuleTool.execute({ topic: "ads" }, {}); @@ -10,9 +17,21 @@ describe("lookupRuleTool", () => { expect(result.text).toContain("홍보"); }); - it("validates topic enum values", () => { - expect(() => - lookupRuleTool.argsSchema.parse({ topic: "unknown" }), - ).toThrow(); + it("accepts natural-language topics and falls back to local rules", async () => { + const parsed = lookupRuleTool.argsSchema.parse({ topic: "광고 기준" }); + const result = await lookupRuleTool.execute(parsed, {}); + + expect(result.source).toBe("community-rules"); + expect(result.text).toContain("광고"); + }); + + it("falls back to local rules when knowledge retrieval fails", async () => { + const result = await lookupRuleTool.execute( + { topic: "광고 기준" }, + { memoryService: failingMemoryService }, + ); + + expect(result.source).toBe("community-rules"); + expect(result.text).toContain("광고"); }); }); diff --git a/src/tools/moderation/lookup-rule.ts b/src/tools/moderation/lookup-rule.ts index 3e7a92d..0c3a6c6 100644 --- a/src/tools/moderation/lookup-rule.ts +++ b/src/tools/moderation/lookup-rule.ts @@ -1,29 +1,40 @@ import { readFileSync } from "node:fs"; import { fileURLToPath } from "node:url"; import { z } from "zod"; +import { getRagEnabled } from "../../config.js"; +import { getRequestLogger } from "../../observability/context.js"; import type { Tool } from "../tool.js"; const argsSchema = z.object({ - topic: z.enum([ - "ads", - "appeal", - "minor-safety", - "off-topic", - "privacy", - "profanity", - "report", - "sanctions", - "spam", - ]), + topic: z.string().min(1).describe("검색할 규칙 주제"), + topK: z.number().int().min(1).max(10).optional(), }); const resultSchema = z.object({ topic: argsSchema.shape.topic, text: z.string(), - source: z.literal("community-rules"), + source: z.enum(["community-rules", "knowledge_documents"]), + matches: z + .array( + z.object({ + id: z.string(), + score: z.number(), + text: z.string(), + }), + ) + .optional(), }); -type RuleTopic = z.infer["topic"]; +type RuleTopic = + | "ads" + | "appeal" + | "minor-safety" + | "off-topic" + | "privacy" + | "profanity" + | "report" + | "sanctions" + | "spam"; const RULES_PATH = fileURLToPath( new URL("../../skills/moderation/resources/community-rules.md", import.meta.url), @@ -36,6 +47,41 @@ function extractRuleSection(topic: RuleTopic): string { return match?.[1]?.trim() || ""; } +function resolveLegacyTopic(topic: string): RuleTopic | null { + if ( + topic === "ads" || + topic === "appeal" || + topic === "minor-safety" || + topic === "off-topic" || + topic === "privacy" || + topic === "profanity" || + topic === "report" || + topic === "sanctions" || + topic === "spam" + ) { + return topic; + } + if (/(광고|홍보|링크)/u.test(topic)) return "ads"; + if (/(도배|반복|스팸)/u.test(topic)) return "spam"; + if (/(욕설|혐오|차별|비하)/u.test(topic)) return "profanity"; + if (/(신고|제보|위반)/u.test(topic)) return "report"; + if (/(경고|제재|강퇴|처벌)/u.test(topic)) return "sanctions"; + if (/(이의|소명|억울|정지|벤|밴|차단)/u.test(topic)) return "appeal"; + if (/(미성년|미자|성적|보호)/u.test(topic)) return "minor-safety"; + if (/(개인정보|전화번호|주소|실명|계정)/u.test(topic)) return "privacy"; + if (/(잡담|주제|오프토픽|off-topic)/iu.test(topic)) return "off-topic"; + return null; +} + +function legacyLookupRule(topic: string): z.infer { + const resolved = resolveLegacyTopic(topic); + return { + topic, + text: resolved ? extractRuleSection(resolved) : RULES_TEXT.trim(), + source: "community-rules", + }; +} + export const lookupRuleTool: Tool< z.infer, z.infer @@ -45,11 +91,34 @@ export const lookupRuleTool: Tool< "광고, 도배, 욕설, 신고, 제재, 이의 제기, 개인정보 같은 moderation 규칙을 조회한다.", argsSchema, resultSchema, - execute(args) { - return Promise.resolve({ - topic: args.topic, - text: extractRuleSection(args.topic), - source: "community-rules", - }); + async execute(args, ctx) { + if (ctx.memoryService && getRagEnabled()) { + try { + const docs = await ctx.memoryService.longTerm.search(args.topic, { + category: "rule", + skill: "moderation", + topK: args.topK ?? 3, + }); + if (docs.length > 0) { + return { + topic: args.topic, + text: docs.map((doc) => doc.text).join("\n\n"), + source: "knowledge_documents", + matches: docs.map((doc) => ({ + id: doc.id, + score: doc.score, + text: doc.text, + })), + }; + } + } catch (error) { + getRequestLogger().warn( + { err: error, topic: args.topic }, + "[lookup-rule] Knowledge retrieval failed; using local rules", + ); + } + } + + return legacyLookupRule(args.topic); }, }; diff --git a/src/tools/onboarding/lookup-community-rule.test.ts b/src/tools/onboarding/lookup-community-rule.test.ts new file mode 100644 index 0000000..202a527 --- /dev/null +++ b/src/tools/onboarding/lookup-community-rule.test.ts @@ -0,0 +1,56 @@ +import { describe, expect, it } from "vitest"; +import type { MemoryService } from "../../memory/memory-types.js"; +import { lookupCommunityRuleTool } from "./lookup-community-rule.js"; + +const failingMemoryService = { + longTerm: { + search: () => Promise.reject(new Error("retrieval failed")), + }, +} as unknown as MemoryService; + +describe("lookupCommunityRuleTool", () => { + it("accepts natural-language topics and falls back to constants", async () => { + const parsed = lookupCommunityRuleTool.argsSchema.parse({ + topic: "디스코드 안내", + }); + const result = await lookupCommunityRuleTool.execute(parsed, {}); + + expect(result.source).toBe("constants"); + expect(result.text).toContain("디스코드"); + }); + + it("uses retrieved onboarding knowledge when available", async () => { + const memoryService = { + longTerm: { + search: () => + Promise.resolve([ + { + category: "onboarding-step", + id: "doc-1", + score: 0.91, + text: "디스코드 닉네임은 롤 닉네임과 맞춰주세요.", + }, + ]), + }, + } as unknown as MemoryService; + + const result = await lookupCommunityRuleTool.execute( + { topic: "디스코드 닉네임" }, + { memoryService }, + ); + + expect(result.source).toBe("knowledge_documents"); + expect(result.matches?.[0]?.id).toBe("doc-1"); + expect(result.text).toContain("롤 닉네임"); + }); + + it("falls back to constants when knowledge retrieval fails", async () => { + const result = await lookupCommunityRuleTool.execute( + { topic: "닉네임 형식" }, + { memoryService: failingMemoryService }, + ); + + expect(result.source).toBe("constants"); + expect(result.text).toContain("닉네임"); + }); +}); diff --git a/src/tools/onboarding/lookup-community-rule.ts b/src/tools/onboarding/lookup-community-rule.ts index 990d14d..b7bdccb 100644 --- a/src/tools/onboarding/lookup-community-rule.ts +++ b/src/tools/onboarding/lookup-community-rule.ts @@ -1,4 +1,6 @@ import { z } from "zod"; +import { getRagEnabled } from "../../config.js"; +import { getRequestLogger } from "../../observability/context.js"; import { DEADLINE_NEAR_THRESHOLD_MIN, DISCORD_GUIDE_TEXT, @@ -10,23 +12,34 @@ import { import type { Tool } from "../tool.js"; const argsSchema = z.object({ - topic: z.enum([ - "age", - "tier-codes", - "discord-link", - "heart-rule", - "nickname-format", - "deadline", - ]), + topic: z.string().min(1).describe("검색할 온보딩 규칙 주제"), + topK: z.number().int().min(1).max(10).optional(), }); const resultSchema = z.object({ topic: argsSchema.shape.topic, text: z.string(), - source: z.literal("constants"), + source: z.enum(["constants", "knowledge_documents"]), + matches: z + .array( + z.object({ + id: z.string(), + score: z.number(), + text: z.string(), + }), + ) + .optional(), }); -const TOPIC_TEXT: Record["topic"], string> = { +type LegacyTopic = + | "age" + | "tier-codes" + | "discord-link" + | "heart-rule" + | "nickname-format" + | "deadline"; + +const TOPIC_TEXT: Record = { age: `가입 가능 연령은 ${MIN_AGE}세 이상이에요.`, "tier-codes": `사용 가능한 티어 코드는 ${TIER_CODES_TEXT}예요.`, "discord-link": DISCORD_GUIDE_TEXT, @@ -35,20 +48,74 @@ const TOPIC_TEXT: Record["topic"], string> = { deadline: `데드라인이 ${DEADLINE_NEAR_THRESHOLD_MIN}분 이하로 남으면 마감이 임박한 상태로 안내해요.`, }; +function resolveLegacyTopic(topic: string): LegacyTopic | null { + if ( + topic === "age" || + topic === "tier-codes" || + topic === "discord-link" || + topic === "heart-rule" || + topic === "nickname-format" || + topic === "deadline" + ) { + return topic; + } + if (/(나이|연령|age)/iu.test(topic)) return "age"; + if (/(티어|tier|랭크)/iu.test(topic)) return "tier-codes"; + if (/(디스코드|디코|discord)/iu.test(topic)) return "discord-link"; + if (/(하트|인증|사진|heart)/iu.test(topic)) return "heart-rule"; + if (/(닉네임|형식|이름|nickname)/iu.test(topic)) return "nickname-format"; + if (/(마감|데드라인|deadline|시간)/iu.test(topic)) return "deadline"; + return null; +} + +function legacyLookupCommunityRule(topic: string): z.infer { + const resolved = resolveLegacyTopic(topic); + return { + topic, + text: resolved + ? TOPIC_TEXT[resolved] + : Object.values(TOPIC_TEXT).join("\n"), + source: "constants", + }; +} + export const lookupCommunityRuleTool: Tool< z.infer, z.infer > = { name: "lookup-community-rule", description: - "나이 제한, 닉네임 형식, 티어 코드, 하트 인증 규칙, 디스코드 안내 같은 커뮤니티 규칙을 상수에서 조회한다.", + "나이 제한, 닉네임 형식, 티어 코드, 하트 인증 규칙, 디스코드 안내 같은 커뮤니티 규칙을 조회한다.", argsSchema, resultSchema, - execute(args) { - return Promise.resolve({ - topic: args.topic, - text: TOPIC_TEXT[args.topic], - source: "constants", - }); + async execute(args, ctx) { + if (ctx.memoryService && getRagEnabled()) { + try { + const docs = await ctx.memoryService.longTerm.search(args.topic, { + category: "onboarding-step", + skill: "onboarding", + topK: args.topK ?? 3, + }); + if (docs.length > 0) { + return { + topic: args.topic, + text: docs.map((doc) => doc.text).join("\n\n"), + source: "knowledge_documents", + matches: docs.map((doc) => ({ + id: doc.id, + score: doc.score, + text: doc.text, + })), + }; + } + } catch (error) { + getRequestLogger().warn( + { err: error, topic: args.topic }, + "[lookup-community-rule] Knowledge retrieval failed; using constants", + ); + } + } + + return legacyLookupCommunityRule(args.topic); }, }; diff --git a/src/tools/tool.ts b/src/tools/tool.ts index 0c9d314..240d683 100644 --- a/src/tools/tool.ts +++ b/src/tools/tool.ts @@ -1,4 +1,5 @@ import type { GarnetClient } from "@common/garnet"; +import type { MemoryService } from "../memory/memory-types.js"; import type { NatsClient } from "@common/nats"; import type { RoomContextService } from "@room/room-context-service"; import type { ZodType } from "zod"; @@ -11,6 +12,7 @@ export interface ToolContext { userId?: string | undefined; session?: OnboardingSession | null | undefined; garnetClient?: GarnetClient | undefined; + memoryService?: MemoryService | undefined; roomContextService?: RoomContextService | undefined; toolRegistry?: ToolRegistry | undefined; }