monomind 2.3.4 → 2.5.0

package/README.md

@@ -223,6 +223,8 @@ monomind doc list                  # what's indexed
 monomind doc export                # portable OKF bundle — move your brain between machines
 ```
 
+**And it follows you across projects.** Ingest a path from *outside* the current project (`monomind doc ingest ~/notes`, or add `--global`) and it lands in your personal global brain at `~/.monomind/global-brain` — searchable from every project on the machine. All retrieval (CLI search, per-prompt injection, the dashboard) merges both stores automatically, with project knowledge winning ties and global hits labeled `[global]`. `doc export --global` moves your whole brain between machines as an OKF bundle — still no cloud, ever.
+
 Retrieval quality is a tested invariant, not a hope: a golden-set eval (paraphrase queries against notes written in different vocabulary) runs in CI with an 80% recall bar.
 
 > **Privacy note:** the embedding model (~90MB) is fetched once from HuggingFace's CDN when your first document is indexed, then cached locally forever. That download is the only outbound request the Second Brain ever makes — your documents and queries never leave your machine. Offline at first index? Search degrades gracefully to keyword matching and `monomind doctor` tells you how to warm up later.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monomind",
-  "version": "2.3.4",
+  "version": "2.5.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/README.md

@@ -223,6 +223,8 @@ monomind doc list                  # what's indexed
 monomind doc export                # portable OKF bundle — move your brain between machines
 ```
 
+**And it follows you across projects.** Ingest a path from *outside* the current project (`monomind doc ingest ~/notes`, or add `--global`) and it lands in your personal global brain at `~/.monomind/global-brain` — searchable from every project on the machine. All retrieval (CLI search, per-prompt injection, the dashboard) merges both stores automatically, with project knowledge winning ties and global hits labeled `[global]`. `doc export --global` moves your whole brain between machines as an OKF bundle — still no cloud, ever.
+
 Retrieval quality is a tested invariant, not a hope: a golden-set eval (paraphrase queries against notes written in different vocabulary) runs in CI with an 80% recall bar.
 
 > **Privacy note:** the embedding model (~90MB) is fetched once from HuggingFace's CDN when your first document is indexed, then cached locally forever. That download is the only outbound request the Second Brain ever makes — your documents and queries never leave your machine. Offline at first index? Search degrades gracefully to keyword matching and `monomind doctor` tells you how to warm up later.

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/init/claudemd-generator.js

@@ -399,12 +399,15 @@ If the \`documents\` capability is active (check \`.monomind/capabilities.json\`
 
 **CLI access:**
 \`\`\`bash
-monomind doc search -q "your query"    # Semantic search
-monomind doc list                       # List indexed docs
-monomind doc ingest ./path              # Ingest new documents
-monomind doc export                     # Export as OKF bundle
+monomind doc search -q "your query"    # Semantic search (project + global brain merged)
+monomind doc search -q "..." --store global   # Personal global brain only
+monomind doc list                       # List indexed docs (--global for the global brain)
+monomind doc ingest ./path              # Ingest new documents (paths outside the project auto-route to the global brain)
+monomind doc export                     # Export as OKF bundle (--global to move your brain between machines)
 \`\`\`
 
+**Global brain:** the user has a personal cross-project knowledge store at \`~/.monomind/global-brain\`. All searches (knowledge_search, doc search, per-prompt injection) automatically merge it with project knowledge — project results win ties, global hits are labeled \`[global]\`. Cite the label so the user knows which brain answered.
+
 **Re-indexing** happens automatically on session start (unchanged files are skipped via content hash).`;
 }
 function graphifySection() {

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/orgrt/daemon.d.ts

@@ -113,6 +113,14 @@ export declare class OrgDaemon {
      *  memory bridge (semantic when the local model is available, tokenized
      *  keyword otherwise). Failures return a message, never throw into the tool. */
     private recallOrgMemory;
+    /** knowledge_search implementation for org agents: the user's Second Brain
+     *  (this project's documents + the personal global brain), merged with the
+     *  same project-first ranking every other surface uses. Failures return a
+     *  message, never throw into the tool call. */
+    searchProjectKnowledge(query: string): Promise<{
+        text: string;
+        hits: number;
+    }>;
     /** Persist the run's outcome into cross-run org memory so org_recall (and
      *  future runs) can find it by meaning, not just recency. Best-effort. */
     private storeRunMemory;

package/packages/@monomind/cli/dist/src/orgrt/daemon.js

@@ -88,6 +88,11 @@ export class OrgDaemon {
                     bus.emit({ type: 'status', from: r, reason: 'org-recall', msg: `recall: ${q.slice(0, 80)}`, data: { hits: answer.hits } });
                     return answer.text;
                 },
+                searchKnowledge: async (r, q) => {
+                    const answer = await this.searchProjectKnowledge(q);
+                    bus.emit({ type: 'status', from: r, reason: 'knowledge-search', msg: `knowledge: ${q.slice(0, 80)}`, data: { hits: answer.hits } });
+                    return answer.text;
+                },
                 queryFn: this.opts.queryFn,
             };
             // Supervised session: transient crashes (provider blips, network) restart
@@ -502,6 +507,23 @@ export class OrgDaemon {
             return { text: `org memory unavailable (${err instanceof Error ? err.message : 'error'})`, hits: 0 };
         }
     }
