@wjmwjmwb/memme 0.1.1

package/README.md

@@ -0,0 +1,36 @@
+# MemMe Node.js SDK
+
+MemMe stores memory data in one SQLite file and uses the VexDB-Lite SQLite
+extension for vector search.
+
+## Supported platforms
+
+Published packages currently support macOS and Linux on x64 and arm64. Windows
+publication is disabled because VexDB-Lite v0.0.17 does not provide a Windows
+SQLite extension asset.
+
+The extension is not bundled in the npm package. Download the matching trusted
+VexDB-Lite SQLite extension and pass its absolute path to the constructor:
+
+```js
+const { MemoryStore } = require("@wjmwjmwb/memme");
+
+const store = MemoryStore.newMock(
+  "memory.db",
+  384,
+  "/opt/vexdb-lite/vexdb_lite.so",
+);
+```
+
+Existing applications can continue to use the environment variable:
+
+```bash
+export MEMME_VEXDB_LITE_EXTENSION=/opt/vexdb-lite/vexdb_lite.so
+```
+
+```js
+const store = MemoryStore.newMock("memory.db", 384);
+```
+
+Mobile and WASM publication remains paused until VexDB-Lite static registration
+uses the same SQLite instance as MemMe.

package/index.d.ts

@@ -0,0 +1,293 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/** Memory result returned to JavaScript. */
+export interface MemoryResult {
+  id: string
+  content: string
+  userId: string
+  agentId?: string
+  appId?: string
+  runId?: string
+  score?: number
+  createdAt: string
+  updatedAt: string
+  metadata?: string
+  importance?: number
+  accessCount?: number
+  immutable: boolean
+  expirationDate?: string
+  categories?: Array<string>
+  memoryType?: string
+  retention?: number
+  stability?: number
+  privacy: string
+  eventTime?: string
+  episodeId?: string
+  sessionId?: string
+}
+/** A chat message for smart operations. */
+export interface ChatMessage {
+  role: string
+  content: string
+}
+/** Entity in the knowledge graph. */
+export interface Entity {
+  id: string
+  name: string
+  entityType?: string
+  userId: string
+}
+/** Relationship in the knowledge graph. */
+export interface GraphRelation {
+  id: string
+  source: string
+  sourceId: string
+  target: string
+  targetId: string
+  relationType: string
+  userId: string
+  description?: string
+}
+/** A history record. */
+export interface HistoryRecord {
+  id: string
+  memoryId: string
+  oldMemory?: string
+  newMemory: string
+  event: string
+  createdAt: string
+}
+/** User statistics. */
+export interface UserStats {
+  userId: string
+  totalMemories: number
+  totalEntities: number
+  totalRelationships: number
+  earliestMemory?: string
+  latestMemory?: string
+  uniqueAgents: number
+}
+/** Memory count per time period. */
+export interface TimeBucket {
+  period: string
+  count: number
+}
+/** Top entity by relationship count. */
+export interface EntityStat {
+  name: string
+  entityType?: string
+  relationshipCount: number
+}
+/** An episode (compressed understanding of a session). */
+export interface Episode {
+  episodeId: string
+  title: string
+  summary: string
+  startedAt: string
+  endedAt?: string
+  significance: number
+  outcome?: string
+  sourceId?: string
+  eventIds: Array<string>
+  sessionIds: Array<string>
+  userId: string
+  createdAt: string
+  lastRecalled?: string
+  recallCount: number
+  storageStrength: number
+  retrievalStrength: number
+  score?: number
+}
+/** A stream event (single event in a session). */
+export interface StreamEvent {
+  eventId: string
+  eventType: string
+  content: string
+  timestamp: string
+  sessionId?: string
+  sourceId?: string
+  userId: string
+  parentId?: string
+  metadata?: string
+  processed: boolean
+  purifiedContent?: string
+  location?: string
+}
+/** A session (immutable event container). */
+export interface Session {
+  sessionId: string
+  userId: string
+  sourceId?: string
+  startedAt: string
+  endedAt?: string
+  metadata?: string
+  createdAt: string
+  eventCount: number
+}
+/** Session context assembled for retrieval-augmented generation. */
+export interface SessionContext {
+  sessionId: string
+  events: Array<StreamEvent>
+  tokensUsed: number
+  tokenBudget: number
+  episodeSummary?: string
+  purifiedCount: number
+  rawCount: number
+}
+/** An identity trait extracted from memories. */
+export interface IdentityTrait {
+  traitId: string
+  traitType: string
+  content: string
+  confidence: number
+  evidenceIds: Array<string>
+  userId: string
+  createdAt: string
+  updatedAt?: string
+}
+/** A meditation (deep processing) record. */
+export interface MeditationRecord {
+  meditationId: string
+  triggeredBy: string
+  startedAt: string
+  finishedAt?: string
+  status: string
+  userId: string
+  eventsProcessed: number
+  episodesCreated: number
+  memoriesCreated: number
+  memoriesUpdated: number
+  memoriesDecayed: number
+  entitiesCreated: number
+  relationsCreated: number
+  conflictsFound: number
+  journal?: string
+  metadata?: string
+}
+/** Result of appending events to a session. */
+export interface AppendEventsResult {
+  sessionId: string
+  eventsAppended: number
+  totalUnprocessed: number
+  compactNeeded: boolean
+}
+/** Result of compacting a session into an episode. */
+export interface CompactResult {
+  sessionId: string
+  episodeId: string
+  memories: Array<MemoryResult>
+  eventsProcessed: number
+}
+/** Graph search result. */
+export interface GraphSearchResult {
+  entities: Array<Entity>
+  relations: Array<GraphRelation>
+}
+/** The main MemMe memory store. */
+export declare class MemoryStore {
+  /**
+   * Create a new MemoryStore with mock embedder (for testing).
+   * Pass a trusted VexDB-Lite extension path explicitly, or omit it to use
+   * MEMME_VEXDB_LITE_EXTENSION.
+   */
+  static newMock(dbPath?: string | undefined | null, dims?: number | undefined | null, vexdbExtensionPath?: string | undefined | null): MemoryStore
+  /**
+   * Create a new MemoryStore with mock embedder AND mock LLM (for E2E testing).
+   * The mock LLM returns pre-scripted responses in order.
+   * Pass an array of JSON strings that the LLM should return.
+   */
+  static newMockWithLlm(responses: Array<string>, dbPath?: string | undefined | null, dims?: number | undefined | null, vexdbExtensionPath?: string | undefined | null): MemoryStore
+  /** Create a new MemoryStore with OpenAI-compatible embedder. */
+  static newOpenai(apiKey: string, dbPath?: string | undefined | null, baseUrl?: string | undefined | null, model?: string | undefined | null, dims?: number | undefined | null, vexdbExtensionPath?: string | undefined | null): MemoryStore
+  /** Configure LLM provider at runtime. Call once after construction. */
+  setLlmProvider(apiKey: string, model: string, baseUrl?: string | undefined | null): void
+  /**
+   * Backup the database to a file path.
+   * Returns metadata about the backup (size, memory count, schema version).
+   */
+  backupToPath(path: string): any
+  /**
+   * Restore the database from a backup file.
+   * **Warning**: The caller must re-create the MemoryStore after calling this.
+   */
+  restoreFromBackup(backupPath: string): void
+  /** Run diagnostic checks on storage, embedder, and LLM. */
+  diagnose(): any
+  /** Check if an LLM provider is configured. */
+  hasLlm(): boolean
+  /** Persist LLM configuration to the database. */
+  saveLlmConfig(apiKey: string, model: string, baseUrl: string): void
+  /** Load persisted LLM configuration. Returns [apiKey, model, baseUrl] or null. */
+  loadLlmConfig(): Array<string> | null
+  /** Add a memory (vector dedup, no LLM). */
+  add(content: string, userId: string, agentId?: string | undefined | null, runId?: string | undefined | null, metadata?: string | undefined | null): Promise<MemoryResult>
+  /** Search memories. */
+  search(query: string, userId: string, agentId?: string | undefined | null, runId?: string | undefined | null, limit?: number | undefined | null, threshold?: number | undefined | null): Promise<Array<MemoryResult>>
+  /** Get a memory by ID. */
+  get(id: string): Promise<MemoryResult | null>
+  /** Update a memory. */
+  update(id: string, content: string): Promise<MemoryResult>
+  /** Delete a memory. */
+  delete(id: string): Promise<void>
+  /** List memories. */
+  list(userId: string, agentId?: string | undefined | null, runId?: string | undefined | null, limit?: number | undefined | null): Promise<Array<MemoryResult>>
+  /**
+   * Hybrid search (vector + FTS with RRF fusion).
+   *
+   * RRF weights are configured at store construction time.
+   */
+  hybridSearch(query: string, userId: string, agentId?: string | undefined | null, runId?: string | undefined | null, limit?: number | undefined | null): Promise<Array<MemoryResult>>
+  /** Rebuild FTS index. */
+  rebuildFtsIndex(): Promise<void>
+  /** Delete all memories matching filters. */
+  deleteAll(userId: string, agentId?: string | undefined | null, runId?: string | undefined | null, appId?: string | undefined | null): Promise<number>
+  /** Get change history for a memory. */
+  history(memoryId: string): Promise<Array<HistoryRecord>>
+  /** Reset the entire store — delete ALL data. Destructive. */
+  reset(): Promise<void>
+  /** Append chat messages as events to a session. Returns whether compact is needed. */
+  appendEvents(sessionId: string, messages: Array<ChatMessage>, userId: string, metadata?: string | undefined | null): Promise<AppendEventsResult>
+  /** Compact a session: extract memories + create episode from unprocessed events. */
+  compact(sessionId: string): Promise<CompactResult>
+  /** Get a session by ID. */
+  getSession(sessionId: string): Promise<Session | null>
+  /** List sessions for a user. */
+  listSessions(userId: string, sourceId?: string | undefined | null, since?: string | undefined | null, until?: string | undefined | null, limit?: number | undefined | null, offset?: number | undefined | null): Promise<Array<Session>>
+  /** Delete a session and its events. */
+  deleteSession(sessionId: string): Promise<void>
+  /** Get events in a session (paginated). */
+  getSessionEvents(sessionId: string, limit?: number | undefined | null, offset?: number | undefined | null): Promise<Array<StreamEvent>>
+  /** Assemble session context for RAG with token budget. */
+  getSessionContext(sessionId: string, tokenBudget?: number | undefined | null, includeSummary?: boolean | undefined | null, maxEvents?: number | undefined | null): Promise<SessionContext>
+  /** List episodes for a user. */
+  listEpisodes(userId: string, limit?: number | undefined | null, offset?: number | undefined | null, since?: string | undefined | null, until?: string | undefined | null): Promise<Array<Episode>>
+  /** Get an episode by ID. */
+  getEpisode(episodeId: string): Promise<Episode | null>
+  /** Get messages (events) in an episode. */
+  getEpisodeMessages(episodeId: string, limit?: number | undefined | null, offset?: number | undefined | null): Promise<Array<StreamEvent>>
+  /** Search episodes by semantic similarity. */
+  searchEpisodes(query: string, userId: string, limit?: number | undefined | null): Promise<Array<Episode>>
+  /** Search messages within an episode by semantic similarity. */
+  searchEpisodeMessages(episodeId: string, query: string, limit?: number | undefined | null): Promise<Array<StreamEvent>>
+  /** Delete an episode. */
+  deleteEpisode(episodeId: string): Promise<void>
+  /** List all identity traits for a user. */
+  listIdentityTraits(userId: string): Promise<Array<IdentityTrait>>
+  /** Add or update an identity trait. */
+  addIdentityTrait(traitType: string, content: string, userId: string, confidence?: number | undefined | null, evidenceIds?: Array<string> | undefined | null): Promise<IdentityTrait>
+  /** Trigger deep processing (meditation): decay, extraction, graph, identity. */
+  meditate(userId: string, triggeredBy: string, since?: string | undefined | null): Promise<MeditationRecord>
+  /** Add graph with LLM. */
+  addGraph(text: string, userId: string, llmApiKey: string, llmModel?: string | undefined | null, llmBaseUrl?: string | undefined | null): Promise<GraphSearchResult>
+  /** Search graph (no LLM). */
+  searchGraph(query: string, userId: string, depth?: number | undefined | null): Promise<GraphSearchResult>
+  /** Get summary statistics for a user. */
+  userStats(userId: string): Promise<UserStats>
+  /** Get memory creation frequency by time period. */
+  memoryFrequency(userId: string, granularity: string, limit?: number | undefined | null): Promise<Array<TimeBucket>>
+  /** Get top entities by relationship count. */
+  topEntities(userId: string, limit?: number | undefined | null): Promise<Array<EntityStat>>
+}

