@lota-sdk/core 0.4.8 → 0.4.10

package/src/services/memory/memory-conversation.ts

@@ -0,0 +1,95 @@
+import { getAgentRoster } from '../../config/agent-defaults'
+import type { ExtractedFact, Message } from '../../db/memory-types'
+import { sanitizeAgentOutputForMemory } from '../../runtime/llm-content'
+import { compactWhitespace, truncateText } from '../../utils/string'
+
+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 LOW_VALUE_MEMORY_IMPORTANCE_THRESHOLD = 0.45
+
+export const isRoutableAgentName = (value?: string): value is string =>
+  Boolean(value && getAgentRoster().includes(value))
+
+function normalizeConversationText(value: string, maxChars: number): string {
+  const normalized = compactWhitespace(value)
+  if (!normalized) return ''
+  return truncateText(normalized, maxChars)
+}
+
+export function 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))
+}
+
+export function 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 = normalizeConversationText(params.input, MAX_CONVERSATION_MESSAGE_CHARS)
+  const sanitizedOutput = 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 = 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 = normalizeConversationText(params.memoryBlock ?? '', MAX_CONVERSATION_MEMORY_BLOCK_CHARS)
+  if (normalizedMemoryBlock) {
+    messages.push({ role: 'user', content: `Thread memory block:\n${normalizedMemoryBlock}` })
+  }
+
+  const normalizedAttachmentContext = 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 }
+}
+
+export function 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',
+  )
+}

package/src/services/memory/memory-errors.ts

@@ -0,0 +1,27 @@
+import { Effect, Schema } from 'effect'
+
+export class MemoryServiceError extends Schema.TaggedErrorClass<MemoryServiceError>()('MemoryServiceError', {
+  message: Schema.String,
+  cause: Schema.Defect,
+}) {}
+
+export function tryMemoryPromise<A, E, R = never>(
+  message: string,
+  thunk: () => PromiseLike<A> | Effect.Effect<A, E, 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 }))
+    }
+  })
+}

package/src/services/memory/memory-org-memory.ts

@@ -0,0 +1,50 @@
+import type { Context } from 'effect'
+import { Cache, Duration, Effect } from 'effect'
+
+import { aiLogger } from '../../config/logger'
+import { Memory } from '../../db/memory'
+import type { SurrealDBService } from '../../db/service'
+import type { HelperModelRuntime } from '../../runtime/helper-model'
+import { ORG_SCOPE_PREFIX, scopeId } from '../../runtime/memory/memory-scope'
+import type { ResolvedLotaRuntimeConfig } from '../../runtime/runtime-config'
+import { createOrgMemoryAgent, ORG_MEMORY_PROMPT } from '../../system-agents/memory.agent'
+import type { BackgroundWorkService } from '../background-work.service'
+
+const MAX_ORG_MEMORY_CLIENTS = 128
+
+interface OrgMemoryDeps {
+  db: SurrealDBService
+  runtimeConfig: ResolvedLotaRuntimeConfig
+  helperModelRuntime: HelperModelRuntime
+  background: Context.Service.Shape<typeof BackgroundWorkService>
+}
+
+export type OrgMemoryCache = Cache.Cache<string, Memory>
+
+export function makeOrgMemoryCache(deps: OrgMemoryDeps) {
+  return Cache.make({
+    lookup: (cacheKey: string) =>
+      Effect.sync(() => {
+        aiLogger.debug`Memory client created and cached for ${cacheKey}`
+        return new Memory(
+          {
+            db: deps.db,
+            runtimeConfig: deps.runtimeConfig,
+            helperModelRuntime: deps.helperModelRuntime,
+            background: deps.background,
+          },
+          { createAgent: createOrgMemoryAgent },
+          { customPrompt: ORG_MEMORY_PROMPT },
+        )
+      }),
+    capacity: MAX_ORG_MEMORY_CLIENTS,
+    timeToLive: Duration.infinity,
+  })
+}
+
+export function getOrgMemory(cache: OrgMemoryCache, orgId: string) {
+  return Effect.gen(function* () {
+    const key = yield* scopeId(ORG_SCOPE_PREFIX, orgId)
+    return yield* Cache.get(cache, key)
+  })
+}

package/src/services/memory/memory-preseeded.ts

