@daily/memory

Universal memory SDK for Daily applications. Combines mem0 (AI memory) with memgraph (graph intelligence) to provide a simple, powerful memory interface.

Features

• AI Memory Storage: Vector-based semantic search via mem0
• Graph Intelligence: Relationship tracking via memgraph
• Multi-tenancy: Workspace-scoped memories
• Type-safe: Full TypeScript support
• Production-ready: Built-in logging, error handling, and health checks

Installation

npm install @daily/memory

Quick Start

import { MemoryClient, MemoryType, EntityType } from '@daily/memory';

const memory = new MemoryClient({
  workspaceId: 'workspace-abc',
  userId: 'user-123',
  supabaseUrl: process.env.SUPABASE_URL,
  supabaseServiceKey: process.env.SUPABASE_SERVICE_ROLE_KEY,
  mem0Url: 'http://localhost:8000',
  mem0ApiKey: process.env.MEM0_API_KEY,
});

// Add a memory
await memory.add({
  content: 'User prefers dark mode and short meetings',
  type: MemoryType.PREFERENCE,
  entityType: EntityType.USER,
  importance: 0.8,
});

// Search memories
const results = await memory.search({
  query: 'What are the user preferences?',
  limit: 5,
});

Environment Variables

# Supabase (required for metadata tracking)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=eyJ...

# mem0 (required)
MEM0_API_KEY=your-api-key
MEM0_URL=http://localhost:8000  # Optional, defaults to localhost or api.mem0.ai

# memgraph (optional, for graph queries)
MEMGRAPH_URL=bolt://localhost:7687
MEMGRAPH_USERNAME=memgraph
MEMGRAPH_PASSWORD=memgraph

# Logging (optional)
DAILY_MEMORY_LOG_LEVEL=info  # debug, info, warn, error

API Reference

MemoryClient

Main client interface for memory operations.

Constructor

new MemoryClient(options: MemoryClientOptions)

Options:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | workspaceId | string | Yes | Workspace ID for multi-tenancy | | userId | string | Yes | Universal user ID | | supabaseUrl | string | No* | Supabase URL (or use SUPABASE_URL) | | supabaseServiceKey | string | No* | Supabase service key (or use SUPABASE_SERVICE_ROLE_KEY) | | mem0Url | string | No | mem0 API endpoint (default: localhost) | | mem0ApiKey | string | No* | mem0 API key (or use MEM0_API_KEY) | | mode | 'development' \| 'production' | No | Environment mode (default: development) |

*Required if not set in environment variables.

Methods

add(memory: MemoryInput): Promise<Memory>

Add a new memory.

const memory = await memory.add({
  content: 'User prefers morning meetings',
  type: MemoryType.PREFERENCE,
  entityType: EntityType.USER,
  entityId: 'user-123',
  importance: 0.7,
  expiresAt: new Date('2025-01-01'),
  context: {
    source: 'daily-reach',
    domain: 'work',
  },
});

search(query: MemorySearchQuery): Promise<Memory[]>

Search memories with semantic similarity.

const results = await memory.search({
  query: 'meeting preferences',
  limit: 10,
  type: MemoryType.PREFERENCE,
  minImportance: 0.5,
  activeOnly: true,
});

getLatest(type: string, limit?: number): Promise<Memory[]>

Get latest memories by type.

const latest = await memory.getLatest(MemoryType.PREFERENCE, 5);

getBySource(source: string, limit?: number): Promise<Memory[]>

Get memories from a specific source app.

const reachMemories = await memory.getBySource('daily-reach', 50);

delete(memoryId: string): Promise<void>

Delete a specific memory.

await memory.delete('mem-abc123');

deleteAll(): Promise<void>

Delete all memories for the current user.

await memory.deleteAll();

graphQuery(options: GraphQueryOptions): Promise<GraphResult>

Execute a Cypher query on memgraph.

const result = await memory.graphQuery({
  query: `
    MATCH (u:User {id: $userId})-[:HAS_PREFERENCE]->(p:Preference)
    RETURN p
  `,
  parameters: { userId: 'user-123' },
});

findRelated(entityType, entityId, relationshipType, direction?, depth?): Promise<GraphResult>

Find related entities in the graph.

const related = await memory.findRelated(
  'User',
  'user-123',
  'HAS_PREFERENCE',
  'OUT',
  2
);

healthCheck(): Promise<HealthStatus>

Check health of all services.

const health = await memory.healthCheck();
// { mem0: true, memgraph: true, supabase: true }

close(): Promise<void>

Close all connections.

await memory.close();

Mem0Client

Direct mem0 API client (usually accessed via MemoryClient).

