@claude-flow/memory 3.0.0-alpha.1

package/src/application/commands/delete-memory.command.ts

@@ -0,0 +1,172 @@
+/**
+ * Delete Memory Command - Application Layer (CQRS)
+ *
+ * Command for deleting memory entries.
+ * Supports soft delete and hard delete.
+ *
+ * @module v3/memory/application/commands
+ */
+
+import { IMemoryRepository } from '../../domain/repositories/memory-repository.interface.js';
+
+/**
+ * Delete Memory Command Input
+ */
+export interface DeleteMemoryInput {
+  id?: string;
+  namespace?: string;
+  key?: string;
+  hardDelete?: boolean;
+}
+
+/**
+ * Delete Memory Command Result
+ */
+export interface DeleteMemoryResult {
+  success: boolean;
+  deleted: boolean;
+  entryId?: string;
+  wasHardDelete: boolean;
+}
+
+/**
+ * Delete Memory Command Handler
+ */
+export class DeleteMemoryCommandHandler {
+  constructor(private readonly repository: IMemoryRepository) {}
+
+  async execute(input: DeleteMemoryInput): Promise<DeleteMemoryResult> {
+    let entryId: string | undefined;
+
+    // Find entry by ID or by namespace:key
+    if (input.id) {
+      entryId = input.id;
+    } else if (input.namespace && input.key) {
+      const entry = await this.repository.findByKey(input.namespace, input.key);
+      entryId = entry?.id;
+    }
+
+    if (!entryId) {
+      return {
+        success: false,
+        deleted: false,
+        wasHardDelete: false,
+      };
+    }
+
+    if (input.hardDelete) {
+      // Hard delete - remove from database
+      const deleted = await this.repository.delete(entryId);
+      return {
+        success: true,
+        deleted,
+        entryId,
+        wasHardDelete: true,
+      };
+    } else {
+      // Soft delete - mark as deleted
+      const entry = await this.repository.findById(entryId);
+      if (entry) {
+        entry.delete();
+        await this.repository.save(entry);
+        return {
+          success: true,
+          deleted: true,
+          entryId,
+          wasHardDelete: false,
+        };
+      }
+    }
+
+    return {
+      success: false,
+      deleted: false,
+      entryId,
+      wasHardDelete: false,
+    };
+  }
+}
+
+/**
+ * Bulk Delete Command Input
+ */
+export interface BulkDeleteMemoryInput {
+  ids?: string[];
+  namespace?: string;
+  olderThan?: Date;
+  hardDelete?: boolean;
+}
+
+/**
+ * Bulk Delete Command Result
+ */
+export interface BulkDeleteMemoryResult {
+  success: boolean;
+  deletedCount: number;
+  failedCount: number;
+  errors: Array<{ id: string; error: string }>;
+}
+
+/**
+ * Bulk Delete Memory Command Handler
+ */
+export class BulkDeleteMemoryCommandHandler {
+  constructor(private readonly repository: IMemoryRepository) {}
+
+  async execute(input: BulkDeleteMemoryInput): Promise<BulkDeleteMemoryResult> {
+    let idsToDelete: string[] = [];
+
+    if (input.ids) {
+      idsToDelete = input.ids;
+    } else if (input.namespace) {
+      const entries = await this.repository.findByNamespace(input.namespace);
+      idsToDelete = entries
+        .filter((e) => !input.olderThan || e.createdAt < input.olderThan)
+        .map((e) => e.id);
+    }
+
+    if (idsToDelete.length === 0) {
+      return {
+        success: true,
+        deletedCount: 0,
+        failedCount: 0,
+        errors: [],
+      };
+    }
+
+    if (input.hardDelete) {
+      const result = await this.repository.deleteMany(idsToDelete);
+      return {
+        success: result.failed === 0,
+        deletedCount: result.success,
+        failedCount: result.failed,
+        errors: result.errors,
+      };
+    } else {
+      // Soft delete
+      const entries = await this.repository.findByIds(idsToDelete);
+      let deletedCount = 0;
+      const errors: Array<{ id: string; error: string }> = [];
+
+      for (const entry of entries) {
+        try {
+          entry.delete();
+          await this.repository.save(entry);
+          deletedCount++;
+        } catch (error) {
+          errors.push({
+            id: entry.id,
+            error: error instanceof Error ? error.message : 'Unknown error',
+          });
+        }
+      }
+
+      return {
+        success: errors.length === 0,
+        deletedCount,
+        failedCount: errors.length,
+        errors,
+      };
+    }
+  }
+}

package/src/application/commands/store-memory.command.ts

