Quickstart

Overview

This guide will walk you through creating your first memory, storing it in Azen, and performing a semantic search to retrieve it. You’ll learn the core workflow that powers AI applications with long-term memory.

What you’ll build: A working memory system that stores user preferences and retrieves them using semantic search.

Prerequisites

Before you begin, make sure you have:

An Azen account (sign up at console.azen.sh)
curl or any HTTP client installed

Create an account and get your API key

Sign up at console.azen.sh
Complete the onboarding flow to create your organization
Navigate to the API Keys section in your dashboard
Click Create API key to generate a new key
Copy your API key immediately — you won’t be able to see it again

Store your API key securely. Anyone with this key can access the Azen API on behalf of your workspace.

Your API key will look like this:

az_1234567890abcdefghijklmnopqrstuvwxyz

Create your first memory

Let’s store a memory about a user’s preference. Azen automatically encrypts the content at rest and queues it for vector embedding.

curl -X POST https://api.azen.sh/api/v1/memory \
  -H "Content-Type: application/json" \
  -H "azen-api-key: YOUR_API_KEY" \
  -d '{
    "text": "I love hiking in the mountains on weekends"
  }'

Response:

{
  "status": "success",
  "memoryId": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "embedding": "processing"
}

The embedding field shows "processing" because embeddings are generated asynchronously. This typically takes 1-2 seconds.

Save the memoryId — you’ll need it to retrieve or delete this memory later.

Create more memories

Let’s add a few more memories to make semantic search more interesting:

# Memory about reading
curl -X POST https://api.azen.sh/api/v1/memory \
  -H "Content-Type: application/json" \
  -H "azen-api-key: YOUR_API_KEY" \
  -d '{"text": "I enjoy reading sci-fi novels before bed"}'

# Memory about cooking
curl -X POST https://api.azen.sh/api/v1/memory \
  -H "Content-Type: application/json" \
  -H "azen-api-key: YOUR_API_KEY" \
  -d '{"text": "I like cooking Italian pasta dishes for dinner"}'

# Memory about exercise
curl -X POST https://api.azen.sh/api/v1/memory \
  -H "Content-Type: application/json" \
  -H "azen-api-key: YOUR_API_KEY" \
  -d '{"text": "Rock climbing is my favorite weekend activity"}'

Wait 2-3 seconds after creating memories to allow embeddings to process before searching.

Search memories semantically

Now let’s search for memories using natural language. Azen uses vector similarity to find the most relevant memories, even if the exact words don’t match.

curl -X POST https://api.azen.sh/api/v1/memory/search \
  -H "Content-Type: application/json" \
  -H "azen-api-key: YOUR_API_KEY" \
  -d '{
    "query": "What outdoor activities does the user enjoy?",
    "topK": 3
  }'

Response:

{
  "status": "success",
  "memories": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "content": "I love hiking in the mountains on weekends",
      "metadata": null,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "embedded": true
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "content": "Rock climbing is my favorite weekend activity",
      "metadata": null,
      "createdAt": "2024-01-15T10:32:00.000Z",
      "embedded": true
    }
  ],
  "rawMatches": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000::0",
      "score": 1.00110459,
      "values": []
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001::0",
      "score": 0.89234567,
      "values": []
    }
  ]
}

The search returns the most relevant memories ranked by similarity score. Notice how it found memories about hiking and rock climbing, even though the query asked about “outdoor activities.”

The topK parameter controls how many results to return (1-50, default is 5). Higher scores indicate better matches.

List all memories

You can retrieve all memories with pagination support:

curl -X GET 'https://api.azen.sh/api/v1/memory?page=1&per=20' \
  -H "azen-api-key: YOUR_API_KEY"

Response:

{
  "status": "success",
  "memories": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440003",
      "content": "Rock climbing is my favorite weekend activity",
      "metadata": null,
      "createdAt": "2024-01-15T10:32:00.000Z",
      "embedded": true
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "content": "I like cooking Italian pasta dishes for dinner",
      "metadata": null,
      "createdAt": "2024-01-15T10:31:00.000Z",
      "embedded": true
    }
  ],
  "page": 1,
  "per": 20,
  "total_pages": 1,
  "total_count": 4
}

Memories are ordered by creation date (newest first), with support for pagination up to 100 items per page.

Retrieve a specific memory

