feat: Add Contextual Pre-Briefer MCP Tool to Memory Core (#9689)

Author: tobiu

ai/mcp/server/memory-core/openapi.yaml

@@ -314,6 +314,52 @@ paths:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
 
+  /context/pre_brief:
+    post:
+      summary: Contextual Pre-Briefing
+      operationId: pre_brief_session
+      x-pass-as-object: true
+      description: |
+        Instantly contextualizes the agent by targeting a specific Epic or Graph Node,
+        loading its high-weight semantic relationships and returning a structured brief.
+        This provides zero-friction context-switching for the LLM.
+      tags: [System]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - targetId
+              properties:
+                targetId:
+                  type: string
+                  description: The Target Epic / Node ID to brief against.
+                limit:
+                  type: number
+                  description: Max context neighbors to pull.
+                  default: 5
+      responses:
+        '200':
+          description: Successful structural brief payload.
+          content:
+            application/json:
+              schema:
+                type: object
+        '400':
+          description: Invalid request body
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: Internal server error.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
   /summaries:
     get:
       summary: Get All Summaries

ai/mcp/server/memory-core/services/MemoryService.mjs

@@ -264,6 +264,78 @@ class MemoryService extends Base {
         }
     }
 
+    /**
+     * Instantly contextualizes the agent by targeting a specific Epic or Graph Node,
+     * loading its high-weight semantic relationships and returning a structured brief.
+     * @param {Object} options
+     * @param {String} options.targetId The Target Epic / Node ID to brief against.
+     * @param {Number} [options.limit=5] Max context neighbors to pull.
+     * @returns {Promise<Object>}
+     */
+    async preBriefSession({ targetId, limit = 5 }) {
+        try {
+            const baseNode = GraphService.getNode({ id: targetId });
+            if (!baseNode) {
+                 return {
+                     error: `Node ${targetId} not found in the Native Graph.`,
+                     code: 'NODE_NOT_FOUND'
+                 };
+            }
+
+            let neighbors = GraphService.getNeighbors({ id: targetId });
+            
+            // Focus purely on highest-weight semantic and architectural relationships
+            neighbors = neighbors
+                .filter(n => n.weight >= 0.5) // filter weak noise
+                .sort((a, b) => b.weight - a.weight)
+                .slice(0, limit);
+
+            const brief = {
+                target: baseNode,
+                context: []
+            };
+
+            const collection = await ChromaManager.getSummaryCollection();
+
+            for (const neighbor of neighbors) {
+                let episodicContext = null;
+                
+                if (neighbor.semanticVectorId) {
+                    try {
+                        const result = await collection.get({
+                            ids: [neighbor.semanticVectorId],
+                            include: ['documents']
+                        });
+                        if (result.documents && result.documents.length > 0) {
+                            episodicContext = result.documents[0];
+                        }
+                    } catch (e) {
+                         // Missing vector is fine, we still have structural graph data
+                    }
+                }
+
+                brief.context.push({
+                    id: neighbor.id,
+                    type: neighbor.type,
+                    name: neighbor.name,
+                    relationship: neighbor.relationship,
+                    weight: neighbor.weight,
+                    episodicContext
+                });
+            }
+
+            return brief;
+
+        } catch (error) {
+            logger.error('[MemoryService] Error in preBriefSession:', error);
+            return {
+                error  : 'Failed to generate contextual brief',
+                message: error.message,
+                code   : 'PRE_BRIEF_ERROR'
+            };
+        }
+    }
+
     /**
      * Mutates the active context frontier in the native knowledge graph.
      * @param {Object} options

ai/mcp/server/memory-core/services/toolService.mjs

@@ -25,6 +25,7 @@ const serviceMapping = {
     manage_database       : DatabaseLifecycleService.manageDatabase      .bind(DatabaseLifecycleService),
     manage_database_backup: DatabaseService         .manageDatabaseBackup.bind(DatabaseService),
     mutate_frontier       : MemoryService           .mutateFrontier      .bind(MemoryService),
+    pre_brief_session     : MemoryService           .preBriefSession     .bind(MemoryService),
     query_raw_memories    : MemoryService           .queryMemories       .bind(MemoryService),
     query_summaries       : SummaryService          .querySummaries      .bind(SummaryService),
     search_nodes          : GraphService            .searchNodes         .bind(GraphService),

test/playwright/unit/ai/mcp/server/memory-core/services/GraphService.spec.mjs

@@ -0,0 +1,99 @@
+import {setup} from '../../../../../../setup.mjs';
+
+const appName = 'GraphServiceTest';
+
+setup({
+    neoConfig: {
+        unitTestMode: true
+    },
+    appConfig: {
+        name             : appName,
+        isMounted        : () => true,
+        vnodeInitialising: false
+    }
+});
+
+import {test, expect} from '@playwright/test';
+import Neo            from '../../../../../../../../src/Neo.mjs';
+import * as core      from '../../../../../../../../src/core/_export.mjs';
+import GraphService   from '../../../../../../../../ai/mcp/server/memory-core/services/GraphService.mjs';
+import aiConfig       from '../../../../../../../../ai/mcp/server/memory-core/config.mjs';
+import fs             from 'fs-extra';
+import path           from 'path';
+import os             from 'os';
+
+test.describe('Neo.ai.mcp.server.memory-core.services.GraphService', () => {
+    let service;
+    const testDbPath = path.join(os.tmpdir(), `memory-core-graph-test-${process.pid}-${Date.now()}.db`);
+
+    test.beforeAll(async () => {
+        // Mock the SQLite target path to a safe pure temporary location
+        aiConfig.sqlitePath = testDbPath;
+        if (fs.existsSync(testDbPath)) {
+            fs.unlinkSync(testDbPath);
+        }
+        await GraphService.initAsync();
+    });
+
+    test.beforeEach(async () => {
+        // Clear graph nodes and edges before each test for isolation
+        if (GraphService.db) {
+            GraphService.db.nodes.clear();
+            GraphService.db.edges.clear();
+        }
+    });
+
+    test.afterEach(() => {
+        if (GraphService.db) {
+            GraphService.db.nodes.clear();
+            GraphService.db.edges.clear();
+        }
+    });
+
+    test.afterAll(() => {
+        if (fs.existsSync(testDbPath)) {
+            try {
+                fs.unlinkSync(testDbPath);
+            } catch (e) {}
+        }
+    });
+
+    test('should extract node neighbors properly', async () => {
+        GraphService.upsertNode({ id: 'EpicA', name: 'Roadmap Planner' });
+        GraphService.upsertNode({ id: 'Task1', name: 'Implementation' });
+        GraphService.upsertNode({ id: 'Task2', name: 'Documentation' });
+        
+        GraphService.linkNodes('EpicA', 'Task1', 'CONTAINS', 1.0);
+        GraphService.linkNodes('EpicA', 'Task2', 'CONTAINS', 0.8);
+        GraphService.linkNodes('Task1', 'Task2', 'DEPENDENCY', 0.5);
+
+        const neighbors = GraphService.getNeighbors({ id: 'EpicA' });
+        
+        // Validation of extraction
+        expect(neighbors.length).toBe(2);
+        
+        const task1 = neighbors.find(n => n.id === 'Task1');
+        const task2 = neighbors.find(n => n.id === 'Task2');
+        
+        expect(task1).toBeDefined();
+        expect(task1.weight).toBe(1.0);
+        expect(task1.relationship).toBe('CONTAINS');
+        
+        expect(task2).toBeDefined();
+        expect(task2.weight).toBe(0.8);
+    });
+
+    test('should correctly expose getContextFrontier topology', async () => {
+        GraphService.upsertNode({ id: 'frontier', type: 'SYSTEM_ANCHOR' });
+        GraphService.upsertNode({ id: 'EpicB' });
+        
+        // Weight < 0.8 should be filtered out by getContextFrontier originally
+        GraphService.linkNodes('frontier', 'EpicB', 'STRATEGIC_PIVOT', 0.9);
+        
+        const topology = GraphService.getContextFrontier();
+        expect(topology).toBeDefined();
+        expect(topology.frontier.id).toBe('frontier');
+        expect(topology.strategicNeighbors.length).toBe(1);
+        expect(topology.strategicNeighbors[0].id).toBe('EpicB');
+    });
+});