agent-relay 1.1.0 → 1.2.3

package/dist/memory/adapters/supermemory.js

@@ -0,0 +1,338 @@
+/**
+ * Supermemory.ai Memory Adapter
+ *
+ * Integration with supermemory.ai for semantic memory storage and retrieval.
+ * Provides AI-optimized search with embedding-based similarity.
+ *
+ * @see https://supermemory.ai/docs
+ */
+/**
+ * Supermemory.ai adapter for semantic memory storage
+ */
+export class SupermemoryAdapter {
+    type = 'supermemory';
+    apiKey;
+    endpoint;
+    container;
+    defaultAgentId;
+    defaultProjectId;
+    timeout;
+    initialized = false;
+    constructor(options) {
+        if (!options.apiKey) {
+            throw new Error('SupermemoryAdapter requires an API key');
+        }
+        this.apiKey = options.apiKey;
+        this.endpoint = options.endpoint ?? 'https://api.supermemory.ai';
+        this.container = options.container;
+        this.defaultAgentId = options.defaultAgentId;
+        this.defaultProjectId = options.defaultProjectId;
+        this.timeout = options.timeout ?? 30000;
+    }
+    async init() {
+        // Verify API key by making a simple request
+        try {
+            const response = await this.fetch('/v3/documents/list', {
+                method: 'POST',
+                body: JSON.stringify({ limit: 1 }),
+            });
+            if (!response.ok && response.status !== 404) {
+                const error = await response.text();
+                throw new Error(`Supermemory API error: ${error}`);
+            }
+            this.initialized = true;
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes('fetch')) {
+                throw new Error(`Failed to connect to Supermemory API: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    async add(content, options) {
+        try {
+            const metadata = {
+                source: options?.source ?? 'agent-relay',
+                agentId: options?.agentId ?? this.defaultAgentId,
+                projectId: options?.projectId ?? this.defaultProjectId,
+                sessionId: options?.sessionId,
+                tags: options?.tags,
+                ...options?.metadata,
+            };
+            // Remove undefined values
+            Object.keys(metadata).forEach(key => {
+                if (metadata[key] === undefined) {
+                    delete metadata[key];
+                }
+            });
+            const body = {
+                content,
+                metadata,
+            };
+            if (this.container) {
+                body.containerTags = [this.container];
+            }
+            const response = await this.fetch('/v3/documents', {
+                method: 'POST',
+                body: JSON.stringify(body),
+            });
+            if (!response.ok) {
+                const error = await response.text();
+                return { success: false, error: `Failed to add memory: ${error}` };
+            }
+            const result = await response.json();
+            return { success: true, id: result.id ?? result.documentId };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+    }
+    async search(query) {
+        try {
+            const filters = {};
+            if (query.agentId) {
+                filters.agentId = query.agentId;
+            }
+            if (query.projectId) {
+                filters.projectId = query.projectId;
+            }
+            if (query.tags && query.tags.length > 0) {
+                filters.tags = query.tags;
+            }
+            const body = {
+                query: query.query,
+                limit: query.limit ?? 10,
+                minScore: query.minScore ?? 0.5,
+            };
+            if (Object.keys(filters).length > 0) {
+                body.filters = filters;
+            }
+            if (this.container) {
+                body.containerTags = [this.container];
+            }
+            // Use v4 search for lower latency
+            const response = await this.fetch('/v4/search', {
+                method: 'POST',
+                body: JSON.stringify(body),
+            });
+            if (!response.ok) {
+                console.error('[supermemory] Search failed:', await response.text());
+                return [];
+            }
+            const result = await response.json();
+            const results = result.results ?? [];
+            return results.map(doc => this.documentToMemoryEntry(doc));
+        }
+        catch (error) {
+            console.error('[supermemory] Search error:', error);
+            return [];
+        }
+    }
+    async get(id) {
+        try {
+            const response = await this.fetch(`/v3/documents/${encodeURIComponent(id)}`, {
+                method: 'GET',
+            });
+            if (!response.ok) {
+                if (response.status === 404) {
+                    return null;
+                }
+                console.error('[supermemory] Get failed:', await response.text());
+                return null;
+            }
+            const doc = await response.json();
+            return this.documentToMemoryEntry(doc);
+        }
+        catch (error) {
+            console.error('[supermemory] Get error:', error);
+            return null;
+        }
+    }
+    async delete(id) {
+        try {
+            const response = await this.fetch(`/v3/documents/${encodeURIComponent(id)}`, {
+                method: 'DELETE',
+            });
+            if (!response.ok && response.status !== 404) {
+                const error = await response.text();
+                return { success: false, error: `Failed to delete: ${error}` };
+            }
+            return { success: true, id };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+    }
+    async update(id, content, options) {
+        try {
+            const body = { content };
+            if (options) {
+                const metadata = {};
+                if (options.tags)
+                    metadata.tags = options.tags;
+                if (options.metadata)
+                    Object.assign(metadata, options.metadata);
+                if (Object.keys(metadata).length > 0) {
+                    body.metadata = metadata;
+                }
+            }
+            const response = await this.fetch(`/v3/documents/${encodeURIComponent(id)}`, {
+                method: 'PATCH',
+                body: JSON.stringify(body),
+            });
+            if (!response.ok) {
+                const error = await response.text();
+                return { success: false, error: `Failed to update: ${error}` };
+            }
+            return { success: true, id };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+    }
+    async list(options) {
+        try {
+            const body = {
+                limit: options?.limit ?? 50,
+                sortBy: 'createdAt',
+                sortOrder: 'desc',
+            };
+            const filters = {};
+            if (options?.agentId)
+                filters.agentId = options.agentId;
+            if (options?.projectId)
+                filters.projectId = options.projectId;
+            if (Object.keys(filters).length > 0) {
+                body.filters = filters;
+            }
+            if (this.container) {
+                body.containerTags = [this.container];
+            }
+            const response = await this.fetch('/v3/documents/list', {
+                method: 'POST',
+                body: JSON.stringify(body),
+            });
+            if (!response.ok) {
+                console.error('[supermemory] List failed:', await response.text());
+                return [];
+            }
+            const result = await response.json();
+            return (result.documents ?? []).map(doc => this.documentToMemoryEntry(doc));
+        }
+        catch (error) {
+            console.error('[supermemory] List error:', error);
+            return [];
+        }
+    }
+    async clear(options) {
+        try {
+            // Supermemory supports bulk delete by container tags
+            // For more specific filtering, we need to list and delete individually
+            if (!options?.agentId && !options?.projectId && this.container) {
+                // Delete by container
+                const response = await this.fetch('/v3/documents/bulk', {
+                    method: 'DELETE',
+                    body: JSON.stringify({ containerTags: [this.container] }),
+                });
+                if (!response.ok) {
+                    return { success: false, error: await response.text() };
+                }
+                return { success: true };
+            }
+            // List and delete matching memories
+            const memories = await this.list({
+                limit: 1000,
+                agentId: options?.agentId,
+                projectId: options?.projectId,
+            });
+            const toDelete = options?.before
+                ? memories.filter(m => m.createdAt < options.before)
+                : memories;
+            for (const memory of toDelete) {
+                await this.delete(memory.id);
+            }
+            return { success: true };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+    }
+    async stats() {
+        // Supermemory doesn't have a stats endpoint, so we approximate
+        const memories = await this.list({ limit: 1000 });
+        const byAgent = {};
+        const byProject = {};
+        for (const memory of memories) {
+            if (memory.agentId) {
+                byAgent[memory.agentId] = (byAgent[memory.agentId] ?? 0) + 1;
+            }
+            if (memory.projectId) {
+                byProject[memory.projectId] = (byProject[memory.projectId] ?? 0) + 1;
+            }
+        }
+        return {
+            totalCount: memories.length,
+            byAgent,
+            byProject,
+        };
+    }
+    async close() {
+        this.initialized = false;
+    }
+    /**
+     * Make a fetch request to the Supermemory API
+     */
+    async fetch(path, options) {
+        const url = `${this.endpoint}${path}`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const response = await fetch(url, {
+                ...options,
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${this.apiKey}`,
+                    ...options.headers,
+                },
+                signal: controller.signal,
+            });
+            return response;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Convert a Supermemory document to a MemoryEntry
+     */
+    documentToMemoryEntry(doc) {
+        const metadata = doc.metadata ?? {};
+        return {
+            id: doc.id,
+            content: doc.content,
+            createdAt: doc.createdAt
+                ? new Date(doc.createdAt).getTime()
+                : Date.now(),
+            tags: metadata.tags,
+            source: metadata.source,
+            agentId: metadata.agentId,
+            projectId: metadata.projectId,
+            sessionId: metadata.sessionId,
+            score: doc.score,
+            metadata,
+        };
+    }
+}
+//# sourceMappingURL=supermemory.js.map

