@mnemoai/core 1.1.0 → 1.1.1

package/src/noise-prototypes.ts

@@ -1,164 +0,0 @@
-// SPDX-License-Identifier: MIT
-/**
- * Embedding-based Noise Prototype Bank
- *
- * Language-agnostic noise detection: maintains a bank of noise prototype
- * embeddings (recall queries, agent denials, greetings). Input texts are
- * compared via cosine similarity — no regex maintenance required.
- *
- * The bank starts with ~15 built-in multilingual prototypes and grows
- * automatically when the LLM extraction returns zero memories (feedback loop).
- */
-
-import type { Embedder } from "./embedder.js";
-
-// ============================================================================
-// Built-in noise prototypes (multilingual)
-// ============================================================================
-
-const BUILTIN_NOISE_TEXTS: readonly string[] = [
-    // Recall queries
-    "Do you remember what I told you?",
-    "Can you recall my preferences?",
-    "What did I say about that?",
-    "你还记得我喜欢什么吗",
-    "你知道我之前说过什么吗",
-    "記得我上次提到的嗎",
-    "我之前跟你说过吗",
-    // Agent denials
-    "I don't have any information about that",
-    "I don't recall any previous conversation",
-    "我没有相关的记忆",
-    // Greetings / boilerplate
-    "Hello, how are you doing today?",
-    "Hi there, what's up",
-    "新的一天开始了",
-];
-
-// ============================================================================
-// Constants
-// ============================================================================
-
-const DEFAULT_THRESHOLD = 0.82;
-const MAX_LEARNED_PROTOTYPES = 200;
-const DEDUP_THRESHOLD = 0.95;
-
-// ============================================================================
-// NoisePrototypeBank
-// ============================================================================
-
-export class NoisePrototypeBank {
-    private vectors: number[][] = [];
-    private builtinCount = 0;
-    private _initialized = false;
-    private debugLog: (msg: string) => void;
-
-    constructor(debugLog?: (msg: string) => void) {
-        this.debugLog = debugLog ?? (() => { });
-    }
-
-    /** Whether the bank has been initialized with prototype embeddings. */
-    get initialized(): boolean {
-        return this._initialized;
-    }
-
-    /** Total number of prototypes (built-in + learned). */
-    get size(): number {
-        return this.vectors.length;
-    }
-
-    /**
-     * Embed all built-in noise prototypes and cache their vectors.
-     * Call once at plugin startup. Safe to call multiple times (no-op after first).
-     */
-    async init(embedder: Embedder): Promise<void> {
-        if (this._initialized) return;
-
-        for (const text of BUILTIN_NOISE_TEXTS) {
-            try {
-                const v = await embedder.embed(text);
-                if (v && v.length > 0) this.vectors.push(v);
-            } catch {
-                // Skip failed embeddings — bank will work with whatever succeeds
-            }
-        }
-        this.builtinCount = this.vectors.length;
-        this._initialized = true;
-
-        // Degeneracy check: if all prototype vectors are nearly identical, the
-        // embedding model does not produce discriminative outputs (e.g. a
-        // deterministic mock that ignores text).  In that case the noise bank
-        // would flag every input as noise, so we disable ourselves.
-        if (this.vectors.length >= 2) {
-            const sim = cosine(this.vectors[0], this.vectors[1]);
-            if (sim > 0.98) {
-                this.debugLog(
-                    `noise-prototype-bank: degenerate embeddings detected (pairwise cosine=${sim.toFixed(4)}), disabling noise filter`,
-                );
-                this._initialized = false;
-                this.vectors = [];
-                return;
-            }
-        }
-
-        this.debugLog(
-            `noise-prototype-bank: initialized with ${this.builtinCount} built-in prototypes`,
-        );
-    }
-
-    /**
-     * Check if a text vector matches any noise prototype.
-     * Returns true if cosine similarity >= threshold with any prototype.
-     */
-    isNoise(textVector: number[], threshold = DEFAULT_THRESHOLD): boolean {
-        if (!this._initialized || this.vectors.length === 0) return false;
-        for (const proto of this.vectors) {
-            if (cosine(proto, textVector) >= threshold) return true;
-        }
-        return false;
-    }
-
-    /**
-     * LLM feedback: add a text vector to the learned noise bank.
-     * Called when LLM extraction returns zero memories (strong noise signal).
-     * Deduplicates against existing prototypes (>= 0.95 similarity = skip).
-     * Evicts oldest learned prototype when bank exceeds MAX_LEARNED_PROTOTYPES.
-     */
-    learn(textVector: number[]): void {
-        if (!this._initialized) return;
-
-        // Deduplicate: too similar to an existing prototype → skip
-        for (const proto of this.vectors) {
-            if (cosine(proto, textVector) >= DEDUP_THRESHOLD) return;
-        }
-
-        this.vectors.push(textVector);
-
-        // Evict oldest learned prototype if over limit (preserve built-in prototypes)
-        if (this.vectors.length > this.builtinCount + MAX_LEARNED_PROTOTYPES) {
-            this.vectors.splice(this.builtinCount, 1);
-        }
-
-        this.debugLog(
-            `noise-prototype-bank: learned new noise prototype (total: ${this.vectors.length})`,
-        );
-    }
-}
-
-// ============================================================================
-// Cosine Similarity
-// ============================================================================
-
-function cosine(a: number[], b: number[]): number {
-    if (a.length !== b.length) return 0;
-    let dot = 0;
-    let na = 0;
-    let nb = 0;
-    for (let i = 0; i < a.length; i++) {
-        dot += a[i] * b[i];
-        na += a[i] * a[i];
-        nb += b[i] * b[i];
-    }
-    const denom = Math.sqrt(na) * Math.sqrt(nb);
-    return denom === 0 ? 0 : dot / denom;
-}