import { Mem0Client } from '@daily/memory';

const mem0 = new Mem0Client({
  workspaceId: 'workspace-abc',
  userId: 'user-123',
  mem0Url: 'http://localhost:8000',
  mem0ApiKey: process.env.MEM0_API_KEY,
});

MemgraphClient

Direct memgraph client (usually accessed via MemoryClient).

import { MemgraphClient } from '@daily/memory';

const memgraph = new MemgraphClient({
  mode: 'development',
});

// Execute Cypher query
const result = await memgraph.query({
  query: 'MATCH (n) RETURN n LIMIT 10',
});

// Create or update node
const node = await memgraph.upsertNode(
  'User',
  'user-123',
  { name: 'Alice', role: 'admin' }
);

// Create or update relationship
const rel = await memgraph.upsertRelationship(
  'User',
  'user-123',
  'HAS_PREFERENCE',
  'Preference',
  'pref-dark-mode',
  { strength: 0.9 }
);

Types

MemoryType

enum MemoryType {
  PREFERENCE = 'preference',
  OBSERVATION = 'observation',
  PATTERN = 'pattern',
  CONTEXT = 'context',
  TEMPORARY = 'temporary',
}

EntityType

enum EntityType {
  KEYWORD = 'keyword',
  SITE = 'site',
  WORKSPACE = 'workspace',
  AUTOMATION = 'automation',
  CONTENT = 'content',
  COMPETITOR = 'competitor',
  USER = 'user',
}

MemoryInput

interface MemoryInput {
  content: string;
  type: MemoryType;
  entityType: EntityType;
  entityId?: string;
  importance?: number;  // 0.0 - 1.0
  expiresAt?: Date;
  context?: MemoryContext;
}

Memory

interface Memory {
  id: string;
  content: string;
  type: MemoryType;
  entityType: EntityType;
  entityId?: string;
  importance: number;
  createdAt: Date;
  expiresAt?: Date;
  context: MemoryContext;
  score?: number;  // Similarity score from search
}

MemorySearchQuery

interface MemorySearchQuery {
  query: string;
  limit?: number;
  type?: MemoryType;
  source?: string;
  entityType?: EntityType;
  minImportance?: number;
  activeOnly?: boolean;
}

Usage Examples

Preference Tracking

// Track user preferences
await memory.add({
  content: 'User prefers 30-minute meetings with agenda',
  type: MemoryType.PREFERENCE,
  entityType: EntityType.USER,
  importance: 0.9,
});

// Retrieve preferences
const prefs = await memory.search({
  query: 'meeting length preferences',
  type: MemoryType.PREFERENCE,
  limit: 5,
});

Observation Logging

// Log user behavior observations
await memory.add({
  content: 'User typically schedules meetings in the morning',
  type: MemoryType.OBSERVATION,
  entityType: EntityType.USER,
  importance: 0.6,
  context: {
    source: 'daily-reach',
    frequency: 'high',
  },
});

Pattern Recognition

// Store detected patterns
await memory.add({
  content: 'User engages more with video content than text',
  type: MemoryType.PATTERN,
  entityType: EntityType.USER,
  importance: 0.8,
});

Graph Relationships

// Build knowledge graph
await memory.graphQuery({
  query: `
    MERGE (u:User {id: $userId})
    MERGE (s:Site {id: $siteId})
    MERGE (u)-[:VISITS {frequency: 'daily'}]->(s)
  `,
  parameters: {
    userId: 'user-123',
    siteId: 'site-abc',
  },
});

// Find related entities
const related = await memory.findRelated('User', 'user-123', 'VISITS');

Multi-app Memory Sharing

// Add memory from one app
await memory.add({
  content: 'User focuses on SaaS companies',
  type: MemoryType.PREFERENCE,
  entityType: EntityType.USER,
  context: { source: 'daily-reach' },
});

// Access from another app
const reachMemories = await memory.getBySource('daily-reach');
const allPrefs = await memory.search({
  query: 'target customer preferences',
});

Architecture

┌─────────────┐
│ Application │
└──────┬──────┘
       │
       ▼
┌─────────────────┐
│  MemoryClient   │
└────┬──┬───┬────┘
     │  │   │
     │  │   └──────► Supabase (metadata)
     │  │
     │  └──────────► memgraph (graph)
     │
     └─────────────► mem0 (AI memory)

Error Handling

All methods throw errors on failure. Check logs for details:

import { logger } from '@daily/memory';

logger.setLevel('debug');  // Enable verbose logging

try {
  await memory.add({ /* ... */ });
} catch (error) {
  console.error('Memory add failed:', error.message);
}

License

UNLICENSED