@lota-sdk/core 0.1.5 → 0.1.7

package/infrastructure/schema/00_identity.surql

@@ -0,0 +1,26 @@
+# SDK identity tables.
+DEFINE TABLE IF NOT EXISTS organization SCHEMAFULL;
+DEFINE FIELD IF NOT EXISTS name ON TABLE organization TYPE string;
+DEFINE FIELD IF NOT EXISTS regularChatDigestLastWorkstreamCursorCreatedAt ON TABLE organization TYPE option<datetime>;
+DEFINE FIELD IF NOT EXISTS regularChatDigestLastWorkstreamCursorId ON TABLE organization TYPE option<string>;
+DEFINE FIELD IF NOT EXISTS skillExtractionLastCursorId ON TABLE organization TYPE option<string>;
+DEFINE FIELD IF NOT EXISTS skillExtractionLastCursorCreatedAt ON TABLE organization TYPE option<datetime>;
+DEFINE FIELD IF NOT EXISTS createdAt ON TABLE organization TYPE datetime DEFAULT time::now() READONLY;
+DEFINE FIELD IF NOT EXISTS updatedAt ON TABLE organization TYPE datetime VALUE time::now();
+
+DEFINE TABLE IF NOT EXISTS user SCHEMAFULL;
+DEFINE FIELD IF NOT EXISTS name ON TABLE user TYPE string;
+DEFINE FIELD IF NOT EXISTS email ON TABLE user TYPE string;
+DEFINE FIELD IF NOT EXISTS createdAt ON TABLE user TYPE datetime DEFAULT time::now() READONLY;
+DEFINE FIELD IF NOT EXISTS updatedAt ON TABLE user TYPE datetime VALUE time::now();
+
+DEFINE INDEX IF NOT EXISTS sdkUserEmailIdx ON TABLE user COLUMNS email;
+
+DEFINE TABLE IF NOT EXISTS organizationMember SCHEMAFULL TYPE RELATION IN user OUT organization;
+DEFINE FIELD IF NOT EXISTS in ON TABLE organizationMember TYPE record<user>;
+DEFINE FIELD IF NOT EXISTS out ON TABLE organizationMember TYPE record<organization>;
+DEFINE FIELD IF NOT EXISTS role ON TABLE organizationMember TYPE string;
+DEFINE FIELD IF NOT EXISTS createdAt ON TABLE organizationMember TYPE datetime DEFAULT time::now() READONLY;
+
+DEFINE INDEX IF NOT EXISTS organizationMemberUniqueIdx ON TABLE organizationMember COLUMNS in, out UNIQUE;
+DEFINE INDEX IF NOT EXISTS organizationMemberOutIdx ON TABLE organizationMember COLUMNS out, createdAt;

package/infrastructure/schema/00_workstream.surql

@@ -15,10 +15,17 @@ DEFINE FIELD IF NOT EXISTS memoryBlockSummary ON TABLE workstream TYPE option<st
 DEFINE FIELD IF NOT EXISTS activeRunId ON TABLE workstream TYPE option<string>;
 DEFINE FIELD IF NOT EXISTS chatSummary ON TABLE workstream TYPE option<string>;
 DEFINE FIELD IF NOT EXISTS lastCompactedMessageId ON TABLE workstream TYPE option<string>;
+DEFINE FIELD IF NOT EXISTS nameGenerated ON TABLE workstream TYPE bool DEFAULT false;
 DEFINE FIELD IF NOT EXISTS isCompacting ON TABLE workstream TYPE bool DEFAULT false;
 DEFINE FIELD IF NOT EXISTS state ON TABLE workstream TYPE option<object> FLEXIBLE;
+DEFINE FIELD IF NOT EXISTS turnCount ON TABLE workstream TYPE int DEFAULT 0;
 
 DEFINE INDEX IF NOT EXISTS workstreamOrgIdx ON TABLE workstream COLUMNS organizationId;
