@futdevpro/fdp-agent-memory 1.1.21 → 1.1.112

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

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_MemoryDormancy_ControlService = void 0;
+const tslib_1 = require("tslib");
+const mongoose_1 = tslib_1.__importDefault(require("mongoose"));
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+const config_control_service_1 = require("../../../_routes/server/config/config.control-service");
+const embedding_1 = require("../../embedding");
+const fam_memory_data_model_1 = require("../../../_models/data-models/fam-memory.data-model");
+/**
+ * `FAM_MemoryDormancy_ControlService` (dsgn-013 §5, MAM F3) — a memória-DORMANCY sweep-je: a régóta-nem-felidézett,
+ * ritkán-használt `memory`-bejegyzéseket ALVÓ-vá (`dormant=true`) jelöli. Az alvó memória NEM hidratálódik a hot
+ * LVS-poolba (RAM-/boot-spórolás, dsgn-013 §5.2), de Mongo-oldali COLD kereséssel elérhető (§5.3) + megtaláláskor
+ * reaktiválódik (visszakerül a hot készletbe). **SOHA nem töröl** — a `dormant` csak hidratálás-kihagyás.
+ *
+ * **Mongo-kifejezhető szabály (== a pure `FAM_MemoryActivation_Util.isDormant` age+recall kapuja):** `lastRecalledAt`
+ * (hiányában `__created`) régebbi mint `minAgeDays`, ÉS `recallCount < maxRecallCount`. A sokszor-felidézett memória
+ * SOHA nem dormant. A sweep `updateMany` — nem érinti a vektor-poolt (a hatás a következő (re)hidratáláskor jön).
+ */
+class FAM_MemoryDormancy_ControlService {
+    static _instance;
+    issuer = 'FAM_MemoryDormancy_ControlService';
+    static MS_PER_DAY = 86_400_000;
+    static getInstance() {
+        if (!FAM_MemoryDormancy_ControlService._instance) {
+            FAM_MemoryDormancy_ControlService._instance = new FAM_MemoryDormancy_ControlService();
+        }
+        return FAM_MemoryDormancy_ControlService._instance;
+    }
+    /**
+     * A dormancy-sweep: a kvalifikáló `memory`-bejegyzések `dormant=true`-vá jelölése. Best-effort — a hiba logolódik és
+     * 0-val tér vissza (a boot-ot/működést nem buktatja). A `nowMs` injektálható (teszt-determinizmus). `dormancyEnabled
+     * = false` → no-op.
+     */
+    async sweep(nowMs) {
+        try {
+            const config = config_control_service_1.FAM_Config_ControlService.getInstance();
+            const enabledValue = (await config.resolve('memory.dormancyEnabled', {})).value;
+            if (enabledValue === false) {
+                return { enabled: false, markedDormant: 0 };
+            }
+            const minAgeDays = await this.resolveNumber(config, 'memory.dormantMinAgeDays', 180);
+            const maxRecallCount = await this.resolveNumber(config, 'memory.dormantMaxRecallCount', 2);
+            const model = this.memoryModel();
+            if (!model) {
+                return { enabled: true, markedDormant: 0 };
+            }
+            const filter = FAM_MemoryDormancy_ControlService.buildSweepFilter({
+                nowMs: nowMs, minAgeDays: minAgeDays, maxRecallCount: maxRecallCount,
+            });
+            const res = await model.updateMany(filter, { $set: { dormant: true } });
+            const marked = res.modifiedCount ?? 0;
+            if (marked > 0) {
+                fsm_dynamo_1.DyFM_Log.info(`[FAM memoryDormancy] ${marked} memória-bejegyzés ALVÓ-vá jelölve (age>${minAgeDays}d, recall<${maxRecallCount}).`);
+            }
+            return { enabled: true, markedDormant: marked };
+        }
+        catch (error) {
+            fsm_dynamo_1.DyFM_Log.warn(`[FAM memoryDormancy] sweep sikertelen (best-effort): ${error?.message}`);
+            return { enabled: true, markedDormant: 0 };
+        }
+    }
+    /**
+     * A sweep Mongo-filtere (PURE, tesztelhető): `completed` + még-nem-dormant + age-gát (`lastRecalledAt` VAGY a
+     * fallback `__created` a `minAgeDays`-cutoff előtt) + recall-gát (`recallCount < maxRecallCount`, a hiányzót is
+     * beleértve). A flag-csak frissítés → a vektor-poolt nem érinti.
+     */
+    static buildSweepFilter(set) {
+        const cutoffMs = set.nowMs - set.minAgeDays * FAM_MemoryDormancy_ControlService.MS_PER_DAY;
+        const cutoffDate = new Date(cutoffMs);
+        // age-gát: explicit lastRecalledAt a cutoff előtt, VAGY nincs lastRecalledAt és a __created a cutoff előtt.
+        const ageGate = {
+            $or: [
+                { lastRecalledAt: { $lt: cutoffMs } },
+                { lastRecalledAt: { $exists: false }, __created: { $lt: cutoffDate } },
+            ],
+        };
+        // recall-gát: recallCount < max (a hiányzó/0 is kvalifikál).
+        const recallGate = {
+            $or: [{ recallCount: { $lt: set.maxRecallCount } }, { recallCount: { $exists: false } }],
+        };
+        return {
+            embeddingStatus: 'completed',
+            dormant: { $ne: true },
+            $and: [ageGate, recallGate],
+        };
+    }
+    /** Egy szám-config feloldása a default-tal (a `resolve.value` lehet más típus → fallback). */
+    async resolveNumber(config, key, fallback) {
+        const value = (await config.resolve(key, {})).value;
+        return typeof value === 'number' ? value : fallback;
+    }
+    /** A `fam_memory` mongoose-modellje (a DS-példányosítás regisztrálja). */
+    memoryModel() {
+        new embedding_1.FAM_Entry_DataService({ dataParams: fam_memory_data_model_1.famMemory_dataParams, issuer: this.issuer });
+        return mongoose_1.default.models[fam_memory_data_model_1.famMemory_dataParams.dataName];
+    }
+}
+exports.FAM_MemoryDormancy_ControlService = FAM_MemoryDormancy_ControlService;

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

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_MemoryReactivation_ControlService = void 0;
+const tslib_1 = require("tslib");
+const mongoose_1 = tslib_1.__importDefault(require("mongoose"));
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+const fam_table_type_enum_1 = require("../../../_enums/fam-table.type-enum");
+const embedding_1 = require("../../embedding");
+const fam_memory_data_model_1 = require("../../../_models/data-models/fam-memory.data-model");
+/**
+ * `FAM_MemoryReactivation_ControlService` (dsgn-013 §4, MAM F2) — a memória FELIDÉZÉS-megerősítése. Amikor a `read`
+ * ténylegesen VISSZAAD egy `memory`-hitet (a felhasználó/agent felidézte), az „új energiát kap": `lastRecalledAt = now`,
+ * `recallCount += 1`, `dormant = false`. Ez az emberi memória retrieval-practice-e — a felidézett emlék megerősödik,
+ * feljebb rangsorol (a dsgn-013 §2 frequencyBoost + a friss recency), és ha alvó volt, visszakerül a hot készletbe.
+ *
+ * **Fire-and-forget:** a `read`-ből async, NEM blokkolja a választ; batch-elt `updateMany` (egy DB-hívás a top-K-ra).
+ * CSAK a ténylegesen visszaadott (használt) hitre fut → nincs „gyakran-keresett-de-irreleváns" felhízás. A hiba
+ * NÉMA-best-effort (a read már sikerült; a felidézés-frissítés elvesztése nem hiba). A flag NEM érinti a vektor-poolt.
+ */
+class FAM_MemoryReactivation_ControlService {
+    static _instance;
+    issuer = 'FAM_MemoryReactivation_ControlService';
+    static getInstance() {
+        if (!FAM_MemoryReactivation_ControlService._instance) {
+            FAM_MemoryReactivation_ControlService._instance = new FAM_MemoryReactivation_ControlService();
+        }
+        return FAM_MemoryReactivation_ControlService._instance;
+    }
+    /**
+     * A megadott `memory`-entry-k FELIDÉZÉS-frissítése (`updateMany`): `lastRecalledAt = nowMs`, `recallCount += 1`,
+     * `dormant = false`. Üres id-lista → no-op (0). Visszaadja a módosított darabszámot. **Nem dob** — a hiba logolódik
+     * és `0`-val tér vissza (best-effort, a read-et nem buktatja).
+     */
+    async reactivate(ids, nowMs) {
+        const uniqueIds = Array.from(new Set(ids.filter((id) => typeof id === 'string' && id.length)));
+        if (!uniqueIds.length) {
+            return 0;
+        }
+        try {
+            const model = this.memoryModel();
+            if (!model) {
+                return 0;
+            }
+            const res = await model.updateMany({ _id: { $in: uniqueIds } }, { $set: { lastRecalledAt: nowMs, dormant: false }, $inc: { recallCount: 1 } });
+            return res.modifiedCount ?? 0;
+        }
+        catch (error) {
+            fsm_dynamo_1.DyFM_Log.warn(`[FAM memoryReactivation] felidézés-frissítés sikertelen (best-effort): ${error?.message}`);
+            return 0;
+        }
+    }
+    /**
+     * A reaktiválandó `memory`-hit `_id`-k kiválasztása a read-eredmény hitjeiből (PURE, tesztelhető): CSAK a
+     * `memory`-táras, `_id`-vel bíró hitek, deduplikálva. A NEM-memory hitek (codebase/documents/…) kimaradnak.
+     */
+    static selectMemoryIds(hits) {
+        const ids = hits
+            .filter((hit) => hit.table === fam_table_type_enum_1.FAM_Table.memory && typeof hit.id === 'string' && hit.id.length > 0)
+            .map((hit) => hit.id);
+        return Array.from(new Set(ids));
+    }
+    /** A `fam_memory` mongoose-modellje (a DS-példányosítás regisztrálja). */
+    memoryModel() {
+        new embedding_1.FAM_Entry_DataService({ dataParams: fam_memory_data_model_1.famMemory_dataParams, issuer: this.issuer });
+        return mongoose_1.default.models[fam_memory_data_model_1.famMemory_dataParams.dataName];
+    }
+}
+exports.FAM_MemoryReactivation_ControlService = FAM_MemoryReactivation_ControlService;

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