+    /** knowledge_search implementation for org agents: the user's Second Brain
+     *  (this project's documents + the personal global brain), merged with the
+     *  same project-first ranking every other surface uses. Failures return a
+     *  message, never throw into the tool call. */
+    async searchProjectKnowledge(query) {
+        try {
+            const { searchKnowledge } = await import('../knowledge/document-pipeline.js');
+            const excerpts = await searchKnowledge(query, { rootDir: this.root, limit: 5, store: 'all' });
+            if (!excerpts.length)
+                return { text: 'No matching documents in the Second Brain for that query.', hits: 0 };
+            const text = excerpts.map((e, i) => `${i + 1}. [${e.filePath || 'unknown'}${e.scope === 'global' ? ' · global' : ''}] (${e.similarity.toFixed(2)})\n${e.text.slice(0, 800)}`).join('\n\n');
+            return { text, hits: excerpts.length };
+        }
+        catch (err) {
+            return { text: `knowledge search unavailable (${err instanceof Error ? err.message : 'error'})`, hits: 0 };
+        }
+    }
     /** Persist the run's outcome into cross-run org memory so org_recall (and
      *  future runs) can find it by meaning, not just recency. Best-effort. */
     async storeRunMemory(name, def, run, summary) {

package/packages/@monomind/cli/dist/src/orgrt/session.d.ts

@@ -17,6 +17,8 @@ export interface SessionOpts {
     onComplete?: (role: string, outcome: 'achieved' | 'partial' | 'failed', summary: string) => void;
     /** Search the org's accumulated cross-run memory (memory_namespace). */
     recall?: (role: string, query: string) => Promise<string>;
+    /** Search the user's Second Brain (project documents + personal global brain). */
+    searchKnowledge?: (role: string, query: string) => Promise<string>;
     def?: OrgDef;
     maxTurns?: number;
     queryFn?: typeof query;

package/packages/@monomind/cli/dist/src/orgrt/session.js

@@ -15,6 +15,7 @@ export function buildRolePrompt(role, def, roster) {
         `Roster: ${roster.join(', ')}. Address another org's agent as "<org-name>:<role-id>".`,
         `If you need a human decision, call ask_human with your question, then end your turn — you'll receive the human's answer as a new message when it arrives. Do not call ask_human for anything you can resolve yourself.`,
         `Before starting substantial work, call org_recall to check what previous runs already learned or delivered — do not redo finished work.`,
+        `The user's documents (notes, handbooks, specs) are searchable with knowledge_search — ground your work in them instead of guessing; results labeled [global] come from the user's personal cross-project brain.`,
         `When you receive a message, act on it, then org_send your result to the requester.`,
         isCoordinator
             ? `When the org's goal for this run is achieved (or clearly can't be), call org_complete exactly once with the outcome and a concise summary of what was done — it is recorded in the org's run history and briefed to the next run. Then end your turn.`
@@ -56,6 +57,10 @@ async function runOneSession(opts) {
         name: 'org',
         version: '1.0.0',
         tools: [
+            ...(opts.searchKnowledge ? [tool('knowledge_search', 'Semantic search over the user\'s Second Brain: this project\'s indexed documents plus their personal cross-project global brain. Use to ground work in the user\'s actual notes, handbooks, and documents.', { query: z.string() }, async (args) => {
+                    const text = await opts.searchKnowledge(role.id, args.query);
+                    return { content: [{ type: 'text', text }] };
+                })] : []),
             ...(opts.recall ? [tool('org_recall', 'Search this org\'s accumulated memory from previous runs (outcomes, decisions, learnings). Use before starting work that may already have been done.', { query: z.string() }, async (args) => {
                     const text = await opts.recall(role.id, args.query);
                     return { content: [{ type: 'text', text }] };

package/packages/@monomind/cli/dist/src/ui/dashboard.html

@@ -1917,6 +1917,11 @@ select.pb-cfg-inp { padding: 4px 7px; cursor: pointer; }
           <div class="filter-bar" style="margin-bottom:6px">
             <input class="filter-input" id="sb-search-input" type="text" placeholder="Ask your Second Brain — semantic search by meaning…"
               onkeydown="if(event.key==='Enter')secondBrainSearch()">
+            <select id="sb-search-scope" class="btn" title="Which brain to search" style="padding:3px 6px">
+              <option value="all" selected>project + global</option>
+              <option value="project">project only</option>
+              <option value="global">global only</option>
+            </select>
             <button class="btn" onclick="secondBrainSearch()" title="Semantic search (warm local model)">⌕ Search</button>
           </div>
           <div id="sb-search-results" style="display:none;margin-bottom:12px"></div>
@@ -13609,10 +13614,11 @@ async function secondBrainSearch() {
   box.style.display = 'block';
   box.innerHTML = '<div class="loading-txt">Searching…</div>';
   try {
+    const scopeSel = document.getElementById('sb-search-scope');
     const r = await fetch('/api/knowledge/search', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ query: q, limit: 5 }),
+      body: JSON.stringify({ query: q, limit: 5, scope: scopeSel ? scopeSel.value : 'all' }),
     });
     if (!r.ok) throw new Error('HTTP ' + r.status);
     const data = await r.json();
@@ -13625,8 +13631,11 @@ async function secondBrainSearch() {
       '<div style="font-size:10px;letter-spacing:0.07em;text-transform:uppercase;color:var(--text-xs);margin-bottom:6px">' +
         results.length + ' result(s) · ' + esc(data.method || '') + '</div>' +
       results.map(function (res) {
+        var srcTag = (res.tags || []).find(function (t) { return t.indexOf('src:') === 0; });
+        var label = srcTag ? srcTag.slice(4).split('/').slice(-2).join('/') : (res.key || '');
         return '<div style="border:1px solid var(--border);border-radius:8px;padding:8px 10px;margin-bottom:6px">' +
-          '<div style="font-size:10px;color:var(--text-lo);margin-bottom:3px">' + esc(res.key || '') +
+          '<div style="font-size:10px;color:var(--text-lo);margin-bottom:3px">' + esc(label) +
+            (res.global ? ' <span style="color:var(--accent-dim,#888);border:1px solid var(--border);border-radius:4px;padding:0 4px">global</span>' : '') +
             ' <span style="color:var(--accent)">' + (typeof res.score === 'number' ? res.score.toFixed(2) : '') + '</span></div>' +
           '<div style="font-size:12px;white-space:pre-wrap;max-height:120px;overflow:hidden">' + esc(String(res.content || '').slice(0, 600)) + '</div>' +
         '</div>';

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

@@ -1035,6 +1035,41 @@ export async function startServer({ port = 4242, projectDir, openBrowser = true
           .catch(() => { /* warm-up is best-effort */ });
       }, 3000);
       if (_warmTimer.unref) _warmTimer.unref();
+
+      // ── Second Brain live ingestion ──────────────────────────────────
+      // This server is the one long-lived local process AND holds the warm
+      // embedding model — so it watches for document changes and ingests
+      // in-process within seconds, instead of waiting for the next session
+      // start. Best-effort: recursive fs.watch is unsupported on some
+      // platforms/volumes; the session-start reindex remains the backstop.
+      try {
+        const _sbDocExts = new Set(['.md', '.txt', '.pdf', '.docx']);
+        const _sbSkip = /(^|\/)(node_modules|\.git|dist|\.monomind|\.claude|\.next|__pycache__|\.venv|vendor)(\/|$)/;
+        const _sbPending = new Map(); // file -> debounce timer
+        const _sbRoot = path.resolve(projectDir || process.cwd());
+        const _sbWatcher = fs.watch(_sbRoot, { recursive: true }, (_evt, rel) => {
+          try {
+            if (!rel) return;
+            const relStr = String(rel);
+            if (_sbSkip.test(relStr) || relStr.startsWith('.')) return;
+            if (!_sbDocExts.has(path.extname(relStr).toLowerCase())) return;
+            const full = path.join(_sbRoot, relStr);
+            clearTimeout(_sbPending.get(full));
+            _sbPending.set(full, setTimeout(async () => {
+              _sbPending.delete(full);
+              try {
+                if (!fs.existsSync(full)) return; // deleted — session-start reindex handles removal
+                const pipeline = await import('../knowledge/document-pipeline.js');
+                const r = await pipeline.ingestDocument(full, 'shared', _sbRoot);
+                if (r.chunksIndexed > 0 && !r.skipped) {
+                  console.log(`[knowledge] live-ingested ${path.basename(full)} (${r.chunksIndexed} chunks)`);
+                }
+              } catch (_) { /* single-file ingest failure never matters here */ }
+            }, 5000));
+          } catch (_) { /* watcher callback must never throw */ }
+        });
+        activeWatchers.push(_sbWatcher);
+      } catch (_) { /* recursive watch unavailable — session-start reindex covers it */ }
     }
   } catch (_) { /* non-fatal */ }
 
@@ -5950,11 +5985,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.5.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",