package/dist/memory/factory.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Memory Adapter Factory
+ *
+ * Creates memory adapters based on configuration.
+ * Supports environment variables for configuration.
+ */
+import type { MemoryAdapter, MemoryConfig } from './types.js';
+/**
+ * Get memory configuration from environment variables
+ *
+ * Environment variables:
+ * - AGENT_RELAY_MEMORY_TYPE: 'inmemory', 'supermemory', 'claude'
+ * - AGENT_RELAY_MEMORY_API_KEY: API key for external services
+ * - AGENT_RELAY_MEMORY_ENDPOINT: Custom API endpoint
+ * - SUPERMEMORY_API_KEY: Supermemory-specific API key (fallback)
+ */
+export declare function getMemoryConfigFromEnv(): MemoryConfig;
+/**
+ * Create a memory adapter based on configuration
+ *
+ * @param config - Memory configuration (merged with env vars)
+ * @returns Initialized memory adapter
+ *
+ * @example
+ * ```typescript
+ * // Use environment variables
+ * const memory = await createMemoryAdapter();
+ *
+ * // Explicit configuration
+ * const memory = await createMemoryAdapter({
+ *   type: 'supermemory',
+ *   apiKey: 'my-api-key',
+ * });
+ * ```
+ */
+export declare function createMemoryAdapter(config?: Partial<MemoryConfig>): Promise<MemoryAdapter>;
+/**
+ * Check if a memory adapter type is available
+ *
+ * @param type - Adapter type to check
+ * @returns Whether the adapter is available
+ */
+export declare function isMemoryAdapterAvailable(type: string): boolean;
+/**
+ * Get list of available memory adapter types
+ */
+export declare function getAvailableMemoryAdapters(): string[];
+//# sourceMappingURL=factory.d.ts.map

