@lota-sdk/core 0.4.7 → 0.4.9

package/src/db/memory.ts

@@ -1,23 +1,24 @@
+import { Schema, Effect } from 'effect'
 import type { z } from 'zod'
 
 import { aiLogger } from '../config/logger'
-import type { CreateHelperAgentFn } from '../runtime/helper-model'
-import { createHelperModelRuntime } from '../runtime/helper-model'
-import { formatResults } from '../runtime/memory-format'
+import type { CreateHelperAgentFn, HelperModelRuntime } from '../runtime/helper-model'
+import { formatResults } from '../runtime/memory/memory-format'
 import {
   buildMemoryFactMaps,
   compileMemoryUpdatesFromDelta,
   createMemoryActionPlan,
   postProcessMemoryFacts,
   projectMemoryDeltaToScope,
-} from '../runtime/memory-pipeline'
-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'
+} from '../runtime/memory/memory-pipeline'
+import { getFactRetrievalMessages } from '../runtime/memory/memory-prompts-fact'
+import { parseMessages } from '../runtime/memory/memory-prompts-parse'
+import { getClassifyMemoryDeltaPrompt } from '../runtime/memory/memory-prompts-update'
+import type { ResolvedLotaRuntimeConfig } from '../runtime/runtime-config'
+import { sha256Hex } from '../utils/crypto'
 import { compactWhitespace, truncateText } from '../utils/string'
 import type { SurrealMemoryStore } from './memory-store'