@@ -117,8 +117,21 @@ class FAM_RetrievalCandidate_DataService {
         const filter = {};
         // ① scope-prefilter (subtree scopeId-halmaz). null → nincs scope-szűrés (teljes tár).
         if (input.scopeIdSet) {
-            // A scopePath denormalizált scope-ref tömb; a scopeId-ra szűrünk (dot-path a Mixed tömbön).
-            filter['scopePath.scopeId'] = { $in: input.scopeIdSet };
+            const isGlobalRulesTable = registryEntry.table === fam_table_type_enum_1.FAM_Table.rules && input.includeGlobalRules !== false;
+            if (isGlobalRulesTable) {
+                // GLOBÁLIS HARD-RULE öröklés (user-FR 2026-06-22 — a FAM fő feature-je): a scope-szűrt `rules`-lekérdezés
+                // a subtree-scope rule-jai MELLÉ a `globalRule:true` (workspace-szintű hard-rules) bejegyzéseket is
+                // behúzza — `(scope subtree-ben) VAGY (globális hard-rule)`. Így egy al-scope-ban is megkapjuk a
+                // mindenhol érvényes hard-rules-t. (A `$or` a tag/kind/isActive AND-feltételekkel kombinálódik.)
+                filter.$or = [
+                    { 'scopePath.scopeId': { $in: input.scopeIdSet } },
+                    { globalRule: true },
+                ];
+            }
+            else {
+                // A scopePath denormalizált scope-ref tömb; a scopeId-ra szűrünk (dot-path a Mixed tömbön).
+                filter['scopePath.scopeId'] = { $in: input.scopeIdSet };
+            }
         }
         // ② tag-prefilter (OR a tagek között): bármely tag-match bekerül.
         if (input.tagFilter && input.tagFilter.length) {

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

@@ -8,6 +8,10 @@ const embedding_1 = require("../../embedding");
 const scope_reference_1 = require("../../scope-reference");
 const fam_retrieval_candidate_data_service_1 = require("./fam-retrieval-candidate.data-service");
 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_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;
 /**
@@ -95,8 +99,57 @@ class FAM_Retrieval_ControlService {
         const relevantSet = visibleHits.filter((hit) => this.codeExactRank(hit) > 0 || hit.finalScore >= config.minScore);
         // ⑦ rendezés (finalScore desc → recency → _id asc).
         this.sortHits(relevantSet, config.scoreOrder);
+        // ⑦b R1 duplikátum-dedup (FAM-REV 2026-06-22, eval-lelet): az AZONOS-tartalmú (kereszt-repo) hitek összevonása
+        // a top-K ELŐTT — a kanonikus (legjobb-ranked) marad, a másolat-szám a `duplicateCount`-ban. A közös fájlok
+        // (`.cursor/rules` / CLAUDE.md / guideline) ne pazarolják a top-K-t 4-5 azonos másolattal. A `sortHits` UTÁN fut
+        // (a megtartott a legjobb-rangsorolt); a contentHash-mentes hitek érintetlenek.
+        const dedupedSet = FAM_Retrieval_ControlService.dedupeByContentHash(relevantSet);
         // ⑧ topK-vágás + dense-detektálás + suggestions.
-        return this.buildResult({ query, relevantSet, config, scopeExpand, detectedCodes });
+        const result = this.buildResult({ query, relevantSet: dedupedSet, config, scopeExpand, detectedCodes });
+        // dsgn-013 §4 (MAM F2) — FELIDÉZÉS-megerősítés: a ténylegesen VISSZAADOTT `memory`-hitek „új energiát kapnak"
+        // (lastRecalledAt=now, recallCount++, dormant=false). ASYNC fire-and-forget — NEM blokkolja a read választ.
+        this.reactivateReturnedMemoryHits(result.hits, config);
+        return result;
+    }
+    /**
+     * A visszaadott top-K `memory`-hitek async felidézés-megerősítése (dsgn-013 §4). Fire-and-forget (void): a read
+     * már elkészült, a felidézés-frissítés best-effort. Csak a `memory`-táras, `_id`-vel bíró hitre; üres → no-op.
+     * `memoryReactivateOnRead=false` → kikapcsolva.
+     */
+    reactivateReturnedMemoryHits(hits, config) {
+        if (!config.memoryReactivateOnRead) {
+            return;
+        }
+        const memoryIds = fam_memory_reactivation_control_service_1.FAM_MemoryReactivation_ControlService.selectMemoryIds(hits);
+        if (!memoryIds.length) {
+            return;
+        }
+        void fam_memory_reactivation_control_service_1.FAM_MemoryReactivation_ControlService.getInstance().reactivate(memoryIds, Date.now());
+    }
+    /**
+     * R1 dedup (pure): az AZONOS `contentHash`-ű hitek összevonása — az ELSŐ (a `sortHits` után legjobb-ranked) marad,
+     * a többi azonos-tartalmú másolatot beleszámoljuk a megtartott `duplicateCount`-jába. A `contentHash`-mentes hitek
+     * (pl. compact-mode projekció nélkül) NEM dedup-olódnak (mind egyedi). Sorrend-tartó.
+     */
+    static dedupeByContentHash(hits) {
+        const keptByHash = new Map();
+        const result = [];
+        for (const hit of hits) {
+            const key = hit.contentHash;
+            if (!key) {
+                result.push(hit);
+                continue;
+            }
+            const kept = keptByHash.get(key);
+            if (kept) {
+                kept.duplicateCount = (kept.duplicateCount ?? 0) + 1;
+            }
+            else {
+                keptByHash.set(key, hit);
+                result.push(hit);
+            }
+        }
+        return result;
     }
     // =========================================================================
     // ④b KÓD-EXPANZIÓ (FEAT-003) — determinisztikus link-retrieval a vektor MELLÉ
@@ -171,6 +224,7 @@ class FAM_Retrieval_ControlService {
             weight: set.weight,
             finalScore: 1.0 * set.weight,
             content: set.includeContent ? set.entry.content : undefined,
+            contentHash: set.entry.contentHash,
             kind: set.entry.kind,
             tags: set.entry.tags ?? [],
             ...this.ruleMeta(set.entry, set.table),
@@ -256,6 +310,8 @@ class FAM_Retrieval_ControlService {
             });
         }
         // ⑤ weight-szorzó: finalScore = score × (weight ?? 1); weight ≤ 0 → kizárt (nem kerül a hits közé).
+        // Improvement 2: a query lexikai term-jeit EGYSZER tokenizáljuk (a hibrid keyword-boost-hoz a toHit-ban).
+        const queryTerms = fam_lexical_match_util_1.FAM_LexicalMatch_Util.tokenize(set.query.query);
         const hits = [];
         for (const vectorHit of vectorHits) {
             const entry = byId.get(vectorHit.id);
@@ -267,12 +323,63 @@ class FAM_Retrieval_ControlService {
                 continue;
             }
             hits.push(this.toHit({
-                entry, vectorHit, table: set.table, weight,
-                importChunkWeight: set.config.importChunkWeight, includeContent: set.includeContent,
+                entry, vectorHit, table: set.table, weight, queryTerms: queryTerms,
+                importChunkWeight: set.config.importChunkWeight, importSourceWeight: set.config.importSourceWeight,
+                includeContent: set.includeContent, config: set.config, nowMs: Date.now(),
             }));
         }
+        // dsgn-013 §5.3 (MAM F3b) — COLD-search supplement: ha `memory` + engedélyezett + a hot pool kevés ERŐSEN-
+        // releváns találatot ad. FONTOS: NEM a candidate-darabszámot nézzük (a vektor-keresés ~MAX_PAGE_SIZE jelöltet ad
+        // vissza, így a `hits.length` szinte mindig nagy) — hanem az ERŐS (raw cosine ≥ relevanceFloor) hot hitek számát.
+        // Ha ezekből kevesebb mint topK van, a hot pool nem elégítette ki a query-t → a dormant készleten keresünk.
+        const strongHotHits = hits.filter((hit) => hit.score >= set.config.relevanceFloor).length;
+        if (set.table === fam_table_type_enum_1.FAM_Table.memory && set.config.memoryColdSearchEnabled && strongHotHits < set.config.topK) {
+            await this.supplementWithColdSearch(set, hits, set.query);
+        }
         return hits;
     }