package/src/observability.ts

@@ -1,81 +0,0 @@
-// SPDX-License-Identifier: LicenseRef-Mnemo-Pro
-/**
- * Observability — aggregated stats from query-tracking.jsonl
- */
-
-import { getRecentQueries, type QueryRecord } from "./query-tracker.js";
-
-export interface QueryStats {
-  totalQueries: number;
-  avgLatencyMs: number;
-  resonancePassRate: number;
-  avgHitCount: number;
-  queryTypeDistribution: Record<string, number>;
-  hourlyTrend: { hour: string; count: number }[];
-}
-
-export async function getStats(maxRecords = 1000): Promise<QueryStats> {
-  const records = await getRecentQueries(maxRecords);
-
-  if (records.length === 0) {
-    return {
-      totalQueries: 0,
-      avgLatencyMs: 0,
-      resonancePassRate: 0,
-      avgHitCount: 0,
-      queryTypeDistribution: {},
-      hourlyTrend: [],
-    };
-  }
-
-  const totalQueries = records.length;
-  const avgLatencyMs = Math.round(
-    records.reduce((sum, r) => sum + r.latency_ms, 0) / totalQueries
-  );
-  const resonancePassRate = +(
-    records.filter((r) => r.resonancePass).length / totalQueries
-  ).toFixed(3);
-  const avgHitCount = +(
-    records.reduce((sum, r) => sum + r.hitCount, 0) / totalQueries
-  ).toFixed(2);
-
-  // Query type distribution
-  const queryTypeDistribution: Record<string, number> = {};
-  for (const r of records) {
-    queryTypeDistribution[r.queryType] =
-      (queryTypeDistribution[r.queryType] || 0) + 1;
-  }
-
-  // Hourly trend — last 24h bucketed by hour
-  const now = Date.now();
-  const cutoff = now - 24 * 60 * 60 * 1000;
-  const hourBuckets = new Map<string, number>();
-
-  for (let i = 0; i < 24; i++) {
-    const d = new Date(now - i * 60 * 60 * 1000);
-    const key = d.toISOString().slice(0, 13); // "YYYY-MM-DDTHH"
-    hourBuckets.set(key, 0);
-  }
-
-  for (const r of records) {
-    const ts = new Date(r.timestamp).getTime();
-    if (ts < cutoff) continue;
-    const key = r.timestamp.slice(0, 13);
-    if (hourBuckets.has(key)) {
-      hourBuckets.set(key, hourBuckets.get(key)! + 1);
-    }
-  }
-
-  const hourlyTrend = Array.from(hourBuckets.entries())
-    .map(([hour, count]) => ({ hour, count }))
-    .sort((a, b) => a.hour.localeCompare(b.hour));
-
-  return {
-    totalQueries,
-    avgLatencyMs,
-    resonancePassRate,
-    avgHitCount,
-    queryTypeDistribution,
-    hourlyTrend,
-  };
-}

