@aitytech/agentkits-memory 1.0.0

package/src/types.ts

@@ -0,0 +1,715 @@
+/**
+ * Project-Scoped Memory Types
+ *
+ * Type definitions for the AgentKits memory system.
+ * Designed for project-level memory stored in .claude/memory/
+ *
+ * @module @agentkits/memory/types
+ */
+
+// ===== Core Memory Entry Types =====
+
+/**
+ * Memory entry type classification (matches existing .claude/memory/*.md structure)
+ */
+export type MemoryType =
+  | 'episodic'    // Time-based: active-context, session-state, progress
+  | 'semantic'    // Facts: project-context, patterns
+  | 'procedural'  // How-to: decisions, errors
+  | 'working'     // Short-term operational memory
+  | 'cache';      // Temporary cached data
+
+/**
+ * Access level for memory entries
+ */
+export type AccessLevel =
+  | 'private'     // Only this session
+  | 'project'     // All sessions in this project
+  | 'shared';     // Shared across projects (future)
+
+/**
+ * Distance metrics for vector similarity search
+ */
+export type DistanceMetric =
+  | 'cosine'      // Cosine similarity (default)
+  | 'euclidean'   // Euclidean distance (L2)
+  | 'dot'         // Dot product
+  | 'manhattan';  // Manhattan distance (L1)
+
+// ===== Memory Entry =====
+
+/**
+ * Core memory entry structure with optional vector embedding
+ */
+export interface MemoryEntry {
+  /** Unique identifier */
+  id: string;
+
+  /** Human-readable key for retrieval (e.g., 'active-context', 'auth-pattern') */
+  key: string;
+
+  /** Actual content of the memory */
+  content: string;
+
+  /** Vector embedding for semantic search (Float32Array for efficiency) */
+  embedding?: Float32Array;
+
+  /** Type of memory */
+  type: MemoryType;
+
+  /** Namespace for organization (maps to old .md file categories) */
+  namespace: string;
+
+  /** Tags for categorization and filtering */
+  tags: string[];
+
+  /** Additional metadata */
+  metadata: Record<string, unknown>;
+
+  /** Session ID that created this entry */
+  sessionId?: string;
+
+  /** Owner ID for multi-user scenarios */
+  ownerId?: string;
+
+  /** Access level */
+  accessLevel: AccessLevel;
+
+  /** Creation timestamp */
+  createdAt: number;
+
+  /** Last update timestamp */
+  updatedAt: number;
+
+  /** Expiration timestamp (optional) */
+  expiresAt?: number;
+
+  /** Version number for optimistic locking */
+  version: number;
+
+  /** References to other memory entries */
+  references: string[];
+
+  /** Access count for usage tracking */
+  accessCount: number;
+
+  /** Last access timestamp */
+  lastAccessedAt: number;
+}
+
+/**
+ * Input for creating a new memory entry
+ */
+export interface MemoryEntryInput {
+  key: string;
+  content: string;
+  type?: MemoryType;
+  namespace?: string;
+  tags?: string[];
+  metadata?: Record<string, unknown>;
+  sessionId?: string;
+  accessLevel?: AccessLevel;
+  expiresAt?: number;
+  references?: string[];
+}
+
+/**
+ * Partial update for a memory entry
+ */
+export interface MemoryEntryUpdate {
+  content?: string;
+  tags?: string[];
+  metadata?: Record<string, unknown>;
+  accessLevel?: AccessLevel;
+  expiresAt?: number;
+  references?: string[];
+}
+
+// ===== Query Types =====
+
+/**
+ * Query type for memory retrieval
+ */
+export type QueryType =
+  | 'semantic'    // Vector similarity search
+  | 'exact'       // Exact key match
+  | 'prefix'      // Key prefix match
+  | 'tag'         // Tag-based search
+  | 'hybrid';     // Combined semantic + filters
+
+/**
+ * Memory query specification
+ */
+export interface MemoryQuery {
+  /** Type of query to perform */
+  type: QueryType;
+
+  /** Content for semantic search (will be embedded) */
+  content?: string;
+
+  /** Pre-computed embedding for semantic search */
+  embedding?: Float32Array;
+
+  /** Exact key to match */
+  key?: string;
+
+  /** Key prefix to match */
+  keyPrefix?: string;
+
+  /** Namespace filter */
+  namespace?: string;
+
+  /** Tag filters (entries must have all specified tags) */
+  tags?: string[];
+
+  /** Memory type filter */
+  memoryType?: MemoryType;
+
+  /** Session ID filter */
+  sessionId?: string;
+
+  /** Owner ID filter */
+  ownerId?: string;
+
+  /** Access level filter */
+  accessLevel?: AccessLevel;
+
+  /** Metadata filters */
+  metadata?: Record<string, unknown>;
+
+  /** Time range filters */
+  createdAfter?: number;
+  createdBefore?: number;
+  updatedAfter?: number;
+  updatedBefore?: number;
+
+  /** Maximum number of results */
+  limit: number;
+
+  /** Offset for pagination */
+  offset?: number;
+
+  /** Minimum similarity threshold (0-1) for semantic search */
+  threshold?: number;
+
+  /** Include expired entries */
+  includeExpired?: boolean;
+
+  /** Distance metric for semantic search */
+  distanceMetric?: DistanceMetric;
+}
+
+/**
+ * Search result with similarity score
+ */
+export interface SearchResult {
+  /** The memory entry */
+  entry: MemoryEntry;
+
+  /** Similarity score (0-1, higher is better) */
+  score: number;
+
+  /** Distance from query vector */
+  distance: number;
+}
+
+/**
+ * Search options for vector search
+ */
+export interface SearchOptions {
+  /** Number of results to return */
+  k: number;
+
+  /** Minimum similarity threshold (0-1) */
+  threshold?: number;
+
+  /** Distance metric */
+  metric?: DistanceMetric;
+
+  /** Additional filters to apply post-search */
+  filters?: Partial<MemoryQuery>;
+}
+
+// ===== HNSW Index Types =====
+
+/**
+ * Quantization type
+ */
+export type QuantizationType = 'scalar' | 'product' | 'binary' | 'none';
+
+/**
+ * Quantization configuration for vector compression
+ */
+export interface QuantizationConfig {
+  /** Enable quantization */
+  enabled: boolean;
+
+  /** Number of bits per dimension (default: 8) */
+  bits: number;
+
+  /** Quantization method */
+  method: 'scalar' | 'product';
+
+  /** Quantization type (alternative to method) */
+  type?: QuantizationType;
+
+  /** Number of subquantizers for product quantization */
+  subquantizers?: number;
+}
+
+/**
+ * HNSW index configuration
+ */
+export interface HNSWConfig {
+  /** Vector dimensions (e.g., 384 for local models, 1536 for OpenAI) */
+  dimensions: number;
+
+  /** Maximum number of connections per layer (default: 16) */
+  M: number;
+
+  /** Size of the dynamic candidate list during construction (default: 200) */
+  efConstruction: number;
+
+  /** Maximum elements the index can hold */
+  maxElements: number;
+
+  /** Distance metric */
+  metric: DistanceMetric;
+
+  /** Quantization configuration */
+  quantization?: QuantizationConfig;
+}
+
+/**
+ * HNSW index statistics
+ */
+export interface HNSWStats {
+  /** Total number of vectors in the index */
+  vectorCount: number;
+
+  /** Memory usage in bytes */
+  memoryUsage: number;
+
+  /** Average search time in milliseconds */
+  avgSearchTime: number;
+
+  /** Index build time in milliseconds */
+  buildTime: number;
+
+  /** Compression ratio if quantization is enabled */
+  compressionRatio?: number;
+}
+
+// ===== Backend Interface =====
+
+/**
+ * Memory backend interface for storage and retrieval
+ */
+export interface IMemoryBackend {
+  /** Initialize the backend */
+  initialize(): Promise<void>;
+
+  /** Shutdown the backend */
+  shutdown(): Promise<void>;
+
+  /** Store a memory entry */
+  store(entry: MemoryEntry): Promise<void>;
+
+  /** Retrieve a memory entry by ID */
+  get(id: string): Promise<MemoryEntry | null>;
+
+  /** Retrieve a memory entry by key within a namespace */
+  getByKey(namespace: string, key: string): Promise<MemoryEntry | null>;
+
+  /** Update a memory entry */
+  update(id: string, update: MemoryEntryUpdate): Promise<MemoryEntry | null>;
+
+  /** Delete a memory entry */
+  delete(id: string): Promise<boolean>;
+
+  /** Query memory entries */
+  query(query: MemoryQuery): Promise<MemoryEntry[]>;
+
+  /** Semantic vector search */
+  search(embedding: Float32Array, options: SearchOptions): Promise<SearchResult[]>;
+
+  /** Bulk insert entries */
+  bulkInsert(entries: MemoryEntry[]): Promise<void>;
+
+  /** Bulk delete entries */
+  bulkDelete(ids: string[]): Promise<number>;
+
+  /** Get entry count */
+  count(namespace?: string): Promise<number>;
+
+  /** List all namespaces */
+  listNamespaces(): Promise<string[]>;
+
+  /** Clear all entries in a namespace */
+  clearNamespace(namespace: string): Promise<number>;
+
+  /** Get backend statistics */
+  getStats(): Promise<BackendStats>;
+
+  /** Perform health check */
+  healthCheck(): Promise<HealthCheckResult>;
+}
+
+/**
+ * Backend statistics
+ */
+export interface BackendStats {
+  /** Total number of entries */
+  totalEntries: number;
+
+  /** Entries by namespace */
+  entriesByNamespace: Record<string, number>;
+
+  /** Entries by type */
+  entriesByType: Record<MemoryType, number>;
+
+  /** Total memory usage in bytes */
+  memoryUsage: number;
+
+  /** HNSW index statistics */
+  hnswStats?: HNSWStats;
+
+  /** Cache statistics */
+  cacheStats?: CacheStats;
+
+  /** Average query time in milliseconds */
+  avgQueryTime: number;
+
+  /** Average search time in milliseconds */
+  avgSearchTime: number;
+}
+
+/**
+ * Health check result
+ */
+export interface HealthCheckResult {
+  /** Overall health status */
+  status: 'healthy' | 'degraded' | 'unhealthy';
+
+  /** Individual component health */
+  components: {
+    storage: ComponentHealth;
+    index: ComponentHealth;
+    cache: ComponentHealth;
+  };
+
+  /** Health check timestamp */
+  timestamp: number;
+
+  /** Any issues detected */
+  issues: string[];
+
+  /** Recommendations for improvement */
+  recommendations: string[];
+}
+
+/**
+ * Individual component health status
+ */
+export interface ComponentHealth {
+  status: 'healthy' | 'degraded' | 'unhealthy';
+  latency: number;
+  message?: string;
+}
+
+// ===== Cache Types =====
+
+/**
+ * Cache configuration
+ */
+export interface CacheConfig {
+  /** Maximum number of entries in the cache */
+  maxSize: number;
+
+  /** Default TTL in milliseconds */
+  ttl: number;
+
+  /** Enable LRU eviction */
+  lruEnabled: boolean;
+
+  /** Maximum memory usage in bytes */
+  maxMemory?: number;
+
+  /** Enable write-through caching (write to backend immediately) */
+  writeThrough?: boolean;
+}
+
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+  /** Number of entries in cache */
+  size: number;
+
+  /** Cache hit rate (0-1) */
+  hitRate: number;
+
+  /** Total cache hits */
+  hits: number;
+
+  /** Total cache misses */
+  misses: number;
+
+  /** Total evictions */
+  evictions: number;
+
+  /** Memory usage in bytes */
+  memoryUsage: number;
+}
+
+/**
+ * Cached entry wrapper
+ */
+export interface CachedEntry<T> {
+  /** The cached data */
+  data: T;
+
+  /** When the entry was cached */
+  cachedAt: number;
+
+  /** When the entry expires */
+  expiresAt: number;
+
+  /** Last access timestamp */
+  lastAccessedAt: number;
+
+  /** Access count */
+  accessCount: number;
+}
+
+// ===== Migration Types =====
+
+/**
+ * Migration source type
+ */
+export type MigrationSource =
+  | 'markdown'    // .claude/memory/*.md files
+  | 'json'        // JSON exports
+  | 'sqlite';     // Existing SQLite databases
+
+/**
+ * Migration configuration
+ */
+export interface MigrationConfig {
+  /** Source backend type */
+  source: MigrationSource;
+
+  /** Source path or connection string */
+  sourcePath: string;
+
+  /** Batch size for migration */
+  batchSize: number;
+
+  /** Generate embeddings during migration */
+  generateEmbeddings: boolean;
+
+  /** Validate data during migration */
+  validateData: boolean;
+
+  /** Continue on error */
+  continueOnError: boolean;
+
+  /** Namespace mapping */
+  namespaceMapping?: Record<string, string>;
+
+  /** Type mapping */
+  typeMapping?: Record<string, MemoryType>;
+}
+
+/**
+ * Migration progress
+ */
+export interface MigrationProgress {
+  /** Total entries to migrate */
+  total: number;
+
+  /** Entries migrated so far */
+  migrated: number;
+
+  /** Entries failed */
+  failed: number;
+
+  /** Entries skipped */
+  skipped: number;
+
+  /** Progress percentage (0-100) */
+  percentage: number;
+
+  /** Errors encountered */
+  errors: MigrationError[];
+}
+
+/**
+ * Migration error
+ */
+export interface MigrationError {
+  /** Entry ID or key that failed */
+  entryId: string;
+
+  /** Error message */
+  message: string;
+
+  /** Error code */
+  code: string;
+
+  /** Whether the error is recoverable */
+  recoverable: boolean;
+}
+
+/**
+ * Migration result
+ */
+export interface MigrationResult {
+  /** Whether migration completed successfully */
+  success: boolean;
+
+  /** Final progress state */
+  progress: MigrationProgress;
+
+  /** Total time taken in milliseconds */
+  duration: number;
+
+  /** Summary message */
+  summary: string;
+}
+
+// ===== Session Types =====
+
+/**
+ * Session information for tracking Claude Code sessions
+ */
+export interface SessionInfo {
+  /** Session ID */
+  id: string;
+
+  /** Session start time */
+  startedAt: number;
+
+  /** Session end time (if ended) */
+  endedAt?: number;
+
+  /** Summary of work done */
+  summary?: string;
+
+  /** Status */
+  status: 'active' | 'completed' | 'abandoned';
+
+  /** Last checkpoint */
+  lastCheckpoint?: string;
+}
+
+// ===== Event Types =====
+
+/**
+ * Memory event types for index operations
+ */
+export type MemoryEventType =
+  | 'insert'
+  | 'update'
+  | 'delete'
+  | 'search'
+  | 'rebuild'
+  | 'resize';
+
+/**
+ * Memory event for tracking index operations
+ */
+export interface MemoryEvent {
+  /** Event type */
+  type: MemoryEventType;
+
+  /** Entry ID (if applicable) */
+  entryId?: string;
+
+  /** Timestamp */
+  timestamp: number;
+
+  /** Additional event data */
+  data?: Record<string, unknown>;
+}
+
+/**
+ * Handler function for memory events
+ */
+export type MemoryEventHandler = (event: MemoryEvent) => void | Promise<void>;
+
+// ===== Utility Types =====
+
+/**
+ * Embedding generator function type
+ */
+export type EmbeddingGenerator = (content: string) => Promise<Float32Array>;
+
+/**
+ * Generates a unique memory ID
+ */
+export function generateMemoryId(): string {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substring(2, 10);
+  return `mem_${timestamp}_${random}`;
+}
+
+/**
+ * Generates a unique session ID
+ */
+export function generateSessionId(): string {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substring(2, 6);
+  return `ses_${timestamp}_${random}`;
+}
+
+/**
+ * Creates a default memory entry
+ */
+export function createDefaultEntry(input: MemoryEntryInput): MemoryEntry {
+  const now = Date.now();
+  return {
+    id: generateMemoryId(),
+    key: input.key,
+    content: input.content,
+    type: input.type || 'semantic',
+    namespace: input.namespace || 'default',
+    tags: input.tags || [],
+    metadata: input.metadata || {},
+    sessionId: input.sessionId,
+    accessLevel: input.accessLevel || 'project',
+    createdAt: now,
+    updatedAt: now,
+    expiresAt: input.expiresAt,
+    version: 1,
+    references: input.references || [],
+    accessCount: 0,
+    lastAccessedAt: now,
+  };
+}
+
+/**
+ * Default namespaces matching existing .claude/memory/*.md structure
+ */
+export const DEFAULT_NAMESPACES = {
+  CONTEXT: 'context',           // project-context.md
+  ACTIVE: 'active-context',     // active-context.md
+  SESSION: 'session-state',     // session-state.md
+  PROGRESS: 'progress',         // progress.md
+  PATTERNS: 'patterns',         // patterns.md
+  DECISIONS: 'decisions',       // decisions.md
+  ERRORS: 'errors',             // errors.md
+} as const;
+
+/**
+ * Maps namespace to memory type
+ */
+export const NAMESPACE_TYPE_MAP: Record<string, MemoryType> = {
+  [DEFAULT_NAMESPACES.CONTEXT]: 'semantic',
+  [DEFAULT_NAMESPACES.ACTIVE]: 'episodic',
+  [DEFAULT_NAMESPACES.SESSION]: 'episodic',
+  [DEFAULT_NAMESPACES.PROGRESS]: 'episodic',
+  [DEFAULT_NAMESPACES.PATTERNS]: 'semantic',
+  [DEFAULT_NAMESPACES.DECISIONS]: 'procedural',
+  [DEFAULT_NAMESPACES.ERRORS]: 'procedural',
+};