@futdevpro/fdp-agent-memory 1.1.137 → 1.1.153

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@futdevpro/fdp-agent-memory",
-    "version": "1.1.137",
+    "version": "1.1.153",
     "description": "Local-first, vector-backed multi-table agent memory exposed as an MCP server (read/write/capabilities). Public, FDP-Templates-free, no auth.",
     "private": false,
     "publishConfig": {

package/build/src/_collections/config-catalog.const.js

@@ -138,19 +138,49 @@ exports.CONFIG_CATALOG = {
         description: 'Minimum similarity-score küszöb (CCAP default 0 = nincs vágás).',
     },
     'read.hydrationWaitMs': {
-        type: 'number', default: 180000, min: 0, max: 600000, integer: true, levels: ALL_LEVELS,
+        type: 'number', default: 20000, min: 0, max: 600000, integer: true, levels: ALL_LEVELS,
         description: 'A readiness-coordinator hidratálás-bevárás felső korlátja ms-ban: a `read`/`search` MEGVÁRJA a '
             + 'tár pool-jának (kezdő VAGY újra-) hidratálását ahelyett, hogy `FAM-VEC-SEARCH-001 pool ÜRES`-t dobna. '
-            + '0 = nincs várakozás (azonnali hiba, ha még nem kész). Boot-kor a ~290k-vektor hidratálás percekig tarthat → '
-            + 'a default 180s ezt fedi; time-out után tiszta „még hidratál, próbáld újra" hiba (a következő hívás már kész).',
+            + '0 = nincs várakozás (azonnali hiba, ha még nem kész). '
+            + 'MÉRT INDOK a 20s-re (2026-08-22): a korábbi default 180s volt, ám EGYETLEN MCP-kliensnek sincs ilyen '
+            + 'hosszú tool-timeoutja (a Codex 60s-mal futott) — vagyis a szerver egy nem létező hívóra várt, és a '
+            + 'jól diagnosztizálható „a pool hidratál, 3/6 tár kész" állapotot ÁTLÁTHATATLAN kliens-oldali timeoutra '
+            + 'fordította. Egy agent három azonos újrapróbálkozással 3 percet égetett el úgy, hogy az okot SOHA nem '
+            + 'láthatta. 20s továbbra is elnyeli a rövid újra-hidratálási zökkenőt, de a TELJES hideg bootot (~120s) '
+            + 'már nem rejti el: azt a hívónak TUDNIA kell, hogy dönthessen (vár, vagy közben mást csinál). '
+            + 'A time-out hibája megmondja, mely tárak vannak még hátra. Aki a régi viselkedést akarja, állítsa vissza.',
+    },
+    'read.maxChunksPerFile': {
+        type: 'number', default: 2, min: 0, max: 50, integer: true, levels: ALL_LEVELS,
+        description: 'Fajlonkent legfeljebb ennyi chunk kerul a top-K elejere; a tobbi a lista vegere csuszik '
+            + '(0 = kikapcsolva, talalat SOHA nem vesz el). Mert indok (2026-08-22): a top-K slotok 44%-a ugyanannak '
+            + 'a fajlnak egy masik darabja volt, egy query-n a TELJES top-5 egyetlen fajlbol allt.',
+    },
+    'read.tableMinShare': {
+        type: 'number', default: 1, min: 0, max: 20, integer: true, levels: ALL_LEVELS,
+        description: 'Tobb-taras query-ben minden talalatot ado tar garantalt helye a top-K-ban (0 = kikapcsolva). '
+            + 'Mert indok (2026-08-22): kontrollalt teszten a rules tar 0/3 aranyban tunt el a documents mogott, '
+            + 'holott a csak-rules query azonnal hozta a kanonikus szabalyt.',
     },
     'read.relevanceFloor': {
-        type: 'number', default: 0.5, min: 0.0, max: 1.0, levels: ALL_LEVELS,
-        description: 'Confidence-padló a nyers cosine score-on: a relevancia-JELZÉSEK (totalRelevant / '
-            + 'denseResults / truncated / suggestions) CSAK az e fölötti hit-eket számolják „magabiztosan '
-            + 'relevánsnak". A returnedHits ettől függetlenül best-effort (recall). Ha a legjobb score is e '
-            + 'ALATT van → a read jelzi, hogy valószínűleg nincs lefedve (north-star). Modell-függő (qwen3 '
-            + 'zaj-padló ~0.44); állítsd a provider/modell szerint.',
+        type: 'number', default: 0.60, min: 0.0, max: 1.0, levels: ALL_LEVELS,
+        // PER-TÁR kalibráció (2026-08-14 MÉRÉS): a tárak score-tartománya ELTÉR — a `codebase`/`documents` szimbólum-
+        // és cím-egyezései magasabbra futnak (top 0.75-0.84), a `rules`/`memory` prózai egyezései alacsonyabbra
+        // (top 0.64-0.66). Egységes küszöbbel az egyik tár túl engedékeny, a másik túl szigorú lenne.
+        defaultsByTable: {
+            [fam_table_type_enum_1.FAM_Table.codebase]: 0.65,
+            [fam_table_type_enum_1.FAM_Table.documents]: 0.65,
+            // A `rules` korpusz ANGOL próza, a kérdések viszont jórészt MAGYARUL érkeznek → a cosine
+            // rendszeresen alacsonyabb. MÉRVE (8 valós, JÓ query): a 0.60-as floor mellett 4/8 query azt
+            // jelentette volna, hogy „0 magabiztos találat" — HOLOTT a helyes szabály a #1 volt. 0.52-nél 1/8.
+            [fam_table_type_enum_1.FAM_Table.rules]: 0.52,
+        },
+        description: 'Confidence-padló a NYERS cosine score-on: a relevancia-jelzések (`totalRelevant` / dense / '
+            + 'suggestions) alapja. **MÉRVE (2026-08-14):** a korábbi `0.5` a `memory` táron 500 tételt jelölt '
+            + '„magabiztosan relevánsnak" (a valódi egyezések 0.60 FÖLÖTT voltak) — a szám így nem információ volt, '
+            + 'hanem zaj, és a dense-jelzés is folyamatosan tüzelt. A `0.60` (codebase/documents `0.65`) a mért '
+            + 'eloszlásból jön. FONTOS: ez a jelzéseket kalibrálja, NEM dobja el a találatokat — a hit-eket a '
+            + '`read.minScore` szűri (best-effort recall marad).',
     },
     'read.importChunkWeight': {
         type: 'number', default: 0.4, min: 0.0, max: 1.0, levels: ALL_LEVELS,
@@ -160,6 +190,17 @@ exports.CONFIG_CATALOG = {
             + 'importChunkWeight` a definíció-chunkok ALÁ rangsorolja őket. READ-time (nincs re-embed); a nyers '
             + 'cosine score (relevancia-jelzések) NEM változik, csak a ranking. 1 = nincs csökkentés.',
     },
+    'read.weightInfluence': {
+        type: 'number', default: 0.06, min: 0.0, max: 1.0, levels: ALL_LEVELS,
+        description: 'A statikus `weight` BEFOLYÁSA a rangsorra (2026-08-14 lelet). A `finalScore` eddig LINEÁRISAN '
+            + 'szorzott a weight-tel, a koszinusz viszont csak ~0.3-0.8 között mozog — ezért egy `weight:5` tétel '
+            + 'MATEMATIKAILAG VERHETETLEN volt: mérve a `rules` táron 2 db w5-ös bejegyzés ült MINDEN szabály-keresés '
+            + 'tetején (score 0.519 × 5 = 2.595 vs. a helyes találat 0.621 × 1 = 0.742). Az effektív súly mostantól '
+            + '`1 + weightInfluence × (weight - 1)` — vagyis a weight DÖNTETLENT BONT (a kurált tartalom felé), de NEM '
+            + 'írja felül a szemantikai relevanciát. `0.12` → w5 ≈ 1.48 · w3 ≈ 1.24 · w2 ≈ 1.12. `1.0` = a régi, '
+            + 'lineáris viselkedés; `0` = a weight teljesen figyelmen kívül. Az azonos súlyú tételek egymáshoz '
+            + 'viszonyított sorrendje VÁLTOZATLAN (a tár-belső rangsort nem érinti).',
+    },
     'read.importSourceWeight': {
         type: 'number', default: 0.85, min: 0.0, max: 1.0, levels: ALL_LEVELS,
         description: 'Az import-FORRÁSÚ (`source.type:"import"`, pl. claude-mem-import) entry-k read-idejű rangsor-'
@@ -177,16 +218,14 @@ exports.CONFIG_CATALOG = {
             + '(régi viselkedés). Default 0.6.',
     },
     'read.scanSummaryWeight': {
-        type: 'number', default: 1.0, min: 0.0, max: 10.0, levels: ALL_LEVELS,
-        description: 'A `source.type:"scan-summary"` (auto-generált projekt-összefoglaló: `project-identity` + '
-            + '`fs-summary`) chunkok EFFEKTÍV statikus weight-SAPKÁJA read-időben (2026-07-26 dispatch-eval): e '
-            + 'generikus entry-k `weight:3` (project-identity) / `weight:2` (fs-summary) → `finalScore ~2.2` még '
-            + 'lexicalScore 0-0.2 mellett is elnyomta a szemantikailag+lexikailag relevánsabb doksikat. E cap a '
-            + 'scan-summary effektív weight-jét `min(weight, scanSummaryWeight)`-re szorítja (factor = cap/weight), '
-            + 'hogy a STATIKUS weight NE tudja legyőzni a relevanciát. `1.0` = tiszta relevancia-rangsor (nincs statikus '
-            + 'boost); az identity-jellegű query-ken a summary a MAGAS cosine-ja miatt így is felszínre kerül (nincs '
-            + 'regresszió). READ-time (nincs re-embed); a nyers cosine + a `weight` DTO-mező NEM változik, csak a ranking. '
-            + 'A stored weight ALÁ csökkenteni is lehet (<1) az agresszívabb leszorításhoz; ≥ stored weight = kikapcsolva.',
+        type: 'number', default: 0.8, min: 0, max: 10, levels: ALL_LEVELS,
+        description: 'A `scan-summary` forrasu bejegyzesek (fs-summary konyvtar-listak) EFFEKTIV suly-plafonja. '
+            + 'Ezek atlagosan ~22 000 karakteres fajlnev-listak `weight: 2`-vel, es mivel egy repo MINDEN fajlnevet '
+            + 'tartalmazzak, gyakorlatilag BARMIRE illeszkednek. Mert kalibracio (2026-08-22, 12 zaj- + 3 jogos '
+            + 'navigacios query): 1.0 eseten a top-K slotok 35%-a fs-summary szemet volt (2 query-n a TOP-1 is); '
+            + '0.9 eseten 20%; 0.8 eseten 5% UGY, hogy a jogos "mi van ebben a repoban" kerdes tovabbra is '
+            + '3/3-ban megtalalja; 0.7 alatt a zaj mar 0%, DE a jogos navigacio is romlani kezd (2/3, majd 1/3). '
+            + 'Ezert 0.8 az optimum. A cap a TEMPERALT (effectiveWeight) sulyra hat.',
     },
     'read.denseResultRatio': {
         type: 'number', default: 2.0, min: 1.0, max: 50.0, levels: ALL_LEVELS,

package/build/src/_collections/fam-agent-guidance.util.js

@@ -33,7 +33,7 @@ class FAM_AgentGuidance_Util {
     /** A `read` tool minimál, helyes hívása (a leggyakoribb szándék). */
     static READ_EXAMPLE = '{"queries":[{"tables":["knowledge"],"query":"amit keresel","topK":5}]}';
     /** A `write` tool minimál, helyes hívása. */
-    static WRITE_EXAMPLE = '{"operation":"create","table":"memory","content":"a megjegyzendő tudás","scopePath":[{"layer":"project","name":"<projekt>"}]}';
+    static WRITE_EXAMPLE = '{"operation":"create","table":"memory","content":"a megjegyzendő tudás","scopePath":[{"layer":"project","rawName":"<projekt>"}]}';
     /**
      * A JSON-parse hiba KONKRÉT okának felismerése a nyers body-ból (PURE). A body-parser üzenete önmagában
      * (`Expected property name or '}' at position 1`) egy agentnek keveset mond — a tényleges minta viszont

package/build/src/_collections/fam-mcp-bridge.util.js

@@ -34,16 +34,26 @@ class FAM_McpBridge_Util {
                 handler: async (args) => {
                     let result = await client.post(`/api/${tool.name}`, args ?? {});
                     // ÖNHEAL (user-FR 2026-06-22): ha a primary időközben leesett (`unreachable`), NE bukjunk némán —
-                    // automatikusan felhúzzuk a leválasztott primary-t (`ensureRunning`) és EGYSZER újrapróbáljuk. Ha a
-                    // primary épp bootol (pool-hidratálás), tiszta „indul, próbáld újra" hibát adunk (a következő hívás megy).
+                    // automatikusan felhúzzuk a leválasztott primary-t (`ensureRunning`) és EGYSZER újrapróbáljuk.
                     if (!result.ok && result.unreachable) {
                         const ensured = await serve_command_1.FAM_Serve_Util.ensureRunning();
                         if (ensured.running) {
                             result = await client.post(`/api/${tool.name}`, args ?? {});
                         }
                         else if (ensured.reason === 'boot-timeout') {
-                            throw new Error('FAM-MCP-BRIDGE-002: A FAM primary most indul (pool-hidratálás folyamatban) — '
-                                + 'próbáld újra pár másodperc múlva. (Az auto-indítás már elindult, leválasztva.)');
+                            throw new Error(`FAM-MCP-BRIDGE-002: ${await FAM_McpBridge_Util.bootHint(client)}`);
+                        }
+                        else {
+                            // A leválasztott indítás NEM sikerült (`no-entry` / `spawn-failed` / `remote-unreachable`).
+                            // Eddig ez a generikus „a REST-hívás sikertelen" ágra esett, amiből az agent NEM tudhatta meg,
+                            // hogy egyáltalán KELL egy szervert indítani, se azt, MIVEL (2026-08-22 owner-lelet).
+                            throw new Error(`FAM-MCP-BRIDGE-003: A FAM primary NEM fut, és az automatikus indítás sem `
+                                + `sikerült (ok: ${ensured.reason}; cél: ${ensured.url}). A FAM-nak szüksége van egy futó `
+                                + 'primary-ra — indítsd el KÉZZEL, egyszer, és utána minden MCP-hívás működik:  '
+                                + '`fam serve`  (állandó, leválasztott szerver; a session-öket túléli). '
+                                + 'Diagnózis: `fam doctor`, vagy `GET http://127.0.0.1:39265/api/health`. '
+                                + 'Ha a port foglalt egy fél-halott processzel, azt előbb állítsd le. '
+                                + 'Addig NE jelentsd a FAM-ot elérhetetlennek — a REST-felület ugyanezen a porton él.');
                         }
                     }
                     if (!result.ok) {
@@ -59,5 +69,36 @@ class FAM_McpBridge_Util {
         }
         await adapter.startStdio();
     }
+    /**
+     * A „most bootol" hibaüzenet ÉLŐ boot-állapottal. Mért indok (2026-08-22): a korábbi szöveg annyit mondott, hogy
+     * „próbáld újra pár másodperc múlva" — miközben a hideg boot MÉRVE ~70–120 s (~338k vektor / ~9 GB). Az agent ezt
+     * szó szerint vette, pár másodpercenként újrapróbált, végig bukott, és ebből arra jutott, hogy a FAM hibás. A
+     * „pár másodperc" tehát nem pontatlanság volt, hanem AKTÍVAN félrevezető: pont abba a mintába lökte, ami nem
+     * segíthet. Ezért az üzenet most (a) megmondja, hol tart a boot, (b) őszinte nagyságrendet ad, (c) a
+     * `/api/health`-re irányít a lekérdezés-ismételgetés HELYETT (`core-error-debuggable`).
+     */
+    static async bootHint(client) {
+        // A `client.get` NEM dob a nem-elérhető szerverre, hanem `ok:false`-t ad — ezért az „még nem lekérdezhető"
+        // ágat EXPLICITEN kezelni kell, különben a legkorábbi (leghidegebb) hívásnál épp a helyzet-információ marad ki.
+        let progress = ' (A boot-állapot még nem lekérdezhető — a REST-felület sem áll fel; ez a boot legelső '
+            + 'másodperceiben normális.)';
+        try {
+            const health = await client.get('/api/health');
+            const hydration = health.ok ? health.data?.hydration : undefined;
+            if (hydration) {
+                progress = ` Boot-állapot: ${hydration.hydratedTables ?? '?'}/${hydration.totalTables ?? '?'} tár kész`
+                    + `${hydration.pendingTables?.length ? ` — hátra van: ${hydration.pendingTables.join(', ')}` : ''}.`;
+            }
+        }
+        catch {
+            // marad az alapértelmezett „még nem lekérdezhető" szöveg
+        }
+        return 'A FAM primary MOST INDUL, a vektor-pool hidratál — az auto-indítás már elfutott (leválasztva), '
+            + `tehát NEKED nem kell szervert indítanod.${progress} `
+            + 'A hideg boot MÉRVE ~2 perc (~338 ezer vektor, ~9 GB), NEM „pár másodperc". '
+            + 'NE ismételgesd ezt a hívást — nézd a készenlétet: `GET http://127.0.0.1:39265/api/health` '
+            + '(`ready` + `hydration.pendingTables`), és addig dolgozz máson. '
+            + 'Ha előre el akarod kerülni ezt az ablakot, indítsd a FAM-ot a session ELEJÉN: `fam serve`.';
+    }
 }
 exports.FAM_McpBridge_Util = FAM_McpBridge_Util;

package/build/src/_modules/embedding/_services/fam-hydration-coordinator.control-service.js

@@ -103,9 +103,20 @@ class FAM_HydrationCoordinator_ControlService {
         const limitMs = timeoutMs ?? this.waitTimeoutMs;
         const ready = await this.raceWithTimeout(entry.promise, limitMs);
         if (!ready) {
-            throw this.hydrationError(table, `A tár hidratálása ${Math.round(limitMs / 1000)}s alatt nem fejeződött be `
-                + '(a pool-hidratálás folyamatban — boot-kor a nagy tárak percekig tarthatnak). Próbáld újra pár '
-                + 'másodperc múlva; a következő hívás már a kész poolt találja.');
+            // A hiba a TELJES boot-képet viszi (mely tárak készek / melyik van hátra). Mért indok (2026-08-22):
+            // e nélkül a hívó csak egy csupasz timeoutot lát, és nem tudja megkülönböztetni a „most bootol" és a
+            // „elromlott" esetet — egy agent emiatt háromszor ismételte ugyanazt a lekérdezést, majd HIBÁSAN arra
+            // jutott, hogy a FAM végig egészséges volt, és csak a saját kliens-plafonja kevés (`core-error-debuggable`).
+            const shot = this.snapshot();
+            const readyTables = shot.filter((s) => s.state === 'ready').map((s) => s.table);
+            const waiting = shot.filter((s) => s.state !== 'ready').map((s) => `${s.table}:${s.state}`);
+            throw this.hydrationError(table, `A tár hidratálása ${Math.round(limitMs / 1000)}s alatt nem fejeződött be. `
+                + `Boot-állapot: ${readyTables.length}/${shot.length} tár kész`
+                + `${waiting.length ? ` — hátra van: ${waiting.join(', ')}` : ''}. `
+                + 'Ez NEM hiba és NEM a te hívásod mérete: a pool-hidratálás fut (hideg boot-kor a nagy tárak '
+                + 'ÖSSZESEN percekig tartanak). NE ismételd ugyanazt a lekérdezést — várd meg a készenlétet a '
+                + '`GET /api/health` `ready` / `hydration.pendingTables` mezőin, VAGY dolgozz addig máson. '
+                + 'A várakozási korlát a `read.hydrationWaitMs` configgal állítható.');
         }
     }
     /** Egy tár aktuális állapota (diag / health / teszt). */

package/build/src/_modules/ingest/_services/fam-scan-job.control-service.js

@@ -379,6 +379,21 @@ class FAM_ScanJob_ControlService {
         return resumed;
     }
     /** A default per-projekt futtató: a meglévő `scan-project` write-handler az operation-queue-n át. */
+    /**
+     * Egy scan-cel kimenetenek OSZTALYOZASA (pure) — a nema elavulas elleni kapu.
+     *
+     * Mert lelet (2026-08-22): a heti re-scan HAROM egymast koveto heten (aug 3/10/17) bukott a `documentations` es az
+     * `OGS-projects\documents` mappakra, mert azokat atneveztek (`fdp-documentations` / `ogs-documents`), de a job
+     * cel-listaja a REGI utvonalat vitte tovabb. A runner viszont mindig `ok`-ot adott vissza, ha a hivas nem dobott —
+     * igy a job `53/53 ok`-kent zarult, es a FAM KET HONAPIG a juniusi doktrinat szolgalta ki ugy, hogy ez sehol nem
+     * latszott. A `filesProcessed: 0` ugyanezt jelenti egy letezo utvonalon (rossz include/exclude vagy tul ago ignore).
+     */
+    static classifyTargetOutcome(set) {
+        if (!set.pathExists) {
+            return 'missing-path';
+        }
+        return set.filesProcessed ? 'ok' : 'zero-files';
+    }
     async defaultRunProject(spec) {
         const startedAt = Date.now();
         // Per-target scope: az EXPLICIT `spec.scopePath` nyer (heterogén „scan-all"-hoz, pl. a memóriám root-szintű
@@ -401,11 +416,43 @@ class FAM_ScanJob_ControlService {
                 exclude: spec.exclude,
             },
         };
+        // ELO-ELLENORZES (2026-08-22, mert lelet): a heti re-scan HAROM egymast koveto heten (aug 3/10/17) NEMAN
+        // bukott a `documentations` / `OGS-projects\documents` mappakra — azokat atneveztek (`fdp-documentations` /
+        // `ogs-documents`), de a job-lista a REGI utvonalat vitte tovabb. A `defaultRunProject` viszont feltetel nelkul
+        // `ok`-ot adott vissza, ezert a job `53/53 ok`-kent zarult, es a FAM ket honapig a JUNIUSI doktrinat szolgalta ki
+        // ugy, hogy azt senki nem lathatta. A nem letezo cel-utvonal ezentul HANGOS hiba, nem zold pipa.
+        if (FAM_ScanJob_ControlService.classifyTargetOutcome({ pathExists: (0, fs_1.existsSync)(spec.path) }) === 'missing-path') {
+            return {
+                project: spec.project, path: spec.path, status: 'error',
+                seconds: Math.round((Date.now() - startedAt) / 1000),
+                error: {
+                    message: `A scan cel-utvonala NEM LETEZIK: '${spec.path}'. A mappat valoszinuleg atneveztek vagy `
+                        + 'athelyeztek — javitsd a scan-job cel-listajat, kulonben ez a forras NEMAN elavul.',
+                },
+            };
+        }
         try {
             const output = await fam_operation_queue_service_1.FAM_OperationQueue_Service.getInstance()
                 .enqueue(() => fam_write_tool_service_1.FAM_WriteTool_Service.getInstance().handle(input));
             const scan = output.scan;
             const verdicts = scan?.verdicts;
+            // NULLA feldolgozott fajl letezo utvonalon: a cel nem jarult hozza az indexhez (rossz include/exclude,
+            // ures mappa vagy tul ago ignore-minta). Ez NEM siker — kulonben ugyanaz a nema elavulas all elo, csak
+            // mas okbol. Hangos hiba, hogy a heti riport ranezesre megmutassa.
+            const outcome = FAM_ScanJob_ControlService.classifyTargetOutcome({
+                pathExists: true, filesProcessed: scan?.filesProcessed,
+            });
+            if (outcome === 'zero-files') {
+                return {
+                    project: spec.project, path: spec.path, status: 'error',
+                    filesProcessed: 0, chunks: scan?.chunks, verdicts: verdicts,
+                    seconds: Math.round((Date.now() - startedAt) / 1000),
+                    error: {
+                        message: `A scan NULLA fajlt dolgozott fel a letezo '${spec.path}' utvonalon — a cel nem `
+                            + 'jarult hozza az indexhez (ellenorizd az include/exclude + .famignore mintakat).',
+                    },
+                };
+            }
             return {
                 project: spec.project, path: spec.path, status: 'ok',
                 filesProcessed: scan?.filesProcessed, chunks: scan?.chunks, verdicts: verdicts,

package/build/src/_modules/mcp/_collections/fam-read-response-shape.util.js

@@ -33,7 +33,10 @@ class FAM_ReadResponseShape_Util {
             table: hit.table,
             // ÚTVONAL-SSOT: a `sourceFilePath` már a hívó `basePath`-jához igazított (rebaseToBasePath), különben az
             // abszolút út — így MINDIG feloldható. A régi mezőket lentebb megtartjuk (kompatibilitás).
-            path: hit.sourceFilePath ?? hit.absolutePath ?? null,
+            // Ha nincs fájl-forrás (API-n írt bejegyzés: manual/agent write), a `path` NEM maradhat néma `null` —
+            // az az agentnek zsákutca („itt egy találat, de nem tudom, hol van"). Helyette LOCATOR-t adunk, amivel
+            // a bejegyzés visszakereshető: `fam:<tár>/<id>` (2026-08-14 elő-próbálgatás lelete).
+            path: hit.sourceFilePath ?? hit.absolutePath ?? `fam:${hit.table}/${hit.id}`,
             score: round(hit.score),
             finalScore: round(hit.finalScore),
         };
@@ -124,12 +127,24 @@ class FAM_ReadResponseShape_Util {
                 + 'a javasolt út — a chat-választ nem terheli).');
         }
         if (set.totalRelevant > set.shown * 3 && !set.hasScopeFilter) {
-            hints.push('CÉLZOTTABBAN: szűkíts `scope`-pal (pl. `{"layer":"project","name":"<projekt>"}`), `tags`-szel '
+            hints.push('CÉLZOTTABBAN: szűkíts `scope`-pal (pl. `{"layer":"project","rawName":"<projekt>"}`), `tags`-szel '
                 + 'vagy `kind`-dal — a sok találat általában túl tág kérdést jelez.');
         }
         if (!set.totalRelevant) {
-            hints.push('NINCS magabiztos találat: próbálj más megfogalmazást/kulcsszavakat, vagy emeld a `topK`-t; '
-                + 'a `minScore: 0` a leggyengébb tippeket is visszaadja.');
+            // SZŰRŐ-SPECIFIKUS diagnózis (2026-08-14 battery-lelet): ha VAN aktív szűrő és NULLA a találat, akkor
+            // nagy eséllyel a SZŰRŐ ölte meg a keresést, nem a query. Korábban ilyenkor is azt tanácsoltuk, hogy
+            // „próbálj más megfogalmazást" — ez FÉLREVEZETŐ volt (mérve: ugyanaz a query szűrő nélkül 5 találatot
+            // adott). Az agentet a TÉNYLEGES okhoz kell terelni.
+            if (set.hasScopeFilter && !set.shown) {
+                hints.push('NULLA találat AKTÍV SZŰRŐVEL — nagy eséllyel a szűrő a szűk keresztmetszet, nem a kérdés. '
+                    + 'Próbáld a query-t szűrő NÉLKÜL (`scopeFilter`/`tagFilter`/`kindFilter` elhagyásával); ha úgy '
+                    + 'vannak találatok, a szűrő értéke hibás vagy nem létezik (a `tags`/`kind` szabad szövegűek, a '
+                    + 'scope-hoz a `{"layer":"…","rawName":"…"}` alak kell).');
+            }
+            else {
+                hints.push('NINCS magabiztos találat: próbálj más megfogalmazást/kulcsszavakat, vagy emeld a `topK`-t; '
+                    + 'a `minScore: 0` a leggyengébb tippeket is visszaadja.');
+            }
         }
         return hints;
     }

package/build/src/_modules/mcp/_services/fam-read-tool.service.js

@@ -237,7 +237,10 @@ class FAM_ReadTool_Service {
             });
         }
         for (const query of input.queries) {
-            if (!query || !Array.isArray(query.tables) || !query.tables.length || !query.query) {
+            // A `.trim()` SZANDEKOS (2026-08-22 robusztussag-lelet): a puszta `!query.query` csak az URES stringet
+            // fogta meg, ezert a csupa-szokoz query ATMENT a validacion, es a vektor-kereses ertelmetlen zajt adott
+            // vissza (egy meresen ~13k token egyetlen ertelmetlen keresesre).
+            if (!query || !Array.isArray(query.tables) || !query.tables.length || !query.query?.trim()) {
                 throw fam_error_factory_util_1.FAM_Error_Util.create({
                     errorCode: error_codes_const_1.FAM_ERROR_CODES.valReadEmptyOrReference,
                     message: 'Minden `read` query-nek legalább 1 `tables` elemet és egy nem-üres `query` '
@@ -246,6 +249,44 @@ class FAM_ReadTool_Service {
                     context: { operation: 'read-validate' },
                 });
             }
+            // ISMERETLEN TÁR (2026-08-14 battery-lelet): eddig egy ELGÉPELT tárnév NÉMÁN 0 találatot adott (HTTP 200)
+            // — az agent ebből azt a HAMIS következtetést vonja le, hogy „nincs ilyen tudás". Ez a legrosszabb hiba-fajta:
+            // csendes, téves válasz. Mostantól EXPLICIT hiba, a MEGENGEDETT tárak felsorolásával.
+            const known = Object.values(fam_table_type_enum_1.FAM_Table);
+            const unknown = query.tables.filter((table) => !known.includes(table));
+            if (unknown.length) {
+                throw fam_error_factory_util_1.FAM_Error_Util.create({
+                    errorCode: error_codes_const_1.FAM_ERROR_CODES.valReadEmptyOrReference,
+                    message: `Ismeretlen tár: ${unknown.map((t) => `'${t}'`).join(', ')}. `
+                        + `Megengedett: ${known.filter((t) => t !== fam_table_type_enum_1.FAM_Table.reference).join(' | ')}. `
+                        + '(Elgépelés? A `capabilities` action:"list" felsorolja a tárakat és a pontos sémákat.)',
+                    issuer: this.issuer,
+                    context: { operation: 'read-validate' },
+                });
+            }
+            // topK/minScore TARTOMÁNY (2026-08-14 battery-lelet): a `topK: -5` eddig egy NYERS TypeError-t okozott
+            // (`Cannot read properties of undefined (reading 'finalScore')`) — kezeletlen összeomlás, kriptikus üzenettel.
+            // A FELSO hatar is ELLENORZOTT (2026-08-22): a hibauzenet eddig is „1 es 200 kozotti" erteket igert, de a
+            // kod a `topK: 10000`-t elfogadta — a szerzodes es a viselkedes szetcsuszott, es a hivo context-bombat kapott.
+            if (query.topK !== undefined
+                && (!Number.isFinite(query.topK) || query.topK < 1 || query.topK > retrieval_1.MAX_PAGE_SIZE)) {
+                throw fam_error_factory_util_1.FAM_Error_Util.create({
+                    errorCode: error_codes_const_1.FAM_ERROR_CODES.valReadEmptyOrReference,
+                    message: `A \`topK\` 1 és ${retrieval_1.MAX_PAGE_SIZE} közötti egész szám kell legyen `
+                        + `(kapott: ${String(query.topK)}). Hagyd el a mezőt a tár-alapú default-hoz.`,
+                    issuer: this.issuer,
+                    context: { operation: 'read-validate' },
+                });
+            }
+            if (query.minScore !== undefined && (!Number.isFinite(query.minScore) || query.minScore < 0 || query.minScore > 1)) {
+                throw fam_error_factory_util_1.FAM_Error_Util.create({
+                    errorCode: error_codes_const_1.FAM_ERROR_CODES.valReadEmptyOrReference,
+                    message: `A \`minScore\` 0 és 1 közötti szám kell legyen (kapott: ${String(query.minScore)}) — `
+                        + 'ez a NYERS koszinusz-küszöb. `0` = mindent visszaad (best-effort recall).',
+                    issuer: this.issuer,
+                    context: { operation: 'read-validate' },
+                });
+            }
             if (query.tables.includes(fam_table_type_enum_1.FAM_Table.reference)) {
                 throw fam_error_factory_util_1.FAM_Error_Util.create({
                     errorCode: error_codes_const_1.FAM_ERROR_CODES.valReadEmptyOrReference,
@@ -278,6 +319,8 @@ class FAM_ReadTool_Service {
             kindFilter: query.kindFilter,
             excludeIds: query.excludeIds,
             depth: query.depth,
+            // Per-query tartalom-kapcsolo atvezetese (2026-08-14 lelet: eddig itt VESZETT EL).
+            includeContent: query.includeContent,
         };
     }
 }

package/build/src/_modules/mcp/_services/fam-write-tool.service.js

@@ -163,6 +163,29 @@ class FAM_WriteTool_Service {
                 context: { operation: 'write-validate', table: input.table },
             });
         }
+        // WEIGHT / IMPORTANCE TARTOMANY (2026-08-22 robusztussag-meres): a `weight: -5` eddig NEMAN atment
+        // (`warnings: []`), es a bejegyzes ezzel VEGLEG visszakereshetetlenne valt — a `finalScore = score x weight`
+        // negativba fordul, igy a talalat SOHA nem rangsorolhat, meg a sajat egyedi markerere + tagjere sem. Az agent
+        // ebbol azt latja, hogy „az iras sikerult, de a tartalom nincs meg" — a legrosszabb fajta nema adatvesztes.
+        if (input.weight !== undefined && (!Number.isFinite(input.weight) || input.weight <= 0)) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.valWriteMissingField,
+                message: `A \`weight\` POZITIV szam kell legyen (kapott: ${String(input.weight)}). A rangsor `
+                    + '`score x weight` szorzat, ezert a 0 vagy negativ suly a bejegyzest VEGLEG '
+                    + 'visszakereshetetlenne teszi. Alap: 1 (coding_patterns: 5).',
+                issuer: this.issuer,
+                context: { operation: 'write-validate', table: input.table },
+            });
+        }
+        if (input.importance !== undefined
+            && (!Number.isFinite(input.importance) || input.importance < 0 || input.importance > 1)) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.valWriteMissingField,
+                message: `Az \`importance\` 0 es 1 kozotti szam kell legyen (kapott: ${String(input.importance)}).`,
+                issuer: this.issuer,
+                context: { operation: 'write-validate', table: input.table },
+            });
+        }
         const needsTarget = input.operation === fam_mcp_interface_1.FAM_WriteOperation.update || input.operation === fam_mcp_interface_1.FAM_WriteOperation.delete;
         if (needsTarget && (!input.target || !input.target.by || !input.target.value)) {
             throw fam_error_factory_util_1.FAM_Error_Util.create({

package/build/src/_modules/retrieval/_collections/fam-lexical-match.util.js

@@ -24,19 +24,44 @@ class FAM_LexicalMatch_Util {
         'az', 'és', 'es', 'hogy', 'van', 'egy', 'nem', 'igen', 'de', 'mert', 'ami', 'amit', 'ez', 'azt', 'volt',
         'lesz', 'kell', 'meg', 'el', 'be', 'ki', 'le', 'fel', 'rá', 'ra', 'mi', 'te', 'ő', 'mit', 'hol',
     ]);
+    /** A magyar ragok HOSSZ szerint csökkenő sorrendben (a leghosszabb egyezés nyer — `-ból` előbb, mint `-ó`). */
+    static HU_SUFFIXES = [
+        'ban', 'ben', 'ból', 'ből', 'nak', 'nek', 'val', 'vel', 'hoz', 'hez', 'höz', 'ról', 'ről', 'tól', 'től',
+        'ot', 'et', 'öt', 'at', 'ok', 'ek', 'ök', 'ak', 'ra', 're', 'ig', 'ba', 'be', 'on', 'en', 'ön', 'an',
+    ];
+    /** A tő MINIMÁLIS hossza tövezés után (a túl-tövezés hamis egyezéseket hozna). */
+    static MIN_STEM_LEN = 4;
     /** Tokenizálás: kisbetűsít, nem-alfanumerikuson tör, stopword + rövid token kihagyva, DEDUP (Set). */
     static tokenize(text) {
         const terms = new Set();
         if (!text) {
             return terms;
         }
-        for (const raw of text.toLowerCase().split(/[^a-z0-9]+/)) {
-            if (raw.length >= FAM_LexicalMatch_Util.MIN_TOKEN_LEN && !FAM_LexicalMatch_Util.STOPWORDS.has(raw)) {
-                terms.add(raw);
+        // ÉKEZET-JAVÍTÁS (2026-08-14 lelet): a korábbi `[^a-z0-9]+` split a magyar ékezetes betűket ELVÁLASZTÓNAK
+        // vette, ezért minden ékezetes szó SZÉTESETT („szabály" → „szab" + „ly", „mérés" → „m" + „r" + „s").
+        // Így a magyar query-k lexikai jele gyakorlatilag ELVESZETT.
+        for (const raw of text.toLowerCase().split(/[^a-z0-9áéíóöőúüű]+/)) {
+            if (raw.length < FAM_LexicalMatch_Util.MIN_TOKEN_LEN || FAM_LexicalMatch_Util.STOPWORDS.has(raw)) {
+                continue;
             }
+            terms.add(raw);
         }
         return terms;
     }
+    /**
+     * Magyar toldalék levágása (PURE) — a tő, ha a levágás UTÁN is értelmes hosszúságú marad, különben `undefined`.
+     * A leggyakoribb rag-osztályok: tárgyeset (`-t`/`-ot`/`-et`/`-öt`/`-at`), többes (`-ok`/`-ek`/`-ök`/`-ak`),
+     * hely-/eszközhatározók (`-ban`/`-ben`/`-ból`/`-ből`/`-ra`/`-re`/`-val`/`-vel`/`-nak`/`-nek`/`-hoz`/`-hez`/`-ig`).
+     * A `MIN_STEM_LEN` védi a túl-tövezéstől (pl. `este` → `est` nem keletkezik hamis egyezésként).
+     */
+    static stripHungarianSuffix(token) {
+        for (const suffix of FAM_LexicalMatch_Util.HU_SUFFIXES) {
+            if (token.length - suffix.length >= FAM_LexicalMatch_Util.MIN_STEM_LEN && token.endsWith(suffix)) {
+                return token.slice(0, token.length - suffix.length);
+            }
+        }
+        return undefined;
+    }
     /**
      * Lexikai átfedés-score (0..1): a `queryTerms` hányad része van jelen az entry kereshető szövegében.
      * `content`-egyezés = base-átfedés; `headingPath`/`sourceFilePath`-egyezés = + `TITLE_PATH_BONUS` súly (1-re vágva).
@@ -52,8 +77,14 @@ class FAM_LexicalMatch_Util {
         let baseMatched = 0;
         let titleMatched = 0;
         for (const term of queryTerms) {
-            const inTitlePath = titlePathTerms.has(term);
-            if (contentTerms.has(term) || inTitlePath) {
+            // MAGYAR TOLDALÉK-ILLESZTÉS (2026-08-14): a magyar az ANGOL szakszavakat is ragozza („loopot",
+            // „scriptet", „branchról"), így a nyers `loopot` SOHA nem egyezett a dokumentum `loop` szavával — mérve:
+            // a „mikor kell review loopot futtatni" query 5 tokenjéből EGY egyezett. A tő ILLESZTÉSI SEGÉD, NEM külön
+            // query-term: nem növeli a nevezőt (különben az angol szavak téves tövezése — `convention` → `conventi` —
+            // HÍGÍTANÁ a score-t), csak egy MÁSODIK esélyt ad ugyanannak a tokennek az egyezésre.
+            const stem = FAM_LexicalMatch_Util.stripHungarianSuffix(term);
+            const inTitlePath = titlePathTerms.has(term) || (!!stem && titlePathTerms.has(stem));
+            if (contentTerms.has(term) || (!!stem && contentTerms.has(stem)) || inTitlePath) {
                 baseMatched++;
             }
             if (inTitlePath) {

package/build/src/_modules/retrieval/_collections/fam-result-diversity.util.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ResultDiversity_Util = void 0;
+/**
+ * `FAM_ResultDiversity_Util` — a visszaadott top-K **információ-sűrűségét** védi. Két MÉRT hibát javít
+ * (dogfood-mérés, 2026-08-22):
+ *
+ * 1. **Chunk-elárasztás:** a top-K slotok **44%-a** (11/25 mérve) UGYANANNAK a fájlnak egy másik chunkja volt —
+ *    a „polling tilalom" query-nél a TELJES top-5 EGYETLEN fájl darabjaiból állt. Az agent így egy dokumentumot
+ *    kap ötször, öt különböző válasz-jelölt helyett.
+ * 2. **Tár-temetés:** több-táras query-ben a `rules` **0/3** arányban tűnt el a `documents` mögött (kontrollált
+ *    mérés: ugyanaz a query csak-`rules`-szal AZONNAL hozta a kanonikus szabályt) — a bőbeszédűbb tár egyszerűen
+ *    kiszorítja a tömörebbet, és az agent azt hiszi, nincs rá szabály.
+ *
+ * **Sosem DOBUNK el találatot** (a recall szent): a levágott chunkok a lista VÉGÉRE kerülnek (demote, nem drop),
+ * így a `totalRelevant` és a `truncated` statisztika érintetlen marad. A `pinned` (kód-exact citáció) hitek
+ * mozdíthatatlanok — az F3-1 garancia elsőbbséget élvez a diverzitással szemben.
+ */
+class FAM_ResultDiversity_Util {
+    /** Legfeljebb ennyi promóciót engedünk a tár-kvótának, hogy a rangsor ne forduljon fel (window fele). */
+    static MAX_PROMOTION_RATIO = 0.5;
+    /**
+     * A fájl-identitás kulcsa. A scan-chunkok `absolutePath`-ja a kanonikus kulcs; ha nincs (memory/knowledge
+     * bejegyzés, ami nem fájlból jött), akkor az `id` — így minden ilyen entry EGYEDI marad, és a chunk-collapse
+     * nem nyúl hozzájuk (nincs mit összevonni).
+     */
+    static fileKey(hit) {
+        return hit.absolutePath || hit.sourceFilePath || `id:${hit.id}`;
+    }
+    /**
+     * Diverzifikálja a RENDEZETT találati listát: (a) fájlonként legfeljebb `maxChunksPerFile` chunk kerül előre,
+     * (b) minden kért tár, amelynek VAN találata, kap legalább `tableMinShare` helyet az első `windowSize`-ban.
+     * A `pinned` hitek sorrendje és tagsága garantáltan változatlan.
+     */
+    static diversify(set) {
+        const pinned = set.isPinned || (() => false);
+        if (set.hits.length <= 1) {
+            return set.hits;
+        }
+        const collapsed = this.collapseChunks(set.hits, set.maxChunksPerFile, pinned);
+        return this.enforceTableShare(collapsed, set.tableMinShare, set.windowSize, pinned);
+    }
+    /**
+     * (a) Chunk-collapse: fájlonként az első `max` chunk marad a helyén, a többi a lista végére csúszik. `max <= 0`
+     * → kikapcsolva (a hívó config-ból tilthatja).
+     */
+    static collapseChunks(hits, max, pinned) {
+        if (max <= 0) {
+            return hits;
+        }
+        const kept = [];
+        const demoted = [];
+        const perFile = new Map();
+        for (const hit of hits) {
+            // A kód-exact citáció (F3-1) MINDIG marad — a determinisztikus garancia erősebb a diverzitásnál.
+            if (pinned(hit)) {
+                kept.push(hit);
+                continue;
+            }
+            const key = this.fileKey(hit);
+            const seen = perFile.get(key) || 0;
+            if (seen < max) {
+                perFile.set(key, seen + 1);
+                kept.push(hit);
+            }
+            else {
+                demoted.push(hit);
+            }
+        }
+        return kept.concat(demoted);
+    }
+    /**
+     * (b) Tár-kvóta: ha egy kért tárnak van találata, de az első `windowSize`-ban kevesebb, mint `minShare`, akkor a
+     * legjobb helyezésű ilyen találatát ELŐRE hozzuk a window UTOLSÓ (nem-pinned) helyére — minimális bolygatással,
+     * a kiszorult elem eggyel hátrébb csúszik (nem esik ki a listából).
+     */
+    static enforceTableShare(hits, minShare, windowSize, pinned) {
+        if (minShare <= 0 || windowSize <= 0 || hits.length <= windowSize) {
+            return hits;
+        }
+        const result = hits.slice();
+        const maxPromotions = Math.max(1, Math.floor(windowSize * this.MAX_PROMOTION_RATIO));
+        let promotions = 0;
+        // A tárak sorrendje a LEGJOBB helyezésük szerint — a leginkább „majdnem befért" tár kap előbb kvótát.
+        for (const table of this.tablesByBestRank(result)) {
+            if (promotions >= maxPromotions) {
+                break;
+            }
+            const inWindow = result.slice(0, windowSize).filter((hit) => hit.table === table).length;
+            if (inWindow >= minShare) {
+                continue;
+            }
+            const donorIndex = result.findIndex((hit, index) => index >= windowSize && hit.table === table);
+            if (donorIndex < 0) {
+                continue;
+            }
+            // A window utolsó NEM-pinned helye a beszúrási pont; ha minden hely pinned, nem bolygatunk.
+            const slot = this.lastUnpinnedSlot(result, windowSize, pinned);
+            if (slot < 0) {
+                break;
+            }
+            const [promoted] = result.splice(donorIndex, 1);
+            result.splice(slot, 0, promoted);
+            promotions++;
+        }
+        return result;
+    }
+    /** A találati listában szereplő tárak, a LEGJOBB (legkisebb indexű) helyezésük szerint rendezve. */
+    static tablesByBestRank(hits) {
+        const bestRank = new Map();
+        hits.forEach((hit, index) => {
+            if (!bestRank.has(hit.table)) {
+                bestRank.set(hit.table, index);
+            }
+        });
+        return Array.from(bestRank.entries()).sort((a, b) => a[1] - b[1]).map((entry) => entry[0]);
+    }
+    /** A window utolsó nem-pinned indexe (ide szúrjuk a promótált hitet), vagy `-1` ha minden hely pinned. */
+    static lastUnpinnedSlot(hits, windowSize, pinned) {
+        for (let index = windowSize - 1; index >= 0; index--) {
+            if (!pinned(hits[index])) {
+                return index;
+            }
+        }
+        return -1;
+    }
+}
+exports.FAM_ResultDiversity_Util = FAM_ResultDiversity_Util;

package/build/src/_modules/retrieval/_services/fam-retrieval-suggestions.util.js

@@ -14,6 +14,8 @@ const TAG_FREQUENCY_RATIO = 0.4;
  * feltételhez kötött (graceful: a hiányzó statisztikájú javaslat KIMARAD, nem hiba — dsgn-005 §kockázat).
  */
 class FAM_RetrievalSuggestions_Util {
+    /** A topK-javaslat abszolut plafonja — e folott a javaslat kontextus-bombava valik (2026-08-22 meres). */
+    static SUGGEST_TOPK_CAP = 25;
     /**
      * A teljes, rendezett javaslat-lista (dsgn-005 §4.4). A sorrend kötött (scope → tag → minScore →
      * topK → kind). Üres relevantSet → `[]`. A scope/tag/kind a relevantSet eloszlásából; a minScore a
@@ -147,8 +149,18 @@ class FAM_RetrievalSuggestions_Util {
             return undefined;
         }
         const totalRelevant = input.relevantSet.length;
-        const suggested = Math.min(totalRelevant, input.maxPageSize);
-        return `emeld a topK-t ${suggested}-re a teljes releváns halmazért (totalRelevant=${totalRelevant})`;
+        // MERSEKELT lepes, NEM „hozd be az egeszet" (2026-08-22, negy fuggetlen agent-meres): a javaslat korabban a
+        // teljes relevans halmazt ajanlotta (merve: `topK: 859`, `906`, `674`), ami (a) kontextus-bomba — egy agent a
+        // tanacsot kovetve tobb tizezer tokent egetett el —, es (b) TELJESITHETETLEN: a `topK: 859` valojaban 77
+        // talalatot adott, mire a valasz a hivo `topK`-jat okolta a vagasert. Ezert: legfeljebb a jelenlegi ablak
+        // haromszorosa, `SUGGEST_TOPK_CAP`-re vagva, es a content-kikapcsolas tanacsaval egyutt.
+        const step = Math.min(totalRelevant, Math.max(input.effectiveTopK * 3, input.effectiveTopK + 1), FAM_RetrievalSuggestions_Util.SUGGEST_TOPK_CAP, input.maxPageSize);
+        if (step <= input.effectiveTopK) {
+            return undefined;
+        }
+        return `emeld a topK-t ${step}-re a kovetkezo adagert (a kuszob felett osszesen ${totalRelevant} elem van — `
+            + 'ezt NE probald egyben lekerni; ha tobb kell, lapozz tovabb, es tartsd `includeContent: false`-on, '
+            + 'amig ki nem valasztottad, melyik talalat kell tartalommal)';
     }
     /**
      * kindFilter-javaslat (dsgn-005 §4.4 #5): csak ha a relevantSet ≥2 különböző `kind`-ot tartalmaz

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FAM_Retrieval_ControlService = void 0;
+exports.FAM_Retrieval_ControlService = exports.MAX_PAGE_SIZE = void 0;
 const fam_table_type_enum_1 = require("../../../_enums/fam-table.type-enum");
 const fam_reference_code_util_1 = require("../../../_collections/fam-reference-code.util");
 const config_control_service_1 = require("../../../_routes/server/config/config.control-service");
@@ -10,10 +10,11 @@ const fam_retrieval_candidate_data_service_1 = require("./fam-retrieval-candidat
 const fam_retrieval_suggestions_util_1 = require("./fam-retrieval-suggestions.util");
 const fam_memory_activation_util_1 = require("../_collections/fam-memory-activation.util");
 const fam_lexical_match_util_1 = require("../_collections/fam-lexical-match.util");
+const fam_result_diversity_util_1 = require("../_collections/fam-result-diversity.util");
 const fam_memory_reactivation_control_service_1 = require("./fam-memory-reactivation.control-service");
 const fam_memory_cold_search_control_service_1 = require("./fam-memory-cold-search.control-service");
 /** A topK / lapozás abszolút plafonja (CCAP MAX_PAGE_SIZE=500; dsgn-005 §6). */
-const MAX_PAGE_SIZE = 500;
+exports.MAX_PAGE_SIZE = 500;
 /**
  * `FAM_Retrieval_ControlService` (MP-5, dsgn-005) — a `read` **egylépcsős** retrieval-pipeline ENGINE-je.
  * Singleton. Egy hívás több táblát + több query-t kezel; minden query ÖNÁLLÓ, kötött-sorrendű
@@ -60,7 +61,10 @@ class FAM_Retrieval_ControlService {
     async read(request) {
         const includeContent = request.includeContent !== false;
         // Per-query párhuzamosítható pipeline-ok (egymástól függetlenek; dsgn-005 §2).
-        const results = await Promise.all(request.queries.map((query) => this.runQuery(query, includeContent, request.globalScopeFilter)));
+        const results = await Promise.all(
+        // A QUERY sajat `includeContent`-je NYER a request-szintu felett (2026-08-14 lelet: eddig a query-szintu
+        // ertek nemán elnyelodott, ezert a „kompakt lista" szandeku hivas teljes tartalmat adott vissza).
+        request.queries.map((query) => this.runQuery(query, query.includeContent !== undefined ? query.includeContent !== false : includeContent, request.globalScopeFilter)));
         return { results: results };
     }
     /**
@@ -80,7 +84,9 @@ class FAM_Retrieval_ControlService {
         const queryVector = await this.embedQuery(query.query, primaryTable);
         // ②–④ per-tár: Mongo-prefilter → vektor-keresés a szűkített poolon → hit-row összefűzés.
         const allHits = [];
-        for (const table of query.tables) {
+        // TÁR-DEDUP (2026-08-14 battery-lelet): a `tables:['rules','rules']` KÉTSZER futtatta ugyanazt a keresést
+        // (mérve: 1036ms vs 558ms) — azonos eredményért dupla vektor-munka. A dedup után a hívó hibája ingyenes.
+        for (const table of Array.from(new Set(query.tables))) {
             const tableHits = await this.searchTable({ table, query, queryVector, scopeExpand, config, includeContent });
             allHits.push(...tableHits);
         }
@@ -270,7 +276,7 @@ class FAM_Retrieval_ControlService {
             vectorHits = await embedding_1.FAM_VectorSearch_ControlService.getInstance().search({
                 table: set.table,
                 queryVector: set.queryVector,
-                topK: MAX_PAGE_SIZE,
+                topK: exports.MAX_PAGE_SIZE,
             });
             if (!vectorHits.length) {
                 return [];
@@ -306,7 +312,7 @@ class FAM_Retrieval_ControlService {
                 table: set.table,
                 queryVector: set.queryVector,
                 candidateIds: candidateIds,
-                topK: Math.min(candidateIds.length, MAX_PAGE_SIZE),
+                topK: Math.min(candidateIds.length, exports.MAX_PAGE_SIZE),
             });
         }
         // ⑤ weight-szorzó: finalScore = score × (weight ?? 1); weight ≤ 0 → kizárt (nem kerül a hits közé).
@@ -408,11 +414,13 @@ class FAM_Retrieval_ControlService {
      * → tiszta relevancia-rangsor; az identity-query-ken a summary a MAGAS cosine miatt így is felszínre kerül. Minden
      * NEM-scan-summary source érintetlen (×1). READ-time, a nyers `score` (relevancia) változatlan.
      */
-    scanSummaryFactor(source, weight, scanSummaryWeight) {
-        if (source?.type !== 'scan-summary' || weight <= scanSummaryWeight) {
+    scanSummaryFactor(source, effective, scanSummaryWeight) {
+        // FONTOS (2026-08-14): a cap a TEMPERÁLT (effektív) súlyra vonatkozik, nem a nyersre — különben a
+        // `effectiveWeight` és a cap KÉTSZER vonná le ugyanazt (mérve: w3 → 1.24 × 0.333 = 0.41 a kívánt 1.0 helyett).
+        if (source?.type !== 'scan-summary' || effective <= scanSummaryWeight) {
             return 1;
         }
-        return scanSummaryWeight / weight;
+        return scanSummaryWeight / effective;
     }
     /**
      * Memory Activation Model decay-szorzó (dsgn-013 §3) — CSAK a `memory` táron, ha engedélyezett. A frissen/gyakran
@@ -453,7 +461,7 @@ class FAM_Retrieval_ControlService {
         // finalScore = score × weight × chunkF × sourceF × decayF × (1 + keywordWeight × lexicalScore).
         const chunkFactor = this.chunkTypeFactor(set.entry.chunkType, set.importChunkWeight);
         const sourceFactor = this.importSourceFactor(set.entry.source, set.importSourceWeight);
-        const summaryFactor = this.scanSummaryFactor(set.entry.source, set.weight, set.config.scanSummaryWeight);
+        const summaryFactor = this.scanSummaryFactor(set.entry.source, FAM_Retrieval_ControlService.effectiveWeight(set.weight, set.config.weightInfluence), set.config.scanSummaryWeight);
         const decayFactor = this.memoryDecayFactor(set.entry, set.table, set.config, set.nowMs);
         const lexicalScore = set.config.keywordWeight > 0
             ? fam_lexical_match_util_1.FAM_LexicalMatch_Util.score(set.queryTerms, {
@@ -466,7 +474,7 @@ class FAM_Retrieval_ControlService {
             table: set.table,
             score: set.vectorHit.score,
             weight: set.weight,
-            finalScore: set.vectorHit.score * set.weight * chunkFactor * sourceFactor * summaryFactor * decayFactor * keywordBoost,
+            finalScore: set.vectorHit.score * FAM_Retrieval_ControlService.effectiveWeight(set.weight, set.config.weightInfluence) * chunkFactor * sourceFactor * summaryFactor * decayFactor * keywordBoost,
             lexicalScore: lexicalScore,
             content: set.includeContent ? set.entry.content : undefined,
             contentHash: set.entry.contentHash,
@@ -485,6 +493,18 @@ class FAM_Retrieval_ControlService {
             lastModifiedMs: lastModified ? new Date(lastModified).getTime() : 0,
         };
     }
+    /**
+     * A statikus `weight` TEMPERÁLT (effektív) értéke (PURE, 2026-08-14 lelet). A `finalScore` eddig LINEÁRISAN
+     * szorzott a weight-tel, a koszinusz viszont csak ~0.3-0.8 között mozog — így egy `weight:5` tétel
+     * MATEMATIKAILAG VERHETETLEN volt. Mérve a `rules` táron: 2 db w5-os bejegyzés ült MINDEN szabály-keresés
+     * tetején (0.519 × 5 = 2.595, míg a HELYES találat 0.621 × 1 = 0.742) — a súly ELNYOMTA a relevanciát.
+     * Mostantól `1 + influence × (weight - 1)`: a weight DÖNTETLENT BONT a kurált tartalom felé, de nem ír felül
+     * egy tisztán jobb szemantikai egyezést. Az AZONOS súlyú tételek sorrendje VÁLTOZATLAN. `influence:1` = a régi
+     * lineáris viselkedés, `0` = a weight figyelmen kívül. A `weight <= 0` (KIZÁRÁS) érintetlen marad.
+     */
+    static effectiveWeight(weight, influence) {
+        return weight <= 0 ? weight : 1 + influence * (weight - 1);
+    }
     /**
      * A `rules` tár per-tár metaadatai a hit-en (`category`/`isActive`/`applicableScopes`) — FEAT-005/006 P1:
      * a zóna-alapú aktív-rule kezelés alapja, hogy a hívó/hook a keresési hit-ből is lássa, MI aktív + mely
@@ -592,7 +612,17 @@ class FAM_Retrieval_ControlService {
         // query-n `#codeExact = 0` → `effectiveTopK = topK` (változatlan viselkedés).
         const codeExactCount = set.relevantSet.filter((hit) => this.codeExactRank(hit)).length;
         const effectiveTopK = Math.max(set.config.topK, codeExactCount);
-        const returnedHits = set.relevantSet.slice(0, effectiveTopK);
+        // Diverzitas (dogfood 2026-08-22): a top-K slotok 44%-a ugyanannak a fajlnak masik chunkja volt, es tobb-taras
+        // query-ben a `rules` 0/3 aranyban tunt el a `documents` mogott. A demote SOHA nem dob el talalatot, ezert a
+        // `confidentSet`/`totalRelevant` statisztika (lentebb, a teljes halmazon) valtozatlan marad.
+        const diversified = fam_result_diversity_util_1.FAM_ResultDiversity_Util.diversify({
+            hits: set.relevantSet,
+            maxChunksPerFile: set.config.maxChunksPerFile,
+            tableMinShare: set.query.tables.length > 1 ? set.config.tableMinShare : 0,
+            windowSize: effectiveTopK,
+            isPinned: (hit) => !!this.codeExactRank(hit),
+        });
+        const returnedHits = diversified.slice(0, effectiveTopK);
         // Magabiztosan releváns halmaz: a nyers cosine `score` (NEM finalScore — a weight ranking-boost, nem
         // relevancia) a `relevanceFloor` felett. A relevantSet rendezett, ezért a confidentSet is.
         const confidentSet = set.relevantSet.filter((hit) => hit.score >= set.config.relevanceFloor);
@@ -646,7 +676,7 @@ class FAM_Retrieval_ControlService {
             query: set.query,
             effectiveTopK: set.effectiveTopK,
             truncated: set.truncated,
-            maxPageSize: MAX_PAGE_SIZE,
+            maxPageSize: exports.MAX_PAGE_SIZE,
         });
     }
     // =========================================================================
@@ -669,13 +699,16 @@ class FAM_Retrieval_ControlService {
             ? await this.resolveNumber(config, 'read.deepTopK', ctx, 25)
             : await this.resolveNumber(config, 'read.topK', ctx, 5));
         const minScore = query.minScore ?? await this.resolveNumber(config, 'read.minScore', ctx, 0);
-        const relevanceFloor = await this.resolveNumber(config, 'read.relevanceFloor', ctx, 0.5);
+        const relevanceFloor = await this.resolveNumber(config, 'read.relevanceFloor', ctx, 0.60);
         const importChunkWeight = await this.resolveNumber(config, 'read.importChunkWeight', ctx, 0.4);
         const importSourceWeight = await this.resolveNumber(config, 'read.importSourceWeight', ctx, 0.85);
-        const scanSummaryWeight = await this.resolveNumber(config, 'read.scanSummaryWeight', ctx, 1.0);
+        const scanSummaryWeight = await this.resolveNumber(config, 'read.scanSummaryWeight', ctx, 0.8);
         const keywordWeight = await this.resolveNumber(config, 'read.keywordWeight', ctx, 0.6);
+        const weightInfluence = await this.resolveNumber(config, 'read.weightInfluence', ctx, 0.06);
         const denseResultRatio = await this.resolveNumber(config, 'read.denseResultRatio', ctx, 2.0);
         const denseResultAbsMin = await this.resolveNumber(config, 'read.denseResultAbsMin', ctx, 25);
+        const maxChunksPerFile = await this.resolveNumber(config, 'read.maxChunksPerFile', ctx, 2);
+        const tableMinShare = await this.resolveNumber(config, 'read.tableMinShare', ctx, 1);
         const scoreOrderValue = (await config.resolve('read.scoreOrder', ctx)).value;
         const scoreOrder = typeof scoreOrderValue === 'string' ? scoreOrderValue : 'weighted';
         // Memory Activation Model (dsgn-013) — a `memory.*` namespace; a decay CSAK a memory táron alkalmazódik (toHit).
@@ -692,15 +725,18 @@ class FAM_Retrieval_ControlService {
         const memoryColdSearchMaxCandidates = await this.resolveNumber(config, 'memory.coldSearchMaxCandidates', ctx, 5000);
         const memorySupersededPenalty = await this.resolveNumber(config, 'memory.supersededPenalty', ctx, 0.25);
         return {
-            topK: Math.min(topKDefault, MAX_PAGE_SIZE),
+            topK: Math.min(topKDefault, exports.MAX_PAGE_SIZE),
             minScore: minScore,
             relevanceFloor: relevanceFloor,
             importChunkWeight: importChunkWeight,
             importSourceWeight: importSourceWeight,
             scanSummaryWeight: scanSummaryWeight,
             keywordWeight: keywordWeight,
+            weightInfluence: weightInfluence,
             denseResultRatio: denseResultRatio,
             denseResultAbsMin: denseResultAbsMin,
+            maxChunksPerFile: maxChunksPerFile,
+            tableMinShare: tableMinShare,
             scoreOrder: scoreOrder,
             memoryActivationEnabled: memoryActivationEnabled,
             memoryHalfLifeDays: memoryHalfLifeDays,

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

@@ -10,10 +10,11 @@
  * opcionális relevance-filter = BACKLOG (NEM épül).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FAM_RetrievalSuggestions_Util = exports.FAM_RetrievalCandidate_DataService = exports.FAM_RuleScopeContext_Util = exports.FAM_RulePropagation_Util = exports.FAM_RuleInjection_Util = exports.FAM_RuleInjection_ControlService = exports.FAM_GlobalRule_ControlService = exports.FAM_Retrieval_ControlService = void 0;
+exports.FAM_RetrievalSuggestions_Util = exports.FAM_RetrievalCandidate_DataService = exports.FAM_RuleScopeContext_Util = exports.FAM_RulePropagation_Util = exports.FAM_RuleInjection_Util = exports.FAM_RuleInjection_ControlService = exports.FAM_GlobalRule_ControlService = exports.MAX_PAGE_SIZE = exports.FAM_Retrieval_ControlService = void 0;
 // SP-5.1/5.2/5.3 — a read-pipeline orchestrátor
 var fam_retrieval_control_service_1 = require("./_services/fam-retrieval.control-service");
 Object.defineProperty(exports, "FAM_Retrieval_ControlService", { enumerable: true, get: function () { return fam_retrieval_control_service_1.FAM_Retrieval_ControlService; } });
+Object.defineProperty(exports, "MAX_PAGE_SIZE", { enumerable: true, get: function () { return fam_retrieval_control_service_1.MAX_PAGE_SIZE; } });
 var fam_global_rule_control_service_1 = require("./_services/fam-global-rule.control-service");
 Object.defineProperty(exports, "FAM_GlobalRule_ControlService", { enumerable: true, get: function () { return fam_global_rule_control_service_1.FAM_GlobalRule_ControlService; } });
 // Rules-Management MP-2 — always-apply rule-injektálás (SessionStart inject + read-reflex) szerver-oldali assembly

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@futdevpro/fdp-agent-memory",
-  "version": "1.1.137",
+  "version": "1.1.153",
   "description": "Local-first, vector-backed multi-table agent memory exposed as an MCP server (read/write/capabilities). Public, FDP-Templates-free, no auth.",
   "private": false,
   "publishConfig": {