package/src/query-tracker.ts

@@ -1,57 +0,0 @@
-// SPDX-License-Identifier: LicenseRef-Mnemo-Pro
-/**
- * Query Tracker
- *
- * Lightweight, append-only JSONL tracker for every recall query.
- * Fire-and-forget writes — never blocks the recall path.
- * Persisted to ~/.openclaw/memory/query-tracking.jsonl.
- */
-
-import { appendFile, readFile, mkdir } from "node:fs/promises";
-import { homedir } from "node:os";
-import { join, dirname } from "node:path";
-
-const TRACKING_PATH = join(homedir(), ".openclaw", "memory", "query-tracking.jsonl");
-
-export interface QueryRecord {
-  timestamp: string;
-  query: string;
-  source: "auto" | "manual" | "cli";
-  hitCount: number;
-  topScore: number;
-  latency_ms: number;
-  queryType: "single" | "multi-hop" | "gated-out";
-  resonancePass: boolean;
-}
-
-let dirEnsured = false;
-
-/**
- * Record a query to the tracking log (fire-and-forget).
- * Errors are silently swallowed to avoid impacting recall latency.
- */
-export function recordQuery(data: QueryRecord): void {
-  const line = JSON.stringify(data) + "\n";
-  const doWrite = async () => {
-    if (!dirEnsured) {
-      await mkdir(dirname(TRACKING_PATH), { recursive: true });
-      dirEnsured = true;
-    }
-    await appendFile(TRACKING_PATH, line, "utf8");
-  };
-  doWrite().catch(() => {});
-}
-
-/**
- * Read the most recent N query records from the tracking log.
- */
-export async function getRecentQueries(n: number = 100): Promise<QueryRecord[]> {
-  try {
-    const raw = await readFile(TRACKING_PATH, "utf8");
-    const lines = raw.trim().split("\n").filter(Boolean);
-    const recent = lines.slice(-n);
-    return recent.map((line) => JSON.parse(line) as QueryRecord);
-  } catch {
-    return [];
-  }
-}

package/src/reflection-event-store.ts