+DEFINE INDEX IF NOT EXISTS workstreamUserIdx ON TABLE workstream COLUMNS userId;
+DEFINE INDEX IF NOT EXISTS workstreamUserOrgModeUpdatedIdx ON TABLE workstream COLUMNS userId, organizationId, mode, updatedAt;
+DEFINE INDEX IF NOT EXISTS workstreamUserOrgStatusModeUpdatedIdx ON TABLE workstream COLUMNS userId, organizationId, status, mode, updatedAt;
+DEFINE INDEX IF NOT EXISTS workstreamUserOrgCoreModeUpdatedIdx ON TABLE workstream COLUMNS userId, organizationId, core, mode, updatedAt;
+DEFINE INDEX IF NOT EXISTS workstreamUserOrgStatusCoreModeUpdatedIdx ON TABLE workstream COLUMNS userId, organizationId, status, core, mode, updatedAt;
 
 # Workstream Message table (AI SDK UIMessage persistence).
 # parts uses OVERWRITE on the wildcard to override the implicit non-FLEXIBLE
@@ -53,3 +60,4 @@ DEFINE FIELD IF NOT EXISTS updatedAt ON TABLE workstreamAttachment TYPE datetime
 
 DEFINE INDEX IF NOT EXISTS workstreamAttachmentWorkstreamIdx ON TABLE workstreamAttachment COLUMNS workstreamId;
 DEFINE INDEX IF NOT EXISTS workstreamAttachmentMessageIdx ON TABLE workstreamAttachment COLUMNS messageId;
+DEFINE INDEX IF NOT EXISTS workstreamAttachmentWorkstreamMessageIdx ON TABLE workstreamAttachment COLUMNS workstreamId, messageId;

package/infrastructure/schema/05_recent_activity.surql

@@ -0,0 +1,48 @@
+# SDK recent activity tables.
+DEFINE TABLE IF NOT EXISTS recentActivityEvent SCHEMAFULL;
+DEFINE FIELD IF NOT EXISTS organizationId ON TABLE recentActivityEvent TYPE record<organization>;
+DEFINE FIELD IF NOT EXISTS userId ON TABLE recentActivityEvent TYPE record<user>;
+DEFINE FIELD IF NOT EXISTS sourceEventId ON TABLE recentActivityEvent TYPE string;
+DEFINE FIELD IF NOT EXISTS source ON TABLE recentActivityEvent TYPE string;
+DEFINE FIELD IF NOT EXISTS kind ON TABLE recentActivityEvent TYPE string;
+DEFINE FIELD IF NOT EXISTS targetKind ON TABLE recentActivityEvent TYPE string;
+DEFINE FIELD IF NOT EXISTS targetId ON TABLE recentActivityEvent TYPE option<string>;
+DEFINE FIELD IF NOT EXISTS mergeKey ON TABLE recentActivityEvent TYPE string;
+DEFINE FIELD IF NOT EXISTS title ON TABLE recentActivityEvent TYPE string;
+DEFINE FIELD IF NOT EXISTS sourceLabel ON TABLE recentActivityEvent TYPE string;
+DEFINE FIELD IF NOT EXISTS deepLink ON TABLE recentActivityEvent TYPE object FLEXIBLE;
+DEFINE FIELD IF NOT EXISTS metadata ON TABLE recentActivityEvent TYPE option<object> FLEXIBLE;
+DEFINE FIELD IF NOT EXISTS occurredAt ON TABLE recentActivityEvent TYPE datetime;
+DEFINE FIELD IF NOT EXISTS createdAt ON TABLE recentActivityEvent TYPE datetime DEFAULT time::now() READONLY;
+
+DEFINE INDEX IF NOT EXISTS recentActivityEventSourceUniqueIdx
+  ON TABLE recentActivityEvent COLUMNS organizationId, userId, sourceEventId UNIQUE;
+DEFINE INDEX IF NOT EXISTS recentActivityEventRecentIdx
+  ON TABLE recentActivityEvent COLUMNS organizationId, userId, occurredAt;
+DEFINE INDEX IF NOT EXISTS recentActivityEventMergeIdx
+  ON TABLE recentActivityEvent COLUMNS organizationId, userId, mergeKey, occurredAt;
+
+DEFINE TABLE IF NOT EXISTS recentActivity SCHEMAFULL;
+DEFINE FIELD IF NOT EXISTS organizationId ON TABLE recentActivity TYPE record<organization>;
+DEFINE FIELD IF NOT EXISTS userId ON TABLE recentActivity TYPE record<user>;
+DEFINE FIELD IF NOT EXISTS mergeKey ON TABLE recentActivity TYPE string;
+DEFINE FIELD IF NOT EXISTS kind ON TABLE recentActivity TYPE string;
+DEFINE FIELD IF NOT EXISTS targetKind ON TABLE recentActivity TYPE string;
+DEFINE FIELD IF NOT EXISTS targetId ON TABLE recentActivity TYPE option<string>;
+DEFINE FIELD IF NOT EXISTS title ON TABLE recentActivity TYPE string;
+DEFINE FIELD IF NOT EXISTS systemTitle ON TABLE recentActivity TYPE string;
+DEFINE FIELD IF NOT EXISTS titleSource ON TABLE recentActivity TYPE string;
+DEFINE FIELD IF NOT EXISTS sourceLabel ON TABLE recentActivity TYPE string;
+DEFINE FIELD IF NOT EXISTS deepLink ON TABLE recentActivity TYPE object FLEXIBLE;
+DEFINE FIELD IF NOT EXISTS metadata ON TABLE recentActivity TYPE option<object> FLEXIBLE;
+DEFINE FIELD IF NOT EXISTS latestEventId ON TABLE recentActivity TYPE option<record<recentActivityEvent>>;
+DEFINE FIELD IF NOT EXISTS latestSourceEventId ON TABLE recentActivity TYPE option<string>;
+DEFINE FIELD IF NOT EXISTS latestEventAt ON TABLE recentActivity TYPE datetime;
+DEFINE FIELD IF NOT EXISTS titleRefinedAt ON TABLE recentActivity TYPE option<datetime>;
+DEFINE FIELD IF NOT EXISTS createdAt ON TABLE recentActivity TYPE datetime DEFAULT time::now() READONLY;
+DEFINE FIELD IF NOT EXISTS updatedAt ON TABLE recentActivity TYPE datetime VALUE time::now();
+
+DEFINE INDEX IF NOT EXISTS recentActivityMergeUniqueIdx
+  ON TABLE recentActivity COLUMNS organizationId, userId, mergeKey UNIQUE;
+DEFINE INDEX IF NOT EXISTS recentActivityRecentIdx
+  ON TABLE recentActivity COLUMNS organizationId, userId, latestEventAt;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lota-sdk/core",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -104,7 +104,8 @@
     "lint": "node ../node_modules/oxlint/bin/oxlint --fix -c ../oxlint.config.ts src",
     "format": "bunx oxfmt src",
     "typecheck": "bunx tsgo --noEmit",
