@olivaresai/alma-sdk

JavaScript/TypeScript SDK for Alma — persistent memory for AI agents.

Full-featured TypeScript client for the Alma REST API. Manage memories, episodes, procedures, soul blocks, conversations, images, voice, and more — all with complete type safety.

Install

npm install @olivaresai/alma-sdk

Requires Node.js 18+ and ESM ("type": "module" in your package.json).

Quick Start

import { AlmaClient } from '@olivaresai/alma-sdk';

const alma = new AlmaClient({
  apiKey: 'alma_sk_...',
  // baseUrl: 'https://alma.olivares.ai/api/v1',  // default
  // environmentId: 'env_...',                      // optional
});

Assemble context for an LLM

const ctx = await alma.context.assemble({ user_message: 'Tell me about my project' });
console.log(ctx.system_prompt);
// Pass ctx.system_prompt as the system message to any LLM

Store a memory

const memory = await alma.memories.create({
  content: 'User prefers TypeScript over JavaScript',
  category: 'preference',
  importance: 8,
});

Search memories

const results = await alma.memories.search({
  q: 'programming preferences',
  mode: 'hybrid', // keyword, semantic, or hybrid
});
for (const memory of results.memories) {
  console.log(memory.content);
}

Chat with streaming

const conversation = await alma.chat.createConversation({ title: 'Hello' });

const abort = await alma.chat.send(conversation.id, 'Hi Alma!', {
  onChunk: (text) => process.stdout.write(text),
  onDone: (event) => {
    console.log(`\n[${event.model} | ${event.inputTokens}+${event.outputTokens} tokens]`);
  },
  onError: (error) => console.error('Stream error:', error),
});

// Call abort() to cancel the stream at any time

Chat without streaming

const response = await alma.chat.sendAndWait(conversation.id, 'What do you know about me?');
console.log(response.content);

Resources

The AlmaClient exposes 12 resource modules, each mapping to a section of the Alma API:

| Resource | Description | |----------|-------------| | alma.memories | Create, list, search, update, delete, and extract memories | | alma.episodes | Create, list, and search conversation episodes | | alma.procedures | Create, list, and manage learned procedures | | alma.blocks | Create, list, update, and delete soul memory blocks | | alma.soul | Soul version history, snapshots, and restore | | alma.context | Assemble context, preview prompts, set focus, continue sessions | | alma.chat | Conversations CRUD, send messages (streaming), retry, budget | | alma.environments | Create, list, and manage separate memory spaces | | alma.images | Generate images, browse history, list models | | alma.voice | Speech-to-text and text-to-speech | | alma.export | Export conversations, memories, soul, full data dumps | | alma.admin | Stats, insights, .alma import/export |

Memory Extraction

const extracted = await alma.memories.extract({
  conversation: 'User said they prefer dark mode and use React 19...',
  auto_save: true,
});

console.log(extracted.memories); // [{ content: '...', category: 'preference', importance: 7 }, ...]
console.log(extracted.episode);  // { summary: '...', topics: ['UI', 'React'] }

Soul Blocks

// List all soul blocks
const blocks = await alma.blocks.list();

// Update a block
await alma.blocks.update('rules', {
  value: 'Always respond in Spanish. Be concise.',
});

Image Generation

const image = await alma.images.generate({
  prompt: 'A peaceful mountain landscape at sunset',
  style: 'natural',
  size: 'landscape',
});
console.log(image.url);

Environments

Target a specific environment by passing environmentId at client initialization:

const alma = new AlmaClient({
  apiKey: 'alma_sk_...',
  environmentId: 'env_abc123',
});

Or manage environments programmatically:

const envs = await alma.environments.list();
const newEnv = await alma.environments.create({ name: 'Work Project' });

Error Handling

import { AlmaClient, AlmaApiError } from '@olivaresai/alma-sdk';

try {
  await alma.memories.create({ content: '' });
} catch (error) {
  if (error instanceof AlmaApiError) {
    console.error(`API error ${error.status}: [${error.code}] ${error.message}`);
  }
}

TypeScript

All types are re-exported from @olivaresai/alma-types:

import type {
  Memory,
  MemoryCategory,
  Episode,
  Procedure,
  Conversation,
  Message,
  MemoryBlock,
  Environment,
  AssembleResult,
  BudgetStatus,
  ChatStreamEvent,
  ChatStreamCallbacks,
} from '@olivaresai/alma-sdk';

Authentication

// API Key (recommended for scripts and backend integrations)
const alma = new AlmaClient({ apiKey: 'alma_sk_...' });

// JWT Bearer Token (for web applications)
const alma = new AlmaClient({ token: 'eyJ...' });

API keys can be created in the Alma settings. Requires an Advanced plan or above.

Links

• Alma App
• API Documentation
• MCP Server
• VSCode Extension
• GitHub

Built by olivares.ai — Give your AI a soul.