@hazeljs/memory 0.2.0-alpha.3

package/dist/store/memory-store.interface.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Store-agnostic interface for memory backends.
+ */
+import { MemoryItem } from '../types/memory-item.types';
+import { MemoryQuery, MemorySearchOptions, MemoryStats, PruneOptions } from '../types/store.types';
+/**
+ * Interface for memory storage backends.
+ * All stores (in-memory, Postgres, Redis, vector) implement this.
+ */
+export interface MemoryStore {
+    /**
+     * Initialize the store (e.g. connect to DB, create tables).
+     */
+    initialize(): Promise<void>;
+    /**
+     * Save a single memory item. Returns the item id.
+     */
+    save(item: MemoryItem): Promise<string>;
+    /**
+     * Save multiple memory items. Returns array of ids.
+     */
+    saveBatch(items: MemoryItem[]): Promise<string[]>;
+    /**
+     * Get a memory item by id.
+     */
+    get(id: string): Promise<MemoryItem | null>;
+    /**
+     * Update an existing memory item (partial update).
+     */
+    update(id: string, updates: Partial<MemoryItem>): Promise<void>;
+    /**
+     * Delete a memory item by id.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Delete multiple memory items by id.
+     */
+    deleteBatch(ids: string[]): Promise<void>;
+    /**
+     * Query memory items with filters (userId, category, source, etc.).
+     */
+    query(options: MemoryQuery): Promise<MemoryItem[]>;
+    /**
+     * Search memories (text or vector). Optional; stores that do not support search may throw or return [].
+     */
+    search?(query: string | number[], options: MemorySearchOptions): Promise<MemoryItem[]>;
+    /**
+     * Get memory statistics (counts by category, oldest/newest).
+     */
+    getStats(userId?: string): Promise<MemoryStats>;
+    /**
+     * Prune old, expired, or low-confidence items. Returns number of items removed.
+     */
+    prune(options?: PruneOptions): Promise<number>;
+}
+//# sourceMappingURL=memory-store.interface.d.ts.map

package/dist/store/memory-store.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-store.interface.d.ts","sourceRoot":"","sources":["../../src/store/memory-store.interface.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEnG;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B;;OAEG;IACH,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAExC;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAElD;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAE5C;;OAEG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhE;;OAEG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElC;;OAEG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1C;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAEnD;;OAEG;IACH,MAAM,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAEvF;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEhD;;OAEG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAChD"}

package/dist/store/memory-store.interface.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Store-agnostic interface for memory backends.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=memory-store.interface.js.map

package/dist/store/memory-store.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-store.interface.js","sourceRoot":"","sources":["../../src/store/memory-store.interface.ts"],"names":[],"mappings":";AAAA;;GAEG"}

package/dist/types/category.types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Memory categories (buckets) for the unified memory model.
+ */
+export declare enum MemoryCategory {
+    PROFILE = "profile",
+    PREFERENCE = "preference",
+    BEHAVIORAL = "behavioral",
+    EMOTIONAL = "emotional",
+    EPISODIC = "episodic",
+    SEMANTIC_SUMMARY = "semantic_summary"
+}
+/**
+ * Categories that are typically stored in the primary store (non-vector).
+ */
+export declare const PRIMARY_CATEGORIES: MemoryCategory[];
+/**
+ * Categories that benefit from vector search (episodic / semantic recall).
+ */
+export declare const VECTOR_CATEGORIES: MemoryCategory[];
+export interface CategoryBucketConfig {
+    defaultTtlMs?: number;
+    maxItemsPerUser?: number;
+    supportsVectorSearch?: boolean;
+}
+/**
+ * Default per-category configuration (e.g. TTL for emotional).
+ */
+export declare const DEFAULT_CATEGORY_CONFIG: Record<MemoryCategory, CategoryBucketConfig>;
+//# sourceMappingURL=category.types.d.ts.map

package/dist/types/category.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"category.types.d.ts","sourceRoot":"","sources":["../../src/types/category.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,oBAAY,cAAc;IACxB,OAAO,YAAY;IACnB,UAAU,eAAe;IACzB,UAAU,eAAe;IACzB,SAAS,cAAc;IACvB,QAAQ,aAAa;IACrB,gBAAgB,qBAAqB;CACtC;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,cAAc,EAM9C,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,cAAc,EAG7C,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,cAAc,EAAE,oBAAoB,CAOhF,CAAC"}

