@juspay/hippocampus 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,69 @@
+import { Engram, EngramCreateInput, EngramUpdateInput, SearchQuery, SearchResult, Chronicle, ChronicleCreateInput, ChronicleUpdateInput, ChronicleQuery, Nexus, NexusCreateInput, HealthResponse, StatusResponse, HippocampusOptions, Strand } 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;
+}

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+export declare class HippocampusError extends Error {
+    readonly statusCode: number;
+    readonly details?: unknown | undefined;
+    constructor(statusCode: number, message: string, details?: unknown | undefined);
+    static fromResponse(status: number, body: unknown): HippocampusError;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+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';

package/dist/index.js

@@ -0,0 +1,318 @@
+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 };

package/dist/logger.d.ts

@@ -0,0 +1,12 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export declare const logger: {
+    /**
+     * Programmatically override which log levels are active.
+     * Pass an array of levels or `'off'` to disable all logging.
+     */
+    setLevels(levels: LogLevel[] | "off"): void;
+    debug(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+};

package/dist/types.d.ts

@@ -0,0 +1,161 @@
+export type Strand = 'factual' | 'experiential' | 'procedural' | 'preferential' | 'relational' | 'general';
+export interface Engram {
+    id: string;
+    ownerId: string;
+    content: string;
+    contentHash: string;
+    strand: Strand;
+    tags: string[];
+    metadata: Record<string, unknown>;
+    signal: number;
+    pulseRate: number;
+    accessCount: number;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+    lastAccessedAt: string;
+}
+export interface EngramCreateInput {
+    ownerId: string;
+    content: string;
+    strand?: Strand;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+    signal?: number;
+    pulseRate?: number;
+}
+export interface EngramUpdateInput {
+    content?: string;
+    strand?: Strand;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+    signal?: number;
+    pulseRate?: number;
+}
+export interface RetrievalTrace {
+    vectorScore: number;
+    keywordScore: number;
+    recencyBoost: number;
+    signalBoost: number;
+    synapseBoost: number;
+    finalScore: number;
+}
+export interface SearchHit {
+    engram: {
+        id: string;
+        ownerId: string;
+        content: string;
+        strand: Strand;
+        tags: string[];
+        metadata: Record<string, unknown>;
+        signal: number;
+        accessCount: number;
+        createdAt: string;
+        updatedAt: string;
+        lastAccessedAt: string;
+    };
+    trace: RetrievalTrace;
+}
+export interface ChronicleHit {
+    chronicle: Chronicle;
+    relevance: number;
+}
+export interface SearchResult {
+    hits: SearchHit[];
+    chronicles: ChronicleHit[];
+    total: number;
+    query: string;
+    took: number;
+}
+export interface SearchQuery {
+    ownerId: string;
+    query: string;
+    limit?: number;
+    offset?: number;
+    strand?: Strand;
+    tags?: string[];
+    minSignal?: number;
+    minScore?: number;
+    expandSynapses?: boolean;
+}
+export interface Chronicle {
+    id: string;
+    ownerId: string;
+    entity: string;
+    attribute: string;
+    value: string;
+    certainty: number;
+    effectiveFrom: string;
+    effectiveUntil: string | null;
+    recordedAt: string;
+    metadata: Record<string, unknown>;
+}
+export interface ChronicleCreateInput {
+    ownerId: string;
+    entity: string;
+    attribute: string;
+    value: string;
+    certainty?: number;
+    effectiveFrom?: string;
+    effectiveUntil?: string | null;
+    metadata?: Record<string, unknown>;
+}
+export interface ChronicleUpdateInput {
+    certainty?: number;
+    effectiveUntil?: string | null;
+    metadata?: Record<string, unknown>;
+}
+export interface ChronicleQuery {
+    ownerId: string;
+    entity?: string;
+    attribute?: string;
+    at?: string;
+    from?: string;
+    to?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface Nexus {
+    id: string;
+    originId: string;
+    linkedId: string;
+    bondType: string;
+    strength: number;
+    effectiveFrom: string;
+    effectiveUntil: string | null;
+    metadata: Record<string, unknown>;
+}
+export interface NexusCreateInput {
+    originId: string;
+    linkedId: string;
+    bondType: string;
+    strength?: number;
+    effectiveFrom?: string;
+    effectiveUntil?: string | null;
+    metadata?: Record<string, unknown>;
+}
+export interface HealthResponse {
+    status: string;
+    database: string;
+    timestamp: string;
+}
+export interface StatusResponse {
+    database: string;
+    stats: {
+        engrams: number;
+        synapses: number;
+        chronicles: number;
+        nexuses: number;
+    };
+    uptime: number;
+    memory: Record<string, number>;
+}
+export interface HippocampusOptions {
+    /** Server URL. Falls back to HC_BASE_URL env var, then http://localhost:4477 */
+    baseUrl?: string;
+    /** API key. Falls back to HC_API_KEY env var */
+    apiKey?: string;
+    headers?: Record<string, string>;
+    retries?: number;
+    retryDelay?: number;
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@juspay/hippocampus",
+  "version": "0.1.0",
+  "description": "TypeScript client SDK for Hippocampus memory server",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "rollup --config rollup.config.js",
+    "clean": "rm -rf dist",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write 'src/**/*.ts' '*.json' '*.js'",
+    "format:check": "prettier --check 'src/**/*.ts' '*.json' '*.js'",
+    "prepublishOnly": "pnpm run clean && pnpm run build"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-replace": "^6.0.3",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@types/node": "^22.19.8",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-unused-imports": "^4.4.1",
+    "prettier": "^3.8.1",
+    "rollup": "^4.57.1",
+    "tslib": "^2.8.1",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8.55.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/juspay/hippocampus.git",
+    "directory": "sdk"
+  },
+  "homepage": "https://github.com/juspay/hippocampus#readme",
+  "bugs": {
+    "url": "https://github.com/juspay/hippocampus/issues"
+  },
+  "keywords": [
+    "hippocampus",
+    "memory",
+    "ai",
+    "llm",
+    "semantic-search",
+    "vector-database",
+    "embeddings",
+    "ai-agents",
+    "memory-engine"
+  ]
+}