/**
 * Project-Scoped Memory Types
 *
 * Type definitions for the AgentKits memory system.
 * Designed for project-level memory stored in .claude/memory/
 *
 * @module @agentkits/memory/types
 */
/**
 * Memory entry type classification (matches existing .claude/memory/*.md structure)
 */
export type MemoryType = 'episodic' | 'semantic' | 'procedural' | 'working' | 'cache';
/**
 * Access level for memory entries
 */
export type AccessLevel = 'private' | 'project' | 'shared';
/**
 * Distance metrics for vector similarity search
 */
export type DistanceMetric = 'cosine' | 'euclidean' | 'dot' | 'manhattan';
/**
 * 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 type for memory retrieval
 */
export type QueryType = 'semantic' | 'exact' | 'prefix' | 'tag' | 'hybrid';
/**
 * 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>;
}
/**
 * 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;
    /** 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 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;
}
/**
 * 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;
}
/**
 * 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>;
/**
 * Embedding generator function type
 */
export type EmbeddingGenerator = (content: string) => Promise<Float32Array>;
/**
 * Generates a unique memory ID
 */
export declare function generateMemoryId(): string;
/**
 * Generates a unique session ID
 */
export declare function generateSessionId(): string;
/**
 * Creates a default memory entry
 */
export declare function createDefaultEntry(input: MemoryEntryInput): MemoryEntry;
/**
 * Default namespaces matching existing .claude/memory/*.md structure
 */
export declare const DEFAULT_NAMESPACES: {
    readonly CONTEXT: "context";
    readonly ACTIVE: "active-context";
    readonly SESSION: "session-state";
    readonly PROGRESS: "progress";
    readonly PATTERNS: "patterns";
    readonly DECISIONS: "decisions";
    readonly ERRORS: "errors";
};
/**
 * Maps namespace to memory type
 */
export declare const NAMESPACE_TYPE_MAP: Record<string, MemoryType>;
//# sourceMappingURL=types.d.ts.map