@mnemoai/core 1.1.0 → 1.1.1

package/src/access-tracker.ts

@@ -1,341 +0,0 @@
-// SPDX-License-Identifier: LicenseRef-Mnemo-Pro
-/**
- * Access Tracker
- *
- * Tracks memory access patterns to support reinforcement-based decay.
- * Frequently accessed memories decay more slowly (longer effective half-life).
- *
- * Key exports:
- * - parseAccessMetadata   — extract accessCount/lastAccessedAt from metadata JSON
- * - buildUpdatedMetadata  — merge access fields into existing metadata JSON
- * - computeEffectiveHalfLife — compute reinforced half-life from access history
- * - AccessTracker         — debounced write-back tracker for batch metadata updates
- */
-
-import type { MemoryStore } from "./store.js";
-
-// ============================================================================
-// Types
-// ============================================================================
-
-export interface AccessMetadata {
-  readonly accessCount: number;
-  readonly lastAccessedAt: number;
-}
-
-export interface AccessTrackerOptions {
-  readonly store: MemoryStore;
-  readonly logger: {
-    warn: (...args: unknown[]) => void;
-    info?: (...args: unknown[]) => void;
-  };
-  readonly debounceMs?: number;
-}
-
-// ============================================================================
-// Constants
-// ============================================================================
-
-const MIN_ACCESS_COUNT = 0;
-const MAX_ACCESS_COUNT = 10_000;
-
-/** Access count itself decays with a 30-day half-life */
-const ACCESS_DECAY_HALF_LIFE_DAYS = 30;
-
-// ============================================================================
-// Utility
-// ============================================================================
-
-function clampAccessCount(value: number): number {
-  if (!Number.isFinite(value)) return MIN_ACCESS_COUNT;
-  return Math.min(
-    MAX_ACCESS_COUNT,
-    Math.max(MIN_ACCESS_COUNT, Math.floor(value)),
-  );
-}
-
-// ============================================================================
-// Metadata Parsing
-// ============================================================================
-
-/**
- * Parse access-related fields from a metadata JSON string.
- *
- * Handles: undefined, empty string, malformed JSON, negative numbers,
- * numbers exceeding 10000. Always returns a valid AccessMetadata.
- */
-export function parseAccessMetadata(
-  metadata: string | undefined,
-): AccessMetadata {
-  if (metadata === undefined || metadata === "") {
-    return { accessCount: 0, lastAccessedAt: 0 };
-  }
-
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(metadata);
-  } catch {
-    return { accessCount: 0, lastAccessedAt: 0 };
-  }
-
-  if (typeof parsed !== "object" || parsed === null) {
-    return { accessCount: 0, lastAccessedAt: 0 };
-  }
-
-  const obj = parsed as Record<string, unknown>;
-
-  // Support both camelCase and snake_case keys (beta smart-memory uses snake_case).
-  const rawCountAny = obj.accessCount ?? obj.access_count;
-  const rawCount =
-    typeof rawCountAny === "number" ? rawCountAny : Number(rawCountAny ?? 0);
-
-  const rawLastAny = obj.lastAccessedAt ?? obj.last_accessed_at;
-  const rawLastAccessed =
-    typeof rawLastAny === "number" ? rawLastAny : Number(rawLastAny ?? 0);
-
-  return {
-    accessCount: clampAccessCount(rawCount),
-    lastAccessedAt:
-      Number.isFinite(rawLastAccessed) && rawLastAccessed >= 0
-        ? rawLastAccessed
-        : 0,
-  };
-}
-
-// ============================================================================
-// Metadata Building
-// ============================================================================
-
-/**
- * Merge an access-count increment into existing metadata JSON.
- *
- * Preserves ALL existing fields in the metadata object — only overwrites
- * `accessCount` and `lastAccessedAt`. Returns a new JSON string.
- */
-export function buildUpdatedMetadata(
-  existingMetadata: string | undefined,
-  accessDelta: number,
-): string {
-  let existing: Record<string, unknown> = {};
-
-  if (existingMetadata !== undefined && existingMetadata !== "") {
-    try {
-      const parsed = JSON.parse(existingMetadata);
-      if (typeof parsed === "object" && parsed !== null) {
-        existing = { ...parsed };
-      }
-    } catch {
-      // malformed JSON — start fresh but preserve nothing
-    }
-  }
-
-  const prev = parseAccessMetadata(existingMetadata);
-  const newCount = clampAccessCount(prev.accessCount + accessDelta);
-
-  const now = Date.now();
-
-  return JSON.stringify({
-    ...existing,
-    // Write both camelCase and snake_case for compatibility.
-    accessCount: newCount,
-    lastAccessedAt: now,
-    access_count: newCount,
-    last_accessed_at: now,
-  });
-}
-
-// ============================================================================
-// Effective Half-Life Computation
-// ============================================================================
-
-/**
- * Compute the effective half-life for a memory based on its access history.
- *
- * The access count itself decays over time (30-day half-life for access
- * freshness), so stale accesses contribute less reinforcement. The extension
- * uses a logarithmic curve (`Math.log1p`) to provide diminishing returns.
- *
- * @param baseHalfLife        - Base half-life in days (e.g. 30)
- * @param accessCount         - Raw number of times the memory was accessed
- * @param lastAccessedAt      - Timestamp (ms) of last access
- * @param reinforcementFactor - Scaling factor for reinforcement (0 = disabled)
- * @param maxMultiplier       - Hard cap: result <= baseHalfLife * maxMultiplier
- * @returns Effective half-life in days
- */
-export function computeEffectiveHalfLife(
-  baseHalfLife: number,
-  accessCount: number,
-  lastAccessedAt: number,
-  reinforcementFactor: number,
-  maxMultiplier: number,
-): number {
-  // Short-circuit: no reinforcement or no accesses
-  if (reinforcementFactor === 0 || accessCount <= 0) {
-    return baseHalfLife;
-  }
-
-  const now = Date.now();
-  const daysSinceLastAccess = Math.max(
-    0,
-    (now - lastAccessedAt) / (1000 * 60 * 60 * 24),
-  );
-
-  // Access freshness decays exponentially with 30-day half-life
-  const accessFreshness = Math.exp(
-    -daysSinceLastAccess * (Math.LN2 / ACCESS_DECAY_HALF_LIFE_DAYS),
-  );
-
-  // Effective access count after freshness decay
-  const effectiveAccessCount = accessCount * accessFreshness;
-
-  // Logarithmic extension for diminishing returns
-  const extension =
-    baseHalfLife * reinforcementFactor * Math.log1p(effectiveAccessCount);
-
-  const result = baseHalfLife + extension;
-
-  // Hard cap
-  const cap = baseHalfLife * maxMultiplier;
-  return Math.min(result, cap);
-}
-
-// ============================================================================
-// AccessTracker Class
-// ============================================================================
-
-/**
- * Debounced write-back tracker for memory access events.
- *
- * `recordAccess()` is synchronous (Map update only, no I/O). Pending deltas
- * accumulate until `flush()` is called (or by a future scheduled callback).
- * On flush, each pending entry is read via `store.getById()`, its metadata
- * is merged with the accumulated access delta, and written back via
- * `store.update()`.
- */
-export class AccessTracker {
-  private readonly pending: Map<string, number> = new Map();
-  private debounceTimer: ReturnType<typeof setTimeout> | null = null;
-  private flushPromise: Promise<void> | null = null;
-  private readonly debounceMs: number;
-  private readonly store: MemoryStore;
-  private readonly logger: {
-    warn: (...args: unknown[]) => void;
-    info?: (...args: unknown[]) => void;
-  };
-
-  constructor(options: AccessTrackerOptions) {
-    this.store = options.store;
-    this.logger = options.logger;
-    this.debounceMs = options.debounceMs ?? 5_000;
-  }
-
-  /**
-   * Record one access for each of the given memory IDs.
-   * Synchronous — only updates the in-memory pending map.
-   */
-  recordAccess(ids: readonly string[]): void {
-    for (const id of ids) {
-      const current = this.pending.get(id) ?? 0;
-      this.pending.set(id, current + 1);
-    }
-
-    // Reset debounce timer
-    this.resetTimer();
-  }
-
-  /**
-   * Return a snapshot of all pending (id -> delta) entries.
-   */
-  getPendingUpdates(): Map<string, number> {
-    return new Map(this.pending);
-  }
-
-  /**
-   * Flush pending access deltas to the store.
-   *
-   * If a flush is already in progress, awaits the current flush to complete.
-   * If new pending data accumulated during the in-flight flush, a follow-up
-   * flush is automatically triggered.
-   */
-  async flush(): Promise<void> {
-    this.clearTimer();
-
-    // If a flush is in progress, wait for it to finish
-    if (this.flushPromise) {
-      await this.flushPromise;
-      // After the in-flight flush completes, check if new data accumulated
-      if (this.pending.size > 0) {
-        return this.flush();
-      }
-      return;
-    }
-
-    if (this.pending.size === 0) return;
-
-    this.flushPromise = this.doFlush();
-    try {
-      await this.flushPromise;
-    } finally {
-      this.flushPromise = null;
-    }
-
-    // If new data accumulated during flush, schedule a follow-up
-    if (this.pending.size > 0) {
-      this.resetTimer();
-    }
-  }
-
-  /**
-   * Tear down the tracker — cancel timers and clear pending state.
-   */
-  destroy(): void {
-    this.clearTimer();
-    if (this.pending.size > 0) {
-      this.logger.warn(
-        `access-tracker: destroying with ${this.pending.size} pending writes`,
-      );
-    }
-    this.pending.clear();
-  }
-
-  // --------------------------------------------------------------------------
-  // Internal helpers
-  // --------------------------------------------------------------------------
-
-  private async doFlush(): Promise<void> {
-    const batch = new Map(this.pending);
-    this.pending.clear();
-
-    for (const [id, delta] of batch) {
-      try {
-        const current = await this.store.getById(id);
-        if (!current) continue;
-
-        const updatedMeta = buildUpdatedMetadata(current.metadata, delta);
-        await this.store.update(id, { metadata: updatedMeta });
-      } catch (err) {
-        // Requeue failed delta for retry on next flush
-        const existing = this.pending.get(id) ?? 0;
-        this.pending.set(id, existing + delta);
-        this.logger.warn(
-          `access-tracker: write-back failed for ${id.slice(0, 8)}:`,
-          err,
-        );
-      }
-    }
-  }
-
-  private resetTimer(): void {
-    this.clearTimer();
-    this.debounceTimer = setTimeout(() => {
-      void this.flush();
-    }, this.debounceMs);
-  }
-
-  private clearTimer(): void {
-    if (this.debounceTimer !== null) {
-      clearTimeout(this.debounceTimer);
-      this.debounceTimer = null;
-    }
-  }
-}