+    /**
+     * A hot memória-találatok kiegészítése a dormant készletből (dsgn-013 §5.3). A cold-hiteket a `toHit`-en át
+     * (decay + faktorok) fűzzük be, a már látott `_id`-ket kiszűrve; a `weight ≤ 0` továbbra is kizárt.
+     */
+    async supplementWithColdSearch(set, hits, query) {
+        // `topK` cold-jelölt (NEM `topK - hits.length` — a `hits` itt a teljes candidate-halmaz, ~MAX_PAGE_SIZE, ami
+        // negatívot adna). A cold-hitek a NORMÁL ranking-pipeline-ba kerülnek; a végső topK-vágás (buildResult) dönt.
+        // A tag/kind prefilter UGYANAZ, mint a hot-path-é (különben kiszűrt entry-ket hozna vissza a cold-supplement).
+        const coldHits = await fam_memory_cold_search_control_service_1.FAM_MemoryColdSearch_ControlService.getInstance().search({
+            queryVector: set.queryVector,
+            scopeIdSet: set.scopeExpand.scopeIdSet ?? [],
+            topK: set.config.topK,
+            maxCandidates: set.config.memoryColdSearchMaxCandidates,
+            nowMs: Date.now(),
+            tagFilter: query.tagFilter,
+            kindFilter: query.kindFilter,
+        });
+        const seen = new Set(hits.map((hit) => hit.id));
+        const queryTerms = fam_lexical_match_util_1.FAM_LexicalMatch_Util.tokenize(query.query);
+        for (const cold of coldHits) {
+            const id = cold.entry._id;
+            const weight = cold.entry.weight ?? 1;
+            if (!id || seen.has(id) || weight <= 0) {
+                continue;
+            }
+            hits.push(this.toHit({
+                entry: cold.entry, vectorHit: { id: id, score: cold.score }, table: set.table, weight: weight, queryTerms: queryTerms,
+                importChunkWeight: set.config.importChunkWeight, importSourceWeight: set.config.importSourceWeight,
+                includeContent: set.includeContent, config: set.config, nowMs: Date.now(),
+            }));
+            seen.add(id);
+            // KRITIKUS (dsgn-013 §5.3 promóció-gap fix): a cold-talált entry vektorát AZONNAL a hot poolba is upsert-eljük.
+            // Különben — miután a reaktiváció `dormant=false`-ra állítja — az entry SEM a hot poolban (csak boot-kor
+            // hidratálódik), SEM a cold-keresésben (a `dormant:true` szűrő kizárja) nem lenne megtalálható a következő
+            // re-hidratálásig → „elérhetetlen a promóció után". A pool-upsert idempotens; a (ritka) topK-ból kieső,
+            // de még dormant entry a következő bootkor úgyis kiesik a poolból (a hidratálás-szűrő korrigálja).
+            const vector = (cold.entry.contentVector ?? []);
+            if (vector.length) {
+                embedding_1.FAM_VectorSearch_ControlService.getInstance().upsertVector({ table: set.table, id: id, vector: vector });
+            }
+        }
+    }
     /**
      * Az import-only chunkok (`chunkType:"imports"`) read-idejű rangsor-szorzója (FAM-REV-060). Egy import-sor
      * (`import { X } from "./y"`) magas cosine-t kap egy szimbólum-név query-re, de alacsony az ÉRTÉKe (csak
@@ -282,18 +389,70 @@ class FAM_Retrieval_ControlService {
     chunkTypeFactor(chunkType, importChunkWeight) {
         return chunkType === 'imports' ? importChunkWeight : 1;
     }
+    /**
+     * R2 import-source faktor (2026-06-22 eval-lelet): a `source.type:'import'` (claude-mem-import) entry-k finalScore-ja
+     * `importSourceWeight`-tel szorzódik (<1), hogy a kurált (`manual`/`agent`/scan) tanulságok a `memory`/`knowledge`
+     * táblákon FÖLÉ rangsoroljanak — az import zaja ne temesse őket. Minden NEM-import source érintetlen (×1).
+     * READ-time, a nyers `score` (relevancia) változatlan; `importSourceWeight=1` → kikapcsolva (változatlan rangsor).
+     */
+    importSourceFactor(source, importSourceWeight) {
+        return source?.type === 'import' ? importSourceWeight : 1;
+    }
+    /**
+     * Memory Activation Model decay-szorzó (dsgn-013 §3) — CSAK a `memory` táron, ha engedélyezett. A frissen/gyakran
+     * FELIDÉZETT memória felül-, a régóta érintetlen alul-rangsorol, de a `floorWeight > 0` miatt SOSEM esik ki. A
+     * `lastRecalledAt` hiányában a `__created` ideje a fallback (cold-start kegyelmi idő). Minden más tár → ×1.
+     */
+    memoryDecayFactor(entry, table, config, nowMs) {
+        if (table !== fam_table_type_enum_1.FAM_Table.memory) {
+            return 1;
+        }
+        let factor = 1;
+        if (config.memoryActivationEnabled) {
+            const createdMs = entry.__created ? new Date(entry.__created).getTime() : undefined;
+            factor = fam_memory_activation_util_1.FAM_MemoryActivation_Util.decayFactor({
+                lastRecalledAt: entry.lastRecalledAt,
+                recallCount: entry.recallCount,
+                nowMs: nowMs,
+                fallbackMs: createdMs,
+                config: {
+                    halfLifeDays: config.memoryHalfLifeDays, floorWeight: config.memoryFloorWeight,
+                    maxFrequencyBoost: config.memoryMaxFrequencyBoost, activationWeight: config.memoryActivationWeight,
+                },
+            });
+        }
+        // dsgn-013 §6 (MAM F4): a LEVÁLTOTT (superseded) régi tartalom penalizálva — a friss verzió fölébe kerül (de
+        // megmarad, cold-kereshető). A penalty az aktiváció-decay MELLÉ szorzódik (akkor is hat, ha a decay ki van kapcsolva).
+        if (entry.superseded) {
+            factor *= config.memorySupersededPenalty;
+        }
+        return factor;
+    }
     /** Egy candidate-entry + a vektor-hit → `FAM_RetrievalHit` (finalScore + denormalizált mezők). */
     toHit(set) {
         const lastModified = set.entry.__lastModified;
-        // ⑤ weight-szorzó + FAM-REV-060 import-chunk read-faktor: finalScore = score × weight × chunkTypeFactor.
+        // ⑤ weight-szorzó + FAM-REV-060 import-chunk read-faktor + R2 import-SOURCE faktor (2026-06-22 eval-lelet:
+        // a claude-mem-import zaja ne temesse a kurált tanulságokat) + dsgn-013 memory-decay (CSAK a memory táron) +
+        // Improvement 2 hibrid LEXIKAI keyword-boost (a literal-match felszínre kerül, BOOST-only) →
+        // 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 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, {
+                content: set.entry.content, headingPath: set.entry.headingPath, sourceFilePath: set.entry.source?.path,
+            })
+            : 0;
+        const keywordBoost = 1 + set.config.keywordWeight * lexicalScore;
         return {
             id: set.vectorHit.id,
             table: set.table,
             score: set.vectorHit.score,
             weight: set.weight,
-            finalScore: set.vectorHit.score * set.weight * chunkFactor,
+            finalScore: set.vectorHit.score * set.weight * chunkFactor * sourceFactor * decayFactor * keywordBoost,
+            lexicalScore: lexicalScore,
             content: set.includeContent ? set.entry.content : undefined,
+            contentHash: set.entry.contentHash,
             kind: set.entry.kind,
             tags: set.entry.tags ?? [],
             ...this.ruleMeta(set.entry, set.table),
@@ -324,6 +483,13 @@ class FAM_Retrieval_ControlService {
             category: rule.category,
             isActive: rule.isActive,
             applicableScopes: (rule.applicableScopes ?? []),
+            // Rules-Management MP-1 mezők a hit-en (read-DTO bővítés) — a hívó/reflex így megkülönbözteti a KURÁLT
+            // kanonikus szabályt (ruleScope/importance/userApproved/ruleId) a nyers, scannelt rules-korpusztól.
+            ruleScope: rule.ruleScope,
+            ruleScopeTopic: rule.ruleScopeTopic,
+            importance: rule.importance,
+            userApproved: rule.userApproved,
+            ruleId: rule.ruleId,
         };
     }
     // =========================================================================