@@ -1,98 +0,0 @@
-// SPDX-License-Identifier: LicenseRef-Mnemo-Pro
-import { createHash } from "node:crypto";
-
-export const REFLECTION_SCHEMA_VERSION = 4;
-
-export type ReflectionErrorSignalLike = {
-  signatureHash: string;
-};
-
-export interface ReflectionEventMetadata {
-  type: "memory-reflection-event";
-  reflectionVersion: 4;
-  stage: "reflect-store";
-  eventId: string;
-  sessionKey: string;
-  sessionId: string;
-  agentId: string;
-  command: string;
-  storedAt: number;
-  usedFallback: boolean;
-  errorSignals: string[];
-  sourceReflectionPath?: string;
-}
-
-export interface ReflectionEventPayload {
-  kind: "event";
-  text: string;
-  metadata: ReflectionEventMetadata;
-}
-
-export interface BuildReflectionEventPayloadParams {
-  eventId?: string;
-  scope: string;
-  sessionKey: string;
-  sessionId: string;
-  agentId: string;
-  command: string;
-  toolErrorSignals: ReflectionErrorSignalLike[];
-  runAt: number;
-  usedFallback: boolean;
-  sourceReflectionPath?: string;
-}
-
-export function createReflectionEventId(params: {
-  runAt: number;
-  sessionKey: string;
-  sessionId: string;
-  agentId: string;
-  command: string;
-}): string {
-  const safeRunAt = Number.isFinite(params.runAt) ? Math.max(0, Math.floor(params.runAt)) : Date.now();
-  const datePart = new Date(safeRunAt).toISOString().replace(/[-:.TZ]/g, "").slice(0, 14);
-  const digest = createHash("sha1")
-    .update(`${safeRunAt}|${params.sessionKey}|${params.sessionId}|${params.agentId}|${params.command}`)
-    .digest("hex")
-    .slice(0, 8);
-  return `refl-${datePart}-${digest}`;
-}
-
-export function buildReflectionEventPayload(params: BuildReflectionEventPayloadParams): ReflectionEventPayload {
-  const eventId = params.eventId || createReflectionEventId({
-    runAt: params.runAt,
-    sessionKey: params.sessionKey,
-    sessionId: params.sessionId,
-    agentId: params.agentId,
-    command: params.command,
-  });
-
-  const metadata: ReflectionEventMetadata = {
-    type: "memory-reflection-event",
-    reflectionVersion: REFLECTION_SCHEMA_VERSION,
-    stage: "reflect-store",
-    eventId,
-    sessionKey: params.sessionKey,
-    sessionId: params.sessionId,
-    agentId: params.agentId,
-    command: params.command,
-    storedAt: params.runAt,
-    usedFallback: params.usedFallback,
-    errorSignals: params.toolErrorSignals.map((signal) => signal.signatureHash),
-    ...(params.sourceReflectionPath ? { sourceReflectionPath: params.sourceReflectionPath } : {}),
-  };
-
-  const text = [
-    `reflection-event · ${params.scope}`,
-    `eventId=${eventId}`,
-    `session=${params.sessionId}`,
-    `agent=${params.agentId}`,
-    `command=${params.command}`,
-    `usedFallback=${params.usedFallback ? "true" : "false"}`,
-  ].join("\n");
-
-  return {
-    kind: "event",
-    text,
-    metadata,
-  };
-}

package/src/reflection-item-store.ts