package/src/adapters/README.md

@@ -1,78 +0,0 @@
-# Storage Adapters
-
-Mnemo supports pluggable storage backends via the `StorageAdapter` interface.
-
-## Available Adapters
-
-| Adapter | Status | BM25/FTS | Install | Best For |
-|---------|--------|----------|---------|----------|
-| **LanceDB** | Stable (default) | Built-in | — | Embedded, edge, single-node |
-| **Qdrant** | Stable | No (vector only) | `npm i @qdrant/js-client-rest` | High-perf filtering, Rust speed |
-| **Chroma** | Stable | Yes (queryTexts) | `npm i chromadb` | Prototyping, Python ecosystem |
-| **PGVector** | Stable | Yes (pg tsvector) | `npm i pg pgvector` | Existing Postgres, full SQL |
-| Weaviate | Planned | — | — | Hybrid search, GraphQL |
-| Milvus | Planned | — | — | Billion-scale, GPU |
-| Pinecone | Planned | — | — | Fully managed SaaS |
-| SQLite-vec | Planned | — | — | Ultra-lightweight, edge |
-
-## Quick Start
-
-```typescript
-import { createMnemo } from '@mnemo/core';
-
-// Default — LanceDB (embedded, zero config)
-const mnemo = await createMnemo({ storage: 'lancedb' });
-
-// Qdrant (self-hosted or Qdrant Cloud)
-const mnemo = await createMnemo({
-  storage: 'qdrant',
-  storageConfig: { url: 'http://localhost:6333' },
-});
-
-// Chroma (embedded or server mode)
-const mnemo = await createMnemo({
-  storage: 'chroma',
-  storageConfig: { url: 'http://localhost:8000' },
-});
-
-// PGVector (existing PostgreSQL)
-const mnemo = await createMnemo({
-  storage: 'pgvector',
-  storageConfig: { connectionString: 'postgres://user:pass@localhost:5432/mnemo' },
-});
-```
-
-## Choosing a Backend
-
-| Scenario | Recommended |
-|----------|-------------|
-| Getting started / prototyping | **LanceDB** (zero setup) |
-| Already running PostgreSQL | **PGVector** (no extra service) |
-| Need fastest vector search | **Qdrant** (Rust, HNSW) |
-| Python-heavy stack | **Chroma** (pip install) |
-| Need BM25 + vector | **LanceDB** or **PGVector** |
-| Air-gapped / edge deployment | **LanceDB** (embedded) |
-
-## Creating a Custom Adapter
-
-Implement the `StorageAdapter` interface and register it:
-
-```typescript
-import { StorageAdapter, registerAdapter } from '@mnemo/core/storage-adapter';
-
-class MyAdapter implements StorageAdapter {
-  readonly name = 'my-backend';
-  async connect(dbPath: string) { /* ... */ }
-  async ensureTable(dim: number) { /* ... */ }
-  async add(records: MemoryRecord[]) { /* ... */ }
-  async vectorSearch(vector, limit, minScore, scopeFilter) { /* ... */ }
-  async fullTextSearch(query, limit, scopeFilter) { /* ... */ }
-  // ... implement all methods from StorageAdapter
-}
-
-registerAdapter('my-backend', () => new MyAdapter());
-```
-
-## Interface Reference
-
-See `storage-adapter.ts` for the full `StorageAdapter` interface with JSDoc.

