mem-os-python 1.6.27__py3-none-any.whl

memos/_js/confidence-machine.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Confidence score state machine for MemOS memory nodes.
+ *
+ * Implements the reinforce/revise/supersede pattern described in
+ * Mem0's "AI Memory Confidence Score" blog post, adapted for MemOS's
+ * local-first architecture.
+ *
+ * Every memory node carries a `confidence` [0,1] and `evidenceCount`
+ * in its metadata. When a new observation touches an existing memory,
+ * the confidence score is adjusted:
+ *
+ * - CONFIRMED (new evidence agrees) → confidence increases (diminishing returns)
+ * - PARTIAL_CONFLICT (new evidence partially conflicts) → confidence decreases
+ * - CONTRADICTED (new evidence clearly replaces) → supersede old memory
+ *
+ * The confidence score feeds into the trust-weighted hybrid search,
+ * so lower-confidence memories rank lower in retrieval results.
+ */
+/** Default confidence floor — memories below this get flagged for review. */
+export declare const CONFIDENCE_FLOOR = 0.3;
+/** Initial confidence for a new memory before any evidence. */
+export declare const INITIAL_CONFIDENCE = 0.5;
+/** Maximum confidence cap. */
+export declare const CONFIDENCE_CAP = 1;
+/**
+ * Keyword signals that mark new content as a negation/update of an
+ * existing fact ("no longer", "moved", …). Exported so the store-path
+ * evidence wiring (src/memory.ts) uses the SAME word list as
+ * {@link classifyEvidence} instead of duplicating it.
+ */
+export declare const CONTRADICTION_SIGNALS: readonly ["not", "never", "no longer", "changed", "moved", "left", "different"];
+/**
+ * The outcome of comparing a new observation against an existing memory.
+ */
+export type EvidenceOutcome = "confirmed" | "partial_conflict" | "contradicted";
+/**
+ * The result of applying evidence to a memory's confidence score.
+ */
+export interface ConfidenceUpdate {
+    /** New confidence score in [0, 1]. */
+    confidence: number;
+    /** New evidence count (total reinforce + revise events). */
+    evidenceCount: number;
+    /** Whether the memory was superseded (i.e. should be marked historical). */
+    superseded: boolean;
+    /** Whether the memory is now below the confidence floor (flagged for review). */
+    flaggedForReview: boolean;
+}
+/**
+ * Apply a single evidence event to a memory's confidence score.
+ *
+ * Uses a diminishing-returns formula for reinforcement:
+ *   confidence += (CAP - confidence) * REINFORCE_RATE
+ *
+ * For partial conflicts (down-adjust):
+ *   confidence -= confidence * REVISE_RATE
+ *
+ * @param currentConfidence — Current confidence score [0, 1].
+ * @param currentEvidence — Current evidence count.
+ * @param outcome — The evidence outcome from comparing new observation.
+ * @returns Updated ConfidenceUpdate.
+ */
+export declare function applyEvidence(currentConfidence: number, currentEvidence: number, outcome: EvidenceOutcome): ConfidenceUpdate;
+/**
+ * Compare a new observation against an existing memory to determine
+ * the evidence outcome.
+ *
+ * This is a simple heuristic-based classifier. For production use,
+ * you may want to replace this with an LLM-based classifier.
+ *
+ * @param existingContent — The existing memory's content.
+ * @param newContent — The new observation's content.
+ * @param similarity — Semantic similarity between the two (0-1).
+ * @returns The EvidenceOutcome.
+ */
+export declare function classifyEvidence(existingContent: string, newContent: string, similarity: number): EvidenceOutcome;
+/**
+ * Do two texts talk about the same SUBJECT?
+ *
+ * Guard used by the store-path evidence wiring before a contradiction is
+ * allowed to supersede a memory: the texts must share at least one
+ * meaningful content word (length > 2, not a stop word). This prevents
+ * "User no longer drinks coffee" from nuking an unrelated memory that
+ * merely happens to contain a signal word.
+ */
+export declare function sharesSubject(a: string, b: string): boolean;
+/**
+ * Get the effective retrieval weight for a memory, combining
+ * trust and confidence scores.
+ *
+ * Higher trust (source) + higher confidence → higher weight.
+ * Memories below the confidence floor get suppressed.
+ *
+ * @param trustScore — The static trust score [0, 1] from provenance.
+ * @param confidence — The dynamic confidence score [0, 1].
+ * @returns Combined weight multiplier in [0, 1].
+ */
+export declare function confidenceWeight(trustScore: number, confidence?: number): number;
+//# sourceMappingURL=confidence-machine.d.ts.map

