Log In

Official SDKs and client libraries for the Lightfast Memory API.

TypeScript / JavaScript

The official TypeScript SDK provides full type safety and supports both Node.js and browser environments.

Installation

bash
npm install @lightfast/memory
# or
pnpm add @lightfast/memory
# or
yarn add @lightfast/memory

Quick Start

typescript
import { createMemory } from '@lightfast/memory'

const memory = createMemory({
apiKey: process.env.LIGHTFAST_API_KEY,
provider: 'chroma',
config: {
  host: 'http://localhost:8000'
}
})

// Add memory
await memory.addMemory({
collection: 'github-lightfast',
id: 'pr-127',
content: 'PR description...',
metadata: { type: 'pr', source: 'github' }
})

// Search
const results = await memory.searchMemory({
query: 'auth refactor',
limit: 10
})

Type Safety

typescript
// Strongly typed metadata
interface GitHubPRMetadata extends MemoryMetadata {
type: 'pr'
source: 'github'
prNumber: number
state: 'open' | 'closed' | 'merged'
}

await memory.addMemory<GitHubPRMetadata>({
collection: 'github-lightfast',
id: 'pr-127',
content: 'PR description...',
metadata: {
  type: 'pr',
  source: 'github',
  prNumber: 127,
  state: 'open'
  // TypeScript enforces this structure
}
})

Provider Configuration

Chroma (Self-Hosted)

typescript
const memory = createMemory({
apiKey: process.env.LIGHTFAST_API_KEY,
provider: 'chroma',
config: {
  host: 'http://localhost:8000',
  ssl: false,
  headers: {
    'X-Custom-Header': 'value'
  }
}
})

Pinecone (Cloud)

typescript
const memory = createMemory({
apiKey: process.env.LIGHTFAST_API_KEY,
provider: 'pinecone',
config: {
  environment: 'us-east1-gcp',
  index: 'lightfast-prod',
  apiKey: process.env.PINECONE_API_KEY,
  namespace: 'production'
}
})

Qdrant (Hybrid)

typescript
const memory = createMemory({
apiKey: process.env.LIGHTFAST_API_KEY,
provider: 'qdrant',
config: {
  url: 'https://xyz.qdrant.io',
  apiKey: process.env.QDRANT_API_KEY,
  collection: 'lightfast'
}
})

Advanced Usage

Batch Operations

typescript
// Add multiple memories efficiently
const memories = [
{ collection: 'github', id: 'pr-1', content: '...' },
{ collection: 'github', id: 'pr-2', content: '...' },
// ... up to 100 items
]

await memory.addMemoryBatch(memories)

Custom Embeddings

typescript
import { generateEmbedding } from './embeddings'

const embedding = await generateEmbedding('Your content...')

await memory.addMemory({
collection: 'custom',
id: 'doc-1',
content: 'Your content...',
embedding: embedding // Use your own embedding
})

Error Handling

typescript
import { MemoryAPIError } from '@lightfast/memory'

try {
await memory.addMemory({ ... })
} catch (error) {
if (error instanceof MemoryAPIError) {
  console.error('API Error:', error.code, error.message)

  if (error.code === 'rate_limit_exceeded') {
    // Wait and retry
    await sleep(error.details.retryAfter * 1000)
  }
}
}

Python

The official Python SDK provides async support and type hints.

Installation

bash
pip install lightfast-memory
# or
poetry add lightfast-memory

Quick Start

python
from lightfast_memory import Memory
import os

memory = Memory(
  api_key=os.getenv("LIGHTFAST_API_KEY"),
  provider="chroma",
  config={"host": "http://localhost:8000"}
)

# Add memory
await memory.add_memory(
  collection="github-lightfast",
  id="pr-127",
  content="PR description...",
  metadata={"type": "pr", "source": "github"}
)

# Search
results = await memory.search_memory(
  query="auth refactor",
  limit=10
)

Async Support

python
import asyncio
from lightfast_memory import AsyncMemory

async def main():
  memory = AsyncMemory(api_key="...")

  # Concurrent operations
  tasks = [
      memory.add_memory(...),
      memory.add_memory(...),
      memory.add_memory(...)
  ]

  results = await asyncio.gather(*tasks)

asyncio.run(main())

Type Hints

python
from typing import TypedDict, Literal
from lightfast_memory import Memory, MemoryMetadata

class GitHubPRMetadata(MemoryMetadata):
  type: Literal["pr"]
  source: Literal["github"]
  pr_number: int
  state: Literal["open", "closed", "merged"]

metadata: GitHubPRMetadata = {
  "type": "pr",
  "source": "github",
  "pr_number": 127,
  "state": "open"
}

await memory.add_memory(
  collection="github-lightfast",
  id="pr-127",
  content="...",
  metadata=metadata
)

Go

The official Go SDK provides idiomatic Go interfaces and error handling.