-    "test:unit": "bun test ../tests/unit/core"
+    "test:unit": "bun test ../tests/unit/core",
+    "test:coverage": "bun test --coverage ../tests/unit/core"
   },
   "publishConfig": {
     "access": "public",
@@ -113,7 +114,7 @@
   "dependencies": {
     "@ai-sdk/openai": "^3.0.41",
     "@logtape/logtape": "^2.0.4",
-    "@lota-sdk/shared": "0.1.0",
+    "@lota-sdk/shared": "file:../shared",
     "@mendable/firecrawl-js": "^4.16.0",
     "@surrealdb/node": "^3.0.3",
     "ai": "^6.0.116",

package/src/ai/embedding-cache.ts

@@ -0,0 +1,48 @@
+import { createHash } from 'node:crypto'
+
+import type IORedis from 'ioredis'
+
+import { aiLogger } from '../config/logger'
+
+const DEFAULT_TTL_SECONDS = 3600
+
+export class EmbeddingCache {
+  constructor(
+    private redis: IORedis,
+    private ttlSeconds: number = DEFAULT_TTL_SECONDS,
+  ) {}
+
+  private buildKey(model: string, text: string): string {
+    const hash = createHash('sha256').update(text).digest('hex')
+    return `emb:${model}:${hash}`
+  }
+
+  async get(model: string, text: string): Promise<number[] | null> {
+    try {
+      const cached = await this.redis.getBuffer(this.buildKey(model, text))
+      if (!cached) return null
+      return JSON.parse(cached.toString()) as number[]
+    } catch (error) {
+      aiLogger.debug`Embedding cache get failed: ${error}`
+      return null
+    }
+  }
+
+  async set(model: string, text: string, embedding: number[]): Promise<void> {
+    try {
+      await this.redis.set(this.buildKey(model, text), JSON.stringify(embedding), 'EX', this.ttlSeconds)
+    } catch (error) {
+      aiLogger.debug`Embedding cache set failed: ${error}`
+    }
+  }
+}
+
+let embeddingCacheInstance: EmbeddingCache | null = null
+
+export function configureEmbeddingCache(redis: IORedis, ttlSeconds?: number): void {
+  embeddingCacheInstance = new EmbeddingCache(redis, ttlSeconds ?? DEFAULT_TTL_SECONDS)
+}
+
+export function getEmbeddingCache(): EmbeddingCache | null {
+  return embeddingCacheInstance
+}

package/src/config/background-processing.ts

@@ -0,0 +1,33 @@
+export interface BackgroundProcessingConfig {
+  memoryExtractionFrequency: number
+  skillExtractionFrequency: number
+  memoryDigestFrequency: number
+  memoryConsolidationFrequency: number
+}
+
+const DEFAULT_CONFIG: BackgroundProcessingConfig = {
+  memoryExtractionFrequency: 3,
+  skillExtractionFrequency: 5,
+  memoryDigestFrequency: 1,
+  memoryConsolidationFrequency: 10,
+}
+
+let resolvedConfig: BackgroundProcessingConfig = { ...DEFAULT_CONFIG }
+
+export function configureBackgroundProcessing(config?: Partial<BackgroundProcessingConfig>): void {
+  resolvedConfig = {
+    memoryExtractionFrequency: config?.memoryExtractionFrequency ?? DEFAULT_CONFIG.memoryExtractionFrequency,
+    skillExtractionFrequency: config?.skillExtractionFrequency ?? DEFAULT_CONFIG.skillExtractionFrequency,
+    memoryDigestFrequency: config?.memoryDigestFrequency ?? DEFAULT_CONFIG.memoryDigestFrequency,
+    memoryConsolidationFrequency: config?.memoryConsolidationFrequency ?? DEFAULT_CONFIG.memoryConsolidationFrequency,
+  }
+}
+
+export function getBackgroundProcessingConfig(): BackgroundProcessingConfig {
+  return resolvedConfig
+}
+
+export function shouldRunAtFrequency(turnCount: number, frequency: number): boolean {
+  if (frequency <= 1) return true
+  return turnCount > 0 && turnCount % frequency === 0
+}

package/src/config/env-shapes.ts

@@ -14,7 +14,6 @@ export const surrealDbEnvShape = {
   SURREALDB_USER: z.string().min(1, 'SurrealDB user is required'),
   SURREALDB_PASSWORD: z.string().min(1, 'SurrealDB password is required'),
   SURREALDB_NAMESPACE: z.string().min(1, 'SurrealDB namespace is required'),
-  SURREALDB_DATABASE: z.string().min(1, 'SurrealDB database is required'),
 } as const satisfies Record<string, ZodTypeAny>
 
 export const betterAuthEnvShape = {

package/src/config/model-constants.ts

@@ -22,6 +22,10 @@ export const OPENROUTER_XHIGH_REASONING_PROVIDER_OPTIONS = {
   openai: { forceReasoning: true, reasoningEffort: 'xhigh', reasoningSummary: 'auto' },
 } as const
 
+export const OPENROUTER_MEDIUM_REASONING_PROVIDER_OPTIONS = {
+  openai: { forceReasoning: true, reasoningEffort: 'medium', reasoningSummary: 'auto' },
+} as const
+
 export const OPENROUTER_LOW_REASONING_PROVIDER_OPTIONS = {
   openai: { forceReasoning: true, reasoningEffort: 'low', reasoningSummary: 'auto' },
 } as const

package/src/db/memory-store.ts

@@ -1,5 +1,7 @@
 import { BoundQuery, eq, inside } from 'surrealdb'
 
+import { getEmbeddingCache } from '../ai/embedding-cache'
+import { env } from '../config/env-shapes'
 import { aiLogger } from '../config/logger'
 import { DEFAULT_MEMORY_SEARCH_LIMIT } from '../config/search'
 import { createDefaultEmbeddings } from '../embeddings/provider'
@@ -7,7 +9,14 @@ import { memoryQueryBuilder } from './memory-query-builder'
 import type { RelationCounts } from './memory-store.helpers'
 import { hashContent, mapRowToMemoryRecord, processGraphAwareRows } from './memory-store.helpers'
 import type { BasicSearchRow, SurrealMemoryRow } from './memory-store.rows'
-import type { LinearNormalization, MemoryEvent, MemoryRecord, MemorySearchResult, RelationType } from './memory-types'
+import type {
+  LinearNormalization,
+  MemoryEvent,
+  MemoryListOptions,
+  MemoryRecord,
+  MemorySearchResult,
+  RelationType,
+} from './memory-types'
 import { ensureRecordId, recordIdToString } from './record-id'
 import type { RecordIdInput, RecordIdRef } from './record-id'
 import { databaseService } from './service'
@@ -33,6 +42,18 @@ export class SurrealMemoryStore {
 
   constructor(private embeddings: EmbeddingClient) {}
 
+  private toMetadataFieldPath(key: string): string {
+    const segments = key.split('.').map((segment) => segment.trim())
+    if (
+      segments.length === 0 ||
+      segments.some((segment) => segment.length === 0 || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(segment))
+    ) {
+      throw new Error(`Invalid memory metadata filter key: ${key}`)
+    }
+
+    return `metadata.${segments.join('.')}`
+  }
+
   private tokenizeQuery(query: string): string[] {
     return query
       .toLowerCase()
@@ -188,6 +209,7 @@ export class SurrealMemoryStore {
     const now = Date.now()
     this.pruneEmbeddingCache(now)
 
+    // L1: in-memory cache
     const cached = this.embeddingCache.get(cacheKey)
     if (cached && now - cached.ts <= EMBEDDING_CACHE_TTL_MS) {
       return cached.embedding
@@ -198,16 +220,32 @@ export class SurrealMemoryStore {
       return await inFlight
     }
 
-    const request = this.embeddings
-      .embedQuery(normalized)
-      .then((embedding) => {
-        this.embeddingCache.set(cacheKey, { embedding, ts: Date.now() })
-        this.pruneEmbeddingCache(Date.now())
-        return embedding
-      })
-      .finally(() => {
-        this.embeddingInFlight.delete(cacheKey)
-      })
+    const request = (async () => {
+      // L2: Redis cache
+      const redisCache = getEmbeddingCache()
+      if (redisCache) {
+        const model = env.AI_EMBEDDING_MODEL
+        const redisCached = await redisCache.get(model, normalized)
+        if (redisCached) {
+          this.embeddingCache.set(cacheKey, { embedding: redisCached, ts: Date.now() })
+          return redisCached
+        }
+      }
+
+      // L3: API call
+      const embedding = await this.embeddings.embedQuery(normalized)
+      this.embeddingCache.set(cacheKey, { embedding, ts: Date.now() })
+      this.pruneEmbeddingCache(Date.now())
+
+      // Backfill Redis
+      if (redisCache) {
+        void redisCache.set(env.AI_EMBEDDING_MODEL, normalized, embedding)
+      }
+
+      return embedding
+    })().finally(() => {
+      this.embeddingInFlight.delete(cacheKey)
+    })
 
     this.embeddingInFlight.set(cacheKey, request)
     return await request
@@ -558,6 +596,8 @@ export class SurrealMemoryStore {
     return processed
   }
 
+  private static HYBRID_SEARCH_TIMEOUT_MS = 2000
+
   async hybridSearchWeighted(
     query: string,
     options: {
@@ -569,6 +609,7 @@ export class SurrealMemoryStore {
       fastMode?: boolean
     },
   ): Promise<MemorySearchResult[]> {
+    const searchStart = performance.now()
     const queryEmbedding = await this.generateEmbedding(query)
 
     const tokens = this.tokenizeQuery(query)
@@ -601,7 +642,25 @@ export class SurrealMemoryStore {
 
     type LinearRow = BasicSearchRow & { linearScore: number }
 
-    const results = await this.queryFinalStatement<LinearRow>(sql, bindVars)
+    let results: LinearRow[]
+    try {
+      results = await Promise.race([
+        this.queryFinalStatement<LinearRow>(sql, bindVars),
+        new Promise<never>((_, reject) =>
+          setTimeout(() => reject(new Error('Hybrid search timeout')), SurrealMemoryStore.HYBRID_SEARCH_TIMEOUT_MS),
+        ),
+      ])
+    } catch {
+      const elapsed = performance.now() - searchStart
+      aiLogger.warn`Hybrid search timed out after ${elapsed.toFixed(0)}ms (scopeId: ${options.scopeId}). Falling back to vector-only.`
+      return this.vectorSearchWithEmbedding({
+        embedding: queryEmbedding,
+        scopeId: options.scopeId,
+        limit: options.limit,
+        memoryType: options.memoryType,
+        fastMode: options.fastMode,
+      })
+    }
 
     if (results.length === 0) {
       aiLogger.debug`Weighted hybrid search returned 0 raw results (scopeId: ${options.scopeId})`
@@ -644,7 +703,8 @@ export class SurrealMemoryStore {
       })
     }
 
-    aiLogger.info`[SUCCESS_WEIGHTED_SEARCH] Weighted hybrid search succeeded (scopeId: ${options.scopeId}, rawResults: ${results.length}, returned: ${processed.length}, weights: ${weights.join(',')}, normalization: ${normalization})`
+    const elapsed = performance.now() - searchStart
+    aiLogger.info`[SUCCESS_WEIGHTED_SEARCH] Weighted hybrid search succeeded (scopeId: ${options.scopeId}, rawResults: ${results.length}, returned: ${processed.length}, weights: ${weights.join(',')}, normalization: ${normalization}, latencyMs: ${elapsed.toFixed(0)})`
     this.touchMemories(processed.map((row) => row.id))
     return processed
   }
@@ -709,16 +769,47 @@ export class SurrealMemoryStore {
     await this.recordHistory(id, existing.content, null, 'DELETE')
   }
 
-  async list(scopeId: string, memoryType?: MemoryRecord['memoryType']): Promise<MemoryRecord[]> {
-    const typeFilter = memoryType ? 'AND memoryType = $memoryType' : ''
+  async list(options: MemoryListOptions): Promise<MemoryRecord[]> {
+    const whereClauses = [
+      'scopeId = $scopeId',
+      'archivedAt IS NONE',
+      '(validUntil IS NONE OR validUntil > time::now())',
+    ]
+    const bindVars: Record<string, unknown> = { scopeId: options.scopeId }
+
+    if (options.memoryType) {
+      whereClauses.push('memoryType = $memoryType')
+      bindVars.memoryType = options.memoryType
+    }
+
+    for (const [index, [key, value]] of Object.entries(options.metadataEquals ?? {}).entries()) {
+      const fieldPath = this.toMetadataFieldPath(key)
+      const bindKey = `metadataEquals_${index}`
+      whereClauses.push(`${fieldPath} = $${bindKey}`)
+      bindVars[bindKey] = value
+    }
+
+    for (const [index, [key, value]] of Object.entries(options.metadataNotEquals ?? {}).entries()) {
+      const fieldPath = this.toMetadataFieldPath(key)
+      const bindKey = `metadataNotEquals_${index}`
+      whereClauses.push(`(${fieldPath} IS NONE OR ${fieldPath} != $${bindKey})`)
+      bindVars[bindKey] = value
+    }
+
+    const sortDirection = options.sort === 'createdAtAsc' ? 'ASC' : 'DESC'
+    const limitClause = typeof options.limit === 'number' ? 'LIMIT $limit' : ''
+    if (typeof options.limit === 'number') {
+      bindVars.limit = options.limit
+    }
+
     const sql = `
       SELECT * FROM ${MEMORY_TABLE}
-      WHERE scopeId = $scopeId ${typeFilter}
-        AND archivedAt IS NONE AND (validUntil IS NONE OR validUntil > time::now())
-      ORDER BY createdAt DESC
+      WHERE ${whereClauses.join('\n        AND ')}
+      ORDER BY createdAt ${sortDirection}
+      ${limitClause}
     `
 
-    const results = await databaseService.query<SurrealMemoryRow>(new BoundQuery(sql, { scopeId, memoryType }))
+    const results = await databaseService.query<SurrealMemoryRow>(new BoundQuery(sql, bindVars))
 
     return results.map((row) => mapRowToMemoryRecord(row))
   }

package/src/db/memory-types.ts

@@ -55,6 +55,17 @@ export interface SearchOptions {
   pointInTime?: string
 }
 
+export type MemoryListScalar = boolean | null | number | string
+
+export interface MemoryListOptions {
+  scopeId: string
+  limit?: number
+  memoryType?: MemoryType
+  metadataEquals?: Record<string, MemoryListScalar>
+  metadataNotEquals?: Record<string, MemoryListScalar>
+  sort?: 'createdAtAsc' | 'createdAtDesc'
+}
+
 export type LinearNormalization = 'minmax' | 'zscore'
 
 export interface WeightedSearchOptions extends SearchOptions {

package/src/db/memory.ts

@@ -21,11 +21,13 @@ import type {
   Durability,
   ExtractedFact,
   MemoryConfig,
+  MemoryListOptions,
   MemorySearchResult,
   MemoryType,
   MemoryUpdateOutput,
   Message,
   MemoryRecord,
+  RelationType,
   SearchOptions,
   WeightedSearchOptions,
 } from './memory-types'
@@ -152,10 +154,18 @@ export class Memory {
     return await this.store.listTopMemories(options)
   }
 
+  async list(options: MemoryListOptions): Promise<MemoryRecord[]> {
+    return await this.store.list(options)
+  }
+
   async updateMemory(id: string, newContent: string): Promise<void> {
     await this.store.update(id, newContent)
   }
 
+  async addRelation(fromId: string, toId: string, relationType: RelationType, confidence = 1): Promise<void> {
+    await this.store.addRelation(fromId, toId, relationType, confidence)
+  }
+
   async getStaleMemories(scopeId: string, limit?: number): Promise<MemorySearchResult[]> {
     return await this.store.getStaleMemories(scopeId, limit)
   }
@@ -237,7 +247,7 @@ export class Memory {
   private async prepareFactsForScope(facts: ExtractedFact[], options: AddOptions): Promise<PreparedScopeUpdate> {
     const factMaps = buildMemoryFactMaps(facts)
 
-    const existingMemories = await this.store.list(options.scopeId, options.memoryType)
+    const existingMemories = await this.store.list({ scopeId: options.scopeId, memoryType: options.memoryType })
     const oldMemoryFormat = existingMemories.map((m) => ({ id: m.id, text: m.content }))
 
     const factContents = facts.map((f) => f.content)

package/src/db/schema-fingerprint.ts

@@ -0,0 +1,21 @@
+import { createHash } from 'node:crypto'
+
+function toSchemaFilePath(value: string | URL): string {
+  return value instanceof URL ? value.pathname : value
+}
+
+export async function computeSchemaFingerprint(schemaFiles: readonly (string | URL)[]): Promise<string> {
+  const hash = createHash('sha256')
+
+  for (const schemaFile of schemaFiles) {
+    const sortKey = toSchemaFilePath(schemaFile)
+    const file = schemaFile instanceof URL ? Bun.file(schemaFile.pathname) : Bun.file(schemaFile)
+
+    hash.update(sortKey)
+    hash.update('\0')
+    hash.update((await file.text()).trim())
+    hash.update('\0')
+  }
+
+  return hash.digest('hex')
+}

package/src/db/sdk-database.ts

@@ -0,0 +1 @@
+export const LOTA_SDK_DATABASE_NAME = 'lotasdk'

package/src/db/service.ts

@@ -926,7 +926,3 @@ export function setDatabaseService(db: SurrealDBService): void {
 
   currentDatabaseService = db
 }
-
-export function getDatabaseService(): SurrealDBService | undefined {
-  return currentDatabaseService
-}

package/src/db/tables.ts

@@ -11,8 +11,8 @@ export const TABLES = {
   PLAN_TASK: 'planTask',
   PLAN_EVENT: 'planEvent',
   ORGANIZATION: 'organization',
+  ORGANIZATION_MEMBER: 'organizationMember',
   USER: 'user',
-  ORG_ACTION: 'orgAction',
   RECENT_ACTIVITY_EVENT: 'recentActivityEvent',
   RECENT_ACTIVITY: 'recentActivity',
 } as const