Alchemyst AI - AI-Native Context Management Platform

What You’re Building

An AI that remembers user preferences and past conversations automatically. Without Memory:

// Day 1
await llm.generate("I'm vegan and allergic to peanuts");
// Day 2
await llm.generate("Give me a recipe");
// AI: "What dietary restrictions do you have?" ❌

With Memory:

// Day 1
await generateWithMemory({ prompt: "I'm vegan", userId: "alice" });
// Day 2
await generateWithMemory({ prompt: "Give me a recipe", userId: "alice" });
// AI: "Here's a vegan recipe: ..."  ✅ Remembered automatically

Prerequisites

Alchemyst account (sign up)
Your ALCHEMYST_AI_API_KEY
Node.js 18+ or Python 3.9+

Time to complete: 15 minutes

Choose Your Approach

TypeScript (Recommended)
Python

Best for: Next.js, React, Node.js appsUses Vercel AI SDK wrapper for automatic memory management.

npm install ai @alchemystai/aisdk

Best for: FastAPI, Django, Flask appsUses direct SDK with manual memory management (more control).

pip install alchemystai openai

Quick Start: TypeScript

Step 1: Set Up Memory

import { generateText } from 'ai';
import { withAlchemyst } from '@alchemystai/aisdk';

// Wrap AI SDK with automatic memory
const generateTextWithMemory = withAlchemyst(generateText, {
  apiKey: process.env.ALCHEMYST_AI_API_KEY,
});

What this does:

Retrieves past conversations for this user
Includes them in the prompt automatically
Stores the new conversation

Step 2: Use Memory

// First conversation: User shares preference
const response1 = await generateTextWithMemory({
  model: "openai:gpt-4",
  prompt: "I'm vegan and allergic to peanuts",
  userId: "alice",
  sessionId: "profile_setup"
});

console.log(response1.text);
// Output: "Got it! I'll remember you're vegan and have a peanut allergy."

// Later: Different session, AI remembers
const response2 = await generateTextWithMemory({
  model: "openai:gpt-4",
  prompt: "Give me a dinner recipe",
  userId: "alice",
  sessionId: "cooking_monday"
});

console.log(response2.text);
// Output: "Here's a vegan stir-fry without peanuts: ..."
// ✅ Remembered from different conversation!

Memory works across:

Different sessions (profile_setup → cooking_monday)
Different topics (preferences → recipes)
Days or weeks apart

Complete TypeScript Example

import { generateText } from 'ai';
import { withAlchemyst } from '@alchemystai/aisdk';

const generateTextWithMemory = withAlchemyst(generateText, {
  apiKey: process.env.ALCHEMYST_AI_API_KEY,
});

async function main() {
  // Day 1: Learn preference
  const response1 = await generateTextWithMemory({
    model: "openai:gpt-4",
    prompt: "I love science fiction movies",
    userId: "bob",
    sessionId: "preferences"
  });
  console.log("AI:", response1.text);
  // Output: "Great! I'll remember you enjoy sci-fi films."

  // Day 2: Use preference
  const response2 = await generateTextWithMemory({
    model: "openai:gpt-4",
    prompt: "Recommend a movie",
    userId: "bob",
    sessionId: "movie_night"
  });
  console.log("AI:", response2.text);
  // Output: "How about Interstellar? You mentioned you love sci-fi."
}

main();

Verify it worked:

Visit platform.getalchemystai.com/context
You should see stored conversations for user “bob”
Click to view memory contents

Quick Start: Python

Step 1: Simple Example (Recommended)

Start with this simplified version to understand the basics:

import os
from alchemyst_ai import AlchemystAI

alchemyst = AlchemystAI(api_key=os.environ.get("ALCHEMYST_AI_API_KEY"))

# Store a memory
alchemyst.v1.context.add({
    "content": "User said: I'm vegan and allergic to peanuts",
    "context_type": "conversation",
    "metadata": {
        "group_name": ["preferences", "alice"]
    }
})

print("✅ Memory stored!")

# Later: Retrieve memories
result = alchemyst.v1.context.search(
    limit=10,
    body_metadata={"group_name": ["preferences", "alice"]}
)

