@revealui/ai 0.1.0

package/dist/memory/stores/episodic-memory.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Episodic Memory
+ *
+ * Long-term memory for conversation history and agent memories.
+ * Uses ORSet for collection management and PNCounter for access metrics.
+ *
+ * Key challenge: Bridge ORSet state (which memories exist) with
+ * agent_memories table (which stores individual memory records with vectors).
+ */
+import type { AgentMemory } from '@revealui/contracts/agents';
+import type { Database } from '@revealui/db/client';
+import { type ORSetData } from '../crdt/or-set.js';
+import { type PNCounterData } from '../crdt/pn-counter.js';
+import type { CRDTPersistence } from '../persistence/crdt-persistence.js';
+import { type VectorSearchOptions } from '../vector/vector-memory-service.js';
+export interface EpisodicMemoryData {
+    userId: string;
+    nodeId: string;
+    memories: ORSetData<string>;
+    accessCounter: PNCounterData;
+}
+/**
+ * Episodic Memory for long-term agent memory storage.
+ *
+ * @example
+ * ```typescript
+ * const memory = new EpisodicMemory('user-123', 'node-abc', db, persistence)
+ * await memory.load()
+ *
+ * const memoryId = await memory.add({
+ *   id: 'mem-1',
+ *   content: 'User prefers dark theme',
+ *   type: 'preference',
+ *   // ... other fields
+ * })
+ *
+ * const all = memory.getAll()
+ * await memory.save()
+ * ```
+ */
+export declare class EpisodicMemory {
+    private memories;
+    private accessCounter;
+    private userId;
+    private nodeId;
+    private db;
+    private persistence?;
+    private memoryCache;
+    private vectorService;
+    /**
+     * Creates a new EpisodicMemory instance.
+     *
+     * @param userId - User identifier
+     * @param nodeId - Node identifier (for CRDT operations)
+     * @param db - Database client (REST DB for CRDT persistence)
+     * @param persistence - Optional persistence adapter
+     */
+    constructor(userId: string, nodeId: string, db: Database, persistence?: CRDTPersistence);
+    /**
+     * Adds a memory to the collection.
+     * Stores the memory in vector database (Supabase) and adds its ID to ORSet.
+     *
+     * @param memory - Memory to add
+     * @returns Tag for this memory addition (for removal)
+     */
+    add(memory: AgentMemory): Promise<string>;
+    /**
+     * Removes a memory by tag.
+     *
+     * @param tag - Tag returned from add()
+     * @returns true if memory was removed
+     */
+    remove(tag: string): boolean;
+    /**
+     * Removes a memory by ID (removes all instances).
+     * Also deletes from database.
+     *
+     * @param memoryId - Memory ID to remove
+     * @returns Number of instances removed
+     */
+    removeById(memoryId: string): Promise<number>;
+    /**
+     * Gets all memory IDs in the set.
+     *
+     * @returns Array of memory IDs
+     */
+    getMemoryIds(): string[];
+    /**
+     * Gets all memories (loads from database if not cached).
+     *
+     * @returns Array of memory objects
+     */
+    getAll(): Promise<AgentMemory[]>;
+    /**
+     * Gets a specific memory by ID.
+     *
+     * @param memoryId - Memory ID
+     * @returns Memory or null if not found
+     */
+    get(memoryId: string): Promise<AgentMemory | null>;
+    /**
+     * Updates a memory by ID.
+     * Merges partial data with the current memory, persists to vector store,
+     * and refreshes the cache. Eliminates the need for callers to access
+     * private fields or instantiate VectorMemoryService directly.
+     *
+     * @param memoryId - Memory ID to update
+     * @param data - Partial memory data to merge
+     * @returns Updated memory
+     * @throws Error if memory not found in this user's ORSet
+     */
+    update(memoryId: string, data: Partial<AgentMemory>): Promise<AgentMemory>;
+    /**
+     * Increments access counter and updates memory access tracking.
+     *
+     * @param memoryId - Optional memory ID to track access for
+     */
+    incrementAccess(memoryId?: string): Promise<void>;
+    /**
+     * Gets the total access count.
+     *
+     * @returns Total access count
+     */
+    getAccessCount(): number;
+    /**
+     * Searches memories using vector similarity search.
+     *
+     * @param query - Search query text
+     * @param options - Search options (limit, threshold, filters)
+     * @returns Array of matching memories sorted by relevance
+     */
+    search(query: string, options?: Omit<VectorSearchOptions, 'userId'>): Promise<AgentMemory[]>;
+    /**
+     * Merges another EpisodicMemory into this one.
+     *
+     * @param other - EpisodicMemory to merge
+     * @returns New merged EpisodicMemory
+     */
+    merge(other: EpisodicMemory): EpisodicMemory;
+    /**
+     * Loads state from database.
+     *
+     * @throws Error if persistence is not configured
+     */
+    load(): Promise<void>;
+    /**
+     * Saves state to database.
+     *
+     * @throws Error if persistence is not configured
+     */
+    save(): Promise<void>;
+    /**
+     * Serializes EpisodicMemory to plain object.
+     *
+     * @returns Serialized data
+     */
+    toData(): EpisodicMemoryData;
+    /**
+     * Deserializes EpisodicMemory from plain object.
+     *
+     * @param data - Serialized data
+     * @param db - Database client
+     * @param persistence - Optional persistence adapter
+     * @returns New EpisodicMemory instance
+     */
+    static fromData(data: EpisodicMemoryData, db: Database, persistence?: CRDTPersistence): EpisodicMemory;
+    /**
+     * Creates a copy of this EpisodicMemory.
+     *
+     * @returns New EpisodicMemory with same state
+     */
+    clone(): EpisodicMemory;
+    /**
+     * Gets the user ID.
+     */
+    getUserId(): string;
+    /**
+     * Gets the node ID.
+     */
+    getNodeId(): string;
+}
+//# sourceMappingURL=episodic-memory.d.ts.map