@@ -1,112 +0,0 @@
-// SPDX-License-Identifier: LicenseRef-Mnemo-Pro
-import type { ReflectionSliceItem } from "./reflection-slices.js";
-
-export type ReflectionItemKind = "invariant" | "derived";
-
-export interface ReflectionItemMetadata {
-  type: "memory-reflection-item";
-  reflectionVersion: 4;
-  stage: "reflect-store";
-  eventId: string;
-  itemKind: ReflectionItemKind;
-  section: "Invariants" | "Derived";
-  ordinal: number;
-  groupSize: number;
-  agentId: string;
-  sessionKey: string;
-  sessionId: string;
-  storedAt: number;
-  usedFallback: boolean;
-  errorSignals: string[];
-  decayModel: "logistic";
-  decayMidpointDays: number;
-  decayK: number;
-  baseWeight: number;
-  quality: number;
-  sourceReflectionPath?: string;
-}
-
-export interface ReflectionItemPayload {
-  kind: "item-invariant" | "item-derived";
-  text: string;
-  metadata: ReflectionItemMetadata;
-}
-
-export interface BuildReflectionItemPayloadsParams {
-  items: ReflectionSliceItem[];
-  eventId: string;
-  agentId: string;
-  sessionKey: string;
-  sessionId: string;
-  runAt: number;
-  usedFallback: boolean;
-  toolErrorSignals: Array<{ signatureHash: string }>;
-  sourceReflectionPath?: string;
-}
-
-export const REFLECTION_INVARIANT_DECAY_MIDPOINT_DAYS = 45;
-export const REFLECTION_INVARIANT_DECAY_K = 0.22;
-export const REFLECTION_INVARIANT_BASE_WEIGHT = 1.1;
-export const REFLECTION_INVARIANT_QUALITY = 1;
-
-export const REFLECTION_DERIVED_DECAY_MIDPOINT_DAYS = 7;
-export const REFLECTION_DERIVED_DECAY_K = 0.65;
-export const REFLECTION_DERIVED_BASE_WEIGHT = 1;
-export const REFLECTION_DERIVED_QUALITY = 0.95;
-
-export function getReflectionItemDecayDefaults(itemKind: ReflectionItemKind): {
-  midpointDays: number;
-  k: number;
-  baseWeight: number;
-  quality: number;
-} {
-  if (itemKind === "invariant") {
-    return {
-      midpointDays: REFLECTION_INVARIANT_DECAY_MIDPOINT_DAYS,
-      k: REFLECTION_INVARIANT_DECAY_K,
-      baseWeight: REFLECTION_INVARIANT_BASE_WEIGHT,
-      quality: REFLECTION_INVARIANT_QUALITY,
-    };
-  }
-
-  return {
-    midpointDays: REFLECTION_DERIVED_DECAY_MIDPOINT_DAYS,
-    k: REFLECTION_DERIVED_DECAY_K,
-    baseWeight: REFLECTION_DERIVED_BASE_WEIGHT,
-    quality: REFLECTION_DERIVED_QUALITY,
-  };
-}
-
-export function buildReflectionItemPayloads(params: BuildReflectionItemPayloadsParams): ReflectionItemPayload[] {
-  return params.items.map((item) => {
-    const defaults = getReflectionItemDecayDefaults(item.itemKind);
-    const metadata: ReflectionItemMetadata = {
-      type: "memory-reflection-item",
-      reflectionVersion: 4,
-      stage: "reflect-store",
-      eventId: params.eventId,
-      itemKind: item.itemKind,
-      section: item.section,
-      ordinal: item.ordinal,
-      groupSize: item.groupSize,
-      agentId: params.agentId,
-      sessionKey: params.sessionKey,
-      sessionId: params.sessionId,
-      storedAt: params.runAt,
-      usedFallback: params.usedFallback,
-      errorSignals: params.toolErrorSignals.map((signal) => signal.signatureHash),
-      decayModel: "logistic",
-      decayMidpointDays: defaults.midpointDays,
-      decayK: defaults.k,
-      baseWeight: defaults.baseWeight,
-      quality: defaults.quality,
-      ...(params.sourceReflectionPath ? { sourceReflectionPath: params.sourceReflectionPath } : {}),
-    };
-
-    return {
-      kind: item.itemKind === "invariant" ? "item-invariant" : "item-derived",
-      text: item.text,
-      metadata,
-    };
-  });
-}

package/src/reflection-mapped-metadata.ts

