@futdevpro/fdp-agent-memory 0.1.0 → 1.1.14

package/build/src/_modules/migration/_services/fam-agent-memory-reader.service.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_AgentMemoryReader_Service = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const error_codes_const_1 = require("../../../_collections/error-codes.const");
+const fam_error_factory_util_1 = require("../../../_collections/fam-error-factory.util");
+const fam_claude_mem_source_type_enum_1 = require("../_enums/fam-claude-mem-source.type-enum");
+const fam_claude_mem_interface_1 = require("../_models/interfaces/fam-claude-mem.interface");
+/**
+ * `FAM_AgentMemoryReader_Service` (agent-memory import, SP-11.1-mintára) — az agent (Claude) tartós
+ * memóriáját (`.claude/.../memory/*.md`) olvassa be **függőség-mentesen** (fs + egyszerű frontmatter-parse),
+ * és `FAM_ClaudeMemRecord[]`-dá normalizálja → a meglévő import-engine (preview/run/rollback/dedup/embed)
+ * VÁLTOZATLANUL feldolgozza (a `readSource` `agent-memory`-ágáról hívva).
+ *
+ * **Forrás-shape (a memória-fájlok frontmatter-e):**
+ * ```
+ * ---
+ * name: <kebab-slug>
+ * description: <egy-soros>
+ * metadata:
+ *   type: user | feedback | project | reference
+ * ---
+ * <markdown body … [[link]] …>
+ * ```
+ * A `MEMORY.md` (mutató-index, NEM memória) **kihagyva**. Defenzív: parse-hiba/üres fájl → `warnings`, a
+ * többi folytatódik (nothing-lost). A cél-tár a `type`-ról képződik a `FAM_TargetMapping_Util`-ban
+ * (reference→knowledge, feedback→rules, project→memory, user→knowledge).
+ */
+class FAM_AgentMemoryReader_Service {
+    static _instance;
+    issuer = 'FAM_AgentMemoryReader_Service';
+    /** A mutató-index fájl (egy-soros pointer-lista, NEM önálló memória) — az importból kihagyva. */
+    static INDEX_FILE = 'MEMORY.md';
+    /** Az agent-memory rekordok rögzített scope-projektje (egy scope minden bejegyzésre; a run auto-create-eli). */
+    static SCOPE_PROJECT = 'agent-memory';
+    static getInstance() {
+        if (!FAM_AgentMemoryReader_Service._instance) {
+            FAM_AgentMemoryReader_Service._instance = new FAM_AgentMemoryReader_Service();
+        }
+        return FAM_AgentMemoryReader_Service._instance;
+    }
+    /** A memória-mappa beolvasása → normalizált rekordok (a `path` a `*.md`-ket tartalmazó könyvtár). */
+    async read(set) {
+        const dir = set.path ?? '';
+        if (!dir || !fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.impSource,
+                message: `Az agent-memory mappa nem található vagy nem könyvtár: '${dir}'.`,
+                issuer: this.issuer,
+                context: { operation: 'agent-memory-read' },
+            });
+        }
+        const warnings = [];
+        const files = fs.readdirSync(dir)
+            .filter((file) => file.toLowerCase().endsWith('.md') && file !== FAM_AgentMemoryReader_Service.INDEX_FILE)
+            .sort();
+        const records = [];
+        for (const file of files) {
+            const full = path.join(dir, file);
+            try {
+                const parsed = FAM_AgentMemoryReader_Service.parse(fs.readFileSync(full, 'utf8'));
+                if (!parsed.body.trim() && !(parsed.description && parsed.description.trim())) {
+                    warnings.push(`üres memória-fájl kihagyva: ${file}`);
+                    continue;
+                }
+                records.push(this.toRecord(file, full, parsed));
+            }
+            catch (error) {
+                warnings.push(`agent-memory parse-hiba (${file}): ${error?.message}`);
+            }
+        }
+        return {
+            from: fam_claude_mem_source_type_enum_1.FAM_ClaudeMemSource_Type.agentMemory,
+            records: records,
+            sessions: [],
+            counts: { observations: records.length, summaries: 0, prompts: 0, sessions: 0 },
+            warnings: warnings,
+        };
+    }
+    /** Egy parse-olt memória → `FAM_ClaudeMemRecord` (entity=agentMemory; type a cél-tárhoz; slug a dedup-hoz). */
+    toRecord(file, fullPath, parsed) {
+        const slug = (parsed.name && parsed.name.trim()) ? parsed.name.trim() : file.replace(/\.md$/i, '');
+        return {
+            entity: fam_claude_mem_interface_1.FAM_ClaudeMemEntity_Type.agentMemory,
+            sourceRowId: slug,
+            project: FAM_AgentMemoryReader_Service.SCOPE_PROJECT,
+            type: parsed.type,
+            title: parsed.description,
+            narrative: parsed.body,
+            concepts: parsed.links,
+            filesRead: [],
+            filesModified: [fullPath],
+        };
+    }
+    /**
+     * Egy `.md` fájl frontmatter + body + `[[link]]` parse-e (függőség-mentes, defenzív). A frontmatter a
+     * `---\n…\n---` blokk; a `name`/`description` top-szintű, a `type` a `metadata:` alatt indentált — mindet a
+     * sor-szintű `field`-regex húzza (az indentet `^\s*` engedi). Frontmatter nélkül a teljes szöveg a body.
+     */
+    static parse(raw) {
+        const links = [...new Set((raw.match(/\[\[([^\]]+)\]\]/g) ?? []).map((m) => m.slice(2, -2).trim()))]
+            .filter((link) => link.length > 0);
+        const frontMatch = raw.match(/^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/);
+        if (!frontMatch) {
+            return { body: raw.trim(), links: links };
+        }
+        const front = frontMatch[1];
+        const body = (frontMatch[2] ?? '').trim();
+        return {
+            name: FAM_AgentMemoryReader_Service.field(front, 'name'),
+            description: FAM_AgentMemoryReader_Service.field(front, 'description'),
+            type: FAM_AgentMemoryReader_Service.field(front, 'type'),
+            body: body,
+            links: links,
+        };
+    }
+    /** Egy frontmatter-mező értéke (`key: value`, sor-szintű, indent-toleráns; a körülvevő idézőjel levágva). */
+    static field(front, key) {
+        const match = front.match(new RegExp(`^\\s*${key}\\s*:\\s*(.+)$`, 'm'));
+        return match ? match[1].trim().replace(/^["']|["']$/g, '').trim() : undefined;
+    }
+}
+exports.FAM_AgentMemoryReader_Service = FAM_AgentMemoryReader_Service;

package/build/src/_modules/migration/_services/fam-claude-mem-import.control-service.js

@@ -14,12 +14,15 @@ const scope_reference_1 = require("../../scope-reference");
 const fam_claude_mem_source_type_enum_1 = require("../_enums/fam-claude-mem-source.type-enum");
 const fam_import_content_hash_util_1 = require("../_collections/fam-import-content-hash.util");
 const fam_target_mapping_util_1 = require("../_collections/fam-target-mapping.util");
+const fam_agent_memory_reader_service_1 = require("./fam-agent-memory-reader.service");
 const fam_claude_mem_export_reader_service_1 = require("./fam-claude-mem-export-reader.service");
 const fam_claude_mem_sqlite_reader_service_1 = require("./fam-claude-mem-sqlite-reader.service");
 const fam_claude_mem_worker_reader_service_1 = require("./fam-claude-mem-worker-reader.service");
 const fam_import_dedup_data_service_1 = require("./fam-import-dedup.data-service");
 /** A preview `mappingPreview` mintájának mérete (nem a teljes lista — a `map` adja a teljeset). */
 const PREVIEW_SAMPLE_SIZE = 10;
+/** Hány feldolgozott rekordonként írjon a run egy progress-sort a szerver-konzolra (user: „more feedback in logs"). */
+const PROGRESS_LOG_EVERY = 2000;
 /** A claude-mem `project` raw név alapértelmezett scope-layer-e (dsgn-009 §4 — project-layer). */
 const PROJECT_SCOPE_LAYER = 'project';
 /**
@@ -69,11 +72,15 @@ class FAM_ClaudeMemImport_ControlService {
         const dedup = { willImport: 0, willSkipExisting: 0, willSkipDuplicateContent: 0 };
         const mappingPreview = [];
         const previewUncertainty = [];
+        // FAM-REV-063: per-projekt scope-feloldás memoizálás (különben 68k rekord = 68k embed → preview-timeout).
+        const scopeCache = new Map();
+        // FAM-REV-063: dedup-batch-index (a per-rekord 3 DB-query helyett in-memory) — a cél-tárak EGYSZER töltve.
+        const dedupIndex = await fam_import_dedup_data_service_1.FAM_ImportDedup_DataService.getInstance().buildIndex(this.targetTablesFor(data, request));
         for (const record of data.records) {
-            const plan = await this.buildPlan({ record: record, request: request, allowCreateScope: false, uncertainty: previewUncertainty });
-            const verdict = await fam_import_dedup_data_service_1.FAM_ImportDedup_DataService.getInstance().verdictFor({
-                record: record, table: plan.table, importSourceId: plan.importSourceId, contentHash: plan.contentHash,
-            });
+            const plan = await this.buildPlan({ record: record, request: request, allowCreateScope: false, uncertainty: previewUncertainty, scopeCache: scopeCache });
+            const verdict = fam_import_dedup_data_service_1.FAM_ImportDedup_DataService.getInstance().verdictForIndexed({
+                table: plan.table, importSourceId: plan.importSourceId, contentHash: plan.contentHash,
+            }, dedupIndex);
             this.tallyDedup(dedup, verdict);
             if (mappingPreview.length < PREVIEW_SAMPLE_SIZE) {
                 mappingPreview.push(plan);
@@ -105,9 +112,10 @@ class FAM_ClaudeMemImport_ControlService {
         const warnings = [...data.warnings];
         const uncertainty = [];
         const plans = [];
+        const scopeCache = new Map(); // FAM-REV-063
         for (const record of data.records) {
             plans.push(await this.buildPlan({
-                record: record, request: request, allowCreateScope: false, uncertainty: uncertainty,
+                record: record, request: request, allowCreateScope: false, uncertainty: uncertainty, scopeCache: scopeCache,
             }));
         }
         return {
@@ -139,14 +147,26 @@ class FAM_ClaudeMemImport_ControlService {
         let failed = 0;
         // Embedding-költség pillanatkép a batch ELŐTT (a delta a batch embed-költsége — BFR-AM-007).
         const costBefore = embedding_1.FAM_EmbeddingCost_ControlService.getInstance().getStats().totalEstimatedCostUsd;
+        // FAM-REV-063: per-projekt scope-feloldás memoizálás (a 68k rekord ~25 projektje egyszer oldódjon fel/
+        // auto-create-elődjön; a run dominánsan a content-embed, de a scope-embed így is 68k→25-re csökken).
+        const scopeCache = new Map();
+        // FAM-REV-063: dedup-batch-index (in-memory, futó-akkumulátor) a per-rekord DB-query helyett.
+        const dedupIndex = await fam_import_dedup_data_service_1.FAM_ImportDedup_DataService.getInstance().buildIndex(this.targetTablesFor(data, request));
+        // Progress-feedback (user-direktíva 2026-06-21: „add more feedback in logs"): a hosszú import alatt a
+        // szerver-konzol mutassa a haladást (nem csak az LM Studio pörög). START + periodikus + KÉSZ sorok.
+        const total = data.records.length;
+        const startMs = Date.now();
+        let processed = 0;
+        fsm_dynamo_1.DyFM_Log.log(`[claude-mem import] ▶ START — ${total} rekord, batch=${batchId} `
+            + `(includePrompts=${request.includePrompts ?? false}). A dedup-skip nem embeddel (gyors); az ÚJ rekordok embeddelődnek.`);
         for (const record of data.records) {
             try {
                 const plan = await this.buildPlan({
-                    record: record, request: request, allowCreateScope: true, uncertainty: uncertaintyNotes,
-                });
-                const verdict = await fam_import_dedup_data_service_1.FAM_ImportDedup_DataService.getInstance().verdictFor({
-                    record: record, table: plan.table, importSourceId: plan.importSourceId, contentHash: plan.contentHash,
+                    record: record, request: request, allowCreateScope: true, uncertainty: uncertaintyNotes, scopeCache: scopeCache,
                 });
+                const verdict = fam_import_dedup_data_service_1.FAM_ImportDedup_DataService.getInstance().verdictForIndexed({
+                    table: plan.table, importSourceId: plan.importSourceId, contentHash: plan.contentHash,
+                }, dedupIndex);
                 if (verdict !== 'import') {
                     // A skip-eltek NEM embeddelődnek (cost-takarékosság — dsgn-009 §5.3 / §9.3).
                     skipped++;
@@ -171,7 +191,19 @@ class FAM_ClaudeMemImport_ControlService {
                     importSourceId: fam_target_mapping_util_1.FAM_TargetMapping_Util.importSourceId(record),
                 });
             }
+            // Periodikus progress (minden PROGRESS_LOG_EVERY rekord + a legvégén): feldolgozva / összes,
+            // ingested/skipped/failed, processed-ráta + durva ETA — a szerver-konzolon élőben látszik.
+            processed++;
+            if (processed % PROGRESS_LOG_EVERY === 0 || processed === total) {
+                const elapsedS = Math.max(1, Math.round((Date.now() - startMs) / 1000));
+                const procRate = processed / elapsedS;
+                const etaMin = procRate > 0 ? Math.round((total - processed) / procRate / 60) : 0;
+                fsm_dynamo_1.DyFM_Log.log(`[claude-mem import] ${processed}/${total} — ingested ${ingested}, skipped ${skipped} (dedup), `
+                    + `failed ${failed} | ${procRate.toFixed(1)} rec/s, ~${etaMin} perc hátra (elapsed ${elapsedS}s).`);
+            }
         }
+        fsm_dynamo_1.DyFM_Log.log(`[claude-mem import] ✓ KÉSZ — ${ingested} ingested + ${skipped} skipped (dedup) + ${failed} failed `
+            + `= ${total} rekord, ${Math.max(1, Math.round((Date.now() - startMs) / 1000))}s alatt. batch=${batchId}.`);
         const costAfter = embedding_1.FAM_EmbeddingCost_ControlService.getInstance().getStats().totalEstimatedCostUsd;
         const status = this.runStatus(ingested, failed);
         const result = {
@@ -249,14 +281,22 @@ class FAM_ClaudeMemImport_ControlService {
         const from = this.resolveFrom(request);
         const includePrompts = this.resolveIncludePrompts(request);
         const path = request.path ?? '';
+        let data;
         switch (from) {
             case fam_claude_mem_source_type_enum_1.FAM_ClaudeMemSource_Type.exportJson:
-                return fam_claude_mem_export_reader_service_1.FAM_ClaudeMemExportReader_Service.getInstance().read({ path: path, includePrompts: includePrompts });
+                data = await fam_claude_mem_export_reader_service_1.FAM_ClaudeMemExportReader_Service.getInstance().read({ path: path, includePrompts: includePrompts });
+                break;
             case fam_claude_mem_source_type_enum_1.FAM_ClaudeMemSource_Type.sqlite:
-                return fam_claude_mem_sqlite_reader_service_1.FAM_ClaudeMemSqliteReader_Service.getInstance().read({ path: path, includePrompts: includePrompts });
+                data = await fam_claude_mem_sqlite_reader_service_1.FAM_ClaudeMemSqliteReader_Service.getInstance().read({ path: path, includePrompts: includePrompts });
+                break;
             case fam_claude_mem_source_type_enum_1.FAM_ClaudeMemSource_Type.workerApi:
-                return fam_claude_mem_worker_reader_service_1.FAM_ClaudeMemWorkerReader_Service.getInstance()
-                    .read({ baseUrl: path, includePrompts: includePrompts });
+                data = await fam_claude_mem_worker_reader_service_1.FAM_ClaudeMemWorkerReader_Service.getInstance().read({ baseUrl: path, includePrompts: includePrompts });
+                break;
+            case fam_claude_mem_source_type_enum_1.FAM_ClaudeMemSource_Type.agentMemory:
+                // Agent-memory markdown-mappa (`.claude/.../memory/*.md`) — a reader `FAM_ClaudeMemRecord`-ot
+                // termel, így a teljes run/preview/rollback/dedup/embed VÁLTOZATLANUL feldolgozza.
+                data = await fam_agent_memory_reader_service_1.FAM_AgentMemoryReader_Service.getInstance().read({ path: path });
+                break;
             default:
                 throw fam_error_factory_util_1.FAM_Error_Util.create({
                     errorCode: error_codes_const_1.FAM_ERROR_CODES.impSource,
@@ -265,6 +305,24 @@ class FAM_ClaudeMemImport_ControlService {
                     context: { operation: 'import-read-source' },
                 });
         }
+        return this.applyImportFilters(data, request);
+    }
+    /**
+     * Kurált-subset szűrés a beolvasott rekordokra (L3 „A" opció + teszt-limit). `excludeTypes` → a megadott
+     * observation-`type`-ok kihagyva (a summary/prompt — nincs `type` — MARAD); `maxRecords` → a szűrt lista
+     * levágva. Mindkettő a `preview`-ban ÉS a `run`-ban hat (a `readSource` a közös belépő). Szűrés nélkül a
+     * forrás-objektum változatlanul tér vissza (nincs fölös másolás).
+     */
+    applyImportFilters(data, request) {
+        let records = data.records;
+        if (request.excludeTypes && request.excludeTypes.length) {
+            const exclude = new Set(request.excludeTypes);
+            records = records.filter((record) => !(record.type && exclude.has(record.type)));
+        }
+        if (typeof request.maxRecords === 'number' && request.maxRecords >= 0) {
+            records = records.slice(0, request.maxRecords);
+        }
+        return records === data.records ? data : { ...data, records: records };
     }
     // =========================================================================
     // leképezési-terv építés (SP-11.2: target-mapping + scope-resolve)
@@ -276,6 +334,17 @@ class FAM_ClaudeMemImport_ControlService {
      * `resolveForWrite` (auto-create-elhet). A scope-feloldás van-match-bizonytalansága az `uncertainty`
      * gyűjtőbe (NEM hiba).
      */
+    /**
+     * A rekordok DISTINCT cél-tárai (FAM-REV-063, a dedup-index építéséhez) — OLCSÓ: csak a target-mapping
+     * (`resolveTarget`) fut rekordonként (NINCS embed/scope-feloldás), így a 68k rekordon is ms-ek.
+     */
+    targetTablesFor(data, request) {
+        const tables = new Set();
+        for (const record of data.records) {
+            tables.add(fam_target_mapping_util_1.FAM_TargetMapping_Util.resolveTarget({ record: record, overrides: request.overrides }).table);
+        }
+        return Array.from(tables);
+    }
     async buildPlan(set) {
         const target = fam_target_mapping_util_1.FAM_TargetMapping_Util.resolveTarget({ record: set.record, overrides: set.request.overrides });
         const content = fam_target_mapping_util_1.FAM_TargetMapping_Util.composeContent(set.record);
@@ -284,7 +353,7 @@ class FAM_ClaudeMemImport_ControlService {
         });
         const importSourceId = fam_target_mapping_util_1.FAM_TargetMapping_Util.importSourceId(set.record);
         const scopeResolve = await this.resolveScopeForRecord({
-            record: set.record, request: set.request, allowCreateScope: set.allowCreateScope,
+            record: set.record, request: set.request, allowCreateScope: set.allowCreateScope, cache: set.scopeCache,
         });
         for (const note of scopeResolve.uncertaintyNotes) {
             set.uncertainty.push(note);
@@ -315,14 +384,28 @@ class FAM_ClaudeMemImport_ControlService {
         if (!rawScope || !rawScope.length) {
             return { scopePath: [], uncertaintyNotes: [] };
         }
+        // FAM-REV-063: a scope a rekord `project`-jétől függ (a 68k rekord ~25 distinct projektre), de a
+        // feloldás (`previewResolveScope`/`resolveForWrite`) EMBEDDEL → per-rekord hívás = 68k embed (preview-
+        // timeout). Memoizálás a rawScope-kulcson: projektenként EGYSZER oldunk fel. Cache-HIT → a scopePath
+        // ugyanaz, de az uncertaintyNotes ÜRES (a note-ot az első [miss] feloldás már begyűjtötte → nincs 68k dup).
+        const cacheKey = JSON.stringify(rawScope);
+        const cached = set.cache?.get(cacheKey);
+        if (cached) {
+            return { scopePath: cached.scopePath, uncertaintyNotes: [] };
+        }
+        let resolved;
         if (set.allowCreateScope) {
             // run: a write-path teljes feloldása (auto-create-elhet — createdBy='agent-write' a MP-3-ban).
             const resolve = await scope_reference_1.FAM_ScopeResolver_ControlService.getInstance().resolveForWrite(rawScope);
-            return { scopePath: resolve.scopePath, uncertaintyNotes: resolve.uncertaintyNotes };
+            resolved = { scopePath: resolve.scopePath, uncertaintyNotes: resolve.uncertaintyNotes };
+        }
+        else {
+            // preview/map: read-only — a read-expand-szerű feloldás NEM hoz létre scope-ot. A trace-feloldáson
+            // át döntjük el, feloldható-e biztosan; ha nem, üres scopePath + a bizonytalanság jelezve.
+            resolved = await this.previewResolveScope(rawScope);
         }
-        // preview/map: read-only — a read-expand-szerű feloldás NEM hoz létre scope-ot. A trace-feloldáson
-        // át döntjük el, feloldható-e biztosan; ha nem, üres scopePath + a bizonytalanság jelezve.
-        return this.previewResolveScope(rawScope);
+        set.cache?.set(cacheKey, resolved);
+        return resolved;
     }
     /**
      * Egy rekord nyers scope-lánca: az override `scope['project:<name>']` explicit `scopePath`-ja

package/build/src/_modules/migration/_services/fam-import-dedup.data-service.js

@@ -71,6 +71,59 @@ class FAM_ImportDedup_DataService {
         }
         return 'import';
     }
+    /**
+     * **Batch-index építése (FAM-REV-063)** — a per-rekord `verdictFor` 3 DB-query-je 68k rekordon ~136s
+     * (preview-timeout). Ehelyett a cél-tárak MEGLÉVŐ claude-mem entry-jeinek `importSourceId` + `contentHash`
+     * kulcsait EGYSZER töltjük Set-ekbe (táranként), és a `verdictForIndexed` in-memory dönt. Első importnál a
+     * forrás-szűrt halmaz üres → azonnali. (Megjegyzés: a betöltés még nem projektált [lean-find = BFR-AM-013],
+     * így RE-importnál a már beimportált halmaz teljes entry-it tölti — első importnál ez 0.)
+     */
+    async buildIndex(tables) {
+        const byTable = new Map();
+        for (const table of tables) {
+            const entry = { sourceIds: new Set(), contentHashes: new Set() };
+            byTable.set(table, entry);
+            const dataService = this.dataServiceFor(table);
+            if (!dataService) {
+                continue;
+            }
+            const existing = await dataService.findHydratableList({
+                importSource: FAM_ImportDedup_DataService.IMPORT_SOURCE,
+            });
+            for (const item of existing) {
+                if (item.importSourceId) {
+                    entry.sourceIds.add(item.importSourceId);
+                }
+                if (item.contentHash) {
+                    entry.contentHashes.add(item.contentHash);
+                }
+            }
+        }
+        return { byTable: byTable };
+    }
+    /**
+     * In-memory dedup-verdikt a batch-indexszel (FAM-REV-063) — a `verdictFor` (1)+(2) lépcsőjének
+     * O(1) megfelelője, NULLA DB-query-vel. Az index egyben **futó-akkumulátor**: az `import`-nak ítélt
+     * rekord kulcsai bekerülnek, így a forráson-belüli (within-batch) duplikátumok is `skip-duplicate-content`-
+     * et kapnak (pontosabb forecast + a sequential run idempotenciája). A (3) ritka, (2)-vel gyakorlatilag
+     * redundáns kompozit-fallback NEM része az indexelt útnak (perf-tradeoff — dsgn-009 §3).
+     */
+    verdictForIndexed(set, index) {
+        let entry = index.byTable.get(set.table);
+        if (!entry) {
+            entry = { sourceIds: new Set(), contentHashes: new Set() };
+            index.byTable.set(set.table, entry);
+        }
+        if (entry.sourceIds.has(set.importSourceId)) {
+            return 'skip-existing';
+        }
+        if (entry.contentHashes.has(set.contentHash)) {
+            return 'skip-duplicate-content';
+        }
+        entry.sourceIds.add(set.importSourceId);
+        entry.contentHashes.add(set.contentHash);
+        return 'import';
+    }
     /** A (3) fallback kompozit-kulcs jelenléte: sdk_session_id + title + created_at_epoch mind kell. */
     hasCompositeKey(record) {
         return Boolean(record.sdkSessionId && record.title && typeof record.createdAtEpoch === 'number');

package/build/src/_modules/migration/index.js

@@ -11,7 +11,7 @@
  * függőség (BFR-AM-009 fallback) — a bedrock-reader landolásakor (MP-15) CSAK a reader-impl cserélődik.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FAM_ClaudeMemEntity_Type = exports.FAM_ClaudeMemSource_Type = exports.FAM_ImportContentHash_Util = exports.FAM_TargetMapping_Util = exports.FAM_ImportDedup_DataService = exports.FAM_ClaudeMemNormalize_Util = exports.FAM_ClaudeMemWorkerReader_Service = exports.FAM_ClaudeMemSqliteReader_Service = exports.FAM_ClaudeMemExportReader_Service = exports.FAM_ClaudeMemImport_ControlService = void 0;
+exports.FAM_ClaudeMemEntity_Type = exports.FAM_ClaudeMemSource_Type = exports.FAM_ImportContentHash_Util = exports.FAM_TargetMapping_Util = exports.FAM_ImportDedup_DataService = exports.FAM_ClaudeMemNormalize_Util = exports.FAM_AgentMemoryReader_Service = exports.FAM_ClaudeMemWorkerReader_Service = exports.FAM_ClaudeMemSqliteReader_Service = exports.FAM_ClaudeMemExportReader_Service = exports.FAM_ClaudeMemImport_ControlService = void 0;
 // SP-11.3 — a migrációs engine (preview → map → run → rollback)
 var fam_claude_mem_import_control_service_1 = require("./_services/fam-claude-mem-import.control-service");
 Object.defineProperty(exports, "FAM_ClaudeMemImport_ControlService", { enumerable: true, get: function () { return fam_claude_mem_import_control_service_1.FAM_ClaudeMemImport_ControlService; } });
@@ -22,6 +22,8 @@ var fam_claude_mem_sqlite_reader_service_1 = require("./_services/fam-claude-mem
 Object.defineProperty(exports, "FAM_ClaudeMemSqliteReader_Service", { enumerable: true, get: function () { return fam_claude_mem_sqlite_reader_service_1.FAM_ClaudeMemSqliteReader_Service; } });
 var fam_claude_mem_worker_reader_service_1 = require("./_services/fam-claude-mem-worker-reader.service");
 Object.defineProperty(exports, "FAM_ClaudeMemWorkerReader_Service", { enumerable: true, get: function () { return fam_claude_mem_worker_reader_service_1.FAM_ClaudeMemWorkerReader_Service; } });
+var fam_agent_memory_reader_service_1 = require("./_services/fam-agent-memory-reader.service");
+Object.defineProperty(exports, "FAM_AgentMemoryReader_Service", { enumerable: true, get: function () { return fam_agent_memory_reader_service_1.FAM_AgentMemoryReader_Service; } });
 var fam_claude_mem_normalize_util_1 = require("./_collections/fam-claude-mem-normalize.util");
 Object.defineProperty(exports, "FAM_ClaudeMemNormalize_Util", { enumerable: true, get: function () { return fam_claude_mem_normalize_util_1.FAM_ClaudeMemNormalize_Util; } });
 // SP-11.2 — dedup + target-mapping + content-hash

package/build/src/_modules/retrieval/_services/fam-retrieval-candidate.data-service.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FAM_RetrievalCandidate_DataService = void 0;
+const tslib_1 = require("tslib");
+const mongoose_1 = tslib_1.__importDefault(require("mongoose"));
 const fam_table_type_enum_1 = require("../../../_enums/fam-table.type-enum");
 const embedding_1 = require("../../embedding");
 /**
@@ -33,8 +35,77 @@ class FAM_RetrievalCandidate_DataService {
             return [];
         }
         const filter = this.buildFilter(input, registryEntry);
-        const dataService = new embedding_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
-        return dataService.findDataList(filter);
+        return this.findActiveCandidates(registryEntry, filter);
+    }
+    /**
+     * FEAT-003 — egy tár azon entry-jei, amik az adott azonosító-kódok BÁRMELYIKÉT citálják
+     * (`referenceCodes $in codes`), az AZONOS prefilter-kontextussal (scope subtree + tag + kind +
+     * `rules.isActive` guard), mint a vektor-jelölt-betöltés. Ez a determinisztikus read-expanzió Mongo-
+     * lekérdezése: a kód-keresés a vektor-hasonlóság HELYETT explicit link → az ÖSSZES citáló elem,
+     * `embeddingStatus`-tól függetlenül. Üres kód-lista / ismeretlen tár → üres lista (no-op).
+     */
+    async loadByReferenceCodes(input, codes) {
+        if (!codes.length) {
+            return [];
+        }
+        const registryEntry = embedding_1.FAM_StoreRegistry_Util.getEntry(input.table);
+        if (!registryEntry) {
+            return [];
+        }
+        const filter = this.buildFilter(input, registryEntry);
+        filter.referenceCodes = { $in: codes };
+        return this.findActiveCandidates(registryEntry, filter);
+    }
+    /**
+     * A topK-hit metaadat-betöltése `_id`-listából (az UNSCOPED read-fast-path-hez, SP-5.x perf). A főpool-
+     * keresés UTÁN CSAK a tényleges hit-eket tölti (a hit-row + weight + recency összefűzéséhez), NEM mind a
+     * jelöltet — unscoped query-nél ez a Mongo-munkát ~242×-ére csökkenti (mért: 727ms → 3ms). Aktív-only
+     * (`_deleted:null`) + `contentVector`-kihagyó lean (a `findActiveCandidates`-en át; a `_id $in` string-ID-it
+     * a Mongoose a `_id`-úton ObjectId-ra castolja). Üres lista / ismeretlen tár → üres (no-op).
+     */
+    async loadByIds(table, ids) {
+        if (!ids.length) {
+            return [];
+        }
+        const registryEntry = embedding_1.FAM_StoreRegistry_Util.getEntry(table);
+        if (!registryEntry) {
+            return [];
+        }
+        const filter = {};
+        filter._id = { $in: ids };
+        return this.findActiveCandidates(registryEntry, filter);
+    }
+    /**
+     * PERF (FAM-REV / BFR-AM-013): a jelölt-betöltés a `contentVector`-t (a domináns memória-/transzfer-
+     * költség: ~2560 float ≈ 20 KB/entry; 23k codebase-entry ≈ 486 MB) **KIHAGYJA** — a vektorok MÁR az
+     * in-memory LVS-pool-ban élnek, a candidate-stage SOHA nem olvassa az `entry.contentVector`-t (a
+     * `toHit`/`mergeCodeHit` sem). **Lean** (plain object, NEM Mongoose-doc → nincs schema-hidratálás) +
+     * `contentVector`-kihagyó projekció a mongoose-modellen → a per-query jelölt-load **~40s → ~1s** (mért
+     * 46,9× a raw-load-on; a Mongoose-hidratálás-megtakarítás tetézi). A `_deleted:null` az aktív-szűrő
+     * (a `findDataList` DB-service-szintű soft-delete-kizárását replikálja: a soft-delete `_deleted`-et
+     * `Date`-re állítja, az aktív entry-n hiányzik/`null`). Model-hiány (boot-előtt) → `findDataList`-fallback
+     * (korrekt, csak lassabb).
+     */
+    async findActiveCandidates(registryEntry, filter) {
+        const dataName = registryEntry.dataParams.dataName;
+        const model = mongoose_1.default.models[dataName];
+        if (!model) {
+            // Fallback: a model még nincs regisztrálva (pl. boot-bootstrap előtt) → teljes-doc findDataList.
+            const dataService = new embedding_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
+            return dataService.findDataList(filter);
+        }
+        // `_deleted:null` → aktív-only (a soft-delete Date-marker kizárva); `contentVector:0` → a 486MB pool-
+        // duplikátum kihagyva; `.lean()` → nincs Mongoose-doc hidratálás.
+        const leanFilter = { ...filter, _deleted: null };
+        const docs = await model.find(leanFilter, { contentVector: 0 }).lean().exec();
+        // KRITIKUS (_id-konzisztencia): a `.lean()` a NYERS Mongo `_id`-t adja (ObjectId), DE a
+        // `DyFM_Metadata._id` STRING, és a vektor-pool-kulcsok + a `findDataList` is string `_id`-vel
+        // dolgoznak. ObjectId-kulcs SOHA nem egyezne a string pool-kulccsal (`Map.get` referencia-
+        // egyenlőség) → a candidateId-match 0 jelöltet adna → 0 hit. Stringify → bit-azonos a findDataList-tel.
+        for (const doc of docs) {
+            doc._id = String(doc._id);
+        }
+        return docs;
     }
     /**
      * A Mongo-prefilter összeállítása (dsgn-005 §2.1/§2.2). A `scopePath.scopeId $in scopeIdSet`
@@ -57,9 +128,12 @@ class FAM_RetrievalCandidate_DataService {
         if (input.kindFilter) {
             filter.kind = input.kindFilter;
         }
-        // Soft-delete/aktív guard a `rules` táron (dsgn-001 §4): inaktív szabály SOHA nem jelölt.
+        // Soft-delete/aktív guard a `rules` táron (dsgn-001 §4): inaktív szabály SOHA nem jelölt. „Inaktív"
+        // = EXPLICIT `isActive:false`; a hiányzó/`true` mező AKTÍV (a `create` a bázis `FAM_Entry`-t menti,
+        // amin a per-tár `isActive:true` schema-default nem mindig perzisztálódik → `$ne:false` robusztus,
+        // hogy az újonnan írt szabály is jelölt legyen; csak a kézzel-deaktivált zárandó ki).
         if (registryEntry.table === fam_table_type_enum_1.FAM_Table.rules) {
-            filter.isActive = true;
+            filter.isActive = { $ne: false };
         }
         return filter;
     }