Skip to content

feat(ai-sdk): re-export @supermemory/tools/ai-sdk #1402

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
haroon0x wants to merge 1 commit into from
Closed

feat(ai-sdk): re-export @supermemory/tools/ai-sdk #1402

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .github/workflows/publish-ai-sdk.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,8 @@ jobs:

- name: Build
if: steps.version-check.outputs.changed == 'true'
run: bun run build
working-directory: .
run: bunx turbo run build --filter='@supermemory/ai-sdk'

- name: Publish
if: steps.version-check.outputs.changed == 'true'
Expand Down
86 changes: 19 additions & 67 deletions bun.lock
View file
Open in desktop

Large diffs are not rendered by default.

320 changes: 31 additions & 289 deletions packages/ai-sdk/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,306 +1,48 @@
# supermemory AI SDK Utilities

Vercel AI SDK utilities for supermemory
# @supermemory/ai-sdk (deprecated)

> [!WARNING]
> **Deprecated.** Use [`@supermemory/tools/ai-sdk`](https://www.npmjs.com/package/@supermemory/tools) instead:
>
> ```ts
> import { supermemoryTools } from "@supermemory/tools/ai-sdk"
> ```
>
> Since 2.0.0 this package is a re-export of `@supermemory/tools/ai-sdk` and
> inherits its container-scoping and coercion semantics. This is a behavior
> change:
>
> - Passing both `projectId` and `containerTags` now throws instead of silently
> ignoring `containerTags`.
> - With no config, calls are scoped to `["sm_project_default"]`. Previously
> they were unscoped, searching and writing across every project. If you
> relied on that, pass `containerTags` explicitly.
> - `limit` is coerced, so a model emitting `"5"` is accepted.

## Installation

```bash
npm install @supermemory/ai-sdk
# or
bun add @supermemory/ai-sdk
# or
pnpm add @supermemory/ai-sdk
# or
yarn add @supermemory/ai-sdk
```

## Features

Choose **one** of the following approaches (they cannot be used together):

- **Infinite Chat Provider**: Connect to various LLM providers with unlimited context support
- **Memory Tools**: Search, add, and fetch memories from supermemory using AI agents

## Infinite Chat Provider

The infinite chat provider allows you to connect to various LLM providers with supermemory's context management.

```typescript
import { generateText } from 'ai'
## Usage

// Using a custom provider URL
const supermemoryOpenai = createOpenAI({
baseUrl: 'https://api.supermemory.ai/v3/https://api.openai.com/v1',
apiKey: 'your-provider-api-key',
headers: {
'x-supermemory-api-key': 'supermemory-api-key',
'x-sm-conversation-id': 'conversation-id'
}
})
```ts
import { supermemoryTools } from "@supermemory/ai-sdk"
import { generateText } from "ai"
import { openai } from "@ai-sdk/openai"

const result = await generateText({
model: supermemoryOpenai('gpt-5'),
messages: [
{ role: 'user', content: 'Hello, how are you?' }
]
model: openai("gpt-5"),
messages: [{ role: "user", content: "What do you remember about me?" }],
tools: supermemoryTools(process.env.SUPERMEMORY_API_KEY!, {
projectId: "your-project-id",
}),
})
```

### Complete Infinite Chat Example

```typescript
import { generateText } from 'ai'

const supermemoryApiKey = process.env.SUPERMEMORY_API_KEY!
const openaiApiKey = process.env.OPENAI_API_KEY!

// Initialize infinite chat provider
const supermemoryOpenai = createOpenAI({
baseUrl: 'https://api.supermemory.ai/v3/https://api.openai.com/v1',
apiKey: 'your-provider-api-key',
headers: {
'x-supermemory-api-key': 'supermemory-api-key',
'x-sm-conversation-id': 'conversation-id'
}
})

async function chat(userMessage: string) {
const result = await generateText({
model: supermemoryOpenai('gpt-5'),
messages: [
{
role: 'system',
content: 'You are a helpful assistant with unlimited context.'
},
{
role: 'user',
content: userMessage
}
]
// No tools - infinite chat handles context automatically
})

return result.text
}
```

### Configuration

```typescript
// Option 1: Use a named provider
interface ConfigWithProviderName {
providerName: 'openai' | 'anthropic' | 'openrouter' | 'deepinfra' | 'groq' | 'google' | 'cloudflare'
providerApiKey: string
headers?: Record<string, string>
}

// Option 2: Use a custom provider URL
interface ConfigWithProviderUrl {
providerUrl: string
providerApiKey: string
headers?: Record<string, string>
}
```

## Memory Tools

supermemory tools allow AI agents to interact with user memories for enhanced context and personalization.

```typescript
import { supermemoryTools } from '@supermemory/ai-sdk'
import { generateText } from 'ai'

const result = await generateText({
model: openai('gpt-5'),
messages: [
{ role: 'user', content: 'What do you remember about my preferences?' }
],
tools: {
...supermemoryTools('your-supermemory-api-key', {
// Optional: specify a base URL for self-hosted instances
baseUrl: 'https://api.supermemory.com',

// Use either projectId OR containerTags, not both
projectId: 'your-project-id',
// OR
containerTags: ['tag1', 'tag2']
}),
// Your other tools go here
}
})
```

### Complete Memory Tools Example

```typescript
import { supermemoryTools } from '@supermemory/ai-sdk'
import { generateText } from 'ai'
import { openai } from '@ai-sdk/openai'

const supermemoryApiKey = process.env.SUPERMEMORY_API_KEY!

async function chatWithTools(userMessage: string) {
const result = await generateText({
model: openai('gpt-5'), // Use standard provider
messages: [
{
role: 'system',
content: 'You are a helpful assistant with access to user memories.'
},
{
role: 'user',
content: userMessage
}
],
tools: {
...supermemoryTools(supermemoryApiKey, {
containerTags: ['my-user-id']
})
},
maxToolRoundtrips: 5
})

return result.text
}
```

### Configuration

```typescript
interface SupermemoryConfig {
// Optional: Base URL for API calls (default: https://api.supermemory.com)
baseUrl?: string

// Container tags for organizing memories (cannot be used with projectId)
containerTags?: string[]

// Project ID for scoping memories (cannot be used with containerTags)
projectId?: string
}
```

### Self-Hosted supermemory

If you're running a self-hosted supermemory instance:

```typescript
const tools = supermemoryTools('your-api-key', {
baseUrl: 'https://your-supermemory-instance.com',
containerTags: ['production', 'user-memories']
})
```

### Available Tools

##### Search Memories

Search through user memories using semantic matching.

```typescript
const searchResult = await tools.searchMemories.execute({
informationToGet: 'user preferences about coffee'
})
```

##### Add Memory

Add new memories to the user's memory store.

```typescript
const addResult = await tools.addMemory.execute({
memory: 'User prefers dark roast coffee in the morning'
})
```

##### Fetch Memory

Retrieve a specific memory by its ID.

```typescript
const fetchResult = await tools.fetchMemory.execute({
memoryId: 'memory-id-123'
})
```

### Using Individual Tools

For more flexibility, you can import and use individual tools:

```typescript
import {
searchMemoriesTool,
addMemoryTool,
fetchMemoryTool
} from '@supermemory/ai-sdk'

const searchTool = searchMemoriesTool('your-api-key', {
projectId: 'your-project-id'
})

// Use only the search tool
const result = await generateText({
model: openai('gpt-5'),
messages: [...],
tools: {
searchMemories: searchTool
}
})
```

### Error Handling

All tool executions return a result object with a `success` field:

```typescript
const result = await tools.searchMemories.execute({
informationToGet: 'user preferences'
})

if (result.success) {
console.log('Found memories:', result.results)
console.log('Total count:', result.count)
} else {
console.error('Error searching memories:', result.error)
}
```

## Development

### Running Tests

```bash
# Run all tests
bun test

# Run tests in watch mode
bun test --watch
```

#### Environment Variables for Tests

All tests require API keys to run. Copy `.env.example` to `.env` and set the required values:

```bash
cp .env.example .env
```

**Required:**
- `SUPERMEMORY_API_KEY`: Your Supermemory API key
- `PROVIDER_API_KEY`: Your AI provider API key (OpenAI, Anthropic, etc.)
- `OPENAI_API_KEY`: Your OpenAI API key for tool integration tests

**Optional:**
- `SUPERMEMORY_BASE_URL`: Custom Supermemory base URL (defaults to `https://api.supermemory.ai`)
- `PROVIDER_NAME`: Provider name (defaults to `openai`) - one of: `openai`, `anthropic`, `openrouter`, `deepinfra`, `groq`, `google`, `cloudflare`
- `PROVIDER_URL`: Custom provider URL (use instead of `PROVIDER_NAME`)
- `MODEL_NAME`: Model to use in tests (defaults to `gpt-3.5-turbo`)

Tests will fail if required API keys are not provided.
All tools and configuration options are documented under
[`@supermemory/tools`](https://www.npmjs.com/package/@supermemory/tools).

## License

MIT

## Support

Email our [24/7 Founder/CEO/Support Executive](dhravya@supermemory.com)
Loading
Loading