@juspay/hippocampus 0.1.0 → 0.1.1

package/dist/client.d.ts

@@ -1,69 +1,39 @@
-import { Engram, EngramCreateInput, EngramUpdateInput, SearchQuery, SearchResult, Chronicle, ChronicleCreateInput, ChronicleUpdateInput, ChronicleQuery, Nexus, NexusCreateInput, HealthResponse, StatusResponse, HippocampusOptions, Strand } from './types';
+import type { HippocampusConfig } from './types';
 export declare class Hippocampus {
-    private baseUrl;
-    private headers;
-    private retries;
-    private retryDelay;
-    constructor(options?: HippocampusOptions);
-    addMemory(input: EngramCreateInput): Promise<{
-        engrams: Engram[];
-    }>;
-    listEngrams(ownerId: string, options?: {
-        limit?: number;
-        offset?: number;
-        strand?: Strand;
-    }): Promise<{
-        engrams: Engram[];
-        total: number;
-    }>;
-    getEngram(id: string): Promise<{
-        engram: Engram;
-    }>;
-    updateEngram(id: string, input: EngramUpdateInput): Promise<{
-        engram: Engram;
-    }>;
-    deleteEngram(id: string): Promise<void>;
-    search(query: SearchQuery): Promise<SearchResult>;
-    reinforceEngram(id: string, boost?: number): Promise<{
-        engram: Engram;
-    }>;
-    recordChronicle(input: ChronicleCreateInput): Promise<{
-        chronicle: Chronicle;
-    }>;
-    queryChronicles(query: ChronicleQuery): Promise<{
-        chronicles: Chronicle[];
-        total: number;
-    }>;
-    getCurrentFact(ownerId: string, entity: string, attribute: string): Promise<{
-        chronicle: Chronicle;
-    }>;
-    getTimeline(ownerId: string, entity: string): Promise<{
-        chronicles: Chronicle[];
-    }>;
-    getChronicle(id: string): Promise<{
-        chronicle: Chronicle;
-    }>;
-    updateChronicle(id: string, input: ChronicleUpdateInput): Promise<{
-        chronicle: Chronicle;
-    }>;
-    expireChronicle(id: string): Promise<void>;
-    createNexus(input: NexusCreateInput): Promise<{
-        nexus: Nexus;
-    }>;
-    getRelatedChronicles(chronicleId: string): Promise<{
-        related: {
-            nexus: Nexus;
-            chronicle: Chronicle;
-        }[];
-    }>;
-    health(): Promise<HealthResponse>;
-    status(): Promise<StatusResponse>;
-    runDecay(ownerId: string): Promise<{
-        affected: number;
-    }>;
-    private request;
-    private get;
-    private post;
-    private patch;
-    private del;
+    private storage;
+    private storageConfig;
+    private prompt;
+    private maxWords;
+    private neurolink;
+    private config;
+    constructor(config?: HippocampusConfig);
+    private ensureStorage;
+    private ensureNeurolink;
+    /**
+     * Add/update memory for an owner.
+     *
+     * Fetches existing memory, merges with new content via LLM, stores result.
+     *
+     * @param ownerId - Unique identifier (user ID, session ID, etc.)
+     * @param content - New conversation content to incorporate
+     * @returns The condensed memory string that was stored, or empty string on failure
+     */
+    add(ownerId: string, content: string): Promise<string>;
+    /**
+     * Get the stored memory for an owner.
+     *
+     * @param ownerId - Unique identifier
+     * @returns The condensed memory string, or null if none exists or on failure
+     */
+    get(ownerId: string): Promise<string | null>;
+    /**
+     * Delete memory for an owner.
+     *
+     * @param ownerId - Unique identifier
+     */
+    delete(ownerId: string): Promise<void>;
+    /**
+     * Close storage connections and clean up resources.
+     */
+    close(): Promise<void>;
 }

package/dist/client.js