@@ -0,0 +1,86 @@
+import { Effect } from 'effect'
+
+import type { Memory } from '../../db/memory'
+import type { MemoryRecord } from '../../db/memory-types'
+import type { MemoryScopeError } from '../../runtime/memory/memory-scope'
+import { ORG_SCOPE_PREFIX, agentScopeId, scopeId } from '../../runtime/memory/memory-scope'
+import { compactWhitespace, truncateText } from '../../utils/string'
+import type { OrgMemoryCache } from './memory-org-memory'
+import { getOrgMemory } from './memory-org-memory'
+
+const PRESEEDED_MEMORY_LIMIT = 5
+const PRESEEDED_MEMORY_MAX_CHARS = 300
+const PRESEEDED_MIN_IMPORTANCE = 0.7
+const PRESEEDED_MEMORY_DURABILITY: MemoryRecord['durability'] = 'core'
+type PreSeededMemoryError = Effect.Error<ReturnType<Memory['listTopMemories']>> | MemoryScopeError
+
+function normalizePreSeededMemoryText(value: string): string {
+  return truncateText(compactWhitespace(value), PRESEEDED_MEMORY_MAX_CHARS)
+}
+
+function formatPreSeededMemoriesSection(memories: MemoryRecord[]): string | undefined {
+  const lines = memories
+    .map((memory) => 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')
+}
+
+export function getTopMemoriesSection(params: {
+  orgMemoryCache: OrgMemoryCache
+  orgId: string
+  agentName?: string
+  limit?: number
+}): Effect.Effect<string | undefined, PreSeededMemoryError, never> {
+  return Effect.gen(function* () {
+    const orgMemory = yield* getOrgMemory(params.orgMemoryCache, params.orgId)
+    const orgScopeId = yield* 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 agentScopedId =
+      params.agentName && params.agentName.trim() ? yield* agentScopeId(params.orgId, params.agentName) : undefined
+
+    const [orgTopMemories, agentTopMemories] = yield* Effect.all([
+      orgMemory.listTopMemories({
+        scopeId: orgScopeId,
+        limit,
+        memoryType: 'fact',
+        durability: PRESEEDED_MEMORY_DURABILITY,
+        minImportance: PRESEEDED_MIN_IMPORTANCE,
+      }),
+      agentScopedId
+        ? orgMemory.listTopMemories({
+            scopeId: agentScopedId,
+            limit,
+            memoryType: 'fact',
+            durability: PRESEEDED_MEMORY_DURABILITY,
+            minImportance: PRESEEDED_MIN_IMPORTANCE,
+          })
+        : Effect.succeed([] as MemoryRecord[]),
+    ])
+
+    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 formatPreSeededMemoriesSection(deduped)
+  })
+}

package/src/services/memory/memory-rerank.ts

@@ -0,0 +1,297 @@
+import { Effect, Schema } from 'effect'
+import { z } from 'zod'
+
+import { aiLogger } from '../../config/logger'
+import type { MemorySearchResult } from '../../db/memory-types'
+import type { HelperModelRuntime } from '../../runtime/helper-model'
+import type { MemoryRerankerStrategy, ResolvedLotaRuntimeConfig } from '../../runtime/runtime-config'
+import { createMemoryRerankerAgent, MEMORY_RERANKER_PROMPT } from '../../system-agents/memory-reranker.agent'
+import { compactWhitespace, truncateText } from '../../utils/string'
+import type { makeRerankService } from './rerank.service'
+
+const RERANK_CANDIDATE_MAX_CHARS = 500
+const RERANK_SECTION_TITLE = 'Most relevant memories'
+
+const RERANK_PROMPT_CANDIDATE_SCHEMA = Schema.Struct({ id: Schema.String, text: Schema.String, score: Schema.Number })
+
+const RERANK_PROMPT_MULTI_SCOPE_CANDIDATE_SCHEMA = Schema.Struct({
+  id: Schema.String,
+  text: Schema.String,
+  score: Schema.Number,
+  scope: Schema.String,
+})
+
+const RERANK_PROMPT_SCHEMA = Schema.Struct({
+  query: Schema.String,
+  maxItems: Schema.Number,
+  candidates: Schema.Array(RERANK_PROMPT_CANDIDATE_SCHEMA),
+})
+
+const RERANK_MULTI_SCOPE_PROMPT_SCHEMA = Schema.Struct({
+  query: Schema.String,
+  maxItems: Schema.Number,
+  candidates: Schema.Array(RERANK_PROMPT_MULTI_SCOPE_CANDIDATE_SCHEMA),
+})
+
+const stringifyRerankPrompt = Schema.encodeSync(Schema.fromJsonString(RERANK_PROMPT_SCHEMA))
+const stringifyRerankMultiScopePrompt = Schema.encodeSync(Schema.fromJsonString(RERANK_MULTI_SCOPE_PROMPT_SCHEMA))
+
+class MemoryRerankError extends Schema.TaggedErrorClass<MemoryRerankError>()('MemoryRerankError', {
+  scope: Schema.Literals(['single', 'multi-scope']),
+  message: Schema.String,
+  cause: Schema.optional(Schema.Unknown),
+}) {}
+
+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>
+
+function truncateCandidateText(value: string): string {
+  return truncateText(compactWhitespace(value), RERANK_CANDIDATE_MAX_CHARS)
+}
+
+function readNumericMetadata(metadata: Record<string, unknown>, key: string): number {
+  const value = metadata[key]
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  return 0
+}
+
+function buildRerankerCandidateText(candidate: MemorySearchResult): string {
+  const metadata = candidate.metadata
+  const relationCount = readNumericMetadata(metadata, 'relationCount')
+  const supportCount = readNumericMetadata(metadata, 'supportCount')
+  const contradictCount = 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')}`
+}
+
+function getRerankerStrategy(runtimeConfig: ResolvedLotaRuntimeConfig): MemoryRerankerStrategy {
+  return runtimeConfig.memory.rerankerStrategy
+}
+
+function buildRerankOutput(ids: string[], title = RERANK_SECTION_TITLE): MemoryRerankOutput {
+  return { sections: [{ title, items: ids.map((id) => ({ id, relevance: '' })) }] }
+}
+
+function toRerankError(scope: 'single' | 'multi-scope', message: string, cause?: unknown): MemoryRerankError {
+  return new MemoryRerankError({ scope, message, cause })
+}
+
+function logRerankError(scope: 'single' | 'multi-scope', error: unknown): void {
+  if (scope === 'multi-scope') {
+    aiLogger.error`Multi-scope memory reranker failed: ${error}`
+    return
+  }
+
+  aiLogger.error`Memory reranker failed: ${error}`
+}
+
+function rerankCandidatesWithHelperEffect(
+  helperModelRuntime: HelperModelRuntime,
+  query: string,
+  candidates: MemorySearchResult[],
+  maxItems: number,
+): Effect.Effect<MemoryRerankOutput, MemoryRerankError> {
+  return Effect.tryPromise({
+    try: () =>
+      helperModelRuntime.generateHelperStructured({
+        tag: 'memory-reranker',
+        createAgent: createMemoryRerankerAgent,
+        defaultSystemPrompt: MEMORY_RERANKER_PROMPT,
+        messages: [
+          {
+            role: 'user',
+            content: stringifyRerankPrompt({
+              query,
+              maxItems,
+              candidates: candidates.map((candidate) => ({
+                id: candidate.id,
+                text: truncateCandidateText(buildRerankerCandidateText(candidate)),
+                score: candidate.score,
+              })),
+            }),
+          },
+        ],
+        schema: MemoryRerankOutputSchema,
+      }),
+    catch: (cause) => {
+      logRerankError('single', cause)
+      return toRerankError('single', 'Memory reranker failed.', cause)
+    },
+  })
+}
+
+function rerankCandidatesWithRerankServiceEffect(
+  query: string,
+  candidates: MemorySearchResult[],
+  maxItems: number,
+  reranker: ReturnType<typeof makeRerankService>,
+): Effect.Effect<MemoryRerankOutput, MemoryRerankError> {
+  return reranker
+    .rerankDocuments({
+      query,
+      topN: maxItems,
+      documents: candidates.map((candidate) => ({
+        id: candidate.id,
+        text: truncateCandidateText(buildRerankerCandidateText(candidate)),
+      })),
+    })
+    .pipe(
+      Effect.mapError((cause) => {
+        logRerankError('single', cause)
+        return toRerankError('single', 'Memory reranker failed.', cause)
+      }),
+      Effect.map((reranked) => buildRerankOutput(reranked.results.map((item: { id: string }) => item.id))),
+    )
+}
+
+export function rerankCandidates(
+  runtimeConfig: ResolvedLotaRuntimeConfig,
+  helperModelRuntime: HelperModelRuntime,
+  query: string,
+  candidates: MemorySearchResult[],
+  maxItems: number,
+  reranker?: ReturnType<typeof makeRerankService>,
+): Effect.Effect<MemoryRerankOutput | null> {
+  if (candidates.length === 0) return Effect.succeed(null)
+
+  return Effect.gen(function* () {
+    if (getRerankerStrategy(runtimeConfig) === 'rerank' && reranker) {
+      return yield* rerankCandidatesWithRerankServiceEffect(query, candidates, maxItems, reranker)
+    }
+
+    return yield* rerankCandidatesWithHelperEffect(helperModelRuntime, query, candidates, maxItems)
+  }).pipe(
+    Effect.catchCause((cause) =>
+      Effect.sync(() => {
+        logRerankError('single', cause)
+        return null
+      }),
+    ),
+  )
+}
+
+function rerankCandidatesMultiScopeWithHelperEffect(
+  helperModelRuntime: HelperModelRuntime,
+  query: string,
+  flattenedCandidates: Array<MemorySearchResult & { scopeTag: string }>,
+  maxItems: number,
+): Effect.Effect<MemoryRerankOutput, MemoryRerankError> {
+  return Effect.tryPromise({
+    try: () =>
+      helperModelRuntime.generateHelperStructured({
+        tag: 'memory-reranker-multi-scope',
+        createAgent: createMemoryRerankerAgent,
+        defaultSystemPrompt: MEMORY_RERANKER_PROMPT,
+        messages: [
+          {
+            role: 'user',
+            content: stringifyRerankMultiScopePrompt({
+              query,
+              maxItems,
+              candidates: flattenedCandidates.map((candidate) => ({
+                id: candidate.id,
+                text: truncateCandidateText(buildRerankerCandidateText(candidate)),
+                score: candidate.score,
+                scope: candidate.scopeTag,
+              })),
+            }),
+          },
+        ],
+        schema: MemoryRerankOutputSchema,
+      }),
+    catch: (cause) => {
+      logRerankError('multi-scope', cause)
+      return toRerankError('multi-scope', 'Multi-scope memory reranker failed.', cause)
+    },
+  })
+}
+
+function rerankCandidatesMultiScopeWithRerankServiceEffect(
+  query: string,
+  flattenedCandidates: Array<MemorySearchResult & { scopeTag: string }>,
+  maxItems: number,
+  reranker: ReturnType<typeof makeRerankService>,
+): Effect.Effect<MemoryRerankOutput, MemoryRerankError> {
+  return reranker
+    .rerankDocuments({
+      query,
+      topN: maxItems,
+      documents: flattenedCandidates.map((candidate) => ({
+        id: candidate.id,
+        text: truncateCandidateText(`${buildRerankerCandidateText(candidate)}\n\nScope: ${candidate.scopeTag}`),
+      })),
+    })
+    .pipe(
+      Effect.mapError((cause) => {
+        logRerankError('multi-scope', cause)
+        return toRerankError('multi-scope', 'Multi-scope memory reranker failed.', cause)
+      }),
+      Effect.map((reranked) =>
+        buildRerankOutput(
+          reranked.results.map((item: { id: string }) => item.id),
+          'Top matches across memory scopes',
+        ),
+      ),
+    )
+}
+
+export function rerankCandidatesMultiScope(
+  runtimeConfig: ResolvedLotaRuntimeConfig,
+  helperModelRuntime: HelperModelRuntime,
+  query: string,
+  scopedCandidates: Array<{ scopeTag: string; candidates: MemorySearchResult[] }>,
+  maxItems: number,
+  reranker?: ReturnType<typeof makeRerankService>,
+): Effect.Effect<MemoryRerankOutput | null> {
+  const flattened = scopedCandidates.flatMap(({ scopeTag, candidates }) =>
+    candidates.map((candidate) => ({ ...candidate, scopeTag })),
+  )
+  if (flattened.length === 0 || flattened.length <= maxItems) return Effect.succeed(null)
+
+  return Effect.gen(function* () {
+    if (getRerankerStrategy(runtimeConfig) === 'rerank' && reranker) {
+      return yield* rerankCandidatesMultiScopeWithRerankServiceEffect(query, flattened, maxItems, reranker)
+    }
+
+    return yield* rerankCandidatesMultiScopeWithHelperEffect(helperModelRuntime, query, flattened, maxItems)
+  }).pipe(
+    Effect.catchCause((cause) =>
+      Effect.sync(() => {
+        logRerankError('multi-scope', cause)
+        return null
+      }),
+    ),
+  )
+}

package/src/services/{memory-utils.ts → memory/memory-utils.ts}

@@ -1,8 +1,9 @@
-import { MEMORY } from '../config/constants'
-import { VECTOR_SEARCH_OVERFETCH_MULTIPLIER } from '../config/search'
-import type { MemorySearchResult } from '../db/memory-types'
-import { compactWhitespace, truncateText } from '../utils/string'
-import type { MemoryRerankOutput } from './memory.service'
+import { VECTOR_SEARCH_OVERFETCH_MULTIPLIER } from '@lota-sdk/shared'
+
+import { MEMORY } from '../../config/constants'
+import type { MemorySearchResult } from '../../db/memory-types'
+import { compactWhitespace, truncateText } from '../../utils/string'
+import type { MemoryRerankOutput } from './memory-rerank'
 
 export function getCandidateLimit(limit: number): number {
   return Math.max(limit * VECTOR_SEARCH_OVERFETCH_MULTIPLIER, MEMORY.DEFAULT_CANDIDATE_LIMIT)