SDK Reference

The official TypeScript SDK for Agent History. Works in Node.js, Bun, and edge runtimes.

Installation

npm install @agenthistory/sdk

Quick Start

basic-usage.tstypescript
import { AgentHistoryClient } from '@agenthistory/sdk'

const client = new AgentHistoryClient({
  agentKey: process.env.AGENT_HISTORY_KEY,
  mode: 'cloud',
})

// Store a memory
await client.remember(recordId, {
  content: 'User prefers dark mode',
  type: 'fact',
})

// Search memories
const results = await client.recall(recordId, 'user preferences')

Client Configuration

interface AgentHistoryClientOptions {
  // API endpoint (default: https://agenthistory.ai)
  baseUrl?: string
  
  // Agent key for authentication
  agentKey?: string
  
  // Wallet for LOCAL mode authentication
  wallet?: {
    address: `0x${string}`
    signMessage: (message: string) => Promise<`0x${string}`>
  }
  
  // Operating mode
  mode: 'local' | 'cloud'
}

CLOUD Mode

Use CLOUD mode for server-side agents. Memories are stored encrypted on Agent History servers.

const client = new AgentHistoryClient({
  agentKey: 'aht_live_...',
  mode: 'cloud',
})

LOCAL Mode

Use LOCAL mode for self-custody. Memories are encrypted client-side and stored as blobs.

const client = new AgentHistoryClient({
  mode: 'local',
  wallet: {
    address: '0x1234...abcd',
    signMessage: async (message) => {
      return await wallet.signMessage(message)
    },
  },
})

Methods

createAgent()

Create a new agent and receive API credentials.

interface CreateAgentInput {
  name: string
  mode?: 'local' | 'cloud'
  tags?: string[]
  category?: string
}

const agent = await client.createAgent({
  name: 'MyAssistant',
  mode: 'cloud',
  tags: ['assistant'],
})

// agent.agentKey - API key for authentication
// agent.recordId - Default record ID
// agent.walletAddress - Associated wallet

createRecord()

Create a new memory record (container).

interface CreateRecordInput {
  name: string
  tags?: string[]
  category?: string
  parentRecordId?: string
}

const record = await client.createRecord({
  name: 'Project Notes',
  tags: ['project', 'notes'],
  category: 'work',
})

remember()

Store a memory. The content is automatically embedded for semantic search.

interface RememberInput {
  content: string        // Memory content (max 50KB)
  type?: MemoryType      // Auto-classified if omitted
  path?: string          // Optional storage path
  idempotencyKey?: string // Prevent duplicates
}

type MemoryType = 'identity' | 'fact' | 'relationship' | 'episode' | 'skill'

const memory = await client.remember(recordId, {
  content: 'John prefers morning meetings before 10am',
  type: 'relationship',
  path: 'relationships/john',
})

recall()

Search memories using natural language queries.

interface RecallOptions {
  query: string          // Search query
  limit?: number         // Max results (1-50, default: 10)
  types?: MemoryType[]   // Filter by type
}

const results = await client.recall(recordId, {
  query: 'meeting preferences',
  limit: 5,
  types: ['relationship', 'fact'],
})

for (const memory of results.memories) {
  console.log(memory.summary)    // Brief summary
  console.log(memory.content)    // Full content
  console.log(memory.type)       // Memory type
  console.log(memory.similarity) // Relevance score (0-1)
}

Shorthand for simple queries:

const results = await client.recall(recordId, 'meeting preferences')

read()

Read a file from storage.

const file = await client.read(recordId, 'config/settings')
console.log(file.content) // File content
console.log(file.path)    // File path

write()

Write a file to storage.

await client.write(recordId, {
  path: 'config/settings',
  content: JSON.stringify({ theme: 'dark' }),
  idempotencyKey: 'settings-v1',
})

getContext()

Get all memories organized by type.

const context = await client.getContext(recordId)

// context.identity - Who the agent is
// context.fact - Known facts
// context.relationship - People and connections
// context.episode - Past events
// context.skill - How-to knowledge

getRecord()

Get record metadata.

const record = await client.getRecord(recordId)
console.log(record.name)
console.log(record.tags)
console.log(record.category)

updateRecord()

Update record metadata.

await client.updateRecord(recordId, {
  name: 'Updated Name',
  tags: ['new-tag'],
})

deleteRecord()

Delete a record and all its memories.

await client.deleteRecord(recordId)

listRecords()

List all records for the agent.

const records = await client.listRecords({
  limit: 20,
  offset: 0,
})

Types

// Memory type classification
type MemoryType = 'identity' | 'fact' | 'relationship' | 'episode' | 'skill'

// Record metadata
interface RecordMetadata {
  id: string
  name: string
  tags: string[]
  category: string
  contentHash: string
  parentId?: string
  encryptionTier: 1 | 2
  createdAt: Date
  updatedAt: Date
}

// Memory object
interface Memory {
  id: string
  path: string
  type: MemoryType
  summary: string
  content?: string
  updatedAt: Date
}

// Recall results
interface RecallResult {
  memories: Memory[]
  totalCount: number
}

Error Handling

import { AgentHistoryError } from '@agenthistory/sdk'

try {
  await client.remember(recordId, { content: '...' })
} catch (error) {
  if (error instanceof AgentHistoryError) {
    console.log(error.code)    // 'VALIDATION_ERROR'
    console.log(error.message) // 'Content is required'
    console.log(error.status)  // 400
  }
}

Next Steps