monomind 2.5.0 → 2.5.2

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

@@ -108,7 +108,7 @@ export function bridgeGetDbPath(customPath) {
     return getDbPath(customPath);
 }
 function getAutomemConfig() {
-    const defaults = { dedupThreshold: 0.85, staleDays: 7 };
+    const defaults = { dedupThreshold: 0.85, staleDays: 7, feedbackInfluence: 0.2 };
     try {
         const configPath = path.join(process.cwd(), '.monomind', 'automem-config.json');
         if (!fs.existsSync(configPath))
@@ -120,12 +120,43 @@ function getAutomemConfig() {
         return {
             dedupThreshold: typeof config?.scaffold?.dedupThreshold === 'number' ? config.scaffold.dedupThreshold : defaults.dedupThreshold,
             staleDays: typeof config?.scaffold?.staleDays === 'number' ? config.scaffold.staleDays : defaults.staleDays,
+            feedbackInfluence: typeof config?.scaffold?.feedbackInfluence === 'number'
+                ? Math.max(0, Math.min(1, config.scaffold.feedbackInfluence)) : defaults.feedbackInfluence,
         };
     }
     catch {
         return defaults;
     }
 }
+// ===== Usage/feedback weights (cognee-style, stored in entry metadata) =====
+//
+// feedback_weight (0..1, default 0.5): EWMA of explicit/auto ratings applied to
+// the entries actually used to produce an answer. frequency_weight (>=0): how
+// often the entry was returned by a search. Both live in the entry's metadata
+// JSON — deliberately NOT backend schema columns, so no @monoes/memory publish
+// is needed and both backends work unchanged.
+const DEFAULT_FEEDBACK_WEIGHT = 0.5;
+const FEEDBACK_EWMA_ALPHA = 0.1;
+/** frequency_weight normalization ceiling: 10+ uses counts as fully reinforced. */
+const FREQUENCY_NORM_CAP = 10;
+function entryWeights(metadata) {
+    const md = (metadata ?? {});
+    const fw = typeof md.feedback_weight === 'number' && Number.isFinite(md.feedback_weight)
+        ? Math.max(0, Math.min(1, md.feedback_weight)) : DEFAULT_FEEDBACK_WEIGHT;
+    const freq = typeof md.frequency_weight === 'number' && Number.isFinite(md.frequency_weight)
+        ? Math.max(0, md.frequency_weight) : 0;
+    return { feedback: fw, frequency: freq };
+}
+/** Blend learned usefulness into a GENUINE embedding-similarity score.
+ *  Cognee guard: never applied to keyword-fallback scores — those carry no
+ *  real relevance signal, and blending there lets a high-feedback stale entry
+ *  outrank relevant matches and self-reinforce (rich-get-richer). */
+function blendScore(cosineSim, weights, influence) {
+    if (influence <= 0)
+        return cosineSim;
+    const usefulness = 0.7 * weights.feedback + 0.3 * Math.min(1, weights.frequency / FREQUENCY_NORM_CAP);
+    return (1 - influence) * cosineSim + influence * usefulness;
+}
 function generateId(prefix) {
     return `${prefix}_${Date.now()}_${crypto.randomBytes(8).toString('hex')}`;
 }
@@ -260,7 +291,9 @@ export async function bridgeStoreEntry(options) {
             ? options.value.slice(0, BRIDGE_MAX_VALUE_LEN) : options.value;
         const namespace = options.namespace ?? 'default';
         const tags = Array.isArray(options.tags)
-            ? options.tags.filter(t => typeof t === 'string' && t.length > 0 && t.length <= MAX_TAG_LEN).slice(0, MAX_TAGS)
+            // src: tags carry the ingest source path for excerpt provenance — paths
+            // routinely exceed the general 64-char tag cap, so they get 512.
+            ? options.tags.filter(t => typeof t === 'string' && t.length > 0 && t.length <= (t.startsWith('src:') ? 512 : MAX_TAG_LEN)).slice(0, MAX_TAGS)
             : [];
         const now = Date.now();
         const id = generateId('entry');
@@ -283,6 +316,7 @@ export async function bridgeStoreEntry(options) {
             content: value,
             namespace,
             tags,
+            metadata: options.metadata,
             expiresAt: options.ttl ? now + options.ttl * 1000 : undefined,
         });
         // Override id and set embedding
@@ -310,6 +344,9 @@ export async function bridgeStoreEntry(options) {
                     filters: { type: 'exact', namespace },
                 });
                 if (similar.length > 0 && similar[0].score >= automemCfg.dedupThreshold) {
+                    // Re-storing near-identical content is a usage signal: the fact keeps
+                    // being worth remembering. Reinforce the surviving entry.
+                    await recordUsageOnBackend(backend, [similar[0].entry.id]).catch(() => { });
                     return { success: true, id: similar[0].entry.id, duplicate: true };
                 }
             }