package/src/adapters/qdrant.ts

@@ -1,191 +0,0 @@
-// SPDX-License-Identifier: MIT
-/**
- * Qdrant Storage Adapter for Mnemo
- *
- * Requirements:
- *   npm install @qdrant/js-client-rest
- *
- * Config:
- *   storage: "qdrant"
- *   storageConfig: { url: "http://localhost:6333", apiKey?: "..." }
- */
-
-import type {
-  StorageAdapter,
-  MemoryRecord,
-  SearchResult,
-  QueryOptions,
-} from "../storage-adapter.js";
-import { registerAdapter } from "../storage-adapter.js";
-
-const COLLECTION = "mnemo_memories";
-
-export class QdrantAdapter implements StorageAdapter {
-  readonly name = "qdrant";
-
-  private client: any = null;
-  private url: string = "http://localhost:6333";
-  private apiKey?: string;
-  private vectorDim = 0;
-
-  constructor(config?: Record<string, unknown>) {
-    if (config?.url) this.url = config.url as string;
-    if (config?.apiKey) this.apiKey = config.apiKey as string;
-  }
-
-  async connect(): Promise<void> {
-    const { QdrantClient } = await import("@qdrant/js-client-rest");
-    this.client = new QdrantClient({
-      url: this.url,
-      ...(this.apiKey ? { apiKey: this.apiKey } : {}),
-    });
-  }
-
-  async ensureTable(vectorDimensions: number): Promise<void> {
-    this.vectorDim = vectorDimensions;
-    const collections = await this.client.getCollections();
-    const exists = collections.collections.some((c: any) => c.name === COLLECTION);
-
-    if (!exists) {
-      await this.client.createCollection(COLLECTION, {
-        vectors: { size: vectorDimensions, distance: "Cosine" },
-      });
-      // Create payload indices for filtering
-      await this.client.createPayloadIndex(COLLECTION, {
-        field_name: "scope",
-        field_schema: "keyword",
-      });
-      await this.client.createPayloadIndex(COLLECTION, {
-        field_name: "category",
-        field_schema: "keyword",
-      });
-    }
-  }
-
-  async add(records: MemoryRecord[]): Promise<void> {
-    const points = records.map((r) => ({
-      id: r.id,
-      vector: r.vector,
-      payload: {
-        text: r.text,
-        timestamp: r.timestamp,
-        scope: r.scope,
-        importance: r.importance,
-        category: r.category,
-        metadata: r.metadata,
-      },
-    }));
-    await this.client.upsert(COLLECTION, { points });
-  }
-
-  async update(id: string, record: MemoryRecord): Promise<void> {
-    await this.add([record]);
-  }
-
-  async delete(filter: string): Promise<void> {
-    // Parse simple "id = 'xxx'" filter
-    const idMatch = filter.match(/id\s*=\s*'([^']+)'/);
-    if (idMatch) {
-      await this.client.delete(COLLECTION, {
-        points: [idMatch[1]],
-      });
-    }
-  }
-
-  async vectorSearch(
-    vector: number[],
-    limit: number,
-    minScore = 0,
-    scopeFilter?: string[],
-  ): Promise<SearchResult[]> {
-    const filter = scopeFilter?.length
-      ? { must: [{ key: "scope", match: { any: scopeFilter } }] }
-      : undefined;
-
-    const results = await this.client.search(COLLECTION, {
-      vector,
-      limit,
-      with_payload: true,
-      score_threshold: minScore,
-      ...(filter ? { filter } : {}),
-    });
-
-    return results.map((r: any) => ({
-      record: this.toRecord(r.id, r.payload),
-      score: r.score,
-    }));
-  }
-
-  async fullTextSearch(
-    _query: string,
-    _limit: number,
-    _scopeFilter?: string[],
-  ): Promise<SearchResult[]> {
-    // Qdrant doesn't have native BM25 — fall back to empty
-    // Users should pair with a separate FTS engine or use vector search
-    return [];
-  }
-
-  async query(options: QueryOptions): Promise<MemoryRecord[]> {
-    const filter = options.where
-      ? this.parseFilter(options.where)
-      : undefined;
-
-    const result = await this.client.scroll(COLLECTION, {
-      limit: options.limit || 100,
-      with_payload: true,
-      with_vectors: true,
-      ...(filter ? { filter } : {}),
-    });
-
-    return result.points.map((p: any) => this.toRecord(p.id, p.payload, p.vector));
-  }
-
-  async count(filter?: string): Promise<number> {
-    const result = await this.client.count(COLLECTION, {
-      ...(filter ? { filter: this.parseFilter(filter) } : {}),
-      exact: true,
-    });
-    return result.count;
-  }
-
-  async ensureFullTextIndex(): Promise<void> {
-    // Qdrant uses payload indices, not FTS indices
-    // Text search via Qdrant requires external FTS or payload keyword match
-  }
-
-  hasFullTextSearch(): boolean {
-    return false; // Qdrant doesn't have native BM25
-  }
-
-  async close(): Promise<void> {
-    this.client = null;
-  }
-
-  // ── Helpers ──
-
-  private toRecord(id: string, payload: any, vector?: number[]): MemoryRecord {
-    return {
-      id,
-      text: payload.text ?? "",
-      vector: vector ? Array.from(vector) : [],
-      timestamp: payload.timestamp ?? 0,
-      scope: payload.scope ?? "global",
-      importance: payload.importance ?? 0.5,
-      category: payload.category ?? "other",
-      metadata: payload.metadata ?? "{}",
-    };
-  }
-
-  private parseFilter(where: string): any {
-    // Simple parser for common filters
-    const scopeMatch = where.match(/scope\s+IN\s*\(([^)]+)\)/i);
-    if (scopeMatch) {
-      const scopes = scopeMatch[1].split(",").map((s) => s.trim().replace(/'/g, ""));
-      return { must: [{ key: "scope", match: { any: scopes } }] };
-    }
-    return undefined;
-  }
-}
-
-registerAdapter("qdrant", (config) => new QdrantAdapter(config));

