@vinaes/succ 1.3.19

package/dist/lib/query-expansion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-expansion.js","sourceRoot":"","sources":["../../src/lib/query-expansion.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGjD,MAAM,gBAAgB,GAAG;;;;;;;;;;;qBAWJ,CAAC;AAEtB;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,KAAa,EAAE,IAAiB;IAChE,MAAM,MAAM,GAAG,gBAAgB,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IAE1D,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC;IACjC,MAAM,OAAO,GAAG,IAAI,IAAI,SAAS,CAAC,OAAO,CAAC;IAE1C,IAAI,CAAC;QACH,MAAM,cAAc,GAAG,OAAO,KAAK,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QAC/E,MAAM,QAAQ,GAAG,MAAM,OAAO,CAC5B,MAAM,EACN;YACE,SAAS,EAAE,GAAG;YACd,WAAW,EAAE,GAAG;SACjB,EACD,cAAc,CACf,CAAC;QAEF,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QAEzD,2DAA2D;QAC3D,MAAM,QAAQ,GAAG,QAAQ;aACtB,KAAK,CAAC,IAAI,CAAC;aACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,kBAAkB;aAC3E,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC;aACxD,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,oCAAoC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;aAClE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAEf,OAAO,QAAQ,CAAC;IAClB,CAAC;IAAC,MAAM,CAAC;QACP,6EAA6E;QAC7E,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/lib/readiness.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Readiness Gate — Search Confidence Assessment
+ *
+ * Assesses search result quality before returning MCP responses.
+ * Inspired by Empirica's epistemic framework (know >= 0.70 readiness gate).
+ *
+ * Non-blocking: never prevents results from being returned.
+ * Adds confidence metadata so AI agents can calibrate trust.
+ */
+import type { ReadinessGateConfig } from './config.js';
+export interface ReadinessInput {
+    similarity: number;
+    bm25Score?: number;
+    vectorScore?: number;
+    quality_score?: number;
+    access_count?: number;
+    last_accessed?: string | null;
+    created_at?: string;
+}
+export type SearchType = 'docs' | 'code' | 'memories';
+export interface ReadinessAssessment {
+    confidence: number;
+    recommendation: 'proceed' | 'warn' | 'insufficient';
+    factors: {
+        coverage: number;
+        top_similarity: number;
+        coherence: number;
+        quality_avg: number;
+        freshness: number;
+    };
+    weak_factors: string[];
+}
+export declare function assessReadiness(results: ReadinessInput[], searchType: SearchType, config?: ReadinessGateConfig): ReadinessAssessment;
+export declare function formatReadinessHeader(assessment: ReadinessAssessment): string;
+//# sourceMappingURL=readiness.d.ts.map

package/dist/lib/readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.d.ts","sourceRoot":"","sources":["../../src/lib/readiness.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAMvD,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAEtD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,SAAS,GAAG,MAAM,GAAG,cAAc,CAAC;IACpD,OAAO,EAAE;QACP,QAAQ,EAAE,MAAM,CAAC;QACjB,cAAc,EAAE,MAAM,CAAC;QACvB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAuFD,wBAAgB,eAAe,CAC7B,OAAO,EAAE,cAAc,EAAE,EACzB,UAAU,EAAE,UAAU,EACtB,MAAM,CAAC,EAAE,mBAAmB,GAC3B,mBAAmB,CAuDrB;AAMD,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,mBAAmB,GAAG,MAAM,CAkB7E"}

package/dist/lib/readiness.js

