@basegrid-io/core

The official Node.js SDK for BaseGrid — persistent memory infrastructure for AI agents.

Sub-200ms memory retrieval. Hybrid semantic search. Built for production.

Installation

npm install @basegrid-io/core

Quick Start

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

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

// Store a memory
await client.add({
  agentId: 'support-bot',
  content: 'User prefers concise answers and dislikes jargon',
});

// Search relevant memories
const memories = await client.search({
  agentId: 'support-bot',
  query: 'communication preferences',
  limit: 5,
});

console.log(memories);

Usage with AI Frameworks

With Vercel AI SDK

import { BaseGrid } from '@basegrid-io/core';
import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

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

// Retrieve context before generating
const memories = await client.search({ agentId: 'assistant', query: userMessage });
const context = memories.map(m => m.content).join('\n');

const { text } = await generateText({
  model: openai('gpt-4o'),
  prompt: `Context from memory:\n${context}\n\nUser: ${userMessage}`,
});

// Store the interaction
await client.add({ agentId: 'assistant', content: `User asked: ${userMessage}` });

With LangChain

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

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

// Use as a memory layer in your chain
const relevantMemories = await client.search({
  agentId: 'langchain-agent',
  query: input,
});

API Reference

client.add(options)

Store a new memory.

const memory = await client.add({
  agentId: string,       // Required: namespace for this agent
  content: string,       // Required: the memory content
  metadata?: object,     // Optional: key-value metadata
  importance?: number,   // Optional: 0-1 (default: 0.5)
});

client.search(options)

Search memories using semantic similarity.

const memories = await client.search({
  agentId: string,   // Required: namespace to search
  query: string,     // Required: semantic search query
  limit?: number,    // Optional: max results (default: 5)
});

client.list(agentId, options?)

List all memories for an agent.

const result = await client.list('support-bot', {
  limit?: number,    // Optional: max results (default: 10)
  offset?: number,   // Optional: pagination offset
  search?: string,   // Optional: text search filter
});

client.delete(memoryId)

Delete a specific memory.

await client.delete('memory_id_here');

Data Management

client.update(memoryId, data)

Update an existing memory.

await client.update('memory_id', {
  content: 'Updated content',
  metadata: { key: 'value' },
});

client.bulkDelete(memoryIds)

Delete multiple memories at once.

await client.bulkDelete(['memory_1', 'memory_2', 'memory_3']);

client.deleteAgentMemories(agentId)

Delete all memories for an agent.

await client.deleteAgentMemories('support-bot');

client.exportAllData()

Export all your data (GDPR compliant).

const data = await client.exportAllData();

Retention Policies

client.getRetentionPolicies()

const policies = await client.getRetentionPolicies();

client.createRetentionPolicy(policy)

await client.createRetentionPolicy({
  agentId: 'support-bot',
  retentionDays: 90,
});

client.updateRetentionPolicy(id, updates)

await client.updateRetentionPolicy('policy_id', {
  retentionDays: 180,
});

client.deleteRetentionPolicy(id)

await client.deleteRetentionPolicy('policy_id');

Configuration

const client = new BaseGrid({
  apiKey: process.env.BASEGRID_API_KEY,  // Required
  baseUrl?: string,                       // Optional: default https://basegrid-production.up.railway.app
});

Pricing

| Plan | Memories | API Calls/Month | Price | |------|----------|-----------------|-------| | Free Trial | 500K | 1,000 | Free for 2 months | | Pro Starter | 500K | 5M | $49/month | | Pro Plus | 2M | 20M | $79/month | | Scale | 10M | 50M | $199/month |

Self-hosting available on Scale plan. Get your key at basegrid.io

Requirements

• Node.js 18+
• A BaseGrid API key (get one free)

Other SDKs

• Python: pip install basegrid-io → basegridio/basegrid-python
• Go: go get github.com/basegridio/basegrid-go → basegridio/basegrid-go

Contributing

See CONTRIBUTING.md

License

Apache 2.0 — see LICENSE

Troubleshooting

Connection Refused Error

If you see connection refused errors, ensure you're using SDK version 1.0.1 or later:

npm install @basegrid-io/core@latest

Earlier versions may have used an incorrect default API endpoint.

Built by BaseGrid · Docs · Discord