package/dist/memory/stores/episodic-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"episodic-memory.d.ts","sourceRoot":"","sources":["../../../src/memory/stores/episodic-memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAA;AAE7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAGnD,OAAO,EAAS,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAA;AACzD,OAAO,EAAa,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAA;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAA;AACzE,OAAO,EAAuB,KAAK,mBAAmB,EAAE,MAAM,oCAAoC,CAAA;AAMlG,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,SAAS,CAAC,MAAM,CAAC,CAAA;IAC3B,aAAa,EAAE,aAAa,CAAA;CAC7B;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAe;IAC/B,OAAO,CAAC,aAAa,CAAW;IAChC,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,EAAE,CAAU;IACpB,OAAO,CAAC,WAAW,CAAC,CAAiB;IACrC,OAAO,CAAC,WAAW,CAAsC;IACzD,OAAO,CAAC,aAAa,CAAqB;IAE1C;;;;;;;OAOG;gBACS,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,WAAW,CAAC,EAAE,eAAe;IAYvF;;;;;;OAMG;IACG,GAAG,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IA+B/C;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAU5B;;;;;;OAMG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAqBnD;;;;OAIG;IACH,YAAY,IAAI,MAAM,EAAE;IAIxB;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAwBtC;;;;;OAKG;IACG,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAuBxD;;;;;;;;;;OAUG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC;IAgBhF;;;;OAIG;IACG,eAAe,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBvD;;;;OAIG;IACH,cAAc,IAAI,MAAM;IAIxB;;;;;;OAMG;IACG,MAAM,CACV,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,IAAI,CAAC,mBAAmB,EAAE,QAAQ,CAAM,GAChD,OAAO,CAAC,WAAW,EAAE,CAAC;IAsBzB;;;;;OAKG;IACH,KAAK,CAAC,KAAK,EAAE,cAAc,GAAG,cAAc;IAO5C;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA4B3B;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAc3B;;;;OAIG;IACH,MAAM,IAAI,kBAAkB;IAS5B;;;;;;;OAOG;IACH,MAAM,CAAC,QAAQ,CACb,IAAI,EAAE,kBAAkB,EACxB,EAAE,EAAE,QAAQ,EACZ,WAAW,CAAC,EAAE,eAAe,GAC5B,cAAc;IAOjB;;;;OAIG;IACH,KAAK,IAAI,cAAc;IAIvB;;OAEG;IACH,SAAS,IAAI,MAAM;IAInB;;OAEG;IACH,SAAS,IAAI,MAAM;CAGpB"}

package/dist/memory/stores/episodic-memory.js

