memq-ai-memory/README.md

Memory SDK with Vercel AI SDK integration

# 🧠 MemQ AI Memory SDK

> **The Ultimate Memory Management SDK for AI Applications** 🚀

A powerful, feature-rich SDK for integrating intelligent memory capabilities into your AI applications. Built with TypeScript and designed for seamless integration with Vercel AI SDK and other AI frameworks.

[![npm version](https://badge.fury.io/js/memq-ai-memory.svg)](https://badge.fury.io/js/memq-ai-memory)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)

## ✨ Features

- 🧠 **Intelligent Memory Management**: Save, retrieve, and search conversations with semantic understanding
- 🤖 **Vercel AI SDK Integration**: Seamless integration with Vercel AI SDK for enhanced chat experiences
- 🔄 **Automatic Context Retrieval**: Automatically fetch relevant memories for context
- 🎯 **Smart Memory Extraction**: AI-powered extraction of key information from conversations
- 🛠️ **Built-in Tools**: Ready-to-use memory tools for AI assistants
- 📱 **Multi-Platform Support**: Works with Node.js, browsers, and React applications
- 🔒 **TypeScript First**: Full TypeScript support with comprehensive type definitions
- ⚡ **High Performance**: Optimized for speed and efficiency

## 🚀 Quick Start

### Installation

```bash
npm install memq-ai-memory
```

### Basic Usage

```typescript
import { MemorySDK } from 'memq-ai-memory';

const sdk = new MemorySDK({
  apiKey: 'your-api-key',
  baseUrl: 'http://localhost:8000'
});

await sdk.initialize();

// Create a memory
const memory = await sdk.createMemory({
  prompt: 'What is the capital of France?',
  response: 'The capital of France is Paris.',
  source: 'chatgpt',
  tags: ['geography', 'france']
});

// Search for memories
const results = await sdk.searchMemories({
  query: 'France',
  limit: 5
});
```

## Quick Start

### Basic Usage

```typescript
import { MemorySDK } from 'memory-sdk';

const sdk = new MemorySDK({ip
  apiKey: 'your-api-key',
  baseUrl: 'http://localhost:8000'
});

await sdk.initialize();

// Create a memory
const memory = await sdk.createMemory({
  prompt: 'What is the capital of France?',
  response: 'The capital of France is Paris.',
  source: 'chat',
  tags: ['geography', 'france']
});

// Search for memories
const results = await sdk.searchMemories({
  query: 'France',
  limit: 5
});
```

### 🤖 Vercel AI SDK Integration

```typescript
import { MemoryProvider, createMemoryAssistant } from 'memq-ai-memory';

// Create a memory provider
const memoryProvider = new MemoryProvider({
  apiKey: 'your-api-key',
  baseUrl: 'http://localhost:8000',
  autoSave: true,
  autoRetrieve: true,
  memoryLimit: 5,
  user_id: 'user-123'
});

// Create a memory-enabled assistant
const assistant = createMemoryAssistant(model, memoryProvider);

// Use the assistant with memory context
const result = await assistant.generateText([
  { role: 'user', content: 'What did we talk about yesterday?' }
]);
```

### 🔄 Streaming with Memory Context

```typescript
import { streamTextWithMemory } from 'memq-ai-memory';

const result = await streamTextWithMemory(
  model,
  messages,
  {
    memoryProvider: {
      apiKey: 'your-api-key',
      baseUrl: 'http://localhost:8000',
      user_id: 'user-123'
    },
    includeMemoryContext: true,
    memoryContextTemplate: 'Previous conversations:\n{memories}\n\nUse this context.'
  }
);
```

## 📚 API Reference

### MemorySDK

The main SDK class for memory operations.

#### Constructor

```typescript
new MemorySDK(config: SDKConfig)
```

#### Methods

- `initialize()`: Initialize the SDK and validate API key
- `createMemory(memory: MemoryCreateRequest)`: Create a new memory
- `searchMemories(request: MemorySearchRequest)`: Search for memories with semantic understanding
- `getAllMemories(userId: string, limit?: number)`: Get all memories for a user
- `getUserFacts(userId: string, category?: string, limit?: number)`: Get user facts
- `getRecentActivity(userId: string, limit?: number)`: Get recent user activity
- `deleteMemory(memoryId: string)`: Delete a memory
- `healthCheck()`: Check API health status

### MemoryProvider

Provider for Vercel AI SDK integration.

#### Constructor

```typescript
new MemoryProvider(config: MemoryProviderConfig)
```

#### Configuration Options

- `apiKey`: Your API key for authentication
- `baseUrl`: Base URL for the memory service (e.g., `http://localhost:8000`)
- `autoSave`: Whether to automatically save conversations (default: `true`)
- `autoRetrieve`: Whether to automatically retrieve relevant memories (default: `true`)
- `memoryLimit`: Number of memories to retrieve (default: `5`)
- `similarityThreshold`: Similarity threshold for retrieval (default: `0.7`)
- `user_id`: User ID for the provider
- `extractMemory`: Custom memory extraction function
- `enableLogging`: Enable request/response logging (default: `false`)

#### Methods

- `initialize()`: Initialize the provider and validate connection
- `getTools()`: Get memory tools for AI SDK integration
- `executeTool(toolCall)`: Execute a memory tool
- `autoSaveMemory(messages, userId?)`: Automatically save conversation to memory
- `autoRetrieveMemories(query, userId?)`: Automatically retrieve relevant memories

### 🛠️ Memory Tools

The SDK provides three powerful built-in tools:

1. **save_memory**: Save a conversation or information to memory with automatic extraction
2. **retrieve_memories**: Retrieve relevant memories based on semantic similarity
3. **search_memories**: Search for specific memories with advanced filtering and categorization

## 💡 Examples

See the `examples/` directory for complete examples:

- `basic-usage.js`: Basic SDK usage examples
- `vercel-ai-example.ts`: Vercel AI SDK integration examples
- `nextjs-app/`: Complete Next.js application example

## ⚙️ Configuration

### Environment Variables

```bash
MEMORY_API_KEY=your-api-key
MEMORY_BASE_URL=http://localhost:8000
```

### TypeScript Configuration

The SDK includes comprehensive TypeScript definitions. Make sure your `tsconfig.json` includes:

```json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}
```

## 🛠️ Development

### Building

```bash
npm run build
```

### Development Mode

```bash
npm run dev
```

### Testing

```bash
npm test
```

## 📦 Installation Options

### NPM
```bash
npm install memq-ai-memory
```

### Yarn
```bash
yarn add memq-ai-memory
```

### PNPM
```bash
pnpm add memq-ai-memory
```

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## 📄 License

MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- 📧 **Email**: support@memq.ai
- 🐛 **Issues**: [GitHub Issues](https://github.com/memq/memQ/issues)
- 📖 **Documentation**: [Full Documentation](https://docs.memq.ai)
- 💬 **Discord**: [Join our community](https://discord.gg/memq)

---


<div align="center">
Made with ❤️ by the MemQ Team
</div>