If you have a memory ID, you can fetch it directly:

curl -X GET https://api.azen.sh/api/v1/memory/550e8400-e29b-41d4-a716-446655440000 \
  -H "azen-api-key: YOUR_API_KEY"

Delete a memory

To remove a memory and its embeddings:

curl -X DELETE https://api.azen.sh/api/v1/memory/550e8400-e29b-41d4-a716-446655440000 \
  -H "azen-api-key: YOUR_API_KEY"

Response:

{
  "status": "success",
  "deleted": true,
  "memoryId": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Memory deleted successfully"
}

Deleting a memory is permanent and cannot be undone. Both the encrypted content and vector embeddings are removed.

Complete example

Here’s a complete working example that ties everything together:

// Complete Azen Memory workflow
const AZEN_API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.azen.sh/api/v1';

async function azenExample() {
  // 1. Create a memory
  const createResponse = await fetch(`${BASE_URL}/memory`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'azen-api-key': AZEN_API_KEY
    },
    body: JSON.stringify({
      text: 'I prefer dark mode in all my applications'
    })
  });
  const created = await createResponse.json();
  console.log('Created memory:', created.memoryId);

  // 2. Wait for embedding to process
  await new Promise(resolve => setTimeout(resolve, 2000));

  // 3. Search for related memories
  const searchResponse = await fetch(`${BASE_URL}/memory/search`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'azen-api-key': AZEN_API_KEY
    },
    body: JSON.stringify({
      query: 'user interface preferences',
      topK: 5
    })
  });
  const results = await searchResponse.json();
  console.log('Search results:', results.memories);

  // 4. List all memories
  const listResponse = await fetch(`${BASE_URL}/memory?page=1&per=10`, {
    headers: { 'azen-api-key': AZEN_API_KEY }
  });
  const list = await listResponse.json();
  console.log(`Total memories: ${list.total_count}`);
}

azenExample();

Next steps

Now that you’ve created your first memories and performed semantic search, explore these topics:

API Reference

Explore all available endpoints and parameters

Understanding Search

Learn how semantic search works under the hood

Security & Encryption

Understand how Azen encrypts your data at rest

Memory System

Learn how Azen’s memory architecture works

Common patterns

Building a conversational AI

Use Azen to give your AI assistant long-term memory:

// Store conversation context
await createMemory({
  text: "User mentioned they are allergic to peanuts",
});

// Later, retrieve relevant context
const context = await searchMemories({
  query: "What are the user's dietary restrictions?",
  topK: 3,
});

User preferences engine

Store and retrieve user preferences across sessions:

// Store preferences
await createMemory({ text: "User prefers email notifications over SMS" });
await createMemory({ text: "User's timezone is America/New_York" });

// Retrieve when needed
const prefs = await searchMemories({
  query: "notification settings",
  topK: 5,
});

Troubleshooting

Embeddings still processing after 5 seconds

Embedding generation typically takes 1-2 seconds. If the embedded field remains false after 5+ seconds:

Check your embedding job status in the dashboard
Verify your text content is valid UTF-8
Contact support if the issue persists

Search returns no results

If your search returns empty results:

Ensure memories have embedded: true before searching
Try broader search queries
Verify memories were created for the correct organization
Check that your memories contain relevant text

401 Unauthorized error

This error indicates authentication issues:

Verify your API key is correct and active
Check that the azen-api-key header is set properly
Ensure your API key hasn’t been revoked
Generate a new API key if needed

Rate limit exceeded (429 error)

You’ve exceeded the rate limit for your API key:

Implement exponential backoff in your retry logic
Check your usage in the console dashboard
Consider upgrading your plan for higher limits
Contact support for custom rate limits

Need help? Join our Discord community or email us at [email protected]

Get Started

Core Concepts

Guides

Overview

Prerequisites

Complete example

Next steps

API Reference

Understanding Search

Security & Encryption

Memory System

Common patterns

Building a conversational AI

User preferences engine

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Overview

​Prerequisites

​Complete example

​Next steps

API Reference

Understanding Search

Security & Encryption

Memory System

​Common patterns

​Building a conversational AI

​User preferences engine

​Troubleshooting

Build docs developers (and LLMs) love

Overview

Prerequisites

Complete example

Next steps

Common patterns

Building a conversational AI

User preferences engine

Troubleshooting