monomind 2.5.1 → 2.5.3

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

@@ -0,0 +1,450 @@
+/**
+ * Memory Knowledge Graph — entities, relations, and rules distilled from
+ * agent sessions and org runs (cognee-concept port, Phase 2 of
+ * docs/mastermind/2026-07-19-cognee-port-plan.md).
+ *
+ * Storage rides store A (memory-bridge) rather than a dedicated SQLite DB:
+ * nodes live in namespace `kg:nodes`, edges in `kg:edges`, distilled rules
+ * additionally in `rules` (so existing knowledge/injection surfaces find them).
+ * That buys embeddings, upsert, sql.js fallback, and the Phase 1
+ * feedback/frequency weighting for free — KG node ranking improves with use
+ * automatically.
+ *
+ * Identity is deterministic and NAME-ONLY (cognee's Entity.identity_fields):
+ * the entry KEY is `n:<normalized-name>`, so the same entity extracted from
+ * any session merges idempotently via upsert regardless of assigned type.
+ * Every write carries `origin_refs` so a bad ingest can be rolled back per
+ * run/session.
+ *
+ * // monolean: graph traversal is in-process over a full kg:edges list —
+ * // fine to ~10k edges; upgrade path is a real SQLite edges table with
+ * // indexed src/dst columns if orgs outgrow that.
+ *
+ * @module v1/cli/memory/memory-kg
+ */
+import { bridgeStoreEntry, bridgeSearchEntries, bridgeListEntries, bridgeGetEntry, bridgeDeleteEntry, } from './memory-bridge.js';
+export const KG_NODES_NS = 'kg:nodes';
+export const KG_EDGES_NS = 'kg:edges';
+export const RULES_NS = 'rules';
+const MAX_NAME_LEN = 200;
+const MAX_DESC_LEN = 2000;
+const MAX_LIST = 10_000;
+/** cognee DataPoint normalization: lowercase, spaces→_, strip apostrophes. */
+export function normalizeName(name) {
+    return String(name).trim().toLowerCase().replace(/['’]/g, '').replace(/\s+/g, '_').slice(0, MAX_NAME_LEN);
+}
+/** Identity is NAME-ONLY (cognee's Entity.identity_fields = ["name"]) — type
+ *  lives in metadata. Including type in the key forked the same entity when
+ *  the LLM said "Module" and the heuristic said "entity". */
+export function nodeKey(_type, name) {
+    return `n:${normalizeName(name)}`;
+}
+function edgeKey(srcKey, relation, dstKey) {
+    return `e:${srcKey}|${normalizeName(relation)}|${dstKey}`;
+}
+// ── Ingest ──────────────────────────────────────────────────────────
+/** Idempotently merge extracted nodes/edges into the KG. Same-name entities
+ *  collapse onto one node (deterministic key + upsert); origin_refs accumulate
+ *  so rollback can undo a single run's contribution. */
+export async function kgIngest(options) {
+    const { originRef, dbPath } = options;
+    let nodesAdded = 0, nodesMerged = 0, edgesAdded = 0, edgesMerged = 0;
+    try {
+        const keyByName = new Map();
+        for (const n of (options.nodes ?? []).slice(0, 500)) {
+            if (!n?.name?.trim())
+                continue;
+            const type = n.type?.trim() || 'entity';
+            const key = nodeKey(type, n.name);
+            keyByName.set(normalizeName(n.name), key);
+            const desc = (n.description ?? '').slice(0, MAX_DESC_LEN);
+            const existing = await bridgeGetEntry({ key, namespace: KG_NODES_NS, dbPath });
+            if (existing?.found && existing.entry) {
+                const md = existing.entry.metadata;
+                const origins = Array.isArray(md.origin_refs) ? md.origin_refs : [];
+                if (!origins.includes(originRef))
+                    origins.push(originRef);
+                // Prefer the richer description; never let a terse re-extraction erase detail.
+                const prevDesc = typeof md.description === 'string' ? md.description : '';
+                const bestDesc = desc.length > prevDesc.length ? desc : prevDesc;
+                // Keep the most specific type: a generic heuristic 'entity' never
+                // overwrites an LLM-assigned type.
+                const prevType = typeof md.type === 'string' ? md.type : 'entity';
+                const bestType = prevType.toLowerCase() !== 'entity' ? prevType : type;
+                await bridgeStoreEntry({
+                    key,
+                    value: `${n.name} — ${bestDesc || bestType}`,
+                    namespace: KG_NODES_NS,
+                    dbPath,
+                    upsert: true,
+                    tags: ['kg', normalizeName(bestType), ...(n.nodeSet ? [normalizeName(n.nodeSet)] : [])],
+                    metadata: {
+                        ...md,
+                        kg: 'node', type: bestType, name: n.name, description: bestDesc,
+                        node_set: n.nodeSet ?? md.node_set ?? null,
+                        origin_refs: origins.slice(-100),
+                        version: (typeof md.version === 'number' ? md.version : 1) + 1,
+                        valid_from: md.valid_from ?? Date.now(),
+                        valid_to: null,
+                    },
+                });
+                nodesMerged++;
+            }
+            else {
+                await bridgeStoreEntry({
+                    key,
+                    value: `${n.name} — ${desc || type}`,
+                    namespace: KG_NODES_NS,
+                    dbPath,
+                    upsert: true,
+                    tags: ['kg', normalizeName(type), ...(n.nodeSet ? [normalizeName(n.nodeSet)] : [])],
+                    metadata: {
+                        kg: 'node', type, name: n.name, description: desc,
+                        node_set: n.nodeSet ?? null,
+                        origin_refs: [originRef],
+                        version: 1,
+                        valid_from: Date.now(),
+                        valid_to: null,
+                    },
+                });
+                nodesAdded++;
+            }
+        }
+        for (const e of (options.edges ?? []).slice(0, 1000)) {
+            if (!e?.source?.trim() || !e?.target?.trim() || !e?.relation?.trim())
+                continue;
+            const srcKey = keyByName.get(normalizeName(e.source)) ?? nodeKey(e.sourceType ?? 'entity', e.source);
+            const dstKey = keyByName.get(normalizeName(e.target)) ?? nodeKey(e.targetType ?? 'entity', e.target);
+            const key = edgeKey(srcKey, e.relation, dstKey);
+            const desc = (e.description ?? '').slice(0, MAX_DESC_LEN);
+            const existing = await bridgeGetEntry({ key, namespace: KG_EDGES_NS, dbPath });
+            if (existing?.found && existing.entry) {
+                const md = existing.entry.metadata;
+                const origins = Array.isArray(md.origin_refs) ? md.origin_refs : [];
+                if (!origins.includes(originRef))
+                    origins.push(originRef);
+                await bridgeStoreEntry({
+                    key,
+                    value: desc || `${e.source} ${e.relation} ${e.target}`,
+                    namespace: KG_EDGES_NS,
+                    dbPath,
+                    upsert: true,
+                    generateEmbeddingFlag: false,
+                    tags: ['kg', normalizeName(e.relation)],
+                    metadata: { ...md, origin_refs: origins.slice(-100) },
+                });
+                edgesMerged++;
+            }
+            else {
+                await bridgeStoreEntry({
+                    key,
+                    value: desc || `${e.source} ${e.relation} ${e.target}`,
+                    namespace: KG_EDGES_NS,
+                    dbPath,
+                    upsert: true,
+                    generateEmbeddingFlag: false,
+                    tags: ['kg', normalizeName(e.relation)],
+                    metadata: {
+                        kg: 'edge', src: srcKey, dst: dstKey,
+                        relation: normalizeName(e.relation),
+                        source_name: e.source, target_name: e.target,
+                        description: desc,
+                        origin_refs: [originRef],
+                        valid_from: Date.now(),
+                        valid_to: null,
+                    },
+                });
+                edgesAdded++;
+            }
+        }
+        return { success: true, nodesAdded, nodesMerged, edgesAdded, edgesMerged };
+    }
+    catch (err) {
+        return {
+            success: false, nodesAdded, nodesMerged, edgesAdded, edgesMerged,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/** Stage-2 of cognee's curator/writer distillation: the CALLER (an LLM agent)
+ *  proposes candidate rules; this accepts each unless a semantically
+ *  near-identical rule exists (embedding dedup — deterministic keys can't
+ *  collapse paraphrases). Accepted rules are stored both as KG nodes
+ *  (node_set=rules) and as plain `rules`-namespace entries so the existing
+ *  injection/search surfaces pick them up with zero new plumbing. */
+export async function kgIngestRules(options) {
+    const verdicts = [];
+    const threshold = options.dedupThreshold ?? 0.78;
+    let accepted = 0;
+    try {
+        for (const r of (options.rules ?? []).slice(0, 50)) {
+            const rule = r?.rule?.trim();
+            if (!rule || rule.length < 8) {
+                verdicts.push({ rule: r?.rule ?? '', verdict: 'invalid' });
+                continue;
+            }
+            const similar = await bridgeSearchEntries({
+                query: rule, namespace: RULES_NS, limit: 1, threshold, dbPath: options.dbPath,
+            });
+            const top = similar?.results?.[0];
+            // Dedup on the RAW cosine (from provenance), not the blended rank score —
+            // the Phase 1 feedback blend shifts scores and would corrupt the gate.
+            const rawScore = top?.provenance?.startsWith('semantic:')
+                ? parseFloat(top.provenance.slice('semantic:'.length)) : top?.score ?? 0;
+            if (top && rawScore >= threshold) {
+                verdicts.push({ rule, verdict: 'already_known', similarTo: top.key });
+                continue;
+            }
+            const key = `rule:${normalizeName(rule).slice(0, 120)}`;
+            await bridgeStoreEntry({
+                key, value: rule + (r.context ? `\n(context: ${r.context.slice(0, 500)})` : ''),
+                namespace: RULES_NS, dbPath: options.dbPath, upsert: true,
+                tags: ['rule'],
+                metadata: { origin_refs: [options.originRef], derived_from: options.originRef },
+            });
+            await kgIngest({
+                nodes: [{ name: rule.slice(0, MAX_NAME_LEN), type: 'Rule', description: rule, nodeSet: 'rules' }],
+                originRef: options.originRef,
+                dbPath: options.dbPath,
+            });
+            verdicts.push({ rule, verdict: 'accepted' });
+            accepted++;
+        }
+        return { success: true, verdicts, accepted };
+    }
+    catch (err) {
+        return { success: false, verdicts, accepted, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** List stored rules (for injection or review). */
+export async function kgListRules(options) {
+    const res = await bridgeListEntries({ namespace: RULES_NS, limit: options?.limit ?? 50, dbPath: options?.dbPath });
+    return (res?.entries ?? []).map(e => ({ rule: e.content, key: e.key }));
+}
+/** Vector-seed → neighborhood → triplet ranking (cognee's brute-force triplet
+ *  search, scaled down). Seed scores already carry the Phase 1 feedback blend. */
+export async function kgSearch(options) {
+    try {
+        const limit = options.limit ?? 8;
+        const seedsRes = await bridgeSearchEntries({
+            query: options.query, namespace: KG_NODES_NS, limit: 15, threshold: 0.25, dbPath: options.dbPath,
+        });
+        let seedResults = seedsRes?.results ?? [];
+        if (options.nodeSet) {
+            const ns = normalizeName(options.nodeSet);
+            seedResults = seedResults.filter(r => (r.tags ?? []).includes(ns));
+        }
+        if (!seedResults.length)
+            return { success: true, context: '', triplets: [], seeds: [] };
+        const seedScore = new Map();
+        for (const s of seedResults)
+            seedScore.set(s.key, s.score);
+        // Full edge scan (see monolean note in module header).
+        const edgesRes = await bridgeListEntries({ namespace: KG_EDGES_NS, limit: MAX_LIST, dbPath: options.dbPath });
+        const edges = (edgesRes?.entries ?? []).filter(e => {
+            const md = e.metadata;
+            return md?.kg === 'edge' && md.valid_to == null;
+        });
+        const triplets = edges
+            .map(e => {
+            const md = e.metadata;
+            const src = String(md.src ?? '');
+            const dst = String(md.dst ?? '');
+            const sSrc = seedScore.get(src) ?? 0;
+            const sDst = seedScore.get(dst) ?? 0;
+            if (sSrc === 0 && sDst === 0)
+                return null;
+            // Both endpoints seeded beats one; the unseeded endpoint contributes a
+            // neutral 0.35 so bridging edges from a strong seed still surface.
+            const score = (Math.max(sSrc, 0.35) + Math.max(sDst, 0.35)) / 2 + (sSrc > 0 && sDst > 0 ? 0.1 : 0);
+            return {
+                source: String(md.source_name ?? src),
+                relation: String(md.relation ?? 'related_to'),
+                target: String(md.target_name ?? dst),
+                fact: e.content,
+                score,
+            };
+        })
+            .filter((t) => !!t)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit);
+        const seeds = seedResults.slice(0, limit).map(s => {
+            // metadata is not in search results; parse from rendered content "name — description"
+            const dash = s.content.indexOf(' — ');
+            return {
+                name: dash > 0 ? s.content.slice(0, dash) : s.key,
+                type: s.key.split(':')[1] ?? 'entity',
+                description: dash > 0 ? s.content.slice(dash + 3) : s.content,
+                score: s.score,
+                id: s.id,
+            };
+        });
+        const context = [
+            ...triplets.map(t => `${t.source} —${t.relation}→ ${t.target}${t.fact && t.fact !== `${t.source} ${t.relation} ${t.target}` ? ` (${t.fact})` : ''}`),
+            ...(triplets.length ? [] : seeds.map(s => `${s.name}: ${s.description}`)),
+        ].join('\n');
+        return { success: true, context, triplets, seeds };
+    }
+    catch (err) {
+        return { success: false, context: '', triplets: [], seeds: [], error: err instanceof Error ? err.message : String(err) };
+    }
+}
+// ── Glossary (anti-duplicate-entity injection for extraction prompts) ──
+export async function kgGlossary(options) {
+    const res = await bridgeListEntries({ namespace: KG_NODES_NS, limit: MAX_LIST, dbPath: options?.dbPath });
+    const nodes = (res?.entries ?? [])
+        // Glossary is for ENTITY name reuse — rule prose and extraction-source
+        // Session nodes would drown it.
+        .filter(e => {
+        const md = e.metadata;
+        const t = String(md?.type ?? '').toLowerCase();
+        return md?.node_set !== 'rules' && t !== 'rule' && t !== 'session';
+    })
+        .map(e => {
+        const md = e.metadata;
+        const fw = typeof md.feedback_weight === 'number' ? md.feedback_weight : 0.5;
+        const freq = typeof md.frequency_weight === 'number' ? md.frequency_weight : 0;
+        const version = typeof md.version === 'number' ? md.version : 1;
+        return { name: String(md.name ?? e.key), rank: version + freq + fw };
+    })
+        .sort((a, b) => b.rank - a.rank);
+    const seen = new Set();
+    const out = [];
+    for (const n of nodes) {
+        const norm = normalizeName(n.name);
+        if (seen.has(norm))
+            continue;
+        seen.add(norm);
+        out.push(n.name);
+        if (out.length >= (options?.limit ?? 40))
+            break;
+    }
+    return out;
+}
+// ── Rollback (per-origin bad-ingest recovery) ───────────────────────
+/** Delete every node/edge/rule whose ONLY origin is `originRef`. Elements with
+ *  other origins survive (shared knowledge isn't destroyed by one bad run);
+ *  their origin lists retain the ref — acceptable residue.
+ *  // monolean: no origin-list rewrite — needs an update-by-id bridge API */
+export async function kgRollback(options) {
+    let deleted = 0, retained = 0;
+    try {
+        for (const ns of [KG_NODES_NS, KG_EDGES_NS, RULES_NS]) {
+            const res = await bridgeListEntries({ namespace: ns, limit: MAX_LIST, dbPath: options.dbPath });
+            for (const e of res?.entries ?? []) {
+                const origins = e.metadata?.origin_refs;
+                if (!Array.isArray(origins) || !origins.includes(options.originRef))
+                    continue;
+                if (origins.length <= 1) {
+                    const del = await bridgeDeleteEntry({ id: e.id, namespace: ns, dbPath: options.dbPath });
+                    if (del?.deleted)
+                        deleted++;
+                }
+                else {
+                    retained++;
+                }
+            }
+        }
+        return { success: true, deleted, retained };
+    }
+    catch (err) {
+        return { success: false, deleted, retained, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** Entities whose descriptions are stale relative to their connectivity —
+ *  the LLM half runs in the LIVE agent: it rewrites each candidate's
+ *  description from the neighborhood facts and resubmits via memory_kg_ingest
+ *  (longer descriptions win on merge). No LLM here (fully local constraint). */
+export async function kgConsolidateCandidates(options) {
+    const minEdges = options?.minEdges ?? 3;
+    const [nodesRes, edgesRes] = await Promise.all([
+        bridgeListEntries({ namespace: KG_NODES_NS, limit: MAX_LIST, dbPath: options?.dbPath }),
+        bridgeListEntries({ namespace: KG_EDGES_NS, limit: MAX_LIST, dbPath: options?.dbPath }),
+    ]);
+    const edgesByNode = new Map();
+    for (const e of edgesRes?.entries ?? []) {
+        const md = e.metadata;
+        for (const end of [String(md.src ?? ''), String(md.dst ?? '')]) {
+            if (!end)
+                continue;
+            const list = edgesByNode.get(end) ?? [];
+            list.push(e.content);
+            edgesByNode.set(end, list);
+        }
+    }
+    return (nodesRes?.entries ?? [])
+        .map(n => {
+        const md = n.metadata;
+        const facts = edgesByNode.get(n.key) ?? [];
+        return {
+            name: String(md.name ?? n.key),
+            type: String(md.type ?? 'entity'),
+            description: String(md.description ?? ''),
+            edgeCount: facts.length,
+            neighborhood: facts.slice(0, 12),
+        };
+    })
+        // Cap the growth target at MAX_DESC_LEN — a very-high-degree node whose
+        // description is already at the cap can never "grow out" of candidacy and
+        // would otherwise permanently occupy a slot.
+        .filter(c => c.edgeCount >= minEdges && c.description.length < Math.min(40 * c.edgeCount, MAX_DESC_LEN))
+        .sort((a, b) => b.edgeCount - a.edgeCount)
+        .slice(0, options?.limit ?? 10);
+}
+// ── Stats ───────────────────────────────────────────────────────────
+export async function kgStats(options) {
+    const [n, e, r] = await Promise.all([
+        bridgeListEntries({ namespace: KG_NODES_NS, limit: MAX_LIST, dbPath: options?.dbPath }),
+        bridgeListEntries({ namespace: KG_EDGES_NS, limit: MAX_LIST, dbPath: options?.dbPath }),
+        bridgeListEntries({ namespace: RULES_NS, limit: MAX_LIST, dbPath: options?.dbPath }),
+    ]);
+    return { nodes: n?.total ?? 0, edges: e?.total ?? 0, rules: r?.total ?? 0 };
+}
+// ── Heuristic extraction (LLM-less fallback) ────────────────────────
+/** Regex extraction for when no LLM is in the loop (memory-palace lineage):
+ *  proper-noun phrases and `code identifiers` become entities, sentence
+ *  co-occurrence becomes relates_to edges. Lower-trust by design — real
+ *  entity/relation quality comes from the LLM path (memory_kg_ingest called
+ *  by the live agent, or the org coordinator's org_learn tool). */
+export function heuristicExtract(text, opts) {
+    const nodes = new Map();
+    const edges = [];
+    const src = String(text || '').slice(0, 50_000);
+    const sentences = src.split(/(?<=[.!?])\s+|\n+/).slice(0, 400);
+    const STOPWORDS = new Set(['The', 'This', 'That', 'These', 'Those', 'It', 'A', 'An', 'If', 'When', 'While', 'But', 'And', 'Or', 'For', 'Then', 'Also', 'Not', 'No', 'Yes', 'I', 'We', 'You', 'They', 'He', 'She', 'Run', 'Outcome', 'Assets', 'Goal', 'Org',
+        'January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December',
+        'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday']);
+    for (const sentence of sentences) {
+        const found = [];
+        // Proper-noun phrases: consecutive Capitalized words (2-40 chars each).
+        for (const m of sentence.matchAll(/\b([A-Z][a-zA-Z0-9_-]{1,40}(?:\s+[A-Z][a-zA-Z0-9_-]{1,40}){0,3})\b/g)) {
+            const phrase = m[1];
+            if (STOPWORDS.has(phrase))
+                continue;
+            found.push(phrase);
+        }
+        // Code identifiers in backticks or dotted/slashed paths.
+        for (const m of sentence.matchAll(/`([^`\n]{2,80})`/g))
+            found.push(m[1]);
+        const uniq = [...new Set(found)].slice(0, 8);
+        for (const name of uniq) {
+            if (!nodes.has(normalizeName(name))) {
+                nodes.set(normalizeName(name), { name, type: /[./`(]/.test(name) ? 'CodeElement' : 'Entity', description: sentence.trim().slice(0, 300) });
+            }
+        }
+        // Co-occurrence edges within a sentence (first mention chains to the rest).
+        for (let i = 1; i < uniq.length && i < 4; i++) {
+            edges.push({ source: uniq[0], target: uniq[i], relation: 'relates_to', description: sentence.trim().slice(0, 300) });
+        }
+    }
+    if (opts?.sourceName) {
+        const srcNode = { name: opts.sourceName, type: 'Session', description: 'extraction source' };
+        nodes.set(normalizeName(opts.sourceName), srcNode);
+        for (const n of [...nodes.values()].slice(0, 30)) {
+            if (n.name !== opts.sourceName)
+                edges.push({ source: n.name, target: opts.sourceName, relation: 'mentioned_in', sourceType: n.type, targetType: 'Session' });
+        }
+    }
+    return { nodes: [...nodes.values()].slice(0, 100), edges: edges.slice(0, 200) };
+}
+//# sourceMappingURL=memory-kg.js.map

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

@@ -0,0 +1,44 @@
+/**
+ * Query Router + RRF fusion — Phase 4 of the cognee port plan.
+ *
+ * routeQuery: cognee's rule-based (non-LLM) recall router scaled to our four
+ * retrieval surfaces — document chunks, knowledge-graph triplets, distilled
+ * rules, and org/pattern memories. Weighted regex rules with a negation
+ * window, a confidence gate (winner must be ≥2× runner-up), and an in-memory
+ * misroute counter for debuggability.
+ *
+ * rrfFuse: Reciprocal Rank Fusion across result lists whose raw scores are
+ * not comparable (cosine vs blended vs keyword) — `Σ 1/(rrf_k + rank + 1)`
+ * with cognee's adaptive rrf_k = max(30, min(60, 20 + 2·top_k)).
+ *
+ * @module v1/cli/memory/query-router
+ */
+export type RetrievalSurface = 'chunks' | 'kg' | 'rules' | 'memory';
+export interface RouteDecision {
+    /** Surfaces to hit, best first. Always non-empty ('chunks' is the fallback). */
+    surfaces: RetrievalSurface[];
+    /** Winner's score ≥ 2× runner-up (cognee's confidence gate). Low-confidence
+     *  routes should hit ALL surfaces and fuse. */
+    confident: boolean;
+    scores: Record<RetrievalSurface, number>;
+}
+export declare function routeQuery(query: string): RouteDecision;
+/** Call when a route proved wrong (caller retried another surface) — counts
+ *  feed debugging, mirroring cognee's record_override telemetry. */
+export declare function recordRouteOverride(from: RetrievalSurface, to: RetrievalSurface): void;
+/** In-memory counts from this process only; pass merged=true to include the
+ *  persisted cross-process counts from .monomind/metrics/route-overrides.json. */
+export declare function getRouteOverrides(merged?: boolean): Record<string, number>;
+export interface FusableResult {
+    /** Stable identity across lists (id or key). */
+    id: string;
+    /** Importance factor input in [0,1]; defaults 0.5. */
+    importance?: number;
+    [extra: string]: unknown;
+}
+/** Fuse ranked lists via RRF × importance factor (cognee hybrid/ranking.py).
+ *  Input lists must each be ranked best-first; raw scores are ignored. */
+export declare function rrfFuse<T extends FusableResult>(lists: T[][], topK: number): (T & {
+    rrf: number;
+})[];
+//# sourceMappingURL=query-router.d.ts.map

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

@@ -0,0 +1,113 @@
+/**
+ * Query Router + RRF fusion — Phase 4 of the cognee port plan.
+ *
+ * routeQuery: cognee's rule-based (non-LLM) recall router scaled to our four
+ * retrieval surfaces — document chunks, knowledge-graph triplets, distilled
+ * rules, and org/pattern memories. Weighted regex rules with a negation
+ * window, a confidence gate (winner must be ≥2× runner-up), and an in-memory
+ * misroute counter for debuggability.
+ *
+ * rrfFuse: Reciprocal Rank Fusion across result lists whose raw scores are
+ * not comparable (cosine vs blended vs keyword) — `Σ 1/(rrf_k + rank + 1)`
+ * with cognee's adaptive rrf_k = max(30, min(60, 20 + 2·top_k)).
+ *
+ * @module v1/cli/memory/query-router
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+// Order matters only for tie display; scoring is additive per surface.
+const ROUTE_RULES = [
+    // Rules: "how should I", conventions, policies, dos and don'ts.
+    { surface: 'rules', pattern: /\b(rules?|conventions?|policy|policies|guidelines?|best practices?|should (i|we|you)|always|never|allowed|forbidden)\b/i, weight: 2 },
+    // KG: relationships, structure, "how does X relate to / depend on Y", who/what connects.
+    { surface: 'kg', pattern: /\b(relat(e|es|ed|ionship)|depend(s|ency|encies)?|connect(s|ed|ion)?|link(s|ed)?|between|structure|architecture|who (owns|maintains|uses)|what (uses|calls|imports))\b/i, weight: 2 },
+    { surface: 'kg', pattern: /\b(entity|entities|graph|triplet)\b/i, weight: 1.5 },
+    // Memory: past runs/decisions/outcomes/history.
+    { surface: 'memory', pattern: /\b(last (run|time)|previous(ly)?|history|past|earlier|before|decision|decided|outcome|learned|remember)\b/i, weight: 2 },
+    // Chunks: docs/specs/definitions/how-to content.
+    { surface: 'chunks', pattern: /\b(doc(s|ument|umentation)?|spec|readme|guide|manual|note(s)?|wrote|written|what is|how (do|to)|explain|describe|definition)\b/i, weight: 1.5 },
+];
+/** Negated mentions must not vote: "not about the architecture" (cognee uses
+ *  a 20-char pre-match negation window; same here). */
+const NEGATION_RE = /\b(not?|without|except|ignore|don'?t|excluding)\b[^.!?]{0,20}$/i;
+const overrideCounts = {};
+/** Overrides persist across processes (the CLI is one-shot — an in-memory
+ *  counter alone evaporates before doctor/debugging can read it). Best-effort
+ *  read-merge-write of a tiny JSON file; never throws into the caller. */
+const OVERRIDES_FILE = ['.monomind', 'metrics', 'route-overrides.json'];
+function persistOverride(key) {
+    try {
+        const file = path.join(process.cwd(), ...OVERRIDES_FILE);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        let disk = {};
+        try {
+            disk = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        }
+        catch { /* fresh file */ }
+        disk[key] = (typeof disk[key] === 'number' ? disk[key] : 0) + 1;
+        fs.writeFileSync(file, JSON.stringify(disk, null, 2));
+    }
+    catch { /* telemetry must never block or throw */ }
+}
+export function routeQuery(query) {
+    const q = String(query ?? '').slice(0, 2000);
+    const scores = { chunks: 0.5, kg: 0, rules: 0, memory: 0 }; // chunks = weak prior
+    for (const rule of ROUTE_RULES) {
+        for (const m of q.matchAll(new RegExp(rule.pattern.source, rule.pattern.flags + 'g'))) {
+            const before = q.slice(Math.max(0, (m.index ?? 0) - 26), m.index ?? 0);
+            if (NEGATION_RE.test(before))
+                continue;
+            scores[rule.surface] += rule.weight;
+        }
+    }
+    const ranked = Object.entries(scores)
+        .sort((a, b) => b[1] - a[1]);
+    const [winner, runnerUp] = ranked;
+    const confident = winner[1] >= 2 * Math.max(runnerUp[1], 0.25);
+    const surfaces = confident
+        ? [winner[0]]
+        : ranked.filter(([, s]) => s > 0).map(([k]) => k);
+    return { surfaces: surfaces.length ? surfaces : ['chunks'], confident, scores };
+}
+/** Call when a route proved wrong (caller retried another surface) — counts
+ *  feed debugging, mirroring cognee's record_override telemetry. */
+export function recordRouteOverride(from, to) {
+    const key = `${from}->${to}`;
+    overrideCounts[key] = (overrideCounts[key] ?? 0) + 1;
+    persistOverride(key);
+}
+/** In-memory counts from this process only; pass merged=true to include the
+ *  persisted cross-process counts from .monomind/metrics/route-overrides.json. */
+export function getRouteOverrides(merged = false) {
+    if (!merged)
+        return { ...overrideCounts };
+    try {
+        const disk = JSON.parse(fs.readFileSync(path.join(process.cwd(), ...OVERRIDES_FILE), 'utf-8'));
+        return { ...disk }; // disk already includes this process's persisted increments
+    }
+    catch {
+        return { ...overrideCounts };
+    }
+}
+/** Fuse ranked lists via RRF × importance factor (cognee hybrid/ranking.py).
+ *  Input lists must each be ranked best-first; raw scores are ignored. */
+export function rrfFuse(lists, topK) {
+    const rrfK = Math.max(30, Math.min(60, 20 + 2 * topK));
+    const byId = new Map();
+    for (const list of lists) {
+        list.forEach((item, rank) => {
+            const importance = typeof item.importance === 'number' ? item.importance : 0.5;
+            const contribution = (1 / (rrfK + rank + 1)) * (0.75 + 0.5 * importance);
+            const existing = byId.get(item.id);
+            if (existing)
+                existing.rrf += contribution;
+            else
+                byId.set(item.id, { item, rrf: contribution });
+        });
+    }
+    return [...byId.values()]
+        .sort((a, b) => b.rrf - a.rrf)
+        .slice(0, topK)
+        .map(({ item, rrf }) => ({ ...item, rrf }));
+}
+//# sourceMappingURL=query-router.js.map

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

@@ -44,6 +44,8 @@ export declare class OrgDaemon {
     private globalSubscribers;
     private leases;
     private forwarders;
+    private watchdogs;
+    private stopping;
     constructor(root: string, opts?: DaemonOpts);
     /** Publish this daemon's inbox so orgs started AFTER this call register with the broker. */
     setInboxUrl(url: string): void;
@@ -98,6 +100,7 @@ export declare class OrgDaemon {
      *  Fire-and-forget — errors are logged but don't propagate to the sender. */
     private autoWake;
     stopOrg(name: string): Promise<void>;
+    private finishStop;
     stopAll(): Promise<void>;
     private orgMemoryNamespace;
     /** Store dir for org cross-run memory — inside the org root so the bridge's
@@ -109,6 +112,16 @@ export declare class OrgDaemon {
      *  unusual daemon setups) that redirect would write into the WRONG project's
      *  memory — verify the guard kept our path, and skip org memory otherwise. */
     private orgMemoryUsable;
+    /** Namespace for a role's PRIVATE memories, inside the org memory DB. */
+    private agentMemoryNamespace;
+    /** org_remember implementation: a deliberate write to org-shared or
+     *  role-private memory (both in the org memory DB, split by namespace). */
+    private rememberOrgMemory;
+    /** Entry IDs served by org_recall during the current run, per org. This is
+     *  the usage record the run-outcome auto-rating consumes (cognee's
+     *  used_graph_element_ids pattern) — recall renders text to the agent, so
+     *  the IDs must be captured here or they're gone. */
+    private recallUsage;
     /** org_recall implementation: search the org's memory namespace via the
      *  memory bridge (semantic when the local model is available, tokenized
      *  keyword otherwise). Failures return a message, never throw into the tool. */
@@ -121,6 +134,11 @@ export declare class OrgDaemon {
         text: string;
         hits: number;
     }>;
+    /** org_learn implementation: merge coordinator-extracted entities/relations/
+     *  rules into the org's knowledge graph (LLM extraction happens inside the
+     *  agent's own subscription-auth SDK session — no separate LLM call here). */
+    private orgLearnedRuns;
+    private learnOrgKnowledge;
     /** 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;