@lota-sdk/core 0.1.5

package/src/db/memory-types.ts

@@ -0,0 +1,193 @@
+import { z } from 'zod'
+
+export const MemoryTypeSchema = z.enum([
+  'fact',
+  'preference',
+  'interaction',
+  'summary',
+  'user_request',
+  'entity',
+  'interest',
+])
+export type MemoryType = z.infer<typeof MemoryTypeSchema>
+
+export const DurabilitySchema = z.enum(['core', 'standard', 'ephemeral'])
+export type Durability = z.infer<typeof DurabilitySchema>
+
+export const MemoryEventSchema = z.enum(['ADD', 'UPDATE', 'DELETE', 'NONE'])
+export type MemoryEvent = z.infer<typeof MemoryEventSchema>
+
+export const RelationTypeSchema = z.enum([
+  'contradicts',
+  'supports',
+  'supersedes',
+  'caused_by',
+  'depends_on',
+  'part_of',
+  'implements',
+])
+export type RelationType = z.infer<typeof RelationTypeSchema>
+
+export interface MemoryRecord {
+  id: string
+  content: string
+  embedding: number[]
+  hash: string
+  scopeId: string
+  memoryType: MemoryType
+  durability: Durability
+  metadata: Record<string, unknown>
+  importance: number
+  accessCount: number
+  needsReview: boolean
+  lastAccessedAt?: Date
+  createdAt: Date
+  updatedAt?: Date
+  validFrom: Date
+  validUntil?: Date
+  archivedAt?: Date
+}
+
+export interface SearchOptions {
+  scopeId: string
+  limit?: number
+  memoryType?: MemoryType
+  pointInTime?: string
+}
+
+export type LinearNormalization = 'minmax' | 'zscore'
+
+export interface WeightedSearchOptions extends SearchOptions {
+  weights?: [number, number]
+  normalization?: LinearNormalization
+  fastMode?: boolean
+  includeNeighborContext?: boolean
+}
+
+export interface AddOptions {
+  scopeId: string
+  memoryType: MemoryType
+  importance?: number
+  metadata?: Record<string, unknown>
+}
+
+export interface MemorySearchResult {
+  id: string
+  content: string
+  score: number
+  metadata: Record<string, unknown>
+  contradictions?: string[]
+}
+
+const ExtractedFactSchema = z.object({
+  content: z.string().describe('The extracted fact or preference.'),
+  type: z.enum(['fact', 'preference', 'decision']).describe('Classification of the memory.'),
+  confidence: z
+    .number()
+    .min(0)
+    .max(1)
+    .describe('1.0 for explicit decisions/confirmed truths, 0.8 for strong implications. Do not extract below 0.6.'),
+  durability: z
+    .enum(['core', 'standard', 'ephemeral'])
+    .describe(
+      'core: business decisions, technical architecture, confirmed requirements. standard: general facts, moderate inferences. ephemeral: preferences, one-off interactions, formatting choices.',
+    ),
+})
+
+export type ExtractedFact = z.infer<typeof ExtractedFactSchema>
+
+export const FactRetrievalSchema = z.object({
+  facts: z.array(ExtractedFactSchema).describe('Extracted durable facts with classification and confidence.'),
+})
+
+const MemoryRelationItemSchema = z.object({
+  memoryId: z.string().describe('The ID of the related memory from the existing memory list.'),
+  relation: RelationTypeSchema.describe('How the new fact relates to this memory.'),
+})
+const MemoryUpdateItemSchema = z.object({
+  id: z.string().describe('The unique identifier of the memory item.'),
+  text: z.string().describe('The content of the memory item.'),
+  event: MemoryEventSchema.describe('The action taken for this memory item (ADD, UPDATE, DELETE, or NONE).'),
+  oldMemory: z.string().optional().describe('The previous content of the memory item if the event was UPDATE.'),
+  relatesTo: z.array(MemoryRelationItemSchema).optional().describe('Relations to existing memories.'),
+})
+
+export const MemoryUpdateSchema = z.object({
+  memory: z
+    .array(MemoryUpdateItemSchema)
+    .describe('An array representing the state of memory items after processing new facts.'),
+})
+
+export type MemoryUpdateOutput = z.infer<typeof MemoryUpdateSchema>
+
+const MemoryDeltaClassificationSchema = z.enum(['new', 'supersedes', 'contradicts', 'enriches', 'duplicate'])
+
+const MemoryDeltaRelationSchema = z
+  .object({
+    relation: RelationTypeSchema.describe('Relation type to attach from this fact output to a target.'),
+    targetMemoryId: z
+      .string()
+      .min(1)
+      .optional()
+      .describe('Target existing memory id when relation points to existing memory.'),
+    targetFactIndex: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe('Target newFacts index when relation points to another newly provided fact.'),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    const hasTargetMemoryId = typeof value.targetMemoryId === 'string' && value.targetMemoryId.trim().length > 0
+    const hasTargetFactIndex = Number.isInteger(value.targetFactIndex)
+
+    if ((hasTargetMemoryId && hasTargetFactIndex) || (!hasTargetMemoryId && !hasTargetFactIndex)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'Exactly one of targetMemoryId or targetFactIndex must be provided.',
+      })
+    }
+  })
+
+const MemoryDeltaItemSchema = z
+  .object({
+    fact: z.string().min(1).describe('The new fact candidate being classified.'),
+    classification: MemoryDeltaClassificationSchema.describe(
+      'How this fact relates to existing memories: new, supersedes, contradicts, enriches, duplicate.',
+    ),
+    targetMemoryIds: z
+      .array(z.string().min(1))
+      .default([])
+      .describe('Existing memory IDs that are directly related to this fact.'),
+    invalidateTargetIds: z
+      .array(z.string().min(1))
+      .default([])
+      .describe('Subset of targetMemoryIds that should be deleted as obsolete/invalidated.'),
+    relations: z
+      .array(MemoryDeltaRelationSchema)
+      .default([])
+      .describe('Explicit semantic relations from this fact to existing memories and/or other new facts by index.'),
+    rationale: z.string().min(1).describe('Short rationale for the classification decision.'),
+  })
+  .strict()
+
+export const MemoryDeltaSchema = z
+  .object({ deltas: z.array(MemoryDeltaItemSchema).describe('Classification output for each new fact.') })
+  .strict()
+export const MemoryImportanceAssessmentSchema = z
+  .object({
+    importance: z.number().min(0).max(1).describe('Long-term usefulness score from 0 to 1 for storing this memory.'),
+    durability: DurabilitySchema.describe('Expected durability for this memory.'),
+    classification: z.enum(['durable', 'transient', 'uncertain']).describe('Durability classification for storage.'),
+    rationale: z.string().min(1).describe('Concise rationale for the score/classification.'),
+  })
+  .strict()
+export interface Message {
+  role: 'user' | 'agent'
+  content: string
+}
+
+export interface MemoryConfig {
+  customPrompt?: string
+}

