@episodial/sdk

JavaScript/TypeScript SDK for the Episodial cognitive memory API. Zero dependencies, works in Node.js 18+ and modern browsers.

Install

npm install @episodial/sdk

Quick Start

import { Episodial } from '@episodial/sdk'

const ep = new Episodial({
  baseUrl: 'https://api.episodial.ai',
  apiKey: 'ep_live_...',
  projectId: 'my-app',
})

// Store a memory
await ep.remember({
  userId: 'user_123',
  userMessage: 'How do I reset my password?',
  assistantMessage: 'Go to Settings → Security → Reset password.',
})

// Recall relevant memories
const { memories } = await ep.recall('user_123', 'password help')

// Inject into your LLM prompt
const context = memories.map(m => m.content).join('\n')

Configuration

const ep = new Episodial({
  baseUrl: 'http://localhost:8000', // Memory Core URL
  apiKey: 'ep_live_...',           // API key (optional in dev)
  organizationId: 'org_...',       // For billing endpoints
  projectId: 'default',            // Default project for all calls
  timeout: 30000,                  // Request timeout in ms
})

Memory Operations

Ingest

Store an episodic event:

await ep.ingest({
  user_id: 'user_123',
  project_id: 'my-app',
  chat_id: 'conv_1',        // optional — scope to a conversation
  event_type: 'llm_interaction',
  payload: {
    user_message: 'What is Kubernetes?',
    assistant_message: 'Kubernetes is a container orchestration platform...',
  },
  initial_salience: 0.7,
})

Or use the convenience method:

await ep.remember({
  userId: 'user_123',
  chatId: 'conv_1',         // optional — scope to a conversation
  userMessage: 'What is Kubernetes?',
  assistantMessage: 'Kubernetes is a container orchestration platform...',
  salience: 0.7,
})

Batch Ingest

await ep.ingestBatch([event1, event2, event3])

Retrieve

const result = await ep.retrieve({
  user_id: 'user_123',
  project_id: 'my-app',
  chat_id: 'conv_1',        // optional — filter by conversation
  task_goal: 'Help user with deployment',
  token_budget: 2000,
})

for (const memory of result.memories) {
  console.log(memory.content, memory.salience, memory.memory_type)
}

Or use the shorthand:

const { memories } = await ep.recall('user_123', 'deployment help', {
  chatId: 'conv_1',
})

Conversation Scoping

Use chatId / chat_id to isolate memories per conversation. Omit it for cross-conversation global memories.

// Retrieve memories from this chat + global memories (default)
const result = await ep.retrieve({
  user_id: 'user_123',
  project_id: 'my-app',
  chat_id: 'conv_1',
  include_global: true,
  task_goal: 'deployment help',
})

// Only memories from this specific chat
const chatOnly = await ep.retrieve({
  user_id: 'user_123',
  project_id: 'my-app',
  chat_id: 'conv_1',
  chat_only: true,
  task_goal: 'deployment help',
})

// All memories for the user (no chat filter)
const all = await ep.retrieve({
  user_id: 'user_123',
  project_id: 'my-app',
  task_goal: 'deployment help',
})

Feedback

Reinforce or decay memories based on usefulness:

await ep.helpful('memory_id_123')   // positive feedback
await ep.unhelpful('memory_id_456') // negative feedback

// Fine-grained control
await ep.feedback({
  memory_id: 'memory_id_123',
  feedback_type: 'success',
  value: 0.8,
  context: 'User confirmed this solved their issue',
})

Forget

// Forget specific memories
await ep.forget({
  memory_ids: ['mem_1', 'mem_2'],
  reason: 'User requested data deletion',
})

// Forget all memories for a user
await ep.forget({
  user_id: 'user_123',
  project_id: 'my-app',
  reason: 'Account deletion',
})

Consolidation

Trigger memory consolidation (episodic → semantic):

await ep.consolidate('user_123', 'my-app')

Procedural Learning

// Mine patterns from past interactions
await ep.mineProcedures('user_123', 'my-app')

// Find matching procedures for current context
const { procedures } = await ep.matchProcedures(
  'user_123',
  'user wants to deploy to production',
)

Billing

// Check balance
const balance = await ep.getBalance()
console.log(`$${balance.balance_dollars} remaining`)

// Get pricing
const pricing = await ep.getPricing()

// Top up
await ep.topup('growth') // $50 + 20% bonus

Error Handling

import { Episodial, EpisodialError } from '@episodial/sdk'

try {
  await ep.recall('user_123', 'hello')
} catch (err) {
  if (err instanceof EpisodialError) {
    console.error(`API error ${err.status}: ${err.message}`)
    if (err.status === 402) console.log('Insufficient balance — top up!')
  }
}

OpenAI Proxy Integration

Episodial can also work as a drop-in proxy. Point your OpenAI client at the Episodial proxy endpoint:

import OpenAI from 'openai'

const openai = new OpenAI({
  baseURL: 'https://api.episodial.ai/v1',
  defaultHeaders: {
    'X-Episodial-Key': 'ep_live_...',
  },
})

// Memories are automatically injected and captured
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'What did we discuss yesterday?' }],
})

License

MIT