@lota-sdk/core 0.1.5

package/src/runtime/memory-pipeline.ts

@@ -0,0 +1,570 @@
+export { agentScopeId, ORG_SCOPE_PREFIX, scopeId } from './memory-scope'
+
+interface MemoryFactInput {
+  content: string
+  confidence: number
+  durability?: string
+  type?: string
+}
+
+interface PostProcessMemoryFactsOptions {
+  maxFacts?: number
+  minChars?: number
+  maxChars?: number
+}
+
+interface MemoryImportanceParams {
+  text: string
+  memoryType: string
+  explicitImportance?: number
+  confidenceByKey: Map<string, number>
+  durabilityByKey: Map<string, string>
+  categoryByKey: Map<string, string | undefined>
+  defaultImportance?: number
+}
+
+interface MemoryFactMaps {
+  confidenceByKey: Map<string, number>
+  durabilityByKey: Map<string, string>
+  categoryByKey: Map<string, string | undefined>
+}
+
+interface MemoryUpdateRelationLike<TRelation extends string = string> {
+  memoryId: string
+  relation: TRelation
+}
+
+interface MemoryUpdateItemLike<TRelation extends string = string> {
+  id: string
+  text: string
+  event: 'ADD' | 'UPDATE' | 'DELETE' | 'NONE'
+  oldMemory?: string
+  relatesTo?: MemoryUpdateRelationLike<TRelation>[]
+}
+
+interface MemoryUpdateOutputLike<TRelation extends string = string> {
+  memory: MemoryUpdateItemLike<TRelation>[]
+}
+
+interface MemoryDeltaItemLike {
+  fact: string
+  classification: 'new' | 'supersedes' | 'contradicts' | 'enriches' | 'duplicate'
+  targetMemoryIds?: string[]
+  invalidateTargetIds?: string[]
+  relations?: MemoryDeltaRelationLike[]
+  rationale?: string
+}
+
+interface MemoryDeltaOutputLike {
+  deltas: MemoryDeltaItemLike[]
+}
+
+interface MemoryDeltaRelationLike<TRelation extends string = string> {
+  relation: TRelation
+  targetMemoryId?: string
+  targetFactIndex?: number
+}
+
+interface MemoryActionAdd {
+  type: 'add'
+  refId: string
+  text: string
+  normalizedText: string
+  importance: number
+  durability: string
+  category: string
+}
+
+interface MemoryActionUpdate {
+  type: 'update'
+  refId: string
+  text: string
+  normalizedText: string
+  importance: number
+  durability?: string
+  category?: string
+}
+
+interface MemoryActionDelete {
+  type: 'delete'
+  refId: string
+}
+
+interface MemoryActionRelation<TRelation extends string = string> {
+  fromRefId: string
+  toRefId: string
+  relation: TRelation
+}
+
+interface MemoryActionPlan<TRelation extends string = string> {
+  actions: Array<MemoryActionAdd | MemoryActionUpdate | MemoryActionDelete>
+  relations: MemoryActionRelation<TRelation>[]
+}
+
+function clampImportance(value: number): number {
+  if (!Number.isFinite(value)) return 0
+  return Math.max(0, Math.min(1, value))
+}
+
+function normalizeMemoryKey(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^\w\s$%]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+function scoreFact<T extends MemoryFactInput>(fact: T): number {
+  const confidence = clampImportance(typeof fact.confidence === 'number' ? fact.confidence : 0)
+  const durability = fact.durability ?? 'standard'
+  const type = fact.type ?? 'fact'
+
+  const durabilityWeight = durability === 'core' ? 0.35 : durability === 'standard' ? 0.2 : 0.05
+  const typeWeight = type === 'decision' ? 0.25 : type === 'fact' ? 0.18 : 0.1
+  const lengthWeight = Math.min(fact.content.length, 120) / 120 / 10
+
+  return confidence + durabilityWeight + typeWeight + lengthWeight
+}
+
+function resolveBestFact<T extends MemoryFactInput>(current: T, candidate: T): T {
+  const currentScore = scoreFact(current)
+  const candidateScore = scoreFact(candidate)
+  if (candidateScore > currentScore) return candidate
+  if (candidateScore < currentScore) return current
+  return candidate.content.length > current.content.length ? candidate : current
+}
+
+function normalizeFactForDedupe(text: string): string {
+  return normalizeMemoryKey(text)
+    .replace(/\b(the|a|an|is|are|was|were|to|of|for|and)\b/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+function resolveAdaptiveFactCap(rawFactCount: number): number {
+  const baseCap = 8
+  const maxCap = 18
+  if (!Number.isFinite(rawFactCount) || rawFactCount <= baseCap) return baseCap
+
+  const scaledCap = Math.round(rawFactCount * 0.7)
+  return Math.max(baseCap, Math.min(maxCap, scaledCap))
+}
+
+export function postProcessMemoryFacts<T extends MemoryFactInput>(
+  rawFacts: T[],
+  options: PostProcessMemoryFactsOptions = {},
+): T[] {
+  const maxFacts = options.maxFacts ?? resolveAdaptiveFactCap(rawFacts.length)
+  const minChars = options.minChars ?? 4
+  const maxChars = options.maxChars ?? 420
+  if (!Array.isArray(rawFacts) || rawFacts.length === 0) return []
+
+  const deduped = new Map<string, T>()
+
+  for (const fact of rawFacts) {
+    const content = typeof fact.content === 'string' ? fact.content.replace(/\s+/g, ' ').trim() : ''
+    if (!content || content.length < minChars || content.length > maxChars) continue
+    const normalizedFact = { ...fact, content }
+    const key = normalizeFactForDedupe(content)
+    if (!key) continue
+
+    const existing = deduped.get(key)
+    if (!existing) {
+      deduped.set(key, normalizedFact)
+      continue
+    }
+
+    deduped.set(key, resolveBestFact(existing, normalizedFact))
+  }
+
+  return [...deduped.values()].sort((left, right) => scoreFact(right) - scoreFact(left)).slice(0, maxFacts)
+}
+
+export function buildMemoryFactMaps<T extends MemoryFactInput>(facts: T[]): MemoryFactMaps {
+  const confidenceByKey = new Map<string, number>()
+  const durabilityByKey = new Map<string, string>()
+  const categoryByKey = new Map<string, string | undefined>()
+
+  for (const fact of facts) {
+    const key = normalizeMemoryKey(fact.content)
+    confidenceByKey.set(key, fact.confidence)
+    durabilityByKey.set(key, fact.durability ?? 'standard')
+    categoryByKey.set(key, fact.type)
+  }
+
+  return { confidenceByKey, durabilityByKey, categoryByKey }
+}
+
+function toUniqueOrderedIds(value: string[] | undefined, validIds: Set<string>): string[] {
+  if (!value || value.length === 0) return []
+  const seen = new Set<string>()
+  const ordered: string[] = []
+  for (const rawId of value) {
+    const id = rawId.trim()
+    if (!id || seen.has(id) || !validIds.has(id)) continue
+    seen.add(id)
+    ordered.push(id)
+  }
+  return ordered
+}
+
+export function compileMemoryUpdatesFromDelta(params: {
+  existingMemories: Array<{ id: string; text: string }>
+  newFacts: string[]
+  delta: MemoryDeltaOutputLike
+}): MemoryUpdateOutputLike {
+  const existingById = new Map(params.existingMemories.map((memory) => [memory.id, memory.text]))
+  const validExistingIds = new Set(existingById.keys())
+  const updates: MemoryUpdateItemLike[] = []
+  const deleteSet = new Set<string>()
+  let nextAddIndex = 0
+
+  const findDeltaForFact = (fact: string, index: number): MemoryDeltaItemLike | null => {
+    const direct = params.delta.deltas.at(index)
+    if (direct?.fact === fact) return direct
+    return params.delta.deltas.find((delta) => delta.fact === fact) ?? null
+  }
+
+  const nextAddId = () => {
+    const next = `new_${nextAddIndex}`
+    nextAddIndex += 1
+    return next
+  }
+
+  const prepared = params.newFacts.map((rawFact, index) => {
+    const fact = rawFact.trim()
+    const delta = fact ? findDeltaForFact(fact, index) : null
+    const classification = delta?.classification ?? 'new'
+    const targetMemoryIds = toUniqueOrderedIds(delta?.targetMemoryIds, validExistingIds)
+    const invalidateTargetIds = toUniqueOrderedIds(delta?.invalidateTargetIds, validExistingIds).filter((id) =>
+      targetMemoryIds.includes(id),
+    )
+
+    return { index, fact, delta, classification, targetMemoryIds, invalidateTargetIds }
+  })
+
+  const addIdByFactIndex = new Map<number, string>()
+  for (const item of prepared) {
+    if (!item.fact) continue
+
+    const shouldAdd =
+      item.classification === 'new' ||
+      item.classification === 'supersedes' ||
+      item.classification === 'contradicts' ||
+      (item.classification === 'enriches' && item.targetMemoryIds.length === 0)
+
+    if (!shouldAdd) continue
+    addIdByFactIndex.set(item.index, nextAddId())
+  }
+
+  const buildRelations = (
+    item: (typeof prepared)[number],
+    fallbackClassification: 'supersedes' | 'contradicts' | 'new',
+  ): MemoryUpdateRelationLike[] => {
+    const relations: MemoryUpdateRelationLike[] = []
+    const relationKeys = new Set<string>()
+    const pushRelation = (memoryId: string, relation: string): void => {
+      const id = memoryId.trim()
+      if (!id || !relation) return
+      const key = `${id}|${relation}`
+      if (relationKeys.has(key)) return
+      relationKeys.add(key)
+      relations.push({ memoryId: id, relation })
+    }
+
+    let explicitRelationCount = 0
+    for (const relation of item.delta?.relations ?? []) {
+      if (typeof relation.relation !== 'string') continue
+
+      if (typeof relation.targetMemoryId === 'string') {
+        const targetMemoryId = relation.targetMemoryId.trim()
+        if (targetMemoryId && validExistingIds.has(targetMemoryId)) {
+          pushRelation(targetMemoryId, relation.relation)
+          explicitRelationCount += 1
+        }
+      }
+
+      if (typeof relation.targetFactIndex === 'number' && Number.isInteger(relation.targetFactIndex)) {
+        if (relation.targetFactIndex === item.index) continue
+        const targetFactIndex = relation.targetFactIndex
+        const targetFactAddId = addIdByFactIndex.get(targetFactIndex)
+        if (targetFactAddId) {
+          pushRelation(targetFactAddId, relation.relation)
+          explicitRelationCount += 1
+        }
+      }
+    }
+
+    if (fallbackClassification === 'supersedes' || fallbackClassification === 'contradicts') {
+      for (const targetMemoryId of item.targetMemoryIds) {
+        pushRelation(targetMemoryId, fallbackClassification)
+      }
+    } else if (item.targetMemoryIds.length > 0 && explicitRelationCount === 0) {
+      for (const targetMemoryId of item.targetMemoryIds) {
+        pushRelation(targetMemoryId, 'supports')
+      }
+    }
+
+    return relations
+  }
+
+  for (const item of prepared) {
+    if (!item.fact) continue
+
+    for (const invalidateId of item.invalidateTargetIds) {
+      deleteSet.add(invalidateId)
+    }
+
+    if (item.classification === 'duplicate') {
+      const targetId = item.targetMemoryIds[0]
+      if (targetId) {
+        updates.push({ id: targetId, text: existingById.get(targetId) ?? item.fact, event: 'NONE' })
+      } else {
+        updates.push({ id: `noop_${item.index}`, text: item.fact, event: 'NONE' })
+      }
+      continue
+    }
+
+    if (item.classification === 'enriches') {
+      const targetId = item.targetMemoryIds[0]
+      if (targetId) {
+        const relations = buildRelations(item, 'new').filter((relation) => relation.memoryId !== targetId)
+        updates.push({
+          id: targetId,
+          text: item.fact,
+          event: 'UPDATE',
+          oldMemory: existingById.get(targetId),
+          ...(relations.length > 0 ? { relatesTo: relations } : {}),
+        })
+        continue
+      }
+
+      const addId = addIdByFactIndex.get(item.index) ?? nextAddId()
+      const relations = buildRelations(item, 'new')
+      updates.push({
+        id: addId,
+        text: item.fact,
+        event: 'ADD',
+        ...(relations.length > 0 ? { relatesTo: relations } : {}),
+      })
+      continue
+    }
+
+    if (item.classification === 'supersedes' || item.classification === 'contradicts') {
+      const addId = addIdByFactIndex.get(item.index) ?? nextAddId()
+      const relations = buildRelations(item, item.classification)
+      updates.push({
+        id: addId,
+        text: item.fact,
+        event: 'ADD',
+        ...(relations.length > 0 ? { relatesTo: relations } : {}),
+      })
+      continue
+    }
+
+    const addId = addIdByFactIndex.get(item.index) ?? nextAddId()
+    const relations = buildRelations(item, 'new')
+    updates.push({
+      id: addId,
+      text: item.fact,
+      event: 'ADD',
+      ...(relations.length > 0 ? { relatesTo: relations } : {}),
+    })
+  }
+
+  const preservedRelationTargetIds = new Set<string>()
+  for (const update of updates) {
+    if (!update.relatesTo?.length) continue
+    for (const relation of update.relatesTo) {
+      preservedRelationTargetIds.add(relation.memoryId)
+    }
+  }
+
+  for (const deleteId of deleteSet) {
+    if (preservedRelationTargetIds.has(deleteId)) continue
+    updates.push({ id: deleteId, text: existingById.get(deleteId) ?? '', event: 'DELETE' })
+  }
+
+  return { memory: updates }
+}
+
+function resolveMemoryImportance(params: MemoryImportanceParams): number {
+  if (typeof params.explicitImportance === 'number') {
+    return clampImportance(params.explicitImportance)
+  }
+
+  if (params.memoryType === 'user_request') {
+    return 0.9
+  }
+
+  const normalizedText = normalizeMemoryKey(params.text)
+  const aiConfidence = params.confidenceByKey.get(normalizedText)
+  if (aiConfidence !== undefined) {
+    const durability = params.durabilityByKey.get(normalizedText) ?? 'standard'
+    const category = params.categoryByKey.get(normalizedText) ?? 'fact'
+
+    const durabilityCap = durability === 'core' ? 0.95 : durability === 'standard' ? 0.85 : 0.7
+    const categoryCap = category === 'decision' ? 0.95 : category === 'fact' ? 0.85 : 0.7
+    return clampImportance(Math.min(aiConfidence, durabilityCap, categoryCap))
+  }
+
+  return params.defaultImportance ?? 0.65
+}
+
+export function createMemoryActionPlan<TRelation extends string = string>(params: {
+  updates: MemoryUpdateOutputLike<TRelation>
+  memoryType: string
+  explicitImportance?: number
+  confidenceByKey: Map<string, number>
+  durabilityByKey: Map<string, string>
+  categoryByKey: Map<string, string | undefined>
+  existingMemories?: Array<{ id: string; text: string }>
+}): MemoryActionPlan<TRelation> {
+  const actions: Array<MemoryActionAdd | MemoryActionUpdate | MemoryActionDelete> = []
+  const relations: MemoryActionRelation<TRelation>[] = []
+
+  const actionKeys = new Set<string>()
+  const relationKeys = new Set<string>()
+  const existingIds = new Set((params.existingMemories ?? []).map((memory) => memory.id))
+  const usedRefIds = new Set<string>()
+  const addRefByIndex = new Map<number, string>()
+  const addIdAliasMap = new Map<string, string>()
+
+  for (const item of params.updates.memory) {
+    if (typeof item.id === 'string' && item.id.trim().length > 0) {
+      usedRefIds.add(item.id.trim())
+    }
+  }
+
+  let generatedCounter = 0
+  const nextGeneratedAddRefId = (): string => {
+    while (usedRefIds.has(`new_generated_${generatedCounter}`)) {
+      generatedCounter += 1
+    }
+    const refId = `new_generated_${generatedCounter}`
+    usedRefIds.add(refId)
+    generatedCounter += 1
+    return refId
+  }
+
+  const pushAction = (action: MemoryActionAdd | MemoryActionUpdate | MemoryActionDelete): void => {
+    const key = `${action.type}|${action.refId}`
+    if (actionKeys.has(key)) return
+    actionKeys.add(key)
+    actions.push(action)
+  }
+
+  const pushRelation = (relation: MemoryActionRelation<TRelation>): void => {
+    const fromRefId = relation.fromRefId.trim()
+    const toRefId = relation.toRefId.trim()
+    if (!fromRefId || !toRefId || fromRefId === toRefId) return
+
+    const key = `${fromRefId}|${toRefId}|${String(relation.relation)}`
+    if (relationKeys.has(key)) return
+    relationKeys.add(key)
+    relations.push({ ...relation, fromRefId, toRefId })
+  }
+
+  for (const [index, item] of params.updates.memory.entries()) {
+    const text = typeof item.text === 'string' ? item.text.replace(/\s+/g, ' ').trim() : ''
+    const itemId = typeof item.id === 'string' ? item.id.trim() : ''
+
+    switch (item.event) {
+      case 'ADD': {
+        if (!text) break
+        const refId = !itemId || existingIds.has(itemId) ? nextGeneratedAddRefId() : itemId
+        addRefByIndex.set(index, refId)
+        if (itemId && itemId !== refId) {
+          addIdAliasMap.set(itemId, refId)
+        }
+
+        const normalizedText = normalizeMemoryKey(text)
+        pushAction({
+          type: 'add',
+          refId,
+          text,
+          normalizedText,
+          importance: resolveMemoryImportance({
+            text,
+            memoryType: params.memoryType,
+            explicitImportance: params.explicitImportance,
+            confidenceByKey: params.confidenceByKey,
+            durabilityByKey: params.durabilityByKey,
+            categoryByKey: params.categoryByKey,
+          }),
+          durability: params.durabilityByKey.get(normalizedText) ?? 'standard',
+          category: params.categoryByKey.get(normalizedText) ?? 'fact',
+        })
+        break
+      }
+
+      case 'UPDATE': {
+        if (!itemId || itemId.startsWith('new_') || !text) break
+        const normalizedText = normalizeMemoryKey(text)
+        pushAction({
+          type: 'update',
+          refId: itemId,
+          text,
+          normalizedText,
+          importance: resolveMemoryImportance({
+            text,
+            memoryType: params.memoryType,
+            explicitImportance: params.explicitImportance,
+            confidenceByKey: params.confidenceByKey,
+            durabilityByKey: params.durabilityByKey,
+            categoryByKey: params.categoryByKey,
+          }),
+          durability: params.durabilityByKey.get(normalizedText),
+          category: params.categoryByKey.get(normalizedText),
+        })
+        break
+      }
+
+      case 'DELETE': {
+        if (!itemId || itemId.startsWith('new_')) break
+        pushAction({ type: 'delete', refId: itemId })
+        break
+      }
+
+      case 'NONE':
+        break
+    }
+  }
+
+  for (const [index, item] of params.updates.memory.entries()) {
+    if (item.event === 'DELETE' || item.event === 'NONE' || !item.relatesTo?.length) continue
+
+    const fromRefId =
+      item.event === 'ADD' ? addRefByIndex.get(index) : typeof item.id === 'string' ? item.id.trim() : ''
+    if (!fromRefId) continue
+
+    for (const relation of item.relatesTo) {
+      if (typeof relation.memoryId !== 'string' || !relation.memoryId.trim()) continue
+      const rawToRefId = relation.memoryId.trim()
+      const toRefId = addIdAliasMap.get(rawToRefId) ?? rawToRefId
+      pushRelation({ fromRefId, toRefId, relation: relation.relation })
+    }
+  }
+
+  const knownIds = new Set<string>((params.existingMemories ?? []).map((memory) => memory.id))
+  for (const action of actions) {
+    knownIds.add(action.refId)
+  }
+
+  const filteredRelations = relations.filter((relation) => {
+    return knownIds.has(relation.fromRefId) && knownIds.has(relation.toRefId)
+  })
+
+  if (filteredRelations.length !== relations.length) {
+    relationKeys.clear()
+    relations.length = 0
+    for (const relation of filteredRelations) {
+      const key = `${relation.fromRefId}|${relation.toRefId}|${String(relation.relation)}`
+      if (relationKeys.has(key)) continue
+      relationKeys.add(key)
+      relations.push(relation)
+    }
+  }
+
+  return { actions, relations }
+}

package/src/runtime/memory-prompts-fact.ts

@@ -0,0 +1,47 @@
+export function getFactRetrievalMessages(
+  parsedMessages: string,
+  customPrompt?: string,
+  maxFacts = 8,
+): [string, string] {
+  const baseInstructions = customPrompt ? `\n\nAdditional instructions: ${customPrompt}` : ''
+
+  const systemPrompt = `You extract durable memories from conversations.
+
+Goal:
+- Return a short list of stable, long-term facts, preferences, or decisions that were explicitly stated.
+
+Classification:
+- "fact": Objective information (tools, architecture, team structure, processes).
+- "preference": Subjective preference or style choice.
+- "decision": Explicit decision, requirement, or policy.
+
+Confidence scoring:
+- 1.0: Explicit, confirmed statements ("We use TypeScript", "I prefer dark mode", "We decided to migrate").
+- 0.8: Strong implications or clearly implied facts.
+- 0.6-0.7: Reasonable inferences with some ambiguity.
+- Below 0.6: Do NOT extract. Skip entirely.
+
+Durability classification:
+- "core": Business decisions, technical architecture choices, confirmed requirements, strategic direction. These are foundational and rarely change. Examples: "We use SurrealDB", "We decided to adopt microservices", "Revenue target is $1M ARR".
+- "standard": General facts, moderate inferences, process details. These may evolve over time. Examples: "Team has 5 engineers", "Sprint cycle is 2 weeks", "Using Jest for testing".
+- "ephemeral": Personal preferences, one-off interactions, formatting choices, style opinions. These are least important long-term. Examples: "User prefers bullet points", "Prefers dark mode", "Likes concise answers".
+
+Hard rules:
+- Only extract information the user states as true, as a decision, as a requirement, or as a stable preference.
+- Do NOT extract transient tasks, questions, research requests, or one-off conversation details.
+- Do NOT turn suggestions, brainstorming, or hypotheticals into facts. If something is not confirmed, skip it.
+- Do NOT trust new facts introduced by the agent unless the user explicitly confirms them.
+- Preserve concrete numeric literals and units exactly when present (examples: "6", "50k", "$79", "15%", "Q2 2026").
+- If a statement explicitly marks an older policy/value as deprecated or obsolete, capture both:
+  1) the current truth
+  2) the deprecation/obsolescence fact
+- Prefer returning fewer items. If uncertain, return an empty list.
+- Max ${maxFacts} facts.
+
+Today's date is ${new Date().toISOString().split('T')[0]}.
+${baseInstructions}`
+
+  const userPrompt = `Conversation:\n${parsedMessages}`
+
+  return [systemPrompt, userPrompt]
+}

package/src/runtime/memory-prompts-parse.ts

@@ -0,0 +1,3 @@
+export function parseMessages(messages: { role: 'user' | 'agent'; content: string }[]): string {
+  return messages.map((m) => `${m.role === 'user' ? 'User' : 'Agent'}: ${m.content}`).join('\n')
+}

package/src/runtime/memory-prompts-update.ts

@@ -0,0 +1,37 @@
+export function getClassifyMemoryDeltaPrompt(params: {
+  existingMemories: { id: string; text: string }[]
+  newFacts: string[]
+}): { systemPrompt: string; userPrompt: string } {
+  const systemPrompt = `You classify how each new fact relates to existing memory.
+
+Decide one classification per fact:
+- new: fact is durable and not materially covered.
+- supersedes: newer truth replacing older truth.
+- contradicts: explicit negation/removal of prior statement or policy.
+- enriches: same durable meaning, better details; usually update one target.
+- duplicate: already represented.
+
+Rules:
+- Return exactly one delta item per new fact, preserving order.
+- fact must match the corresponding newFacts entry verbatim.
+- targetMemoryIds and invalidateTargetIds may only contain ids from existingMemories.
+- invalidateTargetIds must be a subset of targetMemoryIds.
+- In each relation item, set exactly one target: targetMemoryId or targetFactIndex.
+- targetFactIndex must be valid, must not point to the same fact index, and is only for relations to other new facts.
+- For supersedes/contradicts, include target memories when evidence exists.
+- If uncertain, prefer conservative output: classify as new with no targets.
+
+The caller enforces a structured output schema. Return only schema fields.`
+
+  const userPrompt = JSON.stringify(
+    {
+      task: 'Classify memory deltas for new facts.',
+      existingMemories: params.existingMemories,
+      newFacts: params.newFacts,
+    },
+    null,
+    2,
+  )
+
+  return { systemPrompt, userPrompt }
+}

package/src/runtime/memory-scope.ts

@@ -0,0 +1,43 @@
+export const ORG_SCOPE_PREFIX = 'org'
+
+const SCOPE_ID_MAX_LENGTH = 255
+const SCOPE_PREFIX_REGEX = /^[a-z][a-z0-9_]*$/
+
+function stripRecordPrefix(id: string): string {
+  if (typeof id !== 'string' || id.length === 0) {
+    throw new TypeError('id must be a non-empty string')
+  }
+  const [, ...rest] = id.split(':')
+  return rest.length > 0 ? rest.join(':') : id
+}
+
+export function scopeId(prefix: string, id: string): string {
+  if (typeof prefix !== 'string' || prefix.length === 0) {
+    throw new TypeError('prefix must be a non-empty string')
+  }
+  if (!SCOPE_PREFIX_REGEX.test(prefix)) {
+    throw new Error(`Invalid scope prefix: ${prefix}`)
+  }
+
+  const stripped = stripRecordPrefix(id)
+  const scoped = `${prefix}:${stripped}`
+  if (scoped.length > SCOPE_ID_MAX_LENGTH) {
+    throw new Error('scopeId exceeds maximum length')
+  }
+
+  return scoped
+}
+
+export function agentScopeId(orgId: string, agentName: string): string {
+  if (typeof agentName !== 'string' || agentName.trim().length === 0) {
+    throw new TypeError('agentName must be a non-empty string')
+  }
+  const strippedOrgId = stripRecordPrefix(orgId)
+  const scoped = `agent:${strippedOrgId}:${agentName.trim()}`
+
+  if (scoped.length > SCOPE_ID_MAX_LENGTH) {
+    throw new Error('scopeId exceeds maximum length')
+  }
+
+  return scoped
+}