squish-memory 1.0.2 → 1.2.0

package/dist/core/lib/db-client.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Database Client & Schema Loading Abstraction
+ *
+ * Provides a unified interface for accessing both the database client and schema
+ * in a single call, eliminating repetitive patterns of:
+ *   `const db = createDatabaseClient(await getDb()); const schema = await getSchema();`
+ *
+ * Features:
+ * - Single async call to get both db and schema
+ * - Consistent error handling with clear messages
+ * - Preserves schema caching
+ * - Provides raw connection for special cases
+ * - Helper `withDbClient` for functional programming patterns
+ *
+ * @example
+ * ```typescript
+ * // Old pattern (repetitive)
+ * const db = createDatabaseClient(await getDb());
+ * const schema = await getSchema();
+ *
+ * // New pattern (unified)
+ * const { db, schema } = await getDbClient();
+ *
+ * // With helper
+ * const result = await withDbClient(async (client) => {
+ *   return await client.db.select().from(client.schema.memories);
+ * });
+ * ```
+ */
+import type { DatabaseClient } from '../storage/database.js';
+import type { SchemaModule } from '../../db/schema.js';
+/**
+ * Unified database client interface combining:
+ * - `db`: Wrapped database client with select/insert/update/delete methods
+ * - `schema`: Drizzle schema module with table definitions
+ * - `raw`: Raw underlying connection for special cases (mcp-server, index, etc.)
+ */
+export interface DbClient {
+    /**
+     * Wrapped database client with unified API
+     * Provides select(), insert(), update(), delete() methods
+     */
+    db: DatabaseClient;
+    /**
+     * Schema module containing table definitions
+     * Access tables via schema.tableName (e.g., schema.memories, schema.users)
+     */
+    schema: SchemaModule;
+    /**
+     * Raw underlying database connection
+     * Use for special cases that require direct access to the native driver
+     * (e.g., raw SQL queries, specific driver features)
+     */
+    raw: any;
+}
+/**
+ * Get a unified database client with both db and schema.
+ *
+ * This function:
+ * 1. Calls getDb() to initialize/retrieve the database connection
+ * 2. Calls getSchema() to get the appropriate schema (with caching)
+ * 3. Wraps the db with createDatabaseClient() for unified API
+ * 4. Returns all three as a single DbClient object
+ *
+ * Error handling:
+ * - Wraps any database initialization errors with a clear message
+ * - Preserves the original error as `cause` property
+ *
+ * Schema caching:
+ * - Uses the same caching mechanism as getSchema()
+ * - Multiple calls to getDbClient() will return the same schema reference
+ *
+ * @returns Promise<DbClient> Unified client with db, schema, and raw
+ * @throws {Error} When database initialization fails, with cause attached
+ *
+ * @example
+ * ```typescript
+ * const { db, schema, raw } = await getDbClient();
+ *
+ * // Use db for queries
+ * const memories = await db.select().from(schema.memories).limit(10);
+ *
+ * // Use raw for special cases
+ * const client = (raw as any).$client;
+ * if (client && typeof client.exec === 'function') {
+ *   client.exec('VACUUM');
+ * }
+ * ```
+ */
+export declare function getDbClient(): Promise<DbClient>;
+/**
+ * Execute an operation with a unified database client.
+ *
+ * Convenience wrapper that:
+ * 1. Calls getDbClient() to obtain client
+ * 2. Executes the provided operation
+ * 3. Ensures proper cleanup if needed (no-op currently, for future extension)
+ *
+ * @param operation - Async function that receives the DbClient and returns a result
+ * @returns Promise<T> The result returned by the operation
+ * @throws {Error} When database initialization or operation fails
+ *
+ * @example
+ * ```typescript
+ * const count = await withDbClient(async (client) => {
+ *   const result = await client.db
+ *     .select({ count: sql`count(*)` })
+ *     .from(client.schema.memories);
+ *   return result[0].count;
+ * });
+ * ```
+ */
+export declare function withDbClient<T>(operation: (client: DbClient) => Promise<T>): Promise<T>;
+//# sourceMappingURL=db-client.d.ts.map

