@twelvehart/supermemory-runtime 1.0.0-next.0

package/src/config/env.ts

@@ -0,0 +1,71 @@
+import { existsSync } from 'node:fs'
+import { isAbsolute, resolve } from 'node:path'
+import { config as dotenvConfig } from 'dotenv'
+
+export type EnvFileSource = 'cli' | 'SUPERMEMORY_ENV_FILE' | '.env.local' | '.env'
+
+export interface EnvFileResolution {
+  path: string
+  exists: boolean
+  explicit: boolean
+  source: EnvFileSource
+}
+
+function toAbsolutePath(candidate: string, cwd: string): string {
+  return isAbsolute(candidate) ? candidate : resolve(cwd, candidate)
+}
+
+export function resolveEnvFile(options?: { cliEnvFile?: string; cwd?: string }): EnvFileResolution {
+  const cwd = options?.cwd ?? process.cwd()
+
+  if (options?.cliEnvFile) {
+    const path = toAbsolutePath(options.cliEnvFile, cwd)
+    return {
+      path,
+      exists: existsSync(path),
+      explicit: true,
+      source: 'cli',
+    }
+  }
+
+  if (process.env.SUPERMEMORY_ENV_FILE) {
+    const path = toAbsolutePath(process.env.SUPERMEMORY_ENV_FILE, cwd)
+    return {
+      path,
+      exists: existsSync(path),
+      explicit: true,
+      source: 'SUPERMEMORY_ENV_FILE',
+    }
+  }
+
+  const envLocalPath = resolve(cwd, '.env.local')
+  if (existsSync(envLocalPath)) {
+    return {
+      path: envLocalPath,
+      exists: true,
+      explicit: false,
+      source: '.env.local',
+    }
+  }
+
+  const envPath = resolve(cwd, '.env')
+  return {
+    path: envPath,
+    exists: existsSync(envPath),
+    explicit: false,
+    source: '.env',
+  }
+}
+
+export function loadEnvFile(options?: { cliEnvFile?: string; cwd?: string; override?: boolean }): EnvFileResolution {
+  const resolution = resolveEnvFile(options)
+
+  if (resolution.exists) {
+    dotenvConfig({
+      path: resolution.path,
+      override: options?.override ?? false,
+    })
+  }
+
+  return resolution
+}

package/src/config/feature-flags.ts

@@ -0,0 +1,25 @@
+/**
+ * Feature Flags for Memory Service Behavior
+ *
+ * Defaults are local/offline-friendly: LLM and embedding paths are disabled
+ * unless explicitly enabled via environment variables.
+ */
+
+const ENV_FLAGS = {
+  MEMORY_ENABLE_LLM: 'MEMORY_ENABLE_LLM',
+  MEMORY_ENABLE_EMBEDDINGS: 'MEMORY_ENABLE_EMBEDDINGS',
+} as const
+
+function isFlagEnabled(name: string): boolean {
+  const raw = process.env[name]
+  if (!raw) return false
+  return raw.toLowerCase() === 'true' || raw === '1'
+}
+
+export function isLLMFeatureEnabled(): boolean {
+  return isFlagEnabled(ENV_FLAGS.MEMORY_ENABLE_LLM)
+}
+
+export function isEmbeddingRelationshipsEnabled(): boolean {
+  return isFlagEnabled(ENV_FLAGS.MEMORY_ENABLE_EMBEDDINGS)
+}

package/src/config/index.ts

