@juspay/hippocampus 0.1.0 → 0.1.1

package/dist/index.js

@@ -1,318 +1,6 @@
-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}`);
-    }
-}
-
-const ALL_LEVELS = ['debug', 'info', 'warn', 'error'];
-function parseLogLevels(input) {
-    const trimmed = input.trim().toLowerCase();
-    if (trimmed === 'off' || trimmed === '') {
-        return new Set();
-    }
-    const levels = trimmed
-        .split(',')
-        .map((s) => s.trim())
-        .filter(Boolean);
-    return new Set(levels.filter((l) => ALL_LEVELS.includes(l)));
-}
-let enabledLevels = null;
-function getEnabledLevels() {
-    if (enabledLevels === null) {
-        enabledLevels = parseLogLevels(process.env.HC_LOG_LEVEL || 'off');
-    }
-    return enabledLevels;
-}
-function shouldLog(level) {
-    return getEnabledLevels().has(level);
-}
-function formatMessage(level, message, context) {
-    const timestamp = new Date().toISOString();
-    const base = `[${timestamp}] [HIPPOCAMPUS@0.1.0] [${level.toUpperCase()}] ${message}`;
-    if (context && Object.keys(context).length > 0) {
-        return `${base} ${JSON.stringify(context)}`;
-    }
-    return base;
-}
-const logger = {
-    /**
-     * Programmatically override which log levels are active.
-     * Pass an array of levels or `'off'` to disable all logging.
-     */
-    setLevels(levels) {
-        enabledLevels = levels === 'off' ? new Set() : new Set(levels);
-    },
-    debug(message, context) {
-        if (shouldLog('debug')) {
-            console.debug(formatMessage('debug', message, context));
-        }
-    },
-    info(message, context) {
-        if (shouldLog('info')) {
-            console.info(formatMessage('info', message, context));
-        }
-    },
-    warn(message, context) {
-        if (shouldLog('warn')) {
-            console.warn(formatMessage('warn', message, context));
-        }
-    },
-    error(message, context) {
-        if (shouldLog('error')) {
-            console.error(formatMessage('error', message, context));
-        }
-    },
-};
-
-class Hippocampus {
-    baseUrl;
-    headers;
-    retries;
-    retryDelay;
-    constructor(options = {}) {
-        const baseUrl = options.baseUrl || process.env.HC_BASE_URL || 'http://localhost:4477';
-        const apiKey = options.apiKey || process.env.HC_API_KEY;
-        this.baseUrl = baseUrl.replace(/\/$/, '');
-        this.headers = {
-            'Content-Type': 'application/json',
-            ...(apiKey ? { 'X-API-Key': apiKey } : {}),
-            ...options.headers,
-        };
-        this.retries = options.retries ?? 0;
-        this.retryDelay = options.retryDelay ?? 1000;
-        logger.debug('Hippocampus client initialized', {
-            baseUrl: this.baseUrl,
-            retries: this.retries,
-            retryDelay: this.retryDelay,
-            hasApiKey: !!apiKey,
-        });
-    }
-    // --- Engrams ---
-    async addMemory(input) {
-        logger.info('Adding memory', { ownerId: input.ownerId, strand: input.strand });
-        const result = await this.post('/api/engrams', input);
-        logger.info('Memory added', { count: result.engrams.length });
-        return result;
-    }
-    async listEngrams(ownerId, options) {
-        logger.debug('Listing engrams', { ownerId, ...options });
-        const params = new URLSearchParams({ ownerId });
-        if (options?.limit) {
-            params.set('limit', String(options.limit));
-        }
-        if (options?.offset) {
-            params.set('offset', String(options.offset));
-        }
-        if (options?.strand) {
-            params.set('strand', options.strand);
-        }
-        const result = await this.get(`/api/engrams?${params}`);
-        logger.debug('Engrams listed', { total: result.total });
-        return result;
-    }
-    async getEngram(id) {
-        logger.debug('Getting engram', { id });
-        return this.get(`/api/engrams/${id}`);
-    }
-    async updateEngram(id, input) {
-        logger.info('Updating engram', { id });
-        const result = await this.patch(`/api/engrams/${id}`, input);
-        logger.info('Engram updated', { id });
-        return result;
-    }
-    async deleteEngram(id) {
-        logger.info('Deleting engram', { id });
-        await this.del(`/api/engrams/${id}`);
-        logger.info('Engram deleted', { id });
-    }
-    async search(query) {
-        logger.info('Searching engrams', { ownerId: query.ownerId, query: query.query, limit: query.limit });
-        const result = await this.post('/api/engrams/search', query);
-        logger.info('Search completed', { hits: result.hits.length, total: result.total, took: result.took });
-        return result;
-    }
-    async reinforceEngram(id, boost) {
-        logger.debug('Reinforcing engram', { id, boost });
-        const result = await this.post(`/api/engrams/${id}/reinforce`, { boost });
-        logger.debug('Engram reinforced', { id, signal: result.engram.signal });
-        return result;
-    }
-    // --- Chronicles ---
-    async recordChronicle(input) {
-        logger.info('Recording chronicle', { ownerId: input.ownerId, entity: input.entity, attribute: input.attribute });
-        const result = await this.post('/api/chronicles', input);
-        logger.info('Chronicle recorded', { id: result.chronicle.id });
-        return result;
-    }
-    async queryChronicles(query) {
-        logger.debug('Querying chronicles', { ownerId: query.ownerId, entity: query.entity, attribute: query.attribute });
-        const params = new URLSearchParams({ ownerId: query.ownerId });
-        if (query.entity) {
-            params.set('entity', query.entity);
-        }
-        if (query.attribute) {
-            params.set('attribute', query.attribute);
-        }
-        if (query.at) {
-            params.set('at', query.at);
-        }
-        if (query.from) {
-            params.set('from', query.from);
-        }
-        if (query.to) {
-            params.set('to', query.to);
-        }
-        if (query.limit) {
-            params.set('limit', String(query.limit));
-        }
-        if (query.offset) {
-            params.set('offset', String(query.offset));
-        }
-        const result = await this.get(`/api/chronicles?${params}`);
-        logger.debug('Chronicles queried', { total: result.total });
-        return result;
-    }
-    async getCurrentFact(ownerId, entity, attribute) {
-        logger.debug('Getting current fact', { ownerId, entity, attribute });
-        const params = new URLSearchParams({ ownerId, entity, attribute });
-        return this.get(`/api/chronicles/current?${params}`);
-    }
-    async getTimeline(ownerId, entity) {
-        logger.debug('Getting timeline', { ownerId, entity });
-        const params = new URLSearchParams({ ownerId, entity });
-        const result = await this.get(`/api/chronicles/timeline?${params}`);
-        logger.debug('Timeline retrieved', { count: result.chronicles.length });
-        return result;
-    }
-    async getChronicle(id) {
-        logger.debug('Getting chronicle', { id });
-        return this.get(`/api/chronicles/${id}`);
-    }
-    async updateChronicle(id, input) {
-        logger.info('Updating chronicle', { id });
-        const result = await this.patch(`/api/chronicles/${id}`, input);
-        logger.info('Chronicle updated', { id });
-        return result;
-    }
-    async expireChronicle(id) {
-        logger.info('Expiring chronicle', { id });
-        await this.del(`/api/chronicles/${id}`);
-        logger.info('Chronicle expired', { id });
-    }
-    // --- Nexuses ---
-    async createNexus(input) {
-        logger.info('Creating nexus', { originId: input.originId, linkedId: input.linkedId, bondType: input.bondType });
-        const result = await this.post('/api/nexuses', input);
-        logger.info('Nexus created', { id: result.nexus.id });
-        return result;
-    }
-    async getRelatedChronicles(chronicleId) {
-        logger.debug('Getting related chronicles', { chronicleId });
-        const result = await this.get(`/api/chronicles/${chronicleId}/related`);
-        logger.debug('Related chronicles retrieved', { count: result.related.length });
-        return result;
-    }
-    // --- System ---
-    async health() {
-        logger.debug('Health check');
-        return this.get('/api/health');
-    }
-    async status() {
-        logger.debug('Status check');
-        return this.get('/api/status');
-    }
-    async runDecay(ownerId) {
-        logger.info('Running decay', { ownerId });
-        const result = await this.post('/api/decay/run', { ownerId });
-        logger.info('Decay completed', { affected: result.affected });
-        return result;
-    }
-    // --- HTTP helpers ---
-    async request(method, path, body) {
-        const url = `${this.baseUrl}${path}`;
-        let lastError = null;
-        for (let attempt = 0; attempt <= this.retries; attempt++) {
-            try {
-                if (attempt > 0) {
-                    logger.warn('Retrying request', { method, path, attempt, maxRetries: this.retries });
-                }
-                logger.debug('Sending request', { method, url });
-                const response = await fetch(url, {
-                    method,
-                    headers: this.headers,
-                    body: body ? JSON.stringify(body) : undefined,
-                });
-                if (response.status === 204) {
-                    logger.debug('Request successful (204 No Content)', { method, path });
-                    return undefined;
-                }
-                const json = await response.json();
-                if (!response.ok) {
-                    const error = HippocampusError.fromResponse(response.status, json);
-                    logger.error('Request failed with HTTP error', {
-                        method,
-                        path,
-                        statusCode: response.status,
-                        message: error.message,
-                    });
-                    throw error;
-                }
-                logger.debug('Request successful', { method, path, status: response.status });
-                return json;
-            }
-            catch (error) {
-                lastError = error instanceof Error ? error : new Error(String(error));
-                // Don't retry client errors (4xx)
-                if (error instanceof HippocampusError && error.statusCode >= 400 && error.statusCode < 500) {
-                    throw error;
-                }
-                if (attempt < this.retries) {
-                    const delay = this.retryDelay * Math.pow(2, attempt);
-                    logger.warn('Request failed, will retry', {
-                        method,
-                        path,
-                        attempt,
-                        nextRetryIn: `${delay}ms`,
-                        error: lastError.message,
-                    });
-                    await new Promise((resolve) => setTimeout(resolve, delay));
-                }
-                else {
-                    logger.error('Request failed after all retries', {
-                        method,
-                        path,
-                        attempts: attempt + 1,
-                        error: lastError.message,
-                    });
-                }
-            }
-        }
-        throw lastError || new Error('Request failed');
-    }
-    get(path) {
-        return this.request('GET', path);
-    }
-    post(path, body) {
-        return this.request('POST', path, body);
-    }
-    patch(path, body) {
-        return this.request('PATCH', path, body);
-    }
-    del(path) {
-        return this.request('DELETE', path);
-    }
-}
-
-export { Hippocampus, HippocampusError, logger };
+export { Hippocampus } from './client.js';
+export { HippocampusError } from './errors.js';
+export { logger } from './logger.js';
+export { SqliteStorage } from './storage/sqlite.js';
+export { RedisStorage } from './storage/redis.js';
+export { S3Storage } from './storage/s3.js';

package/dist/logger.js

@@ -0,0 +1,61 @@
+const ALL_LEVELS = ['debug', 'info', 'warn', 'error'];
+function parseLogLevels(input) {
+    const trimmed = input.trim().toLowerCase();
+    if (trimmed === 'off' || trimmed === '') {
+        return new Set();
+    }
+    const levels = trimmed
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    return new Set(levels.filter((l) => ALL_LEVELS.includes(l)));
+}
+let enabledLevels = null;
+function getEnabledLevels() {
+    if (enabledLevels === null) {
+        enabledLevels = parseLogLevels(process.env.HC_LOG_LEVEL || 'off');
+    }
+    return enabledLevels;
+}
+function shouldLog(level) {
+    return getEnabledLevels().has(level);
+}
+function formatMessage(level, message, context) {
+    const timestamp = new Date().toISOString();
+    const base = `[${timestamp}] [HIPPOCAMPUS@0.1.1] [${level.toUpperCase()}] ${message}`;
+    if (context && Object.keys(context).length > 0) {
+        return `${base} ${JSON.stringify(context)}`;
+    }
+    return base;
+}
+const logger = {
+    /**
+     * Programmatically override which log levels are active.
+     * Pass an array of levels or `'off'` to disable all logging.
+     */
+    setLevels(levels) {
+        enabledLevels = levels === 'off' ? new Set() : new Set(levels);
+    },
+    debug(message, context) {
+        if (shouldLog('debug')) {
+            console.debug(formatMessage('debug', message, context));
+        }
+    },
+    info(message, context) {
+        if (shouldLog('info')) {
+            console.info(formatMessage('info', message, context));
+        }
+    },
+    warn(message, context) {
+        if (shouldLog('warn')) {
+            console.warn(formatMessage('warn', message, context));
+        }
+    },
+    error(message, context) {
+        if (shouldLog('error')) {
+            console.error(formatMessage('error', message, context));
+        }
+    },
+};
+
+export { logger };

package/dist/storage/redis.d.ts

@@ -0,0 +1,14 @@
+import type { StorageBackend, RedisStorageConfig } from '../types';
+export declare class RedisStorage implements StorageBackend {
+    private client;
+    private keyPrefix;
+    private ttl;
+    private config;
+    constructor(config: RedisStorageConfig);
+    private ensureClient;
+    private key;
+    get(ownerId: string): Promise<string | null>;
+    set(ownerId: string, memory: string): Promise<void>;
+    delete(ownerId: string): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/storage/redis.js

@@ -0,0 +1,98 @@
+import { logger } from '../logger.js';
+
+class RedisStorage {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    client = null;
+    keyPrefix;
+    ttl;
+    config;
+    constructor(config) {
+        this.config = config;
+        this.keyPrefix = config.keyPrefix || 'hippocampus:memory:';
+        this.ttl = config.ttl || 0;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async ensureClient() {
+        if (this.client) {
+            return this.client;
+        }
+        const { createClient } = await import('redis');
+        const host = this.config.host || process.env.REDIS_HOST || 'localhost';
+        const port = this.config.port || parseInt(process.env.REDIS_PORT || '6379', 10);
+        const password = this.config.password || process.env.REDIS_PASSWORD || undefined;
+        const db = this.config.db ?? parseInt(process.env.REDIS_DB || '0', 10);
+        this.client = createClient({
+            socket: { host, port },
+            password,
+            database: db,
+        });
+        this.client.on('error', (err) => {
+            logger.error('Redis client error', { error: err.message });
+        });
+        await this.client.connect();
+        logger.info('Redis storage initialized', { host, port, db, keyPrefix: this.keyPrefix });
+        return this.client;
+    }
+    key(ownerId) {
+        return `${this.keyPrefix}${ownerId}`;
+    }
+    async get(ownerId) {
+        try {
+            const client = await this.ensureClient();
+            return await client.get(this.key(ownerId));
+        }
+        catch (error) {
+            logger.error('Redis get failed', {
+                ownerId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+    }
+    async set(ownerId, memory) {
+        try {
+            const client = await this.ensureClient();
+            if (this.ttl > 0) {
+                await client.set(this.key(ownerId), memory, { EX: this.ttl });
+            }
+            else {
+                await client.set(this.key(ownerId), memory);
+            }
+        }
+        catch (error) {
+            logger.error('Redis set failed', {
+                ownerId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    async delete(ownerId) {
+        try {
+            const client = await this.ensureClient();
+            await client.del(this.key(ownerId));
+        }
+        catch (error) {
+            logger.error('Redis delete failed', {
+                ownerId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    async close() {
+        try {
+            if (this.client) {
+                await this.client.quit();
+                this.client = null;
+                logger.info('Redis storage closed');
+            }
+        }
+        catch (error) {
+            logger.error('Redis close failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            this.client = null;
+        }
+    }
+}
+
+export { RedisStorage };

package/dist/storage/s3.d.ts

@@ -0,0 +1,13 @@
+import type { StorageBackend, S3StorageConfig } from '../types';
+export declare class S3Storage implements StorageBackend {
+    private s3;
+    private bucket;
+    private prefix;
+    constructor(config: S3StorageConfig);
+    private ensureClient;
+    private objectKey;
+    get(ownerId: string): Promise<string | null>;
+    set(ownerId: string, memory: string): Promise<void>;
+    delete(ownerId: string): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/storage/s3.js

@@ -0,0 +1,108 @@
+import { logger } from '../logger.js';
+
+class S3Storage {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    s3 = null;
+    bucket;
+    prefix;
+    constructor(config) {
+        this.bucket = config.bucket;
+        this.prefix = config.prefix || 'hippocampus/memories/';
+        // Ensure prefix ends with /
+        if (this.prefix && !this.prefix.endsWith('/')) {
+            this.prefix += '/';
+        }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async ensureClient() {
+        if (this.s3) {
+            return this.s3;
+        }
+        const { S3Client } = await import('@aws-sdk/client-s3');
+        this.s3 = new S3Client({});
+        logger.info('S3 storage initialized', {
+            bucket: this.bucket,
+            prefix: this.prefix,
+        });
+        return this.s3;
+    }
+    objectKey(ownerId) {
+        return `${this.prefix}${ownerId}`;
+    }
+    async get(ownerId) {
+        try {
+            const s3 = await this.ensureClient();
+            const { GetObjectCommand } = await import('@aws-sdk/client-s3');
+            const response = await s3.send(new GetObjectCommand({
+                Bucket: this.bucket,
+                Key: this.objectKey(ownerId),
+            }));
+            return (await response.Body?.transformToString('utf-8')) ?? null;
+        }
+        catch (error) {
+            // NoSuchKey = ownerId not found — not an error
+            if (error && typeof error === 'object' && 'name' in error && error.name === 'NoSuchKey') {
+                return null;
+            }
+            logger.error('S3 get failed', {
+                ownerId,
+                bucket: this.bucket,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+    }
+    async set(ownerId, memory) {
+        try {
+            const s3 = await this.ensureClient();
+            const { PutObjectCommand } = await import('@aws-sdk/client-s3');
+            await s3.send(new PutObjectCommand({
+                Bucket: this.bucket,
+                Key: this.objectKey(ownerId),
+                Body: memory,
+                ContentType: 'text/plain; charset=utf-8',
+            }));
+        }
+        catch (error) {
+            logger.error('S3 set failed', {
+                ownerId,
+                bucket: this.bucket,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    async delete(ownerId) {
+        try {
+            const s3 = await this.ensureClient();
+            const { DeleteObjectCommand } = await import('@aws-sdk/client-s3');
+            await s3.send(new DeleteObjectCommand({
+                Bucket: this.bucket,
+                Key: this.objectKey(ownerId),
+            }));
+        }
+        catch (error) {
+            logger.error('S3 delete failed', {
+                ownerId,
+                bucket: this.bucket,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    async close() {
+        try {
+            if (this.s3) {
+                this.s3.destroy?.();
+                this.s3 = null;
+                logger.info('S3 storage closed');
+            }
+        }
+        catch (error) {
+            logger.error('S3 close failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            this.s3 = null;
+        }
+    }
+}
+
+export { S3Storage };

package/dist/storage/sqlite.d.ts

@@ -0,0 +1,11 @@
+import type { StorageBackend, SqliteStorageConfig } from '../types';
+export declare class SqliteStorage implements StorageBackend {
+    private db;
+    private dbPath;
+    constructor(config?: SqliteStorageConfig);
+    private ensureDb;
+    get(ownerId: string): Promise<string | null>;
+    set(ownerId: string, memory: string): Promise<void>;
+    delete(ownerId: string): Promise<void>;
+    close(): Promise<void>;
+}