@almadar/agent 2.0.0 → 2.0.2

package/dist/memory/MemoryManager.d.ts

@@ -0,0 +1,243 @@
+/**
+ * Memory Manager - GAP-001: Orbital Memory System
+ *
+ * Manages user memory and preferences using Firestore persistence.
+ * Provides the foundation for personalized AI assistance by learning
+ * from user interactions and feedback.
+ */
+import type { UserPreference, GenerationSession, ProjectContext } from './memory-orbital.js';
+import type { UserFeedback, PatternAffinity, InterruptRecord, ToolApprovalPreference, CheckpointRecord } from './types.js';
+/**
+ * Minimal Firestore interface to avoid importing firebase-admin.
+ * These match the interfaces defined in firestore-checkpointer.ts
+ */
+interface FirestoreDb {
+    collection(path: string): FirestoreCollectionRef;
+    batch(): FirestoreBatch;
+}
+interface FirestoreCollectionRef {
+    doc(id: string): FirestoreDocRef;
+    where(field: string, op: string, value: unknown): FirestoreQuery;
+    orderBy(field: string, direction?: string): FirestoreQuery;
+    limit(n: number): FirestoreQuery;
+}
+interface FirestoreDocRef {
+    set(data: unknown): Promise<unknown>;
+    get(): Promise<FirestoreDocSnapshot>;
+    update(data: unknown): Promise<unknown>;
+    delete(): Promise<unknown>;
+}
+interface FirestoreDocSnapshot {
+    exists: boolean;
+    data(): Record<string, unknown> | undefined;
+}
+interface FirestoreQuery {
+    where(field: string, op: string, value: unknown): FirestoreQuery;
+    orderBy(field: string, direction?: string): FirestoreQuery;
+    limit(n: number): FirestoreQuery;
+    startAfter(doc: unknown): FirestoreQuery;
+    get(): Promise<FirestoreQuerySnapshot>;
+}
+interface FirestoreQuerySnapshot {
+    empty: boolean;
+    docs: FirestoreQueryDocSnapshot[];
+    size: number;
+}
+interface FirestoreQueryDocSnapshot {
+    data(): Record<string, unknown>;
+}
+interface FirestoreBatch {
+    set(ref: unknown, data: unknown): void;
+    delete(ref: unknown): void;
+    commit(): Promise<unknown>;
+}
+/**
+ * Options for MemoryManager
+ */
+export interface MemoryManagerOptions {
+    /**
+     * Firestore database instance (injected)
+     */
+    db: FirestoreDb;
+    /**
+     * Collection name for user preferences
+     * @default 'agent_memory_users'
+     */
+    usersCollection?: string;
+    /**
+     * Collection name for generation sessions
+     * @default 'agent_memory_generations'
+     */
+    generationsCollection?: string;
+    /**
+     * Collection name for project context
+     * @default 'agent_memory_projects'
+     */
+    projectsCollection?: string;
+    /**
+     * Collection name for pattern affinity
+     * @default 'agent_memory_patterns'
+     */
+    patternsCollection?: string;
+    /**
+     * Collection name for user feedback
+     * @default 'agent_memory_feedback'
+     */
+    feedbackCollection?: string;
+    /**
+     * Collection name for interrupt records
+     * @default 'agent_memory_interrupts'
+     */
+    interruptsCollection?: string;
+    /**
+     * Collection name for tool approval preferences
+     * @default 'agent_memory_tool_preferences'
+     */
+    toolPreferencesCollection?: string;
+    /**
+     * Collection name for checkpoint records
+     * @default 'agent_memory_checkpoints'
+     */
+    checkpointsCollection?: string;
+}
+export declare class MemoryManager {
+    private db;
+    private usersCollection;
+    private generationsCollection;
+    private projectsCollection;
+    private patternsCollection;
+    private feedbackCollection;
+    private interruptsCollection;
+    private toolPreferencesCollection;
+    private checkpointsCollection;
+    constructor(options: MemoryManagerOptions);
+    /**
+     * Get user preferences with defaults
+     */
+    getUserPreferences(userId: string): Promise<UserPreference | null>;
+    /**
+     * Update user preferences
+     */
+    updateUserPreferences(userId: string, preferences: Partial<Omit<UserPreference, 'id' | 'userId' | 'learnedAt'>>): Promise<void>;
+    /**
+     * Record a new generation session
+     */
+    recordGeneration(userId: string, session: Omit<GenerationSession, 'id' | 'userId' | 'createdAt'>): Promise<string>;
+    /**
+     * Get a specific generation session
+     */
+    getGenerationSession(sessionId: string): Promise<GenerationSession | null>;
+    /**
+     * Get generation history for a user
+     */
+    getUserGenerationHistory(userId: string, limit?: number): Promise<GenerationSession[]>;
+    /**
+     * Update generation session status
+     */
+    updateGenerationStatus(sessionId: string, status: GenerationSession['success'], validationResult?: GenerationSession['validationResult']): Promise<void>;
+    /**
+     * Get project context
+     */
+    getProjectContext(appId: string): Promise<ProjectContext | null>;
+    /**
+     * Update project context with new information
+     */
+    updateProjectContext(appId: string, update: Partial<Omit<ProjectContext, 'id' | 'appId'>>): Promise<void>;
+    /**
+     * Update pattern affinity based on usage
+     */
+    updatePatternAffinity(userId: string, patternId: string, outcome: 'success' | 'failure' | 'partial', context?: {
+        entityType?: string;
+        useCase?: string;
+    }): Promise<void>;
+    /**
+     * Get pattern affinity for a user
+     */
+    getPatternAffinity(userId: string, patternId: string): Promise<PatternAffinity | null>;
+    /**
+     * Get all patterns used by a user
+     */
+    getUserPatterns(userId: string): Promise<PatternAffinity[]>;
+    /**
+     * Record user feedback on a generation
+     */
+    recordFeedback(sessionId: string, feedback: Omit<UserFeedback, 'feedbackId' | 'sessionId' | 'timestamp'>): Promise<void>;
+    /**
+     * Get feedback for a session
+     */
+    getSessionFeedback(sessionId: string): Promise<UserFeedback[]>;
+    private parsePreference;
+    private serializePreference;
+    private parseSession;
+    private serializeSession;
+    private parseContext;
+    private serializeContext;
+    /**
+     * Record an interrupt decision for learning
+     */
+    recordInterruptDecision(sessionId: string, userId: string, interruptData: {
+        toolName: string;
+        toolArgs: Record<string, unknown>;
+        decision: 'approved' | 'rejected' | 'modified';
+        modifiedArgs?: Record<string, unknown>;
+        reason?: string;
+    }): Promise<void>;
+    /**
+     * Get interrupt history for a session
+     */
+    getSessionInterrupts(sessionId: string): Promise<InterruptRecord[]>;
+    /**
+     * Get interrupt history for a user
+     */
+    getUserInterrupts(userId: string, limit?: number): Promise<InterruptRecord[]>;
+    /**
+     * Get tool approval preference for a user
+     */
+    getToolApprovalPreference(userId: string, toolName: string): Promise<ToolApprovalPreference | null>;
+    /**
+     * Update tool approval preference based on interrupt decisions
+     */
+    private updateToolApprovalPreference;
+    /**
+     * Get all tool approval preferences for a user
+     */
+    getUserToolPreferences(userId: string): Promise<ToolApprovalPreference[]>;
+    /**
+     * Check if a tool should be auto-approved for a user
+     */
+    shouldAutoApproveTool(userId: string, toolName: string): Promise<boolean>;
+    /**
+     * Record a checkpoint for learning
+     */
+    recordCheckpoint(userId: string, checkpointData: {
+        checkpointId: string;
+        threadId: string;
+        parentCheckpointId?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * Record a rollback to a checkpoint
+     */
+    recordRollback(userId: string, checkpointId: string, reason?: string): Promise<void>;
+    /**
+     * Mark a checkpoint as successful (terminal state)
+     */
+    markCheckpointSuccessful(userId: string, checkpointId: string): Promise<void>;
+    /**
+     * Get checkpoint history for a user
+     */
+    getUserCheckpoints(userId: string, limit?: number): Promise<CheckpointRecord[]>;
+    /**
+     * Get checkpoints for a thread
+     */
+    getThreadCheckpoints(threadId: string): Promise<CheckpointRecord[]>;
+    /**
+     * Get frequently rolled-back checkpoints (problem areas)
+     */
+    getProblemCheckpoints(userId: string, minRollbackCount?: number): Promise<CheckpointRecord[]>;
+    /**
+     * Get successful checkpoint patterns for learning
+     */
+    getSuccessfulCheckpoints(userId: string, limit?: number): Promise<CheckpointRecord[]>;
+}
+export {};

package/dist/memory/PreferenceLearner.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Preference Learner
+ *
+ * Uses LLM to infer user preferences from generation sessions.
+ * Leverages @almadar/llm for structured output.
+ *
+ * @packageDocumentation
+ */
+import { LLMClient } from '@almadar/llm';
+import type { GenerationSession, UserPreference } from './memory-orbital.js';
+import { MemoryManager } from './MemoryManager.js';
+export interface PreferenceLearnerOptions {
+    /** LLM client for inference */
+    llmClient?: LLMClient;
+    /** Memory manager for persistence */
+    memoryManager: MemoryManager;
+    /** Confidence threshold for auto-accepting preferences */
+    confidenceThreshold?: number;
+}
+export interface InferredPreference {
+    /** The preference field being inferred */
+    field: keyof Omit<UserPreference, 'id' | 'userId' | 'learnedAt'>;
+    /** The inferred value */
+    value: unknown;
+    /** Confidence level (0-1) */
+    confidence: number;
+    /** Explanation of why this was inferred */
+    reasoning: string;
+}
+export interface PreferenceAnalysis {
+    /** List of inferred preferences */
+    inferences: InferredPreference[];
+    /** Whether the inference is high confidence */
+    isHighConfidence: boolean;
+}
+export declare class PreferenceLearner {
+    private llmClient;
+    private memoryManager;
+    private confidenceThreshold;
+    constructor(options: PreferenceLearnerOptions);
+    /**
+     * Analyze a session and infer user preferences
+     */
+    analyzeSession(session: GenerationSession): Promise<PreferenceAnalysis>;
+    /**
+     * Learn from a session and update preferences if confidence is high
+     */
+    learnFromSession(session: GenerationSession): Promise<UserPreference | null>;
+    /**
+     * Batch learn from multiple sessions
+     */
+    batchLearn(sessions: GenerationSession[]): Promise<UserPreference | null>;
+    private buildAnalysisPrompt;
+    private buildAggregatePrompt;
+    private parseAnalysisResponse;
+    private isValidNamingConvention;
+    private isValidValidationStyle;
+}
+export declare function createPreferenceLearner(options: PreferenceLearnerOptions): PreferenceLearner;

package/dist/memory/agentic-search.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Agentic Search - GAP-006
+ *
+ * Reasoning-based search through memory orbitals.
+ * Unlike RAG (vector similarity), this uses agent traversal with understanding
+ * of state transitions, patterns, and temporal relationships.
+ *
+ * @packageDocumentation
+ */
+import type { MemoryManager } from './MemoryManager.js';
+/**
+ * Search strategy for agentic search
+ */
+export type SearchStrategy = 'temporal' | 'semantic' | 'pattern' | 'hybrid';
+/**
+ * Search parameters
+ */
+export interface AgenticSearchParams {
+    /** User to search memory for */
+    userId: string;
+    /** Natural language query */
+    query: string;
+    /** Search strategy */
+    strategy?: SearchStrategy;
+    /** Maximum search depth (levels of traversal) */
+    depth?: number;
+    /** App/project context to filter by */
+    appId?: string;
+    /** Maximum results to return */
+    limit?: number;
+}
+/**
+ * Search result with relevance score
+ */
+export interface SearchResult {
+    /** Type of memory found */
+    type: 'preference' | 'session' | 'project' | 'interrupt' | 'checkpoint' | 'pattern';
+    /** The actual data */
+    data: unknown;
+    /** Relevance score (0-1) */
+    relevance: number;
+    /** Why this result matched */
+    reasoning: string;
+    /** Source collection */
+    source: string;
+    /** Timestamp for temporal sorting */
+    timestamp?: Date;
+}
+/**
+ * Search result with aggregated insights
+ */
+export interface AgenticSearchResponse {
+    /** Individual search results */
+    results: SearchResult[];
+    /** Aggregated insights from results */
+    insights: {
+        /** Summary of what was found */
+        summary: string;
+        /** Common patterns identified */
+        patterns: string[];
+        /** Temporal trends */
+        trends: string[];
+        /** Suggested next actions */
+        suggestions: string[];
+    };
+    /** Search metadata */
+    metadata: {
+        strategy: SearchStrategy;
+        depth: number;
+        duration: number;
+        totalResults: number;
+    };
+}
+export declare class AgenticSearchEngine {
+    private memoryManager;
+    constructor(memoryManager: MemoryManager);
+    /**
+     * Perform agentic search through memory
+     */
+    search(params: AgenticSearchParams): Promise<AgenticSearchResponse>;
+    /**
+     * Temporal search - "What did I do last week?"
+     * Navigates memory by time relationships
+     */
+    private temporalSearch;
+    /**
+     * Semantic search - "How did I handle user roles?"
+     * Reasoning-based understanding of structure
+     */
+    private semanticSearch;
+    /**
+     * Pattern search - "Show me all list views I've built"
+     * Searches for specific patterns and effects
+     */
+    private patternSearch;
+    /**
+     * Hybrid search - combines all strategies
+     */
+    private hybridSearch;
+    /**
+     * Extract semantic concepts from query
+     */
+    private extractConcepts;
+    /**
+     * Extract potential entity names from query
+     */
+    private extractEntityNames;
+    /**
+     * Generate insights from search results
+     */
+    private generateInsights;
+}
+/**
+ * Create an agentic search engine
+ */
+export declare function createAgenticSearchEngine(memoryManager: MemoryManager): AgenticSearchEngine;

package/dist/memory/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Memory System - GAP-001: Orbital Memory System
+ *
+ * Revolutionary memory storage using `.orb` files instead of RAG/vector DB.
+ * Memory is structured as orbital schemas with temporal state machines.
+ */
+export { MemoryOrbitalSchema, UserPreferenceEntity, GenerationSessionEntity, ProjectContextEntity, type UserPreference, type GenerationSession, type ProjectContext, } from './memory-orbital.js';
+export { MemoryManager, type MemoryManagerOptions, } from './MemoryManager.js';
+export { PreferenceLearner, createPreferenceLearner, type PreferenceLearnerOptions, type InferredPreference, type PreferenceAnalysis, } from './PreferenceLearner.js';
+export { AgenticSearchEngine, createAgenticSearchEngine, type SearchStrategy, type AgenticSearchParams, type SearchResult, type AgenticSearchResponse, } from './agentic-search.js';
+export { ObservabilityCollector, getObservabilityCollector, resetObservabilityCollector, recordEvent, startObservabilitySession, endObservabilitySession, getPerformanceSnapshot, type ObservableEventType, type ObservableEvent, type SessionTelemetry, type PerformanceSnapshot, type HealthCheckResult, } from '../observability.js';
+export { MultiUserManager, getMultiUserManager, resetMultiUserManager, createUserContext, isAdmin, requireOwnership, type UserContext, type ScopedSessionMetadata, type AccessCheckResult, type UserSessionStats, } from '../multi-user.js';
+export { StateSyncManager, getStateSyncManager, resetStateSyncManager, withSync, debounceSync, type StateChangeType, type StateChangeEvent, type VersionVector, type StateSyncSnapshot, type ConflictResolution, type StateSyncConfig, } from '../state-sync.js';
+export type { UserFeedback, PatternAffinity, InterruptRecord, ToolApprovalPreference, CheckpointRecord, } from './types.js';

package/dist/memory/memory-orbital.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Memory Orbital Schema
+ *
+ * Defines the structure for agent memory using Orbital types.
+ * This is an OrbitalSchema that represents user memory, preferences,
+ * and generation history.
+ *
+ * @packageDocumentation
+ */
+import type { OrbitalSchema, Entity } from '@almadar/core';
+/**
+ * User preference entity - stores learned or explicit preferences
+ */
+export declare const UserPreferenceEntity: Entity;
+/**
+ * Generation session entity - stores history of generations
+ */
+export declare const GenerationSessionEntity: Entity;
+/**
+ * Project context entity - stores project-specific conventions
+ */
+export declare const ProjectContextEntity: Entity;
+/**
+ * The complete Memory Orbital Schema
+ * This defines the structure for storing agent memory
+ */
+export declare const MemoryOrbitalSchema: OrbitalSchema;
+export type UserPreference = {
+    id: string;
+    userId: string;
+    namingConvention: 'PascalCase' | 'camelCase' | 'snake_case';
+    validationStyle: 'strict' | 'minimal' | 'none';
+    preferredPatterns: string[];
+    commonEntities: string[];
+    commonTraits: string[];
+    learnedAt: Date;
+    confidence: number;
+};
+export type GenerationSession = {
+    id: string;
+    userId: string;
+    threadId: string;
+    prompt: string;
+    skill: string;
+    generatedSchema?: Record<string, unknown>;
+    entities: string[];
+    patterns: string[];
+    validationResult?: {
+        valid: boolean;
+        errors: unknown[];
+    };
+    createdAt: Date;
+    completedAt?: Date;
+    success: boolean;
+};
+export type ProjectContext = {
+    id: string;
+    appId: string;
+    userId: string;
+    projectName?: string;
+    description?: string;
+    existingEntities: string[];
+    conventions: string[];
+    domain: 'business' | 'ecommerce' | 'cms' | 'dashboard' | 'workflow';
+    lastUpdatedAt: Date;
+};

package/dist/memory/types.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Memory System Types
+ *
+ * Additional types for the memory system beyond the core orbital types.
+ */
+/**
+ * User feedback on a generation session
+ */
+export interface UserFeedback {
+    /** Unique feedback ID */
+    feedbackId: string;
+    /** Session this feedback is for */
+    sessionId: string;
+    /** User who gave the feedback */
+    userId: string;
+    /** Type of feedback */
+    type: 'positive' | 'negative' | 'correction' | 'suggestion';
+    /** Optional comment */
+    comment?: string;
+    /** Suggested correction or improvement */
+    suggestion?: string;
+    /** Timestamp of feedback */
+    timestamp: Date;
+}
+/**
+ * Pattern affinity - tracks how well patterns work for a user
+ */
+export interface PatternAffinity {
+    /** User ID */
+    userId: string;
+    /** Pattern ID */
+    patternId: string;
+    /** How many times used */
+    usageCount: number;
+    /** Successful uses */
+    successCount: number;
+    /** Failed uses */
+    failureCount: number;
+    /** Contexts where this pattern was used */
+    contexts?: {
+        entityType?: string;
+        useCase?: string;
+    }[];
+    /** Last time this pattern was used */
+    lastUsedAt: Date;
+    /** When tracking started */
+    createdAt: Date;
+}
+/**
+ * Generation record - summary of a generation for history
+ */
+export interface GenerationRecord {
+    /** Unique session ID */
+    sessionId: string;
+    /** User who initiated */
+    userId: string;
+    /** App/project context */
+    appId: string;
+    /** Input description/prompt */
+    inputDescription: string;
+    /** Resulting orbital name */
+    generatedOrbital: string;
+    /** Patterns that were used */
+    patternsUsed: string[];
+    /** Generation status */
+    status: 'pending' | 'completed' | 'error' | 'revised';
+    /** When generation started */
+    startedAt: Date;
+    /** When generation completed */
+    completedAt?: Date;
+    /** Number of revisions */
+    revisionCount: number;
+    /** Error message if failed */
+    errorMessage?: string;
+}
+/**
+ * Checkpoint record - tracks checkpoint history for learning
+ */
+export interface CheckpointRecord {
+    /** Unique checkpoint ID */
+    checkpointId: string;
+    /** Thread/session ID */
+    threadId: string;
+    /** User who owns this checkpoint */
+    userId: string;
+    /** Parent checkpoint ID (for rollback tracking) */
+    parentCheckpointId?: string;
+    /** Checkpoint metadata */
+    metadata: {
+        step?: number;
+        skill?: string;
+        status?: string;
+        [key: string]: unknown;
+    };
+    /** When checkpoint was created */
+    createdAt: Date;
+    /** Number of times rolled back to this checkpoint */
+    rollbackCount: number;
+    /** Whether this checkpoint was a successful outcome */
+    wasSuccessful: boolean;
+}
+/**
+ * Interrupt record - tracks human-in-the-loop decisions
+ */
+export interface InterruptRecord {
+    /** Unique interrupt ID */
+    interruptId: string;
+    /** Session this interrupt occurred in */
+    sessionId: string;
+    /** User who made the decision */
+    userId: string;
+    /** Tool that was interrupted */
+    toolName: string;
+    /** Tool arguments that were being executed */
+    toolArgs: Record<string, unknown>;
+    /** User's decision: approved, rejected, or modified */
+    decision: 'approved' | 'rejected' | 'modified';
+    /** Modified arguments if decision was 'modified' */
+    modifiedArgs?: Record<string, unknown>;
+    /** Reason for the decision */
+    reason?: string;
+    /** Timestamp of the interrupt */
+    timestamp: Date;
+}
+/**
+ * Tool approval preferences - learned from interrupt history
+ */
+export interface ToolApprovalPreference {
+    /** User ID */
+    userId: string;
+    /** Tool name */
+    toolName: string;
+    /** Auto-approve this tool in the future */
+    autoApprove: boolean;
+    /** Confidence in this preference (0-1) */
+    confidence: number;
+    /** Number of times this tool has been approved */
+    approvedCount: number;
+    /** Number of times this tool has been rejected */
+    rejectedCount: number;
+    /** Last decision timestamp */
+    lastDecisionAt: Date;
+}