@@ -0,0 +1,140 @@
+import { z } from 'zod'
+import './bootstrap-env.js'
+import { ConfigurationError } from '../utils/errors.js'
+
+const configSchema = z.object({
+  // OpenAI (optional - local fallback available)
+  openaiApiKey: z.string().optional(),
+  embeddingModel: z.string().default('text-embedding-3-small'),
+  embeddingDimensions: z.coerce.number().default(1536),
+
+  // LLM Provider Configuration
+  llmProvider: z.enum(['openai', 'anthropic', 'mock']).optional().describe('LLM provider for memory extraction'),
+  anthropicApiKey: z.string().optional(),
+  llmModel: z.string().optional().describe('Override default model for LLM extraction'),
+  llmMaxTokens: z.coerce.number().default(2000),
+  llmTemperature: z.coerce.number().default(0.1),
+  llmTimeoutMs: z.coerce.number().default(30000),
+  llmMaxRetries: z.coerce.number().default(3),
+
+  // LLM Caching
+  llmCacheEnabled: z
+    .string()
+    .optional()
+    .transform((val) => val !== 'false')
+    .default('true'),
+  llmCacheTtlMs: z.coerce.number().default(900000), // 15 minutes
+
+  // Database
+  databaseUrl: z.string().default('postgresql://supermemory:supermemory_secret@localhost:5432/supermemory'),
+
+  // Vector Store
+  vectorStoreProvider: z.enum(['memory', 'sqlite-vss', 'chroma']).default('memory'),
+  vectorDimensions: z.coerce.number().default(1536),
+  vectorSqlitePath: z.string().default('./data/vectors.db'),
+  chromaUrl: z.string().default('http://localhost:8000'),
+  chromaCollection: z.string().default('supermemory_vectors'),
+
+  // Server
+  apiPort: z.coerce.number().default(3000),
+  apiHost: z.string().default('localhost'),
+
+  // Minimal API authentication (optional)
+  authEnabled: z
+    .string()
+    .optional()
+    .transform((val) => val === 'true' || val === '1')
+    .default('false'),
+  authToken: z.string().optional(),
+
+  // Rate Limiting
+  rateLimitRequests: z.coerce.number().default(100),
+  rateLimitWindowMs: z.coerce.number().default(60000),
+
+  // Logging
+  logLevel: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+})
+
+export type Config = z.infer<typeof configSchema>
+
+function isPostgresDatabaseUrl(url: string): boolean {
+  return url.startsWith('postgresql://') || url.startsWith('postgres://')
+}
+
+function normalizeEnvValue(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined
+  const trimmed = value.trim()
+  return trimmed.length > 0 ? trimmed : undefined
+}
+
+function loadConfig(): Config {
+  const result = configSchema.safeParse({
+    openaiApiKey: normalizeEnvValue(process.env.OPENAI_API_KEY),
+    embeddingModel: normalizeEnvValue(process.env.EMBEDDING_MODEL),
+    embeddingDimensions: normalizeEnvValue(process.env.EMBEDDING_DIMENSIONS),
+
+    // LLM Provider
+    llmProvider: normalizeEnvValue(process.env.LLM_PROVIDER),
+    anthropicApiKey: normalizeEnvValue(process.env.ANTHROPIC_API_KEY),
+    llmModel: normalizeEnvValue(process.env.LLM_MODEL),
+    llmMaxTokens: normalizeEnvValue(process.env.LLM_MAX_TOKENS),
+    llmTemperature: normalizeEnvValue(process.env.LLM_TEMPERATURE),
+    llmTimeoutMs: normalizeEnvValue(process.env.LLM_TIMEOUT_MS),
+    llmMaxRetries: normalizeEnvValue(process.env.LLM_MAX_RETRIES),
+    llmCacheEnabled: normalizeEnvValue(process.env.LLM_CACHE_ENABLED),
+    llmCacheTtlMs: normalizeEnvValue(process.env.LLM_CACHE_TTL_MS),
+
+    databaseUrl: normalizeEnvValue(process.env.DATABASE_URL),
+
+    // Vector Store
+    vectorStoreProvider: normalizeEnvValue(process.env.VECTOR_STORE_PROVIDER),
+    vectorDimensions: normalizeEnvValue(process.env.VECTOR_DIMENSIONS),
+    vectorSqlitePath: normalizeEnvValue(process.env.VECTOR_SQLITE_PATH),
+    chromaUrl: normalizeEnvValue(process.env.CHROMA_URL),
+    chromaCollection: normalizeEnvValue(process.env.CHROMA_COLLECTION),
+
+    apiPort: normalizeEnvValue(process.env.API_PORT),
+    apiHost: normalizeEnvValue(process.env.API_HOST),
+    authEnabled: normalizeEnvValue(process.env.AUTH_ENABLED),
+    authToken: normalizeEnvValue(process.env.AUTH_TOKEN),
+    rateLimitRequests: normalizeEnvValue(process.env.RATE_LIMIT_REQUESTS),
+    rateLimitWindowMs: normalizeEnvValue(process.env.RATE_LIMIT_WINDOW_MS),
+    logLevel: normalizeEnvValue(process.env.LOG_LEVEL),
+  })
+
+  if (!result.success) {
+    console.error('Configuration validation failed:')
+    result.error.issues.forEach((issue) => {
+      console.error(`  - ${issue.path.join('.')}: ${issue.message}`)
+    })
+    const fieldErrors: Record<string, string[]> = {}
+    result.error.issues.forEach((issue) => {
+      const path = issue.path.join('.') || '_root'
+      if (!fieldErrors[path]) {
+        fieldErrors[path] = []
+      }
+      fieldErrors[path].push(issue.message)
+    })
+    throw new ConfigurationError('Invalid configuration', undefined, { fieldErrors })
+  }
+
+  const config = result.data
+
+  if (process.env.NODE_ENV !== 'test' && !isPostgresDatabaseUrl(config.databaseUrl)) {
+    throw new ConfigurationError(
+      'DATABASE_URL must use postgres:// or postgresql:// outside tests. SQLite is only allowed when NODE_ENV=test.',
+      undefined,
+      {
+        fieldErrors: {
+          databaseUrl: [
+            'DATABASE_URL must use postgres:// or postgresql:// outside tests. SQLite is only allowed when NODE_ENV=test.',
+          ],
+        },
+      }
+    )
+  }
+
+  return config
+}
+
+export const config = loadConfig()

