@strav/brain 0.1.0

package/src/index.ts

@@ -0,0 +1,42 @@
+export { default, default as BrainManager } from './brain_manager.ts'
+
+// Provider
+export { default as BrainProvider } from './brain_provider.ts'
+export { brain, AgentRunner, Thread } from './helpers.ts'
+export { Agent } from './agent.ts'
+export { defineTool, defineToolbox } from './tool.ts'
+export { Workflow } from './workflow.ts'
+export { AnthropicProvider } from './providers/anthropic_provider.ts'
+export { OpenAIProvider } from './providers/openai_provider.ts'
+export { OpenAIResponsesProvider } from './providers/openai_responses_provider.ts'
+export { parseSSE } from './utils/sse_parser.ts'
+export { zodToJsonSchema } from './utils/schema.ts'
+export type {
+  AIProvider,
+  BrainConfig,
+  ProviderConfig,
+  CompletionRequest,
+  CompletionResponse,
+  Message,
+  ContentBlock,
+  ToolCall,
+  ToolDefinition,
+  StreamChunk,
+  Usage,
+  AgentResult,
+  ToolCallRecord,
+  AgentEvent,
+  WorkflowResult,
+  EmbeddingResponse,
+  JsonSchema,
+  SSEEvent,
+  BeforeHook,
+  AfterHook,
+  SerializedThread,
+  OutputSchema,
+} from './types.ts'
+export type { ChatOptions, GenerateOptions, GenerateResult, EmbedOptions } from './helpers.ts'
+export type { WorkflowContext } from './workflow.ts'
+
+// Memory
+export * from './memory/index.ts'

package/src/memory/context_budget.ts

@@ -0,0 +1,120 @@
+import type { Message } from '../types.ts'
+import type { MemoryConfig, Fact } from './types.ts'
+import { TokenCounter } from './token_counter.ts'
+import { SemanticMemory } from './semantic_memory.ts'
+
+export interface BudgetBreakdown {
+  /** Total context window tokens. */
+  total: number
+  /** Reserved for the model's response. */
+  response: number
+  /** Tokens used by system prompt + injected facts. */
+  system: number
+  /** Tokens used by the episodic summary. */
+  summary: number
+  /** Available budget for working messages. */
+  working: number
+  /** Tokens currently used by working messages. */
+  used: number
+  /** Remaining headroom before compaction is triggered. */
+  remaining: number
+}
+
+const DEFAULT_RESPONSE_RESERVE = 0.25
+const DEFAULT_MIN_WORKING_MESSAGES = 4
+
+/**
+ * Calculates and tracks how the context window budget is allocated
+ * across system prompt, episodic summaries, semantic facts, and
+ * working messages.
+ */
+export class ContextBudget {
+  private readonly maxTokens: number
+  private readonly responseReserve: number
+  private readonly minWorkingMessages: number
+
+  constructor(config: MemoryConfig, model: string) {
+    this.maxTokens = config.maxContextTokens ?? TokenCounter.contextWindow(model)
+    this.responseReserve = config.responseReserve ?? DEFAULT_RESPONSE_RESERVE
+    this.minWorkingMessages = config.minWorkingMessages ?? DEFAULT_MIN_WORKING_MESSAGES
+  }
+
+  /** Check whether the current context fits within the token budget. */
+  fits(system: string | undefined, summary: string, facts: Fact[], messages: Message[]): boolean {
+    const bd = this.breakdown(system, summary, facts, messages)
+    return bd.remaining >= 0
+  }
+
+  /** Get a detailed breakdown of token usage. */
+  breakdown(
+    system: string | undefined,
+    summary: string,
+    facts: Fact[],
+    messages: Message[]
+  ): BudgetBreakdown {
+    const total = this.maxTokens
+    const response = Math.ceil(total * this.responseReserve)
+
+    const systemTokens = TokenCounter.estimate(system ?? '')
+    const factsTokens =
+      facts.length > 0 ? TokenCounter.estimate(SemanticMemory.formatFacts(facts)) : 0
+    const systemTotal = systemTokens + factsTokens
+
+    const summaryTokens = TokenCounter.estimate(summary)
+    const messageTokens = TokenCounter.estimateMessages(messages)
+
+    const working = total - response - systemTotal - summaryTokens
+    const remaining = working - messageTokens
+
+    return {
+      total,
+      response,
+      system: systemTotal,
+      summary: summaryTokens,
+      working: Math.max(working, 0),
+      used: messageTokens,
+      remaining,
+    }
+  }
+
+  /**
+   * Determine how many messages from the front of the array
+   * need to be compacted so the rest fits within budget.
+   *
+   * Returns 0 if everything already fits.
+   * Respects minWorkingMessages — never compacts below that threshold.
+   */
+  compactionNeeded(
+    system: string | undefined,
+    summary: string,
+    facts: Fact[],
+    messages: Message[]
+  ): number {
+    if (this.fits(system, summary, facts, messages)) return 0
+
+    const total = this.maxTokens
+    const response = Math.ceil(total * this.responseReserve)
+    const systemTokens = TokenCounter.estimate(system ?? '')
+    const factsTokens =
+      facts.length > 0 ? TokenCounter.estimate(SemanticMemory.formatFacts(facts)) : 0
+    const summaryTokens = TokenCounter.estimate(summary)
+
+    const available = total - response - systemTokens - factsTokens - summaryTokens
+    const maxCompactable = Math.max(0, messages.length - this.minWorkingMessages)
+
+    // Accumulate from the back (most recent) until we exceed the budget
+    let kept = 0
+    let tokensFromBack = 0
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const msgTokens = TokenCounter.estimateMessages([messages[i]!])
+      if (tokensFromBack + msgTokens > available) break
+      tokensFromBack += msgTokens
+      kept++
+    }
+
+    const toCompact = messages.length - kept
+
+    // Never compact below minWorkingMessages
+    return Math.min(toCompact, maxCompactable)
+  }
+}

