specmem-hardwicksoftware 3.5.99

package/dist/memory/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/memory/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,gCAAgC;AAChC,OAAO,EACL,qBAAqB,EAKtB,MAAM,sBAAsB,CAAC;AAE9B,+BAA+B;AAC/B,OAAO,EACL,oBAAoB,EAIrB,MAAM,qBAAqB,CAAC;AAE7B,sBAAsB;AACtB,OAAO,EACL,2BAA2B,EAC3B,8BAA8B,EAC9B,6BAA6B,EAC9B,MAAM,+BAA+B,CAAC"}

package/dist/memory/memoryEvolutionMigration.d.ts

@@ -0,0 +1,36 @@
+/**
+ * memoryEvolutionMigration.ts - Database migrations for human-like memory evolution
+ *
+ * This file contains the SQL migrations needed to support:
+ * 1. Memory strength tracking (forgetting curves)
+ * 2. Associative links between memories
+ * 3. Memory chains for reasoning paths
+ * 4. Quadrant-based spatial partitioning
+ *
+ * Run these migrations after the core SpecMem migrations.
+ *
+ * EMBEDDING DIMENSION NOTE:
+ * DEPRECATED: SPECMEM_EMBEDDING_DIMENSIONS is no longer used.
+ * Embedding dimensions are AUTO-DETECTED from the database pgvector column.
+ * The database pg_attribute table is the single source of truth for dimensions.
+ * The system auto-migrates when dimension mismatch is detected at startup.
+ *
+ * NO HARDCODED DIMENSIONS - runtime uses pg_attribute for actual dimension
+ */
+export declare const MEMORY_EVOLUTION_MIGRATIONS: {
+    version: number;
+    name: string;
+    up: string;
+    down: string;
+    checksum: string;
+};
+/**
+ * Get the SQL to run this migration
+ */
+export declare function getMemoryEvolutionMigrationSQL(): string;
+/**
+ * Get the SQL to rollback this migration
+ */
+export declare function getMemoryEvolutionRollbackSQL(): string;
+export default MEMORY_EVOLUTION_MIGRATIONS;
+//# sourceMappingURL=memoryEvolutionMigration.d.ts.map

package/dist/memory/memoryEvolutionMigration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryEvolutionMigration.d.ts","sourceRoot":"","sources":["../../src/memory/memoryEvolutionMigration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,eAAO,MAAM,2BAA2B;;;;;;CAoVvC,CAAC;AAEF;;GAEG;AACH,wBAAgB,8BAA8B,IAAI,MAAM,CAEvD;AAED;;GAEG;AACH,wBAAgB,6BAA6B,IAAI,MAAM,CAEtD;AAED,eAAe,2BAA2B,CAAC"}

package/dist/memory/memoryEvolutionMigration.js