package/src/config/secrets.config.ts

@@ -0,0 +1,291 @@
+/**
+ * Secrets Configuration
+ *
+ * Defines required secrets, optional secrets, validation rules, and rotation policies.
+ * Used during application startup to validate environment configuration.
+ */
+
+/** Secret definition with validation rules */
+export interface SecretDefinition {
+  envVar: string
+  description: string
+  required: boolean
+  format?: 'api_key' | 'database_url' | 'jwt' | 'password' | 'generic'
+  minLength?: number
+  rotationDays?: number
+  defaultValue?: string
+  validate?: (value: string) => { valid: boolean; error?: string }
+}
+
+/** Secret category for organization */
+export interface SecretCategory {
+  name: string
+  description: string
+  secrets: SecretDefinition[]
+}
+
+export const DATABASE_SECRETS: SecretCategory = {
+  name: 'Database',
+  description: 'Database connection credentials',
+  secrets: [
+    {
+      envVar: 'DATABASE_URL',
+      description: 'PostgreSQL connection URL',
+      required: true,
+      format: 'database_url',
+      rotationDays: 90,
+    },
+    {
+      envVar: 'REDIS_URL',
+      description: 'Redis connection URL (for caching and queues)',
+      required: false,
+      format: 'database_url',
+      defaultValue: 'redis://localhost:6379',
+    },
+  ],
+}
+
+export const ENCRYPTION_SECRETS: SecretCategory = {
+  name: 'Encryption',
+  description: 'Master encryption keys',
+  secrets: [
+    {
+      envVar: 'SECRETS_MASTER_PASSWORD',
+      description: 'Optional master password for secrets encryption features',
+      required: false,
+      format: 'password',
+      minLength: 32,
+      rotationDays: 180,
+    },
+    {
+      envVar: 'SECRETS_SALT',
+      description: 'Salt for key derivation (base64)',
+      required: false,
+      format: 'generic',
+      minLength: 24,
+    },
+  ],
+}
+
+export const API_SECRETS: SecretCategory = {
+  name: 'API',
+  description: 'External API keys and tokens',
+  secrets: [
+    {
+      envVar: 'ANTHROPIC_API_KEY',
+      description: 'Anthropic API key for Claude',
+      required: false,
+      format: 'api_key',
+      rotationDays: 365,
+      validate: (value: string) => {
+        if (value.startsWith('sk-ant-')) {
+          return { valid: true }
+        }
+        return { valid: false, error: 'Must start with sk-ant-' }
+      },
+    },
+    {
+      envVar: 'OPENAI_API_KEY',
+      description: 'OpenAI API key',
+      required: false,
+      format: 'api_key',
+      rotationDays: 365,
+      validate: (value: string) => {
+        if (value.startsWith('sk-')) {
+          return { valid: true }
+        }
+        return { valid: false, error: 'Must start with sk-' }
+      },
+    },
+  ],
+}
+
+export const AUTH_SECRETS: SecretCategory = {
+  name: 'Authentication',
+  description: 'Authentication and authorization secrets',
+  secrets: [
+    {
+      envVar: 'JWT_SECRET',
+      description: 'Secret for JWT token signing',
+      required: false,
+      format: 'password',
+      minLength: 32,
+      rotationDays: 90,
+    },
+    {
+      envVar: 'AUTH_TOKEN',
+      description: 'Bearer token for optional REST API auth',
+      required: false,
+      format: 'password',
+      minLength: 16,
+      rotationDays: 90,
+    },
+    {
+      envVar: 'CSRF_SECRET',
+      description: 'Secret for CSRF token generation',
+      required: false,
+      format: 'password',
+      minLength: 32,
+      rotationDays: 90,
+    },
+  ],
+}
+
+export const SESSION_SECRETS: SecretCategory = {
+  name: 'Session',
+  description: 'Session management secrets',
+  secrets: [
+    {
+      envVar: 'SESSION_SECRET',
+      description: 'Secret for session cookie signing',
+      required: false,
+      format: 'password',
+      minLength: 32,
+      rotationDays: 90,
+    },
+  ],
+}
+
+export const ALL_SECRET_CATEGORIES: SecretCategory[] = [
+  DATABASE_SECRETS,
+  ENCRYPTION_SECRETS,
+  API_SECRETS,
+  AUTH_SECRETS,
+  SESSION_SECRETS,
+]
+
+/** Rotation policy definition */
+export interface RotationPolicy {
+  secretName: string
+  intervalDays: number
+  autoRotate: boolean
+  gracePeriodDays: number
+  notifyBeforeDays: number
+}
+
+export const ROTATION_POLICIES: RotationPolicy[] = [
+  {
+    secretName: 'SECRETS_MASTER_PASSWORD',
+    intervalDays: 180,
+    autoRotate: false, // Manual rotation required for master password
+    gracePeriodDays: 0,
+    notifyBeforeDays: 30,
+  },
+  {
+    secretName: 'DATABASE_URL',
+    intervalDays: 90,
+    autoRotate: false, // Manual rotation for database credentials
+    gracePeriodDays: 7,
+    notifyBeforeDays: 14,
+  },
+  {
+    secretName: 'JWT_SECRET',
+    intervalDays: 90,
+    autoRotate: true, // Can auto-rotate JWT secret with grace period
+    gracePeriodDays: 14,
+    notifyBeforeDays: 7,
+  },
+  {
+    secretName: 'CSRF_SECRET',
+    intervalDays: 90,
+    autoRotate: true,
+    gracePeriodDays: 7,
+    notifyBeforeDays: 7,
+  },
+  {
+    secretName: 'SESSION_SECRET',
+    intervalDays: 90,
+    autoRotate: true,
+    gracePeriodDays: 14,
+    notifyBeforeDays: 7,
+  },
+]
+
+/** Get all required secrets */
+export function getRequiredSecrets(): SecretDefinition[] {
+  return ALL_SECRET_CATEGORIES.flatMap((cat) => cat.secrets.filter((s) => s.required))
+}
+
+/** Get all optional secrets */
+export function getOptionalSecrets(): SecretDefinition[] {
+  return ALL_SECRET_CATEGORIES.flatMap((cat) => cat.secrets.filter((s) => !s.required))
+}
+
+/** Get all secrets (required + optional) */
+export function getAllSecrets(): SecretDefinition[] {
+  return ALL_SECRET_CATEGORIES.flatMap((cat) => cat.secrets)
+}
+
+/** Get secret definition by environment variable name */
+export function getSecretDefinition(envVar: string): SecretDefinition | undefined {
+  for (const category of ALL_SECRET_CATEGORIES) {
+    const secret = category.secrets.find((s) => s.envVar === envVar)
+    if (secret) return secret
+  }
+  return undefined
+}
+
+/** Get rotation policy for a secret */
+export function getRotationPolicy(secretName: string): RotationPolicy | undefined {
+  return ROTATION_POLICIES.find((p) => p.secretName === secretName)
+}
+
+/** Check if a secret is due for rotation */
+export function isRotationDue(secretName: string, lastRotated: Date): boolean {
+  const policy = getRotationPolicy(secretName)
+  if (!policy) {
+    return false
+  }
+
+  const now = new Date()
+  const daysSinceRotation = (now.getTime() - lastRotated.getTime()) / (1000 * 60 * 60 * 24)
+
+  return daysSinceRotation >= policy.intervalDays
+}
+
+/** Check if rotation warning should be shown */
+export function shouldWarnRotation(secretName: string, lastRotated: Date): boolean {
+  const policy = getRotationPolicy(secretName)
+  if (!policy) {
+    return false
+  }
+
+  const now = new Date()
+  const daysSinceRotation = (now.getTime() - lastRotated.getTime()) / (1000 * 60 * 60 * 24)
+  const daysUntilRotation = policy.intervalDays - daysSinceRotation
+
+  return daysUntilRotation <= policy.notifyBeforeDays && daysUntilRotation > 0
+}
+
+export interface EncryptionKeyConfig {
+  kdf: 'pbkdf2' | 'scrypt' | 'argon2'
+  iterations: number
+  keyLength: number
+  digest: 'sha256' | 'sha512'
+}
+
+/** Default encryption key configuration (OWASP 2023 recommendations) */
+export const DEFAULT_ENCRYPTION_CONFIG: EncryptionKeyConfig = {
+  kdf: 'pbkdf2',
+  iterations: 600000, // OWASP 2023 recommendation for PBKDF2-SHA512
+  keyLength: 32, // 256 bits
+  digest: 'sha512',
+}
+
+/** Alternative encryption configs for different security levels */
+export const ENCRYPTION_CONFIGS = {
+  standard: DEFAULT_ENCRYPTION_CONFIG,
+  high: {
+    kdf: 'pbkdf2' as const,
+    iterations: 1200000,
+    keyLength: 32,
+    digest: 'sha512' as const,
+  },
+  /** Performance-optimized (minimum secure iterations) */
+  performance: {
+    kdf: 'pbkdf2' as const,
+    iterations: 310000, // OWASP minimum for PBKDF2-SHA256
+    keyLength: 32,
+    digest: 'sha256' as const,
+  },
+} as const