package/src/memory/index.ts

@@ -0,0 +1,17 @@
+export { TokenCounter } from './token_counter.ts'
+export { ContextBudget } from './context_budget.ts'
+export type { BudgetBreakdown } from './context_budget.ts'
+export { MemoryManager } from './memory_manager.ts'
+export type { PreparedContext } from './memory_manager.ts'
+export { SemanticMemory } from './semantic_memory.ts'
+export { InMemoryThreadStore } from './thread_store.ts'
+export { SlidingWindowStrategy } from './strategies/sliding_window.ts'
+export { SummarizeStrategy } from './strategies/summarize.ts'
+export type {
+  MemoryConfig,
+  CompactionStrategy,
+  CompactionResult,
+  ThreadStore,
+  SerializedMemoryThread,
+  Fact,
+} from './types.ts'

package/src/memory/memory_manager.ts

@@ -0,0 +1,168 @@
+import type { Message } from '../types.ts'
+import type { CompactionStrategy, Fact, MemoryConfig } from './types.ts'
+import { ContextBudget } from './context_budget.ts'
+import { SemanticMemory } from './semantic_memory.ts'
+import { SlidingWindowStrategy } from './strategies/sliding_window.ts'
+import { SummarizeStrategy } from './strategies/summarize.ts'
+
+const DEFAULT_COMPACTION_BATCH_SIZE = 10
+const DEFAULT_EXTRACT_FACTS = true
+
+export interface PreparedContext {
+  /** Original system prompt augmented with summary and facts. */
+  system: string | undefined
+  /** Working messages (trimmed, possibly after compaction). */
+  messages: Message[]
+  /** Whether compaction occurred during this preparation. */
+  compacted: boolean
+}
+
+/**
+ * Orchestrates the three-tier memory system:
+ * - Working memory (recent messages within context budget)
+ * - Episodic memory (compacted summaries)
+ * - Semantic memory (extracted facts)
+ *
+ * Instantiated per-Thread, not via DI. Configured through MemoryConfig.
+ */
+export class MemoryManager {
+  private _strategy: CompactionStrategy
+  private _semanticMemory = new SemanticMemory()
+  private _summary = ''
+  private _compactionBatchSize: number
+  private _extractFacts: boolean
+
+  constructor(
+    private config: MemoryConfig,
+    private budget: ContextBudget
+  ) {
+    this._compactionBatchSize = config.compactionBatchSize ?? DEFAULT_COMPACTION_BATCH_SIZE
+    this._extractFacts = config.extractFacts ?? DEFAULT_EXTRACT_FACTS
+    this._strategy = MemoryManager.createStrategy(config.strategy)
+  }
+
+  /**
+   * Prepare context for sending to the LLM.
+   *
+   * This is the core method called by Thread before every completion request.
+   * It checks the token budget, triggers compaction if needed, and builds
+   * the final system prompt with summary and facts injected.
+   *
+   * Important: when compaction occurs, the `messages` array passed in is
+   * mutated (oldest messages are spliced out). This keeps Thread's internal
+   * state consistent with what was actually sent.
+   */
+  async prepareContext(
+    system: string | undefined,
+    messages: Message[],
+    options: { provider: string; model: string }
+  ): Promise<PreparedContext> {
+    const facts = this._semanticMemory.all()
+    let compacted = false
+
+    // Check if compaction is needed
+    const needed = this.budget.compactionNeeded(system, this._summary, facts, messages)
+
+    if (needed > 0) {
+      const toCompact = messages.splice(0, needed)
+
+      const result = await this._strategy.compact(toCompact, {
+        provider: options.provider,
+        model: options.model,
+        existingSummary: this._summary || undefined,
+        extractFacts: this._extractFacts,
+      })
+
+      // Update episodic summary
+      if (result.summary) {
+        this._summary = result.summary
+      }
+
+      // Merge extracted facts
+      if (result.facts) {
+        for (const fact of result.facts) {
+          this._semanticMemory.set(fact.key, fact.value, fact.source, fact.confidence)
+        }
+      }
+
+      compacted = true
+    }
+
+    // Build augmented system prompt
+    const augmentedSystem = this.buildSystemPrompt(system)
+
+    return {
+      system: augmentedSystem,
+      messages: [...messages],
+      compacted,
+    }
+  }
+
+  /** Access the semantic memory for manual fact management. */
+  get facts(): SemanticMemory {
+    return this._semanticMemory
+  }
+
+  /** Get the current episodic summary. */
+  get episodicSummary(): string {
+    return this._summary
+  }
+
+  /** Replace the current compaction strategy. */
+  useStrategy(strategy: CompactionStrategy): void {
+    this._strategy = strategy
+  }
+
+  /** Serialize the full memory state for persistence. */
+  serialize(): { summary: string; facts: Fact[] } {
+    return {
+      summary: this._summary,
+      facts: this._semanticMemory.serialize(),
+    }
+  }
+
+  /** Restore memory state from persisted data. */
+  restore(data: { summary?: string; facts?: Fact[] }): void {
+    if (data.summary !== undefined) {
+      this._summary = data.summary
+    }
+    if (data.facts) {
+      this._semanticMemory.restore(data.facts)
+    }
+  }
+
+  // ── Private ────────────────────────────────────────────────────────────────
+
+  /** Build the final system prompt with summary and facts injected. */
+  private buildSystemPrompt(original: string | undefined): string | undefined {
+    const parts: string[] = []
+
+    if (original) {
+      parts.push(original)
+    }
+
+    if (this._summary) {
+      parts.push(
+        `<conversation_history_summary>\n${this._summary}\n</conversation_history_summary>`
+      )
+    }
+
+    const factsBlock = this._semanticMemory.toPromptBlock()
+    if (factsBlock) {
+      parts.push(factsBlock)
+    }
+
+    return parts.length > 0 ? parts.join('\n\n') : undefined
+  }
+
+  /** Create a compaction strategy by name. */
+  private static createStrategy(name?: string): CompactionStrategy {
+    switch (name) {
+      case 'sliding_window':
+        return new SlidingWindowStrategy()
+      case 'summarize':
+      default:
+        return new SummarizeStrategy()
+    }
+  }
+}