package/dist/types/category.types.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * Memory categories (buckets) for the unified memory model.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CATEGORY_CONFIG = exports.VECTOR_CATEGORIES = exports.PRIMARY_CATEGORIES = exports.MemoryCategory = void 0;
+var MemoryCategory;
+(function (MemoryCategory) {
+    MemoryCategory["PROFILE"] = "profile";
+    MemoryCategory["PREFERENCE"] = "preference";
+    MemoryCategory["BEHAVIORAL"] = "behavioral";
+    MemoryCategory["EMOTIONAL"] = "emotional";
+    MemoryCategory["EPISODIC"] = "episodic";
+    MemoryCategory["SEMANTIC_SUMMARY"] = "semantic_summary";
+})(MemoryCategory || (exports.MemoryCategory = MemoryCategory = {}));
+/**
+ * Categories that are typically stored in the primary store (non-vector).
+ */
+exports.PRIMARY_CATEGORIES = [
+    MemoryCategory.PROFILE,
+    MemoryCategory.PREFERENCE,
+    MemoryCategory.BEHAVIORAL,
+    MemoryCategory.EMOTIONAL,
+    MemoryCategory.SEMANTIC_SUMMARY,
+];
+/**
+ * Categories that benefit from vector search (episodic / semantic recall).
+ */
+exports.VECTOR_CATEGORIES = [
+    MemoryCategory.EPISODIC,
+    MemoryCategory.SEMANTIC_SUMMARY,
+];
+/**
+ * Default per-category configuration (e.g. TTL for emotional).
+ */
+exports.DEFAULT_CATEGORY_CONFIG = {
+    [MemoryCategory.PROFILE]: { maxItemsPerUser: 500 },
+    [MemoryCategory.PREFERENCE]: { maxItemsPerUser: 1000 },
+    [MemoryCategory.BEHAVIORAL]: { maxItemsPerUser: 500 },
+    [MemoryCategory.EMOTIONAL]: { defaultTtlMs: 30 * 60 * 1000, maxItemsPerUser: 100 }, // 30 min default TTL
+    [MemoryCategory.EPISODIC]: { maxItemsPerUser: 5000, supportsVectorSearch: true },
+    [MemoryCategory.SEMANTIC_SUMMARY]: { maxItemsPerUser: 50, supportsVectorSearch: true },
+};
+//# sourceMappingURL=category.types.js.map

package/dist/types/category.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"category.types.js","sourceRoot":"","sources":["../../src/types/category.types.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,IAAY,cAOX;AAPD,WAAY,cAAc;IACxB,qCAAmB,CAAA;IACnB,2CAAyB,CAAA;IACzB,2CAAyB,CAAA;IACzB,yCAAuB,CAAA;IACvB,uCAAqB,CAAA;IACrB,uDAAqC,CAAA;AACvC,CAAC,EAPW,cAAc,8BAAd,cAAc,QAOzB;AAED;;GAEG;AACU,QAAA,kBAAkB,GAAqB;IAClD,cAAc,CAAC,OAAO;IACtB,cAAc,CAAC,UAAU;IACzB,cAAc,CAAC,UAAU;IACzB,cAAc,CAAC,SAAS;IACxB,cAAc,CAAC,gBAAgB;CAChC,CAAC;AAEF;;GAEG;AACU,QAAA,iBAAiB,GAAqB;IACjD,cAAc,CAAC,QAAQ;IACvB,cAAc,CAAC,gBAAgB;CAChC,CAAC;AAQF;;GAEG;AACU,QAAA,uBAAuB,GAAiD;IACnF,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,EAAE,eAAe,EAAE,GAAG,EAAE;IAClD,CAAC,cAAc,CAAC,UAAU,CAAC,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE;IACtD,CAAC,cAAc,CAAC,UAAU,CAAC,EAAE,EAAE,eAAe,EAAE,GAAG,EAAE;IACrD,CAAC,cAAc,CAAC,SAAS,CAAC,EAAE,EAAE,YAAY,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,eAAe,EAAE,GAAG,EAAE,EAAE,qBAAqB;IACzG,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE;IAChF,CAAC,cAAc,CAAC,gBAAgB,CAAC,EAAE,EAAE,eAAe,EAAE,EAAE,EAAE,oBAAoB,EAAE,IAAI,EAAE;CACvF,CAAC"}

package/dist/types/memory-item.types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Core memory item schema (explicit / inferred / system).
+ */
+import { MemoryCategory } from './category.types';
+export type MemorySource = 'explicit' | 'inferred' | 'system';
+/**
+ * Value can be string, structured object, or embedding vector.
+ */
+export type MemoryValue = string | Record<string, unknown> | number[];
+export interface MemoryItem {
+    id: string;
+    userId: string;
+    category: MemoryCategory;
+    key: string;
+    value: MemoryValue;
+    confidence: number;
+    source: MemorySource;
+    evidence: string[];
+    createdAt: Date;
+    updatedAt: Date;
+    expiresAt?: Date;
+    accessCount: number;
+    sessionId?: string;
+}
+/**
+ * Input for creating a memory (id and timestamps can be omitted).
+ */
+export interface MemoryItemInput extends Omit<MemoryItem, 'id' | 'createdAt' | 'updatedAt' | 'accessCount'> {
+    id?: string;
+    accessCount?: number;
+}
+//# sourceMappingURL=memory-item.types.d.ts.map