if result and hasattr(result, 'memories'):
    for memory in result.memories:
        print(f"Found: {memory.content}")
        # Output: Found: User said: I'm vegan and allergic to peanuts

Expected Output:

✅ Memory stored!
Found: User said: I'm vegan and allergic to peanuts

Step 2: Full Integration with OpenAI

Now integrate with OpenAI for complete chat functionality:

import os
from alchemyst_ai import AlchemystAI
import openai

alchemyst = AlchemystAI(api_key=os.environ.get("ALCHEMYST_AI_API_KEY"))
openai_client = openai.OpenAI()

def chat_with_memory(prompt: str, user_id: str, session_id: str):
    """Chat function that remembers past conversations"""

    # 1. Get past conversations
    memory = alchemyst.v1.context.search(
        limit=10,
        body_metadata={"group_name": [session_id, user_id]}
    )

    # 2. Build message history
    messages = [{"role": "system", "content": "You are a helpful assistant."}]

    # Add past memories to context
    if memory and hasattr(memory, 'memories'):
        for mem in memory.memories:
            if hasattr(mem, 'content'):
                messages.append({"role": "assistant", "content": mem.content})

    # Add current prompt
    messages.append({"role": "user", "content": prompt})

    # 3. Generate response with full context
    response = openai_client.chat.completions.create(
        model="gpt-4",
        messages=messages
    )

    assistant_message = response.choices[0].message.content

    # 4. Store this conversation for next time
    alchemyst.v1.context.add({
        "content": f"User: {prompt}\nAssistant: {assistant_message}",
        "context_type": "conversation",
        "metadata": {
            "group_name": [session_id, user_id]
        }
    })

    return assistant_message

# Test it
response = chat_with_memory(
    prompt="I'm vegan",
    user_id="alice",
    session_id="profile"
)
print(response)
# Output: "Got it! I'll remember you're vegan."

response2 = chat_with_memory(
    prompt="Give me a recipe",
    user_id="alice",
    session_id="cooking"
)
print(response2)
# Output: "Here's a vegan pasta recipe: ..."

Expected Output:

Got it! I'll remember you're vegan.
Here's a vegan pasta recipe: ...

Understanding userId and sessionId

These two parameters control memory scope:

await generateTextWithMemory({
  prompt: "...",
  userId: "alice",      // WHO is talking
  sessionId: "cooking"  // WHAT conversation thread
});

Real-World Examples

Use Case	userId	sessionId	Why
Customer support	`customer_123`	`ticket_456`	Track support history per customer
Personal assistant	`user_alice`	`daily_planning_2024_02_01`	Separate daily planning sessions
Team collaboration	`user_bob`	`project_alpha_sprint_3`	Isolate project discussions by sprint
Multi-user chat	`user_charlie`	`team_standup_2024_w05`	Group conversations by topic and time

Pro Tip: Use descriptive sessionIds like "recipe_planning_2024_02" instead of "session_1" for easier debugging and analytics.

Rule: Same userId + same sessionId = same conversation thread

Advanced Features

Stream Responses with Memory

For real-time chat experiences:

TypeScript
Python

import { streamText } from 'ai';
import { withAlchemyst } from '@alchemystai/aisdk';

const streamTextWithMemory = withAlchemyst(streamText, {
  apiKey: process.env.ALCHEMYST_AI_API_KEY,
});

async function streamChat() {
  const { textStream } = await streamTextWithMemory({
    model: "openai:gpt-4",
    prompt: "Tell me about quantum mechanics",
    userId: "user_123",
    sessionId: "physics_101"
  });

  // Process stream chunk by chunk
  for await (const chunk of textStream) {
    process.stdout.write(chunk);
  }
}

streamChat();

Expected Output:

Quantum mechanics is the branch of physics... [streams in real-time]