@@ -0,0 +1,371 @@
+/**
+ * memoryEvolutionMigration.ts - Database migrations for human-like memory evolution
+ *
+ * This file contains the SQL migrations needed to support:
+ * 1. Memory strength tracking (forgetting curves)
+ * 2. Associative links between memories
+ * 3. Memory chains for reasoning paths
+ * 4. Quadrant-based spatial partitioning
+ *
+ * Run these migrations after the core SpecMem migrations.
+ *
+ * EMBEDDING DIMENSION NOTE:
+ * DEPRECATED: SPECMEM_EMBEDDING_DIMENSIONS is no longer used.
+ * Embedding dimensions are AUTO-DETECTED from the database pgvector column.
+ * The database pg_attribute table is the single source of truth for dimensions.
+ * The system auto-migrates when dimension mismatch is detected at startup.
+ *
+ * NO HARDCODED DIMENSIONS - runtime uses pg_attribute for actual dimension
+ */
+export const MEMORY_EVOLUTION_MIGRATIONS = {
+    version: 26,
+    name: 'create_memory_evolution_tables',
+    up: `
+    -- =====================================================
+    -- MIGRATION 26: HUMAN-LIKE MEMORY EVOLUTION SYSTEM
+    -- =====================================================
+    -- This migration adds support for:
+    -- 1. Memory strength tracking (Ebbinghaus forgetting curves)
+    -- 2. Associative memory links (spreading activation)
+    -- 3. Memory chains (reasoning paths)
+    -- 4. Quadrant-based semantic partitioning
+
+    -- =====================================================
+    -- TABLE: memory_strength
+    -- Tracks forgetting curve parameters for each memory
+    -- =====================================================
+    CREATE TABLE IF NOT EXISTS memory_strength (
+      memory_id UUID PRIMARY KEY REFERENCES memories(id) ON DELETE CASCADE,
+
+      -- Forgetting curve parameters
+      stability FLOAT NOT NULL DEFAULT 10.0,        -- Resistance to forgetting (1-100)
+      retrievability FLOAT NOT NULL DEFAULT 1.0,    -- Current recall probability (0-1)
+      ease_factor FLOAT NOT NULL DEFAULT 2.0,       -- How easy to recall (1.3-2.5, SM-2 algorithm)
+
+      -- Review tracking
+      last_review TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+      review_count INTEGER NOT NULL DEFAULT 1,
+      interval_days FLOAT NOT NULL DEFAULT 1.0,     -- Days until next optimal review
+
+      -- Timestamps
+      created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+      updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+      -- Constraints
+      CONSTRAINT valid_stability CHECK (stability >= 1 AND stability <= 100),
+      CONSTRAINT valid_retrievability CHECK (retrievability >= 0 AND retrievability <= 1),
+      CONSTRAINT valid_ease_factor CHECK (ease_factor >= 1.0 AND ease_factor <= 3.0)
+    );
+
+    -- Index for finding memories due for review
+    CREATE INDEX IF NOT EXISTS idx_memory_strength_retrievability
+      ON memory_strength(retrievability);
+    CREATE INDEX IF NOT EXISTS idx_memory_strength_last_review
+      ON memory_strength(last_review);
+
+    -- Trigger to update updated_at
+    DROP TRIGGER IF EXISTS memory_strength_updated_at ON memory_strength;
+    CREATE TRIGGER memory_strength_updated_at
+      BEFORE UPDATE ON memory_strength
+      FOR EACH ROW
+      EXECUTE FUNCTION update_updated_at_column();
+
+    -- =====================================================
+    -- TABLE: memory_associations
+    -- Stores bidirectional associative links between memories
+    -- =====================================================
+    CREATE TABLE IF NOT EXISTS memory_associations (
+      id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+      source_id UUID NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+      target_id UUID NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+
+      -- Link properties
+      link_type VARCHAR(50) NOT NULL DEFAULT 'contextual',
+      strength FLOAT NOT NULL DEFAULT 0.3,          -- 0-1, how strong the association
+      decay_rate FLOAT NOT NULL DEFAULT 0.1,        -- How fast this link weakens
+
+      -- Co-activation tracking
+      co_activation_count INTEGER NOT NULL DEFAULT 1,
+      last_co_activation TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+      -- Timestamps
+      created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+      updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+      -- Constraints
+      CONSTRAINT unique_association UNIQUE (source_id, target_id),
+      CONSTRAINT no_self_association CHECK (source_id != target_id),
+      CONSTRAINT valid_strength CHECK (strength >= 0 AND strength <= 1),
+      CONSTRAINT valid_decay_rate CHECK (decay_rate >= 0 AND decay_rate <= 1),
+      CONSTRAINT valid_link_type CHECK (
+        link_type IN ('semantic', 'temporal', 'causal', 'contextual', 'user_defined')
+      )
+    );
+
+    -- Indexes for association lookups
+    CREATE INDEX IF NOT EXISTS idx_memory_associations_source
+      ON memory_associations(source_id);
+    CREATE INDEX IF NOT EXISTS idx_memory_associations_target
+      ON memory_associations(target_id);
+    CREATE INDEX IF NOT EXISTS idx_memory_associations_strength
+      ON memory_associations(strength DESC);
+    CREATE INDEX IF NOT EXISTS idx_memory_associations_type
+      ON memory_associations(link_type);
+    CREATE INDEX IF NOT EXISTS idx_memory_associations_last_activation
+      ON memory_associations(last_co_activation);
+
+    -- Trigger for updated_at
+    DROP TRIGGER IF EXISTS memory_associations_updated_at ON memory_associations;
+    CREATE TRIGGER memory_associations_updated_at
+      BEFORE UPDATE ON memory_associations
+      FOR EACH ROW
+      EXECUTE FUNCTION update_updated_at_column();
+
+    -- =====================================================
+    -- TABLE: memory_chains
+    -- Stores sequential reasoning paths through memories
+    -- =====================================================
+    CREATE TABLE IF NOT EXISTS memory_chains (
+      id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+
+      -- Chain identification
+      name VARCHAR(255) NOT NULL,
+      description TEXT,
+      chain_type VARCHAR(50) NOT NULL DEFAULT 'reasoning',
+      importance importance_level NOT NULL DEFAULT 'medium',
+
+      -- Chain contents (ordered array of memory IDs)
+      memory_ids UUID[] NOT NULL DEFAULT '{}',
+
+      -- Usage tracking
+      access_count INTEGER NOT NULL DEFAULT 1,
+      last_accessed_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+      -- Timestamps
+      created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+      updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+      -- Flexible metadata
+      metadata JSONB NOT NULL DEFAULT '{}',
+      tags TEXT[] NOT NULL DEFAULT '{}',
+
+      -- Constraints
+      CONSTRAINT valid_chain_type CHECK (
+        chain_type IN ('reasoning', 'implementation', 'debugging', 'exploration', 'conversation')
+      ),
+      CONSTRAINT chain_not_empty CHECK (array_length(memory_ids, 1) > 0 OR memory_ids = '{}')
+    );
+
+    -- Indexes for chain lookups
+    CREATE INDEX IF NOT EXISTS idx_memory_chains_type
+      ON memory_chains(chain_type);
+    CREATE INDEX IF NOT EXISTS idx_memory_chains_importance
+      ON memory_chains(importance);
+    CREATE INDEX IF NOT EXISTS idx_memory_chains_last_accessed
+      ON memory_chains(last_accessed_at DESC);
+    CREATE INDEX IF NOT EXISTS idx_memory_chains_memory_ids
+      ON memory_chains USING GIN(memory_ids);
+    CREATE INDEX IF NOT EXISTS idx_memory_chains_tags
+      ON memory_chains USING GIN(tags);
+    CREATE INDEX IF NOT EXISTS idx_memory_chains_name
+      ON memory_chains(name);
+
+    -- Trigger for updated_at
+    DROP TRIGGER IF EXISTS memory_chains_updated_at ON memory_chains;
+    CREATE TRIGGER memory_chains_updated_at
+      BEFORE UPDATE ON memory_chains
+      FOR EACH ROW
+      EXECUTE FUNCTION update_updated_at_column();
+
+    -- =====================================================
+    -- TABLE: memory_quadrants
+    -- Spatial/semantic partitioning for efficient search
+    -- =====================================================
+    CREATE TABLE IF NOT EXISTS memory_quadrants (
+      id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+
+      -- Quadrant identification
+      name VARCHAR(255) NOT NULL,
+      level INTEGER NOT NULL DEFAULT 0,             -- 0=root, 1=domain, 2=subdomain, 3=leaf
+      parent_id UUID REFERENCES memory_quadrants(id) ON DELETE CASCADE,
+      child_ids UUID[] NOT NULL DEFAULT '{}',
+
+      -- Semantic definition
+      -- NOTE: Dimension is auto-detected, unbounded initially
+      centroid vector,  -- Average embedding of all members
+      radius FLOAT NOT NULL DEFAULT 0,              -- Max distance from centroid
+      keywords TEXT[] NOT NULL DEFAULT '{}',        -- Representative keywords
+
+      -- Statistics
+      memory_count INTEGER NOT NULL DEFAULT 0,
+      total_access_count INTEGER NOT NULL DEFAULT 0,
+      last_accessed_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+      -- Thresholds for splitting/merging
+      max_memories INTEGER NOT NULL DEFAULT 1000,
+      min_memories INTEGER NOT NULL DEFAULT 50,
+      max_radius FLOAT NOT NULL DEFAULT 0.5,
+
+      -- Metadata
+      memory_types memory_type[] NOT NULL DEFAULT '{}',
+      tags TEXT[] NOT NULL DEFAULT '{}',
+      metadata JSONB NOT NULL DEFAULT '{}',
+
+      -- Timestamps
+      created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+      updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+      -- Constraints
+      CONSTRAINT valid_level CHECK (level >= 0 AND level <= 10)
+    );
+
+    -- Indexes for quadrant lookups
+    CREATE INDEX IF NOT EXISTS idx_memory_quadrants_level
+      ON memory_quadrants(level);
+    CREATE INDEX IF NOT EXISTS idx_memory_quadrants_parent
+      ON memory_quadrants(parent_id)
+      WHERE parent_id IS NOT NULL;
+    CREATE INDEX IF NOT EXISTS idx_memory_quadrants_memory_count
+      ON memory_quadrants(memory_count DESC);
+
+    -- HNSW index for centroid similarity search
+    CREATE INDEX IF NOT EXISTS idx_memory_quadrants_centroid_hnsw
+      ON memory_quadrants
+      USING hnsw (centroid vector_cosine_ops)
+      WITH (m = 16, ef_construction = 64);
+
+    -- Trigger for updated_at
+    DROP TRIGGER IF EXISTS memory_quadrants_updated_at ON memory_quadrants;
+    CREATE TRIGGER memory_quadrants_updated_at
+      BEFORE UPDATE ON memory_quadrants
+      FOR EACH ROW
+      EXECUTE FUNCTION update_updated_at_column();
+
+    -- =====================================================
+    -- TABLE: quadrant_assignments
+    -- Tracks which quadrant each memory belongs to
+    -- =====================================================
+    CREATE TABLE IF NOT EXISTS quadrant_assignments (
+      memory_id UUID PRIMARY KEY REFERENCES memories(id) ON DELETE CASCADE,
+      quadrant_id UUID NOT NULL REFERENCES memory_quadrants(id) ON DELETE CASCADE,
+      distance_to_centroid FLOAT NOT NULL DEFAULT 0,
+      assigned_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+    );
+
+    -- Indexes for assignment lookups
+    CREATE INDEX IF NOT EXISTS idx_quadrant_assignments_quadrant
+      ON quadrant_assignments(quadrant_id);
+    CREATE INDEX IF NOT EXISTS idx_quadrant_assignments_distance
+      ON quadrant_assignments(quadrant_id, distance_to_centroid);
+
+    -- =====================================================
+    -- FUNCTION: decay_memory_retrievability
+    -- Automatically decays memory strength over time
+    -- =====================================================
+    CREATE OR REPLACE FUNCTION decay_memory_retrievability()
+    RETURNS void AS $$
+    BEGIN
+      -- Update retrievability using Ebbinghaus formula
+      -- R(t) = e^(-t/S) where t is days since last review, S is stability
+      UPDATE memory_strength
+      SET retrievability = LEAST(1.0, GREATEST(0.0,
+        exp(-EXTRACT(EPOCH FROM (NOW() - last_review)) / (86400 * stability))
+      ));
+    END;
+    $$ LANGUAGE plpgsql;
+
+    -- =====================================================
+    -- FUNCTION: decay_association_strength
+    -- Automatically decays association links over time
+    -- =====================================================
+    CREATE OR REPLACE FUNCTION decay_association_strength()
+    RETURNS INTEGER AS $$
+    DECLARE
+      deleted_count INTEGER;
+    BEGIN
+      -- Decay associations that haven't been reinforced
+      UPDATE memory_associations
+      SET strength = strength * (1 - decay_rate)
+      WHERE last_co_activation < NOW() - INTERVAL '7 days';
+
+      -- Delete very weak associations
+      DELETE FROM memory_associations WHERE strength < 0.05;
+      GET DIAGNOSTICS deleted_count = ROW_COUNT;
+
+      RETURN deleted_count;
+    END;
+    $$ LANGUAGE plpgsql;
+
+    -- =====================================================
+    -- VIEW: memory_health_overview
+    -- Shows overall health of the memory system
+    -- =====================================================
+    CREATE OR REPLACE VIEW memory_health_overview AS
+    SELECT
+      (SELECT COUNT(*) FROM memories WHERE expires_at IS NULL OR expires_at > NOW()) as total_memories,
+      (SELECT COUNT(*) FROM memory_strength WHERE retrievability > 0.7) as strong_memories,
+      (SELECT COUNT(*) FROM memory_strength WHERE retrievability < 0.3) as fading_memories,
+      (SELECT COUNT(*) FROM memory_associations) as total_associations,
+      (SELECT COUNT(*) FROM memory_chains) as total_chains,
+      (SELECT COUNT(*) FROM memory_quadrants) as total_quadrants,
+      (SELECT AVG(retrievability) FROM memory_strength) as avg_retrievability,
+      (SELECT AVG(stability) FROM memory_strength) as avg_stability,
+      NOW() as computed_at;
+
+    -- =====================================================
+    -- INDEX: Add relationship tracking to existing memories table
+    -- =====================================================
+    -- Add a column to track related memories if not exists
+    DO $$ BEGIN
+      ALTER TABLE memories ADD COLUMN IF NOT EXISTS related_memories UUID[] DEFAULT '{}';
+    EXCEPTION WHEN duplicate_column THEN NULL;
+    END $$;
+
+    -- Index for related memories lookup
+    CREATE INDEX IF NOT EXISTS idx_memories_related
+      ON memories USING GIN(related_memories)
+      WHERE related_memories IS NOT NULL AND array_length(related_memories, 1) > 0;
+  `,
+    down: `
+    -- Rollback migration 26
+
+    -- Drop views first
+    DROP VIEW IF EXISTS memory_health_overview;
+
+    -- Drop functions
+    DROP FUNCTION IF EXISTS decay_association_strength();
+    DROP FUNCTION IF EXISTS decay_memory_retrievability();
+
+    -- Drop triggers
+    DROP TRIGGER IF EXISTS quadrant_assignments_updated_at ON quadrant_assignments;
+    DROP TRIGGER IF EXISTS memory_quadrants_updated_at ON memory_quadrants;
+    DROP TRIGGER IF EXISTS memory_chains_updated_at ON memory_chains;
+    DROP TRIGGER IF EXISTS memory_associations_updated_at ON memory_associations;
+    DROP TRIGGER IF EXISTS memory_strength_updated_at ON memory_strength;
+
+    -- Drop tables in dependency order
+    DROP TABLE IF EXISTS quadrant_assignments CASCADE;
+    DROP TABLE IF EXISTS memory_quadrants CASCADE;
+    DROP TABLE IF EXISTS memory_chains CASCADE;
+    DROP TABLE IF EXISTS memory_associations CASCADE;
+    DROP TABLE IF EXISTS memory_strength CASCADE;
+
+    -- Remove added column from memories
+    ALTER TABLE memories DROP COLUMN IF EXISTS related_memories;
+  `,
+    checksum: 'memory_evolution_v26_human_like'
+};
+/**
+ * Get the SQL to run this migration
+ */
+export function getMemoryEvolutionMigrationSQL() {
+    return MEMORY_EVOLUTION_MIGRATIONS.up;
+}
+/**
+ * Get the SQL to rollback this migration
+ */
+export function getMemoryEvolutionRollbackSQL() {
+    return MEMORY_EVOLUTION_MIGRATIONS.down;
+}
+export default MEMORY_EVOLUTION_MIGRATIONS;
+//# sourceMappingURL=memoryEvolutionMigration.js.map