package/dist/types/memory-item.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-item.types.d.ts","sourceRoot":"","sources":["../../src/types/memory-item.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE9D;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,CAAC;AAEtE,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,cAAc,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,WAAW,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAC3C,UAAU,EACV,IAAI,GAAG,WAAW,GAAG,WAAW,GAAG,aAAa,CACjD;IACC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}

package/dist/types/memory-item.types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Core memory item schema (explicit / inferred / system).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=memory-item.types.js.map

package/dist/types/memory-item.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-item.types.js","sourceRoot":"","sources":["../../src/types/memory-item.types.ts"],"names":[],"mappings":";AAAA;;GAEG"}

package/dist/types/store.types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Query, options, and stats for memory stores.
+ */
+import { MemoryCategory } from './category.types';
+export interface MemoryQuery {
+    userId: string;
+    category?: MemoryCategory | MemoryCategory[];
+    source?: import('./memory-item.types').MemorySource | import('./memory-item.types').MemorySource[];
+    minConfidence?: number;
+    notExpired?: boolean;
+    limit?: number;
+    offset?: number;
+    orderBy?: 'createdAt' | 'updatedAt';
+    order?: 'asc' | 'desc';
+}
+export interface MemorySearchOptions {
+    userId: string;
+    category?: MemoryCategory | MemoryCategory[];
+    topK?: number;
+    minScore?: number;
+    vectorQuery?: number[];
+}
+export interface MemoryStats {
+    total: number;
+    byCategory: Record<MemoryCategory, number>;
+    oldestMemory: Date | null;
+    newestMemory: Date | null;
+}
+export interface PruneOptions {
+    userId?: string;
+    olderThan?: Date;
+    minConfidence?: number;
+    category?: MemoryCategory;
+    maxItemsPerUser?: number;
+}
+//# sourceMappingURL=store.types.d.ts.map

package/dist/types/store.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.types.d.ts","sourceRoot":"","sources":["../../src/types/store.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,cAAc,GAAG,cAAc,EAAE,CAAC;IAC7C,MAAM,CAAC,EACH,OAAO,qBAAqB,EAAE,YAAY,GAC1C,OAAO,qBAAqB,EAAE,YAAY,EAAE,CAAC;IACjD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,WAAW,GAAG,WAAW,CAAC;IACpC,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,cAAc,GAAG,cAAc,EAAE,CAAC;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;IAC3C,YAAY,EAAE,IAAI,GAAG,IAAI,CAAC;IAC1B,YAAY,EAAE,IAAI,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B"}

package/dist/types/store.types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Query, options, and stats for memory stores.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=store.types.js.map

package/dist/types/store.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.types.js","sourceRoot":"","sources":["../../src/types/store.types.ts"],"names":[],"mappings":";AAAA;;GAEG"}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@hazeljs/memory",
+  "version": "0.2.0-alpha.3",
+  "description": "Pluggable user memory for HazelJS - profile, preferences, behavioral patterns, emotional state, episodic and semantic memory with multi-store support",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./prisma": {
+      "types": "./dist/prisma.d.ts",
+      "default": "./dist/prisma.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "prisma generate && tsc --skipLibCheck && (test -d src/generated && cp -r src/generated dist/ || true)",
+    "prisma:generate": "prisma generate",
+    "prisma:migrate": "prisma migrate dev",
+    "prisma:deploy": "prisma migrate deploy",
+    "test": "jest --coverage --passWithNoTests",
+    "lint": "eslint \"src/**/*.ts\"",
+    "lint:fix": "eslint \"src/**/*.ts\" --fix",
+    "clean": "rm -rf dist"
+  },
+  "optionalDependencies": {
+    "@prisma/client": "^6.8.2"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.17.50",
+    "@typescript-eslint/eslint-plugin": "^8.18.2",
+    "@typescript-eslint/parser": "^8.18.2",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "prisma": "^6.8.2",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.3.3"
+  },
+  "peerDependencies": {
+    "ioredis": "^5.0.0",
+    "pg": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hazeljs/hazeljs",
+    "directory": "packages/memory"
+  },
+  "keywords": [
+    "hazeljs",
+    "memory",
+    "user-memory",
+    "preferences",
+    "episodic",
+    "agent",
+    "rag",
+    "prisma"
+  ],
+  "author": "Muhammad Arslan <muhammad.arslan@hazeljs.com>",
+  "license": "Apache-2.0",
+  "gitHead": "17ca4464a7955c10c0e4e151a83daf900213bb7a"
+}