package/src/memory/semantic_memory.ts

@@ -0,0 +1,89 @@
+import type { Fact } from './types.ts'
+
+/**
+ * In-memory structured fact store.
+ *
+ * Facts are key-value pairs representing stable knowledge about the
+ * user and their situation, extracted from conversation or set explicitly.
+ * They are injected into the system prompt so the model always has
+ * access to critical context regardless of compaction.
+ *
+ * Platform can persist facts via the ThreadStore's `facts` field.
+ */
+export class SemanticMemory {
+  private _facts = new Map<string, Fact>()
+
+  /** Add or update a fact. */
+  set(
+    key: string,
+    value: string,
+    source: 'extracted' | 'explicit' = 'explicit',
+    confidence: number = 1.0
+  ): void {
+    const now = new Date().toISOString()
+    const existing = this._facts.get(key)
+
+    this._facts.set(key, {
+      key,
+      value,
+      source,
+      confidence,
+      createdAt: existing?.createdAt ?? now,
+      updatedAt: now,
+    })
+  }
+
+  /** Get a specific fact by key. */
+  get(key: string): Fact | undefined {
+    return this._facts.get(key)
+  }
+
+  /** Get all facts as an array. */
+  all(): Fact[] {
+    return Array.from(this._facts.values())
+  }
+
+  /** Get the number of stored facts. */
+  get size(): number {
+    return this._facts.size
+  }
+
+  /** Remove a fact by key. */
+  remove(key: string): boolean {
+    return this._facts.delete(key)
+  }
+
+  /** Format all facts as a prompt block for injection into the system prompt. */
+  toPromptBlock(): string {
+    return SemanticMemory.formatFacts(this.all())
+  }
+
+  /**
+   * Static formatter — also used by ContextBudget for token estimation
+   * without needing a SemanticMemory instance.
+   */
+  static formatFacts(facts: Fact[]): string {
+    if (facts.length === 0) return ''
+
+    const lines = facts.map(f => `- ${f.key}: ${f.value}`)
+    return `<known_facts>\n${lines.join('\n')}\n</known_facts>`
+  }
+
+  /** Serialize facts for persistence. */
+  serialize(): Fact[] {
+    return this.all()
+  }
+
+  /** Restore facts from persisted data. */
+  restore(facts: Fact[]): void {
+    this._facts.clear()
+    for (const fact of facts) {
+      this._facts.set(fact.key, { ...fact })
+    }
+  }
+
+  /** Clear all facts. */
+  clear(): void {
+    this._facts.clear()
+  }
+}

