@lota-sdk/core 0.1.14 → 0.1.16

package/src/db/memory-store.ts

@@ -3,6 +3,8 @@ import { BoundQuery, eq, inside } from 'surrealdb'
 import { aiLogger } from '../config/logger'
 import { DEFAULT_MEMORY_SEARCH_LIMIT } from '../config/search'
 import { getDefaultEmbeddings } from '../embeddings/provider'
+import { withTimeout } from '../utils/async'
+import { clampImportance, truncateText } from '../utils/string'
 import { memoryQueryBuilder } from './memory-query-builder'
 import type { RelationCounts } from './memory-store.helpers'
 import { hashContent, mapRowToMemoryRecord, processGraphAwareRows } from './memory-store.helpers'
@@ -24,6 +26,10 @@ const MEMORY_TABLE = TABLES.MEMORY
 const MEMORY_HISTORY_TABLE = TABLES.MEMORY_HISTORY
 const MEMORY_RELATION_TABLE = TABLES.MEMORY_RELATION
 const MIN_RELEVANCE_SCORE = 0.25
+const STRONG_GRAPH_BOOSTS = { support: 0.1, contradict: 0.2 } as const
+const WEAK_GRAPH_BOOSTS = { support: 0.05, contradict: 0.1 } as const
+const CANDIDATE_FANOUT_MULTIPLIER = 4
+const CANDIDATE_SLICE_FLOOR = 50
 const TOUCH_MEMORIES_MAX_ATTEMPTS = 4
 const TOUCH_MEMORIES_RETRY_BASE_DELAY_MS = 25
 const TOUCH_MEMORIES_RETRY_JITTER_MS = 20
