Documentation

Installation

npm install normal-memory

LLM Providers & Models

OpenAI

Supports every current OpenAI chat/completions model (e.g. gpt-4o, gpt-4o-mini, gpt-4.1, o4-mini, and their real-time variants). Set llmProvider: 'openai' and pass whichever model name you need.

Google Gemini

Set llmProvider: 'gemini' plus models like gemini-2.5-pro, gemini-2.5-flash, or gemini-2.0-flash-lite-001. We validate your selection before we hit Google’s API.

Your LLM API keys stay client-side—Normal Memory reads them per request only. Embeddings and background pipelines still use our managed infrastructure.

Quick Start

import { NormalMemory } from 'normal-memory';

// Initialize SDK
const memory = new NormalMemory({
  apiKey: 'sk_backend_api_key',               // Required: Normal Memory API key
  conversationId: 'conversation-id',          // Required: Conversation ID
  baseUrl: 'https://your-backend-url.com',    // Required: Backend URL
  llmProvider: 'openai',                      // Required: 'openai' | 'gemini'
  llmApiKey: process.env.OPENAI_KEY,          // Required: Bring-your-own LLM key
  llmModel: 'gpt-4o-mini',                    // Optional: Provider-specific model
});

// Use it!
await memory.say("Hi, I'm Alex");
const answer = await memory.ask("What's my name?");

Model agnostic: swap llmProvider, llmApiKey, and llmModel to run against any OpenAI chat/completions model or supported Gemini model. Your LLM keys are never stored.

Core Methods

memory.say(message)

Main method that automatically routes to chat or ask based on message content.

await memory.say("I'm feeling great!");
await memory.say("What do you remember about me?");

memory.chat(message)

Normal conversation with immediate LLM response.

const reply = await memory.chat("Hi, I'm Alex");
// → "Hey Alex! Nice to meet you."

memory.ask(question)

Ask questions using long-term memory.

const answer = await memory.ask("Where do I live?");
// → Uses stored memories to answer

Configuration

const memory = new NormalMemory({
  apiKey: 'sk_...',                 // Required
  conversationId: '...',            // Required
  baseUrl: 'https://...',           // Required backend URL
  llmProvider: 'openai',            // Required: 'openai' | 'gemini'
  llmApiKey: process.env.OPENAI_KEY,// Required: Bring-your-own LLM key
  llmModel: 'gpt-4o-mini',          // Optional: provider-specific override
  smartRouting: true,               // Optional: enable smart routing
});

API Reference

say(message: string): Promise<string>

Automatically routes to chat or ask based on message content.

chat(message: string): Promise<string>

Normal conversation with immediate LLM response.

ask(question: string): Promise<string>

Ask question using long-term memory.

Requirements

  • Node.js >= 18.0.0
  • Valid API key from your backend
  • Valid conversation ID
  • Running Normal Memory backend server

Resources

npm PackageGitHub Repository