memento-mcp-server 1.13.1-a4 → 1.14.0-C

package/dist/domains/memory/tools/recall-tool.js

@@ -14,6 +14,9 @@ import { KnowledgeVaultService } from '../services/knowledge-vault-service.js';
 import { validateTypeParam } from '../../../shared/utils/type-param-validator.js';
 import { mementoConfig } from '../../../shared/config/index.js';
 import { DatabaseUtils } from '../../../shared/utils/database.js';
+import { MemoryNeighborService } from '../services/memory-neighbor-service.js';
+import { getVectorSearchEngine } from '../../search/algorithms/vector-search-engine.js';
+import { MemoryEmbeddingService } from '../services/memory-embedding-service.js';
 /**
  * Provider 필터 정규화 유틸리티
  * 빈 배열인 경우 undefined로 변환하여 모든 provider 검색을 의미
@@ -41,12 +44,25 @@ const RecallSchema = z.object({
     importance_min: z.number().min(0).max(1).optional(),
     importance_max: z.number().min(0).max(1).optional(),
     has_reflection_notes: z.boolean().optional(), // reflection_notes IS NOT NULL 필터링
+    // Procedural Memory Enhancement (v7.0) 필드
+    workflow_name: z.string().optional(),
+    skill_name: z.string().optional(),
+    match_trigger_conditions: z.boolean().optional().default(false),
+    context: z.record(z.any()).optional(), // 구조화된 컨텍스트 정보 (trigger_conditions 매칭용, 예: {tool_name, error_type, params})
+    trigger_context: z.record(z.any()).optional(), // context의 별칭 (하위 호환성)
+    return_format: z.enum(['full', 'steps_only']).optional().default('full'),
     limit: CommonSchemas.Limit,
     vector_weight: z.number().min(0).max(1).optional(),
     text_weight: z.number().min(0).max(1).optional(),
     enable_hybrid: z.boolean().optional(),
     include_metadata: z.boolean().optional(),
-    provider_filter: z.array(z.enum(['tfidf', 'lightweight', 'minilm', 'openai', 'gemini'])).optional()
+    provider_filter: z.array(z.enum(['tfidf', 'lightweight', 'minilm', 'openai', 'gemini'])).optional(),
+    // 자동 앵커 설정 및 이웃 기억 포함 파라미터
+    auto_set_anchor: z.boolean().optional().default(false),
+    include_neighbors: z.boolean().optional().default(false),
+    neighbors_limit: z.number().min(1).max(10).optional().default(3),
+    neighbors_per_item: z.number().min(1).max(50).optional().default(5),
+    neighbors_similarity_threshold: z.number().min(0).max(1).optional().default(0.8)
 }).refine((data) => {
     // 조건부 필수 검증
     if (data.type === 'core' || data.type === 'vault') {
@@ -128,6 +144,26 @@ export class RecallTool extends BaseTool {
                     type: 'boolean',
                     description: 'reflection_notes가 있는 메모리만 조회 (true: IS NOT NULL, false: IS NULL, 선택사항)'
                 },
+                // Procedural Memory Enhancement (v7.0) 필드
+                workflow_name: {
+                    type: 'string',
+                    description: '프로세스 이름으로 필터링 (선택사항)'
+                },
+                skill_name: {
+                    type: 'string',
+                    description: '기술/능력 이름으로 필터링 (선택사항)'
+                },
+                match_trigger_conditions: {
+                    type: 'boolean',
+                    default: false,
+                    description: 'trigger_conditions 매칭 여부 (기본값: false)'
+                },
+                return_format: {
+                    type: 'string',
+                    enum: ['full', 'steps_only'],
+                    default: 'full',
+                    description: '반환 형식 선택: full (모든 필드), steps_only (steps만 반환)'
+                },
                 limit: {
                     type: 'number',
                     minimum: 1,
@@ -163,6 +199,37 @@ export class RecallTool extends BaseTool {
                     type: 'array',
                     items: { type: 'string', enum: ['tfidf', 'lightweight', 'minilm', 'openai', 'gemini'] },
                     description: '검색할 임베딩 provider 필터 (선택사항, 미지정 시 모든 provider 검색)'
+                },
+                auto_set_anchor: {
+                    type: 'boolean',
+                    default: false,
+                    description: '가장 관련성 높은 기억(첫 번째 결과)을 슬롯 A에 자동으로 앵커로 설정 (기본값: false)'
+                },
+                include_neighbors: {
+                    type: 'boolean',
+                    default: false,
+                    description: '검색 결과의 상위 항목에 대해 이웃 기억을 자동으로 포함 (기본값: false)'
+                },
+                neighbors_limit: {
+                    type: 'number',
+                    minimum: 1,
+                    maximum: 10,
+                    default: 3,
+                    description: '이웃 기억을 포함할 상위 결과의 개수 (각 결과당 이웃 개수는 neighbors_per_item으로 제어, 기본값: 3)'
+                },
+                neighbors_per_item: {
+                    type: 'number',
+                    minimum: 1,
+                    maximum: 50,
+                    default: 5,
+                    description: '각 검색 결과 항목당 조회할 이웃 기억의 최대 개수 (기본값: 5)'
+                },
+                neighbors_similarity_threshold: {
+                    type: 'number',
+                    minimum: 0,
+                    maximum: 1,
+                    default: 0.8,
+                    description: '이웃 기억 조회 시 유사도 임계값 (이 값 이상인 기억만 반환, 기본값: 0.8)'
                 }
             },
             required: [] // 조건부 필수는 런타임 검증 (RecallSchema.refine()에서 처리)
@@ -173,7 +240,9 @@ export class RecallTool extends BaseTool {
         this.logInfo('Recall 도구 호출됨', { params });
         try {
             // 파라미터 검증 및 파싱
-            const { query, type, key, agent_id, memory_types, tags, privacy_scope, time_from, time_to, pinned, importance_min, importance_max, limit, vector_weight, text_weight, enable_hybrid, include_metadata, provider_filter } = RecallSchema.parse(params);
+            const { query, type, key, agent_id, memory_types, tags, privacy_scope, time_from, time_to, pinned, importance_min, importance_max, workflow_name, skill_name, match_trigger_conditions, context: triggerContext, trigger_context, return_format, limit, vector_weight, text_weight, enable_hybrid, include_metadata, provider_filter, auto_set_anchor, include_neighbors, neighbors_limit, neighbors_per_item, neighbors_similarity_threshold } = RecallSchema.parse(params);
+            // trigger_context가 제공되면 context로 사용 (하위 호환성)
+            const actualTriggerContext = triggerContext || trigger_context;
             // type 파라미터 롤아웃 모드 검증
             // PRD 요구사항: Phase 1/2에서는 type 파라미터가 없으면 항상 경고/Deprecated 메시지를 띄워야 함
             // memory_types만 있어도 경고를 띄워야 하므로, type이 없으면 항상 검증 수행
@@ -219,7 +288,7 @@ export class RecallTool extends BaseTool {
             });
             // 데이터베이스 연결 확인
             this.validateDatabase(context);
-            const startTime = Date.now();
+            const searchStartTime = Date.now();
             const agentId = agent_id || 'default';
             // type 파라미터에 따른 분기 처리
             if (validatedType === 'core') {
@@ -244,7 +313,7 @@ export class RecallTool extends BaseTool {
                     // 전체 Core Memory 조회
                     records = await coreMemoryService.findByAgentId(agentId);
                 }
-                const executionTime = Date.now() - startTime;
+                const executionTime = Date.now() - searchStartTime;
                 const processedResults = records.map(record => ({
                     memory_id: record.core_id,
                     type: 'core',
@@ -282,7 +351,7 @@ export class RecallTool extends BaseTool {
                     // 전체 Vault 조회 (활성 버전만)
                     records = await knowledgeVaultService.findActiveByAgentId(agentId);
                 }
-                const executionTime = Date.now() - startTime;
+                const executionTime = Date.now() - searchStartTime;
                 const processedResults = records.map(record => ({
                     memory_id: record.vault_id,
                     type: 'vault',
@@ -321,8 +390,24 @@ export class RecallTool extends BaseTool {
                     });
                 }
                 // memory_types 배열 전처리 ('core'/'vault' 제거)
-                // 원래 type 파라미터가 제공되었는지 확인하여 fallback 동작 보장
-                let filteredMemoryTypes = originalTypeProvided ? (validatedType ? [validatedType] : undefined) : memory_types;
+                // validatedType이 존재하면 항상 [validatedType]로 시작 (기본값 포함)
+                // originalTypeProvided가 false이고 memory_types가 제공되면 둘 다 고려하되, validatedType 우선
+                let filteredMemoryTypes;
+                if (validatedType) {
+                    // validatedType이 있으면 항상 사용 (기본값이든 명시적 값이든)
+                    filteredMemoryTypes = [validatedType];
+                    // originalTypeProvided가 false이고 memory_types도 제공되면 경고
+                    if (!originalTypeProvided && memory_types && memory_types.length > 0) {
+                        this.logWarning('type 파라미터가 미지정되어 기본값이 적용되었지만, memory_types도 제공되었습니다. 기본 타입을 우선 적용하고 memory_types는 무시합니다.', {
+                            default_type: validatedType,
+                            memory_types
+                        });
+                    }
+                }
+                else {
+                    // validatedType이 없으면 memory_types 사용
+                    filteredMemoryTypes = memory_types;
+                }
                 if (filteredMemoryTypes && filteredMemoryTypes.length > 0) {
                     const invalidTypes = filteredMemoryTypes.filter(t => t === 'core' || t === 'vault');
                     if (invalidTypes.length > 0) {
@@ -357,7 +442,10 @@ export class RecallTool extends BaseTool {
                     pinned,
                     importance_min,
                     importance_max,
-                    has_reflection_notes: params.has_reflection_notes
+                    has_reflection_notes: params.has_reflection_notes,
+                    // Procedural Memory Enhancement (v7.0) 필터
+                    workflow_name,
+                    skill_name
                 };
                 // 검색 옵션 설정
                 const vectorWeight = vector_weight ?? 0.6;
@@ -386,7 +474,9 @@ export class RecallTool extends BaseTool {
                             limit,
                             vectorWeight: normalizedVectorWeight,
                             textWeight: normalizedTextWeight,
-                            provider_filter: providerFilter
+                            provider_filter: providerFilter,
+                            match_trigger_conditions: match_trigger_conditions,
+                            context: actualTriggerContext // 구조화된 컨텍스트 정보 전달
                         });
                     }
                     else {
@@ -406,20 +496,52 @@ export class RecallTool extends BaseTool {
                     this.logError(searchError, '검색 실행 중 오류', { query, enableHybrid });
                     throw new Error(`검색 실행 실패: ${searchError.message}`);
                 }
-                const executionTime = Date.now() - startTime;
+                const executionTime = Date.now() - searchStartTime;
                 // 검색 결과 가져오기
-                const searchItems = searchResult?.items || [];
+                let searchItems = searchResult?.items || [];
+                // trigger_conditions 매칭 필터링 (match_trigger_conditions=true일 때)
+                if (match_trigger_conditions && searchItems.length > 0) {
+                    searchItems = this.filterByTriggerConditions(searchItems, query, actualTriggerContext);
+                }
                 // Consolidation Score System 업데이트 (기능 플래그 확인)
                 if (mementoConfig.consolidationScoreEnabled && context.services.consolidationScoreService && searchItems.length > 0) {
                     await this.updateConsolidationScoreMetadata(context.db, context.services.consolidationScoreService, context.services.writeCoalescingManager, searchItems);
                 }
                 // 결과 후처리 - searchResult가 undefined인 경우 처리
-                const processedResults = this.processSearchResults(searchItems, includeMetadata);
+                const processedResults = this.processSearchResults(searchItems, includeMetadata, return_format);
+                // 자동 앵커 설정 처리 (auto_set_anchor=true이고 검색 결과가 있을 때)
+                let anchorSetResult = null;
+                if (auto_set_anchor && searchItems.length > 0) {
+                    anchorSetResult = await this.handleAutoSetAnchor(searchItems, agentId, context);
+                }
+                // 자동 이웃 기억 포함 처리 (include_neighbors=true이고 검색 결과가 있을 때)
+                let neighborsResults = [];
+                if (include_neighbors && searchItems.length > 0) {
+                    neighborsResults = await this.handleIncludeNeighbors(searchItems, neighbors_limit, neighbors_per_item, neighbors_similarity_threshold, context);
+                    // 검색 결과 항목에 neighbors 필드 추가
+                    // neighbors_limit보다 많은 결과는 neighbors 필드 없음 (handleIncludeNeighbors가 상위 neighbors_limit개만 처리)
+                    for (let i = 0; i < Math.min(neighborsResults.length, processedResults.length); i++) {
+                        processedResults[i].neighbors = neighborsResults[i];
+                    }
+                }
                 this.logInfo('검색 완료', {
                     resultCount: processedResults.length,
                     executionTime,
                     searchType: enableHybrid ? 'hybrid' : 'text'
                 });
+                // 메타데이터 구성 (앵커 설정 결과 포함)
+                const metadata = {
+                    anchor_set: anchorSetResult?.anchor_set || null
+                };
+                // 앵커 설정 실패 시
+                if (anchorSetResult && anchorSetResult.error) {
+                    metadata.anchor_set_error = true;
+                }
+                // 앵커 설정 건너뜀 시
+                if (anchorSetResult && anchorSetResult.skipped) {
+                    metadata.anchor_set_skipped = true;
+                    metadata.anchor_set_skipped_reason = anchorSetResult.skipped_reason;
+                }
                 return this.createSuccessResult({
                     items: processedResults,
                     total_count: searchResult?.total_count || processedResults.length,
@@ -431,7 +553,8 @@ export class RecallTool extends BaseTool {
                         vector_weight: normalizedVectorWeight,
                         text_weight: normalizedTextWeight,
                         enable_hybrid: enableHybrid
-                    }
+                    },
+                    metadata
                 });
             }
         }
@@ -455,10 +578,91 @@ export class RecallTool extends BaseTool {
             throw error;
         }
     }
+    /**
+     * trigger_conditions로 필터링
+     * match_trigger_conditions=true일 때, 현재 컨텍스트와 trigger_conditions가 매칭되는 항목만 반환
+     *
+     * PRD 요구사항: 구조화된 컨텍스트(예: tool_name, error_type, params)와 JSON 매칭
+     * 구조화된 컨텍스트가 제공되면 이를 우선 사용하고, 없으면 쿼리 텍스트를 사용
+     *
+     * @param items 검색 결과 항목 배열
+     * @param query 검색 쿼리 (컨텍스트로 사용, fallback)
+     * @param context 구조화된 컨텍스트 정보 (우선 사용)
+     * @returns 필터링된 항목 배열
+     */
+    filterByTriggerConditions(items, query, triggerContext) {
+        const queryText = query?.toLowerCase() || '';
+        return items.filter(item => {
+            // trigger_conditions가 없는 항목은 제외
+            if (!item.trigger_conditions) {
+                return false;
+            }
+            try {
+                // JSON 파싱 시도
+                const parsed = typeof item.trigger_conditions === 'string'
+                    ? JSON.parse(item.trigger_conditions)
+                    : item.trigger_conditions;
+                // 객체인지 확인 (배열이나 null이 아닌 경우)
+                if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+                    return false;
+                }
+                // 구조화된 컨텍스트가 제공된 경우: 키-값 기반 정확 매칭
+                // 모든 키/값 쌍이 매칭되어야 함 (첫 번째 키만 맞으면 통과하는 문제 수정)
+                if (triggerContext && Object.keys(triggerContext).length > 0) {
+                    // trigger_conditions의 모든 키-값 쌍이 컨텍스트와 매칭되는지 확인
+                    for (const [key, value] of Object.entries(parsed)) {
+                        const contextValue = triggerContext[key];
+                        // trigger_conditions에 있는 키가 컨텍스트에 없으면 매칭 실패
+                        if (contextValue === undefined) {
+                            return false;
+                        }
+                        // 값이 객체인 경우 재귀적으로 비교
+                        if (typeof value === 'object' && typeof contextValue === 'object' && value !== null && contextValue !== null) {
+                            // 중첩 객체 매칭: context의 값이 trigger_conditions의 값과 부분적으로 일치하는지 확인
+                            const valueStr = JSON.stringify(value).toLowerCase();
+                            const contextStr = JSON.stringify(contextValue).toLowerCase();
+                            if (!(valueStr.includes(contextStr) || contextStr.includes(valueStr))) {
+                                // 하나라도 매칭되지 않으면 실패
+                                return false;
+                            }
+                        }
+                        else {
+                            // 단순 값 매칭: 문자열로 변환하여 비교
+                            const valueStr = String(value).toLowerCase();
+                            const contextStr = String(contextValue).toLowerCase();
+                            if (!(valueStr === contextStr || valueStr.includes(contextStr) || contextStr.includes(valueStr))) {
+                                // 하나라도 매칭되지 않으면 실패
+                                return false;
+                            }
+                        }
+                    }
+                    // 모든 키/값 쌍이 매칭됨
+                    return true;
+                }
+                // 구조화된 컨텍스트가 없는 경우: 쿼리 텍스트 기반 매칭 (fallback)
+                if (queryText) {
+                    // 키 매칭: tool_name, error_type, params 등 구조화된 필드명과 매칭
+                    const triggerKeys = Object.keys(parsed).map(k => k.toLowerCase());
+                    const triggerValues = Object.values(parsed).map(v => String(v).toLowerCase());
+                    // 키 또는 값 중 하나라도 쿼리와 매칭되면 통과
+                    const keyMatch = triggerKeys.some(k => k.includes(queryText) || queryText.includes(k));
+                    const valueMatch = triggerValues.some(v => v.includes(queryText) || queryText.includes(v));
+                    return keyMatch || valueMatch;
+                }
+                // 쿼리와 컨텍스트가 모두 없으면 매칭 기준이 없으므로 필터링
+                // PRD: "현재 컨텍스트와 매칭" 요구사항 - 매칭 기준이 없으면 통과하지 않음
+                return false;
+            }
+            catch (error) {
+                // JSON 파싱 실패 시 제외
+                return false;
+            }
+        });
+    }
     /**
      * 검색 결과 후처리
      */
