@massa-ai/core 1.2.1

package/dist/services/memory/redundancy-filter.js

@@ -0,0 +1,93 @@
+/** PostgreSQL-backed duplicate detection and consolidation for memories. */
+import { logger } from "@massa-ai/shared";
+import { getPrismaClient } from "../query/prisma-client.js";
+import { TokenMetrics } from "../metrics/token-metrics.js";
+export class RedundancyFilter {
+    static instance = null;
+    static getInstance() { return this.instance ??= new RedundancyFilter(); }
+    async findDuplicates(threshold = 0.95, scanLimit = 300) {
+        const rows = await getPrismaClient().$queryRaw `
+      SELECT id, content, type, level, importance, array_to_json(tags)::text AS tags, embedding,
+        created_at, updated_at, access_count, user_id, session_id, project_id, agent_id
+      FROM memories WHERE embedding IS NOT NULL AND deleted_at IS NULL
+      ORDER BY created_at DESC LIMIT ${scanLimit}`;
+        const groups = new Map();
+        for (const row of rows) {
+            if (!row.embedding)
+                continue;
+            const bytes = Buffer.from(row.embedding);
+            const vector = new Float32Array(bytes.buffer, bytes.byteOffset, Math.floor(bytes.byteLength / 4));
+            let norm = 0;
+            for (const value of vector)
+                norm += value * value;
+            norm = Math.sqrt(norm);
+            if (!norm)
+                continue;
+            const group = groups.get(row.type) ?? [];
+            group.push({ row, vector, norm });
+            groups.set(row.type, group);
+        }
+        const pairs = [];
+        const removed = new Set();
+        for (const group of groups.values())
+            for (let left = 0; left < group.length; left++)
+                for (let right = left + 1; right < group.length; right++) {
+                    const a = group[left];
+                    const b = group[right];
+                    if (removed.has(a.row.id) || removed.has(b.row.id) || a.vector.length !== b.vector.length)
+                        continue;
+                    let dot = 0;
+                    for (let index = 0; index < a.vector.length; index++)
+                        dot += a.vector[index] * b.vector[index];
+                    const similarity = dot / (a.norm * b.norm);
+                    if (similarity < threshold)
+                        continue;
+                    const keep = a.row.importance !== b.row.importance ? (a.row.importance > b.row.importance ? a : b) : a.row.access_count >= b.row.access_count ? a : b;
+                    const drop = keep === a ? b : a;
+                    removed.add(drop.row.id);
+                    pairs.push({ keepId: keep.row.id, removeId: drop.row.id, similarity, reason: keep.row.importance !== drop.row.importance ? "Higher importance" : "Higher access count" });
+                }
+        return pairs;
+    }
+    async mergeDuplicates(pairs) {
+        if (!pairs.length)
+            return { merged: 0, edgesTransferred: 0, accessCountsBoosted: 0 };
+        const prisma = getPrismaClient();
+        let merged = 0;
+        let edgesTransferred = 0;
+        let accessCountsBoosted = 0;
+        await prisma.$transaction(async (tx) => {
+            for (const pair of pairs) {
+                const rows = await tx.$queryRaw `SELECT content, access_count FROM memories WHERE id = ${pair.removeId} FOR UPDATE`;
+                if (!rows[0])
+                    continue;
+                const moved = await tx.$executeRaw `
+          INSERT INTO memory_edges (from_id, to_id, edge_type, weight, metadata, created_at, updated_at)
+          SELECT CASE WHEN from_id = ${pair.removeId} THEN ${pair.keepId} ELSE from_id END,
+                 CASE WHEN to_id = ${pair.removeId} THEN ${pair.keepId} ELSE to_id END,
+                 edge_type, weight, metadata, NOW(), NOW()
+          FROM memory_edges WHERE (from_id = ${pair.removeId} OR to_id = ${pair.removeId})
+            AND from_id <> ${pair.keepId} AND to_id <> ${pair.keepId}
+          ON CONFLICT (from_id, to_id, edge_type) DO UPDATE SET weight = GREATEST(memory_edges.weight, EXCLUDED.weight), updated_at = NOW()`;
+                await tx.$executeRaw `DELETE FROM memory_edges WHERE from_id = ${pair.removeId} OR to_id = ${pair.removeId}`;
+                await tx.$executeRaw `UPDATE memories SET access_count = access_count + ${rows[0].access_count}, updated_at = NOW() WHERE id = ${pair.keepId}`;
+                await tx.$executeRaw `DELETE FROM memories WHERE id = ${pair.removeId}`;
+                TokenMetrics.getInstance().recordRedundancyFilterSavings(rows[0].content);
+                merged++;
+                edgesTransferred += Number(moved);
+                if (rows[0].access_count > 0)
+                    accessCountsBoosted++;
+            }
+        });
+        logger.info("RedundancyFilter: merge complete", { merged, edgesTransferred, accessCountsBoosted });
+        return { merged, edgesTransferred, accessCountsBoosted };
+    }
+    async runCleanup(threshold = 0.95) {
+        const start = Date.now();
+        const pairs = await this.findDuplicates(threshold);
+        const result = await this.mergeDuplicates(pairs);
+        return { duplicatesFound: pairs.length, merged: result.merged, edgesTransferred: result.edgesTransferred, durationMs: Date.now() - start };
+    }
+    close() { RedundancyFilter.instance = null; }
+}
+//# sourceMappingURL=redundancy-filter.js.map