@@ -0,0 +1,103 @@
+/**
+ * Store Memory Command - Application Layer (CQRS)
+ *
+ * Command for storing a new memory entry.
+ * Implements CQRS pattern per ADR-002.
+ *
+ * @module v3/memory/application/commands
+ */
+
+import { MemoryEntry, MemoryType } from '../../domain/entities/memory-entry.js';
+import { IMemoryRepository } from '../../domain/repositories/memory-repository.interface.js';
+import { MemoryDomainService } from '../../domain/services/memory-domain-service.js';
+
+/**
+ * Store Memory Command Input
+ */
+export interface StoreMemoryInput {
+  namespace: string;
+  key: string;
+  value: unknown;
+  type?: MemoryType;
+  vector?: Float32Array;
+  metadata?: Record<string, unknown>;
+  ttl?: number;
+}
+
+/**
+ * Store Memory Command Result
+ */
+export interface StoreMemoryResult {
+  success: boolean;
+  entryId: string;
+  entry: MemoryEntry;
+  isUpdate: boolean;
+}
+
+/**
+ * Store Memory Command Handler
+ *
+ * Handles the command to store a memory entry.
+ * Coordinates between domain services and repository.
+ */
+export class StoreMemoryCommandHandler {
+  constructor(
+    private readonly repository: IMemoryRepository,
+    private readonly domainService: MemoryDomainService
+  ) {}
+
+  /**
+   * Execute the store memory command
+   */
+  async execute(input: StoreMemoryInput): Promise<StoreMemoryResult> {
+    // Check if entry already exists
+    const existing = await this.repository.findByKey(input.namespace, input.key);
+    const isUpdate = existing !== null;
+
+    let entry: MemoryEntry;
+
+    if (existing) {
+      // Update existing entry
+      existing.updateValue(input.value);
+      if (input.vector) {
+        existing.updateVector(input.vector);
+      }
+      if (input.metadata) {
+        for (const [key, value] of Object.entries(input.metadata)) {
+          existing.setMetadata(key, value);
+        }
+      }
+      await this.repository.save(existing);
+      entry = existing;
+    } else {
+      // Create new entry
+      if (input.type) {
+        entry = MemoryEntry.create({
+          namespace: input.namespace,
+          key: input.key,
+          value: input.value,
+          type: input.type,
+          vector: input.vector,
+          metadata: input.metadata,
+          ttl: input.ttl,
+        });
+        await this.repository.save(entry);
+      } else {
+        // Use domain service for type detection
+        entry = await this.domainService.storeWithTypeDetection(
+          input.namespace,
+          input.key,
+          input.value,
+          input.vector
+        );
+      }
+    }
+
+    return {
+      success: true,
+      entryId: entry.id,
+      entry,
+      isUpdate,
+    };
+  }
+}

package/src/application/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Memory Application Layer - Public Exports
+ *
+ * Exports all application services, commands, and queries.
+ *
+ * @module v3/memory/application
+ */
+
+// Commands
+export {
+  StoreMemoryCommandHandler,
+  type StoreMemoryInput,
+  type StoreMemoryResult,
+} from './commands/store-memory.command.js';
+
+export {
+  DeleteMemoryCommandHandler,
+  BulkDeleteMemoryCommandHandler,
+  type DeleteMemoryInput,
+  type DeleteMemoryResult,
+  type BulkDeleteMemoryInput,
+  type BulkDeleteMemoryResult,
+} from './commands/delete-memory.command.js';
+
+// Queries
+export {
+  SearchMemoryQueryHandler,
+  GetMemoryByKeyQueryHandler,
+  type SearchMemoryInput,
+  type SearchMemoryResult,
+  type GetMemoryByKeyInput,
+  type GetMemoryByKeyResult,
+} from './queries/search-memory.query.js';
+
+// Application Service
+export { MemoryApplicationService } from './services/memory-application-service.js';

package/src/application/queries/search-memory.query.ts

