@lota-sdk/core 0.1.5

package/src/db/memory-store.ts

@@ -0,0 +1,974 @@
+import { BoundQuery, eq, inside } from 'surrealdb'
+
+import { aiLogger } from '../config/logger'
+import { DEFAULT_MEMORY_SEARCH_LIMIT } from '../config/search'
+import { createDefaultEmbeddings } from '../embeddings/provider'
+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 { ensureRecordId, recordIdToString } from './record-id'
+import type { RecordIdInput, RecordIdRef } from './record-id'
+import { databaseService } from './service'
+import { TABLES } from './tables'
+
+const MEMORY_TABLE = TABLES.MEMORY
+const MEMORY_HISTORY_TABLE = TABLES.MEMORY_HISTORY
+const MEMORY_RELATION_TABLE = TABLES.MEMORY_RELATION
+const EMBEDDING_CACHE_TTL_MS = 5 * 60 * 1000
+const EMBEDDING_CACHE_MAX_ENTRIES = 64
+const MIN_RELEVANCE_SCORE = 0.25
+const TOUCH_MEMORIES_MAX_ATTEMPTS = 4
+const TOUCH_MEMORIES_RETRY_BASE_DELAY_MS = 25
+const TOUCH_MEMORIES_RETRY_JITTER_MS = 20
+
+interface EmbeddingClient {
+  embedQuery(text: string): Promise<number[]>
+}
+
+export class SurrealMemoryStore {
+  private embeddingCache = new Map<string, { embedding: number[]; ts: number }>()
+  private embeddingInFlight = new Map<string, Promise<number[]>>()
+
+  constructor(private embeddings: EmbeddingClient) {}
+
+  private tokenizeQuery(query: string): string[] {
+    return query
+      .toLowerCase()
+      .split(/\s+/)
+      .map((token) => token.trim())
+      .filter((token) => token.length >= 3)
+      .slice(0, 12)
+  }
+
+  private scoreTextMatch(content: string, tokens: string[], fullQuery: string): number {
+    if (!content) return 0
+    const haystack = content.toLowerCase()
+    let score = 0
+
+    const normalizedQuery = fullQuery.trim().toLowerCase()
+    if (normalizedQuery.length >= 3 && haystack.includes(normalizedQuery)) {
+      score += 3
+    }
+
+    for (const token of tokens) {
+      if (haystack.includes(token)) score += 1
+    }
+
+    return score
+  }
+
+  private async listRecentBasic(options: {
+    scopeId: string
+    limit: number
+    memoryType?: MemoryRecord['memoryType']
+  }): Promise<BasicSearchRow[]> {
+    const typeFilter = options.memoryType ? 'AND memoryType = $memoryType' : ''
+    const sql = `
+      SELECT id, content, metadata, createdAt
+      FROM ${MEMORY_TABLE}
+      WHERE scopeId = $scopeId ${typeFilter}
+        AND archivedAt IS NONE AND (validUntil IS NONE OR validUntil > time::now())
+      ORDER BY createdAt DESC
+      LIMIT $limit
+    `
+
+    return await databaseService.query<BasicSearchRow>(
+      new BoundQuery(sql, { scopeId: options.scopeId, memoryType: options.memoryType, limit: options.limit }),
+    )
+  }
+
+  async listTopMemories(options: {
+    scopeId: string
+    limit: number
+    memoryType?: MemoryRecord['memoryType']
+    durability?: MemoryRecord['durability']
+    minImportance?: number
+  }): Promise<MemoryRecord[]> {
+    const typeFilter = options.memoryType ? 'AND memoryType = $memoryType' : ''
+    const durabilityFilter = options.durability ? 'AND durability = $durability' : ''
+    const importanceFilter = typeof options.minImportance === 'number' ? 'AND importance >= $minImportance' : ''
+    const sql = `
+      SELECT *
+      FROM ${MEMORY_TABLE}
+      WHERE scopeId = $scopeId ${typeFilter} ${durabilityFilter} ${importanceFilter}
+        AND archivedAt IS NONE AND (validUntil IS NONE OR validUntil > time::now())
+      ORDER BY importance DESC, accessCount DESC, lastAccessedAt DESC, createdAt DESC
+      LIMIT $limit
+    `
+
+    const rows = await databaseService.query<SurrealMemoryRow>(
+      new BoundQuery(sql, {
+        scopeId: options.scopeId,
+        memoryType: options.memoryType,
+        durability: options.durability,
+        minImportance: options.minImportance,
+        limit: options.limit,
+      }),
+    )
+
+    return rows.map((row) => mapRowToMemoryRecord(row))
+  }
+
+  private async vectorSearchWithEmbedding(options: {
+    embedding: number[]
+    scopeId: string
+    limit: number
+    memoryType?: MemoryRecord['memoryType']
+    fastMode?: boolean
+  }): Promise<MemorySearchResult[]> {
+    const { sql, bindVars } = memoryQueryBuilder.buildVectorSearch({
+      embedding: options.embedding,
+      scopeId: options.scopeId,
+      limit: options.limit,
+      memoryType: options.memoryType,
+    })
+
+    const results = await this.queryFinalStatement<BasicSearchRow & { distance: number }>(sql, bindVars)
+    if (results.length === 0) return []
+    if (options.fastMode) {
+      return this.mapFastRows(results, options.limit, (row) => 1 / (1 + row.distance))
+    }
+
+    const memoryIds = results.map((row) => row.id)
+    const relationCounts = await this.fetchRelationCountsBatch(memoryIds)
+
+    const processed = processGraphAwareRows(
+      results,
+      relationCounts,
+      options.limit,
+      (row) => 1 / (1 + row.distance),
+      { support: 0.1, contradict: 0.2 },
+      MIN_RELEVANCE_SCORE,
+    )
+
+    this.touchMemories(processed.map((row) => row.id))
+    return processed
+  }
+
+  private mapFastRows<T extends BasicSearchRow>(
+    rows: T[],
+    limit: number,
+    scoreResolver: (row: T, index: number) => number,
+  ): MemorySearchResult[] {
+    return rows
+      .slice(0, limit)
+      .map((row, index) => ({
+        id: recordIdToString(row.id, TABLES.MEMORY),
+        content: row.content,
+        score: scoreResolver(row, index),
+        metadata: row.metadata,
+      }))
+  }
+
+  private getEmbeddingCacheKey(content: string): string {
+    return content.trim().toLowerCase()
+  }
+
+  private pruneEmbeddingCache(now: number): void {
+    for (const [cacheKey, entry] of this.embeddingCache.entries()) {
+      if (now - entry.ts > EMBEDDING_CACHE_TTL_MS) {
+        this.embeddingCache.delete(cacheKey)
+      }
+    }
+
+    while (this.embeddingCache.size > EMBEDDING_CACHE_MAX_ENTRIES) {
+      const oldest = this.embeddingCache.keys().next().value
+      if (!oldest) break
+      this.embeddingCache.delete(oldest)
+    }
+  }
+
+  private async generateEmbedding(content: string): Promise<number[]> {
+    const normalized = content.trim()
+    if (!normalized) return []
+
+    const cacheKey = this.getEmbeddingCacheKey(normalized)
+    const now = Date.now()
+    this.pruneEmbeddingCache(now)
+
+    const cached = this.embeddingCache.get(cacheKey)
+    if (cached && now - cached.ts <= EMBEDDING_CACHE_TTL_MS) {
+      return cached.embedding
+    }
+
+    const inFlight = this.embeddingInFlight.get(cacheKey)
+    if (inFlight) {
+      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)
+      })
+
+    this.embeddingInFlight.set(cacheKey, request)
+    return await request
+  }
+
+  async warmEmbedding(content: string): Promise<void> {
+    await this.generateEmbedding(content)
+  }
+
+  private async fetchRelationCountsBatch(memoryIds: RecordIdInput[]): Promise<Map<string, RelationCounts>> {
+    if (memoryIds.length === 0) {
+      return new Map()
+    }
+
+    const memoryRefs = memoryIds.map((id) => ensureRecordId(id, TABLES.MEMORY))
+
+    const sql = `
+      SELECT
+        id,
+        count(<-${MEMORY_RELATION_TABLE}[WHERE relationType = 'supersedes']) AS supersedeCount,
+        count(<-${MEMORY_RELATION_TABLE}[WHERE relationType = 'contradicts']) AS contradictCount,
+        count(<-${MEMORY_RELATION_TABLE}[WHERE relationType = 'supports']) AS supportCount,
+        <-${MEMORY_RELATION_TABLE}[WHERE relationType = 'contradicts']<-${MEMORY_TABLE}.content AS contradictionTexts
+      FROM ${MEMORY_TABLE}
+      WHERE id IN $memoryIds
+    `
+
+    const results = await databaseService.query<{
+      id: RecordIdInput
+      supersedeCount: number
+      contradictCount: number
+      supportCount: number
+      contradictionTexts: string[] | null
+    }>(new BoundQuery(sql, { memoryIds: memoryRefs }))
+
+    const countsMap = new Map<string, RelationCounts>()
+    for (const row of results) {
+      const rawTexts = row.contradictionTexts ?? []
+      const contradictions = rawTexts.filter((text): text is string => typeof text === 'string' && text.length > 0)
+      countsMap.set(recordIdToString(row.id, TABLES.MEMORY), {
+        supersedeCount: row.supersedeCount,
+        contradictCount: row.contradictCount,
+        supportCount: row.supportCount,
+        contradictions,
+      })
+    }
+
+    return countsMap
+  }
+
+  private touchMemories(memoryIds: string[]): void {
+    if (memoryIds.length === 0) return
+    const uniqueIds = [...new Set(memoryIds)]
+    const memoryRefs = uniqueIds.map((id) => ensureRecordId(id, TABLES.MEMORY))
+    const sql = `
+      UPDATE ${MEMORY_TABLE}
+      SET accessCount += 1, lastAccessedAt = time::now()
+      WHERE id IN $memoryIds
+    `
+    const query = new BoundQuery(sql, { memoryIds: memoryRefs })
+
+    void this.runTouchMemoriesWithRetry(query)
+  }
+
+  private async runTouchMemoriesWithRetry(query: BoundQuery): Promise<void> {
+    for (let attempt = 1; attempt <= TOUCH_MEMORIES_MAX_ATTEMPTS; attempt += 1) {
+      try {
+        await databaseService.query(query)
+        return
+      } catch (error) {
+        const retriable = this.isRetriableTransactionConflict(error)
+        const hasMoreAttempts = attempt < TOUCH_MEMORIES_MAX_ATTEMPTS
+        if (!retriable || !hasMoreAttempts) {
+          aiLogger.warn`Failed to update memory access counters after ${attempt} attempt(s): ${error}`
+          return
+        }
+
+        const backoffMs =
+          TOUCH_MEMORIES_RETRY_BASE_DELAY_MS * 2 ** (attempt - 1) +
+          Math.floor(Math.random() * TOUCH_MEMORIES_RETRY_JITTER_MS)
+        await Bun.sleep(backoffMs)
+      }
+    }
+  }
+
+  private isRetriableTransactionConflict(error: unknown): boolean {
+    if (!(error instanceof Error)) return false
+    const message = error.message.toLowerCase()
+    return message.includes('transaction conflict') || message.includes('this transaction can be retried')
+  }
+
+  private async queryFinalStatement<T>(sql: string, bindVars: Record<string, unknown>): Promise<T[]> {
+    const statements = await databaseService.queryAll<unknown>(new BoundQuery(sql, bindVars))
+    const finalStatement = statements.at(-1)
+    return Array.isArray(finalStatement) ? (finalStatement as T[]) : []
+  }
+
+  private async fallbackWeightedSearch(
+    query: string,
+    tokens: string[],
+    options: {
+      embedding: number[]
+      scopeId: string
+      limit: number
+      memoryType?: MemoryRecord['memoryType']
+      reason: string
+      fastMode?: boolean
+    },
+  ): Promise<MemorySearchResult[]> {
+    aiLogger.debug`Weighted hybrid search fallback to vector/recent (scopeId: ${options.scopeId}, reason: ${options.reason})`
+    const vectorResults = await this.vectorSearchWithEmbedding({
+      embedding: options.embedding,
+      scopeId: options.scopeId,
+      limit: options.limit,
+      memoryType: options.memoryType,
+      fastMode: options.fastMode,
+    })
+
+    if (vectorResults.length > 0) {
+      return vectorResults
+    }
+
+    const recentLimit = Math.max(50, options.limit * 10)
+    const recent = await this.listRecentBasic({
+      scopeId: options.scopeId,
+      limit: recentLimit,
+      memoryType: options.memoryType,
+    })
+
+    if (recent.length === 0) {
+      return []
+    }
+
+    const scoredRows = recent
+      .map((row, index) => ({ ...row, index, textScore: this.scoreTextMatch(row.content, tokens, query) }))
+      .sort((a, b) => {
+        if (b.textScore !== a.textScore) return b.textScore - a.textScore
+        return a.index - b.index
+      })
+      .slice(0, Math.max(options.limit * 4, 50))
+
+    if (options.fastMode) {
+      return this.mapFastRows(scoredRows, options.limit, (row) => row.textScore)
+    }
+
+    const recentIds = scoredRows.map((row) => row.id)
+    const recentRelationCounts = await this.fetchRelationCountsBatch(recentIds)
+    const processed = processGraphAwareRows(
+      scoredRows,
+      recentRelationCounts,
+      options.limit,
+      (row) => row.textScore,
+      { support: 0.05, contradict: 0.1 },
+      MIN_RELEVANCE_SCORE,
+    )
+
+    this.touchMemories(processed.map((row) => row.id))
+    return processed
+  }
+
+  private static WRITE_DEDUP_THRESHOLD = 0.9
+
+  async insert(
+    content: string,
+    scopeId: string,
+    memoryType: MemoryRecord['memoryType'],
+    metadata: Record<string, unknown> = {},
+    importance: number = 1,
+    durability: MemoryRecord['durability'] = 'standard',
+  ): Promise<string> {
+    const hash = hashContent(content, scopeId, memoryType)
+    const embedding = await this.generateEmbedding(content)
+
+    importance = Math.max(0, Math.min(1, 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 keepNew = content.length >= nearDup.content.length
+      const winnerContent = keepNew ? content : nearDup.content
+      await this.update(nearDup.id, winnerContent, { importance: mergedImportance })
+      aiLogger.debug`Write-time dedup: merged into existing memory ${nearDup.id} (similarity: ${nearDup.similarity.toFixed(3)})`
+      return nearDup.id
+    }
+
+    const result = await databaseService.insert<{ id: RecordIdInput }>(MEMORY_TABLE, {
+      content,
+      embedding,
+      hash,
+      scopeId,
+      memoryType,
+      metadata,
+      importance,
+      durability,
+    })
+
+    const id = result[0]?.id ? recordIdToString(result[0].id, TABLES.MEMORY) : ''
+
+    await this.recordHistory(id, null, content, 'ADD')
+
+    return id
+  }
+
+  async getByHash(hash: string): Promise<MemoryRecord | null> {
+    const rows = await databaseService.query<SurrealMemoryRow>(
+      new BoundQuery(
+        `
+          SELECT *
+          FROM ${MEMORY_TABLE}
+          WHERE hash = $hash
+          LIMIT 1
+        `,
+        { hash },
+      ),
+    )
+
+    const row = rows.at(0)
+    return row ? mapRowToMemoryRecord(row) : null
+  }
+
+  private async findNearDuplicate(
+    embedding: number[],
+    scopeId: string,
+    content: string,
+  ): Promise<{ id: string; content: string; importance: number; similarity: number } | null> {
+    const candidateLimit = 12
+    const sql = `
+      LET $candidateRows = (
+        SELECT
+          id,
+          vector::distance::knn() AS distance
+        FROM ${MEMORY_TABLE}
+        WHERE scopeId = $scopeId
+          AND archivedAt IS NONE
+          AND embedding <|${candidateLimit}|> $embedding
+        ORDER BY distance ASC
+        LIMIT ${candidateLimit}
+      );
+
+      SELECT
+        id,
+        content,
+        importance,
+        vector::similarity::cosine(embedding, $embedding) AS similarity
+      FROM ${MEMORY_TABLE}
+      WHERE id IN $candidateRows.id
+      ORDER BY similarity DESC
+      LIMIT ${candidateLimit}
+    `
+
+    const neighborRows = await this.queryFinalStatement<{
+      id: RecordIdInput
+      content: string
+      importance: number
+      similarity: number
+    }>(sql, { scopeId, embedding })
+    const neighbors = neighborRows.map((row) => ({ ...row, id: recordIdToString(row.id, TABLES.MEMORY) }))
+
+    for (const neighbor of neighbors) {
+      if (neighbor.similarity < SurrealMemoryStore.WRITE_DEDUP_THRESHOLD) break
+      const [shorter, longer] =
+        content.length <= neighbor.content.length ? [content, neighbor.content] : [neighbor.content, content]
+      const a = shorter.toLowerCase().trim()
+      const b = longer.toLowerCase().trim()
+      if (b.includes(a)) return neighbor
+      const aWords = new Set(a.split(/\s+/))
+      const bWords = new Set(b.split(/\s+/))
+      let overlap = 0
+      for (const word of aWords) {
+        if (bWords.has(word)) overlap++
+      }
+      if (aWords.size > 0 && overlap / aWords.size >= 0.8) return neighbor
+    }
+
+    return null
+  }
+
+  async search(
+    query: string,
+    scopeId: string,
+    limit: number = DEFAULT_MEMORY_SEARCH_LIMIT,
+    memoryType?: MemoryRecord['memoryType'],
+  ): Promise<MemorySearchResult[]> {
+    aiLogger.debug`Memory store search (scopeId: ${scopeId}, memoryType: ${memoryType}, limit: ${limit})`
+    const queryEmbedding = await this.generateEmbedding(query)
+
+    const { sql, bindVars } = memoryQueryBuilder.buildVectorSearch({
+      embedding: queryEmbedding,
+      scopeId,
+      limit,
+      memoryType,
+    })
+
+    const results = await this.queryFinalStatement<BasicSearchRow & { distance: number }>(sql, bindVars)
+
+    aiLogger.debug`Memory store search raw results: ${results.length} rows found`
+
+    const memoryIds = results.map((row) => row.id)
+    const relationCounts = await this.fetchRelationCountsBatch(memoryIds)
+
+    const processed = processGraphAwareRows(
+      results,
+      relationCounts,
+      limit,
+      (row) => 1 / (1 + row.distance),
+      { support: 0.1, contradict: 0.2 },
+      MIN_RELEVANCE_SCORE,
+    )
+
+    aiLogger.debug`Memory store search final results: ${processed.length} memories after filtering`
+    this.touchMemories(processed.map((row) => row.id))
+    return processed
+  }
+
+  async hybridSearch(
+    query: string,
+    scopeId: string,
+    limit: number = DEFAULT_MEMORY_SEARCH_LIMIT,
+    memoryType?: MemoryRecord['memoryType'],
+  ): Promise<MemorySearchResult[]> {
+    const queryEmbedding = await this.generateEmbedding(query)
+
+    const { sql, bindVars } = memoryQueryBuilder.buildHybridSearch({
+      query,
+      embedding: queryEmbedding,
+      scopeId,
+      limit,
+      memoryType,
+    })
+
+    type RrfRow = BasicSearchRow & { rrfScore: number }
+
+    const results = await this.queryFinalStatement<RrfRow>(sql, bindVars)
+
+    const memoryIds = results.map((row) => row.id)
+    const relationCounts = await this.fetchRelationCountsBatch(memoryIds)
+
+    const processed = processGraphAwareRows(
+      results,
+      relationCounts,
+      limit,
+      (row) => row.rrfScore,
+      { support: 0.05, contradict: 0.1 },
+      MIN_RELEVANCE_SCORE,
+    )
+
+    this.touchMemories(processed.map((row) => row.id))
+    return processed
+  }
+
+  async hybridSearchWeighted(
+    query: string,
+    options: {
+      scopeId: string
+      limit: number
+      memoryType?: MemoryRecord['memoryType']
+      weights?: [number, number]
+      normalization?: LinearNormalization
+      fastMode?: boolean
+    },
+  ): Promise<MemorySearchResult[]> {
+    const queryEmbedding = await this.generateEmbedding(query)
+
+    const tokens = this.tokenizeQuery(query)
+    if (tokens.length === 0) {
+      aiLogger.debug`Skipping hybrid search (no valid tokens). Using vector search only.`
+      return this.vectorSearchWithEmbedding({
+        embedding: queryEmbedding,
+        scopeId: options.scopeId,
+        limit: options.limit,
+        memoryType: options.memoryType,
+        fastMode: options.fastMode,
+      })
+    }
+
+    const tokenQuery = tokens.join(' ')
+    const fullTextQuery = tokenQuery.length > 0 ? tokenQuery : query
+
+    const weights = options.weights ?? [2, 1]
+    const normalization = options.normalization ?? 'minmax'
+
+    const { sql, bindVars } = memoryQueryBuilder.buildLinearSearch({
+      query: fullTextQuery,
+      embedding: queryEmbedding,
+      scopeId: options.scopeId,
+      limit: options.limit,
+      memoryType: options.memoryType,
+      weights,
+      normalization,
+    })
+
+    type LinearRow = BasicSearchRow & { linearScore: number }
+
+    const results = await this.queryFinalStatement<LinearRow>(sql, bindVars)
+
+    if (results.length === 0) {
+      aiLogger.debug`Weighted hybrid search returned 0 raw results (scopeId: ${options.scopeId})`
+      return this.fallbackWeightedSearch(query, tokens, {
+        embedding: queryEmbedding,
+        scopeId: options.scopeId,
+        limit: options.limit,
+        memoryType: options.memoryType,
+        reason: 'no_raw_results',
+        fastMode: options.fastMode,
+      })
+    }
+
+    if (options.fastMode) {
+      const fastResults = this.mapFastRows(results, options.limit, (row) => row.linearScore)
+      return fastResults
+    }
+
+    const memoryIds = results.map((row) => row.id)
+    const relationCounts = await this.fetchRelationCountsBatch(memoryIds)
+
+    const processed = processGraphAwareRows(
+      results,
+      relationCounts,
+      options.limit,
+      (row) => row.linearScore,
+      { support: 0.05, contradict: 0.1 },
+      MIN_RELEVANCE_SCORE,
+    )
+
+    if (processed.length === 0) {
+      aiLogger.debug`Weighted hybrid search candidates were fully filtered (scopeId: ${options.scopeId}). Falling back to vector/recent.`
+      return this.fallbackWeightedSearch(query, tokens, {
+        embedding: queryEmbedding,
+        scopeId: options.scopeId,
+        limit: options.limit,
+        memoryType: options.memoryType,
+        reason: 'filtered_to_zero',
+        fastMode: options.fastMode,
+      })
+    }
+
+    aiLogger.info`[SUCCESS_WEIGHTED_SEARCH] Weighted hybrid search succeeded (scopeId: ${options.scopeId}, rawResults: ${results.length}, returned: ${processed.length}, weights: ${weights.join(',')}, normalization: ${normalization})`
+    this.touchMemories(processed.map((row) => row.id))
+    return processed
+  }
+
+  async get(id: string): Promise<MemoryRecord | null> {
+    const sql = `SELECT * FROM ${MEMORY_TABLE} WHERE id = $id`
+    const results = await databaseService.query<SurrealMemoryRow>(
+      new BoundQuery(sql, { id: ensureRecordId(id, TABLES.MEMORY) }),
+    )
+
+    const row = results.at(0)
+    if (!row) return null
+    return mapRowToMemoryRecord(row)
+  }
+
+  async update(
+    id: string,
+    newContent: string,
+    options?: { importance?: number; durability?: MemoryRecord['durability']; metadata?: Record<string, unknown> },
+  ): Promise<void> {
+    const existing = await this.get(id)
+    if (!existing) return
+
+    const newHash = hashContent(newContent, existing.scopeId, existing.memoryType)
+    const newEmbedding = await this.generateEmbedding(newContent)
+
+    const importance =
+      typeof options?.importance === 'number'
+        ? Math.max(existing.importance, Math.max(0, Math.min(1, 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(),
+    }
+    if (importance !== undefined) {
+      updatePayload.importance = importance
+    }
+    if (durability !== undefined) {
+      updatePayload.durability = durability
+    }
+    if (metadata !== undefined) {
+      updatePayload.metadata = metadata
+    }
+
+    await databaseService.updateWhere(MEMORY_TABLE, eq('id', ensureRecordId(id, TABLES.MEMORY)), updatePayload)
+
+    await this.recordHistory(id, existing.content, newContent, 'UPDATE')
+  }
+
+  async delete(id: string): Promise<void> {
+    const existing = await this.get(id)
+    if (!existing) return
+
+    await databaseService.deleteById(MEMORY_TABLE, id)
+
+    await this.recordHistory(id, existing.content, null, 'DELETE')
+  }
+
+  async list(scopeId: string, memoryType?: MemoryRecord['memoryType']): Promise<MemoryRecord[]> {
+    const typeFilter = memoryType ? 'AND memoryType = $memoryType' : ''
+    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
+    `
+
+    const results = await databaseService.query<SurrealMemoryRow>(new BoundQuery(sql, { scopeId, memoryType }))
+
+    return results.map((row) => mapRowToMemoryRecord(row))
+  }
+
+  async findByHash(hash: string): Promise<MemoryRecord | null> {
+    const sql = `SELECT * FROM ${MEMORY_TABLE} WHERE hash = $hash`
+    const results = await databaseService.query<SurrealMemoryRow>(new BoundQuery(sql, { hash }))
+
+    const row = results.at(0)
+    if (!row) return null
+    return mapRowToMemoryRecord(row)
+  }
+
+  async addRelation(fromId: string, toId: string, relationType: RelationType, confidence: number = 1.0): Promise<void> {
+    confidence = Math.max(0, Math.min(1, confidence))
+    const fromRef = ensureRecordId(fromId, TABLES.MEMORY)
+    const toRef = ensureRecordId(toId, TABLES.MEMORY)
+    await databaseService.relate(fromRef, MEMORY_RELATION_TABLE, toRef, { relationType, confidence })
+
+    if (relationType === 'supersedes') {
+      await databaseService.query(
+        new BoundQuery(`UPDATE ${MEMORY_TABLE} SET validUntil = time::now() WHERE id = $toId AND validUntil IS NONE`, {
+          toId: toRef,
+        }),
+      )
+      await this.flagDependentsForReview(toRef)
+    }
+  }
+
+  private async flagDependentsForReview(supersededId: RecordIdRef): Promise<void> {
+    const dependents = await databaseService.query<{ id: RecordIdInput }>(
+      new BoundQuery(
+        `SELECT id FROM ${MEMORY_TABLE}
+       WHERE ->${MEMORY_RELATION_TABLE}[WHERE relationType = 'depends_on']->${MEMORY_TABLE} CONTAINS $supersededId
+         AND archivedAt IS NONE
+         AND needsReview = false`,
+        { supersededId },
+      ),
+    )
+
+    if (dependents.length === 0) return
+
+    const ids = dependents.map((d) => ensureRecordId(d.id, TABLES.MEMORY))
+    await databaseService.updateWhere(MEMORY_TABLE, inside('id', ids), { needsReview: true })
+    aiLogger.debug`Flagged ${dependents.length} dependent memories for review after supersede`
+  }
+
+  async getRelatedMemories(
+    memoryId: string,
+    relationType?: RelationType,
+  ): Promise<{ relatesTo: MemoryRecord[]; relatedBy: MemoryRecord[] }> {
+    const typeFilter = relationType ? `[WHERE relationType = $relationType]` : ''
+
+    const sql = `
+      SELECT 
+        ->${MEMORY_RELATION_TABLE}${typeFilter}->${MEMORY_TABLE}.* AS relatesTo,
+        <-${MEMORY_RELATION_TABLE}${typeFilter}<-${MEMORY_TABLE}.* AS relatedBy
+      FROM ONLY $memoryId
+    `
+
+    const result = await databaseService.query<{ relatesTo: SurrealMemoryRow[]; relatedBy: SurrealMemoryRow[] }>(
+      new BoundQuery(sql, { memoryId: ensureRecordId(memoryId, TABLES.MEMORY), relationType }),
+    )
+
+    const data = result[0] ?? { relatesTo: [], relatedBy: [] }
+    return {
+      relatesTo: data.relatesTo.map((row) => mapRowToMemoryRecord(row)),
+      relatedBy: data.relatedBy.map((row) => mapRowToMemoryRecord(row)),
+    }
+  }
+
+  async findConflicts(scopeId: string): Promise<Array<{ memory: MemoryRecord; contradictedBy: MemoryRecord[] }>> {
+    const sql = `
+      SELECT 
+        *,
+        <-${MEMORY_RELATION_TABLE}[WHERE relationType = 'contradicts']<-${MEMORY_TABLE}.* AS contradictedBy
+      FROM ${MEMORY_TABLE}
+      WHERE scopeId = $scopeId
+        AND count(<-${MEMORY_RELATION_TABLE}[WHERE relationType = 'contradicts']) > 0
+    `
+
+    const results = await databaseService.query<SurrealMemoryRow & { contradictedBy: SurrealMemoryRow[] }>(
+      new BoundQuery(sql, { scopeId }),
+    )
+
+    return results.map((row) => ({
+      memory: mapRowToMemoryRecord(row),
+      contradictedBy: row.contradictedBy.map((r) => mapRowToMemoryRecord(r)),
+    }))
+  }
+
+  async graphWalk(
+    startId: string,
+    depth = 2,
+  ): Promise<{
+    memories: MemoryRecord[]
+    edges: Array<{ from: string; to: string; relationType: RelationType; confidence: number }>
+  }> {
+    const maxDepth = Math.min(depth, 3)
+
+    const visited = new Set<string>([startId])
+    const allEdges: Array<{ from: string; to: string; relationType: RelationType; confidence: number }> = []
+    const allMemories: MemoryRecord[] = []
+
+    let frontier = [startId]
+
+    for (let hop = 0; hop < maxDepth && frontier.length > 0; hop++) {
+      const nextFrontier: string[] = []
+
+      for (const nodeId of frontier) {
+        const sql = `
+          SELECT
+            ->${MEMORY_RELATION_TABLE}.{in AS from, out AS to, relationType, confidence} AS outEdges,
+            ->${MEMORY_RELATION_TABLE}->${MEMORY_TABLE}[WHERE archivedAt IS NONE].* AS outMemories,
+            <-${MEMORY_RELATION_TABLE}.{in AS from, out AS to, relationType, confidence} AS inEdges,
+            <-${MEMORY_RELATION_TABLE}<-${MEMORY_TABLE}[WHERE archivedAt IS NONE].* AS inMemories
+          FROM ONLY $nodeId
+        `
+        const results = await databaseService.query<{
+          outEdges: Array<{ from: RecordIdInput; to: RecordIdInput; relationType: RelationType; confidence: number }>
+          outMemories: SurrealMemoryRow[]
+          inEdges: Array<{ from: RecordIdInput; to: RecordIdInput; relationType: RelationType; confidence: number }>
+          inMemories: SurrealMemoryRow[]
+        }>(new BoundQuery(sql, { nodeId: ensureRecordId(nodeId, TABLES.MEMORY) }))
+
+        const row = results.at(0)
+        if (row) {
+          for (const edge of row.outEdges) {
+            allEdges.push({
+              from: recordIdToString(edge.from, TABLES.MEMORY),
+              to: recordIdToString(edge.to, TABLES.MEMORY),
+              relationType: edge.relationType,
+              confidence: edge.confidence,
+            })
+          }
+          for (const edge of row.inEdges) {
+            allEdges.push({
+              from: recordIdToString(edge.from, TABLES.MEMORY),
+              to: recordIdToString(edge.to, TABLES.MEMORY),
+              relationType: edge.relationType,
+              confidence: edge.confidence,
+            })
+          }
+          for (const mem of [...row.outMemories, ...row.inMemories]) {
+            const memoryId = recordIdToString(mem.id, TABLES.MEMORY)
+            if (!visited.has(memoryId)) {
+              visited.add(memoryId)
+              allMemories.push(mapRowToMemoryRecord(mem))
+              nextFrontier.push(memoryId)
+            }
+          }
+        }
+      }
+
+      frontier = nextFrontier
+    }
+
+    return { memories: allMemories, edges: allEdges }
+  }
+
+  private async recordHistory(
+    memoryId: string,
+    prevValue: string | null,
+    newValue: string | null,
+    event: MemoryEvent,
+  ): Promise<void> {
+    const memoryRef = ensureRecordId(memoryId, TABLES.MEMORY)
+    const historyRow: Record<string, unknown> = {
+      memoryId: memoryRef,
+      event,
+      ...(prevValue === null ? {} : { prevValue }),
+      ...(newValue === null ? {} : { newValue }),
+    }
+    await databaseService.insert<Record<string, unknown>>(MEMORY_HISTORY_TABLE, historyRow)
+  }
+
+  async enrichWithNeighbors(results: MemorySearchResult[], topN: number = 5): Promise<MemorySearchResult[]> {
+    const topIds = results.slice(0, topN).map((r) => r.id)
+    if (topIds.length === 0) return results
+
+    const topRefs = topIds.map((id) => ensureRecordId(id, TABLES.MEMORY))
+
+    const sql = `
+      SELECT
+        id,
+        ->${MEMORY_RELATION_TABLE}->(${MEMORY_TABLE} WHERE archivedAt IS NONE).{id, content} AS outgoing,
+        <-${MEMORY_RELATION_TABLE}<-(${MEMORY_TABLE} WHERE archivedAt IS NONE).{id, content} AS incoming
+      FROM ${MEMORY_TABLE}
+      WHERE id IN $ids
+    `
+
+    const rows = await databaseService.query<{
+      id: RecordIdInput
+      outgoing: Array<{ id: RecordIdInput; content: string; relationType?: string }> | null
+      incoming: Array<{ id: RecordIdInput; content: string; relationType?: string }> | null
+    }>(new BoundQuery(sql, { ids: topRefs }))
+
+    const neighborMap = new Map<string, string[]>()
+    for (const row of rows) {
+      const rowId = recordIdToString(row.id, TABLES.MEMORY)
+      const contexts: string[] = []
+      const seen = new Set<string>()
+      for (const neighbor of [...(row.outgoing ?? []), ...(row.incoming ?? [])]) {
+        const neighborId = recordIdToString(neighbor.id, TABLES.MEMORY)
+        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
+        contexts.push(`${label} ${truncated}`.trim())
+      }
+      if (contexts.length > 0) {
+        neighborMap.set(rowId, contexts)
+      }
+    }
+
+    return results.map((result) => {
+      const neighbors = neighborMap.get(result.id)
+      if (!neighbors) return result
+      return { ...result, metadata: { ...result.metadata, relatedContext: neighbors } }
+    })
+  }
+
+  async getStaleMemories(scopeId: string, limit: number = 5): Promise<MemorySearchResult[]> {
+    const results = await databaseService.query<BasicSearchRow>(
+      new BoundQuery(
+        `SELECT id, content, metadata
+       FROM ${MEMORY_TABLE}
+       WHERE scopeId = $scopeId
+         AND needsReview = true
+         AND archivedAt IS NONE
+       ORDER BY updatedAt DESC
+       LIMIT $limit`,
+        { scopeId, limit },
+      ),
+    )
+
+    return results.map((row) => ({
+      id: recordIdToString(row.id, TABLES.MEMORY),
+      content: row.content,
+      score: 0,
+      metadata: { ...row.metadata, needsReview: true },
+    }))
+  }
+}
+
+let defaultMemoryStore: SurrealMemoryStore | null = null
+
+export function getDefaultMemoryStore(): SurrealMemoryStore {
+  if (!defaultMemoryStore) {
+    defaultMemoryStore = new SurrealMemoryStore(createDefaultEmbeddings())
+  }
+  return defaultMemoryStore
+}