package/dist/memory/memoryEvolutionMigration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryEvolutionMigration.js","sourceRoot":"","sources":["../../src/memory/memoryEvolutionMigration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,OAAO,EAAE,EAAE;IACX,IAAI,EAAE,gCAAgC;IAEtC,EAAE,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiTH;IAED,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BL;IAED,QAAQ,EAAE,iCAAiC;CAC5C,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,8BAA8B;IAC5C,OAAO,2BAA2B,CAAC,EAAE,CAAC;AACxC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,6BAA6B;IAC3C,OAAO,2BAA2B,CAAC,IAAI,CAAC;AAC1C,CAAC;AAED,eAAe,2BAA2B,CAAC"}

package/dist/memory/quadrantSearch.d.ts

@@ -0,0 +1,221 @@
+/**
+ * quadrantSearch.ts - SPATIAL/SEMANTIC QUADRANT PARTITIONING
+ *
+ * Large codebases and memory stores become unwieldy with flat search.
+ * This module implements quadrant-based partitioning for:
+ *
+ * 1. SPATIAL QUADRANTS - Group memories by "semantic space"
+ *    - Each quadrant represents a conceptual domain
+ *    - Queries first identify relevant quadrants, then search within
+ *
+ * 2. HIERARCHICAL INDEXING - Multi-level organization
+ *    - L0: Global index (all quadrants)
+ *    - L1: Domain quadrants (code, docs, conversations, etc.)
+ *    - L2: Sub-domain quadrants (by language, project, topic)
+ *    - L3: Leaf clusters (fine-grained groups)
+ *
+ * 3. ADAPTIVE PARTITIONING - Quadrants split/merge based on:
+ *    - Memory count (too many = split)
+ *    - Semantic dispersion (too varied = split)
+ *    - Access patterns (rarely accessed quadrants merge)
+ *
+ * This dramatically speeds up search for large memory stores by
+ * reducing the search space before expensive vector comparisons.
+ */
+import { Memory, MemoryType, EmbeddingProvider } from '../types/index.js';
+/**
+ * QUADRANT - A semantic partition of memory space
+ *
+ * Each quadrant has:
+ * - A centroid embedding (average of all member memories)
+ * - Boundaries defined by semantic distance
+ * - Statistics for adaptive management
+ */
+export interface Quadrant {
+    id: string;
+    name: string;
+    level: number;
+    parentId: string | null;
+    childIds: string[];
+    centroid: number[];
+    radius: number;
+    keywords: string[];
+    memoryCount: number;
+    totalAccessCount: number;
+    lastAccessedAt: Date;
+    createdAt: Date;
+    updatedAt: Date;
+    maxMemories: number;
+    minMemories: number;
+    maxRadius: number;
+    memoryTypes: MemoryType[];
+    tags: string[];
+    metadata: Record<string, unknown>;
+}
+/**
+ * QUADRANT SEARCH RESULT
+ */
+export interface QuadrantSearchResult {
+    quadrant: Quadrant;
+    distance: number;
+    estimatedRelevance: number;
+    memoryCount: number;
+}
+/**
+ * MEMORY ASSIGNMENT - Tracks which quadrant a memory belongs to
+ */
+export interface QuadrantAssignment {
+    memoryId: string;
+    quadrantId: string;
+    distanceToCentroid: number;
+    assignedAt: Date;
+}
+/**
+ * QuadrantSearchSystem - Hierarchical Semantic Partitioning
+ *
+ * The core idea: Instead of searching ALL memories, first find
+ * relevant quadrants, then search within those quadrants only.
+ *
+ * For a 1M memory store:
+ * - Flat search: Compare query to all 1M embeddings
+ * - Quadrant search: Compare to ~50 quadrants, then ~1000 memories
+ *
+ * This provides 100-1000x speedup for large stores.
+ */
+export declare class QuadrantSearchSystem {
+    private db;
+    private embeddingProvider;
+    private dimensionService;
+    private quadrantCache;
+    private rootQuadrantId;
+    private detectedDimension;
+    private config;
+    constructor(db: any, embeddingProvider: EmbeddingProvider);
+    /**
+     * Get the DimensionService (lazy initialization)
+     */
+    private getDimService;
+    /**
+     * Validate and prepare an embedding for database operations.
+     * Uses DimensionService to handle dimension mismatches.
+     */
+    private prepareEmbedding;
+    /**
+     * Get the current embedding dimension from DB or provider
+     * DYNAMIC - no hardcoded values!
+     */
+    private getDimension;
+    /**
+     * Create a zero vector with the correct dimension
+     */
+    private createZeroCentroid;
+    /**
+     * Initialize the quadrant system with root quadrant
+     */
+    initialize(): Promise<void>;
+    /**
+     * Create a new quadrant
+     */
+    createQuadrant(name: string, description: string, level: number, parentId: string | null, centroid: number[], keywords: string[]): Promise<Quadrant>;
+    /**
+     * Assign a memory to the best quadrant
+     */
+    assignMemory(memory: Memory, embedding: number[]): Promise<QuadrantAssignment>;
+    /**
+     * Find the best quadrant for a given embedding
+     * Dimension-agnostic traversal - skips quadrants with mismatched dimensions
+     */
+    private findBestQuadrant;
+    /**
+     * Search for relevant quadrants given a query embedding
+     *
+     * This is the key optimization: instead of searching all memories,
+     * we first identify the most relevant quadrants, then search within them.
+     * Uses DimensionService to handle dimension mismatches gracefully.
+     */
+    searchQuadrants(queryEmbedding: number[], options?: {
+        maxQuadrants?: number;
+        minRelevance?: number;
+        level?: number;
+        includeChildren?: boolean;
+        originalQuery?: string;
+    }): Promise<QuadrantSearchResult[]>;
+    /**
+     * Search memories within specific quadrants
+     *
+     * This is called AFTER searchQuadrants to get actual memories
+     * from the most relevant quadrants.
+     * Uses DimensionService to handle dimension mismatches gracefully.
+     */
+    searchWithinQuadrants(queryEmbedding: number[], quadrantIds: string[], options?: {
+        limit?: number;
+        threshold?: number;
+        originalQuery?: string;
+    }): Promise<Array<{
+        memory: Memory;
+        similarity: number;
+        quadrantId: string;
+    }>>;
+    /**
+     * Full quadrant-aware search: find quadrants, then search within
+     * Uses DimensionService to handle dimension mismatches gracefully.
+     */
+    smartSearch(queryEmbedding: number[], options?: {
+        limit?: number;
+        threshold?: number;
+        maxQuadrants?: number;
+        originalQuery?: string;
+    }): Promise<Array<{
+        memory: Memory;
+        similarity: number;
+        quadrantId: string;
+    }>>;
+    /**
+     * Global search fallback (searches all memories)
+     * Assumes embedding is already validated by caller.
+     */
+    private globalSearch;
+    /**
+     * Split a quadrant that has grown too large or dispersed
+     * Dimension-agnostic - validates and filters embeddings during split.
+     */
+    splitQuadrant(quadrantId: string): Promise<Quadrant[]>;
+    /**
+     * Simple k-means clustering for quadrant splitting
+     * Dimension-agnostic - filters embeddings by expected dimension.
+     */
+    private kMeansClustering;
+    private loadQuadrantsIntoCache;
+    private updateQuadrantStats;
+    private cosineDistance;
+    /**
+     * Compute cosine similarity between two vectors
+     * Works with any dimension - no hardcoded values
+     */
+    private cosineSimilarity;
+    /**
+     * Compute average of multiple embeddings
+     * Dimension-agnostic - uses first embedding's dimension, validates all others match
+     */
+    private averageEmbeddings;
+    private extractKeywords;
+    private parseEmbedding;
+    private rowToQuadrant;
+    private rowToMemory;
+    /**
+     * Get the current detected embedding dimension
+     * Returns null if not yet detected
+     */
+    getDetectedDimension(): number | null;
+    /**
+     * Force re-detection of embedding dimension
+     * Useful when database schema changes
+     */
+    refreshDimension(): Promise<number>;
+    /**
+     * Validate that an embedding has the correct dimension
+     */
+    validateEmbeddingDimension(embedding: number[]): Promise<boolean>;
+}
+export default QuadrantSearchSystem;
+//# sourceMappingURL=quadrantSearch.d.ts.map

package/dist/memory/quadrantSearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quadrantSearch.d.ts","sourceRoot":"","sources":["../../src/memory/quadrantSearch.ts"],"names":[],"mappings":"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"}