claude-brain 0.30.2 → 0.30.3

package/src/memory/index.ts

@@ -1,1060 +1,943 @@
-/**
- * Memory System - Main Module
- * Phase 3: Memory and Embedding System
- *
- * Unified memory system manager that combines all components
- */
-
-import { randomUUID } from 'crypto'
-import type { Logger } from 'pino'
-import { MemoryDatabase } from './database'
-import { EmbeddingService } from './embeddings'
-import { MemoryStore } from './store'
-import { SemanticSearch } from './search'
-import { MemoryContextBuilder } from './context-builder'
-import type { MemorySystemStats } from './types'
-import { ChromaManager, DEFAULT_CHROMA_CONFIG, getChromaConfigFromEnv, ChromaMigration, type MigrationOptions } from './chroma'
-import { FTS5Search } from './fts5-search'
-import { addFTS5Tables } from './migrations/add-fts5'
-
-// Re-export all types and classes for external use
-export * from './types'
-export { MemoryDatabase } from './database'
-export { EmbeddingService } from './embeddings'
-export { MemoryStore } from './store'
-export { SemanticSearch } from './search'
-export { MemoryContextBuilder, type ContextOptions } from './context-builder'
-export {
-  embeddingToBuffer,
-  bufferToEmbedding,
-  normalizeEmbedding,
-  euclideanDistance,
-  cosineSimilarity,
-  dotProduct,
-  magnitude,
-  averageEmbeddings,
-  topKSimilar
-} from './embedding-utils'
-
-// Phase 12: Advanced Memory Features
-export { PatternRecognizer, type Pattern } from './patterns'
-export { LearningSystem, type Correction, type Preference, type LearningInsights } from './learning'
-export { KnowledgeExtractor, type ExtractedKnowledge, type ExtractionResult } from './knowledge-extractor'
-
-// Phase 26: FTS5 Search
-export { FTS5Search } from './fts5-search'
-export type { ObservationCategory, NewObservation, ObservationResult, ScoredResult } from './fts5-search'
-
-/**
- * Unified memory system manager
- * Combines database, embeddings, store, search, and context building
- */
-export class MemoryManager {
-  readonly database: MemoryDatabase
-  readonly embeddings: EmbeddingService
-  readonly contextBuilder: MemoryContextBuilder
-  readonly chroma: ChromaManager
-
-  // Phase 26: FTS5 search (always available, no external deps)
-  private _fts5: FTS5Search | null = null
-
-  // Store and search are initialized after database is ready
-  private _store: MemoryStore | null = null
-  private _search: SemanticSearch | null = null
-
-  private logger: Logger
-  private initialized: boolean = false
-  private useChromaDB: boolean = true
-  private onDecisionStoredCallbacks: ((input: any) => void)[] = []
-  private onDecisionDeletedCallbacks: ((id: string) => void)[] = []
-
-  constructor(
-    dbPath: string,
-    logger: Logger,
-    useChromaDB: boolean = true,
-    chromaConfig?: any,
-    customEmbeddings?: EmbeddingService
-  ) {
-    this.logger = logger.child({ component: 'memory-manager' })
-    this.useChromaDB = useChromaDB
-
-    this.database = new MemoryDatabase(dbPath, logger)
-    this.embeddings = customEmbeddings || new EmbeddingService(logger)
-    this.contextBuilder = new MemoryContextBuilder(logger)
-
-    const envConfig = getChromaConfigFromEnv()
-    const config = { ...DEFAULT_CHROMA_CONFIG, ...envConfig, ...chromaConfig }
-    this.chroma = new ChromaManager(logger, config)
-  }
-
-  /**
-   * Initialize memory system
-   * Must be called before using store or search
-   */
-  async initialize(): Promise<void> {
-    if (this.initialized) {
-      this.logger.warn('Memory system already initialized')
-      return
-    }
-
-    try {
-      this.logger.info('Initializing memory system...')
-
-      await this.database.initialize()
-
-      await this.embeddings.initialize()
-
-      const db = this.database.getDb()
-      this._store = new MemoryStore(db, this.embeddings, this.logger)
-      this._search = new SemanticSearch(db, this.embeddings, this.logger)
-
-      // Phase 26: Always initialize FTS5 (just SQLite, no external deps)
-      try {
-        addFTS5Tables(db)
-        this._fts5 = new FTS5Search(db, this.logger)
-        this.logger.info('FTS5 search initialized')
-
-        // Phase 26b: Backfill embeddings for existing observations (async, non-blocking)
-        if (this.embeddings.isReady()) {
-          this.backfillEmbeddings().then(count => {
-            if (count > 0) {
-              this.logger.info({ count }, 'Backfilled embeddings for existing observations')
-            }
-          }).catch(() => {
-            // Non-critical, log handled in backfillEmbeddings
-          })
-        }
-      } catch (error) {
-        this.logger.warn({ error }, 'Failed to initialize FTS5, continuing without it')
-      }
-
-      if (this.useChromaDB) {
-        try {
-          await this.chroma.initialize()
-          this.logger.info('ChromaDB backend initialized successfully')
-        } catch (error) {
-          this.logger.warn({ error }, 'Failed to initialize ChromaDB, falling back to SQLite backend')
-          this.useChromaDB = false
-        }
-      }
-
-      this.initialized = true
-      this.logger.info('Memory system initialized successfully')
-    } catch (error) {
-      this.logger.error({ error }, 'Failed to initialize memory system')
-      throw error
-    }
-  }
-
-  /**
-   * Get the memory store (throws if not initialized)
-   */
-  get store(): MemoryStore {
-    if (!this._store) {
-      throw new Error('Memory system not initialized. Call initialize() first.')
-    }
-    return this._store
-  }
-
-  /**
-   * Get the semantic search engine (throws if not initialized)
-   */
-  get search(): SemanticSearch {
-    if (!this._search) {
-      throw new Error('Memory system not initialized. Call initialize() first.')
-    }
-    return this._search
-  }
-
-  /**
-   * Get the FTS5 search engine (null if not initialized)
-   */
-  get fts5(): FTS5Search | null {
-    return this._fts5
-  }
-
-  /**
-   * Check if memory system is initialized
-   */
-  isInitialized(): boolean {
-    return this.initialized
-  }
-
-  /**
-   * Generate and store an embedding for an observation (fire-and-forget).
-   * Runs asynchronously to avoid blocking the store operation.
-   */
-  private storeObservationEmbedding(observationId: string, text: string): void {
-    if (!this._fts5 || !this.embeddings.isReady()) return
-
-    // Fire-and-forget: don't block the store operation
-    this.embeddings.generateEmbedding(text).then(embedding => {
-      this._fts5?.storeEmbedding(observationId, embedding)
-    }).catch(error => {
-      this.logger.debug({ error, observationId }, 'Failed to store observation embedding')
-    })
-  }
-
-  /**
-   * Backfill embeddings for existing observations that don't have them.
-   * Call this after initialization to migrate existing data.
-   */
-  async backfillEmbeddings(batchSize: number = 50): Promise<number> {
-    if (!this._fts5 || !this.embeddings.isReady()) return 0
-    return this._fts5.backfillEmbeddings(this.embeddings, batchSize)
-  }
-
-  close(): void {
-    if (this.useChromaDB) {
-      this.chroma.close()
-    }
-    this.database.close()
-    this._store = null
-    this._search = null
-    this.initialized = false
-    this.logger.info('Memory system closed')
-  }
-
-  /**
-   * Get system statistics
-   */
-  getStats(): MemorySystemStats {
-    if (!this.initialized) {
-      throw new Error('Memory system not initialized')
-    }
-
-    return {
-      database: this.database.getStats(),
-      embeddings: this.embeddings.getCacheStats()
-    }
-  }
-
-  /**
-   * Health check
-   */
-  async healthCheck(): Promise<boolean> {
-    if (!this.initialized) {
-      return false
-    }
-    return this.database.healthCheck()
-  }
-
-  /**
-   * Check if ChromaDB backend is enabled and connected
-   */
-  isChromaDBEnabled(): boolean {
-    return this.useChromaDB
-  }
-
-  /**
-   * Add a listener that fires when a decision is stored (from any backend)
-   */
-  addDecisionStoredListener(callback: (input: any) => void): () => void {
-    this.onDecisionStoredCallbacks.push(callback)
-    let chromaUnsub: (() => void) | undefined
-    if (this.useChromaDB) {
-      chromaUnsub = this.chroma.store.addDecisionStoredListener(callback)
-    }
-    return () => {
-      const idx = this.onDecisionStoredCallbacks.indexOf(callback)
-      if (idx >= 0) this.onDecisionStoredCallbacks.splice(idx, 1)
-      chromaUnsub?.()
-    }
-  }
-
-  /**
-   * Add a listener that fires when a decision is deleted
-   */
-  addDecisionDeletedListener(callback: (id: string) => void): () => void {
-    this.onDecisionDeletedCallbacks.push(callback)
-    return () => {
-      const idx = this.onDecisionDeletedCallbacks.indexOf(callback)
-      if (idx >= 0) this.onDecisionDeletedCallbacks.splice(idx, 1)
-    }
-  }
-
-  async rememberDecision(
-    project: string,
-    context: string,
-    decision: string,
-    reasoning: string,
-    options?: { alternatives?: string; tags?: string[] }
-  ): Promise<string> {
-    // BUG-001 fix: Generate a single shared ID for all backends
-    const sharedId = randomUUID()
-
-    // Phase 26: Always store in FTS5 if available
-    let fts5Id: string | undefined
-    if (this._fts5) {
-      try {
-        // Check for duplicates first
-        const dup = this._fts5.searchForDuplicates(decision, project)
-        if (dup) {
-          this.logger.info({ existingId: dup.id, score: dup.score }, 'FTS5 skipping duplicate decision')
-          return dup.id
-        }
-
-        fts5Id = this._fts5.store({
-          project,
-          category: 'decision',
-          content: decision,
-          reasoning,
-          context,
-          tags: options?.tags
-        }, sharedId)
-
-        // Store embedding for semantic search
-        this.storeObservationEmbedding(fts5Id, [decision, reasoning, context].filter(Boolean).join(' '))
-      } catch (error) {
-        this.logger.warn({ error }, 'FTS5 store failed, continuing with other backends')
-      }
-    }
-
-    // Store in ChromaDB if available
-    if (this.useChromaDB) {
-      try {
-        const chromaId = await this.chroma.store.storeDecision({
-          id: sharedId,
-          project,
-          context,
-          decision,
-          reasoning,
-          alternatives: options?.alternatives,
-          tags: options?.tags
-        })
-        return fts5Id || chromaId
-      } catch (error) {
-        this.logger.warn({ error }, 'ChromaDB store failed')
-        if (fts5Id) return fts5Id
-      }
-    }
-
-    // Fallback to legacy SQLite store if no FTS5 and no ChromaDB
-    if (!fts5Id) {
-      const id = await this.store.storeDecision({
-        project,
-        context,
-        decision,
-        reasoning,
-        alternatives: options?.alternatives,
-        tags: options?.tags
-      })
-      fts5Id = id
-    }
-
-    // Notify listeners (e.g., knowledge graph builder)
-    for (const cb of this.onDecisionStoredCallbacks) {
-      try {
-        cb({ project, context, decision, reasoning, alternatives: options?.alternatives, tags: options?.tags, id: fts5Id })
-      } catch {}
-    }
-    return fts5Id!
-  }
-
-  /**
-   * Get raw search results - uses FTS5 as primary, embeddings as semantic fallback
-   * Use this for internal operations that need raw results
-   */
-  async searchRaw(
-    query: string,
-    options?: { project?: string; limit?: number; minSimilarity?: number }
-  ): Promise<any[]> {
-    const limit = options?.limit || 5
-    const LOW_CONFIDENCE_THRESHOLD = 0.4
-
-    // Phase 26: Try FTS5 first (always available)
-    if (this._fts5) {
-      const ftsResults = this._fts5.searchWithConfidence(query, options?.project, limit)
-
-      // Check if FTS5 returned good results
-      const hasGoodResults = ftsResults.length > 0 &&
-        ftsResults.some(r => r.score >= LOW_CONFIDENCE_THRESHOLD)
-
-      if (hasGoodResults) {
-        return this.transformFtsResults(ftsResults)
-      }
-
-      // Phase 26b: FTS5 returned nothing or low-confidence — try semantic search
-      if (this.embeddings.isReady() && this._fts5.hasEmbeddings()) {
-        try {
-          const queryEmbedding = await this.embeddings.generateEmbedding(query)
-          const semanticResults = await this._fts5.semanticSearch(
-            queryEmbedding,
-            options?.project,
-            limit,
-            options?.minSimilarity || 0.3
-          )
-
-          if (semanticResults.length > 0) {
-            this.logger.debug(
-              { query, ftsCount: ftsResults.length, semanticCount: semanticResults.length },
-              'Semantic search found results where FTS5 did not'
-            )
-
-            // If we had some low-confidence FTS5 results, merge with semantic results
-            if (ftsResults.length > 0) {
-              return this.mergeSearchResults(ftsResults, semanticResults, limit)
-            }
-
-            return this.transformFtsResults(semanticResults)
-          }
-        } catch (error) {
-          this.logger.warn({ error }, 'Semantic search fallback failed')
-        }
-      }
-
-      // Return whatever FTS5 found (even if low confidence)
-      if (ftsResults.length > 0) {
-        return this.transformFtsResults(ftsResults)
-      }
-    }
-
-    // Fallback: Try ChromaDB if available
-    if (this.useChromaDB) {
-      const chromaResults = await this.chroma.search.searchDecisions(query, {
-        project: options?.project,
-        limit,
-        minSimilarity: options?.minSimilarity || 0.5
-      })
-      return chromaResults.map(r => {
-        const memoryContent = typeof r.content === 'string' ? r.content : JSON.stringify(r.content)
-        const decisionObj = r.metadata.decision ? {
-          id: r.id,
-          project: r.metadata.project || options?.project || 'unknown',
-          context: r.metadata.context || '',
-          decision: r.metadata.decision || memoryContent,
-          reasoning: r.metadata.reasoning || '',
-          alternatives: r.metadata.alternatives_considered || '',
-          tags: r.metadata.tags || [],
-          outcome: r.metadata.outcome,
-          createdAt: r.metadata.created_at ? new Date(r.metadata.created_at) : new Date()
-        } : undefined
-
-        return {
-          id: r.id,
-          content: decisionObj ? decisionObj.decision : memoryContent,
-          memory: {
-            id: r.id,
-            project: r.metadata.project || options?.project || 'unknown',
-            content: memoryContent,
-            createdAt: r.metadata.created_at ? new Date(r.metadata.created_at) : new Date(),
-            metadata: r.metadata
-          },
-          similarity: r.similarity,
-          decision: decisionObj,
-          metadata: r.metadata
-        }
-      })
-    }
-
-    // Final fallback: legacy SQLite search
-    return await this.search.search(query, {
-      project: options?.project,
-      limit,
-      minSimilarity: options?.minSimilarity || 0.5
-    })
-  }
-
-  /**
-   * Transform FTS5/semantic ScoredResults to the expected MemorySearchResult structure
-   */
-  private transformFtsResults(results: import('./fts5-search').ScoredResult[]): any[] {
-    return results.map(r => ({
-      id: r.id,
-      content: r.content,
-      memory: {
-        id: r.id,
-        project: r.project,
-        content: r.content,
-        createdAt: new Date(r.created_at),
-        metadata: {
-          project: r.project,
-          category: r.category,
-          context: r.context || '',
-          reasoning: r.reasoning || '',
-          tags: r.tags,
-          created_at: r.created_at
-        }
-      },
-      similarity: r.score,
-      decision: r.category === 'decision' ? {
-        id: r.id,
-        project: r.project,
-        context: r.context || '',
-        decision: r.content,
-        reasoning: r.reasoning || '',
-        alternatives: '',
-        tags: r.tags,
-        createdAt: new Date(r.created_at)
-      } : undefined,
-      metadata: {
-        project: r.project,
-        category: r.category,
-        context: r.context || '',
-        reasoning: r.reasoning || '',
-        tags: r.tags,
-        created_at: r.created_at
-      }
-    }))
-  }
-
-  /**
-   * Merge FTS5 and semantic search results, deduplicating by ID.
-   * Semantic results get a small boost since they matched conceptually.
-   */
-  private mergeSearchResults(
-    ftsResults: import('./fts5-search').ScoredResult[],
-    semanticResults: import('./fts5-search').ScoredResult[],
-    limit: number
-  ): any[] {
-    const seen = new Set<string>()
-    const merged: import('./fts5-search').ScoredResult[] = []
-
-    // Add semantic results first (they matched conceptually when FTS5 didn't)
-    for (const r of semanticResults) {
-      if (!seen.has(r.id)) {
-        seen.add(r.id)
-        merged.push(r)
-      }
-    }
-
-    // Then add FTS5 results that aren't already included
-    for (const r of ftsResults) {
-      if (!seen.has(r.id)) {
-        seen.add(r.id)
-        merged.push(r)
-      }
-    }
-
-    // Sort by score descending and limit
-    merged.sort((a, b) => b.score - a.score)
-    return this.transformFtsResults(merged.slice(0, limit))
-  }
-
-  async recallSimilar(
-    query: string,
-    options?: { project?: string; limit?: number; minSimilarity?: number }
-  ): Promise<string> {
-    const results = await this.searchRaw(query, options)
-    return this.contextBuilder.buildDecisionContext(results)
-  }
-
-  async getRecommendations(
-    currentContext: string,
-    project: string,
-    limit: number = 3
-  ): Promise<string> {
-    const results = await this.search.getRecommendations(currentContext, project, limit)
-    return this.contextBuilder.buildRecommendationContext(results)
-  }
-
-  async migrateToChromaDB(options: MigrationOptions = {}): Promise<any> {
-    if (!this.useChromaDB) {
-      throw new Error('ChromaDB is not enabled')
-    }
-
-    const migration = new ChromaMigration(
-      this.logger,
-      this.database.getDb(),
-      this.chroma.store,
-      this.chroma.collections
-    )
-
-    return migration.migrate(options)
-  }
-
-  /**
-   * Store a pattern in memory — dual-writes to FTS5 + ChromaDB/SQLite
-   */
-  async storePattern(input: {
-    project: string
-    pattern_type: 'solution' | 'anti-pattern' | 'best-practice' | 'common-issue'
-    description: string
-    example?: string
-    confidence: number
-    context?: string
-    source?: string
-  }): Promise<string> {
-    // BUG-001 fix: Generate a single shared ID for all backends
-    const sharedId = randomUUID()
-
-    // Phase 26: Dual-write to FTS5
-    let fts5Id: string | undefined
-    if (this._fts5) {
-      try {
-        fts5Id = this._fts5.store({
-          project: input.project,
-          category: 'pattern',
-          content: input.description,
-          context: input.context,
-          confidence: input.confidence,
-          source: input.source
-        }, sharedId)
-
-        // Store embedding for semantic search
-        this.storeObservationEmbedding(fts5Id, [input.description, input.context].filter(Boolean).join(' '))
-      } catch (error) {
-        this.logger.warn({ error }, 'FTS5 pattern store failed')
-      }
-    }
-
-    if (this.useChromaDB) {
-      try {
-        const chromaId = await this.chroma.store.storePattern({ ...input, id: sharedId })
-        return fts5Id || chromaId
-      } catch (error) {
-        this.logger.warn({ error }, 'ChromaDB pattern store failed')
-        if (fts5Id) return fts5Id
-      }
-    }
-
-    if (!fts5Id) {
-      return this.store.storePattern(input)
-    }
-    return fts5Id
-  }
-
-  /**
-   * Store a correction/lesson learned — dual-writes to FTS5 + ChromaDB/SQLite
-   */
-  async storeCorrection(input: {
-    project: string
-    original: string
-    correction: string
-    reasoning: string
-    context?: string
-    confidence: number
-  }): Promise<string> {
-    // BUG-001 fix: Generate a single shared ID for all backends
-    const sharedId = randomUUID()
-
-    // Phase 26: Dual-write to FTS5
-    let fts5Id: string | undefined
-    if (this._fts5) {
-      try {
-        fts5Id = this._fts5.store({
-          project: input.project,
-          category: 'correction',
-          content: input.correction,
-          reasoning: input.reasoning,
-          context: input.context,
-          confidence: input.confidence
-        }, sharedId)
-
-        // Store embedding for semantic search
-        this.storeObservationEmbedding(fts5Id, [input.correction, input.reasoning, input.context].filter(Boolean).join(' '))
-      } catch (error) {
-        this.logger.warn({ error }, 'FTS5 correction store failed')
-      }
-    }
-
-    if (this.useChromaDB) {
-      try {
-        const chromaId = await this.chroma.store.storeCorrection({ ...input, id: sharedId })
-        return fts5Id || chromaId
-      } catch (error) {
-        this.logger.warn({ error }, 'ChromaDB correction store failed')
-        if (fts5Id) return fts5Id
-      }
-    }
-
-    if (!fts5Id) {
-      return this.store.storeCorrection(input)
-    }
-    return fts5Id
-  }
-
-  /**
-   * Get patterns for a project — routes to FTS5, ChromaDB, or legacy SQLite
-   */
-  async getPatterns(
-    project?: string,
-    options?: {
-      pattern_type?: 'solution' | 'anti-pattern' | 'best-practice' | 'common-issue'
-      limit?: number
-    }
-  ): Promise<any[]> {
-    // Phase 26: Try FTS5 first (BUG-002: works with or without project)
-    if (this._fts5) {
-      const results = this._fts5.fetchAll(project, 'pattern')
-      if (results.length > 0) {
-        return results.map(r => ({
-          id: r.id,
-          description: r.content,
-          metadata: {
-            project: r.project,
-            pattern_type: r.category,
-            confidence: r.confidence,
-            context: r.context || '',
-            created_at: r.created_at
-          }
-        }))
-      }
-    }
-
-    if (this.useChromaDB) {
-      if (project) {
-        return this.chroma.store.getPatternsByProject(project, options)
-      }
-      return this.chroma.store.searchPatterns('', { limit: options?.limit || 10 })
-    }
-    if (project) {
-      return this.store.getPatternsByProject(project, options)
-    }
-    return this.store.searchPatterns('', { limit: options?.limit || 10 })
-  }
-
-  /**
-   * Get corrections for a project — routes to FTS5, ChromaDB, or legacy SQLite
-   */
-  async getCorrections(
-    project?: string,
-    options?: { limit?: number }
-  ): Promise<any[]> {
-    // Phase 26: Try FTS5 first (BUG-002: works with or without project)
-    if (this._fts5) {
-      const results = this._fts5.fetchAll(project, 'correction')
-      if (results.length > 0) {
-        return results.map(r => ({
-          id: r.id,
-          correction: r.content,
-          metadata: {
-            project: r.project,
-            reasoning: r.reasoning || '',
-            context: r.context || '',
-            confidence: r.confidence,
-            created_at: r.created_at
-          }
-        }))
-      }
-    }
-
-    if (this.useChromaDB) {
-      if (project) {
-        return this.chroma.store.getCorrectionsByProject(project, options?.limit || 10)
-      }
-      return this.chroma.store.searchCorrections('', { limit: options?.limit || 10 })
-    }
-    if (project) {
-      return this.store.getCorrectionsByProject(project, options?.limit || 10)
-    }
-    return this.store.searchCorrections('', { limit: options?.limit || 10 })
-  }
-
-  /**
-   * Fetch all decisions with content — routes to FTS5, ChromaDB, or legacy SQLite
-   * Used by analytical tools that need bulk access to decision data
-   */
-  async fetchAllDecisions(project?: string): Promise<any[]> {
-    // Phase 26: Try FTS5 first (BUG-002: works with or without project)
-    if (this._fts5) {
-      const results = this._fts5.fetchAll(project, 'decision')
-      if (results.length > 0) {
-        return results.map(r => ({
-          id: r.id,
-          content: r.content,
-          date: r.created_at,
-          project: r.project,
-          context: r.context || '',
-          decision: r.content,
-          reasoning: r.reasoning || '',
-          alternatives: '',
-          tags: r.tags
-        }))
-      }
-    }
-
-    if (this.useChromaDB) {
-      try {
-        const collection = await this.chroma.collections.getDecisions()
-        const results = await collection.get({
-          where: project ? { project } : undefined
-        })
-        if (results && results.ids) {
-          return results.ids.map((id: string, i: number) => ({
-            id,
-            content: results.documents?.[i] || '',
-            date: results.metadatas?.[i]?.created_at || new Date().toISOString(),
-            project: results.metadatas?.[i]?.project || project || 'unknown',
-            context: results.metadatas?.[i]?.context || '',
-            decision: results.metadatas?.[i]?.decision || results.documents?.[i] || '',
-            reasoning: results.metadatas?.[i]?.reasoning || '',
-            alternatives: results.metadatas?.[i]?.alternatives_considered || '',
-            tags: results.metadatas?.[i]?.tags || []
-          }))
-        }
-        return []
-      } catch (error) {
-        this.logger.warn({ error }, 'ChromaDB fetchAllDecisions failed, falling back to SQLite')
-      }
-    }
-    return this.store.getAllDecisionsWithContent(project)
-  }
-
-  /**
-   * Fetch all patterns with content — routes to FTS5, ChromaDB, or legacy SQLite
-   */
-  async fetchAllPatterns(project?: string): Promise<any[]> {
-    // Phase 26: Try FTS5 first (BUG-002: works with or without project)
-    if (this._fts5) {
-      const results = this._fts5.fetchAll(project, 'pattern')
-      if (results.length > 0) {
-        return results.map(r => ({
-          id: r.id,
-          content: r.content,
-          date: r.created_at,
-          project: r.project,
-          pattern_type: '',
-          description: r.content,
-          example: '',
-          confidence: r.confidence,
-          context: r.context || ''
-        }))
-      }
-    }
-
-    if (this.useChromaDB) {
-      try {
-        const collection = await this.chroma.collections.getPatterns()
-        const results = await collection.get({
-          where: project ? { project } : undefined
-        })
-        if (results && results.ids) {
-          return results.ids.map((id: string, i: number) => ({
-            id,
-            content: results.documents?.[i] || '',
-            date: results.metadatas?.[i]?.created_at || new Date().toISOString(),
-            project: results.metadatas?.[i]?.project || project || 'unknown',
-            pattern_type: results.metadatas?.[i]?.pattern_type || '',
-            description: results.metadatas?.[i]?.description || results.documents?.[i] || '',
-            example: results.metadatas?.[i]?.example || '',
-            confidence: results.metadatas?.[i]?.confidence || 0,
-            context: results.metadatas?.[i]?.context || ''
-          }))
-        }
-        return []
-      } catch (error) {
-        this.logger.warn({ error }, 'ChromaDB fetchAllPatterns failed, falling back to SQLite')
-      }
-    }
-    return this.store.getAllPatternsWithContent(project)
-  }
-
-  /**
-   * Fetch all corrections with content — routes to FTS5, ChromaDB, or legacy SQLite
-   */
-  async fetchAllCorrections(project?: string): Promise<any[]> {
-    // Phase 26: Try FTS5 first (BUG-002: works with or without project)
-    if (this._fts5) {
-      const results = this._fts5.fetchAll(project, 'correction')
-      if (results.length > 0) {
-        return results.map(r => ({
-          id: r.id,
-          content: r.content,
-          date: r.created_at,
-          project: r.project,
-          original: '',
-          correction: r.content,
-          reasoning: r.reasoning || '',
-          context: r.context || '',
-          confidence: r.confidence
-        }))
-      }
-    }
-
-    if (this.useChromaDB) {
-      try {
-        const collection = await this.chroma.collections.getCorrections()
-        const results = await collection.get({
-          where: project ? { project } : undefined
-        })
-        if (results && results.ids) {
-          return results.ids.map((id: string, i: number) => ({
-            id,
-            content: results.documents?.[i] || '',
-            date: results.metadatas?.[i]?.created_at || new Date().toISOString(),
-            project: results.metadatas?.[i]?.project || project || 'unknown',
-            original: results.metadatas?.[i]?.original || '',
-            correction: results.metadatas?.[i]?.correction || results.documents?.[i] || '',
-            reasoning: results.metadatas?.[i]?.reasoning || '',
-            context: results.metadatas?.[i]?.context || '',
-            confidence: results.metadatas?.[i]?.confidence || 0
-          }))
-        }
-        return []
-      } catch (error) {
-        this.logger.warn({ error }, 'ChromaDB fetchAllCorrections failed, falling back to SQLite')
-      }
-    }
-    return this.store.getAllCorrectionsWithContent(project)
-  }
-
-  /**
-   * Search patterns by query — routes to FTS5, ChromaDB, or legacy SQLite
-   */
-  async searchPatterns(
-    query: string,
-    options?: {
-      project?: string
-      pattern_type?: 'solution' | 'anti-pattern' | 'best-practice' | 'common-issue'
-      limit?: number
-      minSimilarity?: number
-    }
-  ): Promise<any[]> {
-    // Phase 26: Try FTS5 first
-    if (this._fts5 && query) {
-      const results = this._fts5.searchWithConfidence(query, options?.project, options?.limit || 10)
-      const patterns = results.filter(r => r.category === 'pattern')
-      if (patterns.length > 0) {
-        return patterns.map(r => ({
-          id: r.id,
-          content: r.content,
-          metadata: {
-            project: r.project,
-            pattern_type: '',
-            description: r.content,
-            confidence: r.confidence,
-            context: r.context || '',
-            created_at: r.created_at
-          },
-          similarity: r.score
-        }))
-      }
-    }
-
-    if (this.useChromaDB) {
-      return this.chroma.store.searchPatterns(query, options)
-    }
-    return this.store.searchPatterns(query, options)
-  }
-
-  /**
-   * Search corrections by query — routes to FTS5, ChromaDB, or legacy SQLite
-   */
-  async searchCorrections(
-    query: string,
-    options?: {
-      project?: string
-      limit?: number
-      minSimilarity?: number
-    }
-  ): Promise<any[]> {
-    // Phase 26: Try FTS5 first
-    if (this._fts5 && query) {
-      const results = this._fts5.searchWithConfidence(query, options?.project, options?.limit || 10)
-      const corrections = results.filter(r => r.category === 'correction')
-      if (corrections.length > 0) {
-        return corrections.map(r => ({
-          id: r.id,
-          content: r.content,
-          metadata: {
-            project: r.project,
-            reasoning: r.reasoning || '',
-            context: r.context || '',
-            confidence: r.confidence,
-            created_at: r.created_at
-          },
-          similarity: r.score
-        }))
-      }
-    }
-
-    if (this.useChromaDB) {
-      return this.chroma.store.searchCorrections(query, options)
-    }
-    return this.store.searchCorrections(query, options)
-  }
-
-  /**
-   * Delete a decision by ID — removes from FTS5 + embeddings + ChromaDB/SQLite
-   */
-  async deleteDecision(id: string): Promise<void> {
-    // Phase 26: Delete from FTS5 and embeddings
-    if (this._fts5) {
-      try {
-        this._fts5.delete(id)
-        this._fts5.deleteEmbedding(id)
-      } catch (error) {
-        this.logger.warn({ error, id }, 'FTS5 delete failed')
-      }
-    }
-
-    if (this.useChromaDB) {
-      await this.chroma.store.deleteDecision(id)
-    } else {
-      this.store.deleteMemory(id)
-    }
-
-    // Notify listeners (e.g., knowledge graph builder) about deletion
-    for (const cb of this.onDecisionDeletedCallbacks) {
-      try {
-        cb(id)
-      } catch {}
-    }
-  }
-
-  /**
-   * Update a decision by deleting the old one and storing a new version.
-   * Phase 20: Ensures both ChromaDB and knowledge graph are atomically updated.
-   */
-  async updateDecision(
-    oldId: string,
-    project: string,
-    context: string,
-    decision: string,
-    reasoning: string,
-    options?: { alternatives?: string; tags?: string[] }
-  ): Promise<string> {
-    // BUG-001: True in-place update using FTS5 (preserves original ID)
-    if (this._fts5) {
-      try {
-        this._fts5.update(oldId, {
-          content: decision,
-          reasoning,
-          context,
-          tags: options?.tags
-        })
-        this.logger.debug({ oldId }, 'Decision updated in-place via FTS5')
-
-        // Also update ChromaDB if available (best-effort)
-        if (this.useChromaDB) {
-          try {
-            await this.chroma.store.deleteDecision(oldId)
-            await this.chroma.store.storeDecision({
-              project,
-              context,
-              decision,
-              reasoning,
-              alternatives: options?.alternatives,
-              tags: options?.tags
-            })
-          } catch {
-            // ChromaDB sync failed, FTS5 is source of truth
-          }
-        }
-
-        return oldId // SAME ID preserved
-      } catch (error) {
-        this.logger.warn({ error, oldId }, 'FTS5 in-place update failed, falling back to delete+store')
-      }
-    }
-
-    // Fallback: delete + store (legacy behavior for non-FTS5 backends)
-    try {
-      await this.deleteDecision(oldId)
-      this.logger.debug({ oldId }, 'Old decision deleted for update')
-    } catch (error) {
-      this.logger.warn({ error, oldId }, 'Failed to delete old decision during update, storing new version anyway')
-    }
-    const newId = await this.rememberDecision(project, context, decision, reasoning, options)
-    this.logger.debug({ oldId, newId }, 'Decision updated: old deleted, new stored')
-    return newId
-  }
-}
-
-/**
- * Create a memory manager instance
- */
-export function createMemoryManager(dbPath: string, logger: Logger): MemoryManager {
-  return new MemoryManager(dbPath, logger)
-}
+/**
+ * Memory System - Main Module
+ * Phase 3: Memory and Embedding System
+ *
+ * Unified memory system manager that combines all components
+ */
+
+import { randomUUID } from 'crypto'
+import type { Logger } from 'pino'
+import { MemoryDatabase } from './database'
+import { EmbeddingService } from './embeddings'
+import { MemoryStore } from './store'
+import { SemanticSearch } from './search'
+import { MemoryContextBuilder } from './context-builder'
+import type { MemorySystemStats } from './types'
+import { ChromaManager, DEFAULT_CHROMA_CONFIG, getChromaConfigFromEnv, ChromaMigration, type MigrationOptions } from './chroma'
+import { FTS5Search } from './fts5-search'
+import { addFTS5Tables } from './migrations/add-fts5'
+import { DualWriteManager } from './dual-write'
+
+// Re-export all types and classes for external use
+export * from './types'
+export { MemoryDatabase } from './database'
+export { EmbeddingService } from './embeddings'
+export { MemoryStore } from './store'
+export { SemanticSearch } from './search'
+export { MemoryContextBuilder, type ContextOptions } from './context-builder'
+export {
+  embeddingToBuffer,
+  bufferToEmbedding,
+  normalizeEmbedding,
+  euclideanDistance,
+  cosineSimilarity,
+  dotProduct,
+  magnitude,
+  averageEmbeddings,
+  topKSimilar
+} from './embedding-utils'
+
+// Phase 12: Advanced Memory Features
+export { PatternRecognizer, type Pattern } from './patterns'
+export { LearningSystem, type Correction, type Preference, type LearningInsights } from './learning'
+export { KnowledgeExtractor, type ExtractedKnowledge, type ExtractionResult } from './knowledge-extractor'
+
+// Phase 26: FTS5 Search
+export { FTS5Search } from './fts5-search'
+export type { ObservationCategory, NewObservation, ObservationResult, ScoredResult } from './fts5-search'
+
+/**
+ * Unified memory system manager
+ * Combines database, embeddings, store, search, and context building
+ */
+export class MemoryManager {
+  readonly database: MemoryDatabase
+  readonly embeddings: EmbeddingService
+  readonly contextBuilder: MemoryContextBuilder
+  readonly chroma: ChromaManager
+
+  // Phase 26: FTS5 search (always available, no external deps)
+  private _fts5: FTS5Search | null = null
+
+  // Store and search are initialized after database is ready
+  private _store: MemoryStore | null = null
+  private _search: SemanticSearch | null = null
+
+  private logger: Logger
+  private initialized: boolean = false
+  private useChromaDB: boolean = true
+  private onDecisionStoredCallbacks: ((input: Record<string, unknown>) => void)[] = []
+  private onDecisionDeletedCallbacks: ((id: string) => void)[] = []
+
+  // Task 3.5: Extracted dual-write logic
+  private dualWrite: DualWriteManager
+
+  constructor(
+    dbPath: string,
+    logger: Logger,
+    useChromaDB: boolean = true,
+    chromaConfig?: Record<string, unknown>,
+    customEmbeddings?: EmbeddingService
+  ) {
+    this.logger = logger.child({ component: 'memory-manager' })
+    this.useChromaDB = useChromaDB
+
+    this.database = new MemoryDatabase(dbPath, logger)
+    this.embeddings = customEmbeddings || new EmbeddingService(logger)
+    this.contextBuilder = new MemoryContextBuilder(logger)
+
+    const envConfig = getChromaConfigFromEnv()
+    const config = { ...DEFAULT_CHROMA_CONFIG, ...envConfig, ...chromaConfig }
+    this.chroma = new ChromaManager(logger, config)
+
+    this.dualWrite = new DualWriteManager(
+      this.logger,
+      () => this._fts5,
+      () => ({ manager: this.chroma, enabled: this.useChromaDB }),
+      () => this.embeddings
+    )
+  }
+
+  /**
+   * Initialize memory system
+   * Must be called before using store or search
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) {
+      this.logger.warn('Memory system already initialized')
+      return
+    }
+
+    try {
+      this.logger.info('Initializing memory system...')
+
+      await this.database.initialize()
+
+      await this.embeddings.initialize()
+
+      const db = this.database.getDb()
+      this._store = new MemoryStore(db, this.embeddings, this.logger)
+      this._search = new SemanticSearch(db, this.embeddings, this.logger)
+
+      // Phase 26: Always initialize FTS5 (just SQLite, no external deps)
+      try {
+        addFTS5Tables(db)
+        this._fts5 = new FTS5Search(db, this.logger)
+        this.logger.info('FTS5 search initialized')
+
+        // Phase 26b: Backfill embeddings for existing observations (async, non-blocking)
+        if (this.embeddings.isReady()) {
+          this.backfillEmbeddings().then(count => {
+            if (count > 0) {
+              this.logger.info({ count }, 'Backfilled embeddings for existing observations')
+            }
+          }).catch((error) => {
+            this.logger.warn({ error }, 'Background embedding backfill failed')
+          })
+        }
+      } catch (error) {
+        this.logger.warn({ error }, 'Failed to initialize FTS5, continuing without it')
+      }
+
+      if (this.useChromaDB) {
+        try {
+          await this.chroma.initialize()
+          this.logger.info('ChromaDB backend initialized successfully')
+        } catch (error) {
+          this.logger.warn({ error }, 'Failed to initialize ChromaDB, falling back to SQLite backend')
+          this.useChromaDB = false
+        }
+      }
+
+      this.initialized = true
+      this.logger.info('Memory system initialized successfully')
+    } catch (error) {
+      this.logger.error({ error }, 'Failed to initialize memory system')
+      throw error
+    }
+  }
+
+  /**
+   * Get the memory store (throws if not initialized)
+   */
+  get store(): MemoryStore {
+    if (!this._store) {
+      throw new Error('Memory system not initialized. Call initialize() first.')
+    }
+    return this._store
+  }
+
+  /**
+   * Get the semantic search engine (throws if not initialized)
+   */
+  get search(): SemanticSearch {
+    if (!this._search) {
+      throw new Error('Memory system not initialized. Call initialize() first.')
+    }
+    return this._search
+  }
+
+  /**
+   * Get the FTS5 search engine (null if not initialized)
+   */
+  get fts5(): FTS5Search | null {
+    return this._fts5
+  }
+
+  /**
+   * Check if memory system is initialized
+   */
+  isInitialized(): boolean {
+    return this.initialized
+  }
+
+  /**
+   * Backfill embeddings for existing observations that don't have them.
+   * Call this after initialization to migrate existing data.
+   */
+  async backfillEmbeddings(batchSize: number = 50): Promise<number> {
+    if (!this._fts5 || !this.embeddings.isReady()) return 0
+    return this._fts5.backfillEmbeddings(this.embeddings, batchSize)
+  }
+
+  close(): void {
+    if (this.useChromaDB) {
+      this.chroma.close()
+    }
+    this.database.close()
+    this._store = null
+    this._search = null
+    this.initialized = false
+    this.logger.info('Memory system closed')
+  }
+
+  /**
+   * Get system statistics
+   */
+  getStats(): MemorySystemStats {
+    if (!this.initialized) {
+      throw new Error('Memory system not initialized')
+    }
+
+    return {
+      database: this.database.getStats(),
+      embeddings: this.embeddings.getCacheStats()
+    }
+  }
+
+  /**
+   * Health check
+   */
+  async healthCheck(): Promise<boolean> {
+    if (!this.initialized) {
+      return false
+    }
+    return this.database.healthCheck()
+  }
+
+  /**
+   * Check if ChromaDB backend is enabled and connected
+   */
+  isChromaDBEnabled(): boolean {
+    return this.useChromaDB
+  }
+
+  /**
+   * Add a listener that fires when a decision is stored (from any backend)
+   */
+  addDecisionStoredListener(callback: (input: Record<string, unknown>) => void): () => void {
+    this.onDecisionStoredCallbacks.push(callback)
+    let chromaUnsub: (() => void) | undefined
+    if (this.useChromaDB) {
+      chromaUnsub = this.chroma.store.addDecisionStoredListener(callback)
+    }
+    return () => {
+      const idx = this.onDecisionStoredCallbacks.indexOf(callback)
+      if (idx >= 0) this.onDecisionStoredCallbacks.splice(idx, 1)
+      chromaUnsub?.()
+    }
+  }
+
+  /**
+   * Add a listener that fires when a decision is deleted
+   */
+  addDecisionDeletedListener(callback: (id: string) => void): () => void {
+    this.onDecisionDeletedCallbacks.push(callback)
+    return () => {
+      const idx = this.onDecisionDeletedCallbacks.indexOf(callback)
+      if (idx >= 0) this.onDecisionDeletedCallbacks.splice(idx, 1)
+    }
+  }
+
+  async rememberDecision(
+    project: string,
+    context: string,
+    decision: string,
+    reasoning: string,
+    options?: { alternatives?: string; tags?: string[] }
+  ): Promise<string> {
+    const sharedId = randomUUID()
+
+    // rememberDecision has a special duplicate check before the standard dual-write
+    if (this._fts5) {
+      const dup = this._fts5.searchForDuplicates(decision, project)
+      if (dup) {
+        this.logger.info({ existingId: dup.id, score: dup.score }, 'FTS5 skipping duplicate decision')
+        return dup.id
+      }
+    }
+
+    const id = await this.dualWrite.store({
+      sharedId,
+      fts5Fn: (fts5, id) => fts5.store({
+        project,
+        category: 'decision',
+        content: decision,
+        reasoning,
+        context,
+        tags: options?.tags
+      }, id),
+      chromaFn: async (chroma, id) => chroma.store.storeDecision({
+        id,
+        project,
+        context,
+        decision,
+        reasoning,
+        alternatives: options?.alternatives,
+        tags: options?.tags
+      }),
+      sqliteFn: () => this.store.storeDecision({
+        project,
+        context,
+        decision,
+        reasoning,
+        alternatives: options?.alternatives,
+        tags: options?.tags
+      }),
+      embeddingText: [decision, reasoning, context].filter(Boolean).join(' ')
+    })
+
+    // Notify listeners (e.g., knowledge graph builder)
+    for (const cb of this.onDecisionStoredCallbacks) {
+      try {
+        cb({ project, context, decision, reasoning, alternatives: options?.alternatives, tags: options?.tags, id })
+      } catch {}
+    }
+    return id
+  }
+
+  /**
+   * Get raw search results - uses FTS5 as primary, embeddings as semantic fallback
+   * Use this for internal operations that need raw results
+   */
+  async searchRaw(
+    query: string,
+    options?: { project?: string; limit?: number; minSimilarity?: number }
+  ): Promise<Record<string, unknown>[]> {
+    const limit = options?.limit || 5
+    const LOW_CONFIDENCE_THRESHOLD = 0.25
+
+    // Phase 26: Try FTS5 first (always available)
+    if (this._fts5) {
+      const ftsResults = this._fts5.searchWithConfidence(query, options?.project, limit)
+
+      // Check if FTS5 returned good results
+      const hasGoodResults = ftsResults.length > 0 &&
+        ftsResults.some(r => r.score >= LOW_CONFIDENCE_THRESHOLD)
+
+      if (hasGoodResults) {
+        return this.transformFtsResults(ftsResults)
+      }
+
+      // Phase 26b: FTS5 returned nothing or low-confidence — try semantic search
+      if (this.embeddings.isReady() && this._fts5.hasEmbeddings()) {
+        try {
+          const queryEmbedding = await this.embeddings.generateEmbedding(query)
+          const semanticResults = await this._fts5.semanticSearch(
+            queryEmbedding,
+            options?.project,
+            limit,
+            options?.minSimilarity || 0.3
+          )
+
+          if (semanticResults.length > 0) {
+            this.logger.debug(
+              { query, ftsCount: ftsResults.length, semanticCount: semanticResults.length },
+              'Semantic search found results where FTS5 did not'
+            )
+
+            // If we had some low-confidence FTS5 results, merge with semantic results
+            if (ftsResults.length > 0) {
+              return this.mergeSearchResults(ftsResults, semanticResults, limit)
+            }
+
+            return this.transformFtsResults(semanticResults)
+          }
+        } catch (error) {
+          this.logger.warn({ error }, 'Semantic search fallback failed')
+        }
+      }
+
+      // Return whatever FTS5 found (even if low confidence)
+      if (ftsResults.length > 0) {
+        return this.transformFtsResults(ftsResults)
+      }
+    }
+
+    // Fallback: Try ChromaDB if available
+    if (this.useChromaDB) {
+      const chromaResults = await this.chroma.search.searchDecisions(query, {
+        project: options?.project,
+        limit,
+        minSimilarity: options?.minSimilarity || 0.3
+      })
+      return chromaResults.map(r => {
+        const memoryContent = typeof r.content === 'string' ? r.content : JSON.stringify(r.content)
+        const decisionObj = r.metadata.decision ? {
+          id: r.id,
+          project: r.metadata.project || options?.project || 'unknown',
+          context: r.metadata.context || '',
+          decision: r.metadata.decision || memoryContent,
+          reasoning: r.metadata.reasoning || '',
+          alternatives: r.metadata.alternatives_considered || '',
+          tags: r.metadata.tags || [],
+          outcome: r.metadata.outcome,
+          createdAt: r.metadata.created_at ? new Date(r.metadata.created_at) : new Date()
+        } : undefined
+
+        return {
+          id: r.id,
+          content: decisionObj ? decisionObj.decision : memoryContent,
+          memory: {
+            id: r.id,
+            project: r.metadata.project || options?.project || 'unknown',
+            content: memoryContent,
+            createdAt: r.metadata.created_at ? new Date(r.metadata.created_at) : new Date(),
+            metadata: r.metadata
+          },
+          similarity: r.similarity,
+          decision: decisionObj,
+          metadata: r.metadata
+        }
+      })
+    }
+
+    // Final fallback: legacy SQLite search
+    return await this.search.search(query, {
+      project: options?.project,
+      limit,
+      minSimilarity: options?.minSimilarity || 0.3
+    })
+  }
+
+  /**
+   * Transform FTS5/semantic ScoredResults to the expected MemorySearchResult structure
+   */
+  private transformFtsResults(results: import('./fts5-search').ScoredResult[]): Record<string, unknown>[] {
+    return results.map(r => ({
+      id: r.id,
+      content: r.content,
+      memory: {
+        id: r.id,
+        project: r.project,
+        content: r.content,
+        createdAt: new Date(r.created_at),
+        metadata: {
+          project: r.project,
+          category: r.category,
+          context: r.context || '',
+          reasoning: r.reasoning || '',
+          tags: r.tags,
+          created_at: r.created_at
+        }
+      },
+      similarity: r.score,
+      decision: r.category === 'decision' ? {
+        id: r.id,
+        project: r.project,
+        context: r.context || '',
+        decision: r.content,
+        reasoning: r.reasoning || '',
+        alternatives: '',
+        tags: r.tags,
+        createdAt: new Date(r.created_at)
+      } : undefined,
+      metadata: {
+        project: r.project,
+        category: r.category,
+        context: r.context || '',
+        reasoning: r.reasoning || '',
+        tags: r.tags,
+        created_at: r.created_at
+      }
+    }))
+  }
+
+  /**
+   * Merge FTS5 and semantic search results, deduplicating by ID.
+   * Semantic results get a small boost since they matched conceptually.
+   */
+  private mergeSearchResults(
+    ftsResults: import('./fts5-search').ScoredResult[],
+    semanticResults: import('./fts5-search').ScoredResult[],
+    limit: number
+  ): Record<string, unknown>[] {
+    const seen = new Set<string>()
+    const merged: import('./fts5-search').ScoredResult[] = []
+
+    // Add semantic results first (they matched conceptually when FTS5 didn't)
+    for (const r of semanticResults) {
+      if (!seen.has(r.id)) {
+        seen.add(r.id)
+        merged.push(r)
+      }
+    }
+
+    // Then add FTS5 results that aren't already included
+    for (const r of ftsResults) {
+      if (!seen.has(r.id)) {
+        seen.add(r.id)
+        merged.push(r)
+      }
+    }
+
+    // Sort by score descending and limit
+    merged.sort((a, b) => b.score - a.score)
+    return this.transformFtsResults(merged.slice(0, limit))
+  }
+
+  async recallSimilar(
+    query: string,
+    options?: { project?: string; limit?: number; minSimilarity?: number }
+  ): Promise<string> {
+    const results = await this.searchRaw(query, options)
+    return this.contextBuilder.buildDecisionContext(results)
+  }
+
+  async getRecommendations(
+    currentContext: string,
+    project: string,
+    limit: number = 3
+  ): Promise<string> {
+    const results = await this.search.getRecommendations(currentContext, project, limit)
+    return this.contextBuilder.buildRecommendationContext(results)
+  }
+
+  async migrateToChromaDB(options: MigrationOptions = {}): Promise<unknown> {
+    if (!this.useChromaDB) {
+      throw new Error('ChromaDB is not enabled')
+    }
+
+    const migration = new ChromaMigration(
+      this.logger,
+      this.database.getDb(),
+      this.chroma.store,
+      this.chroma.collections
+    )
+
+    return migration.migrate(options)
+  }
+
+  /**
+   * Store a pattern in memory — dual-writes to FTS5 + ChromaDB/SQLite
+   */
+  async storePattern(input: {
+    project: string
+    pattern_type: 'solution' | 'anti-pattern' | 'best-practice' | 'common-issue'
+    description: string
+    example?: string
+    confidence: number
+    context?: string
+    source?: string
+  }): Promise<string> {
+    const sharedId = randomUUID()
+
+    return this.dualWrite.store({
+      sharedId,
+      fts5Fn: (fts5, id) => fts5.store({
+        project: input.project,
+        category: 'pattern',
+        content: input.description,
+        context: input.context,
+        confidence: input.confidence,
+        source: input.source
+      }, id),
+      chromaFn: async (chroma, id) => chroma.store.storePattern({ ...input, id }),
+      sqliteFn: () => this.store.storePattern(input),
+      embeddingText: [input.description, input.context].filter(Boolean).join(' ')
+    })
+  }
+
+  /**
+   * Store a correction/lesson learned — dual-writes to FTS5 + ChromaDB/SQLite
+   */
+  async storeCorrection(input: {
+    project: string
+    original: string
+    correction: string
+    reasoning: string
+    context?: string
+    confidence: number
+  }): Promise<string> {
+    const sharedId = randomUUID()
+
+    return this.dualWrite.store({
+      sharedId,
+      fts5Fn: (fts5, id) => fts5.store({
+        project: input.project,
+        category: 'correction',
+        content: input.correction,
+        reasoning: input.reasoning,
+        context: input.context,
+        confidence: input.confidence
+      }, id),
+      chromaFn: async (chroma, id) => chroma.store.storeCorrection({ ...input, id }),
+      sqliteFn: () => this.store.storeCorrection(input),
+      embeddingText: [input.correction, input.reasoning, input.context].filter(Boolean).join(' ')
+    })
+  }
+
+  /**
+   * Get patterns for a project — routes to FTS5, ChromaDB, or legacy SQLite
+   */
+  async getPatterns(
+    project?: string,
+    options?: {
+      pattern_type?: 'solution' | 'anti-pattern' | 'best-practice' | 'common-issue'
+      limit?: number
+    }
+  ): Promise<Record<string, unknown>[]> {
+    return this.dualWrite.fetch({
+      fts5Fn: (fts5) => fts5.fetchAll(project, 'pattern').map(r => ({
+        id: r.id,
+        description: r.content,
+        metadata: {
+          project: r.project,
+          pattern_type: r.category,
+          confidence: r.confidence,
+          context: r.context || '',
+          created_at: r.created_at
+        }
+      })),
+      chromaFn: async (chroma) => {
+        if (project) {
+          return chroma.store.getPatternsByProject(project, options)
+        }
+        return chroma.store.searchPatterns('', { limit: options?.limit || 10 })
+      },
+      sqliteFn: () => {
+        if (project) {
+          return this.store.getPatternsByProject(project, options)
+        }
+        return this.store.searchPatterns('', { limit: options?.limit || 10 })
+      }
+    })
+  }
+
+  /**
+   * Get corrections for a project — routes to FTS5, ChromaDB, or legacy SQLite
+   */
+  async getCorrections(
+    project?: string,
+    options?: { limit?: number }
+  ): Promise<Record<string, unknown>[]> {
+    return this.dualWrite.fetch({
+      fts5Fn: (fts5) => fts5.fetchAll(project, 'correction').map(r => ({
+        id: r.id,
+        correction: r.content,
+        metadata: {
+          project: r.project,
+          reasoning: r.reasoning || '',
+          context: r.context || '',
+          confidence: r.confidence,
+          created_at: r.created_at
+        }
+      })),
+      chromaFn: async (chroma) => {
+        if (project) {
+          return chroma.store.getCorrectionsByProject(project, options?.limit || 10)
+        }
+        return chroma.store.searchCorrections('', { limit: options?.limit || 10 })
+      },
+      sqliteFn: () => {
+        if (project) {
+          return this.store.getCorrectionsByProject(project, options?.limit || 10)
+        }
+        return this.store.searchCorrections('', { limit: options?.limit || 10 })
+      }
+    })
+  }
+
+  /**
+   * Fetch all decisions with content — routes to FTS5, ChromaDB, or legacy SQLite
+   * Used by analytical tools that need bulk access to decision data
+   */
+  async fetchAllDecisions(project?: string): Promise<Record<string, unknown>[]> {
+    return this.dualWrite.fetch({
+      fts5Fn: (fts5) => fts5.fetchAll(project, 'decision').map(r => ({
+        id: r.id,
+        content: r.content,
+        date: r.created_at,
+        project: r.project,
+        context: r.context || '',
+        decision: r.content,
+        reasoning: r.reasoning || '',
+        alternatives: '',
+        tags: r.tags
+      })),
+      chromaFn: async (chroma) => {
+        const collection = await chroma.collections.getDecisions()
+        const results = await collection.get({
+          where: project ? { project } : undefined
+        })
+        if (results && results.ids) {
+          return results.ids.map((id: string, i: number) => ({
+            id,
+            content: results.documents?.[i] || '',
+            date: results.metadatas?.[i]?.created_at || new Date().toISOString(),
+            project: results.metadatas?.[i]?.project || project || 'unknown',
+            context: results.metadatas?.[i]?.context || '',
+            decision: results.metadatas?.[i]?.decision || results.documents?.[i] || '',
+            reasoning: results.metadatas?.[i]?.reasoning || '',
+            alternatives: results.metadatas?.[i]?.alternatives_considered || '',
+            tags: results.metadatas?.[i]?.tags || []
+          }))
+        }
+        return []
+      },
+      sqliteFn: () => this.store.getAllDecisionsWithContent(project)
+    })
+  }
+
+  /**
+   * Fetch all patterns with content — routes to FTS5, ChromaDB, or legacy SQLite
+   */
+  async fetchAllPatterns(project?: string): Promise<Record<string, unknown>[]> {
+    return this.dualWrite.fetch({
+      fts5Fn: (fts5) => fts5.fetchAll(project, 'pattern').map(r => ({
+        id: r.id,
+        content: r.content,
+        date: r.created_at,
+        project: r.project,
+        pattern_type: '',
+        description: r.content,
+        example: '',
+        confidence: r.confidence,
+        context: r.context || ''
+      })),
+      chromaFn: async (chroma) => {
+        const collection = await chroma.collections.getPatterns()
+        const results = await collection.get({
+          where: project ? { project } : undefined
+        })
+        if (results && results.ids) {
+          return results.ids.map((id: string, i: number) => ({
+            id,
+            content: results.documents?.[i] || '',
+            date: results.metadatas?.[i]?.created_at || new Date().toISOString(),
+            project: results.metadatas?.[i]?.project || project || 'unknown',
+            pattern_type: results.metadatas?.[i]?.pattern_type || '',
+            description: results.metadatas?.[i]?.description || results.documents?.[i] || '',
+            example: results.metadatas?.[i]?.example || '',
+            confidence: results.metadatas?.[i]?.confidence || 0,
+            context: results.metadatas?.[i]?.context || ''
+          }))
+        }
+        return []
+      },
+      sqliteFn: () => this.store.getAllPatternsWithContent(project)
+    })
+  }
+
+  /**
+   * Fetch all corrections with content — routes to FTS5, ChromaDB, or legacy SQLite
+   */
+  async fetchAllCorrections(project?: string): Promise<Record<string, unknown>[]> {
+    return this.dualWrite.fetch({
+      fts5Fn: (fts5) => fts5.fetchAll(project, 'correction').map(r => ({
+        id: r.id,
+        content: r.content,
+        date: r.created_at,
+        project: r.project,
+        original: '',
+        correction: r.content,
+        reasoning: r.reasoning || '',
+        context: r.context || '',
+        confidence: r.confidence
+      })),
+      chromaFn: async (chroma) => {
+        const collection = await chroma.collections.getCorrections()
+        const results = await collection.get({
+          where: project ? { project } : undefined
+        })
+        if (results && results.ids) {
+          return results.ids.map((id: string, i: number) => ({
+            id,
+            content: results.documents?.[i] || '',
+            date: results.metadatas?.[i]?.created_at || new Date().toISOString(),
+            project: results.metadatas?.[i]?.project || project || 'unknown',
+            original: results.metadatas?.[i]?.original || '',
+            correction: results.metadatas?.[i]?.correction || results.documents?.[i] || '',
+            reasoning: results.metadatas?.[i]?.reasoning || '',
+            context: results.metadatas?.[i]?.context || '',
+            confidence: results.metadatas?.[i]?.confidence || 0
+          }))
+        }
+        return []
+      },
+      sqliteFn: () => this.store.getAllCorrectionsWithContent(project)
+    })
+  }
+
+  /**
+   * Search patterns by query — routes to FTS5, ChromaDB, or legacy SQLite
+   */
+  async searchPatterns(
+    query: string,
+    options?: {
+      project?: string
+      pattern_type?: 'solution' | 'anti-pattern' | 'best-practice' | 'common-issue'
+      limit?: number
+      minSimilarity?: number
+    }
+  ): Promise<Record<string, unknown>[]> {
+    return this.dualWrite.fetch({
+      fts5Fn: query ? (fts5) => {
+        const results = fts5.searchWithConfidence(query, options?.project, options?.limit || 10)
+        return results.filter(r => r.category === 'pattern').map(r => ({
+          id: r.id,
+          content: r.content,
+          metadata: {
+            project: r.project,
+            pattern_type: '',
+            description: r.content,
+            confidence: r.confidence,
+            context: r.context || '',
+            created_at: r.created_at
+          },
+          similarity: r.score
+        }))
+      } : undefined,
+      chromaFn: async (chroma) => chroma.store.searchPatterns(query, options),
+      sqliteFn: () => this.store.searchPatterns(query, options)
+    })
+  }
+
+  /**
+   * Search corrections by query — routes to FTS5, ChromaDB, or legacy SQLite
+   */
+  async searchCorrections(
+    query: string,
+    options?: {
+      project?: string
+      limit?: number
+      minSimilarity?: number
+    }
+  ): Promise<Record<string, unknown>[]> {
+    return this.dualWrite.fetch({
+      fts5Fn: query ? (fts5) => {
+        const results = fts5.searchWithConfidence(query, options?.project, options?.limit || 10)
+        return results.filter(r => r.category === 'correction').map(r => ({
+          id: r.id,
+          content: r.content,
+          metadata: {
+            project: r.project,
+            reasoning: r.reasoning || '',
+            context: r.context || '',
+            confidence: r.confidence,
+            created_at: r.created_at
+          },
+          similarity: r.score
+        }))
+      } : undefined,
+      chromaFn: async (chroma) => chroma.store.searchCorrections(query, options),
+      sqliteFn: () => this.store.searchCorrections(query, options)
+    })
+  }
+
+  /**
+   * Delete a decision by ID — removes from FTS5 + embeddings + ChromaDB/SQLite
+   */
+  async deleteDecision(id: string): Promise<void> {
+    await this.dualWrite.delete(id, {
+      fts5Fn: (fts5) => {
+        fts5.delete(id)
+        fts5.deleteEmbedding(id)
+      },
+      chromaFn: async (chroma) => chroma.store.deleteDecision(id),
+      sqliteFn: () => this.store.deleteMemory(id)
+    })
+
+    // Notify listeners (e.g., knowledge graph builder) about deletion
+    for (const cb of this.onDecisionDeletedCallbacks) {
+      try {
+        cb(id)
+      } catch {}
+    }
+  }
+
+  /**
+   * Update a decision by deleting the old one and storing a new version.
+   * Phase 20: Ensures both ChromaDB and knowledge graph are atomically updated.
+   */
+  async updateDecision(
+    oldId: string,
+    project: string,
+    context: string,
+    decision: string,
+    reasoning: string,
+    options?: { alternatives?: string; tags?: string[] }
+  ): Promise<string> {
+    // BUG-001: True in-place update using FTS5 (preserves original ID)
+    if (this._fts5) {
+      try {
+        this._fts5.update(oldId, {
+          content: decision,
+          reasoning,
+          context,
+          tags: options?.tags
+        })
+        this.logger.debug({ oldId }, 'Decision updated in-place via FTS5')
+
+        // Also update ChromaDB if available (best-effort)
+        if (this.useChromaDB) {
+          try {
+            await this.chroma.store.deleteDecision(oldId)
+            await this.chroma.store.storeDecision({
+              project,
+              context,
+              decision,
+              reasoning,
+              alternatives: options?.alternatives,
+              tags: options?.tags
+            })
+          } catch {
+            // ChromaDB sync failed, FTS5 is source of truth
+          }
+        }
+
+        return oldId // SAME ID preserved
+      } catch (error) {
+        this.logger.warn({ error, oldId }, 'FTS5 in-place update failed, falling back to delete+store')
+      }
+    }
+
+    // Fallback: delete + store (legacy behavior for non-FTS5 backends)
+    try {
+      await this.deleteDecision(oldId)
+      this.logger.debug({ oldId }, 'Old decision deleted for update')
+    } catch (error) {
+      this.logger.warn({ error, oldId }, 'Failed to delete old decision during update, storing new version anyway')
+    }
+    const newId = await this.rememberDecision(project, context, decision, reasoning, options)
+    this.logger.debug({ oldId, newId }, 'Decision updated: old deleted, new stored')
+    return newId
+  }
+}
+
+/**
+ * Create a memory manager instance
+ */
+export function createMemoryManager(dbPath: string, logger: Logger): MemoryManager {
+  return new MemoryManager(dbPath, logger)
+}