monomind 2.0.3 → 2.1.3

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),

package/packages/@monomind/cli/dist/src/memory/intelligence.js

@@ -10,9 +10,9 @@
  *
  * @module v1/cli/intelligence
  */
-import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync, unlinkSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { cosineSimilarity as sharedCosineSimilarity } from '../utils/cosine-similarity.js';
 import { readJsonFileSync, writeJsonFileAtomic } from '../utils/json-file.js';
 // ============================================================================
@@ -49,6 +49,75 @@ function ensureDataDir() {
 function getPatternsPath() {
     return join(getDataDir(), 'patterns.json');
 }
+// ── multi-process-safe patterns.json flush (P1-14) ─────────────────────────
+// patterns.json can be flushed by more than one process at once — e.g. the
+// long-lived MCP server process and a short-lived CJS hook subprocess each
+// load their own in-memory copy, then flush independently. Without a lock +
+// re-read-before-write, whichever flush lands last silently erases whatever
+// the other process added since its own load. flushToDisk() below re-reads
+// the current on-disk file immediately before writing and merges this
+// process's in-memory patterns in by `id` (keeping whichever record has the
+// newer `lastUsedAt`), guarded by a short advisory lock.
+function getPatternsLockPath() {
+    return `${getPatternsPath()}.lock`;
+}
+const PATTERNS_LOCK_STALE_MS = 10_000; // single JSON write — 10s is generous
+function isPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e?.code === 'EPERM';
+    }
+}
+/**
+ * Mirrors the stale-lock-breaking pattern in
+ * .claude/helpers/control-start.cjs (claimSpawnLock/releaseSpawnLock):
+ * wx-flag write to claim, break the lock if its holder is dead or the lock
+ * is older than the stale threshold, retry once, then give up and proceed
+ * unlocked (best-effort — a missed lock still merges via the re-read, it
+ * just narrows a tiny TOCTOU window further).
+ */
+function claimPatternsLock() {
+    const lockPath = getPatternsLockPath();
+    try {
+        mkdirSync(dirname(lockPath), { recursive: true });
+    }
+    catch {
+        /* ignore */
+    }
+    try {
+        writeFileSync(lockPath, String(process.pid), { flag: 'wx' });
+        return true;
+    }
+    catch {
+        try {
+            const stat = statSync(lockPath);
+            const holder = Number(readFileSync(lockPath, 'utf-8'));
+            if (Date.now() - stat.mtimeMs < PATTERNS_LOCK_STALE_MS && isPidAlive(holder))
+                return false;
+            unlinkSync(lockPath);
+            writeFileSync(lockPath, String(process.pid), { flag: 'wx' });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+function releasePatternsLock() {
+    const lockPath = getPatternsLockPath();
+    try {
+        if (Number(readFileSync(lockPath, 'utf-8')) === process.pid)
+            unlinkSync(lockPath);
+    }
+    catch {
+        /* ignore */
+    }
+}
 /**
  * Get the stats file path
  */
@@ -412,7 +481,34 @@ class LocalReasoningBank {
             return;
         try {
             ensureDataDir();
-            writeJsonFileAtomic(getPatternsPath(), this.patternList);
+            let acquired = claimPatternsLock();
+            if (!acquired)
+                acquired = claimPatternsLock(); // one retry — lock is short-lived
+            try {
+                // Re-read the current on-disk patterns and merge this process's
+                // in-memory changes in by id (newer lastUsedAt wins) instead of
+                // blindly overwriting the whole file with this.patternList — see
+                // the P1-14 comment above claimPatternsLock() for why.
+                const diskPatterns = readJsonFileSync(getPatternsPath(), []);
+                const merged = new Map();
+                if (Array.isArray(diskPatterns)) {
+                    for (const p of diskPatterns) {
+                        if (p && typeof p.id === 'string')
+                            merged.set(p.id, p);
+                    }
+                }
+                for (const p of this.patternList) {
+                    const existing = merged.get(p.id);
+                    if (!existing || (p.lastUsedAt ?? 0) >= (existing.lastUsedAt ?? 0)) {
+                        merged.set(p.id, p);
+                    }
+                }
+                writeJsonFileAtomic(getPatternsPath(), Array.from(merged.values()));
+            }
+            finally {
+                if (acquired)
+                    releasePatternsLock();
+            }
             this.dirty = false;
         }
         catch {

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

@@ -7,6 +7,8 @@
  * @module v1/cli/memory-bridge
  */
 export declare function safeParseEmbedding(raw: string | null | undefined): number[] | null;
+/** 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: {
     key: string;
     value: string;
@@ -113,6 +115,11 @@ export declare function bridgeLoadEmbeddingModel(dbPath?: string): Promise<{
     modelName: string;
     loadTime?: number;
 } | null>;
+export declare function bridgeGetBackendStats(dbPath?: string): Promise<{
+    totalEntries: number;
+    entriesByNamespace: Record<string, number>;
+    memoryUsage: number;
+} | null>;
 export declare function bridgeGetHNSWStatus(dbPath?: string): Promise<{
     built: boolean;
     size: number;

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

@@ -88,6 +88,10 @@ function getDbPath(customPath) {
         return resolved;
     return defaultDir;
 }
+/** Resolve the real on-disk LanceDB path for a given custom path (or the default). */
+export function bridgeGetDbPath(customPath) {
+    return getDbPath(customPath);
+}
 function getAutomemConfig() {
     const defaults = { dedupThreshold: 0.85, staleDays: 7 };
     try {
@@ -439,6 +443,22 @@ export async function bridgeLoadEmbeddingModel(dbPath) {
         return null;
     }
 }
+export async function bridgeGetBackendStats(dbPath) {
+    const backend = await getBackend(dbPath);
+    if (!backend)
+        return null;
+    try {
+        const stats = await backend.getStats();
+        return {
+            totalEntries: stats?.totalEntries ?? 0,
+            entriesByNamespace: stats?.entriesByNamespace ?? {},
+            memoryUsage: stats?.memoryUsage ?? 0,
+        };
+    }
+    catch {
+        return null;
+    }
+}
 // ===== HNSW (replaced by LanceDB ANN — stubs kept for API compat) =====
 export async function bridgeGetHNSWStatus(dbPath) {
     const backend = await getBackend(dbPath);

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

@@ -94,6 +94,12 @@ export declare class SONAOptimizer {
     private failedRoutings;
     private lastUpdate;
     private persistencePath;
+    /** Set when in-memory state diverges from disk — triggers next debounced write */
+    private dirty;
+    /** NodeJS timeout handle for debounced disk flush */
+    private saveTimer;
+    /** Debounce window for disk writes (ms) — batches rapid trajectory bursts */
+    private static readonly SAVE_DEBOUNCE_MS;
     constructor(options?: {
         persistencePath?: string;
     });
@@ -182,6 +188,12 @@ export declare class SONAOptimizer {
      * Load patterns from disk
      */
     private loadFromDisk;
+    /**
+     * Schedule a debounced disk flush.
+     * Multiple calls within SAVE_DEBOUNCE_MS coalesce into a single write,
+     * preventing blocking I/O on every trajectory event during swarm bursts.
+     */
+    private scheduleSave;
     /**
      * Save patterns to disk
      */

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

@@ -0,0 +1,26 @@
+export interface BrokerEntry {
+    url: string;
+    pid: number;
+    updatedAt: number;
+}
+export declare function defaultRegistryDir(): string;
+/** Publish that this process hosts org `name`, reachable via `url`. Call again periodically (heartbeat) — see BrokerLease.
+ *  Writes via tmp+rename (same-directory rename is atomic on POSIX/NTFS) so a concurrent lookupOrg() never observes a
+ *  partially-written entry — this file is rewritten every heartbeat (default 20s) while other processes may read it. */
+export declare function registerOrg(name: string, url: string, dir?: string): void;
+/** Remove this process's registration for `name` (best effort). */
+export declare function unregisterOrg(name: string, dir?: string): void;
+/** Find which process (if any) currently hosts org `name`. Null if never registered or the registration is stale (owner crashed without cleanup). */
+export declare function lookupOrg(name: string, dir?: string, staleMs?: number): BrokerEntry | null;
+/** Keeps a broker registration alive with periodic heartbeats until stop() is called. */
+export declare class BrokerLease {
+    private name;
+    private url;
+    private dir;
+    private intervalMs;
+    private timer;
+    constructor(name: string, url: string, dir?: string, intervalMs?: number);
+    start(): void;
+    stop(): void;
+}
+//# sourceMappingURL=broker.d.ts.map

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

@@ -0,0 +1,73 @@
+// packages/@monomind/cli/src/orgrt/broker.ts
+// monolean: file-based local broker for cross-process org discovery (different
+// `monomind org` processes / project directories, same machine). Upgrade path:
+// a real network registry when cross-machine discovery is needed.
+import { mkdirSync, writeFileSync, readFileSync, unlinkSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+const SAFE_NAME = /^[a-z0-9][a-z0-9_-]*$/i;
+const DEFAULT_STALE_MS = 90_000;
+export function defaultRegistryDir() {
+    return process.env.MONOMIND_ORGRT_BROKER_DIR || join(homedir(), '.monomind', 'orgrt-broker');
+}
+function entryPath(name, dir) {
+    if (!SAFE_NAME.test(name))
+        throw new Error(`invalid org name for broker registry: ${name}`);
+    return join(dir, `${name}.json`);
+}
+/** Publish that this process hosts org `name`, reachable via `url`. Call again periodically (heartbeat) — see BrokerLease.
+ *  Writes via tmp+rename (same-directory rename is atomic on POSIX/NTFS) so a concurrent lookupOrg() never observes a
+ *  partially-written entry — this file is rewritten every heartbeat (default 20s) while other processes may read it. */
+export function registerOrg(name, url, dir = defaultRegistryDir()) {
+    mkdirSync(dir, { recursive: true });
+    const entry = { url, pid: process.pid, updatedAt: Date.now() };
+    const dest = entryPath(name, dir);
+    const tmp = `${dest}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(entry));
+    renameSync(tmp, dest);
+}
+/** Remove this process's registration for `name` (best effort). */
+export function unregisterOrg(name, dir = defaultRegistryDir()) {
+    try {
+        unlinkSync(entryPath(name, dir));
+    }
+    catch { /* already gone */ }
+}
+/** Find which process (if any) currently hosts org `name`. Null if never registered or the registration is stale (owner crashed without cleanup). */
+export function lookupOrg(name, dir = defaultRegistryDir(), staleMs = DEFAULT_STALE_MS) {
+    try {
+        const entry = JSON.parse(readFileSync(entryPath(name, dir), 'utf8'));
+        if (Date.now() - entry.updatedAt >= staleMs)
+            return null;
+        return entry;
+    }
+    catch {
+        return null;
+    }
+}
+/** Keeps a broker registration alive with periodic heartbeats until stop() is called. */
+export class BrokerLease {
+    name;
+    url;
+    dir;
+    intervalMs;
+    timer = null;
+    constructor(name, url, dir = defaultRegistryDir(), intervalMs = 20_000) {
+        this.name = name;
+        this.url = url;
+        this.dir = dir;
+        this.intervalMs = intervalMs;
+    }
+    start() {
+        registerOrg(this.name, this.url, this.dir);
+        this.timer = setInterval(() => registerOrg(this.name, this.url, this.dir), this.intervalMs);
+        this.timer.unref?.();
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+        unregisterOrg(this.name, this.dir);
+    }
+}
+//# sourceMappingURL=broker.js.map

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

@@ -15,7 +15,11 @@ export declare class OrgBus {
     constructor(org: string, run: string, dir: string);
     subscribe(fn: Listener): () => void;
     emit(partial: Omit<BusEvent, 'id' | 'ts' | 'org' | 'run'>): BusEvent;
-    /** await all queued disk writes (tests, shutdown) */
+    /** Await all queued disk writes (tests, shutdown). Listeners registered via subscribe() run
+     *  synchronously inside emit() — flush() has no visibility into any async work they schedule
+     *  off of that (e.g. the forwarder's HTTP POSTs). A caller that needs an async subscriber's
+     *  work to have settled too must await that subscriber's own completion signal separately
+     *  (see daemon.ts stopOrg(), which awaits forwarder.settle() alongside bus.flush()). */
     flush(): Promise<void>;
     static readHistory(dir: string): BusEvent[];
 }

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

@@ -45,7 +45,11 @@ export class OrgBus {
         }
         return e;
     }
-    /** await all queued disk writes (tests, shutdown) */
+    /** Await all queued disk writes (tests, shutdown). Listeners registered via subscribe() run
+     *  synchronously inside emit() — flush() has no visibility into any async work they schedule
+     *  off of that (e.g. the forwarder's HTTP POSTs). A caller that needs an async subscriber's
+     *  work to have settled too must await that subscriber's own completion signal separately
+     *  (see daemon.ts stopOrg(), which awaits forwarder.settle() alongside bus.flush()). */
     flush() { return this.pending; }
     static readHistory(dir) {
         const f = join(dir, 'bus.jsonl');

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

@@ -7,6 +7,9 @@ interface AgentRuntime {
     mailbox: Mailbox;
     policy: PolicyEngine;
     done: Promise<void>;
+    /** 'running' until the session promise settles; 'crashed' if it rejected (see error). */
+    status: 'running' | 'ended' | 'crashed';
+    error?: string;
 }
 export interface RunningOrg {
     def: OrgDef;
@@ -19,20 +22,63 @@ export interface DaemonOpts {
     queryFn?: typeof query;
     forward?: boolean;
     controlJson?: string;
+    /** Enables cross-process inter-org routing: on a local delivery miss, ask the
+     *  machine-local broker whether another `monomind org` process (e.g. a
+     *  different project directory) hosts the target org, and deliver over HTTP
+     *  if so. Off by default — tests and single-process runs don't need it. */
+    crossProcess?: boolean;
+    /** Base URL at which OTHER processes can reach this daemon's inbox (see
+     *  server.ts POST /api/xdeliver). Set this to make orgs hosted here
+     *  discoverable; omit for outbound-only cross-process delivery. */
+    inboxUrl?: string;
+    /** Override the broker's file registry directory (tests only). */
+    brokerDir?: string;
+    /** Override how long stopOrg() waits for agent sessions before proceeding anyway (tests only; default 15000ms). */
+    stopWaitMs?: number;
 }
 export declare class OrgDaemon {
     private root;
     private opts;
     private orgs;
+    private waking;
     private globalSubscribers;
+    private leases;
+    private forwarders;
     constructor(root: string, opts?: DaemonOpts);
+    /** Publish this daemon's inbox so orgs started AFTER this call register with the broker. */
+    setInboxUrl(url: string): void;
     /** subscribe to events from ALL running orgs (dashboard server uses this) */
     subscribe(fn: (e: BusEvent) => void): () => void;
     listOrgs(): RunningOrg[];
     getOrg(name: string): RunningOrg | undefined;
     startOrg(name: string, taskOverride?: string): Promise<RunningOrg>;
+    /**
+     * Resolves an org_send `to` address ("role" for same-org, "org:role" for
+     * cross-org) into its parts. Centralizes the one addressing rule that
+     * matters (an "own-org:role" self-prefix is intra-org, not cross-org) so
+     * deliver()/deliverRemote() don't each re-derive it — the qualified `to`
+     * string returned is always the canonical display form for that address.
+     */
+    private resolveAddress;
     /** Route a message. to = "role" (same org) or "org:role" (cross-org). Returns a receipt string. */
     deliver(fromOrg: string, fromRole: string, to: string, subject: string, body: string): Promise<string>;
+    /** Cross-process leg of deliver(): ask the machine-local broker who hosts targetOrgName, then POST over HTTP.
+     *  `to` here is always the fully-qualified "org:role" display form (resolveAddress already normalized it). */
+    private deliverRemote;
+    /** Inbound handler for cross-process delivery — called by the server's POST /api/xdeliver route
+     *  when ANOTHER process's deliverRemote() reaches this daemon. Pushes straight into the target
+     *  agent's mailbox; the agent picks it up on its own next turn (see Mailbox — never interrupts). */
+    receiveRemote(toOrg: string, toRole: string, fromQualified: string, subject: string, body: string): {
+        ok: true;
+        receipt: string;
+    } | {
+        ok: false;
+        error: string;
+    };
+    private hasOrgDef;
+    /** Start an offline org in the background so queued messages get drained.
+     *  Fire-and-forget — errors are logged but don't propagate to the sender. */
+    private autoWake;
     stopOrg(name: string): Promise<void>;
     stopAll(): Promise<void>;
     private persistState;