monomind 2.0.3 → 2.1.0

package/packages/@monomind/cli/dist/src/mcp-tools/knowledge-tools.js

@@ -1,6 +1,7 @@
 /**
  * MCP Knowledge Tools — Second Brain document ingest and search
  */
+import { validateInput } from '../utils/input-guards.js';
 const knowledgeIngest = {
     name: 'knowledge_ingest',
     description: 'Ingest documents into the Second Brain knowledge base. Accepts a file or directory path. Extracts text, chunks, embeds, and stores in LanceDB for semantic search.',
@@ -15,10 +16,17 @@ const knowledgeIngest = {
         required: ['path'],
     },
     handler: async (input) => {
+        const pathCheck = validateInput(input.path, { type: 'path' });
+        if (!pathCheck.valid) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ success: false, error: pathCheck.error }) }],
+                isError: true,
+            };
+        }
         const { ingestDocument, ingestDirectory } = await import('../knowledge/document-pipeline.js');
         const fs = await import('node:fs');
         const pathMod = await import('node:path');
-        const target = pathMod.resolve(String(input.path));
+        const target = pathMod.resolve(pathCheck.sanitized);
         const scope = String(input.scope || 'shared');
         try {
             const stat = fs.statSync(target);

package/packages/@monomind/cli/dist/src/mcp-tools/monograph-compat.js

@@ -6,26 +6,67 @@
  * moved to the real package.
  */
 import { join, resolve, relative } from 'path';
-import { existsSync, readFileSync, statSync } from 'fs';
-import { openDb, closeDb, countNodes } from '@monoes/monograph';
+import { existsSync, statSync } from 'fs';
+import { execSync } from 'child_process';
+import { openDb, closeDb, countNodes, parseGroupConfig } from '@monoes/monograph';
+import { getProjectCwd } from './types.js';
+import { realOrResolved } from '../utils/input-guards.js';
+// ── Group config reader ───────────────────────────────────────────────────────
 const MAX_GROUP_CONFIG_BYTES = 1 * 1024 * 1024; // 1 MB
+/**
+ * Read repos from a group.yaml config (the real group config format used by
+ * monograph_group_query / monograph_group_sync / monograph_group_list — see
+ * @monoes/monograph's groups/group-config.ts).
+ *
+ * Throws on an out-of-bounds or oversized path instead of silently returning
+ * an empty list, so callers can distinguish "no groups configured" from
+ * "your repoPath was rejected".
+ */
 function readGroupConfig(configPath) {
     if (!existsSync(configPath))
         return [];
+    // Guard: only allow paths within the project cwd to prevent traversal to
+    // /etc/passwd etc. Uses getProjectCwd() (honors MONOMIND_CWD) rather than
+    // process.cwd(), which is trivially bypassed when the MCP server runs with
+    // cwd "/".
+    // realOrResolved resolves symlinks (walking up to the longest existing
+    // ancestor) so a link that's lexically inside projectCwd but physically
+    // points outside it can't bypass this containment check — same guard
+    // input-guards.ts's validatePath uses, applied here against getProjectCwd()
+    // instead of process.cwd() since that's the whole reason this check isn't
+    // just a direct call to validateInput({type:'path'}).
+    const projectCwd = realOrResolved(getProjectCwd());
+    const resolved = realOrResolved(resolve(configPath));
+    const rel = relative(projectCwd, resolved);
+    if (rel.startsWith('..') || resolve(rel) === resolve('/')) {
+        throw new Error(`Rejected group config path outside project directory: ${resolved} (project cwd: ${projectCwd})`);
+    }
+    // OOM guard: skip files larger than 1 MB
+    if (statSync(configPath).size > MAX_GROUP_CONFIG_BYTES) {
+        throw new Error(`Group config file too large (> ${MAX_GROUP_CONFIG_BYTES} bytes): ${configPath}`);
+    }
+    return parseGroupConfig(configPath).repos;
+}
+/**
+ * Compute whether a repo's monograph index is stale relative to HEAD, the
+ * same way monograph_staleness does: compare the last indexed commit hash
+ * against `git rev-list --count <lastCommit>..HEAD`. Mirrors the threshold
+ * used by monograph-tools.ts (STALENESS_THRESHOLD = 10).
+ */
+function isRepoStale(db, repoPath) {
     try {
-        // Guard: only allow paths within cwd to prevent traversal to /etc/passwd etc.
-        const resolved = resolve(configPath);
-        const rel = relative(process.cwd(), resolved);
-        if (rel.startsWith('..') || resolve(rel) === resolve('/'))
-            return [];
-        // OOM guard: skip files larger than 1 MB
-        if (statSync(configPath).size > MAX_GROUP_CONFIG_BYTES)
-            return [];
-        const raw = readFileSync(configPath, 'utf-8');
-        return JSON.parse(raw);
+        const meta = (db.prepare("SELECT value FROM index_meta WHERE key = 'last_commit_hash'").get()
+            ?? db.prepare("SELECT value FROM index_meta WHERE key = 'lastCommit'").get());
+        const lastCommit = meta?.value;
+        if (!lastCommit || !/^[0-9a-f]{7,40}$/i.test(lastCommit))
+            return false;
+        const out = execSync(`git rev-list --count ${lastCommit}..HEAD`, {
+            cwd: repoPath, encoding: 'utf-8',
+        }).trim();
+        return parseInt(out, 10) > 10;
     }
     catch {
-        return [];
+        return false;
     }
 }
 // ── getGroupContracts ─────────────────────────────────────────────────────────
@@ -74,11 +115,12 @@ export async function getGroupStatus(configPath) {
             const nc = countNodes(db);
             const contracts = db.prepare("SELECT COUNT(*) as n FROM nodes WHERE label = 'Route'").get();
             const meta = db.prepare("SELECT value FROM index_meta WHERE key IN ('ua_last_commit','lastCommit') LIMIT 1").get();
+            const stale = isRepoStale(db, repoPath);
             closeDb(db);
             groups.push({
                 name,
                 indexed: nc > 0,
-                stale: false,
+                stale,
                 contractCount: contracts?.n ?? 0,
                 ...(meta?.value ? { lastSync: meta.value } : {}),
             });

package/packages/@monomind/cli/dist/src/mcp-tools/monograph-tools.js

@@ -19,23 +19,36 @@ function _isValidDb(p) {
         return false;
     }
 }
-function getDbPath() {
-    const cwd = getProjectCwd();
+/**
+ * Resolve the monograph DB path for a given repo root (defaults to project cwd).
+ * Falls back to searching up to the git root when the DB isn't directly under
+ * `<cwd>/.monomind` — e.g. when called from a subdirectory of the repo. Only
+ * the no-arg (project cwd) form is cached; explicit `repoPath` overrides are
+ * cheap one-off lookups (staleness checks with a user-supplied path) so caching
+ * them isn't worth the invalidation complexity.
+ */
+function getDbPath(repoPathOverride) {
+    const cwd = repoPathOverride ?? getProjectCwd();
+    const useCache = repoPathOverride === undefined;
     // Invalidate cache when project root changes (e.g. MONOMIND_CWD set after initialize)
-    if (_cachedDbPath && _cachedCwd === cwd)
+    if (useCache && _cachedDbPath && _cachedCwd === cwd)
         return _cachedDbPath;
-    _cachedCwd = cwd;
-    _cachedDbPath = undefined;
+    if (useCache) {
+        _cachedCwd = cwd;
+        _cachedDbPath = undefined;
+    }
     const direct = join(cwd, '.monomind', 'monograph.db');
     if (_isValidDb(direct)) {
-        _cachedDbPath = direct;
+        if (useCache)
+            _cachedDbPath = direct;
         return direct;
     }
     try {
         const root = execSync('git rev-parse --show-toplevel', { cwd, encoding: 'utf8' }).trim();
         const candidate = join(root, '.monomind', 'monograph.db');
         if (_isValidDb(candidate)) {
-            _cachedDbPath = candidate;
+            if (useCache)
+                _cachedDbPath = candidate;
             return candidate;
         }
     }
@@ -46,13 +59,6 @@ function getDbPath() {
 function text(t) {
     return { content: [{ type: 'text', text: t }] };
 }
-function ensureDbExists() {
-    const p = getDbPath();
-    if (!_isValidDb(p)) {
-        throw new Error(`Monograph index not built yet. Run monograph_build first (path: ${p}).`);
-    }
-    return p;
-}
 // ── Active watcher registry ──────────────────────────────────────────────────
 const _activeWatchers = new Map();
 function applyPprRerank(db, seedNodes, damping, maxResults) {
@@ -577,9 +583,13 @@ function taskRelevance(task, nodeText) {
     return taskTerms.filter(t => txt.includes(t)).length / taskTerms.length;
 }
 // ── monograph_visualize ───────────────────────────────────────────────────────
+// Columns needed to render/export the graph — deliberately excludes `embedding`,
+// which can be several KB per node (384D vectors) and would otherwise bloat
+// tool-result payloads and written files by many MB.
+const NODE_RENDER_COLUMNS = 'id, label, name, norm_label, file_path, start_line, end_line, community_id, is_exported, language, properties';
 const monographVisualizeTool = {
     name: 'monograph_visualize',
-    description: 'Render the knowledge graph as HTML (default), SVG, or JSON.',
+    description: 'Render the knowledge graph as HTML (default), SVG, or JSON. Writes output to a file under .monomind/visualize/ and returns the file path (output can be multi-MB at the max node count, too large to return inline).',
     inputSchema: {
         type: 'object',
         properties: {
@@ -589,6 +599,7 @@ const monographVisualizeTool = {
     },
     handler: async (input) => {
         const { openDb, closeDb, toJson, toHtml, toSvg } = await import('@monoes/monograph');
+        const { writeFileSync, mkdirSync } = await import('fs');
         const db = openDb(getDbPath());
         try {
             // Cap maxNodes: passed to SQL LIMIT clause for both nodes (n) and edges
@@ -598,7 +609,7 @@ const monographVisualizeTool = {
             const limit = Number.isFinite(rawMaxNodes) && rawMaxNodes > 0
                 ? Math.min(Math.floor(rawMaxNodes), MAX_EXPORT_NODES)
                 : 500;
-            const nodes = db.prepare('SELECT * FROM nodes LIMIT ?').all(limit);
+            const nodes = db.prepare(`SELECT ${NODE_RENDER_COLUMNS} FROM nodes LIMIT ?`).all(limit);
             // Only include edges where both endpoints are in the visible node set
             const edges = db.prepare(`
         SELECT e.* FROM edges e
@@ -607,11 +618,15 @@ const monographVisualizeTool = {
         LIMIT ?
       `).all(limit, limit, limit * 3);
             const fmt = input.format ?? 'html';
-            if (fmt === 'json')
-                return text(toJson(nodes, edges));
-            if (fmt === 'svg')
-                return text(toSvg(nodes, edges));
-            return text(toHtml(nodes, edges));
+            const rendered = fmt === 'json' ? toJson(nodes, edges)
+                : fmt === 'svg' ? toSvg(nodes, edges)
+                    : toHtml(nodes, edges);
+            const ext = fmt === 'json' ? 'json' : fmt === 'svg' ? 'svg' : 'html';
+            const outDir = resolve(join(getProjectCwd(), '.monomind', 'visualize'));
+            mkdirSync(outDir, { recursive: true });
+            const outPath = join(outDir, `graph-${Date.now()}.${ext}`);
+            writeFileSync(outPath, rendered);
+            return text(`Visualization written to ${outPath} (${nodes.length} nodes, ${edges.length} edges)${ext === 'html' ? '\nNote: HTML uses the vis-network CDN script and requires network access to render.' : ''}`);
         }
         finally {
             closeDb(db);
@@ -700,7 +715,8 @@ const monographReportTool = {
                     return `${i + 1}. **${n.name}** (${n.label}) — degree ${n.degree}${loc ? `  \`${loc}\`` : ''}`;
                 }),
             ].join('\n');
-            const outPath = resolve(input.path ?? join(getProjectCwd(), '.monomind', 'GRAPH_REPORT.md'));
+            const rawOutPath = input.path ?? join(getProjectCwd(), '.monomind', 'GRAPH_REPORT.md');
+            const outPath = resolve(getProjectCwd(), rawOutPath);
             const allowedRoot = resolve(getProjectCwd());
             if (outPath !== allowedRoot && !outPath.startsWith(allowedRoot + sep)) {
                 return text(`Error: path must be within the project directory (${allowedRoot})`);
@@ -725,7 +741,10 @@ let _buildInProgress = false;
 async function computeCommitsBehind(repoPath) {
     const { openDb, closeDb } = await import('@monoes/monograph');
     const { execSync } = await import('child_process');
-    const db = openDb(join(repoPath, '.monomind', 'monograph.db'));
+    const dbPath = getDbPath(repoPath);
+    if (!_isValidDb(dbPath))
+        return null;
+    const db = openDb(dbPath, { fileMustExist: true });
     try {
         const meta = db.prepare("SELECT value FROM index_meta WHERE key = 'last_commit_hash'").get() ?? db.prepare("SELECT value FROM index_meta WHERE key = 'lastCommit'").get();
         const lastCommit = meta?.value ?? null;
@@ -929,11 +948,13 @@ const monographExportTool = {
         const { writeFileSync, mkdirSync } = await import('fs');
         const db = openDb(getDbPath());
         try {
-            const nodes = db.prepare('SELECT * FROM nodes').all();
+            // Exclude `embedding` — a several-KB-per-node vector column that would
+            // otherwise bloat exported files by many MB for no rendering benefit.
+            const nodes = db.prepare(`SELECT ${NODE_RENDER_COLUMNS} FROM nodes`).all();
             const edges = db.prepare('SELECT * FROM edges').all();
             const fmt = input.format;
             const requestedOut = input.outputPath ?? join(getProjectCwd(), '.monomind', 'export');
-            const outDir = resolve(requestedOut);
+            const outDir = resolve(getProjectCwd(), requestedOut);
             const allowedRoot = resolve(getProjectCwd());
             if (outDir !== allowedRoot && !outDir.startsWith(allowedRoot + sep)) {
                 return text(`Error: outputPath must be within the project directory (${allowedRoot})`);
@@ -1072,8 +1093,10 @@ const monographImpactTool = {
             const impactPath = typeof rawImpactPath === 'string' && rawImpactPath.length > MAX_IMPACT_PATH_LEN
                 ? rawImpactPath.slice(0, MAX_IMPACT_PATH_LEN) : rawImpactPath;
             const rawDepth = input.depth;
-            const depth = typeof rawDepth === 'number' && Number.isFinite(rawDepth) && rawDepth > 0
-                ? Math.min(Math.floor(rawDepth), 6) : rawDepth;
+            const depth = rawDepth === undefined
+                ? undefined
+                : (typeof rawDepth === 'number' && Number.isFinite(rawDepth) && rawDepth > 0
+                    ? Math.min(Math.floor(rawDepth), 6) : 3);
             const result = getMonographImpact(db, {
                 name: impactName,
                 filePath: impactPath,
@@ -1737,10 +1760,10 @@ const monographInstallSkillsTool = {
             return text(`Invalid platform "${platform}". Must be one of: ${validPlatforms.join(', ')}`);
         }
         // Load community data from graph
-        const dbPath = join(repoPath, '.monomind', 'monograph.db');
+        const dbPath = getDbPath(repoPath);
         let db;
         try {
-            db = openDb(dbPath);
+            db = openDb(dbPath, { fileMustExist: true });
         }
         catch {
             return text('Graph not built yet. Run monograph_build first.');
@@ -1846,21 +1869,19 @@ const monographListReposTool = {
 // ── monograph_group_contracts ─────────────────────────────────────────────────
 const monographGroupContractsTool = {
     name: 'monograph_group_contracts',
-    description: 'List public API contracts (exported symbols, interfaces, and types) for all groups defined in .monograph/groups.json.',
+    description: 'List public API contracts (exported symbols, interfaces, and types) for all groups defined in group.yaml.',
     inputSchema: {
         type: 'object',
         properties: {
-            repoPath: { type: 'string', description: 'Absolute path to the repository (defaults to cwd).' },
+            configPath: { type: 'string', description: 'Path to group.yaml (defaults to group.yaml in project cwd)' },
         },
     },
     handler: async (input) => {
         const { getGroupContracts } = await import('./monograph-compat.js');
-        const { join } = await import('path');
-        const repoPath = input.repoPath ?? getProjectCwd();
-        const configPath = join(repoPath, '.monograph', 'groups.json');
+        const configPath = input.configPath ?? join(getProjectCwd(), 'group.yaml');
         const contracts = await getGroupContracts(configPath);
         if (contracts.length === 0)
-            return text('No contracts found. Ensure groups are defined in .monograph/groups.json.');
+            return text(`No contracts found. Ensure groups are defined in ${configPath}.`);
         const lines = contracts.map(c => `[${c.groupName}] ${c.symbol} — ${c.filePath}:${c.line}`);
         return text(lines.join('\n'));
     },
@@ -1872,14 +1893,12 @@ const monographGroupStatusTool = {
     inputSchema: {
         type: 'object',
         properties: {
-            repoPath: { type: 'string', description: 'Absolute path to the repository (defaults to cwd).' },
+            configPath: { type: 'string', description: 'Path to group.yaml (defaults to group.yaml in project cwd)' },
         },
     },
     handler: async (input) => {
         const { getGroupStatus } = await import('./monograph-compat.js');
-        const { join } = await import('path');
-        const repoPath = input.repoPath ?? getProjectCwd();
-        const configPath = join(repoPath, '.monograph', 'groups.json');
+        const configPath = input.configPath ?? join(getProjectCwd(), 'group.yaml');
         const status = await getGroupStatus(configPath);
         const lines = [`Groups: ${status.totalGroups} (${status.indexedGroups} indexed, ${status.stalledGroups} stalled)`];
         for (const g of status.groups) {
@@ -1954,10 +1973,10 @@ const monographDeadCodeTool = {
         const repoPath = input.path ?? getProjectCwd();
         const cats = input.categories ?? ['dead-functions', 'orphan-files', 'stale-dist'];
         const result = {};
-        const dbPath = join(repoPath, '.monomind', 'monograph.db');
+        const dbPath = getDbPath(repoPath);
         let db = null;
         try {
-            db = openDb(dbPath);
+            db = openDb(dbPath, { fileMustExist: true });
         }
         catch {
             return text(JSON.stringify({ error: 'No monograph index found. Run monograph_build first.' }));
@@ -1997,9 +2016,12 @@ const monographDeadCodeTool = {
           FROM nodes n
           WHERE n.label = 'File'
             AND (SELECT COUNT(*) FROM edges e WHERE e.target_id = n.id AND e.relation = 'IMPORTS') = 0
-            AND n.file_path NOT LIKE '%test%'
+            AND n.file_path NOT LIKE '%/test/%'
+            AND n.file_path NOT LIKE '%/tests/%'
+            AND n.file_path NOT LIKE '%.test.%'
             AND n.file_path NOT LIKE '%__tests__%'
-            AND n.file_path NOT LIKE '%spec%'
+            AND n.file_path NOT LIKE '%/spec/%'
+            AND n.file_path NOT LIKE '%.spec.%'
             AND n.file_path NOT LIKE '%/index.%'
             AND n.file_path NOT LIKE 'bin/%'
             AND n.file_path NOT LIKE 'scripts/%'

package/packages/@monomind/cli/dist/src/mcp-tools/swarm-tools.js

@@ -7,13 +7,14 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { randomBytes } from 'node:crypto';
-import { getProjectCwd } from './types.js';
+import { getMonomindDataRoot, migrateLegacyStoreFile } from './types.js';
 import { agentTools } from './agent-tools.js';
-// Swarm state persistence
-const SWARM_DIR = '.monomind/swarm';
+// Swarm state persistence — relative to the git-safe data root (see
+// getMonomindDataRoot()), matching agent/task/hive-mind stores.
+const SWARM_DIR = 'swarm';
 const SWARM_STATE_FILE = 'swarm-state.json';
 function getSwarmDir() {
-    return join(getProjectCwd(), SWARM_DIR);
+    return join(getMonomindDataRoot(), SWARM_DIR);
 }
 function getSwarmStatePath() {
     return join(getSwarmDir(), SWARM_STATE_FILE);
@@ -28,6 +29,7 @@ const MAX_SWARM_STORE_BYTES = 10 * 1024 * 1024;
 function loadSwarmStore() {
     try {
         const path = getSwarmStatePath();
+        migrateLegacyStoreFile(path, join(SWARM_DIR, SWARM_STATE_FILE));
         if (existsSync(path)) {
             if (statSync(path).size > MAX_SWARM_STORE_BYTES)
                 return { swarms: {}, version: '3.0.0' };

package/packages/@monomind/cli/dist/src/mcp-tools/system-tools.js

@@ -8,7 +8,7 @@
  * - process.cpuUsage() for real CPU stats
  * - os module for system information
  */
-import { getProjectCwd } from './types.js';
+import { getProjectCwd, getMonomindDataRoot } from './types.js';
 import { existsSync, readFileSync, statSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -184,7 +184,7 @@ export const systemTools = [
             // Fallback: JSON store files (backward compatibility)
             if (_metricsSource === 'none') {
                 try {
-                    const agentStorePath = join(getProjectCwd(), STORAGE_DIR, 'agents', 'store.json');
+                    const agentStorePath = join(getMonomindDataRoot(), 'agents', 'store.json');
                     if (existsSync(agentStorePath) && statSync(agentStorePath).size <= MAX_SYSTEM_STORE_BYTES) {
                         const agentStore = JSON.parse(readFileSync(agentStorePath, 'utf-8'));
                         const agents = Object.values(agentStore.agents || {});
@@ -197,7 +197,7 @@ export const systemTools = [
                 }
                 catch { /* agent store not available */ }
                 try {
-                    const taskStorePath = join(getProjectCwd(), STORAGE_DIR, 'tasks', 'store.json');
+                    const taskStorePath = join(getMonomindDataRoot(), 'tasks', 'store.json');
                     if (existsSync(taskStorePath) && statSync(taskStorePath).size <= MAX_SYSTEM_STORE_BYTES) {
                         const taskStore = JSON.parse(readFileSync(taskStorePath, 'utf-8'));
                         const tasks = Object.values(taskStore.tasks || {});
@@ -534,7 +534,7 @@ export const systemTools = [
         },
         handler: async () => {
             // Read from the task store file
-            const storePath = join(getProjectCwd(), '.monomind', 'tasks', 'store.json');
+            const storePath = join(getMonomindDataRoot(), 'tasks', 'store.json');
             let tasks = [];
             try {
                 if (existsSync(storePath) && statSync(storePath).size <= MAX_SYSTEM_STORE_BYTES) {

package/packages/@monomind/cli/dist/src/mcp-tools/types.d.ts

@@ -24,6 +24,26 @@ export interface MCPToolResult {
  */
 export declare function getProjectCwd(): string;
 export declare function getMonomindDataRoot(cwd?: string): string;
+/**
+ * One-time migration for the agent/task/hive/swarm stores that historically lived
+ * under `<projectCwd>/.monomind/<subpath>` (via getProjectCwd()) before being
+ * consolidated onto the canonical getMonomindDataRoot() location (typically
+ * `<repo>/.git/monomind/<subpath>`). Several MCP tool files (agent-tools.ts,
+ * hive-mind-tools.ts, swarm-tools.ts, system-tools.ts) used to read/write the
+ * legacy path directly, causing the same logical store to physically split from
+ * task-tools.ts/session-tools.ts, which always used getMonomindDataRoot().
+ *
+ * If the canonical file is missing but the legacy file exists, copy (never move,
+ * for safety) the legacy file into place so pre-existing data isn't silently
+ * orphaned. Best-effort and idempotent — never throws, and it's a no-op once the
+ * canonical file exists or when the two paths already coincide (e.g. no .git).
+ *
+ * @param canonicalPath Absolute path under getMonomindDataRoot() the tool now reads from.
+ * @param legacySubpath Path relative to `.monomind/` that the tool used to read from
+ *   (e.g. `join('agents', 'store.json')`).
+ * @param cwd Optional project cwd override (defaults to getProjectCwd()).
+ */
+export declare function migrateLegacyStoreFile(canonicalPath: string, legacySubpath: string, cwd?: string): void;
 export interface MCPTool {
     name: string;
     description: string;

package/packages/@monomind/cli/dist/src/mcp-tools/types.js

@@ -3,7 +3,7 @@
  *
  * Local type definitions to avoid external imports outside package boundary.
  */
-import { statSync, readFileSync } from 'node:fs';
+import { statSync, readFileSync, existsSync, mkdirSync, copyFileSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 /**
  * Returns the effective project working directory.
@@ -60,4 +60,39 @@ export function getMonomindDataRoot(cwd) {
     _dataRootCache.set(workDir, result);
     return result;
 }
+/**
+ * One-time migration for the agent/task/hive/swarm stores that historically lived
+ * under `<projectCwd>/.monomind/<subpath>` (via getProjectCwd()) before being
+ * consolidated onto the canonical getMonomindDataRoot() location (typically
+ * `<repo>/.git/monomind/<subpath>`). Several MCP tool files (agent-tools.ts,
+ * hive-mind-tools.ts, swarm-tools.ts, system-tools.ts) used to read/write the
+ * legacy path directly, causing the same logical store to physically split from
+ * task-tools.ts/session-tools.ts, which always used getMonomindDataRoot().
+ *
+ * If the canonical file is missing but the legacy file exists, copy (never move,
+ * for safety) the legacy file into place so pre-existing data isn't silently
+ * orphaned. Best-effort and idempotent — never throws, and it's a no-op once the
+ * canonical file exists or when the two paths already coincide (e.g. no .git).
+ *
+ * @param canonicalPath Absolute path under getMonomindDataRoot() the tool now reads from.
+ * @param legacySubpath Path relative to `.monomind/` that the tool used to read from
+ *   (e.g. `join('agents', 'store.json')`).
+ * @param cwd Optional project cwd override (defaults to getProjectCwd()).
+ */
+export function migrateLegacyStoreFile(canonicalPath, legacySubpath, cwd) {
+    try {
+        if (existsSync(canonicalPath))
+            return;
+        const legacyPath = join(cwd || getProjectCwd(), '.monomind', legacySubpath);
+        if (legacyPath === canonicalPath)
+            return;
+        if (!existsSync(legacyPath))
+            return;
+        mkdirSync(dirname(canonicalPath), { recursive: true });
+        copyFileSync(legacyPath, canonicalPath);
+    }
+    catch {
+        // Best-effort; leave both stores as-is on any failure.
+    }
+}
 //# sourceMappingURL=types.js.map

package/packages/@monomind/cli/dist/src/memory/hnsw-operations.d.ts

@@ -10,8 +10,20 @@ interface HNSWEntry {
     namespace: string;
     content: string;
 }
+/** Minimal shape of the real @monoes/memory HNSWIndex class relied on here. */
+interface RealHNSWIndex {
+    addPoint(id: string, vector: Float32Array): Promise<void>;
+    search(query: Float32Array, k: number, ef?: number): Promise<Array<{
+        id: string;
+        distance: number;
+    }>>;
+    rebuild(entries: Array<{
+        id: string;
+        vector: Float32Array;
+    }>): Promise<void>;
+}
 interface HNSWIndex {
-    db: any;
+    instance: RealHNSWIndex;
     entries: Map<string, HNSWEntry>;
     dimensions: number;
     initialized: boolean;

package/packages/@monomind/cli/dist/src/memory/hnsw-operations.js

@@ -24,14 +24,59 @@ async function getBridge() {
 }
 let hnswIndex = null;
 let hnswInitializing = false;
+/** Lazily import the pure-JS HNSWIndex class from the optional @monoes/memory package. */
+async function loadHNSWIndexClass() {
+    try {
+        const mod = await import('@monoes/memory');
+        return mod?.HNSWIndex ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read entries with parseable embeddings of the expected dimension from the sql.js DB. */
+async function loadEntriesFromDb(dbPath, dimensions) {
+    if (!fs.existsSync(dbPath))
+        return [];
+    const initSqlJs = (await import('sql.js')).default;
+    const SQL = await initSqlJs();
+    const fileBuffer = fs.readFileSync(dbPath);
+    const db = new SQL.Database(fileBuffer);
+    try {
+        const { safeParseEmbedding } = await import('./memory-bridge.js');
+        const stmt = db.prepare(`SELECT id, key, namespace, content, embedding FROM memory_entries WHERE status = 'active' AND embedding IS NOT NULL LIMIT 50000`);
+        const rows = [];
+        while (stmt.step())
+            rows.push(stmt.get());
+        stmt.free();
+        const results = [];
+        for (const row of rows) {
+            const [id, key, namespace, content, embeddingJson] = row;
+            const parsed = safeParseEmbedding(embeddingJson);
+            if (!parsed || parsed.length !== dimensions)
+                continue;
+            results.push({
+                id,
+                vector: new Float32Array(parsed),
+                entry: { id, key: key || id, namespace: namespace || 'default', content: content || '' },
+            });
+        }
+        return results;
+    }
+    finally {
+        db.close();
+    }
+}
 /**
  * Get or create the HNSW index singleton
  * Lazily initializes from SQLite data on first use
  */
 export async function getHNSWIndex(options) {
     const dimensions = options?.dimensions ?? 384;
-    // Return existing index if already initialized
-    if (hnswIndex?.initialized && !options?.forceRebuild) {
+    // Return existing index if already initialized for the same dimensionality.
+    // A cached index built for a different embedding size must be rebuilt —
+    // otherwise addPoint()/search() silently fail (or corrupt) on the mismatch.
+    if (hnswIndex?.initialized && hnswIndex.dimensions === dimensions && !options?.forceRebuild) {
         return hnswIndex;
     }
     // Prevent concurrent initialization
@@ -50,13 +95,23 @@ export async function getHNSWIndex(options) {
     }
     hnswInitializing = true;
     try {
-        // Native @monoes/core HNSW (WASM VectorDb) was removed in the lean teardown.
-        // This function is kept for callers that check its return value — all callers
-        // already handle null by falling back to the pure-JS / brute-force path.
-        // The memory bridge (memory-bridge.ts) provides ANN search via LanceDB.
-        // Native backend removed — return null so callers use the pure-JS fallback.
+        const HNSWIndexClass = await loadHNSWIndexClass();
+        if (!HNSWIndexClass) {
+            // @monoes/memory isn't installed — no pure-JS fallback available;
+            // callers fall through to brute-force search.
+            hnswInitializing = false;
+            return null;
+        }
+        const dbPath = options?.dbPath ?? path.join(process.cwd(), '.swarm', 'memory.db');
+        const loaded = await loadEntriesFromDb(dbPath, dimensions);
+        const instance = new HNSWIndexClass({ dimensions });
+        await instance.rebuild(loaded.map((l) => ({ id: l.id, vector: l.vector })));
+        const entries = new Map();
+        for (const l of loaded)
+            entries.set(l.id, l.entry);
+        hnswIndex = { instance, entries, dimensions, initialized: true };
         hnswInitializing = false;
-        return null;
+        return hnswIndex;
     }
     catch {
         hnswInitializing = false;
@@ -90,10 +145,7 @@ export async function addToHNSWIndex(id, embedding, entry) {
         return false;
     try {
         const vector = new Float32Array(embedding);
-        await index.db.insert({
-            id,
-            vector
-        });
+        await index.instance.addPoint(id, vector);
         index.entries.set(id, entry);
         // Save metadata for persistence (debounced would be better for high-volume)
         saveHNSWMetadata();
@@ -115,7 +167,7 @@ export async function searchHNSWIndex(queryEmbedding, options) {
         const vector = new Float32Array(queryEmbedding);
         const k = options?.k ?? 10;
         // HNSW search returns results with cosine distance (lower = more similar)
-        const results = await index.db.search({ vector, k: k * 2 }); // Get extra for filtering
+        const results = await index.instance.search(vector, k * 2); // Get extra for filtering
         const filtered = [];
         for (const result of results) {
             const entry = index.entries.get(result.id);
@@ -127,7 +179,7 @@ export async function searchHNSWIndex(queryEmbedding, options) {
             }
             // Convert cosine distance to similarity score (1 - distance)
             // Cosine distance convention: 0 = identical, 2 = opposite
-            const score = 1 - (result.score / 2);
+            const score = 1 - (result.distance / 2);
             filtered.push({
                 id: entry.id.substring(0, 12),
                 key: entry.key || entry.id.substring(0, 15),