package/dist/services/memory/redundancy-filter.js.map

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

package/dist/services/memory/salience-judge.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Salience Judge (Phase 7b, plan item 7b).
+ *
+ * Scores the importance/salience (∈ [0,1]) of a memory's content + type, for
+ * the `MemoryController.store` path when the caller omits `importance`. The
+ * scored value IS the `salience` input to Phase-1 `decayScore` (the memories
+ * table `importance` column already drives decay).
+ *
+ * Contract (cross-cutting §1 + spec R7B-01..04):
+ *   - Default-off via `config.memory.autoImportance.enabled`.
+ *   - Silent degradation: on `!isLlmEnabled()`, `{ok:false}`, or any throw,
+ *     returns the neutral default 0.5. Never throws to the caller (store()).
+ *   - Embedding-independence: scores from content only — the Phase-4/5/6 FTS-only
+ *     seed memories (embedding:[]) are scored identically.
+ *   - Truncates very-long content to the LLM context budget before scoring.
+ *
+ * Pure over inputs + the injected LLM surface, so tests inject fakes without
+ * touching config or network (design.md §7).
+ */
+import { z } from "zod";
+import type { MemoryType } from "@massa-ai/shared";
+import type { QueryLlmSurface } from "../search/query-understanding.js";
+export declare const SalienceSchema: z.ZodObject<{
+    importance: z.ZodNumber;
+}, z.core.$strip>;
+export type Salience = z.infer<typeof SalienceSchema>;
+/** Neutral default returned on every degradation path. */
+export declare const NEUTRAL_SALIENCE = 0.5;
+/**
+ * Stateful handle bundling scoreSalience. Stateless; the `llm` surface is
+ * injectable for tests.
+ */
+export declare class SalienceJudge {
+    private readonly llm;
+    constructor(llm?: QueryLlmSurface);
+    /**
+     * Score salience ∈ [0,1] for the given content + memory type.
+     *
+     * - When `!isLlmEnabled()` OR `autoImportance.enabled` is false OR `{ok:false}`
+     *   OR throw → returns `NEUTRAL_SALIENCE` (0.5). Logged at warn on failure.
+     * - Empty/whitespace content → neutral (no signal to score).
+     */
+    scoreSalience(content: string, type: MemoryType): Promise<{
+        salience: number;
+        source: "llm" | "default";
+    }>;
+}
+export declare function getSalienceJudge(): SalienceJudge;
+/** Test seam: override the module-level judge. */
+export declare function _setSalienceJudgeForTesting(judge: SalienceJudge | null): void;
+//# sourceMappingURL=salience-judge.d.ts.map

