DocsQuick Start

Quick Start Guide

Get started with BaseGrid in under 5 minutes. This guide will walk you through installation, authentication, and your first API call.

Getting Started

1. Sign up and get your API key

Create a free account at basegrid.io/signup and get your API key from the dashboard.

2. Install the SDK

# Node.js / JavaScript
npm install @basegrid-io/core

# Python
pip install basegrid-io

# React Native
npm install @basegrid-io/react-native axios

3. Start using it

import { BaseGrid } from '@basegrid-io/core'

const bg = new BaseGrid({
  apiKey: process.env.BASEGRID_API_KEY
})

// Add a memory
await bg.add({
  agentId: 'support-bot',
  content: 'User prefers email communication',
  metadata: { userId: '123', preference: 'email' }
})

// Search memories
const results = await bg.search({
  agentId: 'support-bot',
  query: 'How should I contact the user?'
})

console.log(results[0].content)
// Output: "User prefers email communication"

Authentication

Initialize the client with your API key. You can find your API key in the dashboard settings.

import { BaseGrid } from '@basegrid-io/core'

const client = new BaseGrid({
  apiKey: process.env.BASEGRID_API_KEY,
  // Optional: custom base URL (defaults to production)
  // baseUrl: 'https://basegrid-production.up.railway.app'
});

Security Best Practice

Never commit your API keys to version control. Use environment variables or a secrets manager.

How to Create an Agent

An "Agent" is just a workspace for your AI's memories. You can create one in 3 ways:

🖥️

1. Dashboard

Easiest for beginners. Just click "New Agent" on your dashboard.

Dashboard → New Agent

⚡

2. Auto-create

Just use any name in your API call. We'll create it if it doesn't exist.

agentId: 'my-new-bot'

🛠️

3. API (Explicit)

For developers who want full control via code.

POST /v1/agents

Memory Types

BaseGrid supports different types of memories to match how your AI agent thinks and recalls information.

💬

Conversational Memory

Chat history and dialogue context

Store conversation history to maintain context across multiple interactions. Perfect for chatbots and customer support agents.

📊

Factual Memory

User preferences and profile data

Store facts about users, preferences, and settings. Ideal for personalization and user profiles.

⚙️

Procedural Memory

Task workflows and processes

Store step-by-step procedures, workflows, and how-to guides. Perfect for task automation.

🖼️

Multi-modal Memory

Images with automatic understanding

Store images alongside text with automatic image analysis using Gemini 1.5 Flash. Perfect for visual context, product catalogs, and document processing.

Multi-modal Memory

BaseGrid supports storing images alongside text. Images are automatically analyzed using Gemini 1.5 Flash to extract descriptions, making them searchable via semantic search.

How It Works

1.You provide an image URL when adding a memory
2.BaseGrid fetches and analyzes the image with Gemini 1.5 Flash
3.The image description is embedded and stored alongside your text
4.Search queries can now find relevant images semantically

Example: Product Catalog

// Store product with image
await client.memory.add({
  agentId: 'product-assistant',
  content: 'Nike Air Max 2024 - Premium running shoes',
  imageUrl: 'https://example.com/products/nike-air-max.jpg',
  metadata: {
    productId: 'NIKE-AM-2024',
    category: 'footwear',
    price: 129.99
  }
});

// Search will find this product even with visual queries
const results = await client.memory.search({
  agentId: 'product-assistant',
  query: 'red and white sneakers'
});
// Returns: Nike Air Max 2024 (matched via image description)

Example: Document Processing

// Store receipt image
await client.memory.add({
  agentId: 'expense-tracker',
  content: 'Business lunch receipt',
  imageUrl: 'https://storage.example.com/receipts/2024-02-13.jpg',
  metadata: {
    date: '2024-02-13',
    category: 'meals',
    amount: 45.50
  }
});

// Later search for expense details
const results = await client.memory.search({
  agentId: 'expense-tracker',
  query: 'restaurant receipts from February'
});

Supported Image Formats

BaseGrid supports JPEG, PNG, WebP, and GIF formats. Images are analyzed automatically—no additional configuration needed.

API Reference

POST/v1/memories

Add a new memory to an agent's memory store.

POST /v1/memories
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "agentId": "support-bot",
  "content": "User prefers dark mode",
  "metadata": {
    "userId": "123",
    "preference": "dark_mode"
  },
  "importance": 0.8
}