package/src/db/memory.ts

@@ -0,0 +1,505 @@
+import { env } from '../config/env-shapes'
+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 {
+  buildMemoryFactMaps,
+  compileMemoryUpdatesFromDelta,
+  createMemoryActionPlan,
+  postProcessMemoryFacts,
+} 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 type { SurrealMemoryStore } from './memory-store'
+import { getDefaultMemoryStore } from './memory-store'
+import { hashContent, isUniqueIndexConflict } from './memory-store.helpers'
+import { FactRetrievalSchema, MemoryDeltaSchema, MemoryUpdateSchema } from './memory-types'
+import type {
+  AddOptions,
+  Durability,
+  ExtractedFact,
+  MemoryConfig,
+  MemorySearchResult,
+  MemoryType,
+  MemoryUpdateOutput,
+  Message,
+  MemoryRecord,
+  SearchOptions,
+  WeightedSearchOptions,
+} from './memory-types'
+
+const MEMORY_WORKER_MODEL_TIMEOUT_MS = 10 * 60 * 1000
+const MEMORY_FACT_EXTRACTION_TIMEOUT_MS = MEMORY_WORKER_MODEL_TIMEOUT_MS
+const MEMORY_DELTA_CLASSIFICATION_TIMEOUT_MS = MEMORY_WORKER_MODEL_TIMEOUT_MS
+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 helperModelRuntime = createHelperModelRuntime()
+
+interface PreparedScopeUpdate {
+  options: AddOptions
+  updates: MemoryUpdateOutput
+  factMaps: ReturnType<typeof buildMemoryFactMaps>
+  existingMemories: Array<{ id: string; text: string }>
+}
+
+export class Memory {
+  private store: SurrealMemoryStore
+  private createAgent: CreateHelperAgentFn
+  private maxOutputTokens?: number
+  private config: MemoryConfig
+
+  constructor(agent: { createAgent: CreateHelperAgentFn; maxOutputTokens?: number }, config: MemoryConfig = {}) {
+    this.store = getDefaultMemoryStore()
+    this.createAgent = agent.createAgent
+    this.maxOutputTokens = agent.maxOutputTokens
+
+    this.config = config
+  }
+
+  private buildFactExtractionPrompt(customPrompt?: string): string | undefined {
+    const sections = [this.config.customPrompt, customPrompt]
+      .map((value) => value?.trim())
+      .filter((value): value is string => typeof value === 'string' && value.length > 0)
+    if (sections.length === 0) return undefined
+    return sections.join('\n\n')
+  }
+
+  async insert(
+    content: string,
+    options: {
+      scopeId: string
+      memoryType: MemoryType
+      importance?: number
+      metadata?: Record<string, unknown>
+      durability?: Durability
+    },
+  ): Promise<string> {
+    return await 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 results = await this.store.search(
+      query,
+      options.scopeId,
+      options.limit ?? env.MEMORY_SEARCH_K,
+      options.memoryType,
+    )
+
+    return formatResults(results)
+  }
+
+  async hybridSearch(query: string, options: SearchOptions): Promise<string> {
+    const results = await this.store.hybridSearch(
+      query,
+      options.scopeId,
+      options.limit ?? env.MEMORY_SEARCH_K,
+      options.memoryType,
+    )
+
+    return formatResults(results)
+  }
+
+  async hybridSearchWeighted(
+    query: string,
+    options: SearchOptions & { weights?: [number, number]; normalization?: 'minmax' | 'zscore' },
+  ): Promise<string> {
+    const results = await this.store.hybridSearchWeighted(query, {
+      scopeId: options.scopeId,
+      limit: options.limit ?? env.MEMORY_SEARCH_K,
+      memoryType: options.memoryType,
+      weights: options.weights,
+      normalization: options.normalization,
+    })
+
+    return formatResults(results)
+  }
+
+  async searchCandidates(query: string, options: WeightedSearchOptions): Promise<MemorySearchResult[]> {
+    const results = await this.store.hybridSearchWeighted(query, {
+      scopeId: options.scopeId,
+      limit: options.limit ?? env.MEMORY_SEARCH_K,
+      memoryType: options.memoryType,
+      weights: options.weights,
+      normalization: options.normalization,
+      fastMode: options.fastMode,
+    })
+
+    if (options.fastMode || options.includeNeighborContext === false) {
+      return results
+    }
+
+    return await this.store.enrichWithNeighbors(results)
+  }
+
+  async listTopMemories(options: {
+    scopeId: string
+    limit: number
+    memoryType?: MemoryType
+    durability?: Durability
+    minImportance?: number
+  }): Promise<MemoryRecord[]> {
+    return await this.store.listTopMemories(options)
+  }
+
+  async updateMemory(id: string, newContent: string): Promise<void> {
+    await this.store.update(id, newContent)
+  }
+
+  async getStaleMemories(scopeId: string, limit?: number): Promise<MemorySearchResult[]> {
+    return await this.store.getStaleMemories(scopeId, limit)
+  }
+
+  async add(
+    messages: Message[],
+    options: AddOptions,
+    extractionOptions?: { customPrompt?: string; maxFacts?: number },
+  ): Promise<void> {
+    const facts = await this.extractFactsFromMessages(messages, extractionOptions)
+    if (facts.length === 0) return
+
+    aiLogger.debug`Extracted ${facts.length} facts from conversation`
+
+    await this.applyFactsToScope(facts, options)
+  }
+
+  async addMultiScope(
+    messages: Message[],
+    scopes: AddOptions[],
+    extractionOptions?: { customPrompt?: string; maxFacts?: number },
+  ): Promise<void> {
+    if (scopes.length === 0) return
+    const facts = await this.extractFactsFromMessages(messages, extractionOptions)
+    if (facts.length === 0) return
+
+    aiLogger.debug`Extracted ${facts.length} facts, applying to ${scopes.length} scopes`
+
+    await this.applyFactsToScopes(facts, scopes)
+  }
+
+  async 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 []
+    }
+
+    return facts
+  }
+
+  async applyFactsToScopes(facts: ExtractedFact[], scopes: AddOptions[]): Promise<void> {
+    if (facts.length === 0 || scopes.length === 0) return
+
+    const prepared = await this.prepareFactsToScopes(facts, scopes)
+    await this.applyPreparedScopeUpdates(prepared)
+  }
+
+  async prepareFactsToScopes(facts: ExtractedFact[], scopes: AddOptions[]): Promise<PreparedScopeUpdate[]> {
+    if (facts.length === 0 || scopes.length === 0) return []
+
+    const prepared: PreparedScopeUpdate[] = []
+    for (const scopeOptions of scopes) {
+      prepared.push(await this.prepareFactsForScope(facts, scopeOptions))
+    }
+    return prepared
+  }
+
+  async applyPreparedScopeUpdates(prepared: PreparedScopeUpdate[]): Promise<void> {
+    if (prepared.length === 0) return
+
+    for (const item of prepared) {
+      await this.applyUpdates(item.updates, item.options, item.factMaps, item.existingMemories)
+    }
+  }
+
+  private async applyFactsToScope(facts: ExtractedFact[], options: AddOptions): Promise<void> {
+    const prepared = await this.prepareFactsForScope(facts, options)
+    await this.applyPreparedScopeUpdates([prepared])
+  }
+
+  private async prepareFactsForScope(facts: ExtractedFact[], options: AddOptions): Promise<PreparedScopeUpdate> {
+    const factMaps = buildMemoryFactMaps(facts)
+
+    const existingMemories = await this.store.list(options.scopeId, options.memoryType)
+    const oldMemoryFormat = existingMemories.map((m) => ({ id: m.id, text: m.content }))
+
+    const factContents = facts.map((f) => f.content)
+    const updates = await this.determineUpdates(oldMemoryFormat, factContents)
+
+    return { options, updates, factMaps, existingMemories: oldMemoryFormat }
+  }
+
+  private async extractFacts(
+    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,
+      })
+
+      return postProcessMemoryFacts(
+        result.facts,
+        typeof extractionOptions?.maxFacts === 'number' ? { maxFacts: extractionOptions.maxFacts } : {},
+      )
+    } catch (error) {
+      aiLogger.error`Failed to extract facts: ${error}`
+      return []
+    }
+  }
+
+  private async determineUpdates(
+    existingMemories: { id: string; text: string }[],
+    newFacts: string[],
+  ): Promise<MemoryUpdateOutput> {
+    if (existingMemories.length === 0) {
+      return { memory: newFacts.map((fact, index) => ({ id: `new_${index}`, text: fact, event: 'ADD' as const })) }
+    }
+
+    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})`
+
+    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,
+      })
+      const compiled = compileMemoryUpdatesFromDelta({ existingMemories, newFacts, delta: deltas })
+      return MemoryUpdateSchema.parse(compiled)
+    } catch (error) {
+      aiLogger.error`Failed to determine memory updates: ${error}`
+      throw error
+    }
+  }
+
+  private normalizeMemoryDeltaText(value: string, maxChars?: number): string {
+    const normalized = value.replace(/\s+/g, ' ').trim()
+    if (!normalized) return ''
+    if (typeof maxChars !== 'number' || normalized.length <= maxChars) return normalized
+    return `${normalized.slice(0, maxChars - 3)}...`
+  }
+
+  private tokenizeMemoryDeltaText(value: string): string[] {
+    return this.normalizeMemoryDeltaText(value)
+      .toLowerCase()
+      .replace(/[^\w\s$%./:-]/g, ' ')
+      .split(/\s+/)
+      .map((token) => token.trim())
+      .filter((token) => token.length >= 3)
+      .slice(0, 24)
+  }
+
+  private selectDeltaCandidateMemories(
+    existingMemories: { id: string; text: string }[],
+    newFacts: string[],
+  ): { id: string; text: string }[] {
+    const normalizedExisting = existingMemories
+      .map((memory, index) => ({
+        id: memory.id,
+        text: this.normalizeMemoryDeltaText(memory.text, MEMORY_DELTA_MEMORY_TEXT_MAX_CHARS),
+        index,
+      }))
+      .filter((memory) => memory.id.trim().length > 0 && memory.text.length > 0)
+
+    if (normalizedExisting.length <= MEMORY_DELTA_MAX_CANDIDATE_MEMORIES) {
+      return normalizedExisting.map((memory) => ({ id: memory.id, text: memory.text }))
+    }
+
+    const scoreById = new Map<string, number>()
+    for (const fact of newFacts) {
+      const factText = this.normalizeMemoryDeltaText(fact)
+      if (!factText) continue
+
+      const factTokens = this.tokenizeMemoryDeltaText(factText)
+      if (factTokens.length === 0) continue
+      const factLower = factText.toLowerCase()
+
+      const scoredForFact = normalizedExisting
+        .map((memory) => {
+          const memoryLower = memory.text.toLowerCase()
+          let overlap = 0
+          for (const token of factTokens) {
+            if (memoryLower.includes(token)) overlap += 1
+          }
+
+          const phraseBoost = factLower.length >= 10 && memoryLower.includes(factLower) ? 3 : 0
+          if (overlap === 0 && phraseBoost === 0) return { id: memory.id, score: 0 }
+
+          const recencyBoost = Math.max(0, 1 - memory.index / 120)
+          const coverageBoost = overlap / factTokens.length
+          return { id: memory.id, score: overlap + phraseBoost + coverageBoost + recencyBoost }
+        })
+        .filter((item) => item.score > 0)
+        .sort((left, right) => right.score - left.score)
+        .slice(0, MEMORY_DELTA_MAX_CANDIDATES_PER_FACT)
+
+      for (const candidate of scoredForFact) {
+        const current = scoreById.get(candidate.id) ?? 0
+        if (candidate.score > current) {
+          scoreById.set(candidate.id, candidate.score)
+        }
+      }
+    }
+
+    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),
+    )
+
+    const selectedIds = new Set<string>(
+      [...scoreById.entries()]
+        .sort((left, right) => right[1] - left[1])
+        .slice(0, targetCandidateCount)
+        .map(([id]) => id),
+    )
+
+    if (selectedIds.size < baselineCount) {
+      for (const memory of normalizedExisting) {
+        selectedIds.add(memory.id)
+        if (selectedIds.size >= baselineCount) break
+      }
+    }
+
+    if (selectedIds.size === 0) {
+      for (const memory of normalizedExisting.slice(0, baselineCount)) {
+        selectedIds.add(memory.id)
+      }
+    }
+
+    const selected = normalizedExisting
+      .filter((memory) => selectedIds.has(memory.id))
+      .sort((left, right) => {
+        const scoreDiff = (scoreById.get(right.id) ?? 0) - (scoreById.get(left.id) ?? 0)
+        if (scoreDiff !== 0) return scoreDiff
+        return left.index - right.index
+      })
+      .slice(0, targetCandidateCount)
+
+    return selected.map((memory) => ({ id: memory.id, text: memory.text }))
+  }
+
+  private async 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,
+      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 = action.text.length > 50 ? `${action.text.slice(0, 50)}...` : action.text
+          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,
+            )
+          } 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
+        }
+
+        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}: ${action.text.slice(0, 50)}...`
+          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 relation: ${error}`
+      }
+    }
+  }
+}