@@ -0,0 +1,142 @@
+/**
+ * Readiness Gate — Search Confidence Assessment
+ *
+ * Assesses search result quality before returning MCP responses.
+ * Inspired by Empirica's epistemic framework (know >= 0.70 readiness gate).
+ *
+ * Non-blocking: never prevents results from being returned.
+ * Adds confidence metadata so AI agents can calibrate trust.
+ */
+import { DEFAULT_READINESS_GATE_CONFIG } from './config.js';
+const MEMORY_WEIGHTS = {
+    coverage: 0.2,
+    top_similarity: 0.3,
+    coherence: 0.15,
+    quality_avg: 0.2,
+    freshness: 0.15,
+};
+const DOC_CODE_WEIGHTS = {
+    coverage: 0.3,
+    top_similarity: 0.4,
+    coherence: 0.3,
+    quality_avg: 0,
+    freshness: 0,
+};
+// ============================================================================
+// Factor calculations
+// ============================================================================
+function calcCoverage(count, expected) {
+    if (expected <= 0)
+        return count > 0 ? 1 : 0;
+    return Math.min(count / expected, 1.0);
+}
+function calcTopSimilarity(results) {
+    if (results.length === 0)
+        return 0;
+    return results[0].similarity;
+}
+function calcCoherence(results) {
+    if (results.length <= 1)
+        return results.length === 1 ? 0.5 : 0;
+    const sims = results.map((r) => r.similarity);
+    const mean = sims.reduce((a, b) => a + b, 0) / sims.length;
+    if (mean === 0)
+        return 0;
+    const variance = sims.reduce((sum, s) => sum + (s - mean) ** 2, 0) / sims.length;
+    const stddev = Math.sqrt(variance);
+    const cv = stddev / mean; // coefficient of variation
+    // cv=0 → perfect coherence (1.0), cv>=1 → no coherence (0.0)
+    return Math.max(0, Math.min(1, 1 - cv));
+}
+function calcQualityAvg(results) {
+    const withQuality = results.filter((r) => r.quality_score != null);
+    if (withQuality.length === 0)
+        return 0.5; // neutral fallback
+    return withQuality.reduce((sum, r) => sum + (r.quality_score ?? 0), 0) / withQuality.length;
+}
+function calcFreshness(results) {
+    const withAccess = results.filter((r) => r.last_accessed != null);
+    if (withAccess.length === 0)
+        return 0.5; // neutral fallback
+    const now = Date.now();
+    const HALF_LIFE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+    const FLOOR = 0.1;
+    const decays = withAccess.map((r) => {
+        const lastAccessed = new Date(r.last_accessed).getTime();
+        const age = Math.max(0, now - lastAccessed);
+        const lambda = Math.LN2 / HALF_LIFE_MS;
+        return Math.max(FLOOR, Math.exp(-lambda * age));
+    });
+    return decays.reduce((a, b) => a + b, 0) / decays.length;
+}
+// ============================================================================
+// Main assessment
+// ============================================================================
+export function assessReadiness(results, searchType, config) {
+    const thresholds = config?.thresholds ?? DEFAULT_READINESS_GATE_CONFIG.thresholds;
+    const expected = config?.expected_results ?? DEFAULT_READINESS_GATE_CONFIG.expected_results;
+    // Empty results
+    if (results.length === 0) {
+        return {
+            confidence: 0,
+            recommendation: 'insufficient',
+            factors: { coverage: 0, top_similarity: 0, coherence: 0, quality_avg: 0, freshness: 0 },
+            weak_factors: ['coverage', 'top_similarity', 'coherence'],
+        };
+    }
+    // Calculate factors
+    const factors = {
+        coverage: calcCoverage(results.length, expected),
+        top_similarity: calcTopSimilarity(results),
+        coherence: calcCoherence(results),
+        quality_avg: calcQualityAvg(results),
+        freshness: calcFreshness(results),
+    };
+    // Select weights based on search type
+    const weights = searchType === 'memories' ? MEMORY_WEIGHTS : DOC_CODE_WEIGHTS;
+    // Weighted sum
+    const confidence = weights.coverage * factors.coverage +
+        weights.top_similarity * factors.top_similarity +
+        weights.coherence * factors.coherence +
+        weights.quality_avg * factors.quality_avg +
+        weights.freshness * factors.freshness;
+    // Identify weak factors (below 0.5, with non-zero weight)
+    const weak_factors = [];
+    for (const [key, value] of Object.entries(factors)) {
+        if (weights[key] > 0 && value < 0.5) {
+            weak_factors.push(key);
+        }
+    }
+    // Recommendation
+    const proceedThreshold = thresholds.proceed ?? 0.7;
+    const warnThreshold = thresholds.warn ?? 0.4;
+    let recommendation;
+    if (confidence >= proceedThreshold) {
+        recommendation = 'proceed';
+    }
+    else if (confidence >= warnThreshold) {
+        recommendation = 'warn';
+    }
+    else {
+        recommendation = 'insufficient';
+    }
+    return { confidence, recommendation, factors, weak_factors };
+}
+// ============================================================================
+// Formatting
+// ============================================================================
+export function formatReadinessHeader(assessment) {
+    const pct = Math.round(assessment.confidence * 100);
+    if (assessment.recommendation === 'proceed') {
+        return ''; // Silent for high confidence
+    }
+    const weakStr = assessment.weak_factors.length > 0
+        ? ` Weak: ${assessment.weak_factors.map((f) => `${f} (${Math.round(assessment.factors[f] * 100)}%)`).join(', ')}`
+        : '';
+    if (assessment.recommendation === 'warn') {
+        return `> **Confidence: ${pct}%** — Limited context available.${weakStr}`;
+    }
+    // insufficient
+    return `> **Low confidence: ${pct}%** — Results may be unreliable.${weakStr}`;
+}
+//# sourceMappingURL=readiness.js.map