@@ -488,18 +654,44 @@ class FAM_Retrieval_ControlService {
         const minScore = query.minScore ?? await this.resolveNumber(config, 'read.minScore', ctx, 0);
         const relevanceFloor = await this.resolveNumber(config, 'read.relevanceFloor', ctx, 0.5);
         const importChunkWeight = await this.resolveNumber(config, 'read.importChunkWeight', ctx, 0.4);
+        const importSourceWeight = await this.resolveNumber(config, 'read.importSourceWeight', ctx, 0.85);
+        const keywordWeight = await this.resolveNumber(config, 'read.keywordWeight', ctx, 0.6);
         const denseResultRatio = await this.resolveNumber(config, 'read.denseResultRatio', ctx, 2.0);
         const denseResultAbsMin = await this.resolveNumber(config, 'read.denseResultAbsMin', ctx, 25);
         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).
+        const memoryActivationValue = (await config.resolve('memory.activationEnabled', ctx)).value;
+        const memoryActivationEnabled = memoryActivationValue !== false;
+        const memoryHalfLifeDays = await this.resolveNumber(config, 'memory.decayHalfLifeDays', ctx, 90);
+        const memoryFloorWeight = await this.resolveNumber(config, 'memory.floorWeight', ctx, 0.05);
+        const memoryMaxFrequencyBoost = await this.resolveNumber(config, 'memory.maxFrequencyBoost', ctx, 2.5);
+        const memoryActivationWeight = await this.resolveNumber(config, 'memory.activationWeight', ctx, 0.35);
+        const memoryReactivateValue = (await config.resolve('memory.reactivateOnRead', ctx)).value;
+        const memoryReactivateOnRead = memoryReactivateValue !== false;
+        const memoryColdSearchValue = (await config.resolve('memory.coldSearchEnabled', ctx)).value;
+        const memoryColdSearchEnabled = memoryColdSearchValue !== false;
+        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),
             minScore: minScore,
             relevanceFloor: relevanceFloor,
             importChunkWeight: importChunkWeight,