package/src/db/client.ts

@@ -0,0 +1,92 @@
+/**
+ * Unified Database Client
+ * Automatically selects between SQLite and PostgreSQL based on DATABASE_URL
+ */
+
+import {
+  getDatabase as getSqliteDatabase,
+  runMigrations as runSqliteMigrations,
+  closeDatabase as closeSqliteDatabase,
+  type DatabaseInstance as SqliteDatabaseInstance,
+} from './index.js'
+
+import {
+  getPostgresDatabase,
+  runPostgresMigrations,
+  closePostgresDatabase,
+  type PostgresDatabaseInstance,
+} from './postgres.js'
+
+export type DatabaseInstance = SqliteDatabaseInstance | PostgresDatabaseInstance
+
+export function getDatabaseUrl(): string {
+  return process.env.DATABASE_URL ?? './data/supermemory.db'
+}
+
+export function isPostgresUrl(url: string): boolean {
+  return url.startsWith('postgresql://') || url.startsWith('postgres://')
+}
+
+function assertPostgresUrlAllowed(url: string): void {
+  if (process.env.NODE_ENV === 'test') {
+    return
+  }
+
+  if (!isPostgresUrl(url)) {
+    throw new Error(
+      'DATABASE_URL must use postgres:// or postgresql:// outside tests. SQLite is only allowed when NODE_ENV=test.'
+    )
+  }
+}
+
+export function getDatabase(): DatabaseInstance {
+  const url = getDatabaseUrl()
+  const isPostgres = isPostgresUrl(url)
+
+  assertPostgresUrlAllowed(url)
+
+  if (isPostgres) {
+    return getPostgresDatabase(url) as DatabaseInstance
+  } else {
+    return getSqliteDatabase(url) as DatabaseInstance
+  }
+}
+
+export async function runMigrations(): Promise<void> {
+  const url = getDatabaseUrl()
+  const isPostgres = isPostgresUrl(url)
+
+  assertPostgresUrlAllowed(url)
+
+  if (isPostgres) {
+    await runPostgresMigrations(url)
+  } else {
+    runSqliteMigrations(url)
+  }
+}
+
+export async function closeDatabase(): Promise<void> {
+  const url = getDatabaseUrl()
+  const isPostgres = isPostgresUrl(url)
+
+  assertPostgresUrlAllowed(url)
+
+  if (isPostgres) {
+    await closePostgresDatabase()
+  } else {
+    closeSqliteDatabase()
+  }
+}
+
+export function getDatabaseInfo() {
+  const url = getDatabaseUrl()
+  const isPostgres = isPostgresUrl(url)
+
+  assertPostgresUrlAllowed(url)
+
+  return {
+    type: isPostgres ? 'postgresql' : 'sqlite',
+    url: isPostgres ? url.replace(/:[^:@]+@/, ':****@') : url, // Mask password
+    isProduction: isPostgres,
+  }
+}