@@ -351,16 +388,22 @@ export async function bridgeSearchEntries(options) {
                     threshold,
                     filters: namespace ? { type: 'exact', namespace } : undefined,
                 });
-                results = searchResults.map((r) => ({
-                    id: r.entry.id,
-                    key: r.entry.key,
-                    content: r.entry.content || '',
-                    score: r.score,
-                    namespace: r.entry.namespace,
-                    provenance: `semantic:${r.score.toFixed(3)}`,
-                    tags: r.entry.tags ?? [],
-                    _createdAt: r.entry.createdAt || 0,
-                }));
+                const { feedbackInfluence } = getAutomemConfig();
+                results = searchResults.map((r) => {
+                    const weights = entryWeights(r.entry.metadata);
+                    // Blend only here (semantic path): r.score is a genuine cosine similarity.
+                    const blended = blendScore(r.score, weights, feedbackInfluence);
+                    return {
+                        id: r.entry.id,
+                        key: r.entry.key,
+                        content: r.entry.content || '',
+                        score: blended,
+                        namespace: r.entry.namespace,
+                        provenance: `semantic:${r.score.toFixed(3)}${blended !== r.score ? `→${blended.toFixed(3)}` : ''}`,
+                        tags: r.entry.tags ?? [],
+                        _createdAt: r.entry.createdAt || 0,
+                    };
+                }).sort((a, b) => b.score - a.score);
                 searchMethod = 'semantic';
             }
             catch { /* fall through to keyword search */ }
@@ -409,11 +452,14 @@ export async function bridgeSearchEntries(options) {
         // forever) — keying it on the query's namespace filter meant an
         // all-namespace search silently dropped knowledge:* results past the
         // stale cutoff.
-        const isKnowledgeNs = namespace?.startsWith('knowledge:');
+        // org:* (cross-run org memory) and rules are durable learned state like
+        // documents — the stale cliff silently erased org recall after a week.
+        const durableNs = (ns) => ns.startsWith('knowledge:') || ns.startsWith('org:') || ns.startsWith('agent:') || ns.startsWith('kg:') || ns === 'rules';
+        const isKnowledgeNs = namespace ? durableNs(namespace) : false;
         if (!isKnowledgeNs) {
             const { staleDays } = getAutomemConfig();
             const staleCutoff = Date.now() - staleDays * 86400000;
-            results = results.filter((r) => String(r.namespace ?? '').startsWith('knowledge:')
+            results = results.filter((r) => durableNs(String(r.namespace ?? ''))
                 || !r._createdAt || r._createdAt > staleCutoff);
         }
         results.forEach((r) => delete r._createdAt);
@@ -451,6 +497,7 @@ export async function bridgeListEntries(options) {
                 updatedAt: new Date(e.updatedAt).toISOString(),
                 hasEmbedding: !!(e.embedding && e.embedding.length > 0),
                 tags: e.tags ?? [],
+                metadata: e.metadata ?? {},
             })),
             total: entries.length,
         };
@@ -481,6 +528,7 @@ export async function bridgeGetEntry(options) {
                 updatedAt: new Date(entry.updatedAt).toISOString(),
                 hasEmbedding: !!(entry.embedding && entry.embedding.length > 0),
                 tags: entry.tags ?? [],
+                metadata: entry.metadata ?? {},
             },
         };
     }
@@ -681,6 +729,93 @@ export async function bridgeSearchPatterns(options) {
         }),
     };
 }
