@massa-ai/core 1.2.1

package/dist/controllers/memory-controller.js

@@ -0,0 +1,232 @@
+/**
+ * Memory Controller
+ *
+ * Orchestration layer for memory operations.
+ * Composes MemoryRepository, MemoryService, MemoryGraphService,
+ * and the consolidation job.
+ *
+ * Tools (store_memory, search_memories) delegate here.
+ * This is the single entry point for all memory use cases.
+ */
+import { logger } from "@massa-ai/shared";
+import { getMemoryRepository } from "../data/memory/memory-repository-factory.js";
+import { MemoryService, } from "../services/memory/memory-service.js";
+import { MemoryGraphService } from "../services/graph/memory-graph.service.js";
+import { memoryConsolidationJob } from "../services/jobs/memory-consolidation-job.js";
+import { getSalienceJudge } from "../services/memory/salience-judge.js";
+import { eventBus } from "../services/events/event-bus.js";
+// ── Controller ───────────────────────────────────────────────
+export class MemoryController {
+    static instance = null;
+    repo;
+    service;
+    graph;
+    constructor() {
+        this.repo = getMemoryRepository();
+        this.service = MemoryService.getInstance();
+        this.graph = MemoryGraphService.getInstance();
+    }
+    static getInstance() {
+        if (!MemoryController.instance) {
+            MemoryController.instance = new MemoryController();
+        }
+        return MemoryController.instance;
+    }
+    // ── Store ──────────────────────────────────────────────────
+    async store(input) {
+        const { content, type, userId, sessionId, projectId, agentId, tags = [], linkTo = [], } = input;
+        // Phase 7b: auto-importance/salience. Caller-wins: an EXPLICIT importance
+        // (including 0) is never overridden. Only an OMITTED importance triggers
+        // auto-scoring (LLM-on) or the 0.5 neutral default (LLM-off/feature-off).
+        let importance;
+        let salienceSource = "default";
+        if (input.importance !== undefined) {
+            importance = input.importance;
+        }
+        else {
+            const judged = await getSalienceJudge().scoreSalience(content, type);
+            importance = judged.salience;
+            salienceSource = judged.source;
+        }
+        // 1. Domain logic: generate ID and determine level
+        const id = this.service.generateId(type, userId);
+        const level = this.service.determineLevel(type, {
+            userId,
+            sessionId,
+            projectId,
+            agentId,
+        });
+        // 2. Generate embedding (async)
+        const embedding = await this.service.generateEmbedding(content);
+        // 3. Persist via repository
+        await this.repo.insert({
+            id,
+            content,
+            type,
+            level,
+            userId,
+            sessionId,
+            projectId,
+            agentId,
+            importance,
+            tags,
+            embedding,
+            metadata: { type, importance, agentId },
+        });
+        // Phase 7b: emit salience-scored only when auto-scoring ran (importance was
+        // omitted). Published after repo.insert succeeds so the memoryId exists.
+        if (input.importance === undefined) {
+            eventBus.publish("memory:salience-scored", {
+                memoryId: id,
+                projectId,
+                salience: importance,
+                source: salienceSource,
+            });
+        }
+        logger.info("Memory stored", {
+            id,
+            type,
+            level,
+            importance,
+            hasUserId: !!userId,
+            hasSessionId: !!sessionId,
+            hasProjectId: !!projectId,
+            agentId: agentId || "unknown",
+        });
+        // 4. Background side-effects (non-blocking)
+        memoryConsolidationJob.maybeRun("store");
+        void this.graph.onMemoryStored(id, linkTo);
+        return { memoryId: id, stored: "local", level, type };
+    }
+    // ── Update ────────────────────────────────────────────────
+    async update(input) {
+        const { id, content, importance, tags, mergeTags = false } = input;
+        if (content !== undefined && content.trim().length === 0) {
+            throw new Error("content must not be empty");
+        }
+        const existing = await this.repo.getById(id);
+        if (!existing) {
+            return { id, updated: false };
+        }
+        // Resolve tags: merge with existing or replace.
+        let resolvedTags;
+        if (tags !== undefined) {
+            let current = [];
+            try {
+                current = existing.tags ? JSON.parse(existing.tags) : [];
+            }
+            catch {
+                current = [];
+            }
+            resolvedTags = mergeTags
+                ? Array.from(new Set([...current, ...tags]))
+                : [...tags];
+        }
+        // Re-embed when content changes; leave embedding untouched otherwise.
+        let embedding;
+        if (content !== undefined) {
+            embedding = await this.service.generateEmbedding(content);
+        }
+        const updated = await this.repo.update(id, {
+            content,
+            importance,
+            tags: resolvedTags,
+            embedding,
+        });
+        if (!updated) {
+            return { id, updated: false };
+        }
+        const memory = await this.repo.getById(id);
+        logger.info("Memory updated", { id, fields: Object.keys(input).filter((k) => k !== "id") });
+        if (!memory) {
+            return { id, updated: true };
+        }
+        // Never return the embedding blob to clients.
+        const { embedding: _embedding, ...memoryWithoutEmbedding } = memory;
+        void _embedding;
+        return { id, updated: true, memory: memoryWithoutEmbedding };
+    }
+    // ── Delete ────────────────────────────────────────────────
+    async delete(id) {
+        const deleted = await this.repo.deleteById(id);
+        if (deleted) {
+            // Sever graph edges (best-effort; never fails the delete).
+            void this.graph.onMemoryDeleted(id);
+            logger.info("Memory deleted", { id });
+        }
+        return { id, deleted };
+    }
+    // ── Search ─────────────────────────────────────────────────
+    async search(input) {
+        const { query, userId, sessionId, projectId, agentId, types, minImportance = 0.3, limit = 10, includePersistent = true, includeRelated = false, } = input;
+        logger.info("Searching memories", {
+            query: query.slice(0, 50),
+            hasUserId: !!userId,
+            hasSessionId: !!sessionId,
+            hasProjectId: !!projectId,
+            agentId: agentId || "any",
+            limit,
+        });
+        // 1. Generate query embedding
+        const queryEmbedding = await this.service.generateEmbedding(query);
+        // 2. FTS pre-filter via repository (with scope filters)
+        const ftsRows = await this.repo.fullTextSearch(query, limit * 3, {
+            userId,
+            sessionId,
+            projectId,
+            agentId,
+            minImportance,
+            types,
+        });
+        logger.info("FTS search completed", {
+            foundResults: ftsRows.length,
+            query: query.slice(0, 30),
+        });
+        // 3. Map to domain objects
+        const memories = ftsRows.map((row) => this.service.rowToMemory(row));
+        // 4. Semantic ranking
+        const hasValidEmbedding = queryEmbedding.some((v) => v !== 0);
+        const rankedResults = hasValidEmbedding
+            ? this.service.semanticRank(memories, queryEmbedding, limit)
+            : memories
+                .slice(0, limit)
+                .map((m) => ({ ...m, score: 1.0 }));
+        logger.info("Ranking completed", {
+            resultsCount: rankedResults.length,
+            usedSemanticRanking: hasValidEmbedding,
+            firstScore: rankedResults[0]?.score,
+        });
+        // 5. Update access counts
+        await Promise.all(rankedResults.map((r) => this.repo.incrementAccessCount(r.id)));
+        // 6. Background consolidation (non-blocking)
+        memoryConsolidationJob.maybeRun("search");
+        // 7. Graph enrichment
+        let relatedSummaries = {};
+        if (includeRelated && rankedResults.length > 0) {
+            try {
+                for (const mem of rankedResults.slice(0, 3)) {
+                    const summary = await this.graph.getNeighborhoodSummary(mem.id);
+                    if (summary) {
+                        relatedSummaries[mem.id] = summary;
+                    }
+                }
+            }
+            catch (err) {
+                logger.warn("Graph enrichment failed", {
+                    error: err.message,
+                });
+            }
+        }
+        logger.info("Memories found", {
+            total: rankedResults.length,
+            topScore: rankedResults[0]?.score || 0,
+        });
+        return {
+            memories: rankedResults,
+            relatedSummaries,
+            query,
+            total: rankedResults.length,
+        };
+    }
+}
+//# sourceMappingURL=memory-controller.js.map

