@mnemoai/core 1.1.3 → 1.1.5

package/README.md

@@ -41,7 +41,7 @@ The result: your AI agent's memory stays relevant instead of drowning in noise.
 
 ## Mnemo vs Paid Competitors
 
-| Capability | Mem0 $249 | Zep $199 | Letta $49 | Cognee $149 | **Mnemo Core** FREE | **Mnemo Pro** $69 |
+| Capability | Mem0 $249 | Zep (usage) | Letta $20 | Cognee OSS | **Mnemo Core** FREE | **Mnemo Pro** $69 |
 |:---|:---:|:---:|:---:|:---:|:---:|:---:|
 | Vector search | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | BM25 keyword search | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |
@@ -141,10 +141,9 @@ import { createMnemo } from '@mnemoai/core';
 const mnemo = await createMnemo({
   embedding: {
     provider: 'openai-compatible',
-    apiKey: process.env.VOYAGE_API_KEY,
-    baseURL: 'https://api.voyageai.com/v1',
-    model: 'voyage-3-large',
-    dimensions: 1024,
+    apiKey: process.env.OPENAI_API_KEY,  // or 'ollama' for local
+    model: 'text-embedding-3-small',
+    dimensions: 1536,
   },
   dbPath: './memory-db',
 });

package/dist/index.d.ts