package/src/db/index.ts

@@ -0,0 +1,73 @@
+import Database from 'better-sqlite3'
+import { drizzle } from 'drizzle-orm/better-sqlite3'
+import { migrate } from 'drizzle-orm/better-sqlite3/migrator'
+import * as schema from './schema.js'
+import { existsSync, mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+let db: ReturnType<typeof drizzle<typeof schema>> | null = null
+let sqliteInstance: Database.Database | null = null
+
+function isPostgresConnectionString(url: string): boolean {
+  const normalized = url.trim().toLowerCase()
+  return normalized.startsWith('postgresql://') || normalized.startsWith('postgres://')
+}
+
+function createDatabase(databaseUrl: string) {
+  if (isPostgresConnectionString(databaseUrl)) {
+    throw new Error(
+      'SQLite database module received a PostgreSQL URL. Use src/db/client.ts or src/db/postgres.ts for PostgreSQL connections.'
+    )
+  }
+
+  // Ensure the directory exists
+  const dir = dirname(databaseUrl)
+  if (dir !== '.' && !existsSync(dir)) {
+    mkdirSync(dir, { recursive: true })
+  }
+
+  const sqlite = new Database(databaseUrl)
+  sqliteInstance = sqlite
+
+  // Enable WAL mode for better concurrent access
+  sqlite.pragma('journal_mode = WAL')
+
+  // Enable foreign keys
+  sqlite.pragma('foreign_keys = ON')
+
+  // Optimize for performance
+  sqlite.pragma('synchronous = NORMAL')
+  sqlite.pragma('cache_size = -64000') // 64MB cache
+  sqlite.pragma('temp_store = MEMORY')
+
+  return drizzle(sqlite, { schema })
+}
+
+export function getDatabase(databaseUrl: string) {
+  if (!db) {
+    db = createDatabase(databaseUrl)
+  }
+  return db
+}
+
+export function runMigrations(databaseUrl: string) {
+  const database = getDatabase(databaseUrl)
+  migrate(database, { migrationsFolder: './drizzle' })
+  console.log('Migrations completed successfully')
+}
+
+export function closeDatabase() {
+  if (sqliteInstance) {
+    sqliteInstance.close()
+    sqliteInstance = null
+    db = null
+  }
+}
+
+export function getSqliteInstance(): Database.Database | null {
+  return sqliteInstance
+}
+
+export type DatabaseInstance = ReturnType<typeof createDatabase>
+
+export { schema }