Optional parameters:

• imageUrl - URL of image to analyze and store
• importance - Score 0-1 for memory prioritization
• metadata - Custom key-value pairs for filtering

POST/v1/memories/search

Search memories using hybrid semantic + keyword search.

POST /v1/memories/search
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "agentId": "support-bot",
  "query": "user preferences",
  "limit": 5
}

Rate Limits

Free

100K

requests/month

Pro Starter

requests/month

Pro Plus

10M

requests/month

Scale

50M

requests/month

Framework Integrations

BaseGrid is designed to work with any AI framework. Here's how to integrate it with the most popular ones.

🦜️🔗

LangChain

Use BaseGrid as a retrieval store for LangChain conversations.

Check out our LangChain integration guide for detailed examples.

🦙

LlamaIndex

Feed retrieved memories into LlamaIndex documents for RAG.

Team Collaboration

Teams allow multiple developers to share agents, memories, and API access under one account. You can create and manage your team directly from the Dashboard → Teams → Create Team.

Inviting Members

To invite a colleague, navigate to your Team Settings, click "Invite Member", enter their email address, select their role, and share the generated invite link with them.

Invite Emails Coming Soon

Automated invite emails are coming soon. For now, you must manually copy and share the invite link with your colleague.

POST/v1/teams/{teamId}/invite

You can also invite members programmatically via the API.

POST /v1/teams/{teamId}/invite
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "email": "[email protected]",
  "role": "member"
}

Roles & Permissions

BaseGrid provides role-based access control (RBAC) to help you manage permissions across your team seamlessly.

👑 Owner

Full control over the team, billing, and API keys. The creator of the team is the owner and cannot be removed.

🛡️ Admin

Can manage team members, settings, and full access to all agents and memories.

👩‍💻 Member

Standard access. Can create, read, update, and delete agents and memories. Cannot manage team settings.

👁️ Viewer

Read-only access to agents, memories, and dashboard metrics. Cannot modify data or team settings.

Role Management

Currently, roles are assigned during the invite process. Changing a member's role after they have joined the team is coming in Q3.

Self-Hosting with Docker

Deploy BaseGrid on your own infrastructure with our Docker setup. Keep your data completely within your VPC while maintaining full control.

Quick Start

# Clone the repository
git clone https://github.com/basegridio/basegrid.git
cd basegrid

# Configure environment
cp .env.example .env
# Edit .env with your configuration

# Deploy with Docker Compose
./scripts/deploy-self-hosted.sh

What's Included

✓PostgreSQL with pgvector extension
✓BaseGrid API server
✓Next.js frontend dashboard
✓Automated backups and health checks

Full Documentation

See the complete self-hosting guide in docs/SELF_HOSTING.md for detailed configuration options.

AI Optimization (Beta)

Enhance your memory system with AI-powered features using Google Gemini for automatic categorization and intelligent query expansion.

Auto-Categorization

Memories are automatically categorized when created. No manual tagging required.

// Add a memory - category is auto-detected
await client.memory.add({
  agentId: 'support-bot',
  content: 'User prefers email communication over phone calls'
});

// Result: Automatically tagged as "preferences"

Query Expansion

Search queries are automatically expanded with semantic variations to improve recall.

// Your query
const results = await client.memory.search({
  agentId: 'support-bot',
  query: 'contact preferences'
});

// Automatically expands to:
// - "contact preferences"
// - "communication methods"
// - "preferred contact channels"

Beta Feature

AI Optimization requires a Google API key. Set GOOGLE_API_KEY in your environment.

Troubleshooting

Connection Refused Error

If you see a "Connection Refused" or "ECONNREFUSED" error, you may be using an older SDK version that defaulted to localhost.

Solution: Update to the latest SDK version:

# Node.js
npm install @basegrid-io/core@latest

# Python
pip install --upgrade basegrid-io

# React Native
npm install @basegrid-io/react-native@latest

Invalid API Key

Ensure your API key is correctly formatted and not expired. API keys start with bg_.

You can regenerate your API key from the dashboard settings.

Examples

Explore real-world examples and best practices for using BaseGrid.

Need Help?

Can't find what you're looking for? We're here to help.

Contact Support Go to Dashboard