@@ -2,7 +2,14 @@
  * Mnemo Memory Plugin
  * Cognitive memory framework with hybrid retrieval, multi-scope isolation, and management CLI
  */
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+interface OpenClawPluginApi {
+    pluginConfig: unknown;
+    registerMemoryProvider(provider: any): void;
+    registerHook(event: string, handler: (...args: any[]) => any): void;
+    registerCommand?(cmd: any): void;
+    getWorkspacePath?(): string;
+    [key: string]: any;
+}
 declare const memoryLanceDBProPlugin: {
     id: string;
     name: string;
@@ -12,7 +19,7 @@ declare const memoryLanceDBProPlugin: {
 };
 export default memoryLanceDBProPlugin;
 export { createMnemo } from "./src/mnemo.js";
-export type { MnemoConfig, MnemoInstance } from "./src/mnemo.js";
+export type { MnemoConfig, MnemoInstance, MemoryCategory, StorageBackend } from "./src/mnemo.js";
 export { MemoryStore } from "./src/store.js";
 export type { MemoryEntry, MemorySearchResult, StoreConfig } from "./src/store.js";
 export type { StorageAdapter } from "./src/storage-adapter.js";

package/dist/src/mnemo.d.ts

@@ -2,59 +2,95 @@
  * Mnemo Core — simplified entry point
  * Usage: const mnemo = await createMnemo(config)
  */
+/** Memory category — controls how memories are classified and retrieved. */
+export type MemoryCategory = "preference" | "fact" | "decision" | "entity" | "other" | "reflection";
+/** Supported storage backends. LanceDB is the default (embedded, zero-config). */
+export type StorageBackend = "lancedb" | "qdrant" | "chroma" | "pgvector";
 export interface MnemoConfig {
+    /** Embedding provider configuration. */
     embedding: {
+        /** Currently only "openai-compatible" is supported (works with OpenAI, Ollama, Voyage, etc.) */
         provider: "openai-compatible";
+        /** API key for the embedding provider. Use "ollama" for local Ollama. */
         apiKey: string;
+        /** Base URL for the embedding API. Default: OpenAI. Use "http://localhost:11434/v1" for Ollama. */
         baseURL?: string;
+        /** Embedding model name. Default: "text-embedding-3-small". */
         model?: string;
+        /** Embedding vector dimensions. Default: 1024. */
         dimensions?: number;
+        /** Task prefix for query embeddings (provider-specific). */
         taskQuery?: string;
+        /** Task prefix for passage embeddings (provider-specific). */
         taskPassage?: string;
     };
+    /** Path to the local database directory. */
     dbPath: string;
+    /** Weibull decay model configuration. */
     decay?: {
+        /** Half-life in days for the recency decay curve. Default: 30. */
         recencyHalfLifeDays?: number;
+        /** Weight of recency in the composite score. Default: 0.5. */
         recencyWeight?: number;
+        /** Weight of access frequency in the composite score. Default: 0.3. */
         frequencyWeight?: number;
+        /** Weight of intrinsic importance in the composite score. Default: 0.2. */
         intrinsicWeight?: number;
     };
+    /** Memory tier promotion thresholds. */
     tier?: {
         coreAccessThreshold?: number;
         coreImportanceThreshold?: number;
         peripheralAgeDays?: number;
     };
+    /** LLM configuration for smart extraction and contradiction detection. */
     llm?: {
         model?: string;
         baseURL?: string;
         apiKey?: string;
     };
+    /** Retrieval pipeline configuration. */
     retrieval?: {
+        /** Number of candidates before reranking. Default: 20. */
         candidatePoolSize?: number;
+        /** Reranking strategy. Default: "none". */
         rerank?: "cross-encoder" | "lightweight" | "none";
+        /** API key for the reranker provider. */
         rerankApiKey?: string;
+        /** Reranker model name. */
         rerankModel?: string;
+        /** Reranker API endpoint. */
         rerankEndpoint?: string;
+        /** Reranker provider. */
         rerankProvider?: string;
     };
-    /** Storage backend: "lancedb" (default), "qdrant", "chroma", "pgvector" */
-    storageBackend?: string;
-    /** Backend-specific config (url, connectionString, etc.) */
+    /** Storage backend. Default: "lancedb" (embedded, zero-config). */
+    storageBackend?: StorageBackend;
+    /** Backend-specific config (e.g., { url: "http://localhost:6333" } for Qdrant). */
     storageConfig?: Record<string, unknown>;
 }
 export interface MnemoInstance {
+    /** Store a memory. Returns the generated memory ID. */
     store(entry: {
+        /** The text content to remember. */
         text: string;
-        category?: string;
+        /** Memory category. Default: "fact". */
+        category?: MemoryCategory;
+        /** Importance score from 0.0 to 1.0. Default: 0.7. */
         importance?: number;
+        /** Scope for multi-agent isolation. Default: "global". */
         scope?: string;
     }): Promise<{
         id: string;
     }>;
+    /** Recall memories by semantic search. Returns ranked results with scores. */
     recall(query: string, options?: {
+        /** Maximum number of results. Default: 5. */
         limit?: number;
+        /** Only return memories from these scopes. */
         scopeFilter?: string[];
-        category?: string;
+        /** Only return memories of this category. */
+        category?: MemoryCategory;
     }): Promise<Array<{
         text: string;
         score: number;
@@ -62,12 +98,34 @@ export interface MnemoInstance {
         importance: number;
         timestamp: number;
     }>>;
+    /** Delete a memory by ID. Returns true if deleted, false if not found. */
     delete(id: string): Promise<boolean>;
+    /** Get memory store statistics. */
     stats(): Promise<{
         totalEntries: number;
         scopeCounts: Record<string, number>;
         categoryCounts: Record<string, number>;
     }>;
+    /** Close the instance and release resources. */
     close(): Promise<void>;
 }
+/**
+ * Create a Mnemo memory instance.
+ *
+ * @example
+ * ```typescript
+ * const mnemo = await createMnemo({
+ *   embedding: {
+ *     provider: "openai-compatible",
+ *     apiKey: process.env.OPENAI_API_KEY,
+ *     model: "text-embedding-3-small",
+ *     dimensions: 1536,
+ *   },
+ *   dbPath: "./my-memory-db",
+ * });
+ *
+ * await mnemo.store({ text: "User prefers dark mode", category: "preference" });
+ * const results = await mnemo.recall("UI preferences");
+ * ```
+ */
 export declare function createMnemo(config: MnemoConfig): Promise<MnemoInstance>;

package/dist/src/mnemo.js

@@ -3,10 +3,10 @@ import { createRetriever, DEFAULT_RETRIEVAL_CONFIG } from "./retriever.js";
 import { Embedder } from "./embedder.js";
 import { createDecayEngine, DEFAULT_DECAY_CONFIG } from "./decay-engine.js";
 async function createMnemo(config) {
-  if (!config) throw new Error("mnemo: config is required");
+  if (!config) throw new Error("mnemo: config is required \u2014 see https://github.com/Methux/mnemo#quick-start");
   if (!config.embedding) throw new Error("mnemo: config.embedding is required");
-  if (!config.embedding.apiKey) throw new Error("mnemo: config.embedding.apiKey is required");
-  if (!config.dbPath) throw new Error("mnemo: config.dbPath is required");
+  if (!config.embedding.apiKey) throw new Error("mnemo: config.embedding.apiKey is required (use 'ollama' for local Ollama)");
+  if (!config.dbPath) throw new Error("mnemo: config.dbPath is required \u2014 path to local database directory");
   const dimensions = config.embedding.dimensions || 1024;
   const embedder = new Embedder({
     apiKey: config.embedding.apiKey,
@@ -33,10 +33,11 @@ async function createMnemo(config) {
   return {
     async store(entry) {
       const vector = await embedder.embed(entry.text);
+      const category = entry.category || "fact";
       const result = await store.store({
         text: entry.text,
         vector,
-        category: entry.category || "fact",
+        category,
         importance: entry.importance ?? 0.7,
         scope: entry.scope || "global"
       });
@@ -70,6 +71,12 @@ async function createMnemo(config) {
       };
     },
     async close() {
+      if (store.adapter) {
+        try {
+          await store.adapter.close();
+        } catch {
+        }
+      }
     }
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemoai/core",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Cognitive science-based AI memory framework — Weibull decay, triple-path retrieval, multi-backend storage",
   "type": "module",
   "main": "dist/index.js",
@@ -65,7 +65,7 @@
   "scripts": {
     "build": "node build.mjs",
     "prepublishOnly": "npm run build",
-    "test": "node --test test/*.test.mjs",
+    "test": "node --test test/core.test.mjs test/package.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"
   },