@mnemoai/core 1.1.0

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@mnemoai/core",
+  "version": "1.1.0",
+  "description": "Cognitive science-based AI memory framework — Weibull decay, triple-path retrieval, multi-backend storage",
+  "type": "module",
+  "main": "index.ts",
+  "keywords": [
+    "ai-memory",
+    "long-term-memory",
+    "vector-search",
+    "bm25",
+    "knowledge-graph",
+    "hybrid-retrieval",
+    "rerank",
+    "weibull-decay",
+    "cognitive-science",
+    "rag",
+    "agent-memory",
+    "lancedb",
+    "qdrant",
+    "chroma",
+    "pgvector"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Methux/mnemo.git"
+  },
+  "homepage": "https://m-nemo.ai",
+  "bugs": {
+    "url": "https://github.com/Methux/mnemo/issues"
+  },
+  "author": "Mnemo Contributors",
+  "license": "MIT",
+  "dependencies": {
+    "@lancedb/lancedb": "^0.26.2",
+    "@sinclair/typebox": "0.34.48",
+    "openai": "^6.21.0"
+  },
+  "optionalDependencies": {
+    "@qdrant/js-client-rest": "^1.12.0",
+    "chromadb": "^1.9.0",
+    "pg": "^8.13.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "test:openclaw-host": "node test/openclaw-host-functional.mjs",
+    "version": "node scripts/sync-plugin-version.mjs openclaw.plugin.json package.json && git add openclaw.plugin.json"
+  },
+  "devDependencies": {
+    "commander": "^14.0.0",
+    "jiti": "^2.6.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/access-tracker.ts

@@ -0,0 +1,341 @@
+// 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

@@ -0,0 +1,78 @@
+# 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/chroma.ts

@@ -0,0 +1,206 @@
+// SPDX-License-Identifier: MIT
+/**
+ * Chroma Storage Adapter for Mnemo
+ *
+ * Requirements:
+ *   npm install chromadb
+ *
+ * Config:
+ *   storage: "chroma"
+ *   storageConfig: { url: "http://localhost:8000" } or { path: "./chroma-data" }
+ */
+
+import type {
+  StorageAdapter,
+  MemoryRecord,
+  SearchResult,
+  QueryOptions,
+} from "../storage-adapter.js";
+import { registerAdapter } from "../storage-adapter.js";
+
+const COLLECTION = "mnemo_memories";
+
+export class ChromaAdapter implements StorageAdapter {
+  readonly name = "chroma";
+
+  private client: any = null;
+  private collection: any = null;
+  private config: Record<string, unknown>;
+
+  constructor(config?: Record<string, unknown>) {
+    this.config = config || {};
+  }
+
+  async connect(dbPath: string): Promise<void> {
+    const chroma = await import("chromadb");
+
+    if (this.config.url) {
+      // Remote Chroma server
+      this.client = new chroma.ChromaClient({ path: this.config.url as string });
+    } else {
+      // Persistent local (Chroma supports persistent storage)
+      this.client = new chroma.ChromaClient({ path: dbPath || this.config.path as string });
+    }
+  }
+
+  async ensureTable(vectorDimensions: number): Promise<void> {
+    this.collection = await this.client.getOrCreateCollection({
+      name: COLLECTION,
+      metadata: { "hnsw:space": "cosine" },
+    });
+  }
+
+  async add(records: MemoryRecord[]): Promise<void> {
+    if (!this.collection) throw new Error("Collection not initialized");
+
+    await this.collection.upsert({
+      ids: records.map((r) => r.id),
+      embeddings: records.map((r) => r.vector),
+      documents: records.map((r) => r.text),
+      metadatas: records.map((r) => ({
+        timestamp: r.timestamp,
+        scope: r.scope,
+        importance: r.importance,
+        category: r.category,
+        metadata: r.metadata,
+      })),
+    });
+  }
+
+  async update(id: string, record: MemoryRecord): Promise<void> {
+    await this.add([record]);
+  }
+
+  async delete(filter: string): Promise<void> {
+    if (!this.collection) throw new Error("Collection not initialized");
+
+    const idMatch = filter.match(/id\s*=\s*'([^']+)'/);
+    if (idMatch) {
+      await this.collection.delete({ ids: [idMatch[1]] });
+    }
+  }
+
+  async vectorSearch(
+    vector: number[],
+    limit: number,
+    minScore = 0,
+    scopeFilter?: string[],
+  ): Promise<SearchResult[]> {
+    if (!this.collection) throw new Error("Collection not initialized");
+
+    const where = scopeFilter?.length
+      ? { scope: { $in: scopeFilter } }
+      : undefined;
+
+    const results = await this.collection.query({
+      queryEmbeddings: [vector],
+      nResults: limit,
+      ...(where ? { where } : {}),
+    });
+
+    if (!results.ids?.[0]) return [];
+
+    return results.ids[0].map((id: string, i: number) => {
+      // Chroma returns distances, convert to similarity
+      const distance = results.distances?.[0]?.[i] ?? 1;
+      const score = 1 - distance; // cosine distance → similarity
+      const meta = results.metadatas?.[0]?.[i] || {};
+
+      return {
+        record: {
+          id,
+          text: results.documents?.[0]?.[i] ?? "",
+          vector: [], // Chroma doesn't return vectors by default
+          timestamp: meta.timestamp ?? 0,
+          scope: meta.scope ?? "global",
+          importance: meta.importance ?? 0.5,
+          category: meta.category ?? "other",
+          metadata: meta.metadata ?? "{}",
+        },
+        score,
+      };
+    }).filter((r: SearchResult) => r.score >= minScore);
+  }
+
+  async fullTextSearch(
+    query: string,
+    limit: number,
+    scopeFilter?: string[],
+  ): Promise<SearchResult[]> {
+    if (!this.collection) return [];
+
+    const where = scopeFilter?.length
+      ? { scope: { $in: scopeFilter } }
+      : undefined;
+
+    // Chroma supports document search via where_document
+    const results = await this.collection.query({
+      queryTexts: [query],
+      nResults: limit,
+      ...(where ? { where } : {}),
+    });
+
+    if (!results.ids?.[0]) return [];
+
+    return results.ids[0].map((id: string, i: number) => {
+      const distance = results.distances?.[0]?.[i] ?? 1;
+      const meta = results.metadatas?.[0]?.[i] || {};
+      return {
+        record: {
+          id,
+          text: results.documents?.[0]?.[i] ?? "",
+          vector: [],
+          timestamp: meta.timestamp ?? 0,
+          scope: meta.scope ?? "global",
+          importance: meta.importance ?? 0.5,
+          category: meta.category ?? "other",
+          metadata: meta.metadata ?? "{}",
+        },
+        score: 1 - distance,
+      };
+    });
+  }
+
+  async query(options: QueryOptions): Promise<MemoryRecord[]> {
+    if (!this.collection) throw new Error("Collection not initialized");
+
+    const result = await this.collection.get({
+      limit: options.limit || 100,
+      include: ["documents", "metadatas", "embeddings"],
+    });
+
+    return (result.ids || []).map((id: string, i: number) => {
+      const meta = result.metadatas?.[i] || {};
+      return {
+        id,
+        text: result.documents?.[i] ?? "",
+        vector: result.embeddings?.[i] ?? [],
+        timestamp: meta.timestamp ?? 0,
+        scope: meta.scope ?? "global",
+        importance: meta.importance ?? 0.5,
+        category: meta.category ?? "other",
+        metadata: meta.metadata ?? "{}",
+      };
+    });
+  }
+
+  async count(): Promise<number> {
+    if (!this.collection) return 0;
+    return await this.collection.count();
+  }
+
+  async ensureFullTextIndex(): Promise<void> {
+    // Chroma handles text search natively via queryTexts
+  }
+
+  hasFullTextSearch(): boolean {
+    return true; // Chroma supports document-level text search
+  }
+
+  async close(): Promise<void> {
+    this.collection = null;
+    this.client = null;
+  }
+}
+
+registerAdapter("chroma", (config) => new ChromaAdapter(config));