companionbot 0.8.1 → 0.9.0

package/dist/ai/claude.js

@@ -75,6 +75,7 @@ export const MODELS = {
 export async function chat(messages, systemPrompt, modelId = "sonnet") {
     const client = getClient();
     const modelConfig = MODELS[modelId];
+    const toolsUsed = [];
     // 메시지를 API 형식으로 변환
     const apiMessages = messages.map((m) => ({
         role: m.role,
@@ -122,6 +123,12 @@ export async function chat(messages, systemPrompt, modelId = "sonnet") {
                 tool_use_id: toolUse.id,
                 content: truncatedResult,
             });
+            // 도구 사용 기록 (히스토리 참조용)
+            toolsUsed.push({
+                name: toolUse.name,
+                input: JSON.stringify(toolUse.input).slice(0, 200),
+                output: truncatedResult.slice(0, 500),
+            });
         }
         // 어시스턴트 메시지와 도구 결과 추가
         apiMessages.push({
@@ -138,11 +145,14 @@ export async function chat(messages, systemPrompt, modelId = "sonnet") {
     // 반복 횟수 초과 시 경고
     if (iterations >= MAX_TOOL_ITERATIONS) {
         console.warn(`[Warning] Tool use loop reached max iterations (${MAX_TOOL_ITERATIONS})`);
-        return "도구 실행이 너무 많이 반복됐어. 다시 시도해줄래?";
+        return { text: "도구 실행이 너무 많이 반복됐어. 다시 시도해줄래?", toolsUsed };
     }
     // 최종 텍스트 응답 추출
     const textBlock = response.content.find((block) => block.type === "text");
-    return textBlock?.text ?? "응답을 생성하지 못했어. 다시 시도해줄래?";
+    return {
+        text: textBlock?.text ?? "응답을 생성하지 못했어. 다시 시도해줄래?",
+        toolsUsed
+    };
 }
 /**
  * 스마트 채팅 - 가능하면 스트리밍, 도구 필요하면 일반 호출
@@ -151,12 +161,15 @@ export async function chat(messages, systemPrompt, modelId = "sonnet") {
  * - 먼저 스트리밍으로 시도
  * - 도구 호출이 감지되면 (stop_reason === "tool_use") 기존 chat()으로 폴백
  * - 스트리밍은 최종 텍스트 응답에만 사용
+ *
+ * 주의: 스트리밍은 재시도하지 않음 (이미 전송된 청크를 되돌릴 수 없음)
+ * 스트리밍 중 에러 발생 시 적절한 에러 메시지를 반환하거나 예외를 전파함
  */
 export async function chatSmart(messages, systemPrompt, modelId, onChunk) {
     // 스트리밍 콜백이 없으면 그냥 일반 chat 사용
     if (!onChunk) {
-        const text = await chat(messages, systemPrompt, modelId);
-        return { text, usedTools: false };
+        const result = await chat(messages, systemPrompt, modelId);
+        return { text: result.text, usedTools: result.toolsUsed.length > 0, toolsUsed: result.toolsUsed };
     }
     const client = getClient();
     const modelConfig = MODELS[modelId];
@@ -179,13 +192,12 @@ export async function chatSmart(messages, systemPrompt, modelId, onChunk) {
     // Thinking은 스트리밍에서 복잡해지므로 일단 비활성화
     // (도구 호출 폴백 시 chat()에서 thinking 사용됨)
     let accumulated = "";
-    let stopReason = null;
-    // 스트리밍에 withRetry 적용 - 실패 시 자동 재시도
-    return await withRetry(async () => {
-        accumulated = ""; // 재시도 시 초기화
+    let streamingStarted = false;
+    try {
         const stream = client.messages.stream(params);
         // 스트리밍 이벤트 처리
         stream.on("text", async (text) => {
+            streamingStarted = true;
             accumulated += text;
             try {
                 await onChunk(text, accumulated);
@@ -197,14 +209,43 @@ export async function chatSmart(messages, systemPrompt, modelId, onChunk) {
         });
         // 스트림 완료 대기
         const finalMessage = await stream.finalMessage();
-        stopReason = finalMessage.stop_reason;
+        const stopReason = finalMessage.stop_reason;
         // 도구 호출이 필요한 경우 - 일반 chat으로 폴백
+        // 주의: chat()은 내부에서 withRetry를 사용하므로 여기서 추가 재시도 불필요
         if (stopReason === "tool_use") {
             console.log("[Stream] Tool use detected, falling back to chat()");
-            const text = await chat(messages, systemPrompt, modelId);
-            return { text, usedTools: true };
+            const result = await chat(messages, systemPrompt, modelId);
+            return { text: result.text, usedTools: true, toolsUsed: result.toolsUsed };
         }
         // 성공적으로 스트리밍 완료
-        return { text: accumulated, usedTools: false };
-    });
+        return { text: accumulated, usedTools: false, toolsUsed: [] };
+    }
+    catch (error) {
+        // 스트리밍 시작 전 에러 (연결 실패 등) - 재시도 가능
+        if (!streamingStarted && error instanceof APIError) {
+            // Rate limit 또는 서버 에러는 withRetry로 재시도
+            if (error.status === 429 || error.status >= 500) {
+                console.log(`[Stream] Pre-stream error (${error.status}), retrying with withRetry...`);
+                return await withRetry(async () => {
+                    // 재시도 시 일반 chat 사용 (스트리밍 대신)
+                    const result = await chat(messages, systemPrompt, modelId);
+                    return { text: result.text, usedTools: false, toolsUsed: result.toolsUsed };
+                });
+            }
+        }
+        // 스트리밍 중 에러 - 재시도 불가 (이미 청크가 전송됨)
+        if (streamingStarted) {
+            console.error("[Stream] Error during streaming (cannot retry):", error);
+            // 이미 일부 텍스트가 전송됐으므로, 에러 메시지를 추가하거나 부분 결과 반환
+            if (accumulated.length > 0) {
+                return {
+                    text: accumulated + "\n\n(응답 생성 중 오류 발생)",
+                    usedTools: false,
+                    toolsUsed: []
+                };
+            }
+        }
+        // 그 외 에러는 전파
+        throw error;
+    }
 }

package/dist/cron/scheduler.js

@@ -167,9 +167,9 @@ async function executeAgentTurn(job, payload, bot) {
 - Run Count: ${(job.runCount || 0) + 1}
 - This is a scheduled task, not a direct user message.`;
         // Call Claude API
-        const response = await chat(messages, systemPrompt, "sonnet");
+        const result = await chat(messages, systemPrompt, "sonnet");
         // Send the response to the chat
-        const trimmedResponse = response?.trim();
+        const trimmedResponse = result.text?.trim();
         if (trimmedResponse) {
             // Split long messages (Telegram limit is 4096 characters)
             const maxLength = TELEGRAM_SAFE_LIMIT;

package/dist/heartbeat/index.js

@@ -141,9 +141,9 @@ ${context}
     ];
     let messageSent = false;
     try {
-        const response = await chat(messages, systemPrompt, "haiku");
-        if (!response.trim().includes("HEARTBEAT_OK")) {
-            await botInstance.api.sendMessage(config.chatId, response);
+        const result = await chat(messages, systemPrompt, "haiku");
+        if (!result.text.trim().includes("HEARTBEAT_OK")) {
+            await botInstance.api.sendMessage(config.chatId, result.text);
             console.log(`[Heartbeat] Sent message to ${config.chatId}`);
             messageSent = true;
             // 타임스탬프는 메모리 캐시에만 저장 (파일 쓰기 안 함)

package/dist/memory/vectorStore.js

@@ -1,6 +1,7 @@
 /**
  * 간단한 벡터 저장소 모듈
  * 메모리 파일들을 로드하고 유사도 기반으로 검색합니다.
+ * 임베딩은 파일에 캐시되어 재시작 후에도 유지됩니다.
  */
 import * as fs from "fs/promises";
 import * as path from "path";
@@ -10,8 +11,61 @@ import { embed, embedBatch, cosineSimilarity } from "./embeddings.js";
 let cachedChunks = [];
 let cacheTimestamp = 0;
 const CACHE_TTL_MS = 5 * 60 * 1000; // 5분
+// 임베딩 영속 캐시 (hash → embedding)
+let embeddingCache = new Map();
+let embeddingCacheLoaded = false;
 // 로딩 중복 방지용 Promise
 let loadingPromise = null;
+/**
+ * 간단한 해시 함수 (텍스트 변경 감지용)
+ */
+function simpleHash(text) {
+    let hash = 0;
+    for (let i = 0; i < text.length; i++) {
+        const char = text.charCodeAt(i);
+        hash = ((hash << 5) - hash) + char;
+        hash = hash & hash; // 32bit 정수로 변환
+    }
+    return hash.toString(16);
+}
+/**
+ * 임베딩 캐시 파일 경로
+ */
+function getEmbeddingCachePath() {
+    return path.join(getMemoryDirPath(), ".embedding-cache.json");
+}
+/**
+ * 임베딩 캐시를 파일에서 로드합니다.
+ */
+async function loadEmbeddingCache() {
+    if (embeddingCacheLoaded)
+        return;
+    try {
+        const cachePath = getEmbeddingCachePath();
+        const data = await fs.readFile(cachePath, "utf-8");
+        const parsed = JSON.parse(data);
+        embeddingCache = new Map(Object.entries(parsed));
+        console.log(`[VectorStore] Loaded ${embeddingCache.size} cached embeddings`);
+    }
+    catch {
+        // 파일 없거나 파싱 실패 - 새로 시작
+        embeddingCache = new Map();
+    }
+    embeddingCacheLoaded = true;
+}
+/**
+ * 임베딩 캐시를 파일에 저장합니다.
+ */
+async function saveEmbeddingCache() {
+    try {
+        const cachePath = getEmbeddingCachePath();
+        const obj = Object.fromEntries(embeddingCache);
+        await fs.writeFile(cachePath, JSON.stringify(obj), "utf-8");
+    }
+    catch (error) {
+        console.warn("[VectorStore] Failed to save embedding cache:", error);
+    }
+}
 /**
  * 텍스트를 적절한 크기의 청크로 분할합니다.
  */
@@ -30,7 +84,11 @@ function splitIntoChunks(text, source) {
             for (const line of lines) {
                 if (currentChunk.length + line.length > 500) {
                     if (currentChunk.trim()) {
-                        chunks.push({ text: currentChunk.trim(), source });
+                        chunks.push({
+                            text: currentChunk.trim(),
+                            source,
+                            hash: simpleHash(currentChunk.trim())
+                        });
                     }
                     currentChunk = line;
                 }
@@ -39,11 +97,19 @@ function splitIntoChunks(text, source) {
                 }
             }
             if (currentChunk.trim()) {
-                chunks.push({ text: currentChunk.trim(), source });
+                chunks.push({
+                    text: currentChunk.trim(),
+                    source,
+                    hash: simpleHash(currentChunk.trim())
+                });
             }
         }
         else {
-            chunks.push({ text: trimmed, source });
+            chunks.push({
+                text: trimmed,
+                source,
+                hash: simpleHash(trimmed)
+            });
         }
     }
     return chunks;
@@ -52,12 +118,14 @@ function splitIntoChunks(text, source) {
  * 내부 로드 로직 - 실제 파일 로드 수행
  */
 async function doLoadAllMemoryChunks() {
+    // 임베딩 캐시 로드
+    await loadEmbeddingCache();
     const chunks = [];
     // 1. 일별 메모리 파일 (최근 30일)
     const memoryDir = getMemoryDirPath();
     try {
         const files = await fs.readdir(memoryDir);
-        const mdFiles = files.filter(f => f.endsWith(".md")).sort().reverse().slice(0, 30);
+        const mdFiles = files.filter(f => f.endsWith(".md") && !f.startsWith(".")).sort().reverse().slice(0, 30);
         for (const file of mdFiles) {
             try {
                 const content = await fs.readFile(path.join(memoryDir, file), "utf-8");
@@ -82,6 +150,15 @@ async function doLoadAllMemoryChunks() {
     catch {
         // 파일 없음 무시
     }
+    // 3. 캐시된 임베딩 복원
+    for (const chunk of chunks) {
+        if (chunk.hash) {
+            const cachedEmbedding = embeddingCache.get(chunk.hash);
+            if (cachedEmbedding) {
+                chunk.embedding = cachedEmbedding;
+            }
+        }
+    }
     return chunks;
 }
 /**
@@ -131,24 +208,35 @@ export async function search(queryEmbedding, topK = 5, minScore = 0.3) {
     // 임베딩이 없는 청크들을 배치로 처리
     const chunksNeedingEmbedding = chunks.filter(c => !c.embedding);
     if (chunksNeedingEmbedding.length > 0) {
+        console.log(`[VectorStore] Generating embeddings for ${chunksNeedingEmbedding.length} chunks`);
         try {
             const texts = chunksNeedingEmbedding.map(c => c.text);
             const embeddings = await embedBatch(texts);
-            // 임베딩 할당
+            // 임베딩 할당 및 캐시 저장
             for (let i = 0; i < chunksNeedingEmbedding.length; i++) {
-                chunksNeedingEmbedding[i].embedding = embeddings[i];
+                const chunk = chunksNeedingEmbedding[i];
+                chunk.embedding = embeddings[i];
+                if (chunk.hash) {
+                    embeddingCache.set(chunk.hash, embeddings[i]);
+                }
             }
+            // 캐시 파일 저장 (비동기, 실패해도 무시)
+            saveEmbeddingCache().catch(() => { });
         }
         catch {
             // 배치 실패 시 개별 처리 폴백
             for (const chunk of chunksNeedingEmbedding) {
                 try {
                     chunk.embedding = await embed(chunk.text);
+                    if (chunk.hash) {
+                        embeddingCache.set(chunk.hash, chunk.embedding);
+                    }
                 }
                 catch {
                     // 개별 실패 무시
                 }
             }
+            saveEmbeddingCache().catch(() => { });
         }
     }
     // 유사도 계산 및 필터링
@@ -172,12 +260,27 @@ export async function search(queryEmbedding, topK = 5, minScore = 0.3) {
 }
 /**
  * 캐시를 무효화합니다.
+ * 임베딩 캐시는 유지 (텍스트 해시 기반이므로)
  */
 export function invalidateCache() {
     cachedChunks = [];
     cacheTimestamp = 0;
     loadingPromise = null;
 }
+/**
+ * 임베딩 캐시까지 완전 초기화합니다.
+ */
+export async function clearAllCaches() {
+    invalidateCache();
+    embeddingCache.clear();
+    embeddingCacheLoaded = false;
+    try {
+        await fs.unlink(getEmbeddingCachePath());
+    }
+    catch {
+        // 파일 없으면 무시
+    }
+}
 // 인메모리 저장소 (간단한 구현)
 let vectorStore = [];
 /**

package/dist/session/state.js

@@ -1,9 +1,13 @@
 import { AsyncLocalStorage } from "async_hooks";
-import { estimateMessagesTokens } from "../utils/tokens.js";
+import { estimateMessagesTokens, estimateTokens } from "../utils/tokens.js";
 // 세션 설정
 const MAX_SESSIONS = 100;
 const SESSION_TTL_MS = 24 * 60 * 60 * 1000; // 24시간
-const MAX_HISTORY_TOKENS = 50000; // 시스템 프롬프트 + 응답 여유 남기고
+// 토큰 한도 (개선됨)
+const MAX_HISTORY_TOKENS = 40000; // 히스토리 한도
+const SUMMARY_THRESHOLD_TOKENS = 25000; // 이 이상이면 요약 시작
+const MIN_RECENT_MESSAGES = 6; // 최소 유지할 최근 메시지
+const MAX_PINNED_TOKENS = 5000; // 핀 맥락 최대 토큰
 // 세션별 상태 저장
 const sessions = new Map();
 // AsyncLocalStorage for chatId context
@@ -11,18 +15,24 @@ const chatIdStorage = new AsyncLocalStorage();
 function getSession(chatId) {
     // chatId 유효성 검사
     if (chatId == null || isNaN(chatId)) {
-        console.warn(`[Session] Invalid chatId: ${chatId}, using fallback session`);
-        // 임시 세션 반환 (저장하지 않음)
+        console.error(`[Session] BUG: Invalid chatId: ${chatId} - history will NOT persist!`);
         return {
             history: [],
             model: "sonnet",
             lastAccessedAt: Date.now(),
+            pinnedContexts: [],
+            summaryChunks: [],
         };
     }
     const existing = sessions.get(chatId);
     const now = Date.now();
     if (existing) {
         existing.lastAccessedAt = now;
+        // 마이그레이션: 기존 세션에 새 필드 추가
+        if (!existing.pinnedContexts)
+            existing.pinnedContexts = [];
+        if (!existing.summaryChunks)
+            existing.summaryChunks = [];
         return existing;
     }
     // 새 세션 생성 전 정리
@@ -31,8 +41,11 @@ function getSession(chatId) {
         history: [],
         model: "sonnet",
         lastAccessedAt: now,
+        pinnedContexts: [],
+        summaryChunks: [],
     };
     sessions.set(chatId, session);
+    console.log(`[Session] Created new session for chatId=${chatId}, total sessions=${sessions.size}`);
     return session;
 }
 function cleanupSessions() {
@@ -55,24 +68,233 @@ function cleanupSessions() {
 }
 export function getHistory(chatId) {
     const session = getSession(chatId);
-    // 참조 반환 (외부 수정 허용 - 의도적)
-    // 필요시 [...session.history]로 복사본 반환 가능
-    return session.history ?? [];
+    if (!session.history) {
+        session.history = [];
+    }
+    return session.history;
+}
+/**
+ * 핀된 맥락 가져오기
+ */
+export function getPinnedContexts(chatId) {
+    return getSession(chatId).pinnedContexts;
+}
+/**
+ * 요약 청크 가져오기
+ */
+export function getSummaryChunks(chatId) {
+    return getSession(chatId).summaryChunks;
+}
+/**
+ * 중요 맥락 핀하기
+ */
+export function pinContext(chatId, text, source = "user") {
+    const session = getSession(chatId);
+    const currentTokens = session.pinnedContexts.reduce((sum, p) => sum + estimateTokens(p.text), 0);
+    const newTokens = estimateTokens(text);
+    // 토큰 한도 체크
+    if (currentTokens + newTokens > MAX_PINNED_TOKENS) {
+        // 오래된 자동 핀부터 제거
+        while (session.pinnedContexts.length > 0 &&
+            currentTokens + newTokens > MAX_PINNED_TOKENS) {
+            const autoIndex = session.pinnedContexts.findIndex((p) => p.source === "auto");
+            if (autoIndex >= 0) {
+                session.pinnedContexts.splice(autoIndex, 1);
+            }
+            else {
+                // 자동 핀 없으면 추가 불가
+                return false;
+            }
+        }
+    }
+    session.pinnedContexts.push({
+        text,
+        createdAt: Date.now(),
+        source,
+    });
+    console.log(`[Pin] chatId=${chatId} added pin (${source}): ${text.slice(0, 50)}...`);
+    return true;
+}
+/**
+ * 핀 제거
+ */
+export function unpinContext(chatId, index) {
+    const session = getSession(chatId);
+    if (index >= 0 && index < session.pinnedContexts.length) {
+        session.pinnedContexts.splice(index, 1);
+        return true;
+    }
+    return false;
+}
+/**
+ * 모든 핀 제거
+ */
+export function clearPins(chatId) {
+    getSession(chatId).pinnedContexts = [];
+}
+/**
+ * 요약 청크 추가
+ */
+export function addSummaryChunk(chatId, chunk) {
+    const session = getSession(chatId);
+    session.summaryChunks.push(chunk);
+    // 오래된 요약은 병합 (최대 3개 유지)
+    while (session.summaryChunks.length > 3) {
+        const [first, second] = session.summaryChunks.splice(0, 2);
+        session.summaryChunks.unshift({
+            summary: `${first.summary}\n\n${second.summary}`,
+            messageCount: first.messageCount + second.messageCount,
+            startTime: first.startTime,
+            endTime: second.endTime,
+        });
+    }
 }
 /**
- * 히스토리를 토큰 기반으로 트리밍한다.
- * 최대 토큰 한도를 초과하면 가장 오래된 메시지부터 제거 (최소 2개는 유지).
+ * 개선된 히스토리 트리밍
+ *
+ * 전략:
+ * 1. 최근 N개 메시지는 반드시 유지
+ * 2. 토큰이 임계치 초과하면 오래된 메시지 제거 (요약 청크로 변환 가능)
+ * 3. 핀된 맥락은 별도로 보존됨 (여기서 처리 안 함)
  */
 export function trimHistoryByTokens(history) {
-    // null/undefined/빈 배열 처리
     if (!history || history.length === 0) {
         return;
     }
-    while (estimateMessagesTokens(history) > MAX_HISTORY_TOKENS && history.length > 2) {
+    const currentTokens = estimateMessagesTokens(history);
+    // 한도 이내면 패스
+    if (currentTokens <= MAX_HISTORY_TOKENS) {
+        return;
+    }
+    console.log(`[Trim] Starting trim: ${currentTokens} tokens, ${history.length} messages`);
+    // 최근 메시지는 반드시 유지
+    while (estimateMessagesTokens(history) > MAX_HISTORY_TOKENS && history.length > MIN_RECENT_MESSAGES) {
         history.shift();
     }
+    const afterTokens = estimateMessagesTokens(history);
+    console.log(`[Trim] After trim: ${afterTokens} tokens, ${history.length} messages`);
+}
+/**
+ * 스마트 트리밍 - 요약과 함께 수행
+ *
+ * @param chatId 채팅 ID
+ * @param summarizeFn 요약 함수 (외부 주입 - API 호출 필요)
+ * @returns 요약이 수행되었는지 여부
+ */
+export async function smartTrimHistory(chatId, summarizeFn) {
+    const session = getSession(chatId);
+    const history = session.history;
+    if (!history || history.length === 0) {
+        return false;
+    }
+    const currentTokens = estimateMessagesTokens(history);
+    // 요약 임계치 이하면 패스
+    if (currentTokens <= SUMMARY_THRESHOLD_TOKENS) {
+        return false;
+    }
+    // 요약 함수가 없으면 기본 트리밍만
+    if (!summarizeFn) {
+        trimHistoryByTokens(history);
+        return false;
+    }
+    console.log(`[SmartTrim] chatId=${chatId} tokens=${currentTokens}, starting summarization...`);
+    // 오래된 메시지들 (최근 6개 제외)
+    const toSummarize = history.slice(0, -MIN_RECENT_MESSAGES);
+    const toKeep = history.slice(-MIN_RECENT_MESSAGES);
+    if (toSummarize.length < 4) {
+        // 요약할 게 별로 없으면 기본 트리밍
+        trimHistoryByTokens(history);
+        return false;
+    }
+    try {
+        const summary = await summarizeFn(toSummarize);
+        // 요약 청크 저장
+        addSummaryChunk(chatId, {
+            summary,
+            messageCount: toSummarize.length,
+            startTime: Date.now() - (toSummarize.length * 60000), // 대략적인 시간
+            endTime: Date.now(),
+        });
+        // 히스토리 교체: [요약 메시지] + [최근 메시지들]
+        history.splice(0, history.length);
+        history.push({
+            role: "user",
+            content: `[이전 대화 요약]\n${summary}`
+        });
+        history.push({
+            role: "assistant",
+            content: "네, 이전 대화 내용을 기억하고 있어요."
+        });
+        history.push(...toKeep);
+        const afterTokens = estimateMessagesTokens(history);
+        console.log(`[SmartTrim] chatId=${chatId} summarized: ${currentTokens} → ${afterTokens} tokens`);
+        return true;
+    }
+    catch (error) {
+        console.error(`[SmartTrim] Failed to summarize:`, error);
+        // 실패하면 기본 트리밍으로 폴백
+        trimHistoryByTokens(history);
+        return false;
+    }
+}
+/**
+ * 중요 맥락 자동 감지
+ *
+ * 패턴:
+ * - "기억해", "잊지 마", "remember"
+ * - 이름, 선호도, 중요 정보 언급
+ * - 명시적 핀 요청
+ */
+export function detectImportantContext(message) {
+    const patterns = [
+        /기억해[줘요]?\s*[:：]?\s*(.+)/i,
+        /잊지\s*마[줘요]?\s*[:：]?\s*(.+)/i,
+        /remember\s*[:：]?\s*(.+)/i,
+        /내\s*이름은?\s+(.+?)(?:이야|야|입니다|예요|요)?[.!]?\s*$/i,
+        /나는?\s+(.+?)(?:을|를)?\s*(?:좋아해|싫어해|선호해)/i,
+    ];
+    for (const pattern of patterns) {
+        const match = message.match(pattern);
+        if (match && match[1]) {
+            return match[1].trim();
+        }
+    }
+    return null;
+}
+/**
+ * 시스템 프롬프트용 맥락 문자열 생성
+ */
+export function buildContextForPrompt(chatId) {
+    const session = getSession(chatId);
+    const parts = [];
+    // 핀된 맥락
+    if (session.pinnedContexts.length > 0) {
+        parts.push("## 📌 중요 맥락 (사용자가 기억해달라고 한 것들)");
+        session.pinnedContexts.forEach((p, i) => {
+            parts.push(`${i + 1}. ${p.text}`);
+        });
+    }
+    // 요약 청크 (있으면)
+    if (session.summaryChunks.length > 0) {
+        parts.push("\n## 📜 이전 대화 요약");
+        session.summaryChunks.forEach((chunk) => {
+            parts.push(`- ${chunk.summary}`);
+        });
+    }
+    return parts.join("\n");
 }
 export function clearHistory(chatId) {
+    const session = sessions.get(chatId);
+    if (session) {
+        session.history = [];
+        session.summaryChunks = [];
+        // 핀은 유지 (중요 맥락이므로)
+    }
+}
+/**
+ * 완전 초기화 (핀 포함)
+ */
+export function clearSession(chatId) {
     sessions.delete(chatId);
 }
 export function getModel(chatId) {
@@ -81,27 +303,30 @@ export function getModel(chatId) {
 export function setModel(chatId, modelId) {
     getSession(chatId).model = modelId;
 }
-/**
- * Run a function with chatId context using AsyncLocalStorage.
- * All code inside the callback can access the chatId via getCurrentChatId().
- */
 export function runWithChatId(chatId, fn) {
     return chatIdStorage.run(chatId, fn);
 }
-/**
- * Get the current chatId from AsyncLocalStorage context.
- * Returns null if called outside of runWithChatId().
- */
 export function getCurrentChatId() {
     return chatIdStorage.getStore() ?? null;
 }
-// 세션 정리 (수동 호출용)
 export function cleanupExpiredSessions() {
     const before = sessions.size;
     cleanupSessions();
     return before - sessions.size;
 }
-// 현재 세션 수 조회
 export function getSessionCount() {
     return sessions.size;
 }
+/**
+ * 세션 통계 (디버그용)
+ */
+export function getSessionStats(chatId) {
+    const session = getSession(chatId);
+    return {
+        historyLength: session.history.length,
+        historyTokens: estimateMessagesTokens(session.history),
+        pinnedCount: session.pinnedContexts.length,
+        pinnedTokens: session.pinnedContexts.reduce((sum, p) => sum + estimateTokens(p.text), 0),
+        summaryCount: session.summaryChunks.length,
+    };
+}