Core Concepts#

Understanding the building blocks of persistent AI memory 🧱

Before we dive into code, let's understand how Memof.ai thinks about memory. Don't worry—this isn't a computer science lecture. We'll keep it practical and, dare we say, entertaining.

The Big Picture#

Memof.ai has three main concepts that work together like a well-oiled machine:

Think of it like organizing your life:

• Workspace = Your company or project
• Bot = Individual employee or agent
• Memory = Everything they remember

Workspaces 🗂️#

Your organizational paradise

A Workspace is a container for your entire project. It's like a folder on your computer, but for AI memories.

Why Workspaces?#

Ever tried mixing personal and work emails in one inbox? Chaos, right? Workspaces prevent that chaos.

// Good: Organized
Workspace: "Customer Support"
  ├─ Bot: Support Agent
  └─ Bot: Sales Agent

Workspace: "Personal Assistant"
  └─ Bot: My AI Helper

// Bad: Chaos
Workspace: "Everything"
  ├─ Bot: Support
  ├─ Bot: Sales  
  ├─ Bot: Personal
  └─ Bot: ...wait, which is which?

Workspace Examples#

E-commerce Company:

SaaS Startup:

Personal Projects:

Key Properties#

{
  id: "ws_abc123",           // Auto-generated unique ID
  name: "Customer Support",  // Your friendly name
  description: "...",        // Optional context
  created_at: "2025-01-01",  // When you created it
  updated_at: "2025-01-15"   // Last modified
}

Pro Tips 💡#

1. One workspace per project/app - Keep things separate
2. Descriptive names - "Customer Support" > "Workspace 1"
3. Start simple - You can always create more later

Bots 🤖#

Your AI agents with permanent memory

A Bot is an individual AI agent within a workspace. Each bot has its own memories and can't access other bots' memories (privacy, yay!).

Why Separate Bots?#

Different bots serve different purposes. You wouldn't want your customer support bot remembering things meant for your sales bot, right?

# Each bot has its own memory space
support_bot.memories  # Customer issues, preferences
sales_bot.memories    # Lead information, deals
personal_bot.memories # Your private stuff

Bot Boundaries#

Use Case Examples#

Customer Support System:

// General support
const supportBot = {
  name: "Support Agent",
  purpose: "Handle customer inquiries"
};

// Specialized support
const technicalBot = {
  name: "Technical Support",
  purpose: "Handle complex technical issues"
};

// VIP support
const vipBot = {
  name: "VIP Support",
  purpose: "Handle premium customer requests"
};

Personal AI Assistant:

personal_bot = {
    'name': 'My Assistant',
    'description': 'Helps with daily tasks and remembers my preferences'
}

Key Properties#

{
  id: "bot_xyz789",              // Auto-generated unique ID
  name: "Support Agent",         // What you call it
  workspace_id: "ws_abc123",     // Which workspace it belongs to
  description: "Handles...",     // Optional details
  created_at: "2025-01-01",      // Birthday!
  updated_at: "2025-01-15"       // Last modified
}

Pro Tips 💡#

1. One bot per role - Support, sales, personal, etc.
2. Clear naming - "Customer Support Bot" > "Bot1"
3. Purpose-driven - Each bot should have a clear job
4. Don't over-separate - Start with one, split when needed

Memories 🧠#

The actual data—where the magic happens

A Memory is a piece of information stored by a bot. This is where you store everything you want your AI to remember.

What Can Be a Memory?#

Literally anything! Here are some examples:

# User preferences
"User prefers dark mode and compact layout"

# Conversation context  
"Working on authentication bug in the login module"

# Personal information
"Customer name is John, email: john@example.com"

# Learned behavior
"User typically asks for TypeScript examples"

# Project state
"Project deadline: Friday, 3 PM EST"

# Custom data
"User's favorite color: Blue, lucky number: 7"

Memory Structure#

{
  id: "mem_123456",                    // Auto-generated ID
  bot_id: "bot_xyz789",                // Which bot owns this
  content: "User prefers Python...",   // The actual memory
  metadata: { /* optional */ },        // Extra structured data
  created_at: "2025-01-15T10:30:00Z", // When it was stored
  updated_at: "2025-01-15T10:30:00Z"  // Last modified
}

Semantic Search 🔍#

This is the cool part

Memof.ai doesn't just store text—it understands meaning. This is called semantic search.

# You store this:
memory = "User is a Python developer who loves clean code and FastAPI"

# You can find it with any of these queries:
"programming language preference"  ✅ Found!
"favorite framework"               ✅ Found!
"code quality standards"           ✅ Found!
"development background"           ✅ Found!
"what does user like"             ✅ Found!

Why this matters: You don't need to remember exact phrases. Search by concept, not keywords!

Memory Best Practices#

✅ Good Memories#

# Specific and actionable
"User prefers email notifications at 9 AM EST"

# Contains context
"Sarah from Acme Corp, technical lead, interested in API integration"

# Natural language (easier to search)
"Customer had trouble with authentication, resolved by resetting password"

❌ Bad Memories#

# Too vague
"User likes stuff"

# No context
"yes"

