@devflow-tools/memory-engine 0.16.12 → 0.16.14

package/dist/explicit-memory-enricher.d.ts

@@ -0,0 +1,24 @@
+import type { ObservationType } from './observation-types.js';
+export interface ExplicitMemoryEvidenceItem {
+    kind: 'dependency' | 'config' | 'instruction' | 'source_event';
+    source: string;
+    summary: string;
+}
+export interface ExplicitMemoryEvidence {
+    type: ObservationType;
+    title: string;
+    narrative: string;
+    facts: string[];
+    concepts: string[];
+    files: string[];
+    tools: string[];
+    evidenceStatus: 'verified' | 'unverified';
+    evidence: ExplicitMemoryEvidenceItem[];
+}
+export interface EnrichExplicitMemoryInput {
+    projectRoot: string;
+    content: string;
+    sourceEventIds?: string[];
+}
+export declare function enrichExplicitMemory(input: EnrichExplicitMemoryInput): ExplicitMemoryEvidence;
+//# sourceMappingURL=explicit-memory-enricher.d.ts.map

package/dist/explicit-memory-enricher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explicit-memory-enricher.d.ts","sourceRoot":"","sources":["../src/explicit-memory-enricher.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,YAAY,GAAG,QAAQ,GAAG,aAAa,GAAG,cAAc,CAAC;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,eAAe,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,cAAc,EAAE,UAAU,GAAG,YAAY,CAAC;IAC1C,QAAQ,EAAE,0BAA0B,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAwED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,yBAAyB,GAAG,sBAAsB,CAqC7F"}

package/dist/explicit-memory-enricher.js

