@lota-sdk/core 0.1.5

package/src/runtime/memory-block.ts

@@ -0,0 +1,264 @@
+import { agentDisplayNames, agentShortDisplayNames, resolveAgentNameAlias } from '../config/agent-defaults'
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+function normalizeMemoryBlockRole(role: string): string {
+  const canonicalRole = resolveAgentNameAlias(role)
+  if (canonicalRole) return canonicalRole
+  return role.trim().toLowerCase()
+}
+
+function getMemoryBlockRoleAliases(role: string): string[] {
+  const normalizedRole = role.trim()
+  if (!normalizedRole) return []
+
+  const canonicalRole = resolveAgentNameAlias(normalizedRole)
+  if (!canonicalRole) return [normalizedRole]
+
+  return [
+    normalizedRole,
+    canonicalRole,
+    agentDisplayNames[canonicalRole],
+    agentShortDisplayNames[canonicalRole],
+  ].filter((value): value is string => typeof value === 'string' && value.trim().length > 0)
+}
+
+function createLabelPrefixRegex(labelRoles: readonly string[]): RegExp | null {
+  if (labelRoles.length === 0) return null
+  const aliases = [...new Set(labelRoles.flatMap((role) => getMemoryBlockRoleAliases(role)))]
+  if (aliases.length === 0) return null
+  return new RegExp(`^(?:${aliases.map((role) => escapeRegex(role)).join('|')})\\s*:\\s*`, 'i')
+}
+
+export interface MemoryBlockEntry {
+  role: string
+  content: string
+  timestamp: string
+}
+
+export interface MemoryBlockRuntime {
+  normalizeMemoryBlockEntry: (entry: string) => string
+  validateMemoryBlockEntry: (entry: string) => { ok: boolean; reason?: string }
+  hasMemoryBlockEntry: (raw: string | null | undefined, role: string, entry: string) => boolean
+  parseMemoryBlock: (raw: string | null | undefined) => MemoryBlockEntry[]
+  serializeMemoryBlock: (entries: MemoryBlockEntry[]) => string
+  formatMemoryBlockForPrompt: (entries: MemoryBlockEntry[]) => string
+  appendToMemoryBlock: (entries: MemoryBlockEntry[], role: string, content: string) => MemoryBlockEntry[]
+}
+
+export interface PersistedMemoryBlockPromptParams {
+  summary?: string | null
+  entries: MemoryBlockEntry[]
+}
+
+export interface CompactMemoryBlockEntriesParams {
+  previousSummary?: string | null
+  entries: MemoryBlockEntry[]
+  triggerEntries: number
+  chunkEntries: number
+  compact: (params: { previousSummary: string; newEntriesText: string }) => Promise<string>
+}
+
+export interface CompactMemoryBlockEntriesResult {
+  compacted: boolean
+  summary: string
+  entries: MemoryBlockEntry[]
+}
+
+export interface PrepareMemoryBlockAppendParams {
+  entry: string
+  agentLabel: string
+  currentBlock?: string
+  normalizeEntry: (entry: string) => string
+  validateEntry: (entry: string) => { ok: boolean; reason?: string }
+  hasEntry: (raw: string | null | undefined, role: string, entry: string) => boolean
+}
+
+export type PrepareMemoryBlockAppendResult =
+  | { skipped: true; reason: string }
+  | { skipped: false; appendedBy: string; normalized: string; formatted: string; optimisticBlock: string }
+
+export function formatPersistedMemoryBlockForPrompt(params: PersistedMemoryBlockPromptParams): string {
+  const sections: string[] = []
+  const summary = params.summary?.trim()
+  if (summary) {
+    sections.push(`summary: ${summary}`)
+  }
+
+  const entriesText =
+    params.entries.length === 0 ? '' : params.entries.map((entry) => `${entry.role}: ${entry.content}`).join('\n\n')
+
+  if (entriesText) {
+    sections.push(entriesText)
+  }
+
+  return sections.join('\n\n')
+}
+
+function toMemoryBlockEntriesSource(entries: Array<{ role: string; content: string }>): string {
+  return entries.map((entry) => `${entry.role}: ${entry.content}`).join('\n')
+}
+
+export async function compactMemoryBlockEntries(
+  params: CompactMemoryBlockEntriesParams,
+): Promise<CompactMemoryBlockEntriesResult> {
+  let summary = typeof params.previousSummary === 'string' ? params.previousSummary.trim() : ''
+  let entries = [...params.entries]
+  let compacted = false
+
+  while (entries.length >= params.triggerEntries) {
+    const chunk = entries.slice(0, params.chunkEntries)
+    const nextSummary = (
+      await params.compact({ previousSummary: summary, newEntriesText: toMemoryBlockEntriesSource(chunk) })
+    ).trim()
+
+    if (!nextSummary) {
+      break
+    }
+
+    summary = nextSummary
+    entries = entries.slice(params.chunkEntries)
+    compacted = true
+  }
+
+  return { compacted, summary, entries }
+}
+
+export function prepareMemoryBlockAppend(params: PrepareMemoryBlockAppendParams): PrepareMemoryBlockAppendResult {
+  const normalized = params.normalizeEntry(params.entry)
+  if (!normalized) {
+    return { skipped: true, reason: 'Empty memory block entry.' }
+  }
+
+  const validation = params.validateEntry(normalized)
+  if (!validation.ok) {
+    return { skipped: true, reason: `Invalid memory block entry: ${validation.reason}.` }
+  }
+
+  const label = normalizeMemoryBlockRole(params.agentLabel)
+  const formatted = `${label}: ${normalized}`
+  const currentBlock = params.currentBlock ?? ''
+  if (params.hasEntry(currentBlock, label, normalized) || (currentBlock && currentBlock.includes(formatted))) {
+    return { skipped: true, reason: 'Duplicate memory block entry.' }
+  }
+
+  const optimisticBlock = currentBlock.trim().length > 0 ? `${currentBlock.trim()}\n\n${formatted}` : formatted
+  return { skipped: false, appendedBy: label, normalized, formatted, optimisticBlock }
+}
+
+export interface CreateMemoryBlockRuntimeOptions {
+  labelRoles?: readonly string[]
+  maxChars?: number
+  now?: () => Date
+}
+
+export function createMemoryBlockRuntime(options: CreateMemoryBlockRuntimeOptions = {}): MemoryBlockRuntime {
+  const labelPrefixRegex = createLabelPrefixRegex(options.labelRoles ?? [])
+  const memoryBlockMaxChars = options.maxChars ?? 400
+  const now = options.now ?? (() => new Date())
+
+  const normalizeMemoryBlockEntry = (entry: string): string => {
+    const normalizedLines = entry
+      .replace(/\r\n/g, '\n')
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .map((line) =>
+        line
+          .replace(labelPrefixRegex ?? /^$/, '')
+          .replace(/^[-*]\s+/, '')
+          .trim(),
+      )
+      .filter(Boolean)
+
+    const candidate = normalizedLines.join(' ').trim()
+    const collapsed = candidate.replace(/\s+/g, ' ').trim()
+    if (!collapsed) return ''
+    return collapsed
+  }
+
+  const parseMemoryBlock = (raw: string | null | undefined): MemoryBlockEntry[] => {
+    if (!raw || !raw.trim()) return []
+    const trimmed = raw.trim()
+    if (!trimmed.startsWith('[')) return []
+    try {
+      const parsed: unknown = JSON.parse(trimmed)
+      if (!Array.isArray(parsed)) return []
+      return parsed as MemoryBlockEntry[]
+    } catch {
+      return []
+    }
+  }
+
+  const hasMemoryBlockEntry = (raw: string | null | undefined, role: string, entry: string): boolean => {
+    const normalizedTarget = normalizeMemoryBlockEntry(entry)
+    if (!normalizedTarget) return false
+    const roleLower = normalizeMemoryBlockRole(role)
+    if (!raw || !raw.trim()) return false
+
+    const parsed = parseMemoryBlock(raw)
+    if (parsed.length > 0) {
+      return parsed.some((item) => {
+        if (normalizeMemoryBlockRole(item.role) !== roleLower) return false
+        return normalizeMemoryBlockEntry(item.content) === normalizedTarget
+      })
+    }
+
+    return raw
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .some((line) => {
+        const match = line.match(/^([a-z][a-z0-9_ -]*)\s*:\s*(.+)$/i)
+        if (!match) return false
+        const rowRole = normalizeMemoryBlockRole(match[1] ?? '')
+        const rowContent = match[2] ?? ''
+        if (rowRole !== roleLower) return false
+        return normalizeMemoryBlockEntry(rowContent) === normalizedTarget
+      })
+  }
+
+  const validateMemoryBlockEntry = (entry: string): { ok: boolean; reason?: string } => {
+    const normalized = normalizeMemoryBlockEntry(entry)
+    if (!normalized) {
+      return { ok: false, reason: 'entry is empty after normalization' }
+    }
+
+    if (normalized.length > memoryBlockMaxChars) {
+      return { ok: false, reason: `entry exceeds ${memoryBlockMaxChars} characters` }
+    }
+
+    return { ok: true }
+  }
+
+  const serializeMemoryBlock = (entries: MemoryBlockEntry[]): string => JSON.stringify(entries)
+
+  const formatMemoryBlockForPrompt = (entries: MemoryBlockEntry[]): string => {
+    if (entries.length === 0) return ''
+    return entries.map((entry) => `${entry.role}: ${entry.content}`).join('\n\n')
+  }
+
+  const appendToMemoryBlock = (entries: MemoryBlockEntry[], role: string, content: string): MemoryBlockEntry[] => {
+    return [...entries, { role, content, timestamp: now().toISOString() }]
+  }
+
+  return {
+    normalizeMemoryBlockEntry,
+    validateMemoryBlockEntry,
+    hasMemoryBlockEntry,
+    parseMemoryBlock,
+    serializeMemoryBlock,
+    formatMemoryBlockForPrompt,
+    appendToMemoryBlock,
+  }
+}
+
+const _defaultRuntime = createMemoryBlockRuntime()
+export const parseMemoryBlock = _defaultRuntime.parseMemoryBlock
+export const serializeMemoryBlock = _defaultRuntime.serializeMemoryBlock
+export const appendToMemoryBlock = _defaultRuntime.appendToMemoryBlock
+export const hasMemoryBlockEntry = _defaultRuntime.hasMemoryBlockEntry
+export const normalizeMemoryBlockEntry = _defaultRuntime.normalizeMemoryBlockEntry
+export const validateMemoryBlockEntry = _defaultRuntime.validateMemoryBlockEntry

package/src/runtime/memory-digest-policy.ts

@@ -0,0 +1,14 @@
+export function shouldEnqueueOnboardingPostChatMemory(params: {
+  onboardingActive: boolean
+  userMessageText: string
+  hasAttachmentContext: boolean
+  agentMessageCount: number
+}): boolean {
+  if (!params.onboardingActive) return false
+  if (params.agentMessageCount <= 0) return false
+  return params.userMessageText.trim().length > 0 || params.hasAttachmentContext
+}
+
+export function shouldEnqueueRegularDigestForWorkstream(params: { onboardingActive: boolean }): boolean {
+  return !params.onboardingActive
+}

package/src/runtime/memory-format.ts

@@ -0,0 +1,8 @@
+interface MemorySearchResultLike {
+  content: string
+}
+
+export function formatResults<T extends MemorySearchResultLike>(results: T[]): string {
+  if (results.length === 0) return 'No stored memories.'
+  return results.map((item) => `- ${item.content}`).join('\n')
+}