+// ===== Usage capture & feedback weighting (closed loop) =====
+async function recordUsageOnBackend(backend, entryIds) {
+    let updated = 0;
+    for (const id of entryIds) {
+        if (typeof id !== 'string' || !id)
+            continue;
+        try {
+            const entry = await backend.get(id);
+            if (!entry)
+                continue;
+            const { frequency } = entryWeights(entry.metadata);
+            await backend.update(id, {
+                metadata: { frequency_weight: frequency + 1 },
+                lastAccessedAt: Date.now(),
+            });
+            updated++;
+        }
+        catch { /* skip unreadable entries */ }
+    }
+    return updated;
+}
+/** Record that these entries were actually USED (returned to and consumed by a
+ *  caller) — increments frequency_weight, which feeds the ranking blend. */
+export async function bridgeRecordUsage(options) {
+    const backend = await getBackend(options.dbPath);
+    if (!backend)
+        return null;
+    try {
+        const updated = await recordUsageOnBackend(backend, (options.entryIds ?? []).slice(0, 100));
+        if (updated)
+            await flushBackend(backend);
+        return { success: true, updated };
+    }
+    catch {
+        return { success: false, updated: 0 };
+    }
+}
+/** Apply a usefulness rating to the entries that produced an answer:
+ *  EWMA feedback_weight' = w + alpha*(score - w), clipped [0,1] (cognee's
+ *  apply_feedback_weights). `ledgerKey` makes application idempotent — a
+ *  daemon retry or duplicate MCP call must never compound the update. */
+export async function bridgeApplyFeedback(options) {
+    const backend = await getBackend(options.dbPath);
+    if (!backend)
+        return null;
+    try {
+        const score = Math.max(0, Math.min(1, options.score));
+        const alpha = typeof options.alpha === 'number' ? Math.max(0, Math.min(1, options.alpha)) : FEEDBACK_EWMA_ALPHA;
+        const ledgerEntryKey = options.ledgerKey ? `applied_${options.ledgerKey.slice(0, 500)}` : null;
+        if (ledgerEntryKey) {
+            const existing = await backend.getByKey('feedback', ledgerEntryKey).catch(() => null);
+            if (existing)
+                return { success: true, applied: 0, alreadyApplied: true };
+        }
+        let applied = 0;
+        for (const id of (options.entryIds ?? []).slice(0, 100)) {
+            if (typeof id !== 'string' || !id)
+                continue;
+            try {
+                const entry = await backend.get(id);
+                if (!entry)
+                    continue;
+                const { feedback } = entryWeights(entry.metadata);
+                const next = Math.max(0, Math.min(1, feedback + alpha * (score - feedback)));
+                await backend.update(id, { metadata: { feedback_weight: next } });
+                applied++;
+            }
+            catch { /* skip unreadable entries */ }
+        }
+        if (ledgerEntryKey) {
+            await bridgeStoreEntry({
+                key: ledgerEntryKey,
+                value: JSON.stringify({ score, entryIds: options.entryIds.slice(0, 100), appliedAt: Date.now(), applied }),
+                namespace: 'feedback',
+                generateEmbeddingFlag: false,
+                dbPath: options.dbPath,
+                upsert: true,
+            });
+        }
+        if (applied)
+            await flushBackend(backend);
+        return { success: true, applied };
+    }
+    catch (err) {
+        return { success: false, applied: 0, error: String(err?.message ?? err) };
+    }
+}
 // ===== Feedback =====
 export async function bridgeRecordFeedback(options) {
     return bridgeStoreEntry({
@@ -832,28 +967,44 @@ export async function bridgeHierarchicalRecall(params) {
     });
 }
 // ===== Consolidation =====
+/** Namespaces GC must never touch: durable knowledge/org/rule state, and the
+ *  feedback ledger (deleting it would un-idempotent past ratings). */
+const GC_PROTECTED_NS = /^(knowledge:|org:|agent:|kg:|rules$|feedback$)/;
 export async function bridgeConsolidate(params) {
-    const backend = await getBackend();
+    const backend = await getBackend(params.dbPath);
     if (!backend)
         return { success: false, consolidated: 0 };
     try {
         const minAge = params.minAge ?? 7 * 24 * 3600 * 1000; // default: 7 days
         const cutoff = Date.now() - minAge;
+        const ns = params.namespace ?? 'default';
         const entries = await backend.query({
             type: 'exact',
-            namespace: 'default',
+            ...(ns === 'all' ? {} : { namespace: ns }),
             limit: params.maxEntries ?? 1000,
         });
         let deleted = 0;
+        let kept = 0;
         for (const e of entries) {
-            if (e.updatedAt < cutoff && e.accessCount === 0) {
+            if (GC_PROTECTED_NS.test(String(e.namespace ?? '')))
+                continue;
+            if (e.updatedAt >= cutoff)
+                continue;
+            const { feedback, frequency } = entryWeights(e.metadata);
+            // Weight-aware GC (first real consumer of the closed loop): entries the
+            // system learned are useful never age out; unused, unrated ones do.
+            if (feedback > 0.6 || frequency >= 3) {
+                kept++;
+                continue;
+            }
+            if ((e.accessCount ?? 0) === 0) {
                 await backend.delete(e.id).catch(() => { });
                 deleted++;
             }
         }
         if (deleted)
             await flushBackend(backend);
-        return { success: true, consolidated: deleted };
+        return { success: true, consolidated: deleted, preserved: kept };
     }
     catch {
         return { success: false, consolidated: 0 };

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

@@ -0,0 +1,185 @@
+/**
+ * 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 (cognee's DataPoint.id_for): the entry KEY is
+ * `n:<type>:<normalized-name>`, so the same entity extracted from any session
+ * merges idempotently via upsert. 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
+ */
+export declare const KG_NODES_NS = "kg:nodes";
+export declare const KG_EDGES_NS = "kg:edges";
+export declare const RULES_NS = "rules";
+export interface KgNodeInput {
+    name: string;
+    /** Basic type, cognee-style ("Person", "Tool", "Service") — not over-specific. */
+    type?: string;
+    description?: string;
+    nodeSet?: string;
+}
+export interface KgEdgeInput {
+    source: string;
+    target: string;
+    /** snake_case relation name. */
+    relation: string;
+    /** One-sentence concrete fact using the endpoint names. */
+    description?: string;
+    sourceType?: string;
+    targetType?: string;
+}
+export interface KgIngestResult {
+    success: boolean;
+    nodesAdded: number;
+    nodesMerged: number;
+    edgesAdded: number;
+    edgesMerged: number;
+    error?: string;
+}
+/** cognee DataPoint normalization: lowercase, spaces→_, strip apostrophes. */
+export declare function normalizeName(name: string): string;
+/** 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 declare function nodeKey(_type: string, name: string): string;
+/** 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 declare function kgIngest(options: {
+    nodes: KgNodeInput[];
+    edges?: KgEdgeInput[];
+    /** Provenance: run id, session id, or doc hash this extraction came from. */
+    originRef: string;
+    dbPath?: string;
+}): Promise<KgIngestResult>;
+export interface RuleVerdict {
+    rule: string;
+    verdict: 'accepted' | 'already_known' | 'invalid';
+    similarTo?: string;
+}
+/** 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 declare function kgIngestRules(options: {
+    rules: {
+        rule: string;
+        context?: string;
+    }[];
+    originRef: string;
+    dbPath?: string;
+    /** Similarity above which a candidate is already_known (default 0.78 —
+     *  MiniLM paraphrases of the same rule commonly land 0.78-0.9; cognee's
+     *  equivalent control is prompt-injected LLM judgment, which we approximate). */
+    dedupThreshold?: number;
+}): Promise<{
+    success: boolean;
+    verdicts: RuleVerdict[];
+    accepted: number;
+    error?: string;
+}>;
+/** List stored rules (for injection or review). */
+export declare function kgListRules(options?: {
+    dbPath?: string;
+    limit?: number;
+}): Promise<{
+    rule: string;
+    key: string;
+}[]>;
+export interface KgSearchResult {
+    success: boolean;
+    /** Rendered triplet lines, best first. */
+    context: string;
+    triplets: {
+        source: string;
+        relation: string;
+        target: string;
+        fact: string;
+        score: number;
+    }[];
+    seeds: {
+        name: string;
+        type: string;
+        description: string;
+        score: number;
+        id: string;
+    }[];
+    error?: string;
+}
+/** Vector-seed → neighborhood → triplet ranking (cognee's brute-force triplet
+ *  search, scaled down). Seed scores already carry the Phase 1 feedback blend. */
+export declare function kgSearch(options: {
+    query: string;
+    dbPath?: string;
+    limit?: number;
+    nodeSet?: string;
+}): Promise<KgSearchResult>;
+export declare function kgGlossary(options?: {
+    dbPath?: string;
+    limit?: number;
+}): Promise<string[]>;
+/** 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 declare function kgRollback(options: {
+    originRef: string;
+    dbPath?: string;
+}): Promise<{
+    success: boolean;
+    deleted: number;
+    retained: number;
+    error?: string;
+}>;
+export interface ConsolidationCandidate {
+    name: string;
+    type: string;
+    description: string;
+    edgeCount: number;
+    /** Neighborhood facts to merge into one canonical description. */
+    neighborhood: string[];
+}
+/** 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 declare function kgConsolidateCandidates(options?: {
+    dbPath?: string;
+    /** Minimum edges for a node to qualify (default 3). */
+    minEdges?: number;
+    limit?: number;
+}): Promise<ConsolidationCandidate[]>;
+export declare function kgStats(options?: {
+    dbPath?: string;
+}): Promise<{
+    nodes: number;
+    edges: number;
+    rules: number;
+}>;
+/** 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 declare function heuristicExtract(text: string, opts?: {
+    sourceName?: string;
+}): {
+    nodes: KgNodeInput[];
+    edges: KgEdgeInput[];
+};
+//# sourceMappingURL=memory-kg.d.ts.map