@@ -0,0 +1,241 @@
+import { logger } from './logger.js';
+
+const DEFAULT_PROMPT = `You are a memory condensation engine. You receive:
+1. OLD_MEMORY: the user's existing memory summary (may be empty)
+2. NEW_CONTENT: new conversation content
+
+Your job: merge the old memory with relevant new information into a single condensed summary.
+
+Rules:
+- Output ONLY the condensed memory text, nothing else
+- Maximum {{MAX_WORDS}} words
+- Preserve important facts: names, preferences, goals, decisions, context
+- Drop greetings, filler, redundant information
+- If NEW_CONTENT has nothing worth remembering, return OLD_MEMORY unchanged
+- If OLD_MEMORY is empty and NEW_CONTENT has nothing worth remembering, return empty string
+
+OLD_MEMORY:
+{{OLD_MEMORY}}
+
+NEW_CONTENT:
+{{NEW_CONTENT}}
+
+Condensed memory:`;
+class Hippocampus {
+    storage = null;
+    storageConfig;
+    prompt;
+    maxWords;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    neurolink = null;
+    config;
+    constructor(config = {}) {
+        this.config = config;
+        this.storageConfig = config.storage || { type: 'sqlite' };
+        this.prompt = config.prompt || process.env.HC_CONDENSATION_PROMPT || DEFAULT_PROMPT;
+        this.maxWords = config.maxWords || 50;
+        logger.info('Hippocampus initialized', {
+            storage: this.storageConfig.type,
+            maxWords: this.maxWords,
+        });
+    }
+    async ensureStorage() {
+        if (this.storage) {
+            return this.storage;
+        }
+        try {
+            switch (this.storageConfig.type) {
+                case 'sqlite': {
+                    const { SqliteStorage } = await import('./storage/sqlite.js');
+                    this.storage = new SqliteStorage(this.storageConfig);
+                    break;
+                }
+                case 'redis': {
+                    const { RedisStorage } = await import('./storage/redis.js');
+                    this.storage = new RedisStorage(this.storageConfig);
+                    break;
+                }
+                case 's3': {
+                    const { S3Storage } = await import('./storage/s3.js');
+                    this.storage = new S3Storage(this.storageConfig);
+                    break;
+                }
+                default:
+                    logger.error('Unknown storage type', {
+                        type: this.storageConfig.type,
+                    });
+                    return null;
+            }
+        }
+        catch (error) {
+            logger.error('Failed to initialize storage backend', {
+                type: this.storageConfig.type,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+        return this.storage;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async ensureNeurolink() {
+        if (this.neurolink) {
+            return this.neurolink;
+        }
+        try {
+            const { NeuroLink } = await import('@juspay/neurolink');
+            this.neurolink = new NeuroLink();
+            logger.info('NeuroLink instance created for Hippocampus condensation');
+            return this.neurolink;
+        }
+        catch (error) {
+            logger.error('Failed to initialize NeuroLink for condensation', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+    }
+    /**
+     * Add/update memory for an owner.
+     *
+     * Fetches existing memory, merges with new content via LLM, stores result.
+     *
+     * @param ownerId - Unique identifier (user ID, session ID, etc.)
+     * @param content - New conversation content to incorporate
+     * @returns The condensed memory string that was stored, or empty string on failure
+     */
+    async add(ownerId, content) {
+        try {
+            const storage = await this.ensureStorage();
+            if (!storage) {
+                return '';
+            }
+            const neurolink = await this.ensureNeurolink();
+            if (!neurolink) {
+                return '';
+            }
+            let oldMemory = '';
+            try {
+                oldMemory = (await storage.get(ownerId)) || '';
+            }
+            catch (error) {
+                logger.warn('Failed to fetch existing memory, proceeding without it', {
+                    ownerId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            const filledPrompt = this.prompt
+                .replaceAll('{{OLD_MEMORY}}', oldMemory || '(none)')
+                .replaceAll('{{NEW_CONTENT}}', content)
+                .replaceAll('{{MAX_WORDS}}', String(this.maxWords));
+            logger.debug('Condensing memory', {
+                ownerId,
+                oldMemoryLength: oldMemory.length,
+                newContentLength: content.length,
+            });
+            let condensed = '';
+            try {
+                const result = await neurolink.generate({
+                    input: { text: filledPrompt },
+                    provider: this.config.neurolink?.provider,
+                    model: this.config.neurolink?.model,
+                    temperature: this.config.neurolink?.temperature ?? 0.1,
+                    disableTools: true,
+                });
+                condensed = (result?.content || '').trim();
+            }
+            catch (error) {
+                logger.error('LLM condensation call failed', {
+                    ownerId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                return oldMemory;
+            }
+            if (condensed) {
+                try {
+                    await storage.set(ownerId, condensed);
+                    logger.info('Memory updated', { ownerId, words: condensed.split(/\s+/).length });
+                }
+                catch (error) {
+                    logger.error('Failed to persist condensed memory', {
+                        ownerId,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+            else if (oldMemory) {
+                logger.debug('No new memory extracted, keeping existing', { ownerId });
+            }
+            return condensed || oldMemory;
+        }
+        catch (error) {
+            logger.error('Unexpected error in add()', {
+                ownerId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return '';
+        }
+    }
+    /**
+     * Get the stored memory for an owner.
+     *
+     * @param ownerId - Unique identifier
+     * @returns The condensed memory string, or null if none exists or on failure
+     */
+    async get(ownerId) {
+        try {
+            const storage = await this.ensureStorage();
+            if (!storage) {
+                return null;
+            }
+            return await storage.get(ownerId);
+        }
+        catch (error) {
+            logger.error('Failed to get memory', {
+                ownerId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+    }
+    /**
+     * Delete memory for an owner.
+     *
+     * @param ownerId - Unique identifier
+     */
+    async delete(ownerId) {
+        try {
+            const storage = await this.ensureStorage();
+            if (!storage) {
+                return;
+            }
+            await storage.delete(ownerId);
+            logger.info('Memory deleted', { ownerId });
+        }
+        catch (error) {
+            logger.error('Failed to delete memory', {
+                ownerId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    /**
+     * Close storage connections and clean up resources.
+     */
+    async close() {
+        try {
+            if (this.storage) {
+                await this.storage.close();
+                this.storage = null;
+            }
+            logger.info('Hippocampus closed');
+        }
+        catch (error) {
+            logger.error('Failed to close Hippocampus', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            this.storage = null;
+        }
+    }
+}
+
+export { Hippocampus };

package/dist/errors.js

@@ -0,0 +1,19 @@
+class HippocampusError extends Error {
+    statusCode;
+    details;
+    constructor(statusCode, message, details) {
+        super(message);
+        this.statusCode = statusCode;
+        this.details = details;
+        this.name = 'HippocampusError';
+    }
+    static fromResponse(status, body) {
+        if (body && typeof body === 'object' && 'error' in body) {
+            const err = body.error;
+            return new HippocampusError(status, err.message || 'Unknown error', err.details);
+        }
+        return new HippocampusError(status, `HTTP ${status}`);
+    }
+}
+
+export { HippocampusError };

package/dist/index.d.ts

@@ -2,4 +2,7 @@ export { Hippocampus } from './client';
 export { HippocampusError } from './errors';
 export { logger } from './logger';
 export type { LogLevel } from './logger';
-export type { Engram, EngramCreateInput, EngramUpdateInput, SearchQuery, SearchResult, SearchHit, RetrievalTrace, ChronicleHit, Chronicle, ChronicleCreateInput, ChronicleUpdateInput, ChronicleQuery, Nexus, NexusCreateInput, Strand, HealthResponse, StatusResponse, HippocampusOptions, } from './types';
+export type { StorageType, StorageBackend, StorageConfig, SqliteStorageConfig, RedisStorageConfig, S3StorageConfig, HippocampusConfig, } from './types';
+export { SqliteStorage } from './storage/sqlite';
+export { RedisStorage } from './storage/redis';
+export { S3Storage } from './storage/s3';