memofai/README.md

Revolutionary dual-track AI memory infrastructure SDK for JavaScript/TypeScript applications

# MOA SDK - JavaScript/TypeScript

[![npm version](https://badge.fury.io/js/memofai.svg)](https://www.npmjs.com/package/memofai)
[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)

Revolutionary dual-track AI memory infrastructure SDK for JavaScript/TypeScript applications.

## 🚀 Installation

```bash
npm install memofai
# or
yarn add memofai
# or
pnpm add memofai
```

## 📋 Development Progress

### ✅ Completed Tasks
- [x] Project structure setup
- [x] TypeScript configuration
- [x] Base client architecture
- [x] Environment configuration (alpha, beta, production)
- [x] Memory operations API
- [x] Search functionality
- [x] Graph search implementation
- [x] Relationship management
- [x] Error handling with custom error classes
- [x] Type definitions (full TypeScript support)
- [x] Documentation and examples
- [x] Build system (ESM, CJS, UMD outputs)
- [x] Testing setup with Jest
- [x] npm publishing configuration
- [x] CI/CD pipeline with GitHub Actions
- [x] Linting and code formatting
- [x] API versioning support

### 🔄 Current Phase
**Phase 3: Ready for Publishing** - Complete! 🎉

The MOA SDK is fully implemented and ready for production use. All features are complete, tested, and documented.

## 🏗️ Quick Start

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

// Initialize with environment and API key
const client = new MOAClient({
  environment: 'beta', // 'alpha' | 'beta' | 'production'
  apiKey: 'your-api-key',
  apiVersion: 'v1'
});

// Create a memory
const memory = await client.memories.create({
  content: "Important information to remember",
  metadata: { source: "user-input" },
  tags: ["important", "user"],
  retention_days: 30
});

// Search memories with hybrid approach
const results = await client.memories.search({
  query: "important information",
  max_results: 10,
  vector_weight: 0.4,
  keyword_weight: 0.3,
  fuzzy_weight: 0.15,
  temporal_weight: 0.1,
  metadata_weight: 0.05
});

// Graph search for semantic relationships
const graphResults = await client.graphSearch.search({
  query: "related concepts",
  search_type: "semantic_neighborhood",
  max_depth: 3,
  max_results: 20,
  min_relationship_strength: 0.3
});

// Generate relationships between memories
const relationships = await client.relationships.generate({
  batch_size: 10,
  force_regenerate: false
});
```

## 🛠️ Features

- **Multi-Environment Support**: Alpha, Beta, Production environments
- **API Versioning**: Support for different API versions
- **TypeScript First**: Full type safety and IntelliSense support
- **Memory Operations**: Complete CRUD operations for memories
- **Advanced Search**: Hybrid search with customizable weights (vector, keyword, fuzzy, temporal, metadata)
- **Graph Search**: 8 different graph-based search algorithms
- **Relationship Management**: AI-powered relationship generation and cleanup
- **Error Handling**: Comprehensive error handling with 9 custom error types
- **Rate Limiting**: Built-in rate limiting and retry mechanisms with exponential backoff
- **Tree-shakable**: Optimized for bundle size with multiple output formats (ESM, CJS)
- **Extensive Testing**: 39 unit tests covering all functionality with high coverage
- **Development Tools**: Full linting, type checking, and CI/CD pipeline

## 📊 Package Statistics

- **Package Size**: ~20.7 kB compressed, ~148 kB unpacked
- **Build Output**: 404 kB total (ESM + CJS + TypeScript declarations)
- **Dependencies**: 1 runtime dependency (axios)
- **Test Coverage**: 39 tests across 2 test suites
- **Supported Node.js**: 16.x, 18.x, 20.x
- **TypeScript**: Full type definitions included

## 📖 API Reference

### Client Initialization

```typescript
interface MOAClientConfig {
  environment: 'alpha' | 'beta' | 'production';
  apiKey: string;
  apiVersion?: string;
  timeout?: number;
  retryAttempts?: number;
  baseURL?: string; // Custom base URL override
}
```

### Memory Operations

```typescript
// Create memory
await client.memories.create(data: MemoryCreateRequest): Promise<MemoryResponse>

// Get memory by ID
await client.memories.get(memoryId: string): Promise<Memory>

// Update memory
await client.memories.update(memoryId: string, data: MemoryUpdateRequest): Promise<MemoryResponse>

// Delete memory
await client.memories.delete(memoryId: string): Promise<MemoryResponse>

// Search memories
await client.memories.search(params: SearchParams): Promise<SearchResponse>

// Get analytics
await client.memories.getAnalytics(): Promise<AnalyticsResponse>
```

### Graph Search

```typescript
await client.graphSearch.search(params: GraphSearchRequest): Promise<GraphSearchResponse>
await client.graphSearch.getSearchTypes(): Promise<SearchTypeInfo[]>
```

### Relationships

```typescript
await client.relationships.generate(params: RelationshipGenerationRequest): Promise<RelationshipGenerationResponse>
await client.relationships.getStats(): Promise<RelationshipStats>
await client.relationships.cleanup(minStrength?: number): Promise<CleanupResponse>
```

## 🔧 Configuration

### Environment URLs

- **Alpha**: `https://api.alpha.memof.ai`
- **Beta**: `https://beta-api.memof.ai`
- **Production**: `https://api.memof.ai`

### API Versions

- **v1**: Current stable version (default)

### Graph Search Types

The SDK supports multiple graph search algorithms:

- **`shortest_path`**: Find memories connected via shortest relationship paths
- **`similarity_cluster`**: Find semantic neighborhoods of similar memories  
- **`concept_traversal`**: Search based on concept relationships
- **`temporal_flow`**: Find memories in temporal sequence
- **`causal_chain`**: Discover causal relationships between memories
- **`semantic_neighborhood`**: Find semantically related memory clusters
- **`multi_hop_similarity`**: Multi-step similarity traversal
- **`concept_intersection`**: Find memories sharing multiple concepts

```typescript
// Get available search types and their descriptions
const searchTypes = await client.graphSearch.getSearchTypes();
console.log(searchTypes);
```

## ⚠️ Error Handling

The SDK provides comprehensive error handling with custom error types:

```typescript
import { 
  MOAError, 
  MOAAuthenticationError,
  MOAValidationError,
  MOANotFoundError,
  MOARateLimitError,
  MOAServerError,
  MOANetworkError,
  MOATimeoutError,
  MOAConfigurationError
} from 'memofai';

try {
  const memory = await client.memories.create({
    content: "Test memory"
  });
} catch (error) {
  if (error instanceof MOAAuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof MOAValidationError) {
    console.error('Validation errors:', error.validationErrors);
  } else if (error instanceof MOARateLimitError) {
    console.error('Rate limited. Retry after:', error.retryAfter);
  } else if (error instanceof MOANetworkError) {
    console.error('Network issue - check connection');
  } else if (error instanceof MOATimeoutError) {
    console.error('Request timed out');
  } else if (error instanceof MOAError) {
    console.error('MOA API error:', error.message, error.code);
  }
}
```

## 🧪 Testing

```bash
npm test
npm run test:coverage
npm run test:watch
```

## 🔨 Development

```bash
# Install dependencies
npm install

# Build the project
npm run build

# Run linter
npm run lint

# Run type checking
npm run type-check

# Start development mode
npm run dev
```

## 📦 Publishing

### Prepare for Publishing

1. **Update version in package.json**:
   ```bash
   npm version patch  # or minor, major
   ```

2. **Validate the build**:
   ```bash
   npm run validate  # Runs type-check, lint, and tests
   npm run build     # Build all formats
   ```

3. **Test the built package locally**:
   ```bash
   npm pack          # Creates a .tgz file
   cd ../test-project
   npm install ../memofai-js/memofai-*.tgz
   ```

### Publishing to npm

1. **Login to npm**:
   ```bash
   npm login
   ```

2. **Publish**:
   ```bash
   npm publish       # This runs prepublishOnly script automatically
   ```

   Or publish with tag:
   ```bash
   npm publish --tag beta
   ```

### Automated Publishing

The package includes GitHub Actions workflow that automatically:
- Runs tests on Node.js 16, 18, and 20
- Publishes to npm when a GitHub release is created
- Requires `NPM_TOKEN` secret in repository settings

To set up automated publishing:
1. Create an npm access token at https://www.npmjs.com/settings/tokens
2. Add it as `NPM_TOKEN` in GitHub repository secrets
3. Create a GitHub release to trigger publishing

## 📦 Manual Publishing to npm

The SDK is ready for publishing! Follow these steps:

### Prerequisites
```bash
# Ensure you're logged into npm
npm login

# Verify your npm credentials
npm whoami
```

### Publishing Process
```bash
# Final validation (optional but recommended)
npm run test
npm run build
npm run type-check
npm run lint

# Publish to npm (use --dry-run first to test)
npm publish --dry-run  # Test the publish process
npm publish            # Actual publish

# For beta releases
npm publish --tag beta
```

### Version Management
```bash
# Update version and publish
npm version patch    # 1.0.0 -> 1.0.1
npm version minor    # 1.0.0 -> 1.1.0
npm version major    # 1.0.0 -> 2.0.0

# Publish after version bump
npm publish
```

### Post-Publishing
After publishing, users can install your SDK:
```bash
npm install memofai-js
# or
yarn add memofai-js
```

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- 📧 Email: hello@memof.ai
- 🌐 Website: https://memof.ai
- 📚 Documentation: https://docs.memof.ai

---

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