memos/_js/confidence-machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confidence-machine.d.ts","sourceRoot":"","sources":["../src/confidence-machine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,+DAA+D;AAC/D,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC,8BAA8B;AAC9B,eAAO,MAAM,cAAc,IAAM,CAAC;AAElC;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,YAChC,KAAK,EACL,OAAO,EACP,WAAW,EACX,SAAS,EACT,OAAO,EACP,MAAM,EACN,WAAW,CACH,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,kBAAkB,GAAG,cAAc,CAAC;AAEhF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,aAAa,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,UAAU,EAAE,OAAO,CAAC;IACpB,iFAAiF;IACjF,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,iBAAiB,EAAE,MAAM,EACzB,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,eAAe,GACvB,gBAAgB,CAqClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,eAAe,CA+BjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAoE3D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAYR"}

memos/_js/confidence-machine.js

@@ -0,0 +1,222 @@
+/**
+ * Confidence score state machine for MemOS memory nodes.
+ *
+ * Implements the reinforce/revise/supersede pattern described in
+ * Mem0's "AI Memory Confidence Score" blog post, adapted for MemOS's
+ * local-first architecture.
+ *
+ * Every memory node carries a `confidence` [0,1] and `evidenceCount`
+ * in its metadata. When a new observation touches an existing memory,
+ * the confidence score is adjusted:
+ *
+ * - CONFIRMED (new evidence agrees) → confidence increases (diminishing returns)
+ * - PARTIAL_CONFLICT (new evidence partially conflicts) → confidence decreases
+ * - CONTRADICTED (new evidence clearly replaces) → supersede old memory
+ *
+ * The confidence score feeds into the trust-weighted hybrid search,
+ * so lower-confidence memories rank lower in retrieval results.
+ */
+/** Default confidence floor — memories below this get flagged for review. */
+export const CONFIDENCE_FLOOR = 0.3;
+/** Initial confidence for a new memory before any evidence. */
+export const INITIAL_CONFIDENCE = 0.5;
+/** Maximum confidence cap. */
+export const CONFIDENCE_CAP = 1.0;
+/**
+ * Keyword signals that mark new content as a negation/update of an
+ * existing fact ("no longer", "moved", …). Exported so the store-path
+ * evidence wiring (src/memory.ts) uses the SAME word list as
+ * {@link classifyEvidence} instead of duplicating it.
+ */
+export const CONTRADICTION_SIGNALS = [
+    "not",
+    "never",
+    "no longer",
+    "changed",
+    "moved",
+    "left",
+    "different",
+];
+/**
+ * Apply a single evidence event to a memory's confidence score.
+ *
+ * Uses a diminishing-returns formula for reinforcement:
+ *   confidence += (CAP - confidence) * REINFORCE_RATE
+ *
+ * For partial conflicts (down-adjust):
+ *   confidence -= confidence * REVISE_RATE
+ *
+ * @param currentConfidence — Current confidence score [0, 1].
+ * @param currentEvidence — Current evidence count.
+ * @param outcome — The evidence outcome from comparing new observation.
+ * @returns Updated ConfidenceUpdate.
+ */
+export function applyEvidence(currentConfidence, currentEvidence, outcome) {
+    if (outcome === "contradicted") {
+        // Superseded — mark as historical, don't delete
+        return {
+            confidence: 0,
+            evidenceCount: currentEvidence + 1,
+            superseded: true,
+            flaggedForReview: false, // superseded is a stronger signal
+        };
+    }
+    if (outcome === "confirmed") {
+        // Reinforce: confidence increases with diminishing returns
+        // New = old + (CAP - old) * rate
+        const newConfidence = Math.min(CONFIDENCE_CAP, currentConfidence + (CONFIDENCE_CAP - currentConfidence) * 0.15);
+        return {
+            confidence: newConfidence,
+            evidenceCount: currentEvidence + 1,
+            superseded: false,
+            flaggedForReview: newConfidence < CONFIDENCE_FLOOR,
+        };
+    }
+    // partial_conflict — confidence decreases
+    const newConfidence = Math.max(0, currentConfidence - currentConfidence * 0.25);
+    return {
+        confidence: newConfidence,
+        evidenceCount: currentEvidence + 1,
+        superseded: false,
+        flaggedForReview: newConfidence < CONFIDENCE_FLOOR,
+    };
+}
+/**
+ * Compare a new observation against an existing memory to determine
+ * the evidence outcome.
+ *
+ * This is a simple heuristic-based classifier. For production use,
+ * you may want to replace this with an LLM-based classifier.
+ *
+ * @param existingContent — The existing memory's content.
+ * @param newContent — The new observation's content.
+ * @param similarity — Semantic similarity between the two (0-1).
+ * @returns The EvidenceOutcome.
+ */
+export function classifyEvidence(existingContent, newContent, similarity) {
+    // High similarity (>= 0.85) → confirmed (reinforced)
+    if (similarity >= 0.85) {
+        return "confirmed";
+    }
+    // Medium similarity (0.5 - 0.85) → partial conflict
+    if (similarity >= 0.5) {
+        return "partial_conflict";
+    }
+    // Low similarity (< 0.5) → check if they contradict
+    // Simple keyword-based contradiction detection
+    const newLower = newContent.toLowerCase();
+    // If the NEW content carries a contradiction signal and similarity is
+    // low, treat as contradicted (e.g. "user likes coffee" vs "user no
+    // longer likes coffee").
+    if (CONTRADICTION_SIGNALS.some((w) => newLower.includes(w)) &&
+        similarity < 0.3) {
+        return "contradicted";
+    }
+    // Very low similarity and no contradiction → unrelated (no change).
+    // NOTE for callers: this is the NEUTRAL fallthrough, not a positive
+    // confirmation — unrelated content must NOT reinforce a memory. The
+    // store-path wiring (src/memory.ts) distinguishes the two by requiring
+    // pair similarity >= 0.85 before treating "confirmed" as a reinforce.
+    return "confirmed";
+}
+/**
+ * Do two texts talk about the same SUBJECT?
+ *
+ * Guard used by the store-path evidence wiring before a contradiction is
+ * allowed to supersede a memory: the texts must share at least one
+ * meaningful content word (length > 2, not a stop word). This prevents
+ * "User no longer drinks coffee" from nuking an unrelated memory that
+ * merely happens to contain a signal word.
+ */
+export function sharesSubject(a, b) {
+    const STOP = new Set([
+        "the",
+        "a",
+        "an",
+        "and",
+        "or",
+        "but",
+        "if",
+        "then",
+        "else",
+        "when",
+        "at",
+        "by",
+        "for",
+        "with",
+        "about",
+        "into",
+        "through",
+        "during",
+        "to",
+        "from",
+        "in",
+        "on",
+        "of",
+        "is",
+        "are",
+        "was",
+        "were",
+        "be",
+        "been",
+        "being",
+        "have",
+        "has",
+        "had",
+        "do",
+        "does",
+        "did",
+        "will",
+        "would",
+        "can",
+        "could",
+        "should",
+        "may",
+        "might",
+        "must",
+        "shall",
+        "user",
+        "prefers",
+        "likes",
+        "not",
+        "no",
+        "longer",
+    ]);
+    const words = (t) => new Set(t
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length > 2 && !STOP.has(w)));
+    const setA = words(a);
+    const setB = words(b);
+    for (const w of setA) {
+        if (setB.has(w))
+            return true;
+    }
+    return false;
+}
+/**
+ * Get the effective retrieval weight for a memory, combining
+ * trust and confidence scores.
+ *
+ * Higher trust (source) + higher confidence → higher weight.
+ * Memories below the confidence floor get suppressed.
+ *
+ * @param trustScore — The static trust score [0, 1] from provenance.
+ * @param confidence — The dynamic confidence score [0, 1].
+ * @returns Combined weight multiplier in [0, 1].
+ */
+export function confidenceWeight(trustScore, confidence) {
+    if (confidence === undefined || confidence === null) {
+        // No confidence tracking yet — use trust score only
+        return trustScore;
+    }
+    if (confidence < CONFIDENCE_FLOOR) {
+        // Below floor: heavily suppress
+        return trustScore * 0.1;
+    }
+    // Combine trust and confidence with a geometric mean
+    // This penalizes memories that are low on either dimension
+    return Math.sqrt(trustScore * confidence);
+}
+//# sourceMappingURL=confidence-machine.js.map

memos/_js/confidence-machine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confidence-machine.js","sourceRoot":"","sources":["../src/confidence-machine.ts"],"names":[],"mappings":"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"}