-    processSearchResults(items, includeMetadata) {
+    processSearchResults(items, includeMetadata, returnFormat = 'full') {
         return items.map(item => {
             const processed = {
                 memory_id: item.id || item.memory_id, // 통일된 필드명 사용
@@ -491,6 +695,10 @@ export class RecallTool extends BaseTool {
                 if (item.type === 'procedural') {
                     processed.task_goal = item.task_goal || null;
                     processed.steps = item.steps || null;
+                    // Procedural Memory Enhancement (v7.0) 필드 추가
+                    processed.workflow_name = item.workflow_name || null;
+                    processed.skill_name = item.skill_name || null;
+                    processed.trigger_conditions = item.trigger_conditions || null;
                     // reflection_notes 필드 추가 (JSON 파싱)
                     if (item.reflection_notes) {
                         try {
@@ -507,6 +715,15 @@ export class RecallTool extends BaseTool {
                     else {
                         processed.reflection_notes = null;
                     }
+                    // return_format='steps_only'일 때 steps만 반환
+                    if (returnFormat === 'steps_only') {
+                        // steps만 포함하고 나머지 필드는 제거
+                        return {
+                            memory_id: processed.memory_id,
+                            id: processed.id,
+                            steps: processed.steps
+                        };
+                    }
                 }
                 if (item.textScore !== undefined) {
                     processed.text_score = item.textScore;
@@ -561,6 +778,263 @@ export class RecallTool extends BaseTool {
         }
         return applied;
     }
+    /**
+     * 자동 앵커 설정 처리
+     * 가장 관련성 높은 기억(첫 번째 결과)을 슬롯 A에 앵커로 설정
+     *
+     * @param searchItems - 검색 결과 항목 배열
+     * @param agentId - 에이전트 ID
+     * @param context - 도구 컨텍스트
+     * @returns 앵커 설정 결과 (성공/실패/건너뜀 상태 포함)
+     */
+    async handleAutoSetAnchor(searchItems, agentId, context) {
+        // 검색 결과가 없으면 앵커 설정 불가
+        if (!searchItems || searchItems.length === 0) {
+            return {
+                success: false,
+                anchor_set: null
+            };
+        }
+        // 첫 번째 결과의 memory_id 가져오기
+        const topMemory = searchItems[0];
+        const memoryId = topMemory.id || topMemory.memory_id;
+        if (!memoryId) {
+            this.logWarning('검색 결과에 memory_id가 없어 앵커 설정을 건너뜁니다', { topMemory });
+            return {
+                success: false,
+                anchor_set: null,
+                error: true
+            };
+        }
+        // AnchorManager 서비스 확인
+        if (!context.services.anchorManager) {
+            this.logWarning('AnchorManager 서비스가 없어 앵커 설정을 건너뜁니다');
+            return {
+                success: false,
+                anchor_set: null,
+                error: true
+            };
+        }
+        try {
+            // 슬롯 A의 앵커 조회 및 pinned 상태 확인 (memory_item 테이블과 조인)
+            const slotAAnchor = await context.services.anchorManager.getAnchor(agentId, 'A');
+            if (slotAAnchor && typeof slotAAnchor === 'object' && 'memory_id' in slotAAnchor) {
+                // pinned 상태 확인 (memory_item 테이블과 조인)
+                const anchorMemory = context.db.prepare(`
+          SELECT pinned FROM memory_item WHERE id = ?
+        `).get(slotAAnchor.memory_id);
+                const isPinned = anchorMemory && (anchorMemory.pinned === 1 || anchorMemory.pinned === true);
+                // 슬롯 A에 pinned 앵커가 있으면 건너뛰기 (보호 정책)
+                if (isPinned) {
+                    this.logInfo('슬롯 A에 pinned 앵커가 있어 앵커 설정을 건너뜁니다', {
+                        agent_id: agentId,
+                        existing_memory_id: slotAAnchor.memory_id
+                    });
+                    return {
+                        success: false,
+                        anchor_set: null,
+                        skipped: true,
+                        skipped_reason: 'pinned_anchor_protected'
+                    };
+                }
+                // 슬롯 A에 일반 앵커가 있으면 슬롯 B로 이동
+                const slotBAnchor = await context.services.anchorManager.getAnchor(agentId, 'B');
+                if (slotBAnchor && typeof slotBAnchor === 'object' && 'memory_id' in slotBAnchor) {
+                    // 슬롯 B의 pinned 상태 확인
+                    const slotBMemory = context.db.prepare(`
+            SELECT pinned FROM memory_item WHERE id = ?
+          `).get(slotBAnchor.memory_id);
+                    const slotBIsPinned = slotBMemory && (slotBMemory.pinned === 1 || slotBMemory.pinned === true);
+                    if (slotBIsPinned) {
+                        this.logWarning('슬롯 B의 pinned 앵커가 덮어써집니다', {
+                            agent_id: agentId,
+                            old_memory_id: slotBAnchor.memory_id,
+                            new_memory_id: slotAAnchor.memory_id
+                        });
+                    }
+                    // 슬롯 B에 앵커가 있으면 슬롯 C로 이동
+                    const slotCAnchor = await context.services.anchorManager.getAnchor(agentId, 'C');
+                    if (slotCAnchor && typeof slotCAnchor === 'object' && 'memory_id' in slotCAnchor) {
+                        // 슬롯 C의 pinned 상태 확인
+                        const slotCMemory = context.db.prepare(`
+              SELECT pinned FROM memory_item WHERE id = ?
+            `).get(slotCAnchor.memory_id);
+                        const slotCIsPinned = slotCMemory && (slotCMemory.pinned === 1 || slotCMemory.pinned === true);
+                        if (slotCIsPinned) {
+                            this.logWarning('슬롯 C의 pinned 앵커가 제거됩니다', {
+                                agent_id: agentId,
+                                old_memory_id: slotCAnchor.memory_id
+                            });
+                        }
+                        // 슬롯 C에 앵커가 있으면 제거 (pinned 여부와 관계없이 회전 규칙에 따라 제거)
+                        await context.services.anchorManager.clearAnchor(agentId, 'C');
+                    }
+                    // 슬롯 B의 기존 앵커를 슬롯 C로 이동 (슬롯 B를 비우기 위해)
+                    // PRD: 슬롯 B/C의 pinned 앵커도 덮어쓰고 A→B→C→제거 순으로 회전
+                    // 먼저 슬롯 B를 제거한 후 슬롯 C에 설정
+                    const slotBMemoryId = slotBAnchor.memory_id;
+                    await context.services.anchorManager.clearAnchor(agentId, 'B');
+                    await context.services.anchorManager.setAnchor(agentId, slotBMemoryId, 'C');
+                }
+                // 슬롯 A의 앵커를 슬롯 B로 이동
+                // 먼저 슬롯 A를 제거한 후 슬롯 B에 설정
+                const slotAMemoryId = slotAAnchor.memory_id;
+                await context.services.anchorManager.clearAnchor(agentId, 'A');
+                await context.services.anchorManager.setAnchor(agentId, slotAMemoryId, 'B');
+            }
+            // 새로운 기억을 슬롯 A에 설정
+            await context.services.anchorManager.setAnchor(agentId, memoryId, 'A');
+            this.logInfo('앵커가 자동으로 설정되었습니다', {
+                agent_id: agentId,
+                memory_id: memoryId,
+                slot: 'A'
+            });
+            return {
+                success: true,
+                anchor_set: {
+                    memory_id: memoryId,
+                    slot: 'A',
+                    agent_id: agentId
+                }
+            };
+        }
+        catch (error) {
+            // 앵커 설정 실패 시 경고만 로그하고 검색 결과는 정상 반환
+            this.logError(error, '앵커 자동 설정 실패', {
+                agent_id: agentId,
+                memory_id: memoryId
+            });
+            return {
+                success: false,
+                anchor_set: null,
+                error: true
+            };
+        }
+    }
+    /**
+     * 자동 이웃 기억 포함 처리
+     * 검색 결과의 상위 항목에 대해 이웃 기억을 자동으로 포함
+     *
+     * @param searchItems - 검색 결과 항목 배열
+     * @param neighborsLimit - 이웃 기억을 포함할 상위 결과의 개수
+     * @param neighborsPerItem - 각 검색 결과 항목당 조회할 이웃 기억의 최대 개수
+     * @param neighborsSimilarityThreshold - 이웃 기억 조회 시 유사도 임계값
+     * @param context - 도구 컨텍스트
+     * @returns 각 검색 결과 항목에 대한 이웃 기억 배열 (순서 보존)
+     */
+    async handleIncludeNeighbors(searchItems, neighborsLimit, neighborsPerItem, neighborsSimilarityThreshold, context) {
+        // 검색 결과가 없으면 빈 배열 반환
+        if (!searchItems || searchItems.length === 0) {
+            return [];
+        }
+        // 상위 neighbors_limit개 결과 추출 (검색 결과 개수보다 작으면 검색 결과 개수로 제한)
+        const topResults = searchItems.slice(0, Math.min(neighborsLimit, searchItems.length));
+        // MemoryNeighborService 인스턴스 생성
+        let neighborService;
+        try {
+            const vectorSearchEngine = getVectorSearchEngine();
+            const embeddingService = context.services.embeddingService || new MemoryEmbeddingService();
+            neighborService = new MemoryNeighborService(vectorSearchEngine, embeddingService);
+            neighborService.setDatabase(context.db);
+        }
+        catch (error) {
+            this.logError(error, 'MemoryNeighborService 초기화 실패', {});
+            // 서비스 초기화 실패 시 빈 배열 반환 (각 요소가 독립적인 배열 인스턴스)
+            return Array.from({ length: topResults.length }, () => []);
+        }
+        // 각 상위 결과에 대해 이웃 기억 조회를 병렬 처리
+        const neighborPromises = topResults.map(async (item, index) => {
+            const memoryId = item.id || item.memory_id;
+            if (!memoryId) {
+                this.logWarning('검색 결과에 memory_id가 없어 이웃 기억 조회를 건너뜁니다', { item });
+                return { index, neighbors: [] };
+            }
+            try {
+                // 개별 이웃 기억 조회에 타임아웃 적용 (각 조회당 최대 2초)
+                const timeoutPromise = new Promise((_, reject) => {
+                    setTimeout(() => reject(new Error('Timeout')), 2000);
+                });
+                const neighborPromise = neighborService.getNeighbors(memoryId, {
+                    limit: neighborsPerItem,
+                    similarity_threshold: neighborsSimilarityThreshold
+                }).then(result => ({
+                    index,
+                    neighbors: result.neighbors
+                }));
+                const result = await Promise.race([neighborPromise, timeoutPromise]);
+                return result;
+            }
+            catch (error) {
+                // 타임아웃 또는 에러 발생 시 빈 배열 반환
+                if (error instanceof Error && error.message === 'Timeout') {
+                    this.logWarning('이웃 기억 조회 타임아웃', { memoryId, index });
+                }
+                else {
+                    this.logError(error, '이웃 기억 조회 실패', { memoryId, index });
+                }
+                return { index, neighbors: [] };
+            }
+        });
+        // 전체 요청 타임아웃 적용 (2.5초, 부분 성공 결과 반환)
+        // 각 promise의 완료 상태를 추적하여 타임아웃 시 즉시 완료된 것만 반환
+        const completedResults = new Map();
+        // 각 promise에 대해 완료 시 결과를 저장
+        neighborPromises.forEach((promise, idx) => {
+            promise
+                .then(result => {
+                completedResults.set(idx, result);
+            })
+                .catch(() => {
+                // 에러는 무시하고 빈 배열로 처리
+                completedResults.set(idx, { index: idx, neighbors: [] });
+            });
+        });
+        let timeoutId = null;
+        const timeoutPromise = new Promise((resolve) => {
+            timeoutId = setTimeout(() => {
+                // 타임아웃 시 현재까지 완료된 결과만 즉시 반환 (Promise.allSettled를 기다리지 않음)
+                const partialResults = [];
+                // 완료된 결과 수집
+                for (let i = 0; i < topResults.length; i++) {
+                    if (completedResults.has(i)) {
+                        partialResults.push(completedResults.get(i));
+                    }
+                    else {
+                        // 완료되지 않은 항목은 빈 배열로 채움
+                        partialResults.push({ index: i, neighbors: [] });
+                    }
+                }
+                // 인덱스 순서로 정렬하여 반환
+                resolve(partialResults.sort((a, b) => a.index - b.index));
+            }, 2500); // 전체 타임아웃: 2.5초
+        });
+        try {
+            const allNeighbors = await Promise.race([
+                Promise.all(neighborPromises),
+                timeoutPromise
+            ]);
+            // 타임아웃 취소
+            if (timeoutId)
+                clearTimeout(timeoutId);
+            // 결과를 원래 순서로 정렬 (인덱스 기준)
+            const sortedNeighbors = allNeighbors
+                .sort((a, b) => a.index - b.index)
+                .map(r => r.neighbors);
+            return sortedNeighbors;
+        }
+        catch (error) {
+            // 타임아웃 취소
+            if (timeoutId)
+                clearTimeout(timeoutId);
+            // 타임아웃 시에도 부분 완료 결과는 반환됨 (timeoutPromise에서 처리)
+            // 완료된 결과만 반환
+            const settledResults = await Promise.allSettled(neighborPromises);
+            return settledResults.map((r, idx) => r.status === 'fulfilled'
+                ? r.value.neighbors
+                : [] // 실패한 항목은 빈 배열
+            );
+        }
+    }
     /**
      * 검색 쿼리 검증
      */