package/src/memory/strategies/sliding_window.ts

@@ -0,0 +1,20 @@
+import type { Message } from '../../types.ts'
+import type { CompactionResult, CompactionStrategy } from '../types.ts'
+
+/**
+ * Simplest compaction strategy — discards oldest messages
+ * without producing a summary. No LLM call required.
+ *
+ * Use this when you want fast, predictable compaction
+ * and don't need continuity from older messages.
+ */
+export class SlidingWindowStrategy implements CompactionStrategy {
+  readonly name = 'sliding_window'
+
+  async compact(
+    _messages: Message[],
+    _options: { provider: string; model: string; existingSummary?: string; extractFacts?: boolean }
+  ): Promise<CompactionResult> {
+    return { summary: '', facts: [], summaryTokens: 0 }
+  }
+}

package/src/memory/strategies/summarize.ts

@@ -0,0 +1,157 @@
+import BrainManager from '../../brain_manager.ts'
+import type { Message } from '../../types.ts'
+import type { CompactionResult, CompactionStrategy, Fact } from '../types.ts'
+import { TokenCounter } from '../token_counter.ts'
+
+const SUMMARIZE_SYSTEM = `You are a conversation summarizer. Your job is to produce a concise summary that preserves all information needed for conversation continuity.
+
+Preserve:
+- Key decisions and their reasoning
+- Important facts about the user and their situation
+- Open questions or pending action items
+- Context that would be needed to continue the conversation naturally
+
+Be concise but thorough. Write in third person past tense.`
+
+const SUMMARIZE_PROMPT = `Summarize the following conversation segment. The summary will replace these messages in the conversation context, so it must preserve everything needed for continuity.
+
+<messages>
+{{messages}}
+</messages>`
+
+const MERGE_PROMPT = `Below is an existing conversation summary followed by a new segment of messages. Produce a single updated summary that merges the existing summary with the new information. Do not simply append — integrate and consolidate.
+
+<existing_summary>
+{{existingSummary}}
+</existing_summary>
+
+<new_messages>
+{{messages}}
+</new_messages>`
+
+const EXTRACT_FACTS_SUFFIX = `
+
+After the summary, output a JSON block with extracted facts. Each fact should be a key-value pair representing a stable piece of information about the user or their situation. Only include facts you are confident about.
+
+Format:
+<facts>
+[{"key": "fact_key", "value": "fact value", "confidence": 0.9}]
+</facts>`
+
+/**
+ * Uses the thread's own LLM to produce a natural-language summary
+ * of compacted messages. Optionally extracts structured facts.
+ *
+ * When an existing summary is provided, it merges rather than
+ * creating a summary-of-summary chain.
+ */
+export class SummarizeStrategy implements CompactionStrategy {
+  readonly name = 'summarize'
+
+  async compact(
+    messages: Message[],
+    options: { provider: string; model: string; existingSummary?: string; extractFacts?: boolean }
+  ): Promise<CompactionResult> {
+    const messagesText = SummarizeStrategy.formatMessages(messages)
+
+    let prompt: string
+    if (options.existingSummary) {
+      prompt = MERGE_PROMPT.replace('{{existingSummary}}', options.existingSummary).replace(
+        '{{messages}}',
+        messagesText
+      )
+    } else {
+      prompt = SUMMARIZE_PROMPT.replace('{{messages}}', messagesText)
+    }
+
+    if (options.extractFacts) {
+      prompt += EXTRACT_FACTS_SUFFIX
+    }
+
+    const response = await BrainManager.complete(options.provider, {
+      model: options.model,
+      messages: [{ role: 'user', content: prompt }],
+      system: SUMMARIZE_SYSTEM,
+      maxTokens: 2048,
+      temperature: 0.3,
+    })
+
+    const { summary, facts } = SummarizeStrategy.parseResponse(
+      response.content,
+      options.extractFacts
+    )
+
+    return {
+      summary,
+      facts,
+      summaryTokens: TokenCounter.estimate(summary),
+    }
+  }
+
+  /** Format messages into readable text for the summarization prompt. */
+  private static formatMessages(messages: Message[]): string {
+    const lines: string[] = []
+
+    for (const msg of messages) {
+      const role = msg.role.charAt(0).toUpperCase() + msg.role.slice(1)
+      const content =
+        typeof msg.content === 'string'
+          ? msg.content
+          : msg.content
+              .filter(b => b.type === 'text' && b.text)
+              .map(b => b.text)
+              .join('\n')
+
+      if (content) {
+        lines.push(`${role}: ${content}`)
+      }
+
+      if (msg.toolCalls) {
+        for (const call of msg.toolCalls) {
+          lines.push(`[Tool call: ${call.name}(${JSON.stringify(call.arguments)})]`)
+        }
+      }
+    }
+
+    return lines.join('\n\n')
+  }
+
+  /** Parse the LLM response, extracting the summary and optional facts block. */
+  private static parseResponse(
+    content: string,
+    extractFacts?: boolean
+  ): { summary: string; facts: Fact[] } {
+    if (!extractFacts) {
+      return { summary: content.trim(), facts: [] }
+    }
+
+    const factsMatch = content.match(/<facts>\s*([\s\S]*?)\s*<\/facts>/)
+    const now = new Date().toISOString()
+
+    let facts: Fact[] = []
+    if (factsMatch?.[1]) {
+      try {
+        const parsed = JSON.parse(factsMatch[1]) as Array<{
+          key: string
+          value: string
+          confidence?: number
+        }>
+        facts = parsed.map(f => ({
+          key: f.key,
+          value: f.value,
+          source: 'extracted' as const,
+          confidence: f.confidence ?? 0.7,
+          createdAt: now,
+          updatedAt: now,
+        }))
+      } catch {
+        // If fact parsing fails, continue with just the summary
+      }
+    }
+
+    // Remove the facts block from the summary
+    const summary = content.replace(/<facts>[\s\S]*?<\/facts>/, '').trim()
+
+    return { summary, facts }
+  }
+}

