Quickstart

Get up and running with Rekall in under 5 minutes. By the end of this guide, you will have installed the SDK, created your first memory, searched for it, and retrieved it by ID.

Estimated time: 5 minutes

This guide assumes you have a Rekall account and an API key. If you do not have one yet, sign up for free and generate a key from your dashboard.

Prerequisites

  • A Rekall account with an API key (prefixed with rk_)
  • Node.js 18+ (for TypeScript) or Python 3.9+ (for Python)
  • A terminal and your preferred code editor

Step 1: Install the SDK

Choose your preferred language and install the Rekall SDK. The agent SDK includes full memory management, semantic search, and type safety out of the box.

# Using npm
npm install @rekall/agent-sdk


# Using yarn
yarn add @rekall/agent-sdk


# Using pnpm
pnpm add @rekall/agent-sdk

Lightweight alternative

If you only need REST client functionality without the full agent SDK, you can use the lightweight @rekall/client package instead: npm install @rekall/client

Step 2: Authenticate

Initialize the SDK with your API key. We recommend storing it in an environment variable rather than hardcoding it.

import { RekallClient } from '@rekall/agent-sdk';


const rekall = new RekallClient({
  apiKey: process.env.REKALL_API_KEY, // rk_...
  // Optional: defaults to https://api.rekall.ai/v1
  // baseUrl: 'https://api.rekall.ai/v1',
});

Keep your API key secure

Never commit API keys to version control. Use environment variables or a secrets manager. Keys prefixed with rk_test_ are for sandbox environments and have limited access.

Step 3: Create a Memory

Let's create your first episodic memory. Episodic memories capture events with rich context -- what happened, when, and why it matters.

const memory = await rekall.memories.create({
  type: 'episodic',
  content: 'User completed onboarding and selected the Pro plan. They mentioned they are building a customer support agent and need long-term memory for user preferences.',
  metadata: {
    source: 'onboarding-flow',
    userId: 'user_abc123',
    tags: ['onboarding', 'pro-plan', 'support-agent'],
  },
  context: 'personal', // personal | hive | agent
});


console.log('Created memory:', memory.id);
// => Created memory: mem_7f3a2b1c...

Example response:

Response
{
  "id": "mem_7f3a2b1c4d5e6f7a8b9c0d1e",
  "type": "episodic",
  "content": "User completed onboarding and selected the Pro plan...",
  "context": "personal",
  "metadata": {
    "source": "onboarding-flow",
    "userId": "user_abc123",
    "tags": ["onboarding", "pro-plan", "support-agent"]
  },
  "strength": 1.0,
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}

Step 4: Search for Memories

Rekall uses semantic search powered by vector embeddings. Search with natural language and get back the most relevant memories, ranked by similarity.

const results = await rekall.memories.search({
  query: 'what plan did the user choose during onboarding?',
  type: 'episodic',     // optional: filter by memory type
  limit: 5,             // optional: max results (default 10)
  threshold: 0.7,       // optional: minimum similarity score
});


for (const result of results) {
  console.log(`[${result.score.toFixed(2)}] ${result.memory.content}`);
}
// => [0.94] User completed onboarding and selected the Pro plan...

Example response:

Search Response
{
  "results": [
    {
      "score": 0.94,
      "memory": {
        "id": "mem_7f3a2b1c4d5e6f7a8b9c0d1e",
        "type": "episodic",
        "content": "User completed onboarding and selected the Pro plan...",
        "context": "personal",
        "strength": 1.0,
        "createdAt": "2025-01-15T10:30:00.000Z"
      }
    }
  ],
  "total": 1
}

Step 5: Retrieve a Memory

If you know the memory ID, you can retrieve it directly. Retrieving a memory also strengthens it -- just like biological memory, the more you access a memory, the stronger it becomes and the slower it decays.

const memory = await rekall.memories.get('mem_7f3a2b1c4d5e6f7a8b9c0d1e');


console.log(memory.content);
// => User completed onboarding and selected the Pro plan...


console.log(memory.strength);
// => 1.0 (freshly created or recently accessed)

Memory strength and decay

Every memory has a strength value between 0 and 1. New memories start at 1.0 and naturally decay over time. Each time a memory is retrieved or referenced, its strength is boosted. This models the spacing effect from cognitive science -- frequently accessed memories persist longer.

What's Next

You have created, searched, and retrieved your first memory. Here is where to go next:

Your First Memory (Full Tutorial)

Walk through the complete CRUD lifecycle with detailed examples and responses.

Core Concepts

Understand the 7 memory types, contexts, and the decay system.

API Reference

Full REST API documentation with examples for every endpoint.

Rekall
rekall