# Overly cryptic
"pref:email;time:9"  # Just use natural language!

Memory Operations#

Create (Store):

client.memories.create({
    'bot_id': 'bot_123',
    'content': 'User loves dark mode'
})

Search (Find):

results = client.memories.search({
    'bot_id': 'bot_123',
    'query': 'UI preferences',
    'limit': 5  # Top 5 most relevant
})

List (View All):

all_memories = client.memories.list({
    'bot_id': 'bot_123'
})

Update:

client.memories.update({
    'id': 'mem_123',
    'content': 'User loves dark mode and compact layout'
})

Delete:

client.memories.delete('mem_123')

Pro Tips 💡#

1. Store meaningful content - Quality > quantity
2. Use natural language - Write like you talk
3. Include context - "Who, what, when, why"
4. Don't over-store - You don't need to remember everything
5. Search broadly - Semantic search is smart, trust it

How They Work Together#

The complete flow 🔄

Let's see how all three concepts work together in a real scenario:

Example: Customer Support System#

// 1. Create a workspace for your support system
const workspace = await client.workspaces.create({
  name: "Customer Support System"
});

// 2. Create bots for different support tiers
const generalBot = await client.bots.create({
  name: "General Support",
  workspaceId: workspace.id
});

const technicalBot = await client.bots.create({
  name: "Technical Support", 
  workspaceId: workspace.id
});

// 3. Store memories for each bot
await client.memories.create({
  botId: generalBot.id,
  content: "Customer John Smith prefers email over phone, timezone: PST"
});

await client.memories.create({
  botId: technicalBot.id,
  content: "John Smith reported API timeout issues with /users endpoint"
});

// 4. Later, retrieve context
const preferences = await client.memories.search({
  botId: generalBot.id,
  query: "John Smith contact preferences"
});

const issues = await client.memories.search({
  botId: technicalBot.id,
  query: "John Smith technical problems"
});

Data Isolation#

Each bot's memories are completely separate. Perfect for privacy and organization!

Common Patterns#

How people actually use this 🎨

Pattern 1: User Context Bot#

# One bot per user, stores everything about them
user_bot = client.bots.create({
    'name': f'User_{user_id}',
    'workspace_id': workspace_id
})

# Store preferences, history, context
client.memories.create({
    'bot_id': user_bot['id'],
    'content': 'Prefers dark mode, uses Python, timezone PST'
})

Pattern 2: Shared Knowledge Bot#

# One bot for shared knowledge across all users
knowledge_bot = client.bots.create({
    'name': 'Product Knowledge',
    'workspace_id': workspace_id
})

# Store company/product information
client.memories.create({
    'bot_id': knowledge_bot['id'],
    'content': 'Our API rate limit is 1000 requests per hour'
})

Pattern 3: Session Context Bot#

# One bot per conversation/session
session_bot = client.bots.create({
    'name': f'Session_{session_id}',
    'workspace_id': workspace_id
})

# Store conversation context
client.memories.create({
    'bot_id': session_bot['id'],
    'content': 'User is debugging authentication issues in their React app'
})

Pattern 4: Hybrid Approach#

# Combine patterns for maximum power
workspace = client.workspaces.create({'name': 'My App'})

# User-specific bot
user_bot = client.bots.create({
    'name': f'User_{user_id}',
    'workspace_id': workspace['id']
})

# Shared knowledge bot  
knowledge_bot = client.bots.create({
    'name': 'Shared Knowledge',
    'workspace_id': workspace['id']
})

# Search across both when needed
user_context = client.memories.search({'bot_id': user_bot['id'], 'query': '...'})
shared_knowledge = client.memories.search({'bot_id': knowledge_bot['id'], 'query': '...'})

Limits & Quotas#

The fine print (but not too fine) 📏

Current platform limits:

• Workspaces: Unlimited (within reason)
• Bots per Workspace: Unlimited (within reason)
• Memories per Bot: Unlimited (seriously!)
• Memory Size: Up to 10KB per memory
• Search Results: Up to 100 per query
• API Rate Limit: 1,000 requests/minute

"Within reason" = We're cool with high usage, just don't try to store the entire internet 😉

Security & Privacy#

Because this matters 🔒

• ✅ Data isolation - Bots can't access each other's memories
• ✅ Workspace separation - Complete isolation between workspaces
• ✅ Token-based auth - Secure API access
• ✅ Encrypted storage - Your data is safe
• ✅ No data sharing - Your memories are yours

What's Next?#

Now that you understand the concepts, let's build something!

• 🚀 Quick Start Guide - Get your first app running
• 🐍 Python SDK - Python developers start here
• 🟨 JavaScript SDK - JavaScript/TypeScript folks
• 🔗 MCP Server - LLM integration
• 🌐 HTTP API - Direct API access

TL;DR#

The super short version ⚡

1. Workspace = Your project container
2. Bot = Individual AI agent
3. Memory = What the bot remembers
4. Semantic search = Find by meaning, not keywords
5. Data isolation = Bots can't see each other's stuff

Got it? Great! Let's build something →

Questions? We love them! → support@memof.ai