package/src/memory/thread_store.ts

@@ -0,0 +1,56 @@
+import type { SerializedMemoryThread, ThreadStore } from './types.ts'
+
+/**
+ * In-memory thread store for development and testing.
+ *
+ * Platform will provide a DatabaseThreadStore backed by PostgreSQL.
+ * This implementation stores everything in a Map — data is lost
+ * when the process exits.
+ */
+export class InMemoryThreadStore implements ThreadStore {
+  private threads = new Map<string, SerializedMemoryThread>()
+
+  async save(thread: SerializedMemoryThread): Promise<void> {
+    this.threads.set(thread.id, {
+      ...thread,
+      messages: [...thread.messages],
+      facts: thread.facts ? [...thread.facts] : undefined,
+    })
+  }
+
+  async load(id: string): Promise<SerializedMemoryThread | null> {
+    const thread = this.threads.get(id)
+    if (!thread) return null
+
+    return {
+      ...thread,
+      messages: [...thread.messages],
+      facts: thread.facts ? [...thread.facts] : undefined,
+    }
+  }
+
+  async delete(id: string): Promise<void> {
+    this.threads.delete(id)
+  }
+
+  async list(options?: { limit?: number; offset?: number }): Promise<SerializedMemoryThread[]> {
+    const all = Array.from(this.threads.values()).sort((a, b) =>
+      b.updatedAt.localeCompare(a.updatedAt)
+    )
+
+    const offset = options?.offset ?? 0
+    const limit = options?.limit ?? all.length
+
+    return all.slice(offset, offset + limit)
+  }
+
+  /** Get the number of stored threads. For testing. */
+  get size(): number {
+    return this.threads.size
+  }
+
+  /** Clear all stored threads. For testing. */
+  clear(): void {
+    this.threads.clear()
+  }
+}