def chat_with_memory_streaming(prompt: str, user_id: str, session_id: str):
    """Stream responses while remembering context"""

    # Get past conversations
    memory = alchemyst.v1.context.search(
        limit=10,
        body_metadata={"group_name": [session_id, user_id]}
    )

    messages = [{"role": "system", "content": "You are a helpful assistant."}]

    if memory and hasattr(memory, 'memories'):
        for mem in memory.memories:
            if hasattr(mem, 'content'):
                messages.append({"role": "assistant", "content": mem.content})

    messages.append({"role": "user", "content": prompt})

    # Stream response
    stream = openai_client.chat.completions.create(
        model="gpt-4",
        messages=messages,
        stream=True
    )

    full_response = ""
    for chunk in stream:
        if chunk.choices[0].delta.content:
            content = chunk.choices[0].delta.content
            print(content, end="", flush=True)
            full_response += content

    # Store complete conversation
    alchemyst.v1.context.add({
        "content": f"User: {prompt}\nAssistant: {full_response}",
        "context_type": "conversation",
        "metadata": {
            "group_name": [session_id, user_id]
        }
    })

    return full_response

# Usage
response = chat_with_memory_streaming(
    prompt="Tell me about quantum mechanics",
    user_id="user_123",
    session_id="physics_101"
)

Expected Output:

Quantum mechanics is the branch of physics... [streams in real-time]

Manage Memory

Update or delete conversations as needed:

TypeScript
Python

import AlchemystAI from '@alchemystai/sdk';

const client = new AlchemystAI({
  apiKey: process.env.ALCHEMYST_AI_API_KEY,
});

// Update specific memory
await client.v1.context.memory.update({
  userId: "alice",
  sessionId: "profile_setup",
  messageId: "msg_001",
  content: "Updated: I'm vegan and gluten-free"
});

// Delete a specific conversation
await client.v1.context.memory.delete({
  userId: "alice",
  sessionId: "profile_setup"
});

// Delete ALL memories for a user (use with caution!)
await client.v1.context.memory.delete({
  userId: "alice"
});

console.log("✅ Memory updated/deleted");

# Update specific memory
alchemyst.v1.context.memory.update(
    user_id="alice",
    session_id="profile_setup",
    message_id="msg_001",
    content="Updated: I'm vegan and gluten-free"
)

# Delete a specific conversation
alchemyst.v1.context.memory.delete(
    user_id="alice",
    session_id="profile_setup"
)

# Delete ALL memories for a user (use with caution!)
alchemyst.v1.context.memory.delete(
    user_id="alice"
)

print("✅ Memory updated/deleted")

Multi-User Conversations

Handle group chats where multiple users participate in the same thread:

TypeScript
Python

// User 1 starts discussion
await generateTextWithMemory({
  model: "openai:gpt-4",
  prompt: "What are React hooks best practices?",
  userId: "alice",
  sessionId: "team_discussion_001"
});

// User 2 joins same discussion
await generateTextWithMemory({
  model: "openai:gpt-4",
  prompt: "Can you elaborate on useEffect?",
  userId: "bob",
  sessionId: "team_discussion_001"  // ← Same session = shared context
});

// User 1 continues - AI has full thread context
await generateTextWithMemory({
  model: "openai:gpt-4",
  prompt: "What about custom hooks?",
  userId: "alice",
  sessionId: "team_discussion_001"
});

// AI has full thread context regardless of who asks

# User 1 starts discussion
chat_with_memory(
    prompt="What are React hooks best practices?",
    user_id="alice",
    session_id="team_discussion_001"
)

# User 2 joins same discussion
chat_with_memory(
    prompt="Can you elaborate on useEffect?",
    user_id="bob",
    session_id="team_discussion_001"  # ← Same session = shared context
)

# User 1 continues - AI has full thread context
chat_with_memory(
    prompt="What about custom hooks?",
    user_id="alice",
    session_id="team_discussion_001"
)

# AI has full thread context regardless of who asks

Key insight: Using the same sessionId across different userId values creates a shared memory space for team conversations.

Configuration Options

Customize memory retrieval and storage behavior:

TypeScript
Python

const generateTextWithMemory = withAlchemyst(generateText, {
  apiKey: process.env.ALCHEMYST_AI_API_KEY,

  // Memory retrieval settings
  similarityThreshold: 0.8,           // How relevant (0-1)
  minimumSimilarityThreshold: 0.5,    // Absolute minimum cutoff
  scope: 'internal',                  // 'internal' | 'external'

  // Storage settings
  contextType: 'conversation',
  source: 'chat-app',

  // Organization (optional)
  metadata: {
    groupName: ['production', 'app-v2'],
    environment: 'production',
    version: '2.0'
  },
});