package/index.js

@@ -0,0 +1,315 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 10
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch (e) {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'android':
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'memme.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./memme.android-arm64.node')
+          } else {
+            nativeBinding = require('memme-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'memme.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./memme.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('memme-android-arm-eabi')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, 'memme.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./memme.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('memme-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'memme.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./memme.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('memme-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'memme.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./memme.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('memme-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'memme.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./memme.darwin-universal.node')
+      } else {
+        nativeBinding = require('memme-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'memme.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./memme.darwin-x64.node')
+          } else {
+            nativeBinding = require('memme-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'memme.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./memme.darwin-arm64.node')
+          } else {
+            nativeBinding = require('memme-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, 'memme.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./memme.freebsd-x64.node')
+      } else {
+        nativeBinding = require('memme-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'memme.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./memme.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('memme-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'memme.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./memme.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('memme-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'memme.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./memme.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('memme-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'memme.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./memme.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('memme-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'memme.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./memme.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('memme-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'memme.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./memme.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('memme-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'memme.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./memme.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('memme-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'memme.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./memme.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('memme-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'memme.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./memme.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('memme-linux-s390x-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { MemoryStore } = nativeBinding
+
+module.exports.MemoryStore = MemoryStore

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@wjmwjmwb/memme",
+  "version": "0.1.1",
+  "description": "Edge-first AI memory engine powered by SQLite — vector search, knowledge graph, BM25, and forgetting curve in a single file",
+  "keywords": ["ai", "memory", "embedding", "sqlite", "edge", "offline", "vector-database", "knowledge-graph", "rag", "llm"],
+  "license": "Apache-2.0",
+  "author": "MemMe Contributors",
+  "os": ["darwin", "linux"],
+  "homepage": "https://github.com/vibeinging/MemMe",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vibeinging/MemMe.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vibeinging/MemMe/issues"
+  },
+  "main": "index.js",
+  "types": "index.d.ts",
+  "napi": {
+    "name": "memme",
+    "triples": {
+      "defaults": false,
+      "additional": [
+        "x86_64-apple-darwin",
+        "aarch64-apple-darwin",
+        "x86_64-unknown-linux-gnu",
+        "aarch64-unknown-linux-gnu"
+      ]
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "package.json"
+  ],
+  "optionalDependencies": {
+    "memme-darwin-arm64": "0.1.1",
+    "memme-darwin-x64": "0.1.1",
+    "memme-linux-arm64-gnu": "0.1.1",
+    "memme-linux-x64-gnu": "0.1.1"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^2.18.0",
+    "vitest": "^4.1.2"
+  },
+  "scripts": {
+    "artifacts": "napi artifacts",
+    "build": "napi build --platform --release --cargo-cwd .",
+    "build:debug": "napi build --platform --cargo-cwd .",
+    "prepublishOnly": "napi prepublish -t npm",
+    "version": "napi version"
+  }
+}