package/dist/services/memory/salience-judge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"salience-judge.d.ts","sourceRoot":"","sources":["../../../src/services/memory/salience-judge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAKxE,eAAO,MAAM,cAAc;;iBAEzB,CAAC;AAEH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAItD,0DAA0D;AAC1D,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAMpC;;;GAGG;AACH,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,GAAE,eAAkC;IAEpE;;;;;;OAMG;IACG,aAAa,CACjB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,UAAU,GACf,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,KAAK,GAAG,SAAS,CAAA;KAAE,CAAC;CAsC5D;AAOD,wBAAgB,gBAAgB,IAAI,aAAa,CAGhD;AACD,kDAAkD;AAClD,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,GAAG,IAAI,CAE7E"}

package/dist/services/memory/salience-judge.js

@@ -0,0 +1,115 @@
+/**
+ * Salience Judge (Phase 7b, plan item 7b).
+ *
+ * Scores the importance/salience (∈ [0,1]) of a memory's content + type, for
+ * the `MemoryController.store` path when the caller omits `importance`. The
+ * scored value IS the `salience` input to Phase-1 `decayScore` (the memories
+ * table `importance` column already drives decay).
+ *
+ * Contract (cross-cutting §1 + spec R7B-01..04):
+ *   - Default-off via `config.memory.autoImportance.enabled`.
+ *   - Silent degradation: on `!isLlmEnabled()`, `{ok:false}`, or any throw,
+ *     returns the neutral default 0.5. Never throws to the caller (store()).
+ *   - Embedding-independence: scores from content only — the Phase-4/5/6 FTS-only
+ *     seed memories (embedding:[]) are scored identically.
+ *   - Truncates very-long content to the LLM context budget before scoring.
+ *
+ * Pure over inputs + the injected LLM surface, so tests inject fakes without
+ * touching config or network (design.md §7).
+ */
+import { z } from "zod";
+import { config, logger } from "@massa-ai/shared";
+import { llm as defaultLlmHandle } from "./llm-client.js";
+// ─── Zod schema ────────────────────────────────────────────────────────────────
+export const SalienceSchema = z.object({
+    importance: z.number().min(0).max(1),
+});
+// ─── Defaults ──────────────────────────────────────────────────────────────────
+/** Neutral default returned on every degradation path. */
+export const NEUTRAL_SALIENCE = 0.5;
+/** Truncate content before the LLM call to bound prompt size. */
+const CONTENT_TRUNCATE_CHARS = 2000;
+// ─── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Stateful handle bundling scoreSalience. Stateless; the `llm` surface is
+ * injectable for tests.
+ */
+export class SalienceJudge {
+    llm;
+    constructor(llm = defaultLlmHandle) {
+        this.llm = llm;
+    }
+    /**
+     * Score salience ∈ [0,1] for the given content + memory type.
+     *
+     * - When `!isLlmEnabled()` OR `autoImportance.enabled` is false OR `{ok:false}`
+     *   OR throw → returns `NEUTRAL_SALIENCE` (0.5). Logged at warn on failure.
+     * - Empty/whitespace content → neutral (no signal to score).
+     */
+    async scoreSalience(content, type) {
+        const memCfg = config.get("memory");
+        if (!memCfg.autoImportance?.enabled) {
+            return { salience: NEUTRAL_SALIENCE, source: "default" };
+        }
+        if (!this.llm.isEnabled()) {
+            return { salience: NEUTRAL_SALIENCE, source: "default" };
+        }
+        const trimmed = (content ?? "").trim();
+        if (trimmed.length === 0) {
+            return { salience: NEUTRAL_SALIENCE, source: "default" };
+        }
+        const prompt = buildPrompt(trimmed, type);
+        let verdict;
+        try {
+            const res = await this.llm.object(prompt, SalienceSchema);
+            verdict = res.ok ? (res.value ?? null) : null;
+        }
+        catch (e) {
+            logger.warn("SalienceJudge threw — degrading to neutral default", {
+                type,
+                error: e.message,
+            });
+            return { salience: NEUTRAL_SALIENCE, source: "default" };
+        }
+        if (!verdict) {
+            logger.warn("SalienceJudge got {ok:false} — degrading to neutral default", {
+                type,
+            });
+            return { salience: NEUTRAL_SALIENCE, source: "default" };
+        }
+        // Clamp defensively (zod already bounds 0..1, but be robust to {value} cast).
+        const clamped = Math.max(0, Math.min(1, verdict.importance));
+        return { salience: clamped, source: "llm" };
+    }
+}
+/**
+ * Module-level convenience wrapper for the default-configured judge. Kept thin
+ * so MemoryController can swap a fake via ctor DI in tests.
+ */
+let activeJudge = null;
+export function getSalienceJudge() {
+    if (!activeJudge)
+        activeJudge = new SalienceJudge();
+    return activeJudge;
+}
+/** Test seam: override the module-level judge. */
+export function _setSalienceJudgeForTesting(judge) {
+    activeJudge = judge;
+}
+// ─── Helpers ───────────────────────────────────────────────────────────────────
+function buildPrompt(content, type) {
+    const slice = content.slice(0, CONTENT_TRUNCATE_CHARS);
+    return [
+        "You are scoring memory salience for a long-term memory system.",
+        "Score the importance of the following memory on a 0..1 scale, where 1 is",
+        "highly reusable/critical and 0 is trivial/ephemeral. Consider decision-impact,",
+        "reusability across future tasks, and rarity of the information.",
+        "Return ONLY a JSON object {\"importance\": number} with importance in [0,1].",
+        "",
+        `Memory type: ${type}`,
+        "",
+        "Content:",
+        slice,
+    ].join("\n");
+}
+//# sourceMappingURL=salience-judge.js.map

