@lota-sdk/core 0.4.7 → 0.4.9

package/src/services/memory.service.ts

@@ -1,844 +0,0 @@
-import { z } from 'zod'
-
-import { agentRoster } from '../config/agent-defaults'
-import { aiLogger } from '../config/logger'
-import { Memory } from '../db/memory'
-import { isUniqueIndexConflict } from '../db/memory-store.helpers'
-import type {
-  AddOptions,
-  ExtractedFact,
-  MemoryListScalar,
-  MemoryRecord,
-  MemorySearchResult,
-  MemoryType,
-  Message,
-  RelationType,
-} from '../db/memory-types'
-import { withOrgMemoryLock } from '../redis/org-memory-lock'
-import { createHelperModelRuntime } from '../runtime/helper-model'
-import { sanitizeAgentOutputForMemory } from '../runtime/llm-content'
-import { ORG_SCOPE_PREFIX, agentScopeId, scopeId } from '../runtime/memory-scope'
-import {
-  countScopedRetrievalCandidates,
-  executeScopedRetrieval,
-  scopedRetrievalToMap,
-} from '../runtime/retrieval-adapters'
-import { getRuntimeConfig } from '../runtime/runtime-config'
-import { createMemoryRerankerAgent, MEMORY_RERANKER_PROMPT } from '../system-agents/memory-reranker.agent'
-import { createOrgMemoryAgent, ORG_MEMORY_PROMPT } from '../system-agents/memory.agent'
-import { clampImportance, compactWhitespace, truncateText } from '../utils/string'
-import { formatMemoryResults, formatRerankedResults, getCandidateLimit } from './memory-utils'
-
-const ORG_MEMORY_TYPE = 'fact'
-const RERANK_CANDIDATE_MAX_CHARS = 500
-const MAX_MEMORY_RESULTS_PER_SCOPE = 10
-const PRESEEDED_MEMORY_LIMIT = 5
-const PRESEEDED_MEMORY_MAX_CHARS = 300
-const PRESEEDED_MIN_IMPORTANCE = 0.7
-const PRESEEDED_MEMORY_DURABILITY: MemoryRecord['durability'] = 'core'
-const MAX_CONVERSATION_HISTORY_MESSAGES = 24
-const MAX_CONVERSATION_MESSAGE_CHARS = 1_200
-const MAX_CONVERSATION_MEMORY_BLOCK_CHARS = 2_000
-const MAX_CONVERSATION_ATTACHMENT_CONTEXT_CHARS = 6_000
-const ONBOARDING_MEMORY_MAX_FACTS = 16
-const MAX_ORG_MEMORY_CLIENTS = 128
-const LOW_VALUE_MEMORY_IMPORTANCE_THRESHOLD = 0.45
-const ONBOARDING_MEMORY_EXTRACTION_PROMPT =
-  'Onboarding mode is active. Extract multiple concrete startup facts from user-provided context: company mission, product capabilities, customer segments, pricing, traction, go-to-market plans, roadmap, team composition, technical stack, risks, and referenced URLs. Prefer one fact per concrete claim.'
-const DIRECT_MEMORY_ASSESSMENT_PROMPT =
-  'The user is submitting a direct memory candidate. Keep the wording faithful. Return one fact only when the statement is durable enough for memory; otherwise return no facts.'
-
-const helperModelRuntime = createHelperModelRuntime()
-
-const MemoryRerankOutputSchema = z.object({
-  sections: z.array(
-    z.object({
-      title: z.string(),
-      items: z.array(
-        z.object({
-          id: z.string(),
-          relevance: z.string().describe('Short relevance reason. Use empty string when no reason is needed.'),
-        }),
-      ),
-    }),
-  ),
-})
-
-export type MemoryRerankOutput = z.infer<typeof MemoryRerankOutputSchema>
-
-const isRoutableAgentName = (value?: string): value is string => Boolean(value && agentRoster.includes(value))
-
-class MemoryService {
-  private orgMemoryCache = new Map<string, Memory>()
-
-  private getOrCreateMemory(cacheKey: string, cache: Map<string, Memory>): Memory {
-    const cached = cache.get(cacheKey)
-    if (cached) {
-      cache.delete(cacheKey)
-      cache.set(cacheKey, cached)
-      return cached
-    }
-
-    const memory = new Memory({ createAgent: createOrgMemoryAgent }, { customPrompt: ORG_MEMORY_PROMPT })
-
-    if (cache.size >= MAX_ORG_MEMORY_CLIENTS) {
-      const oldestKey = cache.keys().next().value
-      if (typeof oldestKey === 'string') {
-        cache.delete(oldestKey)
-        aiLogger.debug`Evicted cached org memory client for ${oldestKey}`
-      }
-    }
-
-    cache.set(cacheKey, memory)
-    aiLogger.debug`Memory client created and cached for ${cacheKey}`
-    return memory
-  }
-
-  private getOrgMemory(orgId: string): Memory {
-    const cacheKey = scopeId(ORG_SCOPE_PREFIX, orgId)
-    return this.getOrCreateMemory(cacheKey, this.orgMemoryCache)
-  }
-
-  private truncateCandidateText(value: string): string {
-    return truncateText(compactWhitespace(value), RERANK_CANDIDATE_MAX_CHARS)
-  }
-
-  private readNumericMetadata(metadata: Record<string, unknown>, key: string): number {
-    const value = metadata[key]
-    if (typeof value === 'number' && Number.isFinite(value)) return value
-    return 0
-  }
-
-  private buildRerankerCandidateText(candidate: MemorySearchResult): string {
-    const metadata = candidate.metadata
-    const relationCount = this.readNumericMetadata(metadata, 'relationCount')
-    const supportCount = this.readNumericMetadata(metadata, 'supportCount')
-    const contradictCount = this.readNumericMetadata(metadata, 'contradictCount')
-
-    const relatedContextRaw = metadata.relatedContext
-    const relatedContext = Array.isArray(relatedContextRaw)
-      ? relatedContextRaw
-          .slice(0, 3)
-          .map((item) => String(item).trim())
-          .filter((item) => item.length > 0)
-      : []
-
-    const contextLines: string[] = []
-    if (relatedContext.length > 0) {
-      contextLines.push(`Related context: ${relatedContext.join(' | ')}`)
-    }
-    if (relationCount > 0 || supportCount > 0 || contradictCount > 0) {
-      contextLines.push(
-        `Graph signals: relations=${relationCount}; supports=${supportCount}; contradicts=${contradictCount}`,
-      )
-    }
-
-    if (contextLines.length === 0) return candidate.content
-    return `${candidate.content}\n\n${contextLines.join('\n')}`
-  }
-
-  private normalizeConversationText(value: string, maxChars: number): string {
-    const normalized = compactWhitespace(value)
-    if (!normalized) return ''
-    return truncateText(normalized, maxChars)
-  }
-
-  private resolveAgentScopeNames(agentName?: string, agentNames: string[] = []): string[] {
-    const unique = new Set<string>()
-    if (typeof agentName === 'string' && agentName.trim()) {
-      unique.add(agentName.trim())
-    }
-    for (const candidate of agentNames) {
-      if (typeof candidate !== 'string') continue
-      const normalized = candidate.trim()
-      if (!normalized) continue
-      unique.add(normalized)
-    }
-    return [...unique].filter((name) => isRoutableAgentName(name))
-  }
-
-  private normalizePreSeededMemoryText(value: string): string {
-    return truncateText(compactWhitespace(value), PRESEEDED_MEMORY_MAX_CHARS)
-  }
-
-  private formatPreSeededMemoriesSection(memories: MemoryRecord[]): string | undefined {
-    const lines = memories
-      .map((memory) => this.normalizePreSeededMemoryText(memory.content))
-      .filter((line) => line.length > 0)
-      .map((line) => `- ${line}`)
-    if (lines.length === 0) return undefined
-
-    return ['<pre-seeded-memories>', ...lines, '</pre-seeded-memories>'].join('\n')
-  }
-
-  private buildConversationMessages(params: {
-    input: string
-    output: string
-    historyMessages: Array<{ role: 'user' | 'agent'; content: string; agentName?: string }>
-    memoryBlock?: string
-    attachmentContext?: string
-  }): { messages: Message[]; normalizedInput: string; sanitizedOutput: string } {
-    const normalizedInput = this.normalizeConversationText(params.input, MAX_CONVERSATION_MESSAGE_CHARS)
-    const sanitizedOutput = this.normalizeConversationText(
-      sanitizeAgentOutputForMemory(params.output),
-      MAX_CONVERSATION_MESSAGE_CHARS,
-    )
-    if (!normalizedInput || !sanitizedOutput) {
-      return { messages: [], normalizedInput, sanitizedOutput }
-    }
-
-    const messages: Message[] = []
-
-    const normalizedHistory: Message[] = params.historyMessages
-      .map((message): Message | null => {
-        const role: Message['role'] = message.role === 'agent' ? 'agent' : 'user'
-        const normalized = this.normalizeConversationText(
-          role === 'agent' ? sanitizeAgentOutputForMemory(message.content) : message.content,
-          MAX_CONVERSATION_MESSAGE_CHARS,
-        )
-        if (!normalized) return null
-        return { role, content: normalized }
-      })
-      .filter((message): message is Message => message !== null)
-      .slice(-MAX_CONVERSATION_HISTORY_MESSAGES)
-
-    messages.push(...normalizedHistory)
-
-    const normalizedMemoryBlock = this.normalizeConversationText(
-      params.memoryBlock ?? '',
-      MAX_CONVERSATION_MEMORY_BLOCK_CHARS,
-    )
-    if (normalizedMemoryBlock) {
-      messages.push({ role: 'user', content: `Thread memory block:\n${normalizedMemoryBlock}` })
-    }
-
-    const normalizedAttachmentContext = this.normalizeConversationText(
-      params.attachmentContext ?? '',
-      MAX_CONVERSATION_ATTACHMENT_CONTEXT_CHARS,
-    )
-    if (normalizedAttachmentContext) {
-      messages.push({ role: 'user', content: `Attachment context:\n${normalizedAttachmentContext}` })
-    }
-
-    messages.push({ role: 'user', content: normalizedInput })
-    messages.push({ role: 'agent', content: sanitizedOutput })
-
-    return { messages, normalizedInput, sanitizedOutput }
-  }
-
-  private async rerankCandidates(
-    query: string,
-    candidates: MemorySearchResult[],
-    maxItems: number,
-  ): Promise<MemoryRerankOutput | null> {
-    if (candidates.length === 0) return null
-
-    try {
-      return await helperModelRuntime.generateHelperStructured({
-        tag: 'memory-reranker',
-        createAgent: createMemoryRerankerAgent,
-        defaultSystemPrompt: MEMORY_RERANKER_PROMPT,
-        messages: [
-          {
-            role: 'user',
-            content: JSON.stringify({
-              query,
-              maxItems,
-              candidates: candidates.map((candidate) => ({
-                id: candidate.id,
-                text: this.truncateCandidateText(this.buildRerankerCandidateText(candidate)),
-                score: candidate.score,
-              })),
-            }),
-          },
-        ],
-        schema: MemoryRerankOutputSchema,
-      })
-    } catch (error) {
-      aiLogger.warn`Memory reranker failed: ${error}`
-      return null
-    }
-  }
-
-  private async rerankCandidatesMultiScope(
-    query: string,
-    scopedCandidates: Array<{ scopeTag: string; candidates: MemorySearchResult[] }>,
-    maxItems: number,
-  ): Promise<MemoryRerankOutput | null> {
-    const flattened = scopedCandidates.flatMap(({ scopeTag, candidates }) =>
-      candidates.map((candidate) => ({ ...candidate, scopeTag })),
-    )
-    if (flattened.length === 0 || flattened.length <= maxItems) return null
-
-    try {
-      return await helperModelRuntime.generateHelperStructured({
-        tag: 'memory-reranker-multi-scope',
-        createAgent: createMemoryRerankerAgent,
-        defaultSystemPrompt: MEMORY_RERANKER_PROMPT,
-        messages: [
-          {
-            role: 'user',
-            content: JSON.stringify({
-              query,
-              maxItems,
-              candidates: flattened.map((candidate) => ({
-                id: candidate.id,
-                text: this.truncateCandidateText(this.buildRerankerCandidateText(candidate)),
-                score: candidate.score,
-                scope: candidate.scopeTag,
-              })),
-            }),
-          },
-        ],
-        schema: MemoryRerankOutputSchema,
-      })
-    } catch (error) {
-      aiLogger.warn`Multi-scope memory reranker failed: ${error}`
-      return null
-    }
-  }
-
-  private async searchMemories({
-    query,
-    memory,
-    scopeId,
-    memoryType,
-    fastMode = true,
-  }: {
-    query: string
-    memory: Memory
-    scopeId: string
-    memoryType: MemoryType
-    fastMode?: boolean
-  }): Promise<string> {
-    const limit = getRuntimeConfig().memory.searchK
-    const candidateLimit = fastMode ? limit : getCandidateLimit(limit)
-
-    const candidates = await memory.searchCandidates(query, {
-      scopeId,
-      limit: candidateLimit,
-      memoryType,
-      fastMode,
-      includeNeighborContext: !fastMode,
-    })
-
-    aiLogger.debug`Memory search candidates (scopeId: ${scopeId}, candidates: ${candidates.length})`
-
-    if (candidates.length === 0) {
-      return 'No stored memories.'
-    }
-
-    if (fastMode || candidates.length <= limit) {
-      aiLogger.debug`Skipping reranking (candidates: ${candidates.length} <= limit: ${limit})`
-      return formatMemoryResults(candidates.slice(0, limit))
-    }
-
-    const reranked = await this.rerankCandidates(query, candidates, limit)
-    return formatRerankedResults(reranked, candidates, limit)
-  }
-
-  async searchOrganizationMemories(orgId: string, query: string): Promise<string> {
-    const orgScopeId = scopeId(ORG_SCOPE_PREFIX, orgId)
-    aiLogger.debug`Organization memory search requested (orgId: ${orgId}, scopeId: ${orgScopeId}, queryLength: ${query.length})`
-    const memory = this.getOrgMemory(orgId)
-
-    const results = await this.searchMemories({ query, memory, scopeId: orgScopeId, memoryType: ORG_MEMORY_TYPE })
-    aiLogger.debug`Organization memory search completed (resultLength: ${results.length}, preview: ${results.slice(0, 100)})`
-    return results
-  }
-
-  async getStaleMemories(orgId: string): Promise<string> {
-    const orgScopeId = scopeId(ORG_SCOPE_PREFIX, orgId)
-    const memory = this.getOrgMemory(orgId)
-    try {
-      const stale = await memory.getStaleMemories(orgScopeId)
-      if (stale.length === 0) return ''
-      const items = stale.map((m) => `- [NEEDS REVIEW] ${m.content}`).join('\n')
-      return `Memories flagged for review (parent fact was superseded):\n${items}`
-    } catch (error) {
-      aiLogger.warn`Failed to get stale memories: ${error}`
-      return ''
-    }
-  }
-
-  async searchOrganizationMemoriesRaw(
-    orgId: string,
-    query: string,
-    options?: { fastMode?: boolean; limit?: number },
-  ): Promise<string> {
-    const orgScopeId = scopeId(ORG_SCOPE_PREFIX, orgId)
-    aiLogger.debug`searchOrganizationMemoriesRaw - orgId: "${orgId}", scopeId: "${orgScopeId}"`
-    const memory = this.getOrgMemory(orgId)
-    const fastMode = options?.fastMode ?? true
-    const searchK = getRuntimeConfig().memory.searchK
-    const limit = options?.limit ?? (fastMode ? Math.min(searchK, 4) : searchK)
-
-    const candidates = await memory.searchCandidates(query, {
-      scopeId: orgScopeId,
-      limit,
-      memoryType: ORG_MEMORY_TYPE,
-      fastMode,
-      includeNeighborContext: !fastMode,
-    })
-    aiLogger.debug`Organization memory search (raw) completed (candidates: ${candidates.length})`
-    return formatMemoryResults(candidates)
-  }
-
-  async searchAgentMemories(orgId: string, agentName: string, query: string): Promise<string> {
-    if (!isRoutableAgentName(agentName)) {
-      aiLogger.debug`Agent memory search skipped - invalid agentName: ${agentName}`
-      return 'No stored memories.'
-    }
-
-    const scoped = agentScopeId(orgId, agentName)
-    aiLogger.debug`Agent memory search requested (orgId: ${orgId}, agentName: ${agentName}, scopeId: ${scoped}, queryLength: ${query.length})`
-    const memory = this.getOrgMemory(orgId)
-
-    const results = await this.searchMemories({ query, memory, scopeId: scoped, memoryType: ORG_MEMORY_TYPE })
-    aiLogger.debug`Agent memory search completed (agentName: ${agentName}, resultLength: ${results.length}, preview: ${results.slice(0, 100)})`
-    return results
-  }
-
-  async searchOrgMemoriesForAgent(orgId: string, agentName: string, query: string): Promise<string> {
-    if (!isRoutableAgentName(agentName)) {
-      return this.searchOrganizationMemories(orgId, query)
-    }
-
-    const [agentResult, orgResult] = await Promise.all([
-      this.searchAgentMemories(orgId, agentName, query),
-      this.searchOrganizationMemories(orgId, query),
-    ])
-
-    return `Agent memory (${agentName}):\n${agentResult}\n\nGlobal org memory:\n${orgResult}`
-  }
-
-  async listOrganizationMemoryRecords(params: {
-    orgId: string
-    limit?: number
-    memoryType?: MemoryType
-    metadataEquals?: Record<string, MemoryListScalar>
-    metadataNotEquals?: Record<string, MemoryListScalar>
-    sort?: 'createdAtAsc' | 'createdAtDesc'
-  }): Promise<MemoryRecord[]> {
-    const { orgId, ...listOptions } = params
-    const orgMemory = this.getOrgMemory(orgId)
-    return orgMemory.list({ scopeId: scopeId(ORG_SCOPE_PREFIX, orgId), ...listOptions })
-  }
-
-  async getTopMemories(params: { orgId: string; agentName?: string; limit?: number }): Promise<string | undefined> {
-    const orgMemory = this.getOrgMemory(params.orgId)
-    const orgScopeId = scopeId(ORG_SCOPE_PREFIX, params.orgId)
-    const requestedLimit = params.limit ?? PRESEEDED_MEMORY_LIMIT
-    const limit = Math.max(1, Math.min(requestedLimit, PRESEEDED_MEMORY_LIMIT))
-
-    const orgRequest = orgMemory.listTopMemories({
-      scopeId: orgScopeId,
-      limit,
-      memoryType: ORG_MEMORY_TYPE,
-      durability: PRESEEDED_MEMORY_DURABILITY,
-      minImportance: PRESEEDED_MIN_IMPORTANCE,
-    })
-
-    const agentRequest =
-      params.agentName && isRoutableAgentName(params.agentName)
-        ? orgMemory.listTopMemories({
-            scopeId: agentScopeId(params.orgId, params.agentName),
-            limit,
-            memoryType: ORG_MEMORY_TYPE,
-            durability: PRESEEDED_MEMORY_DURABILITY,
-            minImportance: PRESEEDED_MIN_IMPORTANCE,
-          })
-        : Promise.resolve([] as MemoryRecord[])
-
-    const [orgTopMemories, agentTopMemories] = await Promise.all([orgRequest, agentRequest])
-    const combined = [...agentTopMemories, ...orgTopMemories].sort((left, right) => {
-      if (right.importance !== left.importance) return right.importance - left.importance
-      if (right.accessCount !== left.accessCount) return right.accessCount - left.accessCount
-      const rightLastAccess = right.lastAccessedAt?.getTime() ?? 0
-      const leftLastAccess = left.lastAccessedAt?.getTime() ?? 0
-      if (rightLastAccess !== leftLastAccess) return rightLastAccess - leftLastAccess
-      return right.createdAt.getTime() - left.createdAt.getTime()
-    })
-
-    const deduped: MemoryRecord[] = []
-    const seen = new Set<string>()
-    for (const memory of combined) {
-      const normalizedKey = compactWhitespace(memory.content).toLowerCase()
-      if (!normalizedKey || seen.has(normalizedKey)) continue
-      seen.add(normalizedKey)
-      deduped.push(memory)
-      if (deduped.length >= limit) break
-    }
-
-    return this.formatPreSeededMemoriesSection(deduped)
-  }
-
-  async searchAllMemoriesBatched({
-    orgId,
-    agentName,
-    query,
-    fastMode = true,
-    allowMultiScopeRerank = true,
-  }: {
-    orgId: string
-    agentName?: string
-    query: string
-    fastMode?: boolean
-    allowMultiScopeRerank?: boolean
-  }): Promise<string> {
-    const limit = Math.min(getRuntimeConfig().memory.searchK, MAX_MEMORY_RESULTS_PER_SCOPE)
-    const candidateLimit = fastMode ? limit : getCandidateLimit(limit)
-    const orgScopeId = scopeId(ORG_SCOPE_PREFIX, orgId)
-    const orgMemory = this.getOrgMemory(orgId)
-
-    const retrievalTasks = [
-      {
-        scopeTag: 'org',
-        retrieve: async () =>
-          await orgMemory.searchCandidates(query, {
-            scopeId: orgScopeId,
-            limit: candidateLimit,
-            memoryType: ORG_MEMORY_TYPE,
-            fastMode,
-            includeNeighborContext: !fastMode,
-          }),
-      },
-    ]
-
-    if (isRoutableAgentName(agentName)) {
-      const agentScoped = agentScopeId(orgId, agentName)
-      retrievalTasks.push({
-        scopeTag: `agent:${agentName}`,
-        retrieve: async () =>
-          await orgMemory.searchCandidates(query, {
-            scopeId: agentScoped,
-            limit: candidateLimit,
-            memoryType: ORG_MEMORY_TYPE,
-            fastMode,
-            includeNeighborContext: !fastMode,
-          }),
-      })
-    }
-
-    const results = await executeScopedRetrieval<MemorySearchResult>(retrievalTasks)
-
-    const totalCandidates = countScopedRetrievalCandidates(results)
-    aiLogger.debug`Batched memory search candidates (scopes: ${results.length}, total: ${totalCandidates})`
-
-    if (totalCandidates === 0) {
-      return 'No stored memories.'
-    }
-
-    if (fastMode || !allowMultiScopeRerank) {
-      const candidatesByScopeTag = scopedRetrievalToMap(results)
-      return this.formatBatchedResults(null, candidatesByScopeTag, limit, agentName)
-    }
-
-    const reranked = await this.rerankCandidatesMultiScope(query, results, limit)
-    const candidatesByScopeTag = scopedRetrievalToMap(results)
-
-    return this.formatBatchedResults(reranked, candidatesByScopeTag, limit, agentName)
-  }
-
-  private formatBatchedResults(
-    reranked: MemoryRerankOutput | null,
-    candidatesByScopeTag: Map<string, MemorySearchResult[]>,
-    limit: number,
-    agentName?: string,
-  ): string {
-    if (reranked && reranked.sections.length > 0) {
-      const allCandidates = Array.from(candidatesByScopeTag.values()).flat()
-      return formatRerankedResults(reranked, allCandidates, limit)
-    }
-
-    const sections: string[] = []
-
-    if (agentName) {
-      const agentCandidates = candidatesByScopeTag.get(`agent:${agentName}`) ?? []
-      if (agentCandidates.length > 0) {
-        sections.push(`Agent memory (${agentName}):\n${formatMemoryResults(agentCandidates.slice(0, limit))}`)
-      } else {
-        sections.push(`Agent memory (${agentName}):\nNo stored memories.`)
-      }
-    }
-
-    const orgCandidates = candidatesByScopeTag.get('org') ?? []
-    if (orgCandidates.length > 0) {
-      sections.push(
-        `${agentName ? 'Global org memory' : 'Organization memory'}:\n${formatMemoryResults(orgCandidates.slice(0, limit))}`,
-      )
-    } else {
-      sections.push(`${agentName ? 'Global org memory' : 'Organization memory'}:\nNo stored memories.`)
-    }
-
-    return sections.join('\n\n')
-  }
-
-  async createOrganizationMemory({
-    orgId,
-    content,
-    memoryType,
-    metadata,
-    importance,
-    durability,
-  }: {
-    orgId: string
-    content: string
-    memoryType: MemoryType
-    metadata?: Record<string, unknown>
-    importance?: number
-    durability?: MemoryRecord['durability']
-  }): Promise<string> {
-    const orgScopeId = scopeId(ORG_SCOPE_PREFIX, orgId)
-    aiLogger.debug`createOrganizationMemory - orgId: "${orgId}", scopeId: "${orgScopeId}", content preview: "${content.slice(0, 50)}"`
-    const memory = this.getOrgMemory(orgId)
-    try {
-      return await memory.insert(content, {
-        scopeId: orgScopeId,
-        memoryType,
-        importance: importance ?? 1,
-        durability,
-        metadata: { orgId, ...metadata },
-      })
-    } catch (error) {
-      if (isUniqueIndexConflict(error, 'memoryHashIdx')) {
-        aiLogger.debug`Organization memory already exists (hash conflict)`
-        return ''
-      }
-      throw error
-    }
-  }
-
-  async addOrganizationMemoryRelation({
-    orgId,
-    fromMemoryId,
-    toMemoryId,
-    relationType,
-    confidence,
-  }: {
-    orgId: string
-    fromMemoryId: string
-    toMemoryId: string
-    relationType: RelationType
-    confidence?: number
-  }): Promise<void> {
-    const memory = this.getOrgMemory(orgId)
-    await memory.addRelation(fromMemoryId, toMemoryId, relationType, confidence)
-  }
-
-  async createAgentMemory({
-    orgId,
-    agentName,
-    content,
-    memoryType,
-    metadata,
-    importance,
-  }: {
-    orgId: string
-    agentName: string
-    content: string
-    memoryType: MemoryType
-    metadata?: Record<string, unknown>
-    importance?: number
-  }): Promise<string> {
-    if (!isRoutableAgentName(agentName)) {
-      throw new Error(`Invalid agentName for agent memory: ${agentName as string}`)
-    }
-
-    const memory = this.getOrgMemory(orgId)
-    const scoped = agentScopeId(orgId, agentName)
-    try {
-      return await memory.insert(content, {
-        scopeId: scoped,
-        memoryType,
-        importance: importance ?? 1,
-        metadata: { orgId, agentName, memoryScope: 'agent', ...metadata },
-      })
-    } catch (error) {
-      if (isUniqueIndexConflict(error, 'memoryHashIdx')) {
-        aiLogger.debug`Agent memory already exists (hash conflict)`
-        return ''
-      }
-      throw error
-    }
-  }
-
-  async assessMemoryCandidate(params: {
-    orgId: string
-    content: string
-  }): Promise<Pick<ExtractedFact, 'classification' | 'durability' | 'importance' | 'rationale'> | null> {
-    const trimmed = compactWhitespace(params.content)
-    if (!trimmed) return null
-
-    const facts = await this.getOrgMemory(params.orgId).extractFactsFromMessages([{ role: 'user', content: trimmed }], {
-      maxFacts: 1,
-      customPrompt: DIRECT_MEMORY_ASSESSMENT_PROMPT,
-    })
-    if (facts.length === 0) return null
-    const fact = facts[0]
-
-    return {
-      classification: fact.classification,
-      durability: fact.durability,
-      importance: clampImportance(fact.importance),
-      rationale: fact.rationale,
-    }
-  }
-
-  private shouldSkipExtractedFacts(facts: ExtractedFact[]): boolean {
-    if (facts.length === 0) return true
-    return facts.every(
-      (fact) =>
-        fact.durability === 'ephemeral' &&
-        fact.importance <= LOW_VALUE_MEMORY_IMPORTANCE_THRESHOLD &&
-        fact.classification !== 'durable',
-    )
-  }
-
-  async updateOrganizationMemoryById({
-    orgId,
-    memoryId,
-    content,
-  }: {
-    orgId: string
-    memoryId: string
-    content: string
-  }): Promise<void> {
-    const memory = this.getOrgMemory(orgId)
-    await memory.updateMemory(memoryId, content)
-  }
-
-  async addExtractedFactsToScopes(params: {
-    orgId: string
-    facts: ExtractedFact[]
-    source: string
-    sourceMetadata?: Record<string, unknown>
-    agentNames?: string[]
-    acquireLock?: boolean
-  }): Promise<void> {
-    if (params.facts.length === 0) return
-
-    const orgMemory = this.getOrgMemory(params.orgId)
-    const scopes: AddOptions[] = [
-      {
-        scopeId: scopeId(ORG_SCOPE_PREFIX, params.orgId),
-        memoryType: ORG_MEMORY_TYPE,
-        metadata: { orgId: params.orgId, source: params.source, ...params.sourceMetadata },
-      },
-    ]
-
-    for (const scopedAgentName of this.resolveAgentScopeNames(undefined, params.agentNames ?? [])) {
-      scopes.push({
-        scopeId: agentScopeId(params.orgId, scopedAgentName),
-        memoryType: ORG_MEMORY_TYPE,
-        metadata: {
-          orgId: params.orgId,
-          source: params.source,
-          ...params.sourceMetadata,
-          agentName: scopedAgentName,
-          memoryScope: 'agent',
-        },
-      })
-    }
-
-    const preparedUpdates = await orgMemory.prepareFactsToScopes(params.facts, scopes)
-    if (preparedUpdates.length === 0) return
-
-    if (params.acquireLock === false) {
-      await orgMemory.applyPreparedScopeUpdates(preparedUpdates)
-    } else {
-      await withOrgMemoryLock(params.orgId, async () => {
-        await orgMemory.applyPreparedScopeUpdates(preparedUpdates)
-      })
-    }
-  }
-
-  async addConversationMemories({
-    orgId,
-    input,
-    output,
-    sourceId,
-    source = 'chat',
-    sourceMetadata,
-    onboardStatus,
-    agentName,
-    historyMessages = [],
-    memoryBlock,
-    attachmentContext,
-    agentNames = [],
-  }: {
-    orgId: string
-    input: string
-    output: string
-    sourceId?: string
-    source?: string
-    sourceMetadata?: Record<string, unknown>
-    onboardStatus?: string
-    agentName?: string
-    historyMessages?: Array<{ role: 'user' | 'agent'; content: string; agentName?: string }>
-    memoryBlock?: string
-    attachmentContext?: string
-    agentNames?: string[]
-  }): Promise<void> {
-    const { messages, normalizedInput, sanitizedOutput } = this.buildConversationMessages({
-      input,
-      output,
-      historyMessages,
-      memoryBlock,
-      attachmentContext,
-    })
-
-    if (!normalizedInput || !sanitizedOutput || messages.length === 0) {
-      aiLogger.debug`Skipping memory add - empty input or output`
-      return
-    }
-
-    const orgScopeId = scopeId(ORG_SCOPE_PREFIX, orgId)
-    aiLogger.debug`addConversationMemories - orgId: "${orgId}", scopeId: "${orgScopeId}", sourceId: ${sourceId ?? 'none'}`
-
-    const orgMemory = this.getOrgMemory(orgId)
-
-    const scopes: AddOptions[] = [
-      {
-        scopeId: orgScopeId,
-        memoryType: ORG_MEMORY_TYPE,
-        metadata: { orgId, source, ...(sourceId ? { sourceId } : {}), ...sourceMetadata },
-      },
-    ]
-
-    for (const scopedAgentName of this.resolveAgentScopeNames(agentName, agentNames)) {
-      const agentId = agentScopeId(orgId, scopedAgentName)
-      scopes.push({
-        scopeId: agentId,
-        memoryType: ORG_MEMORY_TYPE,
-        metadata: {
-          orgId,
-          agentName: scopedAgentName,
-          memoryScope: 'agent',
-          source,
-          ...(sourceId ? { sourceId } : {}),
-          ...sourceMetadata,
-        },
-      })
-    }
-
-    const onboardingActive = onboardStatus !== undefined && onboardStatus !== 'completed'
-    const extractionConfig = onboardingActive
-      ? { maxFacts: ONBOARDING_MEMORY_MAX_FACTS, customPrompt: ONBOARDING_MEMORY_EXTRACTION_PROMPT }
-      : undefined
-    const extractedFacts = await orgMemory.extractFactsFromMessages(messages, extractionConfig)
-    if (this.shouldSkipExtractedFacts(extractedFacts)) {
-      aiLogger.debug`Skipping transient conversation memory`
-      return
-    }
-    const preparedUpdates = await orgMemory.prepareFactsToScopes(extractedFacts, scopes)
-    if (preparedUpdates.length === 0) return
-
-    await withOrgMemoryLock(orgId, async () => {
-      await orgMemory.applyPreparedScopeUpdates(preparedUpdates)
-    })
-    aiLogger.debug`Conversation memories added to ${scopes.length} scope(s) from ${messages.length} message(s)`
-  }
-}
-
-export const memoryService = new MemoryService()