@hazeljs/memory

Pluggable user memory for HazelJS. Profile, preferences, behavioral patterns, emotional state, episodic and semantic memory — one interface, multiple backends. Share the same store between RAG and agents in-process.

Storage: By default the package uses in-memory storage (no dependencies). For durable persistence, use the Prisma store (same pattern as @hazeljs/flow) or plug in Postgres, Redis, or vector backends.

Features

• One interface, multiple backends — In-memory (default), Postgres (raw or Prisma), Redis, vector episodic, composite
• Memory categories — Profile, preference, behavioral, emotional, episodic, semantic_summary
• Explicit vs inferred — Store user-stated facts and system-inferred patterns separately
• Optional TTL — e.g. for emotional state or short-lived context
• Composite store — Route by category to primary + optional episodic/vector store
• RAG & agent integration — Use createHazelMemoryStoreAdapter from @hazeljs/rag/memory-hazel to back MemoryManager; share one store across RAGPipelineWithMemory and AgentRuntime

Installation

pnpm add @hazeljs/memory

No database or env vars are required for the default in-memory mode.

Quick Start

In-memory (default, no dependencies)

import { createDefaultMemoryStore, MemoryService } from '@hazeljs/memory';

const store = createDefaultMemoryStore();
const service = new MemoryService(store);
await service.initialize();

// Use service to get/set memory by userId, category, etc.

PostgreSQL with Prisma

When you use Prisma in your app (e.g. like @hazeljs/flow and @hazeljs/flow-runtime), use the Prisma store:

import { createPrismaMemoryStore, getMemoryPrismaClient } from '@hazeljs/memory/prisma';
import { MemoryService } from '@hazeljs/memory';

const prisma = getMemoryPrismaClient(process.env.DATABASE_URL);
const store = createPrismaMemoryStore(prisma);
const service = new MemoryService(store);
await service.initialize();

Build: Run pnpm prisma:generate (or prisma generate) before pnpm build so the Prisma client is generated. Migrate with pnpm prisma:migrate from the package directory.

Persistence

| Backend | Module / Factory | Use case | | ------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------ | | In-memory | createDefaultMemoryStore() | Development, tests, no DB | | Prisma | createPrismaMemoryStore(prisma) from @hazeljs/memory/prisma | Production, same app DB as flow/core | | Postgres (raw) | PostgresStore — pass a pg pool with a query method (see postgres.store.ts) | Existing Postgres without Prisma | | Redis | RedisStore — pass an ioredis-style client | High-throughput, shared across processes | | Vector episodic | VectorEpisodicStore | Episodic/semantic vector search | | Composite | CompositeMemoryStore | Route by category to primary + optional episodic store |

Memory categories

| Category | Description | | ------------------ | ----------------------------------------- | | profile | User identity and static attributes | | preference | Stated preferences (e.g. language, theme) | | behavioral | Inferred behavior patterns | | emotional | Emotional state (often with TTL) | | episodic | Event-based memories (what happened when) | | semantic_summary | Summarized or semantic facts |

See types in src/types/.

Integration with @hazeljs/rag and @hazeljs/agent

To back RAG (and agent) memory with @hazeljs/memory so RAG and agents share the same user context in-process:

pnpm add @hazeljs/rag @hazeljs/memory

import { MemoryManager, RAGPipelineWithMemory } from '@hazeljs/rag';
import { createHazelMemoryStoreAdapter } from '@hazeljs/rag/memory-hazel';
import { MemoryService, createDefaultMemoryStore } from '@hazeljs/memory';

const hazelStore = createDefaultMemoryStore();
const memoryService = new MemoryService(hazelStore);
const ragStore = createHazelMemoryStoreAdapter(memoryService);
const memoryManager = new MemoryManager(ragStore);

// Pass the same MemoryManager to RAG and to every AgentRuntime
const rag = new RAGPipelineWithMemory(config, memoryManager, llmFunction);
// agentRuntime = new AgentRuntime({ ..., memoryManager });

See @hazeljs/rag README (Memory System / Using @hazeljs/memory as the backend) for full details.

Scripts

• prisma:generate — Generate Prisma client
• prisma:migrate — Run migrations (dev)
• prisma:deploy — Deploy migrations (prod)
• prisma:studio — Open Prisma Studio (when using Prisma store)
• test — Run tests

License

Apache 2.0 © HazelJS

Contributing

Contributions are welcome! See CONTRIBUTING.md for details.