package/dist/memory/factory.js

@@ -0,0 +1,143 @@
+/**
+ * Memory Adapter Factory
+ *
+ * Creates memory adapters based on configuration.
+ * Supports environment variables for configuration.
+ */
+import { InMemoryAdapter } from './adapters/inmemory.js';
+import { SupermemoryAdapter } from './adapters/supermemory.js';
+/**
+ * Get memory configuration from environment variables
+ *
+ * Environment variables:
+ * - AGENT_RELAY_MEMORY_TYPE: 'inmemory', 'supermemory', 'claude'
+ * - AGENT_RELAY_MEMORY_API_KEY: API key for external services
+ * - AGENT_RELAY_MEMORY_ENDPOINT: Custom API endpoint
+ * - SUPERMEMORY_API_KEY: Supermemory-specific API key (fallback)
+ */
+export function getMemoryConfigFromEnv() {
+    const type = process.env.AGENT_RELAY_MEMORY_TYPE ?? 'inmemory';
+    const apiKey = process.env.AGENT_RELAY_MEMORY_API_KEY ??
+        process.env.SUPERMEMORY_API_KEY;
+    return {
+        type,
+        apiKey,
+        endpoint: process.env.AGENT_RELAY_MEMORY_ENDPOINT,
+        defaultAgentId: process.env.AGENT_RELAY_AGENT_ID,
+        defaultProjectId: process.env.AGENT_RELAY_PROJECT_ID,
+    };
+}
+/**
+ * Create a memory adapter based on configuration
+ *
+ * @param config - Memory configuration (merged with env vars)
+ * @returns Initialized memory adapter
+ *
+ * @example
+ * ```typescript
+ * // Use environment variables
+ * const memory = await createMemoryAdapter();
+ *
+ * // Explicit configuration
+ * const memory = await createMemoryAdapter({
+ *   type: 'supermemory',
+ *   apiKey: 'my-api-key',
+ * });
+ * ```
+ */
+export async function createMemoryAdapter(config) {
+    // Merge with environment config
+    const envConfig = getMemoryConfigFromEnv();
+    const finalConfig = {
+        type: config?.type ?? envConfig.type ?? 'inmemory',
+        apiKey: config?.apiKey ?? envConfig.apiKey,
+        endpoint: config?.endpoint ?? envConfig.endpoint,
+        defaultAgentId: config?.defaultAgentId ?? envConfig.defaultAgentId,
+        defaultProjectId: config?.defaultProjectId ?? envConfig.defaultProjectId,
+        options: { ...envConfig.options, ...config?.options },
+    };
+    const adapterType = finalConfig.type.toLowerCase();
+    let adapter;
+    switch (adapterType) {
+        case 'supermemory':
+        case 'supermemory.ai': {
+            if (!finalConfig.apiKey) {
+                throw new Error('Supermemory adapter requires an API key. ' +
+                    'Set AGENT_RELAY_MEMORY_API_KEY or SUPERMEMORY_API_KEY environment variable, ' +
+                    'or provide apiKey in config.');
+            }
+            adapter = new SupermemoryAdapter({
+                apiKey: finalConfig.apiKey,
+                endpoint: finalConfig.endpoint,
+                defaultAgentId: finalConfig.defaultAgentId,
+                defaultProjectId: finalConfig.defaultProjectId,
+                container: finalConfig.options?.container,
+                timeout: finalConfig.options?.timeout,
+            });
+            break;
+        }
+        case 'claude':
+        case 'claude-memory': {
+            // Claude memory is not yet available as a public API
+            // Fall back to in-memory with a warning
+            console.warn('[memory] Claude memory adapter not yet available. ' +
+                'Using in-memory adapter as fallback.');
+            adapter = new InMemoryAdapter({
+                defaultAgentId: finalConfig.defaultAgentId,
+                defaultProjectId: finalConfig.defaultProjectId,
+                maxMemories: finalConfig.options?.maxMemories,
+            });
+            break;
+        }
+        case 'inmemory':
+        case 'memory':
+        case 'none':
+        default: {
+            adapter = new InMemoryAdapter({
+                defaultAgentId: finalConfig.defaultAgentId,
+                defaultProjectId: finalConfig.defaultProjectId,
+                maxMemories: finalConfig.options?.maxMemories,
+            });
+            break;
+        }
+    }
+    await adapter.init();
+    return adapter;
+}
+/**
+ * Check if a memory adapter type is available
+ *
+ * @param type - Adapter type to check
+ * @returns Whether the adapter is available
+ */
+export function isMemoryAdapterAvailable(type) {
+    const adapterType = type.toLowerCase();
+    switch (adapterType) {
+        case 'inmemory':
+        case 'memory':
+        case 'none':
+            return true;
+        case 'supermemory':
+        case 'supermemory.ai':
+            // Available if API key is configured
+            return !!(process.env.AGENT_RELAY_MEMORY_API_KEY ||
+                process.env.SUPERMEMORY_API_KEY);
+        case 'claude':
+        case 'claude-memory':
+            // Not yet available
+            return false;
+        default:
+            return false;
+    }
+}
+/**
+ * Get list of available memory adapter types
+ */
+export function getAvailableMemoryAdapters() {
+    const adapters = ['inmemory'];
+    if (process.env.AGENT_RELAY_MEMORY_API_KEY || process.env.SUPERMEMORY_API_KEY) {
+        adapters.push('supermemory');
+    }
+    return adapters;
+}
+//# sourceMappingURL=factory.js.map