@@ -0,0 +1,378 @@
+/**
+ * Episodic Memory
+ *
+ * Long-term memory for conversation history and agent memories.
+ * Uses ORSet for collection management and PNCounter for access metrics.
+ *
+ * Key challenge: Bridge ORSet state (which memories exist) with
+ * agent_memories table (which stores individual memory records with vectors).
+ */
+import { EmbeddingSchema } from '@revealui/contracts/representation';
+import { generateEmbedding } from '../../embeddings/index.js';
+import { ORSet } from '../crdt/or-set.js';
+import { PNCounter } from '../crdt/pn-counter.js';
+import { VectorMemoryService } from '../vector/vector-memory-service.js';
+// =============================================================================
+// Episodic Memory
+// =============================================================================
+/**
+ * Episodic Memory for long-term agent memory storage.
+ *
+ * @example
+ * ```typescript
+ * const memory = new EpisodicMemory('user-123', 'node-abc', db, persistence)
+ * await memory.load()
+ *
+ * const memoryId = await memory.add({
+ *   id: 'mem-1',
+ *   content: 'User prefers dark theme',
+ *   type: 'preference',
+ *   // ... other fields
+ * })
+ *
+ * const all = memory.getAll()
+ * await memory.save()
+ * ```
+ */
+export class EpisodicMemory {
+    memories; // Stores memory IDs
+    accessCounter;
+    userId;
+    nodeId;
+    db; // REST DB for CRDT persistence
+    persistence;
+    memoryCache = new Map();
+    vectorService; // Vector DB for memory storage
+    /**
+     * Creates a new EpisodicMemory instance.
+     *
+     * @param userId - User identifier
+     * @param nodeId - Node identifier (for CRDT operations)
+     * @param db - Database client (REST DB for CRDT persistence)
+     * @param persistence - Optional persistence adapter
+     */
+    constructor(userId, nodeId, db, persistence) {
+        this.userId = userId;
+        this.nodeId = nodeId;
+        this.db = db;
+        this.persistence = persistence;
+        this.vectorService = new VectorMemoryService();
+        // Initialize CRDTs
+        this.memories = new ORSet(nodeId);
+        this.accessCounter = new PNCounter(nodeId);
+    }
+    /**
+     * Adds a memory to the collection.
+     * Stores the memory in vector database (Supabase) and adds its ID to ORSet.
+     *
+     * @param memory - Memory to add
+     * @returns Tag for this memory addition (for removal)
+     */
+    async add(memory) {
+        // Validate embedding if provided
+        if (memory.embedding) {
+            const validationResult = EmbeddingSchema.safeParse(memory.embedding);
+            if (!validationResult.success) {
+                throw new Error(`Invalid embedding structure: ${validationResult.error.message}`);
+            }
+        }
+        // Store in vector database using VectorMemoryService
+        await this.vectorService.create({
+            id: memory.id,
+            version: memory.version || 1,
+            content: memory.content,
+            type: memory.type,
+            source: memory.source,
+            embedding: memory.embedding,
+            metadata: memory.metadata,
+            accessCount: memory.accessCount || 0,
+            verified: memory.verified,
+        });
+        // Add to ORSet
+        const tag = this.memories.add(memory.id);
+        // Cache the memory
+        this.memoryCache.set(memory.id, memory);
+        return tag;
+    }
+    /**
+     * Removes a memory by tag.
+     *
+     * @param tag - Tag returned from add()
+     * @returns true if memory was removed
+     */
+    remove(tag) {
+        const removed = this.memories.remove(tag);
+        if (removed) {
+            // Note: We don't delete from database here - that's a design decision
+            // The memory stays in DB for audit/history, but is removed from active set
+            // If you want to actually delete, call removeById() instead
+        }
+        return removed;
+    }
+    /**
+     * Removes a memory by ID (removes all instances).
+     * Also deletes from database.
+     *
+     * @param memoryId - Memory ID to remove
+     * @returns Number of instances removed
+     */
+    async removeById(memoryId) {
+        // Remove from ORSet
+        const entries = this.memories.entries();
+        let count = 0;
+        for (const [tag, id] of entries) {
+            if (id === memoryId) {
+                this.memories.remove(tag);
+                count++;
+            }
+        }
+        // Delete from vector database
+        if (count > 0) {
+            await this.vectorService.delete(memoryId);
+            this.memoryCache.delete(memoryId);
+        }
+        return count;
+    }
+    /**
+     * Gets all memory IDs in the set.
+     *
+     * @returns Array of memory IDs
+     */
+    getMemoryIds() {
+        return this.memories.values();
+    }
+    /**
+     * Gets all memories (loads from database if not cached).
+     *
+     * @returns Array of memory objects
+     */
+    async getAll() {
+        const ids = this.memories.values();
+        const memories = [];
+        for (const id of ids) {
+            // Check cache first
+            const cached = this.memoryCache.get(id);
+            if (cached) {
+                memories.push(cached);
+                continue;
+            }
+            // Load from vector database
+            const memory = await this.vectorService.getById(id);
+            if (memory) {
+                this.memoryCache.set(id, memory);
+                memories.push(memory);
+            }
+        }
+        return memories;
+    }
+    /**
+     * Gets a specific memory by ID.
+     *
+     * @param memoryId - Memory ID
+     * @returns Memory or null if not found
+     */
+    async get(memoryId) {
+        // Check cache
+        const cached = this.memoryCache.get(memoryId);
+        if (cached) {
+            return cached;
+        }
+        // Check if in ORSet
+        if (!this.memories.values().includes(memoryId)) {
+            return null;
+        }
+        // Load from vector database
+        const memory = await this.vectorService.getById(memoryId);
+        if (memory) {
+            this.memoryCache.set(memoryId, memory);
+            return memory;
+        }
+        return null;
+    }
+    /**
+     * Updates a memory by ID.
+     * Merges partial data with the current memory, persists to vector store,
+     * and refreshes the cache. Eliminates the need for callers to access
+     * private fields or instantiate VectorMemoryService directly.
+     *
+     * @param memoryId - Memory ID to update
+     * @param data - Partial memory data to merge
+     * @returns Updated memory
+     * @throws Error if memory not found in this user's ORSet
+     */
+    async update(memoryId, data) {
+        if (!this.memories.values().includes(memoryId)) {
+            throw new Error(`Memory not found: ${memoryId}`);
+        }
+        const current = this.memoryCache.get(memoryId) ?? (await this.vectorService.getById(memoryId));
+        if (!current) {
+            throw new Error(`Memory not found in store: ${memoryId}`);
+        }
+        const merged = { ...current, ...data, id: memoryId };
+        const updated = await this.vectorService.update(memoryId, merged);
+        this.memoryCache.set(memoryId, updated);
+        return updated;
+    }
+    /**
+     * Increments access counter and updates memory access tracking.
+     *
+     * @param memoryId - Optional memory ID to track access for
+     */
+    async incrementAccess(memoryId) {
+        this.accessCounter.increment();
+        if (memoryId) {
+            // Get current memory
+            const memory = await this.get(memoryId);
+            if (memory) {
+                // Update access count in vector database
+                await this.vectorService.update(memoryId, {
+                    accessCount: (memory.accessCount || 0) + 1,
+                    accessedAt: new Date().toISOString(),
+                });
+                // Update cache
+                const cached = this.memoryCache.get(memoryId);
+                if (cached) {
+                    cached.accessCount = (cached.accessCount || 0) + 1;
+                    cached.accessedAt = new Date().toISOString();
+                }
+            }
+        }
+    }
+    /**
+     * Gets the total access count.
+     *
+     * @returns Total access count
+     */
+    getAccessCount() {
+        return this.accessCounter.value();
+    }
+    /**
+     * Searches memories using vector similarity search.
+     *
+     * @param query - Search query text
+     * @param options - Search options (limit, threshold, filters)
+     * @returns Array of matching memories sorted by relevance
+     */
+    async search(query, options = {}) {
+        try {
+            // Generate embedding for the search query
+            const embedding = await generateEmbedding(query);
+            // Search for similar memories using vector search
+            const results = await this.vectorService.searchSimilar(embedding.vector, {
+                ...options,
+                limit: options.limit ?? 10,
+                threshold: options.threshold ?? 0.5,
+            });
+            // Return memories sorted by similarity
+            return results.map((r) => r.memory);
+        }
+        catch (_error) {
+            // Embedding generation failed (e.g. embedding service unavailable).
+            // Return empty results — do NOT fall back to getAll(), which would dump the
+            // entire memory store into agent context regardless of relevance.
+            return [];
+        }
+    }
+    /**
+     * Merges another EpisodicMemory into this one.
+     *
+     * @param other - EpisodicMemory to merge
+     * @returns New merged EpisodicMemory
+     */
+    merge(other) {
+        const merged = new EpisodicMemory(this.userId, this.nodeId, this.db, this.persistence);
+        merged.memories = this.memories.merge(other.memories);
+        merged.accessCounter = this.accessCounter.merge(other.accessCounter);
+        return merged;
+    }
+    /**
+     * Loads state from database.
+     *
+     * @throws Error if persistence is not configured
+     */
+    async load() {
+        if (!this.persistence) {
+            throw new Error('Persistence not configured. Pass persistence to constructor.');
+        }
+        const crdtId = `episodic-memory:${this.userId}`;
+        const states = await this.persistence.loadCompositeState(crdtId);
+        // Restore memories ORSet
+        const memoriesData = states.get('or_set:memories');
+        if (memoriesData && 'added' in memoriesData) {
+            this.memories = ORSet.fromData(memoriesData);
+        }
+        // Restore access counter
+        const counterData = states.get('pn_counter:access');
+        if (counterData && 'increments' in counterData) {
+            this.accessCounter = PNCounter.fromData(counterData);
+        }
+        // Preload memory cache
+        const ids = this.memories.values();
+        for (const id of ids.slice(0, 100)) {
+            // Load first 100 into cache
+            await this.get(id);
+        }
+    }
+    /**
+     * Saves state to database.
+     *
+     * @throws Error if persistence is not configured
+     */
+    async save() {
+        if (!this.persistence) {
+            throw new Error('Persistence not configured. Pass persistence to constructor.');
+        }
+        const crdtId = `episodic-memory:${this.userId}`;
+        const states = new Map();
+        states.set('or_set:memories', this.memories.toData());
+        states.set('pn_counter:access', this.accessCounter.toData());
+        await this.persistence.saveCompositeState(crdtId, states);
+    }
+    /**
+     * Serializes EpisodicMemory to plain object.
+     *
+     * @returns Serialized data
+     */
+    toData() {
+        return {
+            userId: this.userId,
+            nodeId: this.nodeId,
+            memories: this.memories.toData(),
+            accessCounter: this.accessCounter.toData(),
+        };
+    }
+    /**
+     * Deserializes EpisodicMemory from plain object.
+     *
+     * @param data - Serialized data
+     * @param db - Database client
+     * @param persistence - Optional persistence adapter
+     * @returns New EpisodicMemory instance
+     */
+    static fromData(data, db, persistence) {
+        const memory = new EpisodicMemory(data.userId, data.nodeId, db, persistence);
+        memory.memories = ORSet.fromData(data.memories);
+        memory.accessCounter = PNCounter.fromData(data.accessCounter);
+        return memory;
+    }
+    /**
+     * Creates a copy of this EpisodicMemory.
+     *
+     * @returns New EpisodicMemory with same state
+     */
+    clone() {
+        return EpisodicMemory.fromData(this.toData(), this.db, this.persistence);
+    }
+    /**
+     * Gets the user ID.
+     */
+    getUserId() {
+        return this.userId;
+    }
+    /**
+     * Gets the node ID.
+     */
+    getNodeId() {
+        return this.nodeId;
+    }
+}