@@ -1,84 +0,0 @@
-// SPDX-License-Identifier: LicenseRef-Mnemo-Pro
-import type { ReflectionMappedMemoryItem } from "./reflection-slices.js";
-
-export type ReflectionMappedKind = "user-model" | "agent-model" | "lesson" | "decision";
-export type ReflectionMappedCategory = "preference" | "fact" | "decision";
-
-export interface ReflectionMappedMetadata {
-  type: "memory-reflection-mapped";
-  reflectionVersion: 4;
-  stage: "reflect-store";
-  eventId: string;
-  mappedKind: ReflectionMappedKind;
-  mappedCategory: ReflectionMappedCategory;
-  section: string;
-  ordinal: number;
-  groupSize: number;
-  agentId: string;
-  sessionKey: string;
-  sessionId: string;
-  storedAt: number;
-  usedFallback: boolean;
-  errorSignals: string[];
-  decayModel: "logistic";
-  decayMidpointDays: number;
-  decayK: number;
-  baseWeight: number;
-  quality: number;
-  sourceReflectionPath?: string;
-}
-
-export interface ReflectionMappedDecayDefaults {
-  midpointDays: number;
-  k: number;
-  baseWeight: number;
-  quality: number;
-}
-
-const REFLECTION_MAPPED_DECAY_DEFAULTS: Record<ReflectionMappedKind, ReflectionMappedDecayDefaults> = {
-  decision: { midpointDays: 45, k: 0.25, baseWeight: 1.1, quality: 1 },
-  "user-model": { midpointDays: 21, k: 0.3, baseWeight: 1, quality: 0.95 },
-  "agent-model": { midpointDays: 10, k: 0.35, baseWeight: 0.95, quality: 0.93 },
-  lesson: { midpointDays: 7, k: 0.45, baseWeight: 0.9, quality: 0.9 },
-};
-
-export function getReflectionMappedDecayDefaults(kind: ReflectionMappedKind): ReflectionMappedDecayDefaults {
-  return REFLECTION_MAPPED_DECAY_DEFAULTS[kind];
-}
-
-export function buildReflectionMappedMetadata(params: {
-  mappedItem: ReflectionMappedMemoryItem;
-  eventId: string;
-  agentId: string;
-  sessionKey: string;
-  sessionId: string;
-  runAt: number;
-  usedFallback: boolean;
-  toolErrorSignals: Array<{ signatureHash: string }>;
-  sourceReflectionPath?: string;
-}): ReflectionMappedMetadata {
-  const defaults = getReflectionMappedDecayDefaults(params.mappedItem.mappedKind);
-  return {
-    type: "memory-reflection-mapped",
-    reflectionVersion: 4,
-    stage: "reflect-store",
-    eventId: params.eventId,
-    mappedKind: params.mappedItem.mappedKind,
-    mappedCategory: params.mappedItem.category,
-    section: params.mappedItem.heading,
-    ordinal: params.mappedItem.ordinal,
-    groupSize: params.mappedItem.groupSize,
-    agentId: params.agentId,
-    sessionKey: params.sessionKey,
-    sessionId: params.sessionId,
-    storedAt: params.runAt,
-    usedFallback: params.usedFallback,
-    errorSignals: params.toolErrorSignals.map((signal) => signal.signatureHash),
-    decayModel: "logistic",
-    decayMidpointDays: defaults.midpointDays,
-    decayK: defaults.k,
-    baseWeight: defaults.baseWeight,
-    quality: defaults.quality,
-    ...(params.sourceReflectionPath ? { sourceReflectionPath: params.sourceReflectionPath } : {}),
-  };
-}

package/src/reflection-metadata.ts

@@ -1,23 +0,0 @@
-// SPDX-License-Identifier: LicenseRef-Mnemo-Pro
-export function parseReflectionMetadata(metadataRaw: string | undefined): Record<string, unknown> {
-  if (!metadataRaw) return {};
-  try {
-    const parsed = JSON.parse(metadataRaw);
-    return parsed && typeof parsed === "object" ? parsed as Record<string, unknown> : {};
-  } catch {
-    return {};
-  }
-}
-
-export function isReflectionEntry(entry: { category: string; metadata?: string }): boolean {
-  if (entry.category === "reflection") return true;
-  const metadata = parseReflectionMetadata(entry.metadata);
-  return metadata.type === "memory-reflection" ||
-    metadata.type === "memory-reflection-event" ||
-    metadata.type === "memory-reflection-item";
-}
-
-export function getDisplayCategoryTag(entry: { category: string; scope: string; metadata?: string }): string {
-  if (!isReflectionEntry(entry)) return `${entry.category}:${entry.scope}`;
-  return `reflection:${entry.scope}`;
-}