def chat_with_memory(
    prompt: str,
    user_id: str,
    session_id: str,
    similarity_threshold: float = 0.8,
    min_similarity_threshold: float = 0.5,
    scope: str = 'internal'
):
    memory = alchemyst.v1.context.search(
        limit=10,
        similarity_threshold=similarity_threshold,
        minimum_similarity_threshold=min_similarity_threshold,
        scope=scope,
        body_metadata={"group_name": [session_id, user_id]}
    )
    # ... rest of implementation

Configuration Reference

Parameter	Value	When to Use
similarityThreshold	`0.5`	Broad, exploratory searches
	`0.7`	Recommended default - balanced
	`0.9`	Precise matches only
minimumSimilarityThreshold	`0.5`	Never return results below this
scope	`'internal'`	Your app’s private data
	`'external'`	Public/shared knowledge

Recommendation: Start with similarityThreshold: 0.7. Lower to 0.5 if you get no results, raise to 0.9 if results are too broad.

Troubleshooting

Missing userId or sessionId error

Error Message:

{
  "error": "userId and sessionId are required",
  "code": "MISSING_PARAMETERS"
}

Cause: Both parameters are required for memory operations.Fix: Always provide both:

await generateTextWithMemory({
  model: "openai:gpt-4",
  prompt: "Hello",
  userId: "user_123",    // ✅ Required
  sessionId: "chat_456"  // ✅ Required
});

Memory not retrieving

Symptoms: AI doesn’t remember past conversations.Causes:

Threshold too high
Wrong userId/sessionId
Memory wasn’t stored correctly

Fixes:1. Lower threshold:

similarityThreshold: 0.6  // Instead of 0.9

2. Verify exact same IDs:

// IDs must match EXACTLY (case-sensitive)
userId: "user_123"      // ❌ Not "user_124" or "User_123"
sessionId: "chat_456"   // ❌ Not "chat_457" or "Chat_456"

3. Test retrieval directly:

const memories = await client.v1.context.search({
  limit: 10,
  body_metadata: {"group_name": ["chat_456", "user_123"]}
});
console.log("Found memories:", memories.memories?.length);
console.log("Memory content:", memories.memories);

Expected Output:

Found memories: 2
Memory content: [
  { content: "User: I'm vegan\nAssistant: Got it!" },
  { content: "User: Give me a recipe\nAssistant: Here's a vegan..." }
]

Too much irrelevant context

Symptoms: AI references unrelated past conversations or gets confused.Causes:

Threshold too low
Mixing unrelated conversations in same session

Fixes:1. Raise threshold:

similarityThreshold: 0.85  // More strict

2. Use separate sessions by topic:

// ✅ Good - separate by topic
sessionId: "physics_homework"
sessionId: "cooking_recipes"
sessionId: "movie_recommendations"

// ❌ Bad - everything mixed
sessionId: "general_chat"

3. Limit memory retrieval:

// Only retrieve last 5 memories instead of 10
limit: 5

Memory storage failures

Error Message:

{
  "error": "Failed to store memory",
  "code": "STORAGE_ERROR"
}

Common Causes:

Invalid API key
Rate limit exceeded
Content too large

Fixes:1. Verify API key:

console.log("API Key set:", !!process.env.ALCHEMYST_AI_API_KEY);
// Should output: API Key set: true

2. Check rate limits:

Free tier: 100 operations/day
Pro tier: Unlimited

3. Reduce content size:

// Keep memory entries under 10KB each
const content = longText.slice(0, 10000);  // Truncate if needed

Best Practices

1. Session Naming Convention

// ✅ Good - descriptive and structured
sessionId: "support_ticket_2024_02_001"
sessionId: "recipe_planning_vegan_week_5"
sessionId: "project_alpha_sprint_3_planning"

// ❌ Bad - hard to debug
sessionId: "session1"
sessionId: "chat"
sessionId: "abc123"