Installation

bash
go get github.com/lightfastai/lightfast-go

Quick Start

go
package main

import (
  "context"
  "log"
  "os"

  "github.com/lightfastai/lightfast-go/memory"
)

func main() {
  client := memory.NewClient(
      memory.WithAPIKey(os.Getenv("LIGHTFAST_API_KEY")),
      memory.WithProvider("chroma"),
      memory.WithConfig(map[string]interface{}{
          "host": "http://localhost:8000",
      }),
  )

  ctx := context.Background()

  // Add memory
  err := client.AddMemory(ctx, &memory.AddMemoryRequest{
      Collection: "github-lightfast",
      ID:         "pr-127",
      Content:    "PR description...",
      Metadata: map[string]interface{}{
          "type":   "pr",
          "source": "github",
      },
  })
  if err != nil {
      log.Fatal(err)
  }

  // Search
  results, err := client.SearchMemory(ctx, &memory.SearchRequest{
      Query: "auth refactor",
      Limit: 10,
  })
  if err != nil {
      log.Fatal(err)
  }
}

Error Handling

go
import "github.com/lightfastai/lightfast-go/memory"

err := client.AddMemory(ctx, req)
if err != nil {
  if apiErr, ok := err.(*memory.APIError); ok {
      switch apiErr.Code {
      case "rate_limit_exceeded":
          // Wait and retry
          time.Sleep(time.Duration(apiErr.RetryAfter) * time.Second)
      case "conflict":
          // Memory exists, update instead
          err = client.UpdateMemory(ctx, updateReq)
      default:
          log.Printf("API error: %s - %s", apiErr.Code, apiErr.Message)
      }
  }
}

Ruby

Coming soon! The Ruby SDK is currently in development.

ruby
# Coming soon
gem 'lightfast-memory'

client = Lightfast::Memory.new(
api_key: ENV['LIGHTFAST_API_KEY']
)

client.add_memory(
collection: 'github-lightfast',
id: 'pr-127',
content: 'PR description...'
)

PHP

Coming soon! The PHP SDK is currently in development.

php
// Coming soon
composer require lightfast/memory

$memory = new LightfastMemory([
  'apiKey' => $_ENV['LIGHTFAST_API_KEY']
]);

$memory->addMemory([
  'collection' => 'github-lightfast',
  'id' => 'pr-127',
  'content' => 'PR description...'
]);

Community SDKs

Rust

Community-maintained Rust SDK:

toml
[dependencies]
lightfast-memory = "0.1.0"
rust
use lightfast_memory::{Memory, AddMemoryRequest};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
  let memory = Memory::new(
      std::env::var("LIGHTFAST_API_KEY")?
  );

  memory.add_memory(AddMemoryRequest {
      collection: "github-lightfast".to_string(),
      id: "pr-127".to_string(),
      content: "PR description...".to_string(),
      metadata: None,
      embedding: None,
  }).await?;

  Ok(())
}

Java

Community-maintained Java SDK:

xml
<dependency>
  <groupId>ai.lightfast</groupId>
  <artifactId>memory-sdk</artifactId>
  <version>0.1.0</version>
</dependency>
java
import ai.lightfast.memory.MemoryClient;

MemoryClient client = MemoryClient.builder()
  .apiKey(System.getenv("LIGHTFAST_API_KEY"))
  .build();

client.addMemory(
  "github-lightfast",
  "pr-127",
  "PR description..."
);

OpenAPI Specification

Generate your own client using our OpenAPI spec:

bash
# Download OpenAPI spec
curl https://api.lightfast.ai/v1/openapi.json -o lightfast-openapi.json

# Generate client (example with OpenAPI Generator)
openapi-generator generate -i lightfast-openapi.json -g typescript-axios -o ./generated-client

SDK Features Comparison

FeatureTypeScriptPythonGoRubyPHP
Type Safety✅✅✅🚧🚧
Async Support✅✅✅🚧🚧
Batch Operations✅✅✅🚧🚧
Custom Embeddings✅✅✅🚧🚧
Retry Logic✅✅✅🚧🚧
Streaming✅✅❌🚧🚧
Browser Support✅❌❌❌❌

Contributing

We welcome contributions to our SDKs! See our GitHub repository for:

  • Contributing guidelines
  • Issue templates
  • Development setup
  • Testing instructions

Support

On this page

TypeScript / JavaScriptInstallationQuick StartType SafetyProvider ConfigurationChroma (Self-Hosted)Pinecone (Cloud)Qdrant (Hybrid)Advanced UsageBatch OperationsCustom EmbeddingsError HandlingPythonInstallationQuick StartAsync SupportType HintsGoInstallationQuick StartError HandlingRubyPHPCommunity SDKsRustJavaOpenAPI SpecificationSDK Features ComparisonContributingSupport