package/dist/core/lib/db-client.js

@@ -0,0 +1,130 @@
+/**
+ * Database Client & Schema Loading Abstraction
+ *
+ * Provides a unified interface for accessing both the database client and schema
+ * in a single call, eliminating repetitive patterns of:
+ *   `const db = createDatabaseClient(await getDb()); const schema = await getSchema();`
+ *
+ * Features:
+ * - Single async call to get both db and schema
+ * - Consistent error handling with clear messages
+ * - Preserves schema caching
+ * - Provides raw connection for special cases
+ * - Helper `withDbClient` for functional programming patterns
+ *
+ * @example
+ * ```typescript
+ * // Old pattern (repetitive)
+ * const db = createDatabaseClient(await getDb());
+ * const schema = await getSchema();
+ *
+ * // New pattern (unified)
+ * const { db, schema } = await getDbClient();
+ *
+ * // With helper
+ * const result = await withDbClient(async (client) => {
+ *   return await client.db.select().from(client.schema.memories);
+ * });
+ * ```
+ */
+import { getDb } from '../../db/index.js';
+import { getSchema } from '../../db/schema.js';
+import { createDatabaseClient } from '../storage/database.js';
+/**
+ * Internal cached schema to preserve getSchema() caching behavior
+ */
+let cachedSchema = null;
+/**
+ * Get a unified database client with both db and schema.
+ *
+ * This function:
+ * 1. Calls getDb() to initialize/retrieve the database connection
+ * 2. Calls getSchema() to get the appropriate schema (with caching)
+ * 3. Wraps the db with createDatabaseClient() for unified API
+ * 4. Returns all three as a single DbClient object
+ *
+ * Error handling:
+ * - Wraps any database initialization errors with a clear message
+ * - Preserves the original error as `cause` property
+ *
+ * Schema caching:
+ * - Uses the same caching mechanism as getSchema()
+ * - Multiple calls to getDbClient() will return the same schema reference
+ *
+ * @returns Promise<DbClient> Unified client with db, schema, and raw
+ * @throws {Error} When database initialization fails, with cause attached
+ *
+ * @example
+ * ```typescript
+ * const { db, schema, raw } = await getDbClient();
+ *
+ * // Use db for queries
+ * const memories = await db.select().from(schema.memories).limit(10);
+ *
+ * // Use raw for special cases
+ * const client = (raw as any).$client;
+ * if (client && typeof client.exec === 'function') {
+ *   client.exec('VACUUM');
+ * }
+ * ```
+ */
+export async function getDbClient() {
+    try {
+        // Get raw database connection
+        const rawDb = await getDb();
+        // Get schema (with caching)
+        if (!cachedSchema) {
+            cachedSchema = await getSchema();
+        }
+        // Create wrapped database client
+        const db = createDatabaseClient(rawDb);
+        return {
+            db,
+            schema: cachedSchema,
+            raw: rawDb,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error
+            ? `Database initialization failed: ${error.message}`
+            : 'Database initialization failed';
+        // Wrap error with clear message while preserving cause
+        const wrappedError = new Error(message);
+        // @ts-ignore - TypeScript doesn't allow 'cause' on Error, but it's valid
+        wrappedError.cause = error;
+        throw wrappedError;
+    }
+}
+/**
+ * Execute an operation with a unified database client.
+ *
+ * Convenience wrapper that:
+ * 1. Calls getDbClient() to obtain client
+ * 2. Executes the provided operation
+ * 3. Ensures proper cleanup if needed (no-op currently, for future extension)
+ *
+ * @param operation - Async function that receives the DbClient and returns a result
+ * @returns Promise<T> The result returned by the operation
+ * @throws {Error} When database initialization or operation fails
+ *
+ * @example
+ * ```typescript
+ * const count = await withDbClient(async (client) => {
+ *   const result = await client.db
+ *     .select({ count: sql`count(*)` })
+ *     .from(client.schema.memories);
+ *   return result[0].count;
+ * });
+ * ```
+ */
+export async function withDbClient(operation) {
+    const client = await getDbClient();
+    try {
+        return await operation(client);
+    }
+    finally {
+        // Future: Add cleanup logic if needed (connection pooling, etc.)
+        // Currently getDb() handles connection pooling and reuse
+    }
+}
+//# sourceMappingURL=db-client.js.map

package/dist/core/lib/parse-embedding.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Parse embedding from various storage formats.
+ * Converted from 4 locations: hybrid-search.ts, consolidation.ts, memories.ts, entity-deduplicator.ts
+ *
+ * @param embeddingData - Input in Float32Array, Buffer, Uint8Array, JSON string, or Array format
+ * @returns Array of numbers or null if parsing fails
+ */
+export declare function parseEmbedding(embeddingData: unknown): number[] | null;
+//# sourceMappingURL=parse-embedding.d.ts.map

package/dist/core/lib/parse-embedding.js

@@ -0,0 +1,58 @@
+/**
+ * Parse embedding from various storage formats.
+ * Converted from 4 locations: hybrid-search.ts, consolidation.ts, memories.ts, entity-deduplicator.ts
+ *
+ * @param embeddingData - Input in Float32Array, Buffer, Uint8Array, JSON string, or Array format
+ * @returns Array of numbers or null if parsing fails
+ */
+export function parseEmbedding(embeddingData) {
+    if (!embeddingData)
+        return null;
+    // Handle Array directly (most common case)
+    if (Array.isArray(embeddingData)) {
+        return embeddingData;
+    }
+    // Handle Float32Array directly
+    if (embeddingData instanceof Float32Array) {
+        return Array.from(embeddingData);
+    }
+    // Handle Uint8Array and Buffer - try JSON first, then binary Float32
+    if (embeddingData instanceof Uint8Array || Buffer.isBuffer(embeddingData)) {
+        // Try to parse as JSON string first
+        try {
+            const json = JSON.parse(embeddingData.toString());
+            if (Array.isArray(json)) {
+                return json;
+            }
+        }
+        catch {
+            // Not JSON, try binary Float32
+        }
+        // Try to parse as binary Float32Array
+        try {
+            const buffer = embeddingData.buffer;
+            const arrayBuffer = buffer instanceof ArrayBuffer
+                ? buffer
+                : buffer;
+            const floatArray = new Float32Array(arrayBuffer);
+            return Array.from(floatArray);
+        }
+        catch {
+            return null;
+        }
+    }
+    // Handle JSON string
+    if (typeof embeddingData === 'string') {
+        try {
+            const parsed = JSON.parse(embeddingData);
+            if (Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=parse-embedding.js.map

package/dist/core/lib/schemas.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Shared Zod schemas for input validation across Squish
+ * Provides consistent validation for common input types
+ */
+import { z } from 'zod';
+/**
+ * Limit schema: integer between 1 and 100, default 20
+ */
+export declare const limitSchema: z.ZodDefault<z.ZodNumber>;
+/**
+ * Offset schema: integer >= 0, default 0
+ */
+export declare const offsetSchema: z.ZodDefault<z.ZodNumber>;
+/**
+ * Project ID/path schema: non-empty string
+ */
+export declare const projectIdSchema: z.ZodString;
+/**
+ * Memory ID schema: valid UUID
+ */
+export declare const memoryIdSchema: z.ZodString;
+/**
+ * Pagination schema combining limit and offset
+ */
+export declare const paginationSchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>;
+    offset: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * Search query schema: non-empty string
+ */
+export declare const searchQuerySchema: z.ZodString;
+/**
+ * Memory type schema
+ */
+export declare const memoryTypeSchema: z.ZodEnum<{
+    observation: "observation";
+    fact: "fact";
+    decision: "decision";
+    context: "context";
+    preference: "preference";
+    note: "note";
+}>;
+/**
+ * Association type schema
+ */
+export declare const associationTypeSchema: z.ZodEnum<{
+    supersedes: "supersedes";
+    contradicts: "contradicts";
+    supports: "supports";
+    relates_to: "relates_to";
+    duplicate: "duplicate";
+}>;
+/**
+ * Weight schema: number between 0 and 1
+ */
+export declare const weightSchema: z.ZodNumber;
+/**
+ * Learning type schema
+ */
+export declare const learningTypeSchema: z.ZodEnum<{
+    observation: "observation";
+    success: "success";
+    failure: "failure";
+    fix: "fix";
+}>;
+/**
+ * Observation type schema
+ */
+export declare const observationTypeSchema: z.ZodEnum<{
+    error: "error";
+    insight: "insight";
+    pattern: "pattern";
+    tool_use: "tool_use";
+    file_change: "file_change";
+}>;
+/**
+ * Confidence level schema
+ */
+export declare const confidenceLevelSchema: z.ZodEnum<{
+    certain: "certain";
+    speculative: "speculative";
+    outdated: "outdated";
+}>;
+/**
+ * Search input schema (common for search operations)
+ */
+export declare const searchInputSchema: z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    offset: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    project: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodEnum<{
+        observation: "observation";
+        fact: "fact";
+        decision: "decision";
+        context: "context";
+        preference: "preference";
+        note: "note";
+    }>>;
+}, z.core.$strip>;
+/**
+ * Memory recall schema
+ */
+export declare const recallInputSchema: z.ZodObject<{
+    memoryId: z.ZodString;
+    limit: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    project: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Tag operation schema
+ */
+export declare const tagOperationSchema: z.ZodObject<{
+    action: z.ZodEnum<{
+        add: "add";
+        remove: "remove";
+    }>;
+    tag: z.ZodString;
+    search: z.ZodOptional<z.ZodString>;
+    olderThan: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodEnum<{
+        observation: "observation";
+        fact: "fact";
+        decision: "decision";
+        context: "context";
+        preference: "preference";
+        note: "note";
+    }>>;
+    limit: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    project: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/core/lib/schemas.js

@@ -0,0 +1,87 @@
+/**
+ * Shared Zod schemas for input validation across Squish
+ * Provides consistent validation for common input types
+ */
+import { z } from 'zod';
+/**
+ * Limit schema: integer between 1 and 100, default 20
+ */
+export const limitSchema = z.number().int().min(1).max(100).default(20);
+/**
+ * Offset schema: integer >= 0, default 0
+ */
+export const offsetSchema = z.number().int().min(0).default(0);
+/**
+ * Project ID/path schema: non-empty string
+ */
+export const projectIdSchema = z.string().min(1);
+/**
+ * Memory ID schema: valid UUID
+ */
+export const memoryIdSchema = z.string().uuid();
+/**
+ * Pagination schema combining limit and offset
+ */
+export const paginationSchema = z.object({
+    limit: limitSchema,
+    offset: offsetSchema,
+});
+/**
+ * Search query schema: non-empty string
+ */
+export const searchQuerySchema = z.string().min(1).trim();
+/**
+ * Memory type schema
+ */
+export const memoryTypeSchema = z.enum(['observation', 'fact', 'decision', 'context', 'preference', 'note']);
+/**
+ * Association type schema
+ */
+export const associationTypeSchema = z.enum(['relates_to', 'supports', 'contradicts', 'supersedes', 'duplicate']);
+/**
+ * Weight schema: number between 0 and 1
+ */
+export const weightSchema = z.number().min(0).max(1);
+/**
+ * Learning type schema
+ */
+export const learningTypeSchema = z.enum(['success', 'failure', 'fix', 'observation']);
+/**
+ * Observation type schema
+ */
+export const observationTypeSchema = z.enum(['tool_use', 'file_change', 'error', 'pattern', 'insight']);
+/**
+ * Confidence level schema
+ */
+export const confidenceLevelSchema = z.enum(['certain', 'speculative', 'outdated']);
+/**
+ * Search input schema (common for search operations)
+ */
+export const searchInputSchema = z.object({
+    query: searchQuerySchema,
+    limit: limitSchema.optional(),
+    offset: offsetSchema.optional(),
+    project: projectIdSchema.optional(),
+    type: memoryTypeSchema.optional(),
+});
+/**
+ * Memory recall schema
+ */
+export const recallInputSchema = z.object({
+    memoryId: memoryIdSchema,
+    limit: limitSchema.optional(),
+    project: projectIdSchema.optional(),
+});
+/**
+ * Tag operation schema
+ */
+export const tagOperationSchema = z.object({
+    action: z.enum(['add', 'remove']),
+    tag: z.string().min(1),
+    search: z.string().optional(),
+    olderThan: z.string().optional(),
+    type: memoryTypeSchema.optional(),
+    limit: limitSchema.optional(),
+    project: projectIdSchema.optional(),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/core/lib/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared type definitions for Squish Memory system
+ * Consolidated from core/memory/memories.ts and core/memory/normalization.ts
+ */
+export type MemoryType = 'observation' | 'fact' | 'decision' | 'context' | 'preference' | 'note' | 'task';
+/**
+ * Confidence level for memory records
+ * - certain: High confidence, verified information
+ * - speculative: Low confidence, unverified or uncertain
+ * - outdated: Information that may no longer be accurate
+ */
+export type ConfidenceLevel = 'certain' | 'speculative' | 'outdated';
+/**
+ * Unified MemoryRecord interface
+ * Used across memories.ts and normalization.ts
+ *
+ * Note: type is string to avoid circular dependency with memories.ts
+ * Use MemoryType for type checking when needed
+ */
+export interface MemoryRecord {
+    id: string;
+    projectId?: string | null;
+    type: string;
+    content: string;
+    summary?: string | null;
+    tags: string[];
+    metadata?: Record<string, unknown> | null;
+    createdAt?: string | null;
+    validFrom?: string | null;
+    validTo?: string | null;
+    recordedAt?: string | null;
+    similarity?: number;
+    importance?: number;
+    confidenceLevel?: ConfidenceLevel | null;
+}
+/**
+ * Result of a safety check
+ * Used to determine if a merge action can proceed
+ */
+export interface SafetyCheckResult {
+    passed: boolean;
+    warnings: string[];
+    blockers: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/lib/types.js

@@ -0,0 +1,6 @@
+/**
+ * Shared type definitions for Squish Memory system
+ * Consolidated from core/memory/memories.ts and core/memory/normalization.ts
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/{utils.d.ts → lib/utils.d.ts}

@@ -2,6 +2,7 @@
  * Shared utility functions for the squish codebase
  */
 export declare function normalizeTimestamp(value: any): string | null;
+export declare function now(): string;
 export declare function isDatabaseUnavailableError(error: any): boolean;
 export declare function withDatabaseErrorHandling<T>(operation: () => Promise<T>, errorMessage: string): Promise<T>;
 export declare function clampLimit(value: number | undefined, defaultValue: number, min?: number, max?: number): number;
@@ -10,4 +11,8 @@ export declare function prepareEmbedding(embedding: number[] | null): {
     embeddingJson?: string | null;
 };
 export declare function determineOverallStatus(dbStatus: string, redisOk: boolean): string;
+export declare function parseDate(input: string): Date | null;
+export declare function filterByDateRange<T extends {
+    createdAt?: string | null;
+}>(items: T[], since?: string, until?: string): T[];
 //# sourceMappingURL=utils.d.ts.map