@@ -0,0 +1,292 @@
+import { closeSync, existsSync, openSync, readSync } from 'node:fs';
+import { join, relative } from 'node:path';
+const MAX_PACKAGE_JSON_BYTES = 256 * 1024;
+const MAX_LOCKFILE_BYTES = 512 * 1024;
+const MAX_CONFIG_BYTES = 128 * 1024;
+const MAX_INSTRUCTION_BYTES = 96 * 1024;
+const MAX_CONTENT_LENGTH = 4_000;
+const ENTITIES = [
+    {
+        canonical: 'motion',
+        aliases: ['motion', 'framer motion', 'framer-motion'],
+        packages: ['motion', 'framer-motion'],
+        concepts: ['motion', 'animation', 'framer-motion'],
+    },
+    {
+        canonical: 'react',
+        aliases: ['react', 'reactjs', 'react.js'],
+        packages: ['react'],
+        concepts: ['react'],
+    },
+    {
+        canonical: 'tailwind',
+        aliases: ['tailwind', 'tailwind css', 'tailwindcss'],
+        packages: ['tailwindcss'],
+        concepts: ['tailwind', 'tailwindcss', 'css'],
+    },
+    {
+        canonical: 'shadcn',
+        aliases: ['shadcn', 'shadcn ui', 'shadcn/ui'],
+        packages: ['shadcn'],
+        concepts: ['shadcn', 'ui-components'],
+    },
+    {
+        canonical: 'pnpm',
+        aliases: ['pnpm'],
+        concepts: ['pnpm', 'package-manager'],
+        tool: 'pnpm',
+    },
+    {
+        canonical: 'npm',
+        aliases: ['npm'],
+        concepts: ['npm', 'package-manager'],
+        tool: 'npm',
+    },
+    {
+        canonical: 'yarn',
+        aliases: ['yarn'],
+        concepts: ['yarn', 'package-manager'],
+        tool: 'yarn',
+    },
+    {
+        canonical: 'bun',
+        aliases: ['bun'],
+        concepts: ['bun', 'package-manager'],
+        tool: 'bun',
+    },
+];
+const PROJECT_SCOPE = /(?:\bproject\b|\brepository\b|\bcodebase\b|\bteam\b|项目|仓库|代码库|团队|全局|统一|一律)/iu;
+const PERSONAL_PREFERENCE = /(?:\bi\s+(?:prefer|like|want)\b|\bmy preference\b|我(?:更)?(?:喜欢|偏好|希望))/iu;
+const DECISION = /(?:\bdecid(?:e|ed)\b|\bchosen?\b|决定|选定|已选)/iu;
+const CONVENTION = /(?:\b(?:always|never|must|should|required?|standard(?:ize|ized)?)\b|\b(?:do not|don't)\s+use\b|\buse\s+[^\s]+|统一|一律|必须|需要|默认|规范|约定|不要|不使用|使用)/iu;
+export function enrichExplicitMemory(input) {
+    const narrative = input.content.normalize('NFKC').trim().slice(0, MAX_CONTENT_LENGTH);
+    if (!narrative)
+        throw new Error('Explicit memory content must be nonblank');
+    const matchedEntities = ENTITIES.filter(entity => containsAlias(narrative, entity.aliases));
+    const type = classifyExplicitMemory(narrative);
+    const projectEvidence = collectProjectEvidence(input.projectRoot, matchedEntities);
+    const sourceEvidence = uniqueStrings(input.sourceEventIds ?? []).map(source => ({
+        kind: 'source_event',
+        source,
+        summary: 'Explicit user memory request captured from the canonical session event.',
+    }));
+    const evidence = dedupeEvidence([...projectEvidence.evidence, ...sourceEvidence]);
+    const concepts = uniqueStrings(matchedEntities.flatMap(entity => entity.concepts));
+    const tools = uniqueStrings(matchedEntities.flatMap(entity => entity.tool ? [entity.tool] : []));
+    const entitySummary = matchedEntities.map(entity => entity.canonical).join(', ');
+    const titlePrefix = type === 'project_convention'
+        ? 'Project convention'
+        : type === 'decision_made'
+            ? 'Project decision'
+            : 'User preference';
+    const titleSubject = entitySummary || firstClause(narrative);
+    return {
+        type,
+        title: `${titlePrefix}: ${titleSubject}`.slice(0, 160),
+        narrative,
+        facts: uniqueStrings([
+            narrative,
+            ...matchedEntities.map(entity => `Referenced entity: ${entity.canonical}`),
+        ]),
+        concepts,
+        files: uniqueStrings(projectEvidence.files),
+        tools,
+        evidenceStatus: projectEvidence.evidence.length > 0 ? 'verified' : 'unverified',
+        evidence,
+    };
+}
+function classifyExplicitMemory(content) {
+    if (PROJECT_SCOPE.test(content) && (CONVENTION.test(content) || DECISION.test(content))) {
+        return 'project_convention';
+    }
+    if (PERSONAL_PREFERENCE.test(content))
+        return 'user_preference';
+    if (DECISION.test(content))
+        return 'decision_made';
+    if (CONVENTION.test(content))
+        return 'project_convention';
+    return 'user_preference';
+}
+function collectProjectEvidence(projectRoot, entities) {
+    if (entities.length === 0)
+        return { evidence: [], files: [] };
+    const evidence = [];
+    const files = [];
+    const packagePath = join(projectRoot, 'package.json');
+    const packageText = readBoundedText(packagePath, MAX_PACKAGE_JSON_BYTES);
+    if (packageText !== null) {
+        const dependencyVersions = parseDependencyVersions(packageText);
+        const packageManager = parsePackageManager(packageText);
+        for (const entity of entities) {
+            for (const packageName of entity.packages ?? []) {
+                const version = dependencyVersions.get(packageName);
+                if (!version)
+                    continue;
+                addEvidence(evidence, files, projectRoot, packagePath, {
+                    kind: 'dependency',
+                    source: 'package.json',
+                    summary: `${packageName} is declared at ${version}.`,
+                });
+            }
+            if (entity.tool && packageManager?.name === entity.tool) {
+                addEvidence(evidence, files, projectRoot, packagePath, {
+                    kind: 'config',
+                    source: 'package.json',
+                    summary: `packageManager selects ${packageManager.raw}.`,
+                });
+            }
+        }
+    }
+    const lockfiles = [
+        { name: 'package-lock.json', tool: 'npm' },
+        { name: 'pnpm-lock.yaml', tool: 'pnpm' },
+        { name: 'yarn.lock', tool: 'yarn' },
+        { name: 'bun.lock', tool: 'bun' },
+        { name: 'bun.lockb', tool: 'bun' },
+    ];
+    for (const lockfile of lockfiles) {
+        const path = join(projectRoot, lockfile.name);
+        const text = readBoundedText(path, MAX_LOCKFILE_BYTES);
+        if (text === null)
+            continue;
+        for (const entity of entities) {
+            const packageMatch = (entity.packages ?? []).find(packageName => lockfileContainsPackage(text, packageName));
+            if (packageMatch) {
+                addEvidence(evidence, files, projectRoot, path, {
+                    kind: 'dependency',
+                    source: lockfile.name,
+                    summary: `${packageMatch} is resolved by ${lockfile.name}.`,
+                });
+            }
+            if (entity.tool === lockfile.tool) {
+                addEvidence(evidence, files, projectRoot, path, {
+                    kind: 'config',
+                    source: lockfile.name,
+                    summary: `${lockfile.name} confirms the ${lockfile.tool} package-manager workflow.`,
+                });
+            }
+        }
+    }
+    const configFiles = ['.devflow/config.json', 'components.json'];
+    for (const name of configFiles) {
+        collectTextEvidence(projectRoot, name, MAX_CONFIG_BYTES, 'config', entities, evidence, files);
+    }
+    const instructionFiles = ['CLAUDE.md', 'AGENTS.md', 'GEMINI.md', '.github/copilot-instructions.md'];
+    for (const name of instructionFiles) {
+        collectTextEvidence(projectRoot, name, MAX_INSTRUCTION_BYTES, 'instruction', entities, evidence, files);
+    }
+    return { evidence: dedupeEvidence(evidence), files: uniqueStrings(files) };
+}
+function collectTextEvidence(projectRoot, name, maxBytes, kind, entities, evidence, files) {
+    const path = join(projectRoot, name);
+    const text = readBoundedText(path, maxBytes);
+    if (text === null)
+        return;
+    for (const entity of entities) {
+        if (!containsAlias(text, entity.aliases))
+            continue;
+        addEvidence(evidence, files, projectRoot, path, {
+            kind,
+            source: name,
+            summary: `${name} references ${entity.canonical}.`,
+        });
+    }
+}
+function addEvidence(evidence, files, projectRoot, path, item) {
+    evidence.push(item);
+    files.push(relative(projectRoot, path) || item.source);
+}
+function parseDependencyVersions(text) {
+    try {
+        const parsed = JSON.parse(text);
+        const result = new Map();
+        for (const field of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+            const dependencies = parsed[field];
+            if (!dependencies || typeof dependencies !== 'object' || Array.isArray(dependencies))
+                continue;
+            for (const [name, version] of Object.entries(dependencies)) {
+                if (typeof version === 'string')
+                    result.set(name, version);
+            }
+        }
+        return result;
+    }
+    catch {
+        return new Map();
+    }
+}
+function parsePackageManager(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed.packageManager !== 'string')
+            return null;
+        const raw = parsed.packageManager.trim();
+        const name = raw.split('@')[0]?.toLowerCase();
+        return name ? { name, raw } : null;
+    }
+    catch {
+        return null;
+    }
+}
+function lockfileContainsPackage(text, packageName) {
+    const escaped = escapeRegExp(packageName);
+    return new RegExp(`(?:node_modules/|[/'\"\\s])${escaped}(?:@|[/'\"\\s:])`, 'iu').test(text);
+}
+function containsAlias(text, aliases) {
+    const normalized = text.normalize('NFKC').toLocaleLowerCase('en-US');
+    return aliases.some(alias => {
+        const escaped = escapeRegExp(alias.toLocaleLowerCase('en-US')).replace(/\\[\s/.-]/g, '[\\s/.-]+');
+        // ASCII technology names often touch CJK text directly, as in
+        // "使用motion作为". Only adjacent ASCII identifier characters block a match.
+        return new RegExp(`(^|[^a-z0-9_])${escaped}(?=$|[^a-z0-9_])`, 'u').test(normalized);
+    });
+}
+function readBoundedText(path, maxBytes) {
+    if (!existsSync(path))
+        return null;
+    let descriptor;
+    try {
+        descriptor = openSync(path, 'r');
+        const buffer = Buffer.allocUnsafe(maxBytes);
+        const bytesRead = readSync(descriptor, buffer, 0, maxBytes, 0);
+        return buffer.subarray(0, bytesRead).toString('utf8');
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+    }
+}
+function firstClause(value) {
+    return value.split(/[.。!！?？\n]/u)[0].trim().slice(0, 120) || 'explicit memory';
+}
+function dedupeEvidence(items) {
+    const seen = new Set();
+    return items.filter(item => {
+        const key = `${item.kind}\0${item.source}\0${item.summary}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    }).slice(0, 32);
+}
+function uniqueStrings(values) {
+    const seen = new Set();
+    const result = [];
+    for (const value of values) {
+        const normalized = value.normalize('NFKC').trim();
+        const key = normalized.toLocaleLowerCase('en-US');
+        if (!normalized || seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(normalized);
+    }
+    return result.slice(0, 32);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=explicit-memory-enricher.js.map

package/dist/explicit-memory-enricher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explicit-memory-enricher.js","sourceRoot":"","sources":["../src/explicit-memory-enricher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACpE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAmC3C,MAAM,sBAAsB,GAAG,GAAG,GAAG,IAAI,CAAC;AAC1C,MAAM,kBAAkB,GAAG,GAAG,GAAG,IAAI,CAAC;AACtC,MAAM,gBAAgB,GAAG,GAAG,GAAG,IAAI,CAAC;AACpC,MAAM,qBAAqB,GAAG,EAAE,GAAG,IAAI,CAAC;AACxC,MAAM,kBAAkB,GAAG,KAAK,CAAC;AAEjC,MAAM,QAAQ,GAAuB;IACnC;QACE,SAAS,EAAE,QAAQ;QACnB,OAAO,EAAE,CAAC,QAAQ,EAAE,eAAe,EAAE,eAAe,CAAC;QACrD,QAAQ,EAAE,CAAC,QAAQ,EAAE,eAAe,CAAC;QACrC,QAAQ,EAAE,CAAC,QAAQ,EAAE,WAAW,EAAE,eAAe,CAAC;KACnD;IACD;QACE,SAAS,EAAE,OAAO;QAClB,OAAO,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,UAAU,CAAC;QACzC,QAAQ,EAAE,CAAC,OAAO,CAAC;QACnB,QAAQ,EAAE,CAAC,OAAO,CAAC;KACpB;IACD;QACE,SAAS,EAAE,UAAU;QACrB,OAAO,EAAE,CAAC,UAAU,EAAE,cAAc,EAAE,aAAa,CAAC;QACpD,QAAQ,EAAE,CAAC,aAAa,CAAC;QACzB,QAAQ,EAAE,CAAC,UAAU,EAAE,aAAa,EAAE,KAAK,CAAC;KAC7C;IACD;QACE,SAAS,EAAE,QAAQ;QACnB,OAAO,EAAE,CAAC,QAAQ,EAAE,WAAW,EAAE,WAAW,CAAC;QAC7C,QAAQ,EAAE,CAAC,QAAQ,CAAC;QACpB,QAAQ,EAAE,CAAC,QAAQ,EAAE,eAAe,CAAC;KACtC;IACD;QACE,SAAS,EAAE,MAAM;QACjB,OAAO,EAAE,CAAC,MAAM,CAAC;QACjB,QAAQ,EAAE,CAAC,MAAM,EAAE,iBAAiB,CAAC;QACrC,IAAI,EAAE,MAAM;KACb;IACD;QACE,SAAS,EAAE,KAAK;QAChB,OAAO,EAAE,CAAC,KAAK,CAAC;QAChB,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC;QACpC,IAAI,EAAE,KAAK;KACZ;IACD;QACE,SAAS,EAAE,MAAM;QACjB,OAAO,EAAE,CAAC,MAAM,CAAC;QACjB,QAAQ,EAAE,CAAC,MAAM,EAAE,iBAAiB,CAAC;QACrC,IAAI,EAAE,MAAM;KACb;IACD;QACE,SAAS,EAAE,KAAK;QAChB,OAAO,EAAE,CAAC,KAAK,CAAC;QAChB,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC;QACpC,IAAI,EAAE,KAAK;KACZ;CACF,CAAC;AAEF,MAAM,aAAa,GAAG,8EAA8E,CAAC;AACrG,MAAM,mBAAmB,GAAG,0EAA0E,CAAC;AACvG,MAAM,QAAQ,GAAG,8CAA8C,CAAC;AAChE,MAAM,UAAU,GAAG,iJAAiJ,CAAC;AAErK,MAAM,UAAU,oBAAoB,CAAC,KAAgC;IACnE,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,kBAAkB,CAAC,CAAC;IACtF,IAAI,CAAC,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAE5E,MAAM,eAAe,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,aAAa,CAAC,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5F,MAAM,IAAI,GAAG,sBAAsB,CAAC,SAAS,CAAC,CAAC;IAC/C,MAAM,eAAe,GAAG,sBAAsB,CAAC,KAAK,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC;IACnF,MAAM,cAAc,GAAG,aAAa,CAAC,KAAK,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC9E,IAAI,EAAE,cAAuB;QAC7B,MAAM;QACN,OAAO,EAAE,yEAAyE;KACnF,CAAC,CAAC,CAAC;IACJ,MAAM,QAAQ,GAAG,cAAc,CAAC,CAAC,GAAG,eAAe,CAAC,QAAQ,EAAE,GAAG,cAAc,CAAC,CAAC,CAAC;IAClF,MAAM,QAAQ,GAAG,aAAa,CAAC,eAAe,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;IACnF,MAAM,KAAK,GAAG,aAAa,CAAC,eAAe,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACjG,MAAM,aAAa,GAAG,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjF,MAAM,WAAW,GAAG,IAAI,KAAK,oBAAoB;QAC/C,CAAC,CAAC,oBAAoB;QACtB,CAAC,CAAC,IAAI,KAAK,eAAe;YACxB,CAAC,CAAC,kBAAkB;YACpB,CAAC,CAAC,iBAAiB,CAAC;IACxB,MAAM,YAAY,GAAG,aAAa,IAAI,WAAW,CAAC,SAAS,CAAC,CAAC;IAE7D,OAAO;QACL,IAAI;QACJ,KAAK,EAAE,GAAG,WAAW,KAAK,YAAY,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;QACtD,SAAS;QACT,KAAK,EAAE,aAAa,CAAC;YACnB,SAAS;YACT,GAAG,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,sBAAsB,MAAM,CAAC,SAAS,EAAE,CAAC;SAC3E,CAAC;QACF,QAAQ;QACR,KAAK,EAAE,aAAa,CAAC,eAAe,CAAC,KAAK,CAAC;QAC3C,KAAK;QACL,cAAc,EAAE,eAAe,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,YAAY;QAC/E,QAAQ;KACT,CAAC;AACJ,CAAC;AAED,SAAS,sBAAsB,CAAC,OAAe;IAC7C,IAAI,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;QACxF,OAAO,oBAAoB,CAAC;IAC9B,CAAC;IACD,IAAI,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,iBAAiB,CAAC;IAChE,IAAI,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,eAAe,CAAC;IACnD,IAAI,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,oBAAoB,CAAC;IAC1D,OAAO,iBAAiB,CAAC;AAC3B,CAAC;AAED,SAAS,sBAAsB,CAC7B,WAAmB,EACnB,QAA4B;IAE5B,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;IAC9D,MAAM,QAAQ,GAAiC,EAAE,CAAC;IAClD,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;IACtD,MAAM,WAAW,GAAG,eAAe,CAAC,WAAW,EAAE,sBAAsB,CAAC,CAAC;IACzE,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;QACzB,MAAM,kBAAkB,GAAG,uBAAuB,CAAC,WAAW,CAAC,CAAC;QAChE,MAAM,cAAc,GAAG,mBAAmB,CAAC,WAAW,CAAC,CAAC;QACxD,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;YAC9B,KAAK,MAAM,WAAW,IAAI,MAAM,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;gBAChD,MAAM,OAAO,GAAG,kBAAkB,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;gBACpD,IAAI,CAAC,OAAO;oBAAE,SAAS;gBACvB,WAAW,CAAC,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE;oBACrD,IAAI,EAAE,YAAY;oBAClB,MAAM,EAAE,cAAc;oBACtB,OAAO,EAAE,GAAG,WAAW,mBAAmB,OAAO,GAAG;iBACrD,CAAC,CAAC;YACL,CAAC;YACD,IAAI,MAAM,CAAC,IAAI,IAAI,cAAc,EAAE,IAAI,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC;gBACxD,WAAW,CAAC,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE;oBACrD,IAAI,EAAE,QAAQ;oBACd,MAAM,EAAE,cAAc;oBACtB,OAAO,EAAE,0BAA0B,cAAc,CAAC,GAAG,GAAG;iBACzD,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,SAAS,GAAG;QAChB,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,KAAK,EAAE;QAC1C,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,EAAE;QACxC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE;QACnC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE;QACjC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,EAAE;KACnC,CAAC;IACF,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC9C,MAAM,IAAI,GAAG,eAAe,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC;QACvD,IAAI,IAAI,KAAK,IAAI;YAAE,SAAS;QAC5B,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;YAC9B,MAAM,YAAY,GAAG,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAC9D,uBAAuB,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC;YAC9C,IAAI,YAAY,EAAE,CAAC;gBACjB,WAAW,CAAC,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE;oBAC9C,IAAI,EAAE,YAAY;oBAClB,MAAM,EAAE,QAAQ,CAAC,IAAI;oBACrB,OAAO,EAAE,GAAG,YAAY,mBAAmB,QAAQ,CAAC,IAAI,GAAG;iBAC5D,CAAC,CAAC;YACL,CAAC;YACD,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,IAAI,EAAE,CAAC;gBAClC,WAAW,CAAC,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE;oBAC9C,IAAI,EAAE,QAAQ;oBACd,MAAM,EAAE,QAAQ,CAAC,IAAI;oBACrB,OAAO,EAAE,GAAG,QAAQ,CAAC,IAAI,iBAAiB,QAAQ,CAAC,IAAI,4BAA4B;iBACpF,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,WAAW,GAAG,CAAC,sBAAsB,EAAE,iBAAiB,CAAC,CAAC;IAChE,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAC/B,mBAAmB,CAAC,WAAW,EAAE,IAAI,EAAE,gBAAgB,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;IAChG,CAAC;IACD,MAAM,gBAAgB,GAAG,CAAC,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,iCAAiC,CAAC,CAAC;IACpG,KAAK,MAAM,IAAI,IAAI,gBAAgB,EAAE,CAAC;QACpC,mBAAmB,CAAC,WAAW,EAAE,IAAI,EAAE,qBAAqB,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC1G,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,cAAc,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;AAC7E,CAAC;AAED,SAAS,mBAAmB,CAC1B,WAAmB,EACnB,IAAY,EACZ,QAAgB,EAChB,IAA8B,EAC9B,QAA4B,EAC5B,QAAsC,EACtC,KAAe;IAEf,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG,eAAe,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC7C,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO;IAC1B,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC9B,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC;YAAE,SAAS;QACnD,WAAW,CAAC,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE;YAC9C,IAAI;YACJ,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE,GAAG,IAAI,eAAe,MAAM,CAAC,SAAS,GAAG;SACnD,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAClB,QAAsC,EACtC,KAAe,EACf,WAAmB,EACnB,IAAY,EACZ,IAAgC;IAEhC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpB,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC;AACzD,CAAC;AAED,SAAS,uBAAuB,CAAC,IAAY;IAC3C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAA4B,CAAC;QAC3D,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;QACzC,KAAK,MAAM,KAAK,IAAI,CAAC,cAAc,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,sBAAsB,CAAC,EAAE,CAAC;YACpG,MAAM,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;YACnC,IAAI,CAAC,YAAY,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC;gBAAE,SAAS;YAC/F,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;gBAC3D,IAAI,OAAO,OAAO,KAAK,QAAQ;oBAAE,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YAC7D,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,GAAG,EAAE,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,mBAAmB,CAAC,IAAY;IACvC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAiC,CAAC;QAChE,IAAI,OAAO,MAAM,CAAC,cAAc,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC3D,MAAM,GAAG,GAAG,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;QACzC,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;QAC9C,OAAO,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,uBAAuB,CAAC,IAAY,EAAE,WAAmB;IAChE,MAAM,OAAO,GAAG,YAAY,CAAC,WAAW,CAAC,CAAC;IAC1C,OAAO,IAAI,MAAM,CAAC,8BAA8B,OAAO,kBAAkB,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC9F,CAAC;AAED,SAAS,aAAa,CAAC,IAAY,EAAE,OAAiB;IACpD,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACrE,OAAO,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE;QAC1B,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;QAClG,8DAA8D;QAC9D,yEAAyE;QACzE,OAAO,IAAI,MAAM,CAAC,iBAAiB,OAAO,kBAAkB,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACtF,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,eAAe,CAAC,IAAY,EAAE,QAAgB;IACrD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,UAA8B,CAAC;IACnC,IAAI,CAAC;QACH,UAAU,GAAG,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACjC,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QAC5C,MAAM,SAAS,GAAG,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;QAC/D,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;YAAS,CAAC;QACT,IAAI,UAAU,KAAK,SAAS;YAAE,SAAS,CAAC,UAAU,CAAC,CAAC;IACtD,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,KAAa;IAChC,OAAO,KAAK,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,iBAAiB,CAAC;AAClF,CAAC;AAED,SAAS,cAAc,CAAC,KAAmC;IACzD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,OAAO,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE;QACzB,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC;QAC5D,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QAChC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAClB,CAAC;AAED,SAAS,aAAa,CAAC,MAAgB;IACrC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,UAAU,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;QAClD,MAAM,GAAG,GAAG,UAAU,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC;QAClD,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QAC3C,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC7B,CAAC;AAED,SAAS,YAAY,CAAC,KAAa;IACjC,OAAO,KAAK,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;AACtD,CAAC"}

package/dist/hybrid-search.d.ts

@@ -11,6 +11,8 @@ export interface SearchOptions {
     sessionId?: string;
     maxPerFailureCategory?: number;
     excludedIds?: ReadonlySet<string>;
+    requestId?: string;
+    executionId?: string;
 }
 export interface SearchResultEntry {
     id: string;
@@ -31,10 +33,30 @@ export interface SearchResultEntry {
     resolutionState: 'current' | 'resolved' | 'superseded';
     failureCategory: FailureCategory | null;
     clusterKey: string;
+    concepts: string[];
+    evidenceStatus: 'verified' | 'unverified';
 }
 export interface SearchResult {
     entry: SearchResultEntry;
     score: number;
+    applicability?: string[];
+    relevanceSignals?: {
+        semantic: number;
+        entityOverlap: number;
+        evidenceStrength: number;
+        taskApplicability: number;
+    };
+}
+export interface SearchDiagnostics {
+    threshold: number;
+    candidateCount: number;
+    selectedCount: number;
+    rejectedCount: number;
+    rejectionCategories: Record<string, number>;
+}
+export interface SearchWithDiagnosticsResult {
+    results: SearchResult[];
+    diagnostics: SearchDiagnostics;
 }
 export declare function rrfFusion(results: Map<string, {
     ranks: Map<string, number>;
@@ -49,5 +71,6 @@ export declare class HybridSearch {
     private engine;
     constructor(store: MemoryStore, embedder: EmbeddingProvider, engine?: MemoryEngine);
     search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    searchWithDiagnostics(query: string, options?: SearchOptions): Promise<SearchWithDiagnosticsResult>;
 }
 //# sourceMappingURL=hybrid-search.d.ts.map

package/dist/hybrid-search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hybrid-search.d.ts","sourceRoot":"","sources":["../src/hybrid-search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,mBAAmB,CAAC;AACrE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,0BAA0B,CAAC;AAElC,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,WAAW,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,SAAS,GAAG,UAAU,GAAG,YAAY,CAAC;IACvD,eAAe,EAAE,eAAe,GAAG,IAAI,CAAC;IACxC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,iBAAiB,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;CACf;AAcD,wBAAgB,SAAS,CACvB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,KAAK,EAAE,iBAAiB,CAAA;CAAE,CAAC,EAC9E,CAAC,EAAE,MAAM,GACR,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAkBtC;AAmED,qBAAa,YAAY;IAIrB,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,QAAQ;IAJlB,OAAO,CAAC,MAAM,CAAsB;gBAG1B,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,iBAAiB,EACnC,MAAM,CAAC,EAAE,YAAY;IAKjB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;CAwNlF"}
+{"version":3,"file":"hybrid-search.d.ts","sourceRoot":"","sources":["../src/hybrid-search.ts"],"names":[],"mappings":"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"}

package/dist/hybrid-search.js

@@ -1,4 +1,5 @@
 import { classifyFailureCategory, observationClusterKey, } from './observation-quality.js';
+import { evaluateMemoryRelevance, MEMORY_SELECTION_THRESHOLD, } from './memory-relevance.js';
 const DEFAULT_WEIGHTS = {
     bm25: 0.25,
     observationBm25: 0.2,
@@ -53,10 +54,12 @@ function rowToEntry(row) {
             title: row.title,
             narrative: row.content,
         }),
+        concepts: [],
+        evidenceStatus: row.source === 'manual' ? 'verified' : 'unverified',
     };
 }
 function observationToEntry(row) {
-    const createdAt = row.source === 'explicit_intent' && row.type === 'user_preference'
+    const createdAt = row.source === 'explicit_intent'
         ? row.explicit_accepted_at ?? row.timestamp
         : row.timestamp;
     return {
@@ -83,6 +86,8 @@ function observationToEntry(row) {
             narrative: row.narrative,
             facts: parseStringArray(row.facts),
         }),
+        concepts: parseStringArray(row.concepts),
+        evidenceStatus: row.evidence_status,
     };
 }
 const MIN_EFFECTIVE_CONFIDENCE = 0.3;
@@ -96,10 +101,22 @@ export class HybridSearch {
         this.engine = engine ?? null;
     }
     async search(query, options = {}) {
+        return (await this.searchWithDiagnostics(query, options)).results;
+    }
+    async searchWithDiagnostics(query, options = {}) {
         const requestedLimit = options.limit ?? 10;
         const limit = Number.isFinite(requestedLimit) ? Math.max(0, Math.floor(requestedLimit)) : 10;
         if (limit === 0)
-            return [];
+            return {
+                results: [],
+                diagnostics: {
+                    threshold: MEMORY_SELECTION_THRESHOLD,
+                    candidateCount: 0,
+                    selectedCount: 0,
+                    rejectedCount: 0,
+                    rejectionCategories: {},
+                },
+            };
         const exclusionAllowance = options.excludedIds?.size ?? 0;
         const fetchLimit = limit * 3 + exclusionAllowance;
         let bm25Results = [];
@@ -114,10 +131,17 @@ export class HybridSearch {
         catch { /* Observation lexical retrieval is independently non-fatal */ }
         let vectorResults = [];
         let observationResults = [];
+        const semanticScores = new Map();
         try {
             const embedding = await this.embedder.embed(query);
             vectorResults = this.store.searchVector(embedding, fetchLimit);
             observationResults = this.store.searchObservationVector(embedding, fetchLimit, options.excludedIds);
+            for (const result of vectorResults) {
+                semanticScores.set(result.id, cosineSimilarityFromDistance(result.distance));
+            }
+            for (const result of observationResults) {
+                semanticScores.set(result.observation.id, cosineSimilarityFromDistance(result.distance));
+            }
         }
         catch { /* embedding may fail */ }
         const graphIds = new Set();
@@ -207,30 +231,53 @@ export class HybridSearch {
                 continue;
             newestResolutionByCategory.set(entry.failureCategory, Math.max(newestResolutionByCategory.get(entry.failureCategory) ?? 0, entry.createdAt));
         }
-        const now = Date.now();
+        const rejected = new Map();
         const ranked = fused.map(result => {
             const entry = docs.get(result.id).entry;
-            const ageDays = Math.max(0, now - entry.createdAt) / 86_400_000;
-            const recency = Math.exp(-ageDays / 180);
-            const accessFeedback = Math.min(1, Math.log1p(entry.accessCount) / Math.log(11));
-            const projectMatch = options.scope ? (entry.scope === options.scope ? 1 : 0) : 0.5;
-            const evidenceScore = 0.28 * entry.confidence
-                + 0.22 * entry.strength
-                + 0.2 * recency
-                + 0.15 * projectMatch
-                + 0.15 * accessFeedback;
-            let score = 0.55 * result.score + 0.45 * evidenceScore;
-            if (entry.resolutionState === 'resolved')
-                score *= 0.85;
-            if (entry.resolutionState === 'superseded')
-                score *= 0.1;
             const newerResolution = entry.failureCategory
                 ? newestResolutionByCategory.get(entry.failureCategory)
                 : undefined;
-            if (entry.type !== 'error_resolution' && newerResolution && newerResolution > entry.createdAt) {
-                score *= 0.3;
+            const failureCategory = entry.type !== 'error_resolution'
+                && newerResolution
+                && newerResolution > entry.createdAt
+                ? entry.failureCategory
+                : entry.failureCategory;
+            const evaluation = evaluateMemoryRelevance({
+                query,
+                purpose: options.purpose,
+                type: entry.type,
+                source: entry.source === 'observation' ? this.store.getObservation(entry.id)?.source ?? 'distill' : entry.source,
+                title: entry.title,
+                content: entry.content,
+                concepts: entry.concepts,
+                evidenceStatus: entry.evidenceStatus,
+                confidence: entry.confidence,
+                importance: entry.strength * 10,
+                createdAt: entry.createdAt,
+                semanticScore: semanticScores.get(entry.id) ?? 0,
+                resolutionState: entry.resolutionState,
+                failureCategory,
+            });
+            if (!evaluation.eligible && evaluation.rejectionReason) {
+                rejected.set(evaluation.rejectionReason, (rejected.get(evaluation.rejectionReason) ?? 0) + 1);
+                if (options.requestId) {
+                    try {
+                        this.store.recordRetrievalAccess({
+                            sourceType: entry.source === 'observation' ? 'observation' : 'memory',
+                            sourceId: entry.id,
+                            accessType: 'rejected',
+                            sessionId: options.sessionId,
+                            requestId: options.requestId,
+                            executionId: options.executionId,
+                            query,
+                            purpose: `${options.purpose ?? 'search'}:${evaluation.rejectionReason}`,
+                            score: 0,
+                        });
+                    }
+                    catch { /* rejection telemetry is non-critical */ }
+                }
             }
-            return { ...result, score };
+            return { ...result, score: evaluation.score, evaluation };
         }).sort((left, right) => right.score - left.score
             || docs.get(right.id).entry.createdAt - docs.get(left.id).entry.createdAt
             || left.id.localeCompare(right.id));
@@ -239,7 +286,9 @@ export class HybridSearch {
         const sessionCounts = new Map();
         const failureCategoryCounts = new Map();
         const maxPerFailureCategory = Math.max(1, options.maxPerFailureCategory ?? 2);
-        for (const { id, score } of ranked) {
+        for (const { id, score, evaluation } of ranked) {
+            if (!evaluation.eligible)
+                continue;
             if (options.excludedIds?.has(id))
                 continue;
             const doc = docs.get(id);
@@ -280,18 +329,30 @@ export class HybridSearch {
                 sessionCounts.set(doc.entry.sessionId, (sessionCounts.get(doc.entry.sessionId) ?? 0) + 1);
             }
             const roundedScore = Math.round(score * 10000) / 10000;
-            results.push({ entry: doc.entry, score: roundedScore });
+            results.push({
+                entry: doc.entry,
+                score: roundedScore,
+                applicability: evaluation.applicability,
+                relevanceSignals: {
+                    semantic: evaluation.signals.semantic,
+                    entityOverlap: evaluation.signals.entityOverlap,
+                    evidenceStrength: evaluation.signals.evidenceStrength,
+                    taskApplicability: evaluation.signals.taskApplicability,
+                },
+            });
             if (options.recordAccess !== false) {
                 try {
                     this.store.recordRetrievalAccess({
                         sourceType: doc.entry.source === 'observation' ? 'observation' : 'memory',
                         sourceId: doc.entry.id,
-                        accessType: 'search_hit',
+                        accessType: 'exposed',
                         sessionId: options.sessionId,
                         query,
                         purpose: options.purpose ?? 'search',
                         rank: results.length,
                         score: roundedScore,
+                        requestId: options.requestId,
+                        executionId: options.executionId,
                     });
                 }
                 catch { /* non-critical */ }
@@ -299,9 +360,21 @@ export class HybridSearch {
             if (results.length >= limit)
                 break;
         }
-        return results;
+        return {
+            results,
+            diagnostics: {
+                threshold: MEMORY_SELECTION_THRESHOLD,
+                candidateCount: docs.size,
+                selectedCount: results.length,
+                rejectedCount: Math.max(0, docs.size - results.length),
+                rejectionCategories: Object.fromEntries(rejected),
+            },
+        };
     }
 }
+function cosineSimilarityFromDistance(distance) {
+    return Math.max(0, Math.min(1, 1 - distance));
+}
 function parseStringArray(value) {
     try {
         const parsed = JSON.parse(value);