@@ -88,7 +94,7 @@ export class SurrealMemoryStore {
       LIMIT $limit
     `
 
-    return await databaseService.query<BasicSearchRow>(
+    return databaseService.query<BasicSearchRow>(
       new BoundQuery(sql, { scopeId: options.scopeId, memoryType: options.memoryType, limit: options.limit }),
     )
   }
@@ -153,7 +159,7 @@ export class SurrealMemoryStore {
       relationCounts,
       options.limit,
       (row) => 1 / (1 + row.distance),
-      { support: 0.1, contradict: 0.2 },
+      STRONG_GRAPH_BOOSTS,
       MIN_RELEVANCE_SCORE,
     )
 
@@ -180,7 +186,7 @@ export class SurrealMemoryStore {
     const normalized = content.trim()
     if (!normalized) return []
 
-    return await this.embeddings.embedQuery(normalized)
+    return this.embeddings.embedQuery(normalized)
   }
 
   async warmEmbedding(content: string): Promise<void> {
@@ -317,7 +323,7 @@ export class SurrealMemoryStore {
         if (b.textScore !== a.textScore) return b.textScore - a.textScore
         return a.index - b.index
       })
-      .slice(0, Math.max(options.limit * 4, 50))
+      .slice(0, Math.max(options.limit * CANDIDATE_FANOUT_MULTIPLIER, CANDIDATE_SLICE_FLOOR))
 
     if (options.fastMode) {
       return this.mapFastRows(scoredRows, options.limit, (row) => row.textScore)
@@ -330,7 +336,7 @@ export class SurrealMemoryStore {
       recentRelationCounts,
       options.limit,
       (row) => row.textScore,
-      { support: 0.05, contradict: 0.1 },
+      WEAK_GRAPH_BOOSTS,
       MIN_RELEVANCE_SCORE,
     )
 
@@ -351,11 +357,11 @@ export class SurrealMemoryStore {
     const hash = hashContent(content, scopeId, memoryType)
     const embedding = await this.generateEmbedding(content)
 
-    importance = Math.max(0, Math.min(1, importance))
+    importance = clampImportance(importance)
 
     const nearDup = await this.findNearDuplicate(embedding, scopeId, content)
     if (nearDup) {
-      const mergedImportance = Math.max(0, Math.min(1, Math.max(nearDup.importance, importance)))
+      const mergedImportance = clampImportance(Math.max(nearDup.importance, importance))
       const keepNew = content.length >= nearDup.content.length
       const winnerContent = keepNew ? content : nearDup.content
       await this.update(nearDup.id, winnerContent, { importance: mergedImportance })
@@ -483,7 +489,7 @@ export class SurrealMemoryStore {
       relationCounts,
       limit,
       (row) => 1 / (1 + row.distance),
-      { support: 0.1, contradict: 0.2 },
+      STRONG_GRAPH_BOOSTS,
       MIN_RELEVANCE_SCORE,
     )
 
@@ -520,7 +526,7 @@ export class SurrealMemoryStore {
       relationCounts,
       limit,
       (row) => row.rrfScore,
-      { support: 0.05, contradict: 0.1 },
+      WEAK_GRAPH_BOOSTS,
       MIN_RELEVANCE_SCORE,
     )
 
@@ -576,12 +582,11 @@ export class SurrealMemoryStore {
 
     let results: LinearRow[]
     try {
-      results = await Promise.race([
+      results = await withTimeout(
         this.queryFinalStatement<LinearRow>(sql, bindVars),
-        new Promise<never>((_, reject) =>
-          setTimeout(() => reject(new Error('Hybrid search timeout')), SurrealMemoryStore.HYBRID_SEARCH_TIMEOUT_MS),
-        ),
-      ])
+        SurrealMemoryStore.HYBRID_SEARCH_TIMEOUT_MS,
+        'Hybrid search',
+      )
     } 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.`
@@ -619,7 +624,7 @@ export class SurrealMemoryStore {
       relationCounts,
       options.limit,
       (row) => row.linearScore,
-      { support: 0.05, contradict: 0.1 },
+      WEAK_GRAPH_BOOSTS,
       MIN_RELEVANCE_SCORE,
     )
 
@@ -665,18 +670,13 @@ export class SurrealMemoryStore {
 
     const importance =
       typeof options?.importance === 'number'
-        ? Math.max(existing.importance, Math.max(0, Math.min(1, options.importance)))
+        ? Math.max(existing.importance, clampImportance(options.importance))
         : undefined
 
     const durability = options?.durability
     const metadata = options?.metadata ? { ...existing.metadata, ...options.metadata } : undefined
 
-    const updatePayload: Record<string, unknown> = {
-      content: newContent,
-      embedding: newEmbedding,
-      hash: newHash,
-      updatedAt: new Date(),
-    }
+    const updatePayload: Record<string, unknown> = { content: newContent, embedding: newEmbedding, hash: newHash }
     if (importance !== undefined) {
       updatePayload.importance = importance
     }
@@ -756,7 +756,7 @@ export class SurrealMemoryStore {
   }
 
   async addRelation(fromId: string, toId: string, relationType: RelationType, confidence: number = 1.0): Promise<void> {
-    confidence = Math.max(0, Math.min(1, confidence))
+    confidence = clampImportance(confidence)
     const fromRef = ensureRecordId(fromId, TABLES.MEMORY)
     const toRef = ensureRecordId(toId, TABLES.MEMORY)
     await databaseService.relate(fromRef, MEMORY_RELATION_TABLE, toRef, { relationType, confidence })
@@ -949,7 +949,7 @@ export class SurrealMemoryStore {
         if (!neighbor.content || seen.has(neighborId)) continue
         seen.add(neighborId)
         const label = neighbor.relationType ? `[${neighbor.relationType}]` : ''
-        const truncated = neighbor.content.length > 200 ? `${neighbor.content.slice(0, 197)}...` : neighbor.content
+        const truncated = truncateText(neighbor.content, 200)
         contexts.push(`${label} ${truncated}`.trim())
       }
       if (contexts.length > 0) {

package/src/db/memory.ts

@@ -12,6 +12,7 @@ import { getFactRetrievalMessages } from '../runtime/memory-prompts-fact'
 import { parseMessages } from '../runtime/memory-prompts-parse'
 import { getClassifyMemoryDeltaPrompt } from '../runtime/memory-prompts-update'
 import { getRuntimeConfig } from '../runtime/runtime-config'
+import { compactWhitespace, truncateText } from '../utils/string'
 import type { SurrealMemoryStore } from './memory-store'
 import { getDefaultMemoryStore } from './memory-store'
 import { hashContent, isUniqueIndexConflict } from './memory-store.helpers'
@@ -39,6 +40,7 @@ const MEMORY_DELTA_MAX_CANDIDATE_MEMORIES = 80
 const MEMORY_DELTA_MAX_CANDIDATES_PER_FACT = 10
 const MEMORY_DELTA_MIN_BASELINE_CANDIDATES = 12
 const MEMORY_DELTA_MEMORY_TEXT_MAX_CHARS = 400
+const CANDIDATE_FANOUT_MULTIPLIER = 4
 const helperModelRuntime = createHelperModelRuntime()
 
 interface PreparedScopeUpdate {
@@ -80,7 +82,7 @@ export class Memory {
       durability?: Durability
     },
   ): Promise<string> {
-    return await this.store.insert(
+    return this.store.insert(
       content,
       options.scopeId,
       options.memoryType,
@@ -135,7 +137,7 @@ export class Memory {
       return results
     }
 
-    return await this.store.enrichWithNeighbors(results)
+    return this.store.enrichWithNeighbors(results)
   }
 
   async listTopMemories(options: {
@@ -145,11 +147,11 @@ export class Memory {
     durability?: Durability
     minImportance?: number
   }): Promise<MemoryRecord[]> {
-    return await this.store.listTopMemories(options)
+    return this.store.listTopMemories(options)
   }
 
   async list(options: MemoryListOptions): Promise<MemoryRecord[]> {
-    return await this.store.list(options)
+    return this.store.list(options)
   }
 
   async updateMemory(id: string, newContent: string): Promise<void> {
@@ -161,7 +163,7 @@ export class Memory {
   }
 
   async getStaleMemories(scopeId: string, limit?: number): Promise<MemorySearchResult[]> {
-    return await this.store.getStaleMemories(scopeId, limit)
+    return this.store.getStaleMemories(scopeId, limit)
   }
 
   async add(
@@ -242,12 +244,12 @@ export class Memory {
     const factMaps = buildMemoryFactMaps(facts)
 
     const existingMemories = await this.store.list({ scopeId: options.scopeId, memoryType: options.memoryType })
-    const oldMemoryFormat = existingMemories.map((m) => ({ id: m.id, text: m.content }))
+    const memoryDeltaInput = existingMemories.map((m) => ({ id: m.id, text: m.content }))
 
     const factContents = facts.map((f) => f.content)
-    const updates = await this.determineUpdates(oldMemoryFormat, factContents)
+    const updates = await this.determineUpdates(memoryDeltaInput, factContents)
 
-    return { options, updates, factMaps, existingMemories: oldMemoryFormat }
+    return { options, updates, factMaps, existingMemories: memoryDeltaInput }
   }
 
   private async extractFacts(
@@ -277,7 +279,7 @@ export class Memory {
         typeof extractionOptions?.maxFacts === 'number' ? { maxFacts: extractionOptions.maxFacts } : {},
       )
     } catch (error) {
-      aiLogger.error`Failed to extract facts: ${error}`
+      aiLogger.warn`Failed to extract facts: ${error}`
       return []
     }
   }
@@ -313,10 +315,10 @@ export class Memory {
   }
 
   private normalizeMemoryDeltaText(value: string, maxChars?: number): string {
-    const normalized = value.replace(/\s+/g, ' ').trim()
+    const normalized = compactWhitespace(value)
     if (!normalized) return ''
-    if (typeof maxChars !== 'number' || normalized.length <= maxChars) return normalized
-    return `${normalized.slice(0, maxChars - 3)}...`
+    if (typeof maxChars !== 'number') return normalized
+    return truncateText(normalized, maxChars)
   }
 
   private tokenizeMemoryDeltaText(value: string): string[] {
@@ -384,7 +386,7 @@ export class Memory {
     const targetCandidateCount = Math.min(MEMORY_DELTA_MAX_CANDIDATE_MEMORIES, normalizedExisting.length)
     const baselineCount = Math.min(
       targetCandidateCount,
-      Math.max(MEMORY_DELTA_MIN_BASELINE_CANDIDATES, newFacts.length * 4),
+      Math.max(MEMORY_DELTA_MIN_BASELINE_CANDIDATES, newFacts.length * CANDIDATE_FANOUT_MULTIPLIER),
     )
 
     const selectedIds = new Set<string>(
@@ -440,7 +442,7 @@ export class Memory {
     for (const action of plan.actions) {
       switch (action.type) {
         case 'add': {
-          const truncatedContent = action.text.length > 50 ? `${action.text.slice(0, 50)}...` : action.text
+          const truncatedContent = truncateText(action.text, 50)
           const metadata = { ...options.metadata, memoryCategory: action.category }
           const hash = hashContent(action.text, options.scopeId, options.memoryType)
           let newId: string
@@ -481,7 +483,7 @@ export class Memory {
             metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
           })
           idMap.set(action.refId, action.refId)
-          aiLogger.debug`Updated memory ${action.refId}: ${action.text.slice(0, 50)}...`
+          aiLogger.debug`Updated memory ${action.refId}: ${truncateText(action.text, 50)}`
           break
         }
 
@@ -502,7 +504,7 @@ export class Memory {
         await this.store.addRelation(fromId, toId, relation.relation)
         aiLogger.debug`Created ${relation.relation} relation: ${fromId} -> ${toId}`
       } catch (error) {
-        aiLogger.warn`Failed to create relation: ${error}`
+        aiLogger.warn`Failed to create memory relation (non-fatal, graph may be incomplete): ${error}`
       }
     }
   }

package/src/db/schema-fingerprint.ts

@@ -7,6 +7,7 @@ function toSchemaFilePath(value: string | URL): string {
 export async function computeSchemaFingerprint(schemaFiles: readonly (string | URL)[]): Promise<string> {
   const hash = createHash('sha256')
 
+  // Sequential reads required: hash must be computed in deterministic file order
   for (const schemaFile of schemaFiles) {
     const sortKey = toSchemaFilePath(schemaFile)
     const file = schemaFile instanceof URL ? Bun.file(schemaFile.pathname) : Bun.file(schemaFile)