package/dist/lib/readiness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.js","sourceRoot":"","sources":["../../src/lib/readiness.ts"],"names":[],"mappings":"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"}

package/dist/lib/reference-embeddings.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Reference Embedding Cache — shared infrastructure for embedding-based classification.
+ *
+ * Registers named sets of reference phrases, lazily computes their embeddings on first use,
+ * and provides max-similarity queries against cached reference sets.
+ * Used by detectInvariantWithEmbedding() and estimateSpecificityByEmbedding().
+ */
+export interface ReferenceSet {
+    phrases: string[];
+    embeddings: number[][] | null;
+}
+/**
+ * Register a named set of reference phrases.
+ * Embeddings are NOT computed here — they're lazily computed on first query.
+ */
+export declare function registerReferenceSet(name: string, phrases: string[]): void;
+/**
+ * Get (or lazily compute) embeddings for a reference set.
+ */
+export declare function getReferenceEmbeddings(name: string): Promise<number[][]>;
+/**
+ * Compute max cosine similarity between a content embedding and all embeddings in a reference set.
+ * Returns 0 if the reference set is empty or embeddings can't be computed.
+ */
+export declare function maxSimilarityToReference(embedding: number[], setName: string): Promise<number>;
+/**
+ * Compute average cosine similarity between a content embedding and all embeddings in a reference set.
+ */
+export declare function avgSimilarityToReference(embedding: number[], setName: string): Promise<number>;
+/**
+ * Clear all cached reference embeddings (for tests).
+ * Keeps the registered phrases — only clears computed embeddings.
+ */
+export declare function clearReferenceCache(): void;
+/**
+ * Fully reset all reference sets (for tests).
+ */
+export declare function resetReferenceSets(): void;
+//# sourceMappingURL=reference-embeddings.d.ts.map

package/dist/lib/reference-embeddings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-embeddings.d.ts","sourceRoot":"","sources":["../../src/lib/reference-embeddings.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,MAAM,EAAE,EAAE,GAAG,IAAI,CAAC;CAC/B;AAID;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAE1E;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAS9E;AAED;;;GAGG;AACH,wBAAsB,wBAAwB,CAC5C,SAAS,EAAE,MAAM,EAAE,EACnB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CAmBjB;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,SAAS,EAAE,MAAM,EAAE,EACnB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CAoBjB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAI1C;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/lib/reference-embeddings.js

