@olivaresai/alma-sdk

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

TypeScript client for the Alma REST API. The SDK focuses on the persistent-memory core — memories, chat, and context assembly — with typed convenience wrappers for common secondary surfaces (images, voice, cowork, video, export). For any Alma API endpoint not covered by a typed resource, a raw HTTP escape hatch is provided so you never have to drop to fetch().

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);

Typed resources

The AlmaClient exposes typed wrappers around 14 sections of the Alma API.

Core — persistent memory

These are the reason to use Alma. They are first-class in the SDK, covered by integration tests, and kept stable across minor versions.

| Resource | Description | |----------|-------------| | alma.memories | Create, list, search, update, delete, and extract memories | | alma.chat | Conversations CRUD, send messages (streaming + non-streaming), retry, budget | | alma.context | Assemble context, preview prompts, set focus, continue sessions |

Convenience wrappers

These map 1:1 to their API routes and are kept in sync, but the surface is smaller. If a method you need is missing, prefer the raw HTTP client below rather than waiting for a release.

| Resource | Description | |----------|-------------| | alma.episodes | Conversation episode summaries | | alma.procedures | Learned procedures | | alma.blocks | Soul memory blocks | | alma.soul | Soul version history, snapshots, and restore | | alma.environments | Separate memory spaces | | alma.images | AI image generation (Flux, Leonardo) | | alma.voice | Speech-to-text and text-to-speech | | alma.export | Export conversations, memories, soul, full data dumps | | alma.admin | Dashboard stats | | alma.cowork | Agent workspaces (code edit, review, test, explain) | | alma.video | Runway video generation, projects, stitching |

Uncovered endpoints — use alma.http

Several API routes are intentionally not wrapped as typed resources — they're either niche, rarely used, or still being shaped. Rather than wait for a future release, call them with the built-in HTTP client:

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

// GET /flashcards/due  →  array of Flashcard rows
const due = await alma.http.get<{ flashcards: Array<{ id: string; question: string }> }>(
  '/flashcards/due',
);

// POST /ideas  →  create a quick note
const idea = await alma.http.post<{ idea: { id: string } }>('/ideas', {
  title: 'Refactor chat-service',
  content: 'P0-2 done, audit P0-1 next',
});

// DELETE /templates/xyz
await alma.http.delete<{ deleted: true }>('/templates/xyz');

alma.http methods:

• get<T>(path) — resolves to parsed JSON body of type T
• post<T>(path, body?)
• put<T>(path, body?)
• delete<T>(path)

Errors throw AlmaApiError just like the typed resources — status, code, and message are populated from the server response.

Routes currently only reachable via alma.http (15 groups):

flashcards, ideas, tasks, templates, writing, trends, teams, teams/billing, stats, share, files, music, audio, search, byok, context/documents, billing (subscription management is expected to happen inside the Alma web app, not via SDK).

If you find yourself writing the same HTTP wrapper in multiple projects, file an issue — the most-used ones get promoted to typed resources.

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

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