code-graph-context 2.8.0 → 2.10.0

package/dist/core/embeddings/embedding-sidecar.js

@@ -0,0 +1,244 @@
+/**
+ * Embedding Sidecar Manager
+ * Manages a Python FastAPI process that serves local embedding requests.
+ * The sidecar loads the model once and keeps it warm between requests.
+ */
+import { spawn } from 'child_process';
+import { existsSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const DEFAULT_CONFIG = {
+    port: parseInt(process.env.EMBEDDING_SIDECAR_PORT ?? '', 10) || 8787,
+    host: '127.0.0.1',
+    model: process.env.EMBEDDING_MODEL ?? 'Qodo/Qodo-Embed-1-1.5B',
+    startupTimeoutMs: 120_000, // 2 min — first run downloads the model
+    requestTimeoutMs: 60_000,
+};
+export class EmbeddingSidecar {
+    process = null;
+    readyPromise = null;
+    config;
+    _dimensions = null;
+    stopping = false;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    get baseUrl() {
+        return `http://${this.config.host}:${this.config.port}`;
+    }
+    get dimensions() {
+        return this._dimensions;
+    }
+    get isRunning() {
+        return this.process !== null && !this.stopping;
+    }
+    /**
+     * Start the sidecar process. No-ops if already running.
+     * Resolves when the server is healthy and ready to serve requests.
+     */
+    async start() {
+        if (this.readyPromise)
+            return this.readyPromise;
+        this.stopping = false;
+        this.readyPromise = this.doStart();
+        try {
+            await this.readyPromise;
+        }
+        catch (err) {
+            // Clean up on failed start
+            this.cleanup();
+            throw err;
+        }
+    }
+    /**
+     * Resolve the python binary — prefer venv, fall back to system python3.
+     */
+    resolvePython(sidecarDir) {
+        const venvPython = join(sidecarDir, '.venv', 'bin', 'python3');
+        if (existsSync(venvPython))
+            return venvPython;
+        return 'python3';
+    }
+    async doStart() {
+        // Check if something is already listening on the port (e.g. previous run)
+        if (await this.checkHealth()) {
+            console.error(`[embedding-sidecar] Server already running on ${this.baseUrl}`);
+            return;
+        }
+        await this.verifyPython();
+        // sidecar/ lives at project root — go up from dist/core/embeddings/ or src/core/embeddings/
+        const sidecarDir = join(__dirname, '..', '..', '..', 'sidecar');
+        const python = this.resolvePython(sidecarDir);
+        console.error(`[embedding-sidecar] Starting on ${this.baseUrl} (python: ${python}, model: ${this.config.model})`);
+        this.process = spawn(python, ['-m', 'uvicorn', 'embedding_server:app', '--host', this.config.host, '--port', String(this.config.port)], {
+            cwd: sidecarDir,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: {
+                ...process.env,
+                EMBEDDING_MODEL: this.config.model,
+            },
+        });
+        // Forward stderr for visibility (model loading progress, errors)
+        this.process.stderr?.on('data', (data) => {
+            const line = data.toString().trim();
+            if (line)
+                console.error(`[embedding-sidecar] ${line}`);
+        });
+        this.process.on('error', (err) => {
+            console.error(`[embedding-sidecar] Process error: ${err.message}`);
+        });
+        this.process.on('exit', (code, signal) => {
+            if (!this.stopping) {
+                console.error(`[embedding-sidecar] Process exited unexpectedly (code=${code}, signal=${signal})`);
+            }
+            this.cleanup();
+        });
+        // Poll until healthy
+        await this.waitForHealthy();
+    }
+    async verifyPython() {
+        return new Promise((resolve, reject) => {
+            const check = spawn('python3', ['--version'], { stdio: 'pipe' });
+            let output = '';
+            check.stdout?.on('data', (d) => (output += d.toString()));
+            check.stderr?.on('data', (d) => (output += d.toString()));
+            check.on('error', () => {
+                reject(new Error('python3 not found. Local embeddings require Python 3.10+.\n\n' +
+                    'Install Python and the sidecar dependencies:\n' +
+                    '  pip install -r sidecar/requirements.txt\n\n' +
+                    'Or set OPENAI_ENABLED=true to use OpenAI instead.'));
+            });
+            check.on('close', (code) => {
+                if (code !== 0) {
+                    reject(new Error(`python3 check failed: ${output}`));
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+    }
+    async waitForHealthy() {
+        const start = Date.now();
+        const pollInterval = 1000;
+        while (Date.now() - start < this.config.startupTimeoutMs) {
+            if (this.stopping)
+                throw new Error('Sidecar stopped during startup');
+            if (this.process?.exitCode !== null && this.process?.exitCode !== undefined) {
+                throw new Error(`Sidecar process exited during startup with code ${this.process.exitCode}`);
+            }
+            if (await this.checkHealth()) {
+                console.error(`[embedding-sidecar] Ready (${Date.now() - start}ms)`);
+                return;
+            }
+            await new Promise((r) => setTimeout(r, pollInterval));
+        }
+        throw new Error(`Embedding sidecar failed to start within ${this.config.startupTimeoutMs}ms.\n` +
+            'This usually means the model is still downloading or dependencies are missing.\n\n' +
+            'Try running manually:\n' +
+            '  cd sidecar && python3 -m uvicorn embedding_server:app --host 127.0.0.1 --port 8787');
+    }
+    async checkHealth() {
+        try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 2000);
+            const res = await fetch(`${this.baseUrl}/health`, { signal: controller.signal });
+            clearTimeout(timeout);
+            if (res.ok) {
+                const data = (await res.json());
+                if (data.dimensions)
+                    this._dimensions = data.dimensions;
+                return data.status === 'ok';
+            }
+            return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Embed an array of texts. Lazily starts the sidecar if not running.
+     */
+    async embed(texts) {
+        await this.start();
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.config.requestTimeoutMs);
+        try {
+            const res = await fetch(`${this.baseUrl}/embed`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ texts }),
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                const detail = await res.text();
+                throw new Error(`Sidecar embed failed (${res.status}): ${detail}`);
+            }
+            const data = (await res.json());
+            if (data.dimensions)
+                this._dimensions = data.dimensions;
+            return data.embeddings;
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'AbortError') {
+                throw new Error(`Embedding request timed out after ${this.config.requestTimeoutMs}ms`);
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    /**
+     * Embed a single text. Convenience wrapper.
+     */
+    async embedText(text) {
+        const [embedding] = await this.embed([text]);
+        return embedding;
+    }
+    /**
+     * Stop the sidecar process.
+     */
+    async stop() {
+        this.stopping = true;
+        if (this.process) {
+            console.error('[embedding-sidecar] Stopping...');
+            this.process.kill('SIGTERM');
+            // Give it 5s to shut down gracefully, then force kill
+            await new Promise((resolve) => {
+                const forceKill = setTimeout(() => {
+                    if (this.process) {
+                        this.process.kill('SIGKILL');
+                    }
+                    resolve();
+                }, 5000);
+                this.process?.on('exit', () => {
+                    clearTimeout(forceKill);
+                    resolve();
+                });
+            });
+        }
+        this.cleanup();
+    }
+    cleanup() {
+        this.process = null;
+        this.readyPromise = null;
+    }
+}
+/**
+ * Singleton sidecar instance — shared across all tool calls.
+ * The sidecar starts lazily on first embed request and stays warm.
+ */
+let sidecarInstance = null;
+export const getEmbeddingSidecar = () => {
+    sidecarInstance ??= new EmbeddingSidecar();
+    return sidecarInstance;
+};
+export const stopEmbeddingSidecar = async () => {
+    if (sidecarInstance) {
+        await sidecarInstance.stop();
+        sidecarInstance = null;
+    }
+};

package/dist/core/embeddings/embeddings.service.js

@@ -1,146 +1,74 @@
-import OpenAI from 'openai';
-import { debugLog } from '../../mcp/utils.js';
-import { getTimeoutConfig } from '../config/timeouts.js';
 /**
- * Custom error class for OpenAI configuration issues
- * Provides helpful guidance on how to resolve the issue
+ * Embeddings Service — barrel module
+ *
+ * Exports a common interface and a factory. Consumers do `new EmbeddingsService()`
+ * and get the right implementation based on OPENAI_ENABLED.
+ *
+ *   OPENAI_ENABLED=true  → OpenAI text-embedding-3-large (requires OPENAI_API_KEY)
+ *   default              → Local Python sidecar with Qodo-Embed-1-1.5B
  */
-export class OpenAIConfigError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'OpenAIConfigError';
-    }
-}
+import { LocalEmbeddingsService } from './local-embeddings.service.js';
+import { OpenAIEmbeddingsService } from './openai-embeddings.service.js';
+// Re-export error classes so existing imports keep working
+export { OpenAIConfigError, OpenAIAPIError } from './openai-embeddings.service.js';
+export const EMBEDDING_BATCH_CONFIG = {
+    maxBatchSize: 100,
+    delayBetweenBatchesMs: 500,
+};
 /**
- * Custom error class for OpenAI API issues (rate limits, quota, etc.)
+ * Known dimensions per model.
+ * For unlisted models, dimensions are detected at runtime from the sidecar health endpoint.
  */
-export class OpenAIAPIError extends Error {
-    statusCode;
-    constructor(message, statusCode) {
-        super(message);
-        this.statusCode = statusCode;
-        this.name = 'OpenAIAPIError';
+export const EMBEDDING_DIMENSIONS = {
+    // OpenAI models
+    'text-embedding-3-large': 3072,
+    'text-embedding-3-small': 1536,
+    // Local models (via sidecar)
+    'Qodo/Qodo-Embed-1-1.5B': 1536,
+    'sentence-transformers/all-MiniLM-L6-v2': 384,
+    'sentence-transformers/all-mpnet-base-v2': 768,
+    'BAAI/bge-small-en-v1.5': 384,
+    'BAAI/bge-base-en-v1.5': 768,
+    'nomic-ai/nomic-embed-text-v1.5': 768,
+};
+export const isOpenAIEnabled = () => {
+    return process.env.OPENAI_ENABLED?.toLowerCase() === 'true';
+};
+/**
+ * Get the vector dimensions for the active embedding provider.
+ * For known models, returns a static value. For unknown local models,
+ * falls back to 1536 — the actual dimensions are verified at runtime
+ * when the sidecar starts and reports via /health.
+ */
+export const getEmbeddingDimensions = () => {
+    if (isOpenAIEnabled()) {
+        const model = process.env.OPENAI_EMBEDDING_MODEL ?? 'text-embedding-3-large';
+        return EMBEDDING_DIMENSIONS[model] ?? 3072;
     }
-}
-export const EMBEDDING_BATCH_CONFIG = {
-    maxBatchSize: 100, // OpenAI supports up to 2048, but 100 is efficient
-    delayBetweenBatchesMs: 500, // Rate limit protection (500ms = ~2 batches/sec)
+    const model = process.env.EMBEDDING_MODEL ?? 'Qodo/Qodo-Embed-1-1.5B';
+    return EMBEDDING_DIMENSIONS[model] ?? 1536;
 };
+/**
+ * Factory that returns the correct service based on OPENAI_ENABLED.
+ * Drop-in replacement everywhere `new EmbeddingsService()` was used.
+ */
 export class EmbeddingsService {
-    openai;
-    model;
-    constructor(model = 'text-embedding-3-large') {
-        const apiKey = process.env.OPENAI_API_KEY;
-        if (!apiKey) {
-            throw new OpenAIConfigError('OPENAI_API_KEY environment variable is required.\n\n' +
-                'To use semantic search features (search_codebase, natural_language_to_cypher), ' +
-                'you need an OpenAI API key.\n\n' +
-                'Set it in your environment:\n' +
-                '  export OPENAI_API_KEY=sk-...\n\n' +
-                'Or in .env file:\n' +
-                '  OPENAI_API_KEY=sk-...\n\n' +
-                'Alternative: Use impact_analysis or traverse_from_node which do not require OpenAI.');
-        }
-        const timeoutConfig = getTimeoutConfig();
-        this.openai = new OpenAI({
-            apiKey,
-            timeout: timeoutConfig.openai.embeddingTimeoutMs,
-            maxRetries: 2, // Built-in retry for transient errors
-        });
-        this.model = model;
-    }
-    /**
-     * Embed a single text string
-     */
-    async embedText(text) {
-        try {
-            const response = await this.openai.embeddings.create({
-                model: this.model,
-                input: text,
-            });
-            return response.data[0].embedding;
+    impl;
+    constructor(model) {
+        if (isOpenAIEnabled()) {
+            this.impl = new OpenAIEmbeddingsService(model);
         }
-        catch (error) {
-            // Handle specific error types with helpful messages
-            if (error.code === 'ETIMEDOUT' || error.message?.includes('timeout')) {
-                throw new OpenAIAPIError('OpenAI embedding request timed out. Consider increasing OPENAI_EMBEDDING_TIMEOUT_MS.');
-            }
-            if (error.status === 429) {
-                throw new OpenAIAPIError('OpenAI rate limit exceeded.\n\n' +
-                    'This usually means:\n' +
-                    '- You have hit your API rate limit\n' +
-                    '- You have exceeded your quota\n\n' +
-                    'Solutions:\n' +
-                    '- Wait a few minutes and try again\n' +
-                    '- Check your OpenAI usage at https://platform.openai.com/usage\n' +
-                    '- Use impact_analysis or traverse_from_node which do not require OpenAI', 429);
-            }
-            if (error.status === 401) {
-                throw new OpenAIAPIError('OpenAI API key is invalid or expired.\n\n' + 'Please check your OPENAI_API_KEY environment variable.', 401);
-            }
-            if (error.status === 402 || error.message?.includes('quota') || error.message?.includes('billing')) {
-                throw new OpenAIAPIError('OpenAI quota exceeded or billing issue.\n\n' +
-                    'Solutions:\n' +
-                    '- Check your OpenAI billing at https://platform.openai.com/settings/organization/billing\n' +
-                    '- Add credits to your account\n' +
-                    '- Use impact_analysis or traverse_from_node which do not require OpenAI', 402);
-            }
-            console.error('Error creating embedding:', error);
-            throw error;
+        else {
+            this.impl = new LocalEmbeddingsService();
         }
     }
-    /**
-     * Embed multiple texts in a single API call.
-     * OpenAI's embedding API supports batching natively.
-     */
-    async embedTexts(texts) {
-        if (texts.length === 0)
-            return [];
-        try {
-            const response = await this.openai.embeddings.create({
-                model: this.model,
-                input: texts,
-            });
-            // Map results back to original order (OpenAI returns with index)
-            return response.data.sort((a, b) => a.index - b.index).map((d) => d.embedding);
-        }
-        catch (error) {
-            if (error.code === 'ETIMEDOUT' || error.message?.includes('timeout')) {
-                throw new OpenAIAPIError('OpenAI batch embedding request timed out. Consider reducing batch size or increasing timeout.');
-            }
-            // Rate limited - SDK already has maxRetries:2, don't add recursive retry
-            if (error.status === 429) {
-                throw new OpenAIAPIError('OpenAI rate limit exceeded. Wait a few minutes and try again.\n' +
-                    'Check your usage at https://platform.openai.com/usage', 429);
-            }
-            // Re-throw with context
-            throw new OpenAIAPIError(`OpenAI embedding failed: ${error.message}`, error.status);
-        }
+    embedText(text) {
+        return this.impl.embedText(text);
     }
-    /**
-     * Embed texts in batches with rate limiting.
-     * Returns array of embeddings in same order as input.
-     * @param texts Array of texts to embed
-     * @param batchSize Number of texts per API call (default: 100)
-     */
-    async embedTextsInBatches(texts, batchSize = EMBEDDING_BATCH_CONFIG.maxBatchSize) {
-        await debugLog('Batch embedding started', { textCount: texts.length });
-        const results = [];
-        const totalBatches = Math.ceil(texts.length / batchSize);
-        for (let i = 0; i < texts.length; i += batchSize) {
-            const batch = texts.slice(i, i + batchSize);
-            const batchIndex = Math.floor(i / batchSize) + 1;
-            await debugLog('Embedding batch progress', { batchIndex, totalBatches, batchSize: batch.length });
-            const batchResults = await this.embedTexts(batch);
-            results.push(...batchResults);
-            // Rate limit protection between batches
-            if (i + batchSize < texts.length) {
-                await this.delay(EMBEDDING_BATCH_CONFIG.delayBetweenBatchesMs);
-            }
-        }
-        return results;
+    embedTexts(texts) {
+        return this.impl.embedTexts(texts);
     }
-    delay(ms) {
-        return new Promise((resolve) => setTimeout(resolve, ms));
+    embedTextsInBatches(texts, batchSize) {
+        return this.impl.embedTextsInBatches(texts, batchSize);
     }
 }

package/dist/core/embeddings/local-embeddings.service.js

@@ -0,0 +1,41 @@
+/**
+ * Local Embeddings Service
+ * Uses a Python sidecar running Qodo-Embed-1-1.5B (or configurable model).
+ * Default provider — no API key required.
+ */
+import { debugLog } from '../../mcp/utils.js';
+import { getEmbeddingSidecar } from './embedding-sidecar.js';
+const BATCH_CONFIG = {
+    maxBatchSize: 16, // Small batches — 1.5B model on MPS has limited VRAM
+};
+export class LocalEmbeddingsService {
+    async embedText(text) {
+        const sidecar = getEmbeddingSidecar();
+        return sidecar.embedText(text);
+    }
+    async embedTexts(texts) {
+        if (texts.length === 0)
+            return [];
+        const sidecar = getEmbeddingSidecar();
+        return sidecar.embed(texts);
+    }
+    async embedTextsInBatches(texts, batchSize = BATCH_CONFIG.maxBatchSize) {
+        await debugLog('Batch embedding started', { provider: 'local', textCount: texts.length });
+        const sidecar = getEmbeddingSidecar();
+        const results = [];
+        const totalBatches = Math.ceil(texts.length / batchSize);
+        for (let i = 0; i < texts.length; i += batchSize) {
+            const batch = texts.slice(i, i + batchSize);
+            const batchIndex = Math.floor(i / batchSize) + 1;
+            await debugLog('Embedding batch progress', {
+                provider: 'local',
+                batchIndex,
+                totalBatches,
+                batchSize: batch.length,
+            });
+            const batchResults = await sidecar.embed(batch);
+            results.push(...batchResults);
+        }
+        return results;
+    }
+}

package/dist/core/embeddings/openai-embeddings.service.js

@@ -0,0 +1,114 @@
+/**
+ * OpenAI Embeddings Service
+ * Uses OpenAI's text-embedding API. Requires OPENAI_API_KEY.
+ * Opt-in via OPENAI_ENABLED=true.
+ */
+import OpenAI from 'openai';
+import { debugLog } from '../../mcp/utils.js';
+import { getTimeoutConfig } from '../config/timeouts.js';
+export class OpenAIConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'OpenAIConfigError';
+    }
+}
+export class OpenAIAPIError extends Error {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = 'OpenAIAPIError';
+    }
+}
+const BATCH_CONFIG = {
+    maxBatchSize: 100,
+    delayBetweenBatchesMs: 500,
+};
+export class OpenAIEmbeddingsService {
+    openai;
+    model;
+    constructor(model = 'text-embedding-3-large') {
+        const apiKey = process.env.OPENAI_API_KEY;
+        if (!apiKey) {
+            throw new OpenAIConfigError('OPENAI_API_KEY environment variable is required.\n\n' +
+                'To use semantic search features (search_codebase, natural_language_to_cypher), ' +
+                'you need an OpenAI API key.\n\n' +
+                'Set it in your environment:\n' +
+                '  export OPENAI_API_KEY=sk-...\n\n' +
+                'Or in .env file:\n' +
+                '  OPENAI_API_KEY=sk-...\n\n' +
+                'Alternative: Use local embeddings (default) which require no API key.');
+        }
+        const timeoutConfig = getTimeoutConfig();
+        this.openai = new OpenAI({
+            apiKey,
+            timeout: timeoutConfig.openai.embeddingTimeoutMs,
+            maxRetries: 2,
+        });
+        this.model = model;
+    }
+    async embedText(text) {
+        try {
+            const response = await this.openai.embeddings.create({
+                model: this.model,
+                input: text,
+            });
+            return response.data[0].embedding;
+        }
+        catch (error) {
+            throw this.wrapError(error);
+        }
+    }
+    async embedTexts(texts) {
+        if (texts.length === 0)
+            return [];
+        try {
+            const response = await this.openai.embeddings.create({
+                model: this.model,
+                input: texts,
+            });
+            return response.data.sort((a, b) => a.index - b.index).map((d) => d.embedding);
+        }
+        catch (error) {
+            throw this.wrapError(error);
+        }
+    }
+    async embedTextsInBatches(texts, batchSize = BATCH_CONFIG.maxBatchSize) {
+        await debugLog('Batch embedding started', { provider: 'openai', textCount: texts.length });
+        const results = [];
+        const totalBatches = Math.ceil(texts.length / batchSize);
+        for (let i = 0; i < texts.length; i += batchSize) {
+            const batch = texts.slice(i, i + batchSize);
+            const batchIndex = Math.floor(i / batchSize) + 1;
+            await debugLog('Embedding batch progress', {
+                provider: 'openai',
+                batchIndex,
+                totalBatches,
+                batchSize: batch.length,
+            });
+            const batchResults = await this.embedTexts(batch);
+            results.push(...batchResults);
+            if (i + batchSize < texts.length) {
+                await new Promise((resolve) => setTimeout(resolve, BATCH_CONFIG.delayBetweenBatchesMs));
+            }
+        }
+        return results;
+    }
+    wrapError(error) {
+        if (error.code === 'ETIMEDOUT' || error.message?.includes('timeout')) {
+            return new OpenAIAPIError('OpenAI embedding request timed out. Consider increasing OPENAI_EMBEDDING_TIMEOUT_MS.');
+        }
+        if (error.status === 429) {
+            return new OpenAIAPIError('OpenAI rate limit exceeded. Wait a few minutes and try again.\n' +
+                'Check your usage at https://platform.openai.com/usage', 429);
+        }
+        if (error.status === 401) {
+            return new OpenAIAPIError('OpenAI API key is invalid or expired.\nPlease check your OPENAI_API_KEY.', 401);
+        }
+        if (error.status === 402 || error.message?.includes('quota') || error.message?.includes('billing')) {
+            return new OpenAIAPIError('OpenAI quota exceeded or billing issue.\n' +
+                'Check billing at https://platform.openai.com/settings/organization/billing', 402);
+        }
+        return new OpenAIAPIError(`OpenAI embedding failed: ${error.message}`, error.status);
+    }
+}

package/dist/mcp/constants.js

@@ -43,6 +43,7 @@ export const TOOL_NAMES = {
     saveSessionNote: 'save_session_note',
     recallSessionNotes: 'recall_session_notes',
     cleanupSession: 'cleanup_session',
+    swarmMessage: 'swarm_message',
 };
 // Tool Metadata
 export const TOOL_METADATA = {
@@ -221,7 +222,7 @@ Returns pheromones with current intensity after decay. minIntensity default: 0.3
     },
     [TOOL_NAMES.swarmCleanup]: {
         title: 'Swarm Cleanup',
-        description: `Bulk delete pheromones. Specify swarmId, agentId, or all:true. Warning pheromones preserved by default (override with keepTypes:[]). Use dryRun:true to preview.`,
+        description: `Bulk delete pheromones, tasks, and messages. Specify swarmId, agentId, or all:true. Warning pheromones preserved by default (override with keepTypes:[]). Messages and tasks are deleted when swarmId is provided. Use dryRun:true to preview.`,
     },
     [TOOL_NAMES.swarmPostTask]: {
         title: 'Swarm Post Task',
@@ -343,6 +344,28 @@ Parameters:
 
 Returns counts of deleted notes, bookmarks, and edges.`,
     },
+    [TOOL_NAMES.swarmMessage]: {
+        title: 'Swarm Message',
+        description: `Direct agent-to-agent messaging via Neo4j. Unlike pheromones (passive/decay-based), messages are explicit and delivered when agents claim tasks.
+
+**Actions:**
+- send: Post a message to a specific agent or broadcast to all agents in a swarm
+- read: Retrieve unread messages (or all messages) for an agent
+- acknowledge: Mark messages as read
+
+**Categories:** blocked, conflict, finding, request, alert, handoff
+
+**Key behavior:**
+- Messages sent to a specific agent are delivered when that agent calls swarm_claim_task
+- Broadcast messages (toAgentId omitted) are visible to all agents in the swarm
+- Messages auto-expire after 4 hours (configurable via ttlMs)
+- Use this for critical coordination signals that agents MUST see, not optional context
+
+**Examples:**
+- Agent finds a breaking type error: send alert to all
+- Agent is blocked on a file another agent owns: send blocked to that agent
+- Agent discovers context another agent needs: send finding to that agent`,
+    },
 };
 // Default Values
 export const DEFAULTS = {

package/dist/mcp/handlers/graph-generator.handler.js

@@ -3,7 +3,7 @@
  * Handles importing parsed graph data into Neo4j with embeddings
  */
 import fs from 'fs/promises';
-import { EMBEDDING_BATCH_CONFIG } from '../../core/embeddings/embeddings.service.js';
+import { EMBEDDING_BATCH_CONFIG, getEmbeddingDimensions } from '../../core/embeddings/embeddings.service.js';
 import { QUERIES } from '../../storage/neo4j/neo4j.service.js';
 import { DEFAULTS } from '../constants.js';
 import { debugLog } from '../utils.js';
@@ -181,10 +181,11 @@ export class GraphGeneratorHandler {
         }
     }
     async createVectorIndexes() {
-        console.error('Creating vector indexes...');
-        await this.neo4jService.run(QUERIES.CREATE_EMBEDDED_VECTOR_INDEX);
-        await this.neo4jService.run(QUERIES.CREATE_SESSION_NOTES_VECTOR_INDEX);
-        await debugLog('Vector indexes created');
+        const dims = getEmbeddingDimensions();
+        console.error(`Creating vector indexes (dimensions: ${dims})...`);
+        await this.neo4jService.run(QUERIES.CREATE_EMBEDDED_VECTOR_INDEX(dims));
+        await this.neo4jService.run(QUERIES.CREATE_SESSION_NOTES_VECTOR_INDEX(dims));
+        await debugLog('Vector indexes created', { dimensions: dims });
     }
     flattenProperties(properties) {
         const flattened = {};