monomind 2.3.4 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monomind",
-  "version": "2.3.4",
+  "version": "2.4.0",
   "description": "Open-source CLI extension for Claude Code. Adds an MCP server with a codebase knowledge graph, persistent memory, multi-agent coordination, and reusable slash commands. MIT licensed, runs locally, no data leaves your machine.",
   "main": "dist/index.js",
   "type": "module",

package/packages/@monomind/cli/.claude/helpers/handlers/route-handler.cjs

@@ -368,7 +368,10 @@ module.exports = {
               if (sbResp.ok) {
                 var sbData = await sbResp.json();
                 if (sbData && Array.isArray(sbData.results) && sbData.results.length > 0) {
-                  sbHits = sbData.results.map(function(r) { return { key: r.key, value: r.content, score: r.score, metadata: {} }; });
+                  sbHits = sbData.results.map(function(r) {
+                    var src = (r.tags || []).find(function(t) { return t.indexOf('src:') === 0; });
+                    return { key: r.key, value: r.content, score: r.score, global: !!r.global, metadata: src ? { filePath: src.slice(4) } : {} };
+                  });
                   sbMethod = sbData.method === 'semantic' ? 'semantic' : 'keyword';
                 }
               }
@@ -415,7 +418,7 @@ module.exports = {
                 var sbH = sbHits[sbI];
                 var sbSrc = (sbH.metadata && sbH.metadata.filePath) ? String(sbH.metadata.filePath).split('/').slice(-2).join('/') : sbH.key;
                 var sbText = String(sbH.value || '').replace(/\s+/g, ' ').slice(0, 240);
-                sbLines.push('  • [' + sbSrc + '] ' + sbText);
+                sbLines.push('  • [' + sbSrc + (sbH.global ? ' · global' : '') + '] ' + sbText);
               }
               sbLines.push('  (deeper lookup: mcp__monomind__knowledge_search or `monomind doc search -q "..."`)');
               console.log(sbLines.join('\n'));

package/packages/@monomind/cli/dist/src/commands/doc.js

@@ -3,22 +3,41 @@
  */
 import * as path from 'node:path';
 import { output } from '../output.js';
+import { getGlobalBrainDir } from '../memory/memory-bridge.js';
 const ingestCommand = {
     name: 'ingest',
     description: 'Ingest documents into the knowledge base',
     options: [
-        { name: 'scope', short: 's', description: 'Knowledge scope (default: shared)', type: 'string', default: 'shared' },
+        // No `default` on scope: the auto-global routing below must be able to
+        // tell "user typed --scope shared" apart from "user typed nothing" — a
+        // parser-injected default makes them indistinguishable.
+        { name: 'scope', short: 's', description: 'Knowledge scope (default: shared; auto-routes to global for paths outside the project)', type: 'string' },
+        { name: 'global', short: 'g', description: 'Ingest into the personal cross-project global brain (~/.monomind/global-brain)', type: 'boolean' },
     ],
     examples: [
         { command: 'monomind doc ingest ./docs', description: 'Ingest all docs in a directory' },
+        { command: 'monomind doc ingest ~/notes --global', description: 'Ingest into the global brain (auto-detected for paths outside the project)' },
         { command: 'monomind doc ingest report.pdf', description: 'Ingest a single file' },
     ],
     action: async (ctx) => {
         const target = ctx.args[0] || '.';
-        const scope = String(ctx.flags.scope || 'shared');
         const { ingestDocument, ingestDirectory } = await import('../knowledge/document-pipeline.js');
         const fs = await import('node:fs');
         const resolved = path.resolve(target);
+        // Zero-decision routing: an explicit --global wins; otherwise paths OUTSIDE
+        // the current project belong to the personal brain (a project store keyed
+        // to this cwd would never see them again from another project).
+        let scope = String(ctx.flags.scope || 'shared');
+        if (ctx.flags.global === true) {
+            scope = 'global';
+        }
+        else if (!ctx.flags.scope) {
+            const relToCwd = path.relative(process.cwd(), resolved);
+            if (relToCwd.startsWith('..') || path.isAbsolute(relToCwd)) {
+                scope = 'global';
+                output.writeln(output.dim(`  ${target} is outside this project — ingesting into the global brain (use --scope shared to force project scope)`));
+            }
+        }
         const spinner = output.createSpinner({ text: 'Indexing documents...' });
         spinner.start();
         try {
@@ -68,9 +87,11 @@ const searchDocCommand = {
         { name: 'limit', short: 'l', description: 'Max results (default: 10)', type: 'number', default: 10 },
         { name: 'scope', short: 's', description: 'Knowledge scope (default: shared)', type: 'string', default: 'shared' },
         { name: 'min-score', description: 'Minimum similarity (default: 0.3)', type: 'number', default: 0.3 },
+        { name: 'store', description: 'Which store(s): project | global | all (default: all — project results win ties)', type: 'string', default: 'all' },
     ],
     examples: [
-        { command: 'monomind doc search -q "authentication flow"', description: 'Search for auth docs' },
+        { command: 'monomind doc search -q "authentication flow"', description: 'Search project + global brain' },
+        { command: 'monomind doc search -q "pricing notes" --store global', description: 'Search only the personal global brain' },
     ],
     action: async (ctx) => {
         const query = String(ctx.flags.query || ctx.args[0] || '');
@@ -79,10 +100,12 @@ const searchDocCommand = {
             return { success: false, exitCode: 1 };
         }
         const { searchKnowledge } = await import('../knowledge/document-pipeline.js');
+        const storeFlag = String(ctx.flags.store || 'all');
         const excerpts = await searchKnowledge(query, {
             scope: String(ctx.flags.scope || 'shared'),
             limit: Number(ctx.flags.limit || 10),
             minScore: Number(ctx.flags['min-score'] || 0.3),
+            store: storeFlag === 'project' || storeFlag === 'global' ? storeFlag : 'all',
         });
         if (!excerpts.length) {
             output.writeln(output.dim('No results found.'));
@@ -92,7 +115,8 @@ const searchDocCommand = {
         output.writeln();
         for (let i = 0; i < excerpts.length; i++) {
             const ex = excerpts[i];
-            output.writeln(`${output.highlight(`${i + 1}.`)} ${output.dim(`(${ex.similarity.toFixed(3)})`)} ${ex.filePath || 'unknown'}`);
+            const origin = ex.scope === 'global' ? ` ${output.dim('[global]')}` : '';
+            output.writeln(`${output.highlight(`${i + 1}.`)} ${output.dim(`(${ex.similarity.toFixed(3)})`)} ${ex.filePath || 'unknown'}${origin}`);
             const preview = ex.text.length > 200 ? ex.text.slice(0, 200) + '...' : ex.text;
             output.writeln(`   ${output.dim(preview)}`);
             output.writeln();
@@ -105,11 +129,13 @@ const listDocCommand = {
     description: 'List indexed documents',
     options: [
         { name: 'scope', short: 's', description: 'Knowledge scope', type: 'string' },
+        { name: 'global', short: 'g', description: 'List the personal cross-project global brain', type: 'boolean' },
     ],
     action: async (ctx) => {
         const { listDocuments } = await import('../knowledge/document-pipeline.js');
-        const scope = ctx.flags.scope ? String(ctx.flags.scope) : undefined;
-        const docs = listDocuments(process.cwd(), scope);
+        const isGlobal = ctx.flags.global === true;
+        const scope = isGlobal ? 'global' : ctx.flags.scope ? String(ctx.flags.scope) : undefined;
+        const docs = listDocuments(isGlobal ? getGlobalBrainDir() : process.cwd(), scope);
         if (!docs.length) {
             output.writeln(output.dim('No documents indexed. Run: monomind doc ingest <path>'));
             return { success: true, data: [] };
@@ -133,15 +159,17 @@ const exportDocCommand = {
     options: [
         { name: 'output', short: 'o', description: 'Output directory', type: 'string', default: '.monomind/knowledge-export' },
         { name: 'scope', short: 's', description: 'Knowledge scope (default: shared)', type: 'string', default: 'shared' },
+        { name: 'global', short: 'g', description: 'Export the personal cross-project global brain (portable between machines)', type: 'boolean' },
     ],
     action: async (ctx) => {
         const { exportToOKF } = await import('../knowledge/document-pipeline.js');
         const outDir = path.resolve(String(ctx.flags.output || '.monomind/knowledge-export'));
-        const scope = String(ctx.flags.scope || 'shared');
+        const isGlobal = ctx.flags.global === true;
+        const scope = isGlobal ? 'global' : String(ctx.flags.scope || 'shared');
         const spinner = output.createSpinner({ text: 'Exporting to OKF...' });
         spinner.start();
         try {
-            const result = await exportToOKF(outDir, process.cwd(), scope);
+            const result = await exportToOKF(outDir, isGlobal ? getGlobalBrainDir() : process.cwd(), scope);
             spinner.succeed(`Exported ${result.exported} documents to ${result.outputDir}`);
             return { success: true, data: result };
         }

package/packages/@monomind/cli/dist/src/index.js

@@ -220,6 +220,13 @@ export class CLI {
                     this.output.printDebug(`Completed in ${Date.now() - startTime}ms`);
                 }
                 if (result && !result.success) {
+                    // Always surface the failure reason: many actions return
+                    // { success: false, message } without logging, and exiting 1 with
+                    // zero output left users guessing (swarm finding #12). Actions that
+                    // already printed a rich error produce one extra terse summary line
+                    // — acceptable; silence is not.
+                    if (result.message)
+                        this.output.printError(result.message);
                     process.exit(result.exitCode || 1);
                 }
             }

package/packages/@monomind/cli/dist/src/knowledge/document-pipeline.d.ts

@@ -43,6 +43,8 @@ export declare function searchKnowledge(query: string, opts?: {
     limit?: number;
     minScore?: number;
     rootDir?: string;
+    /** which store(s): project-only, global-only, or both (default). */
+    store?: 'project' | 'global' | 'all';
 }): Promise<KnowledgeExcerpt[]>;
 export declare function listDocuments(rootDir?: string, scope?: string): DocumentMeta[];
 export declare function removeDocument(filePath: string, scope?: string, rootDir?: string): Promise<void>;

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

@@ -7,6 +7,14 @@
  * @module v1/cli/memory-bridge
  */
 export declare function safeParseEmbedding(raw: string | null | undefined): number[] | null;
+/** The personal, cross-project knowledge store. Deliberately a SIBLING of
+ *  ~/.monomind/projects (never inside it) so per-project pruning heuristics
+ *  (`cleanup --data`) can never touch it. Env-overridable for tests and for
+ *  users who keep their brain on a synced/external location. Resolved lazily
+ *  so the override works regardless of import order. */
+export declare function getGlobalBrainDir(): string;
+/** Sentinel callers pass as dbPath to address the global brain. */
+export declare const GLOBAL_BRAIN = "@global";
 /** Resolve the real on-disk LanceDB path for a given custom path (or the default). */
 export declare function bridgeGetDbPath(customPath?: string): string;
 export declare function bridgeStoreEntry(options: {
@@ -46,6 +54,7 @@ export declare function bridgeSearchEntries(options: {
         score: number;
         namespace: string;
         provenance?: string;
+        tags?: string[];
     }[];
     searchTime: number;
     searchMethod?: string;

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

@@ -70,22 +70,37 @@ function realOrResolved(p) {
         return p;
     }
 }
+/** The personal, cross-project knowledge store. Deliberately a SIBLING of
+ *  ~/.monomind/projects (never inside it) so per-project pruning heuristics
+ *  (`cleanup --data`) can never touch it. Env-overridable for tests and for
+ *  users who keep their brain on a synced/external location. Resolved lazily
+ *  so the override works regardless of import order. */
+export function getGlobalBrainDir() {
+    return process.env.MONOMIND_GLOBAL_BRAIN_DIR || path.join(os.homedir(), '.monomind', 'global-brain');
+}
+/** Sentinel callers pass as dbPath to address the global brain. */
+export const GLOBAL_BRAIN = '@global';
 function getDbPath(customPath) {
     const defaultDir = path.join(projectDataDir(), 'lancedb');
     if (!customPath || customPath === ':memory:')
         return defaultDir;
+    if (customPath === GLOBAL_BRAIN)
+        return getGlobalBrainDir();
     // Treat legacy .db paths (and the legacy .swarm dir) as a signal to use the default
     if (customPath.endsWith('.db'))
         return defaultDir;
     const resolved = realOrResolved(path.resolve(customPath));
     // Guard against path traversal from MCP inputs: only allow paths inside the
-    // project or inside the per-project home data dir.
+    // project, the per-project home data dir, or the global brain.
     const relCwd = path.relative(realOrResolved(process.cwd()), resolved);
     const relHome = path.relative(realOrResolved(projectDataDir()), resolved);
+    const relGlobal = path.relative(realOrResolved(getGlobalBrainDir()), resolved);
     if (!relCwd.startsWith('..') && !path.isAbsolute(relCwd))
         return resolved;
     if (!relHome.startsWith('..') && !path.isAbsolute(relHome))
         return resolved;
+    if (!relGlobal.startsWith('..') && !path.isAbsolute(relGlobal))
+        return resolved;
     return defaultDir;
 }
 /** Resolve the real on-disk LanceDB path for a given custom path (or the default). */
@@ -114,13 +129,10 @@ function getAutomemConfig() {
 function generateId(prefix) {
     return `${prefix}_${Date.now()}_${crypto.randomBytes(8).toString('hex')}`;
 }
-// ===== Lazy singleton LanceDB backend =====
-let backendPromise = null;
-let backendInstance = null;
-let bridgeAvailable = null;
+const backendSlots = new Map();
 let _embedder = null;
+let _embedderPromise = null;
 const MAX_INIT_ATTEMPTS = 3;
-let initAttempts = 0;
 /** Flush after mutations: the sql.js fallback backend is in-memory WASM and
  *  only reaches disk via persist(); the CLI process is short-lived, so waiting
  *  for an auto-persist interval would lose writes. No-op on better-sqlite3. */
@@ -130,59 +142,73 @@ async function flushBackend(backend) {
     }
     catch { /* best effort */ }
 }
+async function loadEmbedder() {
+    if (_embedder)
+        return;
+    if (!_embedderPromise) {
+        _embedderPromise = (async () => {
+            try {
+                const hf = await import('@huggingface/transformers');
+                // revision must be a git ref — 'main' is the HF default; 'default' 404s and
+                // silently killed embeddings (every search degraded to keyword matching)
+                // dtype pinned explicitly: transformers.js logs a "dtype not specified"
+                // warning to the console on every load otherwise (leaks into CLI output).
+                const extractor = await hf.pipeline('feature-extraction', BRIDGE_EMBEDDING_MODEL, { revision: 'main', dtype: 'fp32' });
+                _embedder = async (text) => {
+                    const output = await extractor(text, { pooling: 'mean', normalize: true });
+                    return new Float32Array(output.data);
+                };
+            }
+            catch (e) {
+                _embedderPromise = null; // allow retry (e.g. first call offline)
+                if (process.env.DEBUG || process.env.MONOMIND_DEBUG)
+                    console.error('[memory-bridge] embedding model failed to load — store and search without vectors:', e);
+            }
+        })();
+    }
+    await _embedderPromise;
+}
 async function getBackend(dbPath) {
-    if (bridgeAvailable === false)
+    const dir = getDbPath(dbPath);
+    let slot = backendSlots.get(dir);
+    if (!slot) {
+        slot = { promise: null, instance: null, available: null, attempts: 0 };
+        backendSlots.set(dir, slot);
+    }
+    if (slot.available === false)
         return null;
-    if (initAttempts >= MAX_INIT_ATTEMPTS) {
-        bridgeAvailable = false;
+    if (slot.attempts >= MAX_INIT_ATTEMPTS) {
+        slot.available = false;
         return null;
     }
-    if (backendInstance)
-        return backendInstance;
-    if (!backendPromise) {
-        backendPromise = (async () => {
+    if (slot.instance)
+        return slot.instance;
+    if (!slot.promise) {
+        slot.promise = (async () => {
             try {
                 const mod = await import('@monoes/memory');
-                // Try to create embedding generator from HuggingFace transformers
-                let embeddingGenerator;
-                try {
-                    const hf = await import('@huggingface/transformers');
-                    // revision must be a git ref — 'main' is the HF default; 'default' 404s and
-                    // silently killed embeddings (every search degraded to keyword matching)
-                    // dtype pinned explicitly: transformers.js logs a "dtype not specified"
-                    // warning to the console on every load otherwise (leaks into CLI output).
-                    const extractor = await hf.pipeline('feature-extraction', BRIDGE_EMBEDDING_MODEL, { revision: 'main', dtype: 'fp32' });
-                    embeddingGenerator = async (text) => {
-                        const output = await extractor(text, { pooling: 'mean', normalize: true });
-                        return new Float32Array(output.data);
-                    };
-                    _embedder = embeddingGenerator;
-                }
-                catch (e) {
-                    if (process.env.DEBUG || process.env.MONOMIND_DEBUG)
-                        console.error('[memory-bridge] embedding model failed to load — store and search without vectors:', e);
-                }
+                await loadEmbedder();
                 // Local SQLite engine (LanceDB replaced 2026-07): better-sqlite3 when its
                 // native binding loads, sql.js (pure WASM) otherwise — both persist text
                 // AND embeddings, so vectors are always recomputable/derivable data.
-                // getDbPath keeps its traversal guard and directory semantics; the SQLite
-                // file lives inside that directory.
-                const dir = getDbPath(dbPath);
                 fs.mkdirSync(dir, { recursive: true });
                 // Origin marker: records which project this data dir belongs to, so
                 // `monomind cleanup --data` can verifiably prune dirs whose project
-                // no longer exists (the dir-name hash is one-way). Best-effort.
-                try {
-                    const originFile = path.join(projectDataDir(), 'origin.json');
-                    fs.writeFileSync(originFile, JSON.stringify({ path: path.resolve(process.cwd()), updatedAt: new Date().toISOString() }) + '\n', 'utf-8');
+                // no longer exists (the dir-name hash is one-way). Best-effort; never
+                // written for the global brain (it has no single origin project).
+                if (dir !== getGlobalBrainDir()) {
+                    try {
+                        const originFile = path.join(projectDataDir(), 'origin.json');
+                        fs.writeFileSync(originFile, JSON.stringify({ path: path.resolve(process.cwd()), updatedAt: new Date().toISOString() }) + '\n', 'utf-8');
+                    }
+                    catch { /* non-fatal */ }
                 }
-                catch { /* non-fatal */ }
                 const cfg = {
                     databasePath: path.join(dir, 'memory.db'),
                     walMode: true,
                     optimize: true,
                     defaultNamespace: 'default',
-                    embeddingGenerator,
+                    embeddingGenerator: _embedder ?? undefined,
                 };
                 const origLog = console.log;
                 console.log = (...args) => {
@@ -207,20 +233,20 @@ async function getBackend(dbPath) {
                 finally {
                     console.log = origLog;
                 }
-                backendInstance = backend;
-                bridgeAvailable = true;
+                slot.instance = backend;
+                slot.available = true;
                 return backend;
             }
             catch {
-                initAttempts++;
-                backendPromise = null;
-                if (initAttempts >= MAX_INIT_ATTEMPTS)
-                    bridgeAvailable = false;
+                slot.attempts++;
+                slot.promise = null;
+                if (slot.attempts >= MAX_INIT_ATTEMPTS)
+                    slot.available = false;
                 return null;
             }
         })();
     }
-    return backendPromise;
+    return slot.promise;
 }
 // ===== Core CRUD =====
 export async function bridgeStoreEntry(options) {
@@ -332,6 +358,7 @@ export async function bridgeSearchEntries(options) {
                     score: r.score,
                     namespace: r.entry.namespace,
                     provenance: `semantic:${r.score.toFixed(3)}`,
+                    tags: r.entry.tags ?? [],
                     _createdAt: r.entry.createdAt || 0,
                 }));
                 searchMethod = 'semantic';
@@ -370,6 +397,7 @@ export async function bridgeSearchEntries(options) {
                     score: Math.min(0.9, 0.3 + score * 0.6),
                     namespace: e.namespace,
                     provenance: `keyword:${score.toFixed(2)}`,
+                    tags: e.tags ?? [],
                     _createdAt: e.createdAt || 0,
                 }));
             }
@@ -598,17 +626,17 @@ export async function getControllerRegistry(dbPath) {
     return getBackend(dbPath);
 }
 export async function shutdownBridge() {
-    if (backendInstance) {
-        try {
-            await backendInstance.shutdown();
+    for (const slot of backendSlots.values()) {
+        if (slot.instance) {
+            try {
+                await slot.instance.shutdown();
+            }
+            catch { /* ignore */ }
         }
-        catch { /* ignore */ }
     }
-    backendInstance = null;
-    backendPromise = null;
-    bridgeAvailable = null;
+    backendSlots.clear();
     _embedder = null;
-    initAttempts = 0;
+    _embedderPromise = null;
 }
 // ===== Pattern store =====
 export async function bridgeStorePattern(options) {

package/packages/@monomind/cli/dist/src/ui/server.mjs

@@ -5950,11 +5950,21 @@ new Sigma(g,document.getElementById('g'),{renderEdgeLabels:false,labelColor:{col
             res.end('{"error":"knowledge bridge unavailable"}');
             return;
           }
-          const out = await bridge.bridgeSearchEntries({ query, namespace, limit });
+          // scope: project | global | all (default all) — project results get a
+          // small tie boost; global hits are flagged so callers can show origin.
+          const scope = payload.scope === 'project' || payload.scope === 'global' ? payload.scope : 'all';
+          const [proj, glob] = await Promise.all([
+            scope !== 'global' ? bridge.bridgeSearchEntries({ query, namespace, limit }).catch(() => null) : null,
+            scope !== 'project' ? bridge.bridgeSearchEntries({ query, namespace: 'knowledge:global', limit, dbPath: '@global' }).catch(() => null) : null,
+          ]);
+          const merged = [
+            ...(proj?.results || []).map(r => ({ key: r.key, content: String(r.content || '').slice(0, 2000), score: r.score + 0.05, global: false, tags: r.tags })),
+            ...(glob?.results || []).map(r => ({ key: r.key, content: String(r.content || '').slice(0, 2000), score: r.score, global: true, tags: r.tags })),
+          ].sort((a, b) => b.score - a.score).slice(0, limit);
           res.writeHead(200, { 'Content-Type': 'application/json', ...(corsOrigin ? { 'Access-Control-Allow-Origin': corsOrigin } : {}) });
           res.end(JSON.stringify({
-            method: out?.searchMethod || 'none',
-            results: (out?.results || []).map(r => ({ key: r.key, content: String(r.content || '').slice(0, 2000), score: r.score })),
+            method: proj?.searchMethod || glob?.searchMethod || 'none',
+            results: merged,
           }));
         } catch (err) {
           res.writeHead(500, { 'Content-Type': 'application/json' });

package/packages/@monomind/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monoes/monomindcli",
-  "version": "2.3.4",
+  "version": "2.4.0",
   "type": "module",
   "description": "CLI engine for Monomind — an open-source MCP server that extends Claude Code with a codebase knowledge graph (tree-sitter + SQLite), persistent memory, multi-agent task coordination, and session hooks. MIT licensed, fully local.",
   "main": "dist/src/index.js",