npm package: @memoracore/sdk
Description: Official SDK for MemoraCore - The Memory Layer for Production AI Agents
Author: MemoraCore
Latest version: 0.1.0

# @memoracore/sdk

Official SDK for MemoraCore - The Memory Layer for Production AI Agents.

## Installation

```bash
npm install @memoracore/sdk
```

## Quick Start

```typescript
import { MemoraCore } from '@memoracore/sdk'

const client = new MemoraCore({
  apiKey: process.env.MEMORACORE_API_KEY
})

const agent = client.agent('your-agent-id')

// Chat with memory
const response = await agent.chat({
  userId: 'user_123',
  message: 'I need help with my subscription'
})

console.log(response.message)
console.log(response.memoryContext) // { typesUsed: ['user-preference'], memoriesUsedCount: 2 }
```

## Features

### Chat with Memory

```typescript
const response = await agent.chat({
  userId: 'user_123',
  message: 'Hello!',
  context: { plan: 'pro' },        // Optional: user metadata
  conversationId: 'conv_abc123',   // Optional: continue conversation
})

// Response
{
  message: "Hello! How can I help you today?",
  conversationId: "550e8400-e29b-41d4-a716-446655440000",
  agentConfidence: 0.92,
  memoryContext: {
    visibility: "summary",
    typesUsed: ["user-preference", "past-issue"],
    memoriesUsedCount: 3
  },
  escalated: false
}
```

### Event Handling

```typescript
// Listen for escalations
agent.on('escalation', (data) => {
  console.log('Escalation:', data.reason, data.summary)
  notifySupport(data)
})

// Listen for errors
agent.on('error', (data) => {
  console.error('Error:', data.code, data.message)
})

// Unsubscribe
const unsubscribe = agent.on('escalation', handler)
unsubscribe() // Stop listening
```

### Memory Management

```typescript
// Manually store a memory
await agent.remember({
  userId: 'user_123',
  type: 'user-preference',
  content: 'Prefers email communication',
  importance: 0.8,
  expiresInDays: 30,
})

// Recall memories
const memories = await agent.recall({
  userId: 'user_123',
  types: ['user-preference', 'past-issue'],
  limit: 10,
})
```

### Streaming (Coming Soon)

```typescript
for await (const chunk of agent.chatStream({
  userId: 'user_123',
  message: 'Tell me about my account',
})) {
  process.stdout.write(chunk)
}
```

## Configuration

```typescript
const client = new MemoraCore({
  apiKey: 'mc_live_xxx',
  baseUrl: 'https://memoracore.dev/api', // Optional: custom endpoint
})

const agent = client.agent('agent-id', {
  safeMode: {
    enabled: true,
    maxTokensPerRequest: 4096,
    blockPatterns: ['password', 'ssn'],
    requireApprovalAbove: 0.8,
  },
})
```

## Memory Types

| Type | Description |
|------|-------------|
| `user-preference` | Communication preferences, timezone, language |
| `account-detail` | Company name, role, team size |
| `entitlement` | Plan tier, features, subscription status |
| `past-issue` | Previous problems and resolutions |
| `communication-style` | Formal vs casual, detailed vs brief |
| `temporary-context` | Short-term context that expires quickly |

## Events

| Event | Description |
|-------|-------------|
| `escalation` | Agent escalated to human support |
| `error` | API error occurred |
| `confidence_drop` | Agent confidence dropped significantly |
| `memory_conflict` | Conflicting memories detected |
| `cost_spike` | Unusual token usage detected |

## TypeScript Support

Full TypeScript support with exported types:

```typescript
import type {
  MemoraCore,
  Agent,
  ChatOptions,
  ChatResponse,
  MemoryType,
  MemoryContext,
  EscalationTrigger,
} from '@memoracore/sdk'
```

## License

MIT