memofai/README.md

Official JavaScript/TypeScript SDK for Memory-of-Agents (MOA) - AI memory infrastructure for intelligent applications

# memofai

[![npm version](https://badge.fury.io/js/memofai.svg)](https://www.npmjs.com/package/memofai)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.2+-blue.svg)](https://www.typescriptlang.org/)

Official JavaScript/TypeScript SDK for Memory-of-Agents (MOA). Build intelligent applications with persistent AI memory.

## Features

✨ **Clean Namespace API** - Intuitive methods organized by resource type  
🔒 **Type-Safe** - Full TypeScript support with comprehensive types  
🧠 **Memory Management** - Store, search, and retrieve AI agent memories  
🤖 **Bot Operations** - Create and manage AI bots with ease  
🏢 **Workspace Control** - Organize your AI infrastructure  
⚡ **Auto-Retry** - Built-in retry logic for resilient API calls  
🎯 **Natural Language Search** - Query memories conversationally

## Installation

```bash
npm install memofai
```

## Quick Start

### Get Your API Token

1. Visit [dashboard.memof.ai/dashboard/tokens](https://dashboard.memof.ai/access-tokens)
2. Click "Create New Token"
3. Copy your token (format: `moa_...`)

### Basic Example

```typescript
import { createMoaClient } from 'memofai';

const client = createMoaClient({
  apiToken: 'moa_your_token_here',
  environment: 'production'
});

// Create a workspace
const workspace = await client.workspaces.create({
  name: "My AI Workspace",
  description: "Workspace for my AI agents"
});

// Create a bot
const bot = await client.bots.create({
  name: "Assistant",
  description: "Helpful AI assistant",
  moa_workspace: workspace.id,
  type: "conversational",
  status: "active"
});

// Store a memory
const memory = await client.memories.store({
  bot_id: bot.id,
  content_text: "User prefers concise responses",
  memory_type: "preference"
});

// Search memories
const results = await client.memories.search({
  bot_id: bot.id,
  query: "How should I communicate with the user?",
  top_k: 5
});
```

## API Reference

### Configuration

```typescript
const client = createMoaClient({
  apiToken: 'moa_your_token',
  environment: 'production', // 'dev' | 'alpha' | 'beta' | 'sandbox' | 'production'
  timeout: 30000,            // Optional: request timeout (ms)
  retries: 3,                // Optional: retry attempts
  retryDelay: 1000          // Optional: retry delay (ms)
});
```

### Workspaces

```typescript
// List all workspaces
const workspaces = await client.workspaces.list();

// Create workspace
const workspace = await client.workspaces.create({
  name: "My Workspace",
  description: "Optional description"
});

// Get workspace
const workspace = await client.workspaces.retrieve(workspaceId);

// Update workspace
const updated = await client.workspaces.update(workspaceId, {
  name: "New Name"
});

// Delete workspace
await client.workspaces.delete(workspaceId);
```

### Bots

```typescript
// List all bots
const bots = await client.bots.list();

// Create bot
const bot = await client.bots.create({
  name: "My Bot",
  description: "AI assistant",
  moa_workspace: workspaceId,
  type: "conversational",
  status: "active"
});

// Get bot
const bot = await client.bots.retrieve(botId);

// Update bot
const updated = await client.bots.update(botId, {
  name: "Updated Name"
});

// Delete bot
await client.bots.delete(botId);
```

### Memories

```typescript
// Store memory
const memory = await client.memories.store({
  bot_id: botId,
  content_text: "User prefers dark mode",
  memory_type: "preference"
});

// List memories
const result = await client.memories.list(botId, {
  memory_type: "preference",
  limit: 20
});

// Search memories
const results = await client.memories.search({
  bot_id: botId,
  query: "What are user preferences?",
  top_k: 5,
  generate_answer: true
});

// Reprocess memory
const result = await client.memories.reprocess(memoryId, {
  bot_id: botId
});

// Delete memory
await client.memories.delete(memoryId, {
  bot_id: botId
});
```

## Error Handling

```typescript
import { ValidationError, NotFoundError, AuthenticationError } from 'memofai';

try {
  const bot = await client.bots.retrieve(botId);
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Validation errors:', error.validationErrors);
  } else if (error instanceof NotFoundError) {
    console.error('Bot not found');
  } else if (error instanceof AuthenticationError) {
    console.error('Invalid API token');
  }
}
```

## TypeScript Support

Full TypeScript support with comprehensive types:

```typescript
import type {
  Workspace,
  Bot,
  Memory,
  CreateWorkspaceBody,
  CreateBotBody,
  StoreMemoryBody,
  SearchMemoriesResponse
} from 'memofai';
```

## Environments

| Environment | Description |
|------------|-------------|
| `dev` | Local development |
| `alpha` | Early testing |
| `beta` | Pre-production |
| `sandbox` | Testing & development |
| `production` | Production (default) |

## Links

- [Website](https://memof.ai)
- [API Dashboard](https://dashboard.memof.ai)
- [Get API Token](https://dashboard.memof.ai/dashboard/tokens)
- [GitHub](https://github.com/memof-ai/memofai-js-sdk)
- [npm Package](https://www.npmjs.com/package/memofai)

## Support

- Email: hello@memof.ai
- GitHub Issues: [Create an issue](https://github.com/memof-ai/memofai-js-sdk/issues/new)

## License

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

---

Built with ❤️ by the Memory-of-Agents Team

#### Store Memory