2. Memory Retention Limits

// ✅ Good - limit memory lookback
limit: 10  // Last 10 conversations

// ❌ Bad - retrieving everything
limit: 1000  // Too much context, slows down LLM

3. Privacy-Aware Memory

// Store memories with appropriate scope
const generateTextWithMemory = withAlchemyst(generateText, {
  apiKey: process.env.ALCHEMYST_AI_API_KEY,
  scope: 'internal',  // ✅ Private user data
  metadata: {
    dataClassification: 'PII',  // Track sensitive data
    retentionPolicy: '90days'
  }
});

4. Error Handling

// ✅ Good - handle failures gracefully
try {
  const response = await generateTextWithMemory({
    model: "openai:gpt-4",
    prompt: userInput,
    userId: user.id,
    sessionId: conversation.id
  });
  return response.text;
} catch (error) {
  console.error("Memory error:", error);
  // Fallback: Generate without memory
  return await generateText({
    model: "openai:gpt-4",
    prompt: userInput
  });
}

Verify Your Setup

After implementing memory, verify it’s working:

1. Check Platform UI

Visit platform.getalchemystai.com/context
Filter by your userId
You should see stored memories with timestamps
Click to view conversation content

2. Test with Code

// Store a test memory
await client.v1.context.add({
  documents: [{ content: "Test memory: The user likes pizza" }],
  contextType: "conversation",
  metadata: {
    groupName: ["test_session", "test_user"]
  }
});

// Retrieve it immediately
const result = await client.v1.context.search({
  limit: 10,
  body_metadata: {"group_name": ["test_session", "test_user"]}
});

console.log("Test passed:", result.memories?.length === 1);
// Expected Output: Test passed: true

What’s Next?

Add Context Search

Combine memory with document search for powerful RAG

Vercel AI SDK Guide

Deep dive into AI SDK integration

TypeScript SDK Reference

Complete API reference for TypeScript

Python SDK Reference

Complete API reference for Python

Learn Advanced Patterns

User Profiling

Build rich user profiles from memory

Memory Use Cases

Customer support, personal assistants, chatbots

Memory API Reference

Complete REST API documentation

Sample Projects

Community-built memory applications

Need Help?

Discord Community

Get real-time help from our community

Documentation

Browse guides and API references

Email Support

Contact our support team

GitHub Issues

Report bugs or request features

​What You’re Building

​Prerequisites

​Choose Your Approach

​Quick Start: TypeScript

​Step 1: Set Up Memory

​Step 2: Use Memory

​Complete TypeScript Example

​Quick Start: Python

​Step 1: Simple Example (Recommended)

​Step 2: Full Integration with OpenAI

​Understanding userId and sessionId

​Real-World Examples

​Advanced Features

​Stream Responses with Memory

​Manage Memory

​Multi-User Conversations

​Configuration Options

​Configuration Reference

​Troubleshooting

​Best Practices

​1. Session Naming Convention

​2. Memory Retention Limits

​3. Privacy-Aware Memory

​4. Error Handling

​Verify Your Setup

​1. Check Platform UI

​2. Test with Code

​What’s Next?

Add Context Search

Vercel AI SDK Guide

TypeScript SDK Reference

Python SDK Reference

​Learn Advanced Patterns

User Profiling

Memory Use Cases

Memory API Reference

Sample Projects

​Need Help?

Discord Community

Documentation

Email Support

GitHub Issues

What You’re Building

Prerequisites

Choose Your Approach

Quick Start: TypeScript

Step 1: Set Up Memory

Step 2: Use Memory

Complete TypeScript Example

Quick Start: Python

Step 1: Simple Example (Recommended)

Step 2: Full Integration with OpenAI

Understanding userId and sessionId

Real-World Examples

Advanced Features

Stream Responses with Memory

Manage Memory

Multi-User Conversations

Configuration Options

Configuration Reference

Troubleshooting

Best Practices

1. Session Naming Convention

2. Memory Retention Limits

3. Privacy-Aware Memory

4. Error Handling

Verify Your Setup

1. Check Platform UI

2. Test with Code

What’s Next?

Learn Advanced Patterns

Need Help?