-import { getDefaultMemoryStore } from './memory-store'
+import { createMemoryStore } from './memory-store'
 import { hashContent, isUniqueIndexConflict } from './memory-store.helpers'
 import { FactRetrievalSchema, MemoryDeltaSchema, MemoryUpdateSchema } from './memory-types'
 import type {
@@ -35,6 +36,7 @@ import type {
   SearchOptions,
   WeightedSearchOptions,
 } from './memory-types'
+import type { SurrealDBService } from './service'
 
 const MEMORY_WORKER_MODEL_TIMEOUT_MS = 10 * 60 * 1000
 const MEMORY_FACT_EXTRACTION_TIMEOUT_MS = MEMORY_WORKER_MODEL_TIMEOUT_MS
@@ -44,7 +46,6 @@ 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 {
   options: AddOptions
@@ -53,10 +54,30 @@ interface PreparedScopeUpdate {
   existingMemories: Array<{ id: string; text: string }>
 }
 
-interface ScopedExistingMemories {
-  options: AddOptions
-  existingMemories: Array<{ id: string; text: string }>
-  scopeMemoryIdsByUnionId: Record<string, string[]>
+class MemoryServiceError extends Schema.TaggedErrorClass<MemoryServiceError>()('MemoryServiceError', {
+  message: Schema.String,
+  cause: Schema.Defect,
+}) {}
+
+function tryMemoryPromise<A, R = never>(
+  message: string,
+  thunk: () => PromiseLike<A> | Effect.Effect<A, unknown, R>,
+): Effect.Effect<A, MemoryServiceError, R> {
+  return Effect.suspend(() => {
+    try {
+      const value = thunk()
+      if (Effect.isEffect(value)) {
+        return value.pipe(Effect.mapError((cause) => new MemoryServiceError({ message, cause })))
+      }
+
+      return Effect.tryPromise({
+        try: () => Promise.resolve(value),
+        catch: (cause) => new MemoryServiceError({ message, cause }),
+      })
+    } catch (cause) {
+      return Effect.fail(new MemoryServiceError({ message, cause }))
+    }
+  })
 }
 
 export class Memory {
@@ -64,9 +85,20 @@ export class Memory {
   private createAgent: CreateHelperAgentFn
   private maxOutputTokens?: number
   private config: MemoryConfig
-
-  constructor(agent: { createAgent: CreateHelperAgentFn; maxOutputTokens?: number }, config: MemoryConfig = {}) {
-    this.store = getDefaultMemoryStore()
+  private runtimeConfig: ResolvedLotaRuntimeConfig
+  private helperModelRuntime: HelperModelRuntime
+
+  constructor(
+    deps: { db: SurrealDBService; runtimeConfig: ResolvedLotaRuntimeConfig; helperModelRuntime: HelperModelRuntime },
+    agent: { createAgent: CreateHelperAgentFn; maxOutputTokens?: number },
+    config: MemoryConfig = {},
+  ) {
+    this.store = createMemoryStore(deps.db, {
+      embeddingModel: deps.runtimeConfig.aiGateway.embeddingModel,
+      openRouterApiKey: deps.runtimeConfig.aiGateway.openRouterApiKey,
+    })
+    this.runtimeConfig = deps.runtimeConfig
+    this.helperModelRuntime = deps.helperModelRuntime
     this.createAgent = agent.createAgent
     this.maxOutputTokens = agent.maxOutputTokens
 
@@ -84,10 +116,10 @@ export class Memory {
   private buildMemoryUnionId(text: string): string | null {
     const normalized = this.normalizeMemoryDeltaText(text, MEMORY_DELTA_MEMORY_TEXT_MAX_CHARS)
     if (!normalized) return null
-    return `union_${new Bun.CryptoHasher('sha256').update(normalized).digest('hex')}`
+    return `union_${sha256Hex(normalized)}`
   }
 
-  async insert(
+  insert(
     content: string,
     options: {
       scopeId: string
@@ -96,242 +128,314 @@ export class Memory {
       metadata?: Record<string, unknown>
       durability?: Durability
     },
-  ): Promise<string> {
-    return this.store.insert(
-      content,
-      options.scopeId,
-      options.memoryType,
-      options.metadata ?? {},
-      options.importance ?? 1,
-      options.durability ?? 'standard',
+  ): Effect.Effect<string, MemoryServiceError, never> {
+    return tryMemoryPromise('Failed to insert memory.', () =>
+      this.store.insert(
+        content,
+        options.scopeId,
+        options.memoryType,
+        options.metadata ?? {},
+        options.importance ?? 1,
+        options.durability ?? 'standard',
+      ),
     )
   }
 
-  async search(query: string, options: SearchOptions): Promise<string> {
-    const limit = options.limit ?? getRuntimeConfig().memory.searchK
-    const results = await this.store.search(query, options.scopeId, limit, options.memoryType)
-
-    return formatResults(results)
+  search(query: string, options: SearchOptions): Effect.Effect<string, MemoryServiceError, never> {
+    const self = this
+    return Effect.gen(function* () {
+      const limit = options.limit ?? self.runtimeConfig.memory.searchK
+      const results = yield* tryMemoryPromise('Failed to search memory.', () =>
+        self.store.search(query, options.scopeId, limit, options.memoryType),
+      )
+      return formatResults(results)
+    })
   }
 
-  async hybridSearch(query: string, options: SearchOptions): Promise<string> {
-    const limit = options.limit ?? getRuntimeConfig().memory.searchK
-    const results = await this.store.hybridSearch(query, options.scopeId, limit, options.memoryType)
-
-    return formatResults(results)
+  hybridSearch(query: string, options: SearchOptions): Effect.Effect<string, MemoryServiceError, never> {
+    const self = this
+    return Effect.gen(function* () {
+      const limit = options.limit ?? self.runtimeConfig.memory.searchK
+      const results = yield* tryMemoryPromise('Failed to perform hybrid search.', () =>
+        self.store.hybridSearch(query, options.scopeId, limit, options.memoryType),
+      )
+      return formatResults(results)
+    })
   }
 
-  async hybridSearchWeighted(
+  hybridSearchWeighted(
     query: string,
     options: SearchOptions & { weights?: [number, number]; normalization?: 'minmax' | 'zscore' },
-  ): Promise<string> {
-    const limit = options.limit ?? getRuntimeConfig().memory.searchK
-    const results = await this.store.hybridSearchWeighted(query, {
-      scopeId: options.scopeId,
-      limit,
-      memoryType: options.memoryType,
-      weights: options.weights,
-      normalization: options.normalization,
+  ): Effect.Effect<string, MemoryServiceError, never> {
+    const self = this
+    return Effect.gen(function* () {
+      const limit = options.limit ?? self.runtimeConfig.memory.searchK
+      const results = yield* tryMemoryPromise('Failed to perform weighted hybrid search.', () =>
+        self.store.hybridSearchWeighted(query, {
+          scopeId: options.scopeId,
+          limit,
+          memoryType: options.memoryType,
+          weights: options.weights,
+          normalization: options.normalization,
+        }),
+      )
+      return formatResults(results)
     })
-
-    return formatResults(results)
   }
 
-  async searchCandidates(query: string, options: WeightedSearchOptions): Promise<MemorySearchResult[]> {
-    const limit = options.limit ?? getRuntimeConfig().memory.searchK
-    const results = await this.store.hybridSearchWeighted(query, {
-      scopeId: options.scopeId,
-      limit,
-      memoryType: options.memoryType,
-      weights: options.weights,
-      normalization: options.normalization,
-      fastMode: options.fastMode,
-    })
+  searchCandidates(
+    query: string,
+    options: WeightedSearchOptions,
+  ): Effect.Effect<MemorySearchResult[], MemoryServiceError, never> {
+    const self = this
+    return Effect.gen(function* () {
+      const limit = options.limit ?? self.runtimeConfig.memory.searchK
+      const results = yield* tryMemoryPromise('Failed to search memory candidates.', () =>
+        self.store.hybridSearchWeighted(query, {
+          scopeId: options.scopeId,
+          limit,
+          memoryType: options.memoryType,
+          weights: options.weights,
+          normalization: options.normalization,
+          fastMode: options.fastMode,
+        }),
+      )
 
-    if (options.fastMode || options.includeNeighborContext === false) {
-      return results
-    }
+      if (options.fastMode || options.includeNeighborContext === false) {
+        return results
+      }
 
-    return this.store.enrichWithNeighbors(results)
+      return yield* tryMemoryPromise('Failed to enrich memory candidates.', () =>
+        self.store.enrichWithNeighbors(results),
+      )
+    })
   }
 
-  async listTopMemories(options: {
+  listTopMemories(options: {
     scopeId: string
     limit: number
     memoryType?: MemoryType
     durability?: Durability
     minImportance?: number
-  }): Promise<MemoryRecord[]> {
-    return this.store.listTopMemories(options)
+  }): Effect.Effect<MemoryRecord[], MemoryServiceError, never> {
+    return tryMemoryPromise('Failed to list top memories.', () => this.store.listTopMemories(options))
   }
 
-  async list(options: MemoryListOptions): Promise<MemoryRecord[]> {
-    return this.store.list(options)
+  list(options: MemoryListOptions): Effect.Effect<MemoryRecord[], MemoryServiceError, never> {
+    return tryMemoryPromise('Failed to list memories.', () => this.store.list(options))
   }
 
-  async updateMemory(id: string, newContent: string): Promise<void> {
-    await this.store.update(id, newContent)
+  updateMemory(id: string, newContent: string): Effect.Effect<void, MemoryServiceError, never> {
+    return tryMemoryPromise(`Failed to update memory ${id}.`, () => 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)
+  addRelation(
+    fromId: string,
+    toId: string,
+    relationType: RelationType,
+    confidence = 1,
+  ): Effect.Effect<void, MemoryServiceError, never> {
+    return tryMemoryPromise(`Failed to add ${relationType} relation.`, () =>
+      this.store.addRelation(fromId, toId, relationType, confidence),
+    )
   }
 
-  async getStaleMemories(scopeId: string, limit?: number): Promise<MemorySearchResult[]> {
-    return this.store.getStaleMemories(scopeId, limit)
+  getStaleMemories(scopeId: string, limit?: number): Effect.Effect<MemorySearchResult[], MemoryServiceError, never> {
+    return tryMemoryPromise('Failed to load stale memories.', () => this.store.getStaleMemories(scopeId, limit))
   }
 
-  async extractFactsFromMessages(
+  extractFactsFromMessages(
     messages: Message[],
     extractionOptions?: { customPrompt?: string; maxFacts?: number },
-  ): Promise<ExtractedFact[]> {
-    if (messages.length === 0) return []
-
-    const parsedMessages = parseMessages(messages)
-
-    const facts = await this.extractFacts(parsedMessages, extractionOptions)
-    if (facts.length === 0) {
-      aiLogger.debug`No facts extracted from conversation`
-      return []
-    }
+  ): Effect.Effect<ExtractedFact[], MemoryServiceError, never> {
+    const self = this
+    return Effect.gen(function* () {
+      if (messages.length === 0) return []
+
+      const parsedMessages = parseMessages(messages)
+      const facts = yield* self.extractFactsEffect(parsedMessages, extractionOptions)
+      if (facts.length === 0) {
+        aiLogger.debug`No facts extracted from conversation`
+        return []
+      }
 
-    return facts
+      return facts
+    })
   }
 
-  async applyFactsToScopes(facts: ExtractedFact[], scopes: AddOptions[]): Promise<void> {
-    if (facts.length === 0 || scopes.length === 0) return
+  applyFactsToScopes(facts: ExtractedFact[], scopes: AddOptions[]): Effect.Effect<void, MemoryServiceError, never> {
+    const self = this
+    return Effect.gen(function* () {
+      if (facts.length === 0 || scopes.length === 0) return
+      const prepared = yield* self.prepareFactsToScopesEffect(facts, scopes)
+      yield* self.applyPreparedScopeUpdates(prepared)
+    })
+  }
 
-    const prepared = await this.prepareFactsToScopes(facts, scopes)
-    await this.applyPreparedScopeUpdates(prepared)
+  prepareFactsToScopes(
+    facts: ExtractedFact[],
+    scopes: AddOptions[],
+  ): Effect.Effect<PreparedScopeUpdate[], MemoryServiceError, never> {
+    return this.prepareFactsToScopesEffect(facts, scopes)
   }
 
-  async prepareFactsToScopes(facts: ExtractedFact[], scopes: AddOptions[]): Promise<PreparedScopeUpdate[]> {
-    if (facts.length === 0 || scopes.length === 0) return []
+  applyPreparedScopeUpdates(prepared: PreparedScopeUpdate[]): Effect.Effect<void, MemoryServiceError, never> {
+    if (prepared.length === 0) return Effect.void
 
-    const factMaps = buildMemoryFactMaps(facts)
-    const factContents = facts.map((fact) => fact.content)
-    const scopePayloads: ScopedExistingMemories[] = await Promise.all(
-      scopes.map(async (scopeOptions) => {
-        const existingMemories = await this.store.list({
-          scopeId: scopeOptions.scopeId,
-          memoryType: scopeOptions.memoryType,
-        })
-        const normalizedMemories = existingMemories.map((memory) => ({ id: memory.id, text: memory.content }))
-        const scopeMemoryIdsByUnionId: Record<string, string[]> = {}
-        for (const memory of normalizedMemories) {
-          const unionId = this.buildMemoryUnionId(memory.text)
-          if (!unionId) continue
-          ;(scopeMemoryIdsByUnionId[unionId] ??= []).push(memory.id)
-        }
-        return { options: scopeOptions, existingMemories: normalizedMemories, scopeMemoryIdsByUnionId }
-      }),
+    return Effect.forEach(
+      prepared,
+      (item) =>
+        tryMemoryPromise('Failed to apply memory updates', () =>
+          this.applyUpdates(item.updates, item.options, item.factMaps, item.existingMemories),
+        ),
+      { concurrency: 2, discard: true },
     )
-    const unionMemories = new Map<string, { id: string; text: string }>()
-    for (const scopePayload of scopePayloads) {
-      for (const memory of scopePayload.existingMemories) {
-        const unionId = this.buildMemoryUnionId(memory.text)
-        if (!unionId || unionMemories.has(unionId)) continue
-        const normalizedText = this.normalizeMemoryDeltaText(memory.text, MEMORY_DELTA_MEMORY_TEXT_MAX_CHARS)
-        if (!normalizedText) continue
-        unionMemories.set(unionId, { id: unionId, text: normalizedText })
-      }
-    }
-
-    const delta = await this.determineDelta([...unionMemories.values()], factContents)
-    return scopePayloads.map(({ options, existingMemories, scopeMemoryIdsByUnionId }) => ({
-      options,
-      updates: MemoryUpdateSchema.parse(
-        compileMemoryUpdatesFromDelta({
-          existingMemories,
-          newFacts: factContents,
-          delta: projectMemoryDeltaToScope({
-            delta,
-            scopeMemoryIds: existingMemories.map((memory) => memory.id),
-            scopeMemoryIdsByUnionId,
-          }),
-        }),
-      ),
-      factMaps,
-      existingMemories,
-    }))
   }
 
-  async applyPreparedScopeUpdates(prepared: PreparedScopeUpdate[]): Promise<void> {
-    if (prepared.length === 0) return
+  private prepareFactsToScopesEffect(
+    facts: ExtractedFact[],
+    scopes: AddOptions[],
+  ): Effect.Effect<PreparedScopeUpdate[], MemoryServiceError, never> {
+    return Effect.gen(
+      function* (this: Memory) {
+        if (facts.length === 0 || scopes.length === 0) return []
+
+        const factMaps = buildMemoryFactMaps(facts)
+        const factContents = facts.map((fact) => fact.content)
+        const scopePayloads = yield* Effect.all(
+          scopes.map((scopeOptions) =>
+            tryMemoryPromise(`Failed to list memories for scope ${scopeOptions.scopeId}.`, () =>
+              this.store.list({ scopeId: scopeOptions.scopeId, memoryType: scopeOptions.memoryType }),
+            ).pipe(
+              Effect.map((existingMemories) => {
+                const normalizedMemories = existingMemories.map((memory) => ({ id: memory.id, text: memory.content }))
+                const scopeMemoryIdsByUnionId: Record<string, string[]> = {}
+                for (const memory of normalizedMemories) {
+                  const unionId = this.buildMemoryUnionId(memory.text)
+                  if (!unionId) continue
+                  ;(scopeMemoryIdsByUnionId[unionId] ??= []).push(memory.id)
+                }
+                return { options: scopeOptions, existingMemories: normalizedMemories, scopeMemoryIdsByUnionId }
+              }),
+            ),
+          ),
+        )
+
+        const unionMemories = new Map<string, { id: string; text: string }>()
+        for (const scopePayload of scopePayloads) {
+          for (const memory of scopePayload.existingMemories) {
+            const unionId = this.buildMemoryUnionId(memory.text)
+            if (!unionId || unionMemories.has(unionId)) continue
+            const normalizedText = this.normalizeMemoryDeltaText(memory.text, MEMORY_DELTA_MEMORY_TEXT_MAX_CHARS)
+            if (!normalizedText) continue
+            unionMemories.set(unionId, { id: unionId, text: normalizedText })
+          }
+        }
 
-    for (const item of prepared) {
-      await this.applyUpdates(item.updates, item.options, item.factMaps, item.existingMemories)
-    }
+        const delta = yield* this.determineDeltaEffect([...unionMemories.values()], factContents)
+        return scopePayloads.map(({ options, existingMemories, scopeMemoryIdsByUnionId }) => ({
+          options,
+          updates: MemoryUpdateSchema.parse(
+            compileMemoryUpdatesFromDelta({
+              existingMemories,
+              newFacts: factContents,
+              delta: projectMemoryDeltaToScope({
+                delta,
+                scopeMemoryIds: existingMemories.map((memory) => memory.id),
+                scopeMemoryIdsByUnionId,
+              }),
+            }),
+          ),
+          factMaps,
+          existingMemories,
+        }))
+      }.bind(this),
+    )
   }
 
-  private async extractFacts(
+  private extractFactsEffect(
     parsedMessages: string,
     extractionOptions?: { customPrompt?: string; maxFacts?: number },
-  ): Promise<ExtractedFact[]> {
-    const [systemPrompt, userPrompt] = getFactRetrievalMessages(
-      parsedMessages,
-      this.buildFactExtractionPrompt(extractionOptions?.customPrompt),
-      extractionOptions?.maxFacts,
-    )
-
-    try {
-      const result = await helperModelRuntime.generateHelperStructured({
-        tag: 'memory-extract-facts',
-        createAgent: this.createAgent,
-        defaultSystemPrompt: this.config.customPrompt,
-        systemPrompt,
-        maxOutputTokens: this.maxOutputTokens,
-        timeoutMs: MEMORY_FACT_EXTRACTION_TIMEOUT_MS,
-        messages: [{ role: 'user', content: userPrompt }],
-        schema: FactRetrievalSchema,
-      })
+  ): Effect.Effect<ExtractedFact[], MemoryServiceError, never> {
+    return Effect.gen(
+      function* (this: Memory) {
+        const [systemPrompt, userPrompt] = getFactRetrievalMessages(
+          parsedMessages,
+          this.buildFactExtractionPrompt(extractionOptions?.customPrompt),
+          extractionOptions?.maxFacts,
+        )
+
+        const result = yield* Effect.tryPromise({
+          try: () =>
+            this.helperModelRuntime.generateHelperStructured({
+              tag: 'memory-extract-facts',
+              createAgent: this.createAgent,
+              defaultSystemPrompt: this.config.customPrompt,
+              systemPrompt,
+              maxOutputTokens: this.maxOutputTokens,
+              timeoutMs: MEMORY_FACT_EXTRACTION_TIMEOUT_MS,
+              messages: [{ role: 'user', content: userPrompt }],
+              schema: FactRetrievalSchema,
+            }),
+          catch: (cause) => new MemoryServiceError({ message: 'Failed to extract facts.', cause }),
+        })
 
-      return postProcessMemoryFacts(
-        result.facts,
-        typeof extractionOptions?.maxFacts === 'number' ? { maxFacts: extractionOptions.maxFacts } : {},
-      )
-    } catch (error) {
-      aiLogger.warn`Failed to extract facts: ${error}`
-      return []
-    }
+        return postProcessMemoryFacts(
+          result.facts,
+          typeof extractionOptions?.maxFacts === 'number' ? { maxFacts: extractionOptions.maxFacts } : {},
+        )
+      }.bind(this),
+    ).pipe(
+      Effect.catchTag('MemoryServiceError', (error) =>
+        Effect.sync(() => {
+          aiLogger.warn`Failed to extract facts: ${error.message}`
+          return []
+        }),
+      ),
+    )
   }
 
-  private async determineDelta(
+  private determineDeltaEffect(
     existingMemories: { id: string; text: string }[],
     newFacts: string[],
-  ): Promise<{ deltas: Array<z.infer<typeof MemoryDeltaSchema>['deltas'][number]> }> {
-    if (existingMemories.length === 0) {
-      return {
-        deltas: newFacts.map((fact) => ({
-          fact,
-          classification: 'new' as const,
-          targetMemoryIds: [],
-          invalidateTargetIds: [],
-          relations: [],
-          rationale: 'No existing memories in scope.',
-        })),
-      }
-    }
-
-    const candidateMemories = this.selectDeltaCandidateMemories(existingMemories, newFacts)
-    const { systemPrompt, userPrompt } = getClassifyMemoryDeltaPrompt({ existingMemories: candidateMemories, newFacts })
-    aiLogger.debug`Memory delta candidate selection (existing=${existingMemories.length}, selected=${candidateMemories.length}, facts=${newFacts.length})`
+  ): Effect.Effect<{ deltas: Array<z.infer<typeof MemoryDeltaSchema>['deltas'][number]> }, MemoryServiceError, never> {
+    return Effect.gen(
+      function* (this: Memory) {
+        if (existingMemories.length === 0) {
+          return {
+            deltas: newFacts.map((fact) => ({
+              fact,
+              classification: 'new' as const,
+              targetMemoryIds: [],
+              invalidateTargetIds: [],
+              relations: [],
+              rationale: 'No existing memories in scope.',
+            })),
+          }
+        }
 
-    try {
-      const deltas = await helperModelRuntime.generateHelperStructured({
-        tag: 'memory-classify-delta',
-        createAgent: this.createAgent,
-        systemPrompt,
-        maxOutputTokens: this.maxOutputTokens,
-        timeoutMs: MEMORY_DELTA_CLASSIFICATION_TIMEOUT_MS,
-        messages: [{ role: 'user', content: userPrompt }],
-        schema: MemoryDeltaSchema,
-      })
-      return deltas
-    } catch (error) {
-      aiLogger.error`Failed to determine memory updates: ${error}`
-      throw error
-    }
+        const candidateMemories = this.selectDeltaCandidateMemories(existingMemories, newFacts)
+        const { systemPrompt, userPrompt } = getClassifyMemoryDeltaPrompt({
+          existingMemories: candidateMemories,
+          newFacts,
+        })
+        aiLogger.debug`Memory delta candidate selection (existing=${existingMemories.length}, selected=${candidateMemories.length}, facts=${newFacts.length})`
+
+        return yield* Effect.tryPromise({
+          try: () =>
+            this.helperModelRuntime.generateHelperStructured({
+              tag: 'memory-classify-delta',
+              createAgent: this.createAgent,
+              systemPrompt,
+              maxOutputTokens: this.maxOutputTokens,
+              timeoutMs: MEMORY_DELTA_CLASSIFICATION_TIMEOUT_MS,
+              messages: [{ role: 'user', content: userPrompt }],
+              schema: MemoryDeltaSchema,
+            }),
+          catch: (cause) => new MemoryServiceError({ message: 'Failed to determine memory updates.', cause }),
+        })
+      }.bind(this),
+    )
   }
 
   private normalizeMemoryDeltaText(value: string, maxChars?: number): string {
@@ -441,92 +545,111 @@ export class Memory {
     return selected.map((memory) => ({ id: memory.id, text: memory.text }))
   }
 
-  private async applyUpdates(
+  private applyUpdates(
     updates: MemoryUpdateOutput,
     options: AddOptions,
     factMaps: ReturnType<typeof buildMemoryFactMaps>,
     existingMemories: Array<{ id: string; text: string }>,
-  ): Promise<void> {
-    const plan = createMemoryActionPlan({
-      updates,
-      memoryType: options.memoryType,
-      explicitImportance: options.importance,
-      extractedImportanceByKey: factMaps.extractedImportanceByKey,
-      confidenceByKey: factMaps.confidenceByKey,
-      durabilityByKey: factMaps.durabilityByKey,
-      categoryByKey: factMaps.categoryByKey,
-      existingMemories,
-    })
+  ): Effect.Effect<void, MemoryServiceError, never> {
+    const self = this
+    return Effect.gen(function* () {
+      const plan = createMemoryActionPlan({
+        updates,
+        memoryType: options.memoryType,
+        explicitImportance: options.importance,
+        extractedImportanceByKey: factMaps.extractedImportanceByKey,
+        confidenceByKey: factMaps.confidenceByKey,
+        durabilityByKey: factMaps.durabilityByKey,
+        categoryByKey: factMaps.categoryByKey,
+        existingMemories,
+      })
 
-    const idMap = new Map<string, string>()
-
-    for (const action of plan.actions) {
-      switch (action.type) {
-        case 'add': {
-          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
-
-          try {
-            newId = await this.store.insert(
-              action.text,
-              options.scopeId,
-              options.memoryType,
-              metadata,
-              action.importance,
-              action.durability as Durability,
+      const idMap = new Map<string, string>()
+      for (const action of plan.actions) {
+        switch (action.type) {
+          case 'add': {
+            const truncatedContent = truncateText(action.text, 50)
+            const metadata = { ...options.metadata, memoryCategory: action.category }
+            const hash = hashContent(action.text, options.scopeId, options.memoryType)
+
+            const newId = yield* tryMemoryPromise(`Failed to insert memory for scope ${options.scopeId}.`, () =>
+              self.store.insert(
+                action.text,
+                options.scopeId,
+                options.memoryType,
+                metadata,
+                action.importance,
+                action.durability as Durability,
+              ),
+            ).pipe(
+              Effect.catchTag('MemoryServiceError', (error) => {
+                if (!isUniqueIndexConflict(error.cause, 'memoryHashIdx')) {
+                  return Effect.fail(error)
+                }
+
+                return tryMemoryPromise(`Failed to look up memory hash ${hash}.`, () =>
+                  self.store.getByHash(hash),
+                ).pipe(
+                  Effect.flatMap((existing) => {
+                    if (!existing) {
+                      return Effect.fail(error)
+                    }
+
+                    return Effect.sync(() => {
+                      aiLogger.debug`Skipped duplicate memory insert due to hash conflict: ${existing.id}`
+                      return existing.id
+                    })
+                  }),
+                )
+              }),
             )
-          } catch (error) {
-            if (!isUniqueIndexConflict(error, 'memoryHashIdx')) {
-              throw error
-            }
-
-            const existing = await this.store.getByHash(hash)
-            if (!existing) {
-              throw error
-            }
-
-            newId = existing.id
-            aiLogger.debug`Skipped duplicate memory insert due to hash conflict: ${newId}`
+
+            idMap.set(action.refId, newId)
+            aiLogger.debug`Added new memory (memoryType: ${options.memoryType}, category: ${action.category}, durability: ${action.durability}, importance: ${action.importance.toFixed(2)}, content: ${truncatedContent})`
+            break
           }
 
-          idMap.set(action.refId, newId)
-          aiLogger.debug`Added new memory (memoryType: ${options.memoryType}, category: ${action.category}, durability: ${action.durability}, importance: ${action.importance.toFixed(2)}, content: ${truncatedContent})`
-          break
-        }
+          case 'update': {
+            const metadata = { ...options.metadata, ...(action.category ? { memoryCategory: action.category } : {}) }
+            yield* tryMemoryPromise(`Failed to update memory ${action.refId}.`, () =>
+              self.store.update(action.refId, action.text, {
+                importance: action.importance,
+                durability: action.durability as Durability | undefined,
+                metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+              }),
+            )
+            idMap.set(action.refId, action.refId)
+            aiLogger.debug`Updated memory ${action.refId}: ${truncateText(action.text, 50)}`
+            break
+          }
 
-        case 'update': {
-          const metadata = { ...options.metadata, ...(action.category ? { memoryCategory: action.category } : {}) }
-          await this.store.update(action.refId, action.text, {
-            importance: action.importance,
-            durability: action.durability as Durability | undefined,
-            metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
-          })
-          idMap.set(action.refId, action.refId)
-          aiLogger.debug`Updated memory ${action.refId}: ${truncateText(action.text, 50)}`
-          break
+          case 'delete':
+            yield* tryMemoryPromise(`Failed to delete memory ${action.refId}.`, () => self.store.delete(action.refId))
+            aiLogger.debug`Deleted memory ${action.refId}`
+            break
         }
-
-        case 'delete':
-          await this.store.delete(action.refId)
-          aiLogger.debug`Deleted memory ${action.refId}`
-          break
       }
-    }
-
-    for (const relation of plan.relations) {
-      const fromId = idMap.get(relation.fromRefId)
-      if (!fromId) continue
-
-      const toId = idMap.get(relation.toRefId) ?? relation.toRefId
 
-      try {
-        await this.store.addRelation(fromId, toId, relation.relation)
-        aiLogger.debug`Created ${relation.relation} relation: ${fromId} -> ${toId}`
-      } catch (error) {
-        aiLogger.warn`Failed to create memory relation (non-fatal, graph may be incomplete): ${error}`
+      for (const relation of plan.relations) {
+        const fromId = idMap.get(relation.fromRefId)
+        if (!fromId) continue
+
+        const toId = idMap.get(relation.toRefId) ?? relation.toRefId
+        yield* tryMemoryPromise(`Failed to create memory relation ${relation.relation}.`, () =>
+          self.store.addRelation(fromId, toId, relation.relation),
+        ).pipe(
+          Effect.tap(() =>
+            Effect.sync(() => {
+              aiLogger.debug`Created ${relation.relation} relation: ${fromId} -> ${toId}`
+            }),
+          ),
+          Effect.catchTag('MemoryServiceError', (error) =>
+            Effect.sync(() => {
+              aiLogger.warn`Failed to create memory relation (non-fatal, graph may be incomplete): ${error.message}`
+            }),
+          ),
+        )
       }
-    }
+    })
   }
 }