package/dist/memory/stores/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Memory System implementations
+ *
+ * Hierarchical memory management for AI agents:
+ * - Working Memory: Short-term, session-scoped
+ * - Episodic Memory: Conversation history
+ * - Semantic Memory: Knowledge base with vector search
+ * - Procedural Memory: Workflows and behaviors
+ *
+ * @packageDocumentation
+ */
+export { EpisodicMemory, type EpisodicMemoryData } from './episodic-memory.js';
+export { ProceduralMemory, type WorkflowContext, type WorkflowDefinition, type WorkflowResult, type WorkflowStep, } from './procedural-memory.js';
+export { type SemanticEntry, SemanticMemory, type SemanticMemoryOptions, type SemanticSearchResult, } from './semantic-memory.js';
+export { type SessionState, WorkingMemory, type WorkingMemoryData, } from './working-memory.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/memory/stores/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/memory/stores/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,cAAc,EAAE,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAC9E,OAAO,EACL,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,YAAY,GAClB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACL,KAAK,aAAa,EAClB,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,GAC1B,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,KAAK,YAAY,EACjB,aAAa,EACb,KAAK,iBAAiB,GACvB,MAAM,qBAAqB,CAAA"}

package/dist/memory/stores/index.js

@@ -0,0 +1,15 @@
+/**
+ * Memory System implementations
+ *
+ * Hierarchical memory management for AI agents:
+ * - Working Memory: Short-term, session-scoped
+ * - Episodic Memory: Conversation history
+ * - Semantic Memory: Knowledge base with vector search
+ * - Procedural Memory: Workflows and behaviors
+ *
+ * @packageDocumentation
+ */
+export { EpisodicMemory } from './episodic-memory.js';
+export { ProceduralMemory, } from './procedural-memory.js';
+export { SemanticMemory, } from './semantic-memory.js';
+export { WorkingMemory, } from './working-memory.js';

