supermemory-ai-provider/README.md

Vercel AI Provider for providing memory to LLMs using Supermemory

# Supermemory AI SDK Provider

The **Supermemory AI SDK Provider** is a library that integrates with the Vercel AI SDK. This library brings enhanced AI interaction capabilities to your applications by introducing persistent memory functionality. With Supermemory, language model conversations gain memory, enabling more contextualized and personalized responses based on past interactions.

For detailed information on using the Vercel AI SDK, refer to Vercel's [API Reference](https://sdk.vercel.ai/docs/reference) and [Documentation](https://sdk.vercel.ai/docs).

## Features

- 🧠 Persistent memory storage for AI conversations
- 🔄 Seamless integration with Vercel AI SDK
- 🚀 Support for multiple LLM providers (OpenAI, Anthropic)
- 📝 Rich message format support
- ⚡ Streaming capabilities
- 🔍 Context-aware responses

## Installation

```bash
npm install @supermemory/vercel-ai-provider
```

## Before We Begin

### Setting Up Supermemory

1. Obtain your Supermemory API Key from your Supermemory dashboard.

2. Initialize the Supermemory Client:

```typescript
import { createSupermemory } from "@supermemory/vercel-ai-provider";

const supermemory = createSupermemory({
  provider: "openai",
  supermemoryApiKey: "your-supermemory-api-key",
  apiKey: "openai-api-key",
  config: {
    // Additional model-specific configuration options can be added here.
  },
});
```

### Note
By default, the `openai` provider is used, so specifying it is optional:
```typescript
const supermemory = createSupermemory();
```
For better security, consider setting `SUPERMEMORY_API_KEY` and `OPENAI_API_KEY` as environment variables.

3. Add Memories to Enhance Context:

```typescript
import { LanguageModelV1Prompt } from "ai";
import { addMemories } from "@supermemory/vercel-ai-provider";

const messages: LanguageModelV1Prompt = [
  {
    role: "user",
    content: [
      { type: "text", text: "I love red cars." },
      { type: "text", text: "I like Toyota Cars." },
      { type: "text", text: "I prefer SUVs." },
    ],
  },
];

await addMemories(messages, { user_id: "user123" });
```

These memories are now stored in your profile. You can view and manage them on your Supermemory dashboard.

### Note:

For standalone features, such as `addMemories` and `retrieveMemories`,
you must either set `SUPERMEMORY_API_KEY` as an environment variable or pass it directly in the function call.

Example:

```typescript
await addMemories(messages, { user_id: "user123", supermemoryApiKey: "your-supermemory-api-key" });
await retrieveMemories(prompt, { user_id: "user123", supermemoryApiKey: "your-supermemory-api-key" });
await getMemories(prompt, { user_id: "user123", supermemoryApiKey: "your-supermemory-api-key" });
```

### Note:

`retrieveMemories` enriches the prompt with relevant memories from your profile, while `getMemories` returns the memories in array format which can be used for further processing.

## Usage Examples

### 1. Basic Text Generation with Memory Context

```typescript
import { generateText } from "ai";
import { createSupermemory } from "@supermemory/vercel-ai-provider";

const supermemory = createSupermemory();

const { text } = await generateText({
  model: supermemory("gpt-4-turbo", {
    user_id: "user123",
  }),
  prompt: "Suggest me a good car to buy!",
});
```

### 2. Combining OpenAI Provider with Memory Utils

```typescript
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { retrieveMemories } from "@supermemory/vercel-ai-provider";

const prompt = "Suggest me a good car to buy.";
const memories = await retrieveMemories(prompt, { user_id: "user123" });

const { text } = await generateText({
  model: openai("gpt-4-turbo"),
  prompt: prompt,
  system: memories,
});
```

### 3. Structured Message Format with Memory

```typescript
import { generateText } from "ai";
import { createSupermemory } from "@supermemory/vercel-ai-provider";

const supermemory = createSupermemory();

const { text } = await generateText({
  model: supermemory("gpt-4-turbo", {
    user_id: "user123",
  }),
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "Suggest me a good car to buy." },
        { type: "text", text: "Why is it better than the other cars for me?" },
        { type: "text", text: "Give options for every price range." },
      ],
    },
  ],
});
```

### 4. Advanced Memory Integration with OpenAI

```typescript
import { generateText, LanguageModelV1Prompt } from "ai";
import { openai } from "@ai-sdk/openai";
import { retrieveMemories } from "@supermemory/vercel-ai-provider";

// New format using system parameter for memory context
const messages: LanguageModelV1Prompt = [
  {
    role: "user",
    content: [
      { type: "text", text: "Suggest me a good car to buy." },
      { type: "text", text: "Why is it better than the other cars for me?" },
      { type: "text", text: "Give options for every price range." },
    ],
  },
];

const memories = await retrieveMemories(messages, { user_id: "user123" });

const { text } = await generateText({
  model: openai("gpt-4-turbo"),
  messages: messages,
  system: memories,
});
```

### 5. Streaming Responses with Memory Context

```typescript
import { streamText } from "ai";
import { createSupermemory } from "@supermemory/vercel-ai-provider";

const supermemory = createSupermemory();

const { textStream } = await streamText({
  model: supermemory("gpt-4-turbo", {
    user_id: "user123",
  }),
  prompt:
    "Suggest me a good car to buy! Why is it better than the other cars for me? Give options for every price range.",
});

for await (const textPart of textStream) {
  process.stdout.write(textPart);
}
```

## Core Functions

- `createSupermemory()`: Initializes a new supermemory provider instance with optional configuration
- `retrieveMemories()`: Enriches prompts with relevant memories
- `addMemories()`: Add memories to your profile
- `getMemories()`: Get memories from your profile in array format

## Configuration Options

```typescript
const supermemory = createSupermemory({
  config: {
    // Additional model-specific configuration options can be added here.
  },
});
```

## Best Practices

1. **User Identification**: Always provide a unique `user_id` identifier for consistent memory retrieval
2. **Context Management**: Use appropriate context window sizes to balance performance and memory
3. **Error Handling**: Implement proper error handling for memory operations
4. **Memory Cleanup**: Regularly clean up unused memory contexts to optimize performance

## Notes

- Requires proper API key configuration for underlying providers (e.g., OpenAI)
- Memory features depend on proper user identification via `user_id`
- Supports both streaming and non-streaming responses
- Compatible with all Vercel AI SDK features and patterns