package/src/adaptive-retrieval.ts

@@ -1,90 +0,0 @@
-// SPDX-License-Identifier: MIT
-/**
- * Adaptive Retrieval
- * Determines whether a query needs memory retrieval at all.
- * Skips retrieval for greetings, commands, simple instructions, and system messages.
- * Saves embedding API calls and reduces noise injection.
- */
-
-// Queries that are clearly NOT memory-retrieval candidates
-const SKIP_PATTERNS = [
-  // Greetings & pleasantries
-  /^(hi|hello|hey|good\s*(morning|afternoon|evening|night)|greetings|yo|sup|howdy|what'?s up)\b/i,
-  // System/bot commands
-  /^\//,  // slash commands
-  /^(run|build|test|ls|cd|git|npm|pip|docker|curl|cat|grep|find|make|sudo)\b/i,
-  // Simple affirmations/negations
-  /^(yes|no|yep|nope|ok|okay|sure|fine|thanks|thank you|thx|ty|got it|understood|cool|nice|great|good|perfect|awesome)\s*[.!]?$/i,
-  // Continuation prompts
-  /^(go ahead|continue|proceed|do it|start|begin|next)\s*[.!]?$/i,
-  // Pure emoji
-  /^[\p{Emoji}\s]+$/u,
-  // Heartbeat/system (match anywhere, not just at start, to handle prefixed formats)
-  /HEARTBEAT/i,
-  /^\[System/i,
-  // Single-word utility pings
-  /^(ping|pong|test|debug)\s*[.!?]?$/i,
-];
-
-// Queries that SHOULD trigger retrieval even if short
-const FORCE_RETRIEVE_PATTERNS = [
-  /\b(remember|recall|forgot|memory|memories)\b/i,
-  /\b(last time|before|previously|earlier|yesterday|ago)\b/i,
-  /\b(my (name|email|phone|address|birthday|preference))\b/i,
-  /\b(what did (i|we)|did i (tell|say|mention))\b/i,
-];
-
-/**
- * Normalize the raw prompt before applying skip/force rules.
- */
-function normalizeQuery(query: string): string {
-  let s = query.trim();
-
-  // 1. Strip injected metadata headers.
-  const metadataPattern = /^(Conversation info|Sender) \(untrusted metadata\):[\s\S]*?\n\s*\n/gim;
-  s = s.replace(metadataPattern, "");
-
-  // 2. Strip cron wrapper prefix.
-  s = s.trim().replace(/^\[cron:[^\]]+\]\s*/i, "");
-
-  // 3. Strip timestamp prefix [Mon 2026-03-02 04:21 GMT+8].
-  s = s.trim().replace(/^\[[A-Za-z]{3}\s\d{4}-\d{2}-\d{2}\s\d{2}:\d{2}\s[^\]]+\]\s*/, "");
-
-  const result = s.trim();
-  return result;
-}
-
-/**
- * Determine if a query should skip memory retrieval.
- * Returns true if retrieval should be skipped.
- * @param query The raw prompt text
- * @param minLength Optional minimum length override (if set, overrides built-in thresholds)
- */
-export function shouldSkipRetrieval(query: string, minLength?: number): boolean {
-  const trimmed = normalizeQuery(query);
-
-  // Force retrieve if query has memory-related intent (checked FIRST,
-  // before length check, so short CJK queries aren't skipped)
-  if (FORCE_RETRIEVE_PATTERNS.some(p => p.test(trimmed))) return false;
-
-  // Too short to be meaningful
-  if (trimmed.length < 5) return true;
-
-  // Skip if matches any skip pattern
-  if (SKIP_PATTERNS.some(p => p.test(trimmed))) return true;
-
-  // If caller provides a custom minimum length, use it
-  if (minLength !== undefined && minLength > 0) {
-    if (trimmed.length < minLength && !trimmed.includes('?')) return true;
-    return false;
-  }
-
-  // Skip very short non-question messages (likely commands or affirmations)
-  // CJK characters carry more meaning per character, so use a lower threshold
-  const hasCJK = /[\u4e00-\u9fff\u3040-\u309f\u30a0-\u30ff\uac00-\ud7af]/.test(trimmed);
-  const defaultMinLength = hasCJK ? 6 : 15;
-  if (trimmed.length < defaultMinLength && !trimmed.includes('?')) return true;
-
-  // Default: do retrieve
-  return false;
-}