@@ -0,0 +1,237 @@
+/**
+ * Search Memory Query - Application Layer (CQRS)
+ *
+ * Query for searching memory entries.
+ * Supports text search, vector search, and filtering.
+ *
+ * @module v3/memory/application/queries
+ */
+
+import { MemoryEntry, MemoryType, MemoryStatus } from '../../domain/entities/memory-entry.js';
+import {
+  IMemoryRepository,
+  VectorSearchResult,
+  MemoryQueryOptions,
+} from '../../domain/repositories/memory-repository.interface.js';
+
+/**
+ * Search Memory Query Input
+ */
+export interface SearchMemoryInput {
+  // Vector search
+  vector?: Float32Array;
+  similarityThreshold?: number;
+
+  // Filter options
+  namespace?: string;
+  type?: MemoryType;
+  status?: MemoryStatus;
+
+  // Pagination
+  limit?: number;
+  offset?: number;
+
+  // Sorting
+  orderBy?: 'createdAt' | 'updatedAt' | 'accessCount' | 'lastAccessedAt';
+  orderDirection?: 'asc' | 'desc';
+
+  // Text search (searches in value and metadata)
+  textQuery?: string;
+
+  // Access tracking
+  trackAccess?: boolean;
+}
+
+/**
+ * Search Memory Query Result
+ */
+export interface SearchMemoryResult {
+  entries: MemoryEntry[];
+  total: number;
+  hasMore: boolean;
+  searchType: 'vector' | 'filter' | 'text';
+  similarities?: number[];
+}
+
+/**
+ * Search Memory Query Handler
+ */
+export class SearchMemoryQueryHandler {
+  constructor(private readonly repository: IMemoryRepository) {}
+
+  async execute(input: SearchMemoryInput): Promise<SearchMemoryResult> {
+    const limit = input.limit ?? 10;
+    const offset = input.offset ?? 0;
+
+    // Vector search takes precedence
+    if (input.vector) {
+      return this.executeVectorSearch(input, limit, offset);
+    }
+
+    // Text search
+    if (input.textQuery) {
+      return this.executeTextSearch(input, limit, offset);
+    }
+
+    // Filter-based search
+    return this.executeFilterSearch(input, limit, offset);
+  }
+
+  private async executeVectorSearch(
+    input: SearchMemoryInput,
+    limit: number,
+    offset: number
+  ): Promise<SearchMemoryResult> {
+    const results = await this.repository.searchByVector({
+      vector: input.vector!,
+      namespace: input.namespace,
+      limit: limit + offset, // Get extra for pagination
+      threshold: input.similarityThreshold ?? 0.5,
+      type: input.type,
+    });
+
+    // Apply offset
+    const paginatedResults = results.slice(offset, offset + limit);
+
+    // Track access if requested
+    if (input.trackAccess) {
+      await this.trackEntryAccess(paginatedResults.map((r) => r.entry));
+    }
+
+    return {
+      entries: paginatedResults.map((r) => r.entry),
+      total: results.length,
+      hasMore: results.length > offset + limit,
+      searchType: 'vector',
+      similarities: paginatedResults.map((r) => r.similarity),
+    };
+  }
+
+  private async executeTextSearch(
+    input: SearchMemoryInput,
+    limit: number,
+    offset: number
+  ): Promise<SearchMemoryResult> {
+    // Get all entries matching filters
+    const options: MemoryQueryOptions = {
+      namespace: input.namespace,
+      type: input.type,
+      status: input.status ?? 'active',
+      orderBy: input.orderBy ?? 'createdAt',
+      orderDirection: input.orderDirection ?? 'desc',
+    };
+
+    const allEntries = await this.repository.findAll(options);
+
+    // Filter by text query
+    const query = input.textQuery!.toLowerCase();
+    const matchingEntries = allEntries.filter((entry) => {
+      const valueStr = JSON.stringify(entry.value).toLowerCase();
+      const metadataStr = JSON.stringify(entry.metadata).toLowerCase();
+      return valueStr.includes(query) || metadataStr.includes(query);
+    });
+
+    // Paginate
+    const paginatedEntries = matchingEntries.slice(offset, offset + limit);
+
+    // Track access if requested
+    if (input.trackAccess) {
+      await this.trackEntryAccess(paginatedEntries);
+    }
+
+    return {
+      entries: paginatedEntries,
+      total: matchingEntries.length,
+      hasMore: matchingEntries.length > offset + limit,
+      searchType: 'text',
+    };
+  }
+
+  private async executeFilterSearch(
+    input: SearchMemoryInput,
+    limit: number,
+    offset: number
+  ): Promise<SearchMemoryResult> {
+    const options: MemoryQueryOptions = {
+      namespace: input.namespace,
+      type: input.type,
+      status: input.status ?? 'active',
+      limit,
+      offset,
+      orderBy: input.orderBy ?? 'createdAt',
+      orderDirection: input.orderDirection ?? 'desc',
+    };
+
+    const entries = await this.repository.findAll(options);
+    const total = await this.repository.count({
+      namespace: input.namespace,
+      type: input.type,
+      status: input.status ?? 'active',
+    });
+
+    // Track access if requested
+    if (input.trackAccess) {
+      await this.trackEntryAccess(entries);
+    }
+
+    return {
+      entries,
+      total,
+      hasMore: total > offset + limit,
+      searchType: 'filter',
+    };
+  }
+
+  private async trackEntryAccess(entries: MemoryEntry[]): Promise<void> {
+    for (const entry of entries) {
+      entry.recordAccess();
+      await this.repository.save(entry);
+    }
+  }
+}
+
+/**
+ * Get Memory By Key Query Input
+ */
+export interface GetMemoryByKeyInput {
+  namespace: string;
+  key: string;
+  trackAccess?: boolean;
+}
+
+/**
+ * Get Memory By Key Query Result
+ */
+export interface GetMemoryByKeyResult {
+  found: boolean;
+  entry?: MemoryEntry;
+}
+
+/**
+ * Get Memory By Key Query Handler
+ */
+export class GetMemoryByKeyQueryHandler {
+  constructor(private readonly repository: IMemoryRepository) {}
+
+  async execute(input: GetMemoryByKeyInput): Promise<GetMemoryByKeyResult> {
+    const entry = await this.repository.findByKey(input.namespace, input.key);
+
+    if (!entry) {
+      return { found: false };
+    }
+
+    if (!entry.isAccessible()) {
+      return { found: false };
+    }
+
+    if (input.trackAccess) {
+      entry.recordAccess();
+      await this.repository.save(entry);
+    }
+
+    return {
+      found: true,
+      entry,
+    };
+  }
+}