package/dist/services/memory/salience-judge.js.map

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

package/dist/services/metrics/token-metrics.d.ts

@@ -0,0 +1,114 @@
+export interface ModelPricing {
+    input: number;
+    output: number;
+}
+export interface TokenSavingsBreakdown {
+    /** Tokens saved by session file cache (diff-only + reference tokens) */
+    sessionCache: number;
+    /** Tokens saved by redundancy filter (deduplicated memories) */
+    redundancyFilter: number;
+    /** Tokens saved by context compression */
+    compression: number;
+    /** Total tokens saved across all optimizations */
+    total: number;
+}
+export interface TokenMetricsStats {
+    /** Breakdown of token savings by source */
+    savings: TokenSavingsBreakdown;
+    /** Total tokens processed (input to optimization pipeline) */
+    totalTokensProcessed: number;
+    /** Total tokens delivered (output after optimizations) */
+    totalTokensDelivered: number;
+    /** Overall compression ratio (0-1, higher = more savings) */
+    overallCompressionRatio: number;
+    /** Number of context requests served */
+    requestsServed: number;
+    /** Estimated cost savings in USD (based on model pricing) */
+    estimatedCostSavings: number;
+    /** Model used for cost estimation */
+    model: string;
+}
+export interface TokenMetricsTimeSeries {
+    timestamp: number;
+    savings: TokenSavingsBreakdown;
+    compressionRatio: number;
+}
+/**
+ * Singleton token metrics collector with models.dev integration.
+ */
+export declare class TokenMetrics {
+    private static instance;
+    private readonly counters;
+    private totalTokensProcessed;
+    private totalTokensDelivered;
+    private requestsServed;
+    /** Time-series history for tracking trends */
+    private readonly history;
+    /** Pricing cache: model ID -> pricing data */
+    private readonly pricingCache;
+    private constructor();
+    static getInstance(): TokenMetrics;
+    /**
+     * Get model pricing from models.dev API with caching and fallback.
+     *
+     * @param modelId - Model identifier (e.g., "gpt-4", "claude-3-5-sonnet")
+     * @returns Pricing data or fallback if unavailable
+     */
+    getModelPricing(modelId: string): Promise<ModelPricing>;
+    /**
+     * Calculate cost savings for a given model.
+     *
+     * @param tokensSaved - Number of tokens saved
+     * @param modelId - Model identifier for pricing lookup
+     * @returns Cost savings in USD
+     */
+    calculateCostSavings(tokensSaved: number, modelId?: string): Promise<number>;
+    /**
+     * Record tokens saved by session file cache.
+     * Called from SessionFileCache.check() when returning unchanged/changed chunks.
+     */
+    recordSessionCacheSavings(tokensSaved: number): void;
+    /**
+     * Record tokens saved by redundancy filter.
+     * Called from RedundancyFilter.merge() after deduplicating memories.
+     *
+     * @param removedContent - Content of the removed duplicate memory
+     */
+    recordRedundancyFilterSavings(removedContent: string): void;
+    /**
+     * Record tokens saved by context compression.
+     * Called from ContextController after compression.
+     */
+    recordCompressionSavings(originalTokens: number, compressedTokens: number): void;
+    /**
+     * Record a complete context request with all metrics.
+     * Called from ContextController.getOptimizedContext().
+     */
+    recordContextRequest(tokensProcessed: number, tokensDelivered: number, sessionCacheSavings?: number, compressionSavings?: number): void;
+    /**
+     * Get current token metrics statistics.
+     *
+     * @param modelId - Model identifier for cost estimation (defaults to "gpt-4")
+     */
+    getStats(modelId?: string): Promise<TokenMetricsStats>;
+    /**
+     * Get time-series history of token savings.
+     * Useful for charting trends over time.
+     */
+    getHistory(): TokenMetricsTimeSeries[];
+    /**
+     * Get the most recent N history entries.
+     */
+    getRecentHistory(limit?: number): TokenMetricsTimeSeries[];
+    /**
+     * Reset all counters (useful for testing).
+     */
+    reset(): void;
+    /**
+     * Get a human-readable summary of token savings.
+     *
+     * @param modelId - Model identifier for cost estimation (defaults to "gpt-4")
+     */
+    getSummary(modelId?: string): Promise<string>;
+}
+//# sourceMappingURL=token-metrics.d.ts.map

