@lota-sdk/core 0.1.5

package/src/services/memory.service.ts

@@ -0,0 +1,807 @@
+import { z } from 'zod'
+
+import { agentRoster } from '../config/agent-defaults'
+import { env } from '../config/env-shapes'
+import { aiLogger } from '../config/logger'
+import { Memory } from '../db/memory'
+import { isUniqueIndexConflict } from '../db/memory-store.helpers'
+import type {
+  AddOptions,
+  ExtractedFact,
+  MemoryRecord,
+  MemorySearchResult,
+  MemoryType,
+  Message,
+} 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 { createMemoryRerankerAgent, memoryRerankerPrompt } from '../system-agents/memory-reranker.agent'
+import { createOrgMemoryAgent, orgMemoryPrompt } from '../system-agents/memory.agent'
+import { assessMemoryImportance, clampMemoryImportance } from './memory-assessment.service'
+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 MAX_CONVERSATION_ASSESSMENT_CHARS = 7_000
+const ONBOARDING_MEMORY_MAX_FACTS = 16
+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 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): boolean => 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) return cached
+
+    const memory = new Memory({ createAgent: createOrgMemoryAgent }, { customPrompt: orgMemoryPrompt })
+
+    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 {
+    const normalized = value.replace(/\s+/g, ' ').trim()
+    if (normalized.length <= RERANK_CANDIDATE_MAX_CHARS) return normalized
+    return `${normalized.slice(0, 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 = value.replace(/\s+/g, ' ').trim()
+    if (!normalized) return ''
+    if (normalized.length <= maxChars) return normalized
+    return `${normalized.slice(0, maxChars - 3)}...`
+  }
+
+  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 {
+    const normalized = value.replace(/\s+/g, ' ').trim()
+    if (normalized.length <= PRESEEDED_MEMORY_MAX_CHARS) return normalized
+    return `${normalized.slice(0, PRESEEDED_MEMORY_MAX_CHARS - 3)}...`
+  }
+
+  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: `Workstream 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 buildConversationAssessmentInput(messages: Message[]): string {
+    const lines = messages.map((message, index) => `[${message.role.toUpperCase()} #${index + 1}] ${message.content}`)
+    return this.normalizeConversationText(lines.join('\n\n'), MAX_CONVERSATION_ASSESSMENT_CHARS)
+  }
+
+  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: memoryRerankerPrompt,
+        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: memoryRerankerPrompt,
+        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,
+  }: {
+    query: string
+    memory: Memory
+    scopeId: string
+    memoryType: MemoryType
+  }): Promise<string> {
+    const limit = env.MEMORY_SEARCH_K
+    const candidateLimit = getCandidateLimit(limit)
+
+    const candidates = await memory.searchCandidates(query, { scopeId, limit: candidateLimit, memoryType })
+
+    aiLogger.debug`Memory search candidates (scopeId: ${scopeId}, candidates: ${candidates.length})`
+
+    if (candidates.length === 0) {
+      return 'No stored memories.'
+    }
+
+    if (candidates.length <= limit) {
+      aiLogger.debug`Skipping reranking (candidates: ${candidates.length} <= limit: ${limit})`
+      return formatMemoryResults(candidates)
+    }
+
+    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)
+
+    try {
+      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
+    } catch (error: unknown) {
+      const normalizedError = error instanceof Error ? error : new Error(String(error))
+      aiLogger.error`Organization memory search failed: ${normalizedError}`
+      throw normalizedError
+    }
+  }
+
+  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 {
+      return ''
+    }
+  }
+
+  async searchOrganizationMemoriesRaw(
+    orgId: string,
+    query: string,
+    options?: { fastMode?: boolean; limit?: number },
+  ): Promise<string> {
+    const orgScopeId = scopeId(ORG_SCOPE_PREFIX, orgId)
+    aiLogger.info`[MEMORY_DEBUG] searchOrganizationMemoriesRaw - orgId: "${orgId}", scopeId: "${orgScopeId}"`
+    const memory = this.getOrgMemory(orgId)
+    const fastMode = options?.fastMode ?? true
+    const limit = options?.limit ?? (fastMode ? Math.min(env.MEMORY_SEARCH_K, 4) : env.MEMORY_SEARCH_K)
+
+    try {
+      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)
+    } catch (error: unknown) {
+      const normalizedError = error instanceof Error ? error : new Error(String(error))
+      aiLogger.error`Organization memory search (raw) failed: ${normalizedError}`
+      throw normalizedError
+    }
+  }
+
+  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)
+
+    try {
+      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
+    } catch (error: unknown) {
+      const normalizedError = error instanceof Error ? error : new Error(String(error))
+      aiLogger.error`Agent memory search failed: ${normalizedError}`
+      throw normalizedError
+    }
+  }
+
+  async searchOrgMemoriesForAgent(orgId: string, agentName: string, query: string): Promise<string> {
+    if (!isRoutableAgentName(agentName)) {
+      return await 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 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 = memory.content.replace(/\s+/g, ' ').trim().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 = false,
+    allowMultiScopeRerank = true,
+  }: {
+    orgId: string
+    agentName?: string
+    query: string
+    fastMode?: boolean
+    allowMultiScopeRerank?: boolean
+  }): Promise<string> {
+    const limit = Math.min(env.MEMORY_SEARCH_K, 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 as string)
+      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,
+  }: {
+    orgId: string
+    content: string
+    memoryType: MemoryType
+    metadata?: Record<string, unknown>
+    importance?: number
+  }): Promise<string> {
+    const orgScopeId = scopeId(ORG_SCOPE_PREFIX, orgId)
+    aiLogger.info`[MEMORY_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,
+        metadata: { orgId, ...metadata },
+      })
+    } catch (error) {
+      if (isUniqueIndexConflict(error, 'memoryHashIdx')) {
+        aiLogger.debug`Organization memory already exists (hash conflict)`
+        return ''
+      }
+      throw error
+    }
+  }
+
+  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}`)
+    }
+
+    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 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,
+    onboardStatus,
+    agentName,
+    historyMessages = [],
+    memoryBlock,
+    attachmentContext,
+    agentNames = [],
+  }: {
+    orgId: string
+    input: string
+    output: string
+    sourceId?: string
+    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.info`[MEMORY_DEBUG] addConversationMemories - orgId: "${orgId}", scopeId: "${orgScopeId}", sourceId: ${sourceId ?? 'none'}`
+
+    const orgMemory = this.getOrgMemory(orgId)
+    let assessedImportance: number | undefined
+    let assessmentMetadata: Record<string, unknown> | undefined
+
+    try {
+      const assessmentInput = this.buildConversationAssessmentInput(messages)
+      if (assessmentInput) {
+        const assessment = await assessMemoryImportance({
+          content: assessmentInput,
+          targetScope: 'global',
+          tag: 'memory-conversation-assessment',
+        })
+        if (assessment.classification === 'transient' && assessment.durability === 'ephemeral') {
+          aiLogger.debug`Skipping transient conversation memory`
+          return
+        }
+        assessedImportance = Math.round(clampMemoryImportance(assessment.importance) * 100) / 100
+        assessmentMetadata = {
+          importanceSource: 'model_assessed',
+          durability: assessment.durability,
+          classification: assessment.classification,
+          rationale: assessment.rationale,
+        }
+      }
+    } catch (error) {
+      aiLogger.warn`Conversation memory assessment failed; continuing with default scoring: ${error}`
+    }
+
+    const scopes: AddOptions[] = [
+      {
+        scopeId: orgScopeId,
+        memoryType: ORG_MEMORY_TYPE,
+        ...(typeof assessedImportance === 'number' ? { importance: assessedImportance } : {}),
+        metadata: { orgId, source: 'chat', ...(sourceId ? { sourceId } : {}), ...assessmentMetadata },
+      },
+    ]
+
+    for (const scopedAgentName of this.resolveAgentScopeNames(agentName, agentNames)) {
+      const agentId = agentScopeId(orgId, scopedAgentName)
+      scopes.push({
+        scopeId: agentId,
+        memoryType: ORG_MEMORY_TYPE,
+        ...(typeof assessedImportance === 'number' ? { importance: assessedImportance } : {}),
+        metadata: {
+          orgId,
+          agentName: scopedAgentName,
+          memoryScope: 'agent',
+          source: 'chat',
+          ...(sourceId ? { sourceId } : {}),
+          ...assessmentMetadata,
+        },
+      })
+    }
+
+    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 (extractedFacts.length === 0) return
+    const preparedUpdates = await orgMemory.prepareFactsToScopes(extractedFacts, scopes)
+    if (preparedUpdates.length === 0) return
+
+    try {
+      await withOrgMemoryLock(orgId, async () => {
+        await orgMemory.applyPreparedScopeUpdates(preparedUpdates)
+      })
+      aiLogger.debug`Conversation memories added to ${scopes.length} scope(s) from ${messages.length} message(s)`
+    } catch (error: unknown) {
+      const normalizedError = error instanceof Error ? error : new Error(String(error))
+      aiLogger.error`Memory write failed: ${normalizedError}`
+      throw normalizedError
+    }
+  }
+}
+
+export const memoryService = new MemoryService()