Add memory layers and RAG retrieval

This commit is contained in:
dahyeon committed 2026-05-18 22:33:25 -07:00
1 parent 1d0be56842
commit 1a86bded0b
31 files changed
+1592 -58

No files matched your search

+20
View File
@@ -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);
+41
View File
@@ -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"
+8 -1
View File
@@ -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<string, (deps: SkillRunnerDeps) => 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, {
+9 -1
View File
@@ -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<void> {
}
// MongoDB + RoomContextService setup (optional)
let mongoConnection: Awaited<ReturnType<typeof initMongoDB>> | undefined;
let roomContextService: InstanceType<typeof RoomContextService> | 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<void> {
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<void> {
factory({
garnetClient,
llmClient,
memoryService,
natsClient,
roomContextService,
shadowEvalBus,
+28
View File
@@ -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,
}),
]);
});
});
+40
View File
@@ -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<T extends { embedding: number[] }>(
query: number[],
docs: T[],
topK: number,
): Array<T & { score: number }> {
if (topK <= 0) {
return [];
}
return docs
.map((doc) => ({
...doc,
score: cosineSimilarity(query, doc.embedding),
}))
.sort((left, right) => right.score - left.score)
.slice(0, topK);
}
+146
View File
@@ -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<number[]>;
embedBatch(texts: string[]): Promise<number[][]>;
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<number[]> {
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<number[][]> {
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<number[]> {
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<number[][]> {
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(),
);
}
+52
View File
@@ -0,0 +1,52 @@
import { describe, expect, it } from "vitest";
import { GarnetSessionMemory, getSessionBlackboardKey } from "./garnet-session-memory.js";
class MemoryGarnet {
readonly records = new Map<string, unknown>();
getJson<T>(key: string): Promise<T | null> {
return Promise.resolve((this.records.get(key) as T | undefined) ?? null);
}
setJson(key: string, value: unknown): Promise<void> {
this.records.set(key, value);
return Promise.resolve();
}
getString(): Promise<string | null> {
return Promise.resolve(null);
}
setString(): Promise<void> {
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);
});
});
+75
View File
@@ -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<T>(
skill: string,
chatroomId: string,
userId: string,
): Promise<T | null> {
return this.garnetClient.getJson<T>(
getSessionBlackboardKey(skill, chatroomId, userId),
);
}
setBlackboard<T>(
skill: string,
chatroomId: string,
userId: string,
value: T,
): Promise<void> {
return this.garnetClient.setJson(
getSessionBlackboardKey(skill, chatroomId, userId),
value,
getBlackboardTtlSeconds(),
);
}
getConversationHistory(
chatroomId: string,
userId: string,
): Promise<ConversationMessage[]> {
return this.conversationStore.getHistory(chatroomId, userId);
}
appendMessage(
chatroomId: string,
userId: string,
message: ConversationMessage,
): Promise<void> {
return this.conversationStore.appendMessage(chatroomId, userId, message);
}
getSummary(chatroomId: string, userId: string): Promise<string | null> {
return this.conversationStore.getSummary(chatroomId, userId);
}
setSummary(
chatroomId: string,
userId: string,
summary: string,
): Promise<void> {
return this.conversationStore.setSummary(chatroomId, userId, summary);
}
}
+167
View File
@@ -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<boolean>;
}
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<IngestResult> {
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;
}
+50
View File
@@ -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: <T>() =>
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");
});
});
+95
View File
@@ -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<WorkingMemory> {
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<Blackboard>(
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);
}
+71
View File
@@ -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<string, unknown> | undefined;
}
export interface KnowledgeDocument {
id?: string | undefined;
skill?: string | undefined;
category: string;
text: string;
embedding?: number[] | undefined;
metadata?: Record<string, unknown> | 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<T>(skill: string, chatroomId: string, userId: string): Promise<T | null>;
setBlackboard<T>(
skill: string,
chatroomId: string,
userId: string,
value: T,
): Promise<void>;
getConversationHistory(chatroomId: string, userId: string): Promise<ConversationMessage[]>;
appendMessage(chatroomId: string, userId: string, message: ConversationMessage): Promise<void>;
getSummary(chatroomId: string, userId: string): Promise<string | null>;
setSummary(chatroomId: string, userId: string, summary: string): Promise<void>;
}
export interface SearchOptions {
skill?: string | undefined;
category?: string | undefined;
topK?: number | undefined;
}
export interface LongTermMemory {
loadUserProfile(userId: string): Promise<UserProfile | null>;
updateUserProfile(userId: string, patch: Partial<UserProfile>): Promise<void>;
search(query: string, options: SearchOptions): Promise<RetrievedDocument[]>;
upsertDocument(doc: KnowledgeDocument): Promise<string>;
deleteDocument(id: string): Promise<void>;
}
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<WorkingMemory>;
}
+266
View File
@@ -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<string, unknown> | undefined;
createdAt: Date;
updatedAt: Date;
}
const KnowledgeSchema = new Schema<KnowledgeDocumentRecord>(
{
_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<string, unknown> {
const filter: Record<string, unknown> = {};
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<KnowledgeDocumentRecord>;
constructor(
private readonly garnetClient: Pick<GarnetClient, "getJson" | "setJson">,
connection: mongoose.Connection,
private readonly embeddingClient: EmbeddingClient,
) {
this.model =
(connection.models["KnowledgeDocument"] as mongoose.Model<KnowledgeDocumentRecord> | undefined) ??
connection.model<KnowledgeDocumentRecord>(
"KnowledgeDocument",
KnowledgeSchema,
KNOWLEDGE_COLLECTION,
);
}
loadUserProfile(userId: string): Promise<UserProfile | null> {
return this.garnetClient.getJson<UserProfile>(userProfileKey(userId));
}
async updateUserProfile(
userId: string,
patch: Partial<UserProfile>,
): Promise<void> {
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<RetrievedDocument[]> {
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<string> {
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<boolean> {
return Boolean(await this.model.exists({ _id: id }).exec());
}
async deleteDocument(id: string): Promise<void> {
await this.model.deleteOne({ _id: id }).exec();
}
}
export class NoopLongTermMemory implements LongTermMemory {
constructor(private readonly garnetClient: Pick<GarnetClient, "getJson" | "setJson">) {}
loadUserProfile(userId: string): Promise<UserProfile | null> {
return this.garnetClient.getJson<UserProfile>(userProfileKey(userId));
}
async updateUserProfile(
userId: string,
patch: Partial<UserProfile>,
): Promise<void> {
const current = (await this.loadUserProfile(userId)) ?? emptyProfile(userId);
await this.garnetClient.setJson(
userProfileKey(userId),
{ ...current, ...patch, userId: current.userId },
userProfileTtlSeconds(),
);
}
search(): Promise<RetrievedDocument[]> {
return Promise.resolve([]);
}
upsertDocument(doc: KnowledgeDocument): Promise<string> {
return Promise.reject(
new Error(
`Knowledge memory is unavailable; cannot upsert ${doc.id ?? doc.category}`,
),
);
}
deleteDocument(): Promise<void> {
return Promise.resolve();
}
}
+1 -1
View File
@@ -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);
}
+41 -2
View File
@@ -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<string | undefined> {
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,
+1
View File
@@ -15,5 +15,6 @@ export function createOnboardingSkill(deps: SkillDeps): Skill {
deps.roomContextService,
deps.shadowEvalBus,
deps.natsClient,
deps.memoryService,
);
}
+22
View File
@@ -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');
}
@@ -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);
+12 -2
View File
@@ -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<NatsClient, 'request'>,
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,
};
+24 -1
View File
@@ -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<Blackboard> {
if (this.sessionMemory) {
const saved = await this.sessionMemory.getBlackboard<Blackboard>(
"onboarding",
chatroomId,
userId,
);
return mergeBlackboard(saved, {});
}
const key = getBlackboardKey(chatroomId, userId);
const saved = await this.garnetClient.getJson<Blackboard>(key);
return mergeBlackboard(saved, {});
@@ -50,6 +63,16 @@ export class OnboardingBlackboardStore {
userId: string,
value: Blackboard,
): Promise<void> {
if (this.sessionMemory) {
await this.sessionMemory.setBlackboard(
"onboarding",
chatroomId,
userId,
value,
);
return;
}
const key = getBlackboardKey(chatroomId, userId);
await this.garnetClient.setJson(
key,
+14 -2
View File
@@ -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<UserProfile | null> {
if (this.longTermMemory) {
return this.longTermMemory.loadUserProfile(userId);
}
return this.garnetClient.getJson<UserProfile>(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;
}
}
+2
View File
@@ -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;
+2
View File
@@ -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;
+23 -4
View File
@@ -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("광고");
});
});
+88 -19
View File
@@ -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<typeof argsSchema>["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<typeof resultSchema> {
const resolved = resolveLegacyTopic(topic);
return {
topic,
text: resolved ? extractRuleSection(resolved) : RULES_TEXT.trim(),
source: "community-rules",
};
}
export const lookupRuleTool: Tool<
z.infer<typeof argsSchema>,
z.infer<typeof resultSchema>
@@ -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);
},
};
@@ -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("닉네임");
});
});
+84 -17
View File
@@ -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<z.infer<typeof argsSchema>["topic"], string> = {
type LegacyTopic =
| "age"
| "tier-codes"
| "discord-link"
| "heart-rule"
| "nickname-format"
| "deadline";
const TOPIC_TEXT: Record<LegacyTopic, string> = {
age: `가입 가능 연령은 ${MIN_AGE}세 이상이에요.`,
"tier-codes": `사용 가능한 티어 코드는 ${TIER_CODES_TEXT}예요.`,
"discord-link": DISCORD_GUIDE_TEXT,
@@ -35,20 +48,74 @@ const TOPIC_TEXT: Record<z.infer<typeof argsSchema>["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<typeof resultSchema> {
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<typeof argsSchema>,
z.infer<typeof resultSchema>
> = {
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);
},
};
+2
View File
@@ -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;
}