agent-relay 1.1.0 → 1.2.3

package/dist/memory/memory-hooks.js

@@ -0,0 +1,313 @@
+/**
+ * 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 { createMemoryAdapter } from './factory.js';
+/**
+ * Default patterns that indicate content worth auto-saving
+ *
+ * Categories:
+ * - Learnings: discoveries, realizations, insights
+ * - Decisions: significant choices made
+ * - Breakthroughs: problems solved, aha moments
+ * - Failures: things that went wrong, errors encountered
+ * - Preferences: user/project preferences
+ * - Retrospectives: end-of-task reflections
+ */
+const DEFAULT_SAVE_PATTERNS = [
+    // Learnings and discoveries
+    /(?:learned|discovered|found out|realized|important|remember|note to self)/i,
+    /(?:key insight|takeaway|lesson learned|now I understand)/i,
+    // Significant decisions
+    /(?:decided to|decision:|chose to|going with|settled on|approach:|strategy:)/i,
+    /(?:trade-?off|weighing|considering|opting for)/i,
+    // Breakthroughs and solutions
+    /(?:breakthrough|finally|solved|figured out|the fix was|root cause)/i,
+    /(?:aha|eureka|that's why|the issue was|problem was)/i,
+    // Failures and problems
+    /(?:failed because|mistake was|should have|shouldn't have|next time)/i,
+    /(?:went wrong|broke because|error was due to|caused by)/i,
+    /(?:avoid|don't repeat|pitfall|gotcha|watch out)/i,
+    // User/project preferences
+    /(?:user prefers?|preference|always use|never use|don't use)/i,
+    /(?:project uses?|codebase uses?|this repo|this project)/i,
+    /(?:convention|pattern|style guide|best practice)/i,
+    // Retrospectives
+    /(?:in retrospect|looking back|reflecting|summary:|recap:)/i,
+    /(?:what worked|what didn't|improvements for next time)/i,
+];
+/**
+ * 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 function createMemoryHooks(options = {}) {
+    const state = {
+        adapter: options.adapter ?? null,
+        adapterPromise: null,
+        sessionLearnings: [],
+        options: {
+            agentId: options.agentId ?? 'default',
+            projectId: options.projectId ?? 'default',
+            injectOnStart: options.injectOnStart ?? true,
+            maxStartMemories: options.maxStartMemories ?? 5,
+            startSearchQuery: options.startSearchQuery ?? '',
+            promptOnEnd: options.promptOnEnd ?? false,
+            autoSave: options.autoSave ?? true,
+            autoSaveOnEnd: options.autoSaveOnEnd ?? true,
+            savePatterns: options.savePatterns ?? DEFAULT_SAVE_PATTERNS,
+            config: options.config,
+        },
+    };
+    return {
+        onSessionStart: createSessionStartHook(state),
+        onSessionEnd: createSessionEndHook(state),
+        onOutput: createOutputHook(state),
+    };
+}
+/**
+ * Lazily get or create the memory adapter
+ */
+async function getAdapter(state) {
+    if (state.adapter) {
+        return state.adapter;
+    }
+    if (!state.adapterPromise) {
+        state.adapterPromise = createMemoryAdapter({
+            ...state.options.config,
+            defaultAgentId: state.options.agentId,
+            defaultProjectId: state.options.projectId,
+        }).catch(error => {
+            console.error('[memory-hooks] Failed to create adapter:', error);
+            return null;
+        });
+    }
+    state.adapter = await state.adapterPromise;
+    return state.adapter;
+}
+/**
+ * Session start hook - loads relevant memories
+ */
+function createSessionStartHook(state) {
+    return async (ctx) => {
+        if (!state.options.injectOnStart) {
+            return;
+        }
+        state.sessionId = ctx.sessionId;
+        const adapter = await getAdapter(state);
+        if (!adapter) {
+            return;
+        }
+        try {
+            // Build search query based on context
+            const searchQuery = state.options.startSearchQuery ||
+                `project: ${ctx.workingDir} OR agent: ${state.options.agentId}`;
+            const memories = await adapter.search({
+                query: searchQuery,
+                limit: state.options.maxStartMemories,
+                agentId: state.options.agentId,
+                projectId: state.options.projectId,
+            });
+            if (memories.length === 0) {
+                return;
+            }
+            const formattedMemories = formatMemoriesForInjection(memories);
+            return {
+                inject: `\n[CONTEXT FROM MEMORY]\n${formattedMemories}\n`,
+            };
+        }
+        catch (error) {
+            console.error('[memory-hooks] Failed to load memories:', error);
+        }
+    };
+}
+/**
+ * Session end hook - logs learnings summary and optionally prompts for more
+ */
+function createSessionEndHook(state) {
+    return async (ctx) => {
+        // Log session summary (learnings were already saved immediately during output)
+        if (state.options.autoSaveOnEnd && ctx.graceful && state.sessionLearnings.length > 0) {
+            const uniqueLearnings = [...new Set(state.sessionLearnings)];
+            console.log(`[memory-hooks] Session captured ${uniqueLearnings.length} learnings (saved during session)`);
+            // Clear for next session
+            state.sessionLearnings = [];
+        }
+        // Optional prompt for additional saves
+        if (state.options.promptOnEnd && ctx.graceful) {
+            return {
+                inject: `
+[SESSION ENDING]
+If you learned anything important, save it for future sessions:
+  @memory:save <what you learned>
+
+Examples:
+  @memory:save User prefers TypeScript over JavaScript
+  @memory:save This project uses Prisma for database access
+  @memory:save Auth tokens stored in httpOnly cookies
+`,
+            };
+        }
+    };
+}
+/**
+ * Output hook - handles @memory: patterns and auto-save
+ */
+function createOutputHook(state) {
+    return async (ctx) => {
+        const { content } = ctx;
+        // Handle @memory: patterns (explicit saves)
+        const memoryMatch = content.match(/@memory:(\w+)\s+(.+)/);
+        if (memoryMatch) {
+            const [, action, payload] = memoryMatch;
+            return handleMemoryCommand(state, action, payload.trim());
+        }
+        // Auto-detect and save learnings
+        if (state.options.autoSave) {
+            for (const pattern of state.options.savePatterns) {
+                if (pattern.test(content)) {
+                    // Extract the relevant sentence/phrase
+                    const relevantContent = extractRelevantContent(content, pattern);
+                    if (relevantContent && relevantContent.length > 10) {
+                        // Collect for session-end retrospective
+                        if (state.options.autoSaveOnEnd) {
+                            state.sessionLearnings.push(relevantContent);
+                        }
+                        // Also save immediately (ensures persistence even on crash)
+                        const adapter = await getAdapter(state);
+                        if (adapter) {
+                            await adapter.add(relevantContent, {
+                                source: 'auto-detected',
+                                sessionId: state.sessionId,
+                                tags: ['auto-saved'],
+                            });
+                        }
+                    }
+                    break;
+                }
+            }
+        }
+    };
+}
+/**
+ * Handle @memory: commands
+ */
+async function handleMemoryCommand(state, action, payload) {
+    const adapter = await getAdapter(state);
+    if (!adapter) {
+        return { inject: '[memory] Memory service not available' };
+    }
+    switch (action.toLowerCase()) {
+        case 'save':
+        case 'add': {
+            const result = await adapter.add(payload, {
+                source: 'agent-command',
+                sessionId: state.sessionId,
+            });
+            if (result.success) {
+                return { inject: `[memory] Saved: "${truncate(payload, 50)}"` };
+            }
+            else {
+                return { inject: `[memory] Failed to save: ${result.error}` };
+            }
+        }
+        case 'search':
+        case 'find':
+        case 'recall': {
+            const memories = await adapter.search({
+                query: payload,
+                limit: 5,
+            });
+            if (memories.length === 0) {
+                return { inject: '[memory] No relevant memories found' };
+            }
+            const formatted = formatMemoriesForInjection(memories);
+            return { inject: `[memory] Found ${memories.length} memories:\n${formatted}` };
+        }
+        case 'forget':
+        case 'delete': {
+            const result = await adapter.delete(payload);
+            if (result.success) {
+                return { inject: `[memory] Deleted memory: ${payload}` };
+            }
+            else {
+                return { inject: `[memory] Failed to delete: ${result.error}` };
+            }
+        }
+        case 'list': {
+            if (!adapter.list) {
+                return { inject: '[memory] List not supported by this adapter' };
+            }
+            const limit = parseInt(payload) || 10;
+            const memories = await adapter.list({ limit });
+            if (memories.length === 0) {
+                return { inject: '[memory] No memories stored' };
+            }
+            const formatted = formatMemoriesForInjection(memories);
+            return { inject: `[memory] Recent memories:\n${formatted}` };
+        }
+        default:
+            return {
+                inject: `[memory] Unknown action: ${action}. Use: save, search, forget, list`,
+            };
+    }
+}
+/**
+ * Format memories for injection into agent context
+ */
+function formatMemoriesForInjection(memories) {
+    return memories
+        .map((m, i) => {
+        const score = m.score ? ` (relevance: ${Math.round(m.score * 100)}%)` : '';
+        const tags = m.tags?.length ? ` [${m.tags.join(', ')}]` : '';
+        return `${i + 1}. ${m.content}${tags}${score}`;
+    })
+        .join('\n');
+}
+/**
+ * Extract relevant content around a pattern match
+ */
+function extractRelevantContent(content, pattern) {
+    const match = content.match(pattern);
+    if (!match)
+        return null;
+    // Find the sentence containing the match
+    const sentences = content.split(/[.!?]+/);
+    for (const sentence of sentences) {
+        if (pattern.test(sentence)) {
+            return sentence.trim();
+        }
+    }
+    return match[0];
+}
+/**
+ * Truncate string with ellipsis
+ */
+function truncate(str, maxLen) {
+    if (str.length <= maxLen)
+        return str;
+    return str.slice(0, maxLen - 3) + '...';
+}
+/**
+ * Get memory hooks with default settings
+ *
+ * @param agentId - Agent identifier
+ * @param projectId - Project identifier
+ */
+export function getMemoryHooks(agentId, projectId) {
+    return createMemoryHooks({ agentId, projectId });
+}
+//# sourceMappingURL=memory-hooks.js.map

package/dist/memory/service.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Memory Service
+ *
+ * A simplified service wrapper around memory adapters for use in hooks.
+ * Provides a consistent interface and handles common operations.
+ */
+import type { MemoryAdapter, MemoryService, MemoryConfig } from './types.js';
+/**
+ * Options for creating a memory service
+ */
+export interface MemoryServiceOptions {
+    /** Pre-configured adapter to use */
+    adapter?: MemoryAdapter;
+    /** Configuration for creating a new adapter */
+    config?: Partial<MemoryConfig>;
+    /** Default agent ID for all operations */
+    agentId?: string;
+    /** Default project ID for all operations */
+    projectId?: string;
+    /** Default session ID for all operations */
+    sessionId?: string;
+}
+/**
+ * Create a memory service instance
+ *
+ * @param options - Service configuration
+ * @returns Memory service instance
+ *
+ * @example
+ * ```typescript
+ * // Create with default in-memory adapter
+ * const memory = createMemoryService();
+ *
+ * // Create with specific adapter
+ * const adapter = await createMemoryAdapter({ type: 'supermemory', apiKey });
+ * const memory = createMemoryService({ adapter });
+ *
+ * // Create with config
+ * const memory = createMemoryService({
+ *   config: { type: 'supermemory' },
+ *   agentId: 'my-agent',
+ * });
+ * ```
+ */
+export declare function createMemoryService(options?: MemoryServiceOptions): MemoryService & {
+    getUnderlyingAdapter(): MemoryAdapter | null;
+    close(): Promise<void>;
+};
+//# sourceMappingURL=service.d.ts.map

package/dist/memory/service.js

@@ -0,0 +1,146 @@
+/**
+ * Memory Service
+ *
+ * A simplified service wrapper around memory adapters for use in hooks.
+ * Provides a consistent interface and handles common operations.
+ */
+import { createMemoryAdapter } from './factory.js';
+/**
+ * Internal memory service implementation
+ */
+class MemoryServiceImpl {
+    adapter = null;
+    adapterPromise = null;
+    options;
+    available = false;
+    constructor(options = {}) {
+        this.options = options;
+        if (options.adapter) {
+            this.adapter = options.adapter;
+            this.available = true;
+        }
+    }
+    /**
+     * Lazily initialize the adapter
+     */
+    async getAdapter() {
+        if (this.adapter) {
+            return this.adapter;
+        }
+        if (!this.adapterPromise) {
+            this.adapterPromise = this.initAdapter();
+        }
+        return this.adapterPromise;
+    }
+    async initAdapter() {
+        try {
+            const config = this.options.config ?? {};
+            this.adapter = await createMemoryAdapter({
+                ...config,
+                defaultAgentId: config.defaultAgentId ?? this.options.agentId,
+                defaultProjectId: config.defaultProjectId ?? this.options.projectId,
+            });
+            this.available = true;
+            return this.adapter;
+        }
+        catch (error) {
+            console.error('[memory] Failed to initialize adapter:', error);
+            this.available = false;
+            return null;
+        }
+    }
+    async add(content, options) {
+        const adapter = await this.getAdapter();
+        if (!adapter) {
+            return { success: false, error: 'Memory adapter not available' };
+        }
+        return adapter.add(content, {
+            ...options,
+            agentId: options?.agentId ?? this.options.agentId,
+            projectId: options?.projectId ?? this.options.projectId,
+            sessionId: options?.sessionId ?? this.options.sessionId,
+        });
+    }
+    async search(query) {
+        const adapter = await this.getAdapter();
+        if (!adapter) {
+            return [];
+        }
+        const searchQuery = typeof query === 'string'
+            ? {
+                query,
+                agentId: this.options.agentId,
+                projectId: this.options.projectId,
+            }
+            : {
+                ...query,
+                agentId: query.agentId ?? this.options.agentId,
+                projectId: query.projectId ?? this.options.projectId,
+            };
+        return adapter.search(searchQuery);
+    }
+    async delete(id) {
+        const adapter = await this.getAdapter();
+        if (!adapter) {
+            return { success: false, error: 'Memory adapter not available' };
+        }
+        return adapter.delete(id);
+    }
+    async list(limit) {
+        const adapter = await this.getAdapter();
+        if (!adapter || !adapter.list) {
+            return [];
+        }
+        return adapter.list({
+            limit,
+            agentId: this.options.agentId,
+            projectId: this.options.projectId,
+        });
+    }
+    isAvailable() {
+        return this.available;
+    }
+    /**
+     * Get the underlying adapter (for advanced use)
+     */
+    getUnderlyingAdapter() {
+        return this.adapter;
+    }
+    /**
+     * Close the adapter
+     */
+    async close() {
+        if (this.adapter?.close) {
+            await this.adapter.close();
+        }
+        this.adapter = null;
+        this.adapterPromise = null;
+        this.available = false;
+    }
+}
+/**
+ * Create a memory service instance
+ *
+ * @param options - Service configuration
+ * @returns Memory service instance
+ *
+ * @example
+ * ```typescript
+ * // Create with default in-memory adapter
+ * const memory = createMemoryService();
+ *
+ * // Create with specific adapter
+ * const adapter = await createMemoryAdapter({ type: 'supermemory', apiKey });
+ * const memory = createMemoryService({ adapter });
+ *
+ * // Create with config
+ * const memory = createMemoryService({
+ *   config: { type: 'supermemory' },
+ *   agentId: 'my-agent',
+ * });
+ * ```
+ */
+export function createMemoryService(options) {
+    return new MemoryServiceImpl(options);
+}
+//# sourceMappingURL=service.js.map

package/dist/memory/types.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Agent Relay Memory Types
+ *
+ * Core types for the memory adapter system. Memory adapters provide
+ * semantic storage and retrieval of agent learnings and context.
+ */
+/**
+ * A memory entry stored in the system
+ */
+export interface MemoryEntry {
+    /** Unique identifier for the memory */
+    id: string;
+    /** The actual content of the memory */
+    content: string;
+    /** Timestamp when memory was created */
+    createdAt: number;
+    /** Timestamp when memory was last accessed */
+    lastAccessedAt?: number;
+    /** Optional metadata tags */
+    tags?: string[];
+    /** Source of the memory (e.g., 'agent', 'user', 'session') */
+    source?: string;
+    /** Agent that created the memory */
+    agentId?: string;
+    /** Project associated with this memory */
+    projectId?: string;
+    /** Session ID where memory was created */
+    sessionId?: string;
+    /** Relevance score (when returned from search) */
+    score?: number;
+    /** Additional structured metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Query options for searching memories
+ */
+export interface MemorySearchQuery {
+    /** Semantic search query text */
+    query: string;
+    /** Maximum number of results to return */
+    limit?: number;
+    /** Minimum relevance score threshold (0-1) */
+    minScore?: number;
+    /** Filter by tags */
+    tags?: string[];
+    /** Filter by agent ID */
+    agentId?: string;
+    /** Filter by project ID */
+    projectId?: string;
+    /** Filter by memories created after this timestamp */
+    since?: number;
+    /** Filter by memories created before this timestamp */
+    before?: number;
+}
+/**
+ * Options for adding a memory
+ */
+export interface AddMemoryOptions {
+    /** Optional tags for the memory */
+    tags?: string[];
+    /** Source of the memory */
+    source?: string;
+    /** Agent creating the memory */
+    agentId?: string;
+    /** Project context */
+    projectId?: string;
+    /** Session context */
+    sessionId?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of a memory operation
+ */
+export interface MemoryResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** ID of the affected memory (if applicable) */
+    id?: string;
+    /** Error message if operation failed */
+    error?: string;
+}
+/**
+ * Memory adapter interface
+ *
+ * All memory backends must implement this interface to be used
+ * with the agent-relay memory system.
+ */
+export interface MemoryAdapter {
+    /** Unique identifier for this adapter type */
+    readonly type: string;
+    /**
+     * Initialize the adapter (connect to backend, etc.)
+     */
+    init(): Promise<void>;
+    /**
+     * Add a new memory to the system
+     * @param content - The content to remember
+     * @param options - Optional metadata and context
+     * @returns Result with the new memory's ID
+     */
+    add(content: string, options?: AddMemoryOptions): Promise<MemoryResult>;
+    /**
+     * Search for relevant memories
+     * @param query - Search parameters
+     * @returns Array of matching memories, ordered by relevance
+     */
+    search(query: MemorySearchQuery): Promise<MemoryEntry[]>;
+    /**
+     * Get a specific memory by ID
+     * @param id - The memory ID
+     * @returns The memory entry or null if not found
+     */
+    get(id: string): Promise<MemoryEntry | null>;
+    /**
+     * Delete a memory
+     * @param id - The memory ID to delete
+     * @returns Result indicating success/failure
+     */
+    delete(id: string): Promise<MemoryResult>;
+    /**
+     * Update an existing memory
+     * @param id - The memory ID
+     * @param content - New content
+     * @param options - Optional updated metadata
+     * @returns Result indicating success/failure
+     */
+    update?(id: string, content: string, options?: Partial<AddMemoryOptions>): Promise<MemoryResult>;
+    /**
+     * List recent memories
+     * @param options - Filter options
+     * @returns Array of recent memories
+     */
+    list?(options?: {
+        limit?: number;
+        agentId?: string;
+        projectId?: string;
+    }): Promise<MemoryEntry[]>;
+    /**
+     * Clear all memories matching criteria
+     * @param options - Filter for what to clear
+     */
+    clear?(options?: {
+        agentId?: string;
+        projectId?: string;
+        before?: number;
+    }): Promise<MemoryResult>;
+    /**
+     * Get statistics about stored memories
+     */
+    stats?(): Promise<{
+        totalCount: number;
+        byAgent?: Record<string, number>;
+        byProject?: Record<string, number>;
+    }>;
+    /**
+     * Close the adapter and release resources
+     */
+    close?(): Promise<void>;
+}
+/**
+ * Configuration for memory adapters
+ */
+export interface MemoryConfig {
+    /** Adapter type: 'inmemory', 'supermemory', 'claude', etc. */
+    type: string;
+    /** API key for external services */
+    apiKey?: string;
+    /** API endpoint URL (for supermemory, etc.) */
+    endpoint?: string;
+    /** Default agent ID to use */
+    defaultAgentId?: string;
+    /** Default project ID to use */
+    defaultProjectId?: string;
+    /** Additional adapter-specific options */
+    options?: Record<string, unknown>;
+}
+/**
+ * Memory service interface for hooks
+ *
+ * This is a simplified interface exposed to hooks for memory operations.
+ */
+export interface MemoryService {
+    /** Add a memory */
+    add(content: string, options?: AddMemoryOptions): Promise<MemoryResult>;
+    /** Search for memories */
+    search(query: string | MemorySearchQuery): Promise<MemoryEntry[]>;
+    /** Delete a memory */
+    delete(id: string): Promise<MemoryResult>;
+    /** List recent memories */
+    list(limit?: number): Promise<MemoryEntry[]>;
+    /** Check if memory service is available */
+    isAvailable(): boolean;
+}
+//# sourceMappingURL=types.d.ts.map