+            importSourceWeight: importSourceWeight,
+            keywordWeight: keywordWeight,
             denseResultRatio: denseResultRatio,
             denseResultAbsMin: denseResultAbsMin,
             scoreOrder: scoreOrder,
+            memoryActivationEnabled: memoryActivationEnabled,
+            memoryHalfLifeDays: memoryHalfLifeDays,
+            memoryFloorWeight: memoryFloorWeight,
+            memoryMaxFrequencyBoost: memoryMaxFrequencyBoost,
+            memoryActivationWeight: memoryActivationWeight,
+            memoryReactivateOnRead: memoryReactivateOnRead,
+            memoryColdSearchEnabled: memoryColdSearchEnabled,
+            memoryColdSearchMaxCandidates: memoryColdSearchMaxCandidates,
+            memorySupersededPenalty: memorySupersededPenalty,
         };
     }
     /** Egy szám-config feloldása a default-tal (a `resolve.value` lehet más típus → fallback). */

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

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_RuleInjection_ControlService = void 0;
+const tslib_1 = require("tslib");
+const mongoose_1 = tslib_1.__importDefault(require("mongoose"));
+const error_codes_const_1 = require("../../../_collections/error-codes.const");
+const fam_error_factory_util_1 = require("../../../_collections/fam-error-factory.util");
+const fam_rules_data_model_1 = require("../../../_models/data-models/fam-rules.data-model");
+const embedding_1 = require("../../embedding");
+const fam_rule_injection_util_1 = require("../_collections/fam-rule-injection.util");
+const fam_rule_propagation_util_1 = require("../_collections/fam-rule-propagation.util");
+const fam_rule_scope_context_util_1 = require("../_collections/fam-rule-scope-context.util");
+/**
+ * `FAM_RuleInjection_ControlService` (Rules-Management MP-2) — a SessionStart-injektálás (+ a `read`-reflex) szerver-oldali
+ * ASSEMBLY-je: a `cwd`-ből (vagy explicit felülírásból) detektálja a tier-kontextust, prefilterezi a `fam_rules`-t a
+ * MOST érvényes TIER-ekre (`FAM_RuleInjection_Util.buildFilter`), `importance`-rangsorolja, és char-budgetbe illeszti
+ * a „(…and N more)" záró sorral. A hook így DUMB marad (csak hív + az `additionalContext`-be teszi a blokkot) — a teljes
+ * ranking/scope/budget logika ITT, szerver-oldalon, unit-tesztelhetően él (mint a `/api/doctor`).
+ */
+class FAM_RuleInjection_ControlService {
+    static _instance;
+    issuer = 'FAM_RuleInjection_ControlService';
+    static getInstance() {
+        if (!FAM_RuleInjection_ControlService._instance) {
+            FAM_RuleInjection_ControlService._instance = new FAM_RuleInjection_ControlService();
+        }
+        return FAM_RuleInjection_ControlService._instance;
+    }
+    /** A MOST érvényes always-apply rule-blokk összeállítása (detektált/felülírt kontextus alapján). */
+    async assembleInjection(input) {
+        const context = this.resolveContext(input);
+        const rules = await this.loadRulesForContext(context);
+        const assembled = fam_rule_injection_util_1.FAM_RuleInjection_Util.assemble({
+            rules: rules, budgetChars: input.budgetChars,
+        });
+        return { ...assembled, context: context };
+    }
+    /**
+     * MP-5 — a kontextusra érvényes szabályok GENERÁLT, marker-keretezett `CLAUDE.md`-blokkja (propagáció a FAM-nélküli
+     * projekt-agenteknek). Budget NÉLKÜL (minden alkalmazható szabály bekerül), dedup `ruleId`/`derivedFrom` szerint.
+     */
+    async assemblePropagation(input) {
+        const context = this.resolveContext(input);
+        const rules = await this.loadRulesForContext(context);
+        const block = fam_rule_propagation_util_1.FAM_RulePropagation_Util.wrap(fam_rule_propagation_util_1.FAM_RulePropagation_Util.renderBlock(rules));
+        return { block: block, ruleCount: fam_rule_propagation_util_1.FAM_RulePropagation_Util.dedup(rules).length, context: context };
+    }
+    /** A tier-kontextusra érvényes, aktív `rules`-entry-k betöltése injektálható view-ként (közös SSOT a két assembly-hez). */
+    async loadRulesForContext(context) {
+        const model = this.rulesModel();
+        if (!model) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.vecSearch,
+                message: 'A `fam_rules` model nincs regisztrálva (boot-előtt?).',
+                issuer: this.issuer,
+                context: { operation: 'load-rules-for-context' },
+            });
+        }
+        const filter = fam_rule_injection_util_1.FAM_RuleInjection_Util.buildFilter(context);
+        // CSAK a rangsorhoz/megjelenítéshez kellő mezők (a vektor NEM kell → könnyű lean-query).
+        const docs = await model.find(filter, {
+            content: 1, importance: 1, weight: 1, globalRule: 1, category: 1,
+            ruleScope: 1, ruleScopeTopic: 1, ruleId: 1, derivedFrom: 1, __lastModified: 1,
+        }).lean();
+        return docs.map((doc) => this.toInjectable(doc));
+    }
+    /** Explicit felülírás > `cwd`-detekció. A `projectType`/`topics`/budget mindig az inputból. */
+    resolveContext(input) {
+        const detected = fam_rule_scope_context_util_1.FAM_RuleScopeContext_Util.detect(input.cwd);
+        return {
+            isFdp: input.isFdp ?? detected.isFdp,
+            inProject: input.inProject ?? detected.inProject,
+            projectName: detected.projectName,
+            projectRoot: detected.projectRoot,
+            projectType: input.projectType ?? detected.projectType,
+            topics: input.topics ?? detected.topics,
+        };
+    }
+    /** Egy lean Mongo-doc → `FAM_InjectableRule` view. */
+    toInjectable(doc) {
+        const lastModified = doc.__lastModified;
+        return {
+            id: typeof doc._id === 'string' ? doc._id : (doc._id ? String(doc._id) : undefined),
+            content: typeof doc.content === 'string' ? doc.content : undefined,
+            importance: typeof doc.importance === 'number' ? doc.importance : undefined,
+            weight: typeof doc.weight === 'number' ? doc.weight : undefined,
+            globalRule: doc.globalRule === true,
+            category: typeof doc.category === 'string' ? doc.category : undefined,
+            ruleScope: typeof doc.ruleScope === 'string' ? doc.ruleScope : undefined,
+            ruleScopeTopic: typeof doc.ruleScopeTopic === 'string' ? doc.ruleScopeTopic : undefined,
+            ruleId: typeof doc.ruleId === 'string' ? doc.ruleId : undefined,
+            derivedFrom: typeof doc.derivedFrom === 'string' ? doc.derivedFrom : undefined,
+            lastModifiedMs: lastModified ? new Date(lastModified).getTime() : 0,
+        };
+    }
+    /** A `fam_rules` mongoose-modellje (a DS-példányosítás regisztrálja). */
+    rulesModel() {
+        new embedding_1.FAM_Entry_DataService({ dataParams: fam_rules_data_model_1.famRules_dataParams, issuer: this.issuer });
+        return mongoose_1.default.models[fam_rules_data_model_1.famRules_dataParams.dataName];
+    }
+}
+exports.FAM_RuleInjection_ControlService = FAM_RuleInjection_ControlService;

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