@@ -0,0 +1,95 @@
+/**
+ * Reference Embedding Cache — shared infrastructure for embedding-based classification.
+ *
+ * Registers named sets of reference phrases, lazily computes their embeddings on first use,
+ * and provides max-similarity queries against cached reference sets.
+ * Used by detectInvariantWithEmbedding() and estimateSpecificityByEmbedding().
+ */
+import { getEmbeddings, cosineSimilarity } from './embeddings.js';
+const referenceSets = new Map();
+/**
+ * Register a named set of reference phrases.
+ * Embeddings are NOT computed here — they're lazily computed on first query.
+ */
+export function registerReferenceSet(name, phrases) {
+    referenceSets.set(name, { phrases, embeddings: null });
+}
+/**
+ * Get (or lazily compute) embeddings for a reference set.
+ */
+export async function getReferenceEmbeddings(name) {
+    const set = referenceSets.get(name);
+    if (!set)
+        throw new Error(`Reference set "${name}" not registered`);
+    if (set.embeddings === null) {
+        set.embeddings = await getEmbeddings(set.phrases);
+    }
+    return set.embeddings;
+}
+/**
+ * Compute max cosine similarity between a content embedding and all embeddings in a reference set.
+ * Returns 0 if the reference set is empty or embeddings can't be computed.
+ */
+export async function maxSimilarityToReference(embedding, setName) {
+    try {
+        const refEmbeddings = await getReferenceEmbeddings(setName);
+        if (refEmbeddings.length === 0)
+            return 0;
+        let maxSim = -1;
+        for (const ref of refEmbeddings) {
+            try {
+                const sim = cosineSimilarity(embedding, ref);
+                if (sim > maxSim)
+                    maxSim = sim;
+            }
+            catch {
+                // Dimension mismatch — skip this reference
+            }
+        }
+        return maxSim > 0 ? maxSim : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Compute average cosine similarity between a content embedding and all embeddings in a reference set.
+ */
+export async function avgSimilarityToReference(embedding, setName) {
+    try {
+        const refEmbeddings = await getReferenceEmbeddings(setName);
+        if (refEmbeddings.length === 0)
+            return 0;
+        let sum = 0;
+        let count = 0;
+        for (const ref of refEmbeddings) {
+            try {
+                sum += cosineSimilarity(embedding, ref);
+                count++;
+            }
+            catch {
+                // Dimension mismatch — skip
+            }
+        }
+        return count > 0 ? sum / count : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Clear all cached reference embeddings (for tests).
+ * Keeps the registered phrases — only clears computed embeddings.
+ */
+export function clearReferenceCache() {
+    for (const set of referenceSets.values()) {
+        set.embeddings = null;
+    }
+}
+/**
+ * Fully reset all reference sets (for tests).
+ */
+export function resetReferenceSets() {
+    referenceSets.clear();
+}
+//# sourceMappingURL=reference-embeddings.js.map

package/dist/lib/reference-embeddings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-embeddings.js","sourceRoot":"","sources":["../../src/lib/reference-embeddings.ts"],"names":[],"mappings":"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"}

package/dist/lib/reflection-synthesizer.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Reflection Synthesizer
+ *
+ * Reads community clusters from the memory graph and synthesizes
+ * pattern/learning memories from unreflected observations.
+ *
+ * Plugs into daemon's handleReflection() between community detection
+ * and centrality cache update.
+ */
+import type { CommunityResult } from './graph/community-detection.js';
+export interface SynthesisResult {
+    clustersProcessed: number;
+    patternsCreated: number;
+    duplicatesSkipped: number;
+    reinforced: number;
+    observationsMarked: number;
+    errors: string[];
+}
+/**
+ * Synthesize patterns from community clusters.
+ * Only processes clusters with enough unreflected observations.
+ */
+export declare function synthesizeFromCommunities(communityResult: CommunityResult, options?: {
+    dryRun?: boolean;
+    log?: (msg: string) => void;
+}): Promise<SynthesisResult>;
+//# sourceMappingURL=reflection-synthesizer.d.ts.map

package/dist/lib/reflection-synthesizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflection-synthesizer.d.ts","sourceRoot":"","sources":["../../src/lib/reflection-synthesizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAWH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AA0BtE,MAAM,WAAW,eAAe;IAC9B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAsB,yBAAyB,CAC7C,eAAe,EAAE,eAAe,EAChC,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAO,GAC9D,OAAO,CAAC,eAAe,CAAC,CAmI1B"}

package/dist/lib/reflection-synthesizer.js

@@ -0,0 +1,149 @@
+/**
+ * Reflection Synthesizer
+ *
+ * Reads community clusters from the memory graph and synthesizes
+ * pattern/learning memories from unreflected observations.
+ *
+ * Plugs into daemon's handleReflection() between community detection
+ * and centrality cache update.
+ */
+import { callLLM } from './llm.js';
+import { getEmbedding } from './embeddings.js';
+import { saveMemory, getMemoryById, updateMemoryTags, findSimilarMemory, incrementCorrectionCount, } from './storage/index.js';
+const SYNTHESIS_PROMPT = `You are analyzing a cluster of related observations from a developer's coding sessions.
+
+Observations:
+{observations}
+
+Based on these observations, extract 1-3 high-level patterns, preferences, or learnings.
+Each should be a clear, concise statement that captures recurring behavior or important context.
+
+Rules:
+- Only output patterns that emerge from MULTIPLE observations
+- Be specific: include tool names, language preferences, workflow patterns
+- Do NOT repeat individual observations — synthesize them
+- If observations are too diverse to synthesize, output "NO_PATTERNS"
+
+Output as JSON array:
+[{"content": "...", "type": "pattern|learning"}]`;
+const MIN_CLUSTER_SIZE = 5;
+const MAX_OBSERVATIONS_PER_SYNTHESIS = 15;
+/** Semantic dedup threshold for synthesized reflections.
+ *  Lower than saveMemory's 0.92 to catch LLM paraphrases of the same insight. */
+const SYNTHESIS_DEDUP_THRESHOLD = 0.8;
+/**
+ * Synthesize patterns from community clusters.
+ * Only processes clusters with enough unreflected observations.
+ */
+export async function synthesizeFromCommunities(communityResult, options = {}) {
+    const { dryRun = false, log = () => { } } = options;
+    const result = {
+        clustersProcessed: 0,
+        patternsCreated: 0,
+        duplicatesSkipped: 0,
+        reinforced: 0,
+        observationsMarked: 0,
+        errors: [],
+    };
+    // Filter to clusters large enough to synthesize
+    const eligibleClusters = communityResult.communities.filter((c) => c.size >= MIN_CLUSTER_SIZE);
+    if (eligibleClusters.length === 0) {
+        log('[synthesizer] No clusters large enough for synthesis');
+        return result;
+    }
+    for (const cluster of eligibleClusters) {
+        try {
+            // Load memories for this cluster
+            const memories = [];
+            for (const memId of cluster.members.slice(0, MAX_OBSERVATIONS_PER_SYNTHESIS)) {
+                const mem = await getMemoryById(memId);
+                if (mem && mem.type === 'observation') {
+                    const tags = Array.isArray(mem.tags)
+                        ? mem.tags
+                        : typeof mem.tags === 'string'
+                            ? JSON.parse(mem.tags || '[]')
+                            : [];
+                    // Skip already-reflected observations
+                    if (!tags.includes('reflected')) {
+                        memories.push({ id: mem.id, content: mem.content, tags, type: mem.type });
+                    }
+                }
+            }
+            if (memories.length < MIN_CLUSTER_SIZE)
+                continue;
+            // Build observation text
+            const observationText = memories.map((m, i) => `${i + 1}. ${m.content}`).join('\n');
+            const prompt = SYNTHESIS_PROMPT.replace('{observations}', observationText);
+            const llmResponse = await callLLM(prompt, {
+                timeout: 30000,
+                useSleepAgent: true,
+                maxTokens: 1000,
+                temperature: 0.3,
+            });
+            if (llmResponse.includes('NO_PATTERNS')) {
+                log(`[synthesizer] Cluster ${cluster.id}: no patterns found`);
+                continue;
+            }
+            // Parse JSON response
+            const jsonMatch = llmResponse.match(/\[[\s\S]*?\]/);
+            if (!jsonMatch) {
+                result.errors.push(`Cluster ${cluster.id}: failed to parse LLM response`);
+                continue;
+            }
+            const patterns = JSON.parse(jsonMatch[0]);
+            result.clustersProcessed++;
+            for (const pattern of patterns) {
+                if (!pattern.content || pattern.content.length < 20)
+                    continue;
+                if (!dryRun) {
+                    const embedding = await getEmbedding(pattern.content);
+                    // Semantic dedup: check if a similar memory already exists (0.80 threshold
+                    // catches LLM paraphrases that saveMemory's 0.92 dedup would miss)
+                    const existing = await findSimilarMemory(embedding, SYNTHESIS_DEDUP_THRESHOLD);
+                    if (existing) {
+                        // Reinforce patterns/learnings — increment correction_count so they
+                        // eventually pin (Tier 1) if the daemon keeps seeing the same insight.
+                        // Skip observations — they're too noisy to reinforce automatically.
+                        const existingMem = await getMemoryById(existing.id);
+                        const existingType = existingMem?.type;
+                        if (existingType === 'pattern' || existingType === 'learning') {
+                            await incrementCorrectionCount(existing.id);
+                            result.reinforced++;
+                            log(`[synthesizer] Reinforced existing ${existingType} #${existing.id} (sim=${existing.similarity.toFixed(2)}): ${existing.content.substring(0, 60)}...`);
+                        }
+                        else {
+                            result.duplicatesSkipped++;
+                            log(`[synthesizer] Skipped duplicate ${existingType ?? 'unknown'} (sim=${existing.similarity.toFixed(2)}): ${pattern.content.substring(0, 60)}...`);
+                        }
+                        continue;
+                    }
+                    const memType = pattern.type === 'learning' ? 'learning' : 'pattern';
+                    await saveMemory(pattern.content, embedding, ['reflection', 'synthesized'], 'reflection', {
+                        qualityScore: { score: 0.7, factors: { synthesized: 1 } },
+                        type: memType,
+                    });
+                    result.patternsCreated++;
+                    log(`[synthesizer] Created ${memType}: ${pattern.content.substring(0, 80)}...`);
+                }
+            }
+            // Mark source observations as 'reflected' so they aren't re-synthesized
+            if (!dryRun) {
+                for (const mem of memories) {
+                    try {
+                        const newTags = [...mem.tags, 'reflected'];
+                        await updateMemoryTags(mem.id, newTags);
+                        result.observationsMarked++;
+                    }
+                    catch {
+                        // Non-critical — worst case we re-process next cycle
+                    }
+                }
+            }
+        }
+        catch (err) {
+            result.errors.push(`Cluster ${cluster.id}: ${err}`);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=reflection-synthesizer.js.map

package/dist/lib/reflection-synthesizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflection-synthesizer.js","sourceRoot":"","sources":["../../src/lib/reflection-synthesizer.ts"],"names":[],"mappings":"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"}

package/dist/lib/retention.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Memory Retention Policy with Decay
+ *
+ * Implements automatic memory cleanup based on:
+ * - Quality score (from quality scoring system)
+ * - Time-based decay (older memories decay in value)
+ * - Access frequency (frequently accessed memories are preserved)
+ *
+ * Formula:
+ *   effective_score = quality_score * recency_factor * access_boost
+ *
+ *   recency_factor = 1 / (1 + decay_rate * days_since_creation)
+ *   access_boost = min(1 + (access_weight * access_count), max_boost)
+ *
+ * Tiers:
+ *   - keep: effective_score >= keep_threshold (default 0.3)
+ *   - warn: effective_score >= delete_threshold && < keep_threshold
+ *   - delete: effective_score < delete_threshold (default 0.15)
+ */
+import type { MemoryForRetention } from './storage/index.js';
+export declare const DEFAULT_RETENTION_CONFIG: {
+    decay_rate: number;
+    access_weight: number;
+    max_access_boost: number;
+    keep_threshold: number;
+    delete_threshold: number;
+    default_quality_score: number;
+};
+export interface RetentionConfig {
+    decay_rate?: number;
+    access_weight?: number;
+    max_access_boost?: number;
+    keep_threshold?: number;
+    delete_threshold?: number;
+    default_quality_score?: number;
+    use_temporal_decay?: boolean;
+}
+export interface EffectiveScoreResult {
+    memoryId: number;
+    content: string;
+    qualityScore: number;
+    accessCount: number;
+    ageDays: number;
+    recencyFactor: number;
+    accessBoost: number;
+    effectiveScore: number;
+    tier: 'keep' | 'warn' | 'delete';
+}
+/**
+ * Calculate the recency factor based on age.
+ * Returns a value between 0 and 1, where 1 is brand new.
+ */
+export declare function calculateRecencyFactor(ageDays: number, decayRate: number): number;
+/**
+ * Calculate the access boost based on access count.
+ * Returns a multiplier >= 1.
+ */
+export declare function calculateAccessBoost(accessCount: number, accessWeight: number, maxBoost: number): number;
+/**
+ * Calculate the effective score for a memory.
+ */
+export declare function calculateEffectiveScore(memory: MemoryForRetention, config?: RetentionConfig): EffectiveScoreResult;
+/**
+ * Analyze all memories and categorize by retention tier.
+ */
+export declare function analyzeRetention(memories: MemoryForRetention[], config?: RetentionConfig): {
+    keep: EffectiveScoreResult[];
+    warn: EffectiveScoreResult[];
+    delete: EffectiveScoreResult[];
+    stats: RetentionStats;
+};
+export interface RetentionStats {
+    totalMemories: number;
+    keepCount: number;
+    warnCount: number;
+    deleteCount: number;
+    avgEffectiveScore: number;
+    avgQualityScore: number;
+    avgAgeDays: number;
+    avgAccessCount: number;
+    scoreDistribution: {
+        high: number;
+        medium: number;
+        low: number;
+        critical: number;
+    };
+}
+/**
+ * Calculate retention statistics.
+ */
+export declare function calculateRetentionStats(results: EffectiveScoreResult[]): RetentionStats;
+/**
+ * Format retention analysis for CLI output.
+ */
+export declare function formatRetentionAnalysis(analysis: {
+    keep: EffectiveScoreResult[];
+    warn: EffectiveScoreResult[];
+    delete: EffectiveScoreResult[];
+    stats: RetentionStats;
+}, verbose?: boolean): string;
+/**
+ * Format retention stats for MCP tool output (JSON-friendly).
+ */
+export declare function formatRetentionStatsForMcp(stats: RetentionStats): string;
+//# sourceMappingURL=retention.d.ts.map

package/dist/lib/retention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention.d.ts","sourceRoot":"","sources":["../../src/lib/retention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAQ7D,eAAO,MAAM,wBAAwB;;;;;;;CAmBpC,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAE/B,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,GACf,MAAM,CAER;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,kBAAkB,EAC1B,MAAM,GAAE,eAAoB,GAC3B,oBAAoB,CAmEtB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,kBAAkB,EAAE,EAC9B,MAAM,GAAE,eAAoB,GAC3B;IACD,IAAI,EAAE,oBAAoB,EAAE,CAAC;IAC7B,IAAI,EAAE,oBAAoB,EAAE,CAAC;IAC7B,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAC/B,KAAK,EAAE,cAAc,CAAC;CACvB,CAeA;AAED,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IAEvB,iBAAiB,EAAE;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,EAAE,MAAM,CAAC;QACZ,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,cAAc,CA0CvF;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE;IACR,IAAI,EAAE,oBAAoB,EAAE,CAAC;IAC7B,IAAI,EAAE,oBAAoB,EAAE,CAAC;IAC7B,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAC/B,KAAK,EAAE,cAAc,CAAC;CACvB,EACD,OAAO,GAAE,OAAe,GACvB,MAAM,CAiER;AAOD;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAoBxE"}