package/dist/memory/stores/procedural-memory.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Procedural Memory
+ *
+ * Stores and executes named workflows for AI agents.
+ * Workflows are sequences of typed steps that can be run
+ * sequentially or in parallel.
+ *
+ * @example
+ * ```typescript
+ * const mem = new ProceduralMemory()
+ *
+ * mem.register('onboard-user', [
+ *   { id: 'welcome', type: 'action', label: 'Send welcome email',
+ *     execute: async (ctx) => { ... } },
+ *   { id: 'create-profile', type: 'action', label: 'Init profile',
+ *     execute: async (ctx) => { ... } },
+ * ])
+ *
+ * const result = await mem.execute('onboard-user', { userId: 'u1' })
+ * ```
+ */
+export interface WorkflowContext {
+    [key: string]: unknown;
+}
+export interface WorkflowStep {
+    id: string;
+    label: string;
+    type: 'action' | 'condition' | 'parallel';
+    /** True when this step and the next should run concurrently */
+    parallel?: boolean;
+    execute: (context: WorkflowContext) => Promise<unknown>;
+}
+export interface WorkflowDefinition {
+    name: string;
+    description?: string;
+    steps: WorkflowStep[];
+    createdAt: number;
+}
+export interface WorkflowResult {
+    workflow: string;
+    success: boolean;
+    steps: Array<{
+        id: string;
+        status: 'ok' | 'error';
+        result?: unknown;
+        error?: string;
+    }>;
+    durationMs: number;
+}
+/**
+ * Procedural Memory stores named workflow definitions and executes them
+ * against a shared context object.
+ */
+export declare class ProceduralMemory {
+    private workflows;
+    /**
+     * Register a new workflow.
+     * If a workflow with the same name already exists it is overwritten.
+     */
+    register(name: string, steps: WorkflowStep[], description?: string): void;
+    /**
+     * Unregister a workflow by name.
+     */
+    unregister(name: string): void;
+    /**
+     * Check whether a workflow is registered.
+     */
+    has(name: string): boolean;
+    /**
+     * List all registered workflow names.
+     */
+    listWorkflows(): string[];
+    /**
+     * Get the definition for a registered workflow.
+     */
+    getDefinition(name: string): WorkflowDefinition | undefined;
+    /**
+     * Execute a workflow by name.
+     *
+     * Steps marked `parallel: true` are executed concurrently with the
+     * immediately following step(s). All other steps run sequentially.
+     *
+     * @param name    - Registered workflow name
+     * @param context - Initial context object passed to each step
+     * @throws {Error} If the workflow is not registered
+     */
+    execute(name: string, context?: WorkflowContext): Promise<WorkflowResult>;
+}
+//# sourceMappingURL=procedural-memory.d.ts.map

package/dist/memory/stores/procedural-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"procedural-memory.d.ts","sourceRoot":"","sources":["../../../src/memory/stores/procedural-memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH,MAAM,WAAW,eAAe;IAC9B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,QAAQ,GAAG,WAAW,GAAG,UAAU,CAAA;IACzC,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,OAAO,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CACxD;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,EAAE,YAAY,EAAE,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACtF,UAAU,EAAE,MAAM,CAAA;CACnB;AAMD;;;GAGG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,SAAS,CAA6C;IAE9D;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI;IAIzE;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI9B;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B;;OAEG;IACH,aAAa,IAAI,MAAM,EAAE;IAIzB;;OAEG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAI3D;;;;;;;;;OASG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC;CA4DpF"}