package/dist/controllers/memory-controller.js.map

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

package/dist/controllers/search-controller.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Search Controller
+ *
+ * Orchestration layer for project search operations.
+ * Extracts preview generation, glob filtering, and auto-reindex
+ * coordination from the SearchProjectTool.
+ */
+import { ContextualSearchRLM } from "../services/search/contextual-search-rlm.js";
+import type { SearchDegradation } from "../services/search/search-diagnostics.js";
+import type { FilterDowngrade } from "../services/search/filter-validation.js";
+export interface ProjectSearchInput {
+    query: string;
+    projectId: string;
+    projectPath?: string;
+    maxResults?: number;
+    minScore?: number;
+    responseMode?: "summary" | "full" | "enriched";
+    autoReindex?: boolean;
+    include?: string[];
+    exclude?: string[];
+    explainScores?: boolean;
+    /**
+     * Files to boost in ranking (from Symbol Graph prefilter).
+     * Results whose filePath is in this list get score * 1.3.
+     */
+    boostFiles?: string[];
+    sessionId?: string;
+}
+export interface ProjectSearchResult {
+    query: string;
+    projectId: string;
+    responseMode: string;
+    tokenSavings: string;
+    indexStatus: any;
+    recommendations: string[];
+    filters: {
+        applied: boolean;
+        include: string[];
+        exclude: string[];
+        totalResults: number;
+        filteredResults: number;
+    };
+    results: FormattedResult[];
+    /**
+     * N4 (WAVE4-N4): pre-clamp reachable count, post-clamp shown, omitted.
+     * `results_total` is the count of results that survived admission + search +
+     * glob filtering (the reachable set) BEFORE the final `.slice(0, maxResults)`
+     * clamps the displayed page. `results_shown` is the displayed page length.
+     * `results_omitted = results_total - results_shown`.
+     * Spec AC 3 — emitted at the top level (not centralized in serializeToolResponse
+     * per the M36 contract; per-tool is the existing convention).
+     */
+    results_total: number;
+    results_shown: number;
+    results_omitted: number;
+    /**
+     * Admission preflight warning (Tier 2). Present only when the project is
+     * indexed but `isIndexStale` flagged it (files_changed / path_mismatch /
+     * age_threshold). Search still ran; callers MAY surface this to the user.
+     * Absent when fresh, or when no projectPath was supplied (stale check skipped).
+     */
+    warning?: string;
+    stale?: {
+        reason: string;
+        modifiedFiles?: number;
+        newFiles?: number;
+        deletedFiles?: number;
+    };
+    /** Optional subsystems that failed without invalidating mandatory retrieval. */
+    degradations?: SearchDegradation[];
+    /**
+     * Wave 5 FR-18 / AD-W5-012: filter downgrade records. Present only when
+     * `validateFilters` reconciled a contradiction (same pattern in both
+     * include and exclude). The exclude entry is dropped (never both) and the
+     * record is emitted here so the caller can correct its hints. Additive —
+     * absent when no downgrades occurred.
+     */
+    filter_downgrades?: FilterDowngrade[];
+}
+interface FormattedResult {
+    id: string;
+    score: number;
+    filePath: string;
+    lineStart?: number;
+    lineEnd?: number;
+    language?: string;
+    preview: string;
+    explanation?: string;
+    content?: string;
+    parentSymbol?: string;
+    fileImports?: string;
+    chunkIndex?: number;
+    totalChunks?: number;
+}
+export declare class SearchController {
+    private static instance;
+    private contextualSearch;
+    private constructor();
+    static getInstance(): SearchController;
+    /** Expose the underlying search engine for direct use by ContextController. */
+    getSearchEngine(): ContextualSearchRLM;
+    searchProject(input: ProjectSearchInput): Promise<ProjectSearchResult>;
+    private handleAutoReindex;
+    generatePreview(result: any, _query?: string): string;
+    filterByPatterns(results: any[], include?: string[], exclude?: string[]): any[];
+    /**
+     * Apply a 30% score boost to results whose filePath is in boostFiles.
+     * Re-sorts by boosted score descending.
+     */
+    applyBoost(results: any[], boostFiles: string[]): any[];
+}
+export {};
+//# sourceMappingURL=search-controller.d.ts.map

package/dist/controllers/search-controller.d.ts.map

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