package/dist/memory/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Agent Relay Memory System
+ *
+ * Provides semantic memory storage and retrieval with multiple backend support.
+ * Memory adapters can be used standalone or integrated with the hooks system.
+ *
+ * @example
+ * ```typescript
+ * import { createMemoryAdapter } from 'agent-relay/memory';
+ *
+ * // Create an in-memory adapter for testing
+ * const memory = await createMemoryAdapter({ type: 'inmemory' });
+ *
+ * // Or use supermemory.ai for production
+ * const memory = await createMemoryAdapter({
+ *   type: 'supermemory',
+ *   apiKey: process.env.SUPERMEMORY_API_KEY,
+ * });
+ *
+ * // Add a memory
+ * await memory.add('User prefers TypeScript', { tags: ['preference'] });
+ *
+ * // Search for relevant memories
+ * const results = await memory.search({ query: 'programming language' });
+ * ```
+ */
+export * from './types.js';
+export * from './adapters/index.js';
+export { createMemoryAdapter, getMemoryConfigFromEnv } from './factory.js';
+export { createMemoryService } from './service.js';
+export { createMemoryHooks, getMemoryHooks } from './memory-hooks.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/memory/index.js

@@ -0,0 +1,32 @@
+/**
+ * Agent Relay Memory System
+ *
+ * Provides semantic memory storage and retrieval with multiple backend support.
+ * Memory adapters can be used standalone or integrated with the hooks system.
+ *
+ * @example
+ * ```typescript
+ * import { createMemoryAdapter } from 'agent-relay/memory';
+ *
+ * // Create an in-memory adapter for testing
+ * const memory = await createMemoryAdapter({ type: 'inmemory' });
+ *
+ * // Or use supermemory.ai for production
+ * const memory = await createMemoryAdapter({
+ *   type: 'supermemory',
+ *   apiKey: process.env.SUPERMEMORY_API_KEY,
+ * });
+ *
+ * // Add a memory
+ * await memory.add('User prefers TypeScript', { tags: ['preference'] });
+ *
+ * // Search for relevant memories
+ * const results = await memory.search({ query: 'programming language' });
+ * ```
+ */
+export * from './types.js';
+export * from './adapters/index.js';
+export { createMemoryAdapter, getMemoryConfigFromEnv } from './factory.js';
+export { createMemoryService } from './service.js';
+export { createMemoryHooks, getMemoryHooks } from './memory-hooks.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,60 @@
+/**
+ * Memory Hooks
+ *
+ * Provides memory-aware lifecycle hooks that automatically:
+ * - Load relevant context on session start
+ * - Prompt for memory save on session end
+ * - Handle @memory: pattern output
+ */
+import type { LifecycleHooks } from '../hooks/types.js';
+import type { MemoryAdapter, MemoryConfig } from './types.js';
+/**
+ * Options for memory hooks
+ */
+export interface MemoryHooksOptions {
+    /** Pre-configured memory adapter */
+    adapter?: MemoryAdapter;
+    /** Configuration for creating a new adapter */
+    config?: Partial<MemoryConfig>;
+    /** Agent ID for memory operations */
+    agentId?: string;
+    /** Project ID for memory operations */
+    projectId?: string;
+    /** Whether to inject relevant memories on session start */
+    injectOnStart?: boolean;
+    /** Maximum memories to inject on start */
+    maxStartMemories?: number;
+    /** Search query for session start (default: project-based) */
+    startSearchQuery?: string;
+    /** Whether to prompt for memory save on session end */
+    promptOnEnd?: boolean;
+    /** Whether to auto-save important learnings from output */
+    autoSave?: boolean;
+    /** Whether to auto-save session summary on graceful end */
+    autoSaveOnEnd?: boolean;
+    /** Patterns that indicate content worth saving */
+    savePatterns?: RegExp[];
+}
+/**
+ * Create memory hooks for automatic context loading and saving
+ *
+ * @example
+ * ```typescript
+ * const hooks = createMemoryHooks({
+ *   config: { type: 'supermemory', apiKey: 'xxx' },
+ *   agentId: 'my-agent',
+ *   projectId: 'my-project',
+ * });
+ *
+ * registry.registerLifecycleHooks(hooks);
+ * ```
+ */
+export declare function createMemoryHooks(options?: MemoryHooksOptions): LifecycleHooks;
+/**
+ * Get memory hooks with default settings
+ *
+ * @param agentId - Agent identifier
+ * @param projectId - Project identifier
+ */
+export declare function getMemoryHooks(agentId: string, projectId: string): LifecycleHooks;
+//# sourceMappingURL=memory-hooks.d.ts.map