@@ -10,10 +10,21 @@
  * opcionális relevance-filter = BACKLOG (NEM épül).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FAM_RetrievalSuggestions_Util = exports.FAM_RetrievalCandidate_DataService = 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.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; } });
+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
+var fam_rule_injection_control_service_1 = require("./_services/fam-rule-injection.control-service");
+Object.defineProperty(exports, "FAM_RuleInjection_ControlService", { enumerable: true, get: function () { return fam_rule_injection_control_service_1.FAM_RuleInjection_ControlService; } });
+var fam_rule_injection_util_1 = require("./_collections/fam-rule-injection.util");
+Object.defineProperty(exports, "FAM_RuleInjection_Util", { enumerable: true, get: function () { return fam_rule_injection_util_1.FAM_RuleInjection_Util; } });
+var fam_rule_propagation_util_1 = require("./_collections/fam-rule-propagation.util");
+Object.defineProperty(exports, "FAM_RulePropagation_Util", { enumerable: true, get: function () { return fam_rule_propagation_util_1.FAM_RulePropagation_Util; } });
+var fam_rule_scope_context_util_1 = require("./_collections/fam-rule-scope-context.util");
+Object.defineProperty(exports, "FAM_RuleScopeContext_Util", { enumerable: true, get: function () { return fam_rule_scope_context_util_1.FAM_RuleScopeContext_Util; } });
 // SP-5.1 ① scope + ② tag/kind Mongo-prefilter (a vektor-keresés ELŐTT)
 var fam_retrieval_candidate_data_service_1 = require("./_services/fam-retrieval-candidate.data-service");
 Object.defineProperty(exports, "FAM_RetrievalCandidate_DataService", { enumerable: true, get: function () { return fam_retrieval_candidate_data_service_1.FAM_RetrievalCandidate_DataService; } });