package/dist/services/metrics/token-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-metrics.d.ts","sourceRoot":"","sources":["../../../src/services/metrics/token-metrics.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,wEAAwE;IACxE,YAAY,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,gBAAgB,EAAE,MAAM,CAAC;IACzB,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,OAAO,EAAE,qBAAqB,CAAC;IAC/B,8DAA8D;IAC9D,oBAAoB,EAAE,MAAM,CAAC;IAC7B,0DAA0D;IAC1D,oBAAoB,EAAE,MAAM,CAAC;IAC7B,6DAA6D;IAC7D,uBAAuB,EAAE,MAAM,CAAC;IAChC,wCAAwC;IACxC,cAAc,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,oBAAoB,EAAE,MAAM,CAAC;IAC7B,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,qBAAqB,CAAC;IAC/B,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAmCD;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA6B;IAEpD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAIvB;IAEF,OAAO,CAAC,oBAAoB,CAAK;IACjC,OAAO,CAAC,oBAAoB,CAAK;IACjC,OAAO,CAAC,cAAc,CAAK;IAE3B,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IAExD,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmE;IAEhG,OAAO;IAEP,MAAM,CAAC,WAAW,IAAI,YAAY;IASlC;;;;;OAKG;IACG,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAkE7D;;;;;;OAMG;IACG,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,MAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;IAQ3F;;;OAGG;IACH,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAKpD;;;;;OAKG;IACH,6BAA6B,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI;IAM3D;;;OAGG;IACH,wBAAwB,CAAC,cAAc,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,IAAI;IAMhF;;;OAGG;IACH,oBAAoB,CAClB,eAAe,EAAE,MAAM,EACvB,eAAe,EAAE,MAAM,EACvB,mBAAmB,GAAE,MAAU,EAC/B,kBAAkB,GAAE,MAAU,GAC7B,IAAI;IA8CP;;;;OAIG;IACG,QAAQ,CAAC,OAAO,GAAE,MAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA6BrE;;;OAGG;IACH,UAAU,IAAI,sBAAsB,EAAE;IAItC;;OAEG;IACH,gBAAgB,CAAC,KAAK,GAAE,MAAY,GAAG,sBAAsB,EAAE;IAI/D;;OAEG;IACH,KAAK,IAAI,IAAI;IAWb;;;;OAIG;IACG,UAAU,CAAC,OAAO,GAAE,MAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;CAkB7D"}