Memory & Sessions

Gravity cleanly separates agent configuration, run state, and persistent session state.

Memory Providers

InMemoryProvider (default)

Fast, zero-setup. Great for development, tests, and single-process apps.

import { InMemoryProvider } from 'gravity-sdk';

const agent = new Agent({
  memory: new InMemoryProvider(),
  // ...
});

SQLiteProvider (persistent)

Persists conversation history to a local SQLite database. Survives process restarts.

import { SQLiteProvider } from 'gravity-sdk';

const agent = new Agent({
  memory: new SQLiteProvider('./sessions.db'),
  // ...
});

Multi-Turn Conversations

Pass the same sessionId across multiple calls to maintain conversation history:

const agent = new Agent({ name: 'ChatBot', /* ... */ });

// Turn 1
await agent.run('My name is Iaman.', 'user-42');

// Turn 2 — agent remembers context from Turn 1
const res = await agent.run('What is my name?', 'user-42');
console.log(res.output);
// → "Your name is Iaman."

Custom Storage Adapter

Implement the MemoryProvider interface to plug in any backend (Redis, Postgres, etc.):

import { MemoryProvider, Session, Message } from 'gravity-sdk';

class RedisProvider implements MemoryProvider {
  async getSession(id: string): Promise<Session | null> { /* ... */ }
  async createSession(id: string): Promise<Session> { /* ... */ }
  async saveMessage(sessionId: string, message: Message): Promise<void> { /* ... */ }
  async getMessages(sessionId: string): Promise<Message[]> { /* ... */ }
}

const agent = new Agent({
  memory: new RedisProvider(),
  // ...
});

Message Structure

interface Message {
  role: 'system' | 'user' | 'assistant' | 'tool';
  content: string;
  toolCalls?: ToolCall[];
  toolResultId?: string;
}