Skip to main content
Ruby client library for the Skald API.

​
Installation

Add this line to your application’s Gemfile: 
gem 'skald'
And then execute: 
bundle install
Or install it yourself as: 
gem install skald

​
Requirements

  • Ruby 3.0.0 or higher

​
Usage

​
Initialize the client

require 'skald'

skald = Skald.new('your-api-key-here')

​
Memo Management

​
Create a Memo

Create a new memo that will be automatically processed (summarized, tagged, chunked, and indexed for search): 
result = skald.create_memo(
  title: 'Meeting Notes',
  content: 'Full content of the memo...',
  metadata: {
    type: 'notes',
    author: 'John Doe'
  },
  reference_id: 'external-id-123',
  tags: ['meeting', 'q1'],
  source: 'notion',
  expiration_date: '2024-12-31T23:59:59Z'
)

puts result # { ok: true }
Required Fields:
  • title (string, max 255 chars) - The title of the memo
  • content (string) - The full content of the memo
Optional Fields:
  • metadata (hash) - Custom JSON metadata
  • reference_id (string, max 255 chars) - An ID from your side that you can use to match Skald memo UUIDs with e.g. documents on your end
  • tags (array of strings) - Tags for categorization
  • source (string, max 255 chars) - An indication from your side of the source of this content, useful when building integrations
  • expiration_date (string) - ISO 8601 timestamp for automatic memo expiration

​
Get a Memo

Retrieve a memo by its UUID or your reference ID: 
# Get by UUID
memo = skald.get_memo('550e8400-e29b-41d4-a716-446655440000')

# Get by reference ID
memo = skald.get_memo('external-id-123', 'reference_id')

puts memo[:title]
puts memo[:content]
puts memo[:summary]
puts memo[:tags]
puts memo[:chunks]
The get_memo() method returns complete memo details including content, AI-generated summary, tags, and content chunks.

​
List Memos

List all memos with pagination: 
# Get first page with default page size (20)
memos = skald.list_memos

# Get specific page with custom page size
memos = skald.list_memos(page: 2, page_size: 50)

puts "Total memos: #{memos[:count]}"
puts "Results: #{memos[:results].length}"
puts "Next page: #{memos[:next]}"
Parameters:
  • page (integer, optional) - Page number (default: 1)
  • page_size (integer, optional) - Results per page (default: 20, max: 100)

​
Update a Memo

Update an existing memo by UUID or reference ID: 
# Update by UUID
skald.update_memo('550e8400-e29b-41d4-a716-446655440000', {
  title: 'Updated Title',
  metadata: { status: 'reviewed' }
})

# Update by reference ID and trigger reprocessing
skald.update_memo('external-id-123', {
  content: 'New content that will be reprocessed'
}, 'reference_id')
Note: When you update the content field, the memo will be automatically reprocessed (summary, tags, and chunks regenerated). Updatable Fields:
  • title (string)
  • content (string)
  • metadata (hash)
  • client_reference_id (string)
  • source (string)
  • expiration_date (string)

​
Delete a Memo

Permanently delete a memo and all associated data: 
# Delete by UUID
skald.delete_memo('550e8400-e29b-41d4-a716-446655440000')

# Delete by reference ID
skald.delete_memo('external-id-123', 'reference_id')
Warning: This operation permanently deletes the memo and all related data (content, summary, tags, chunks) and cannot be undone.

​
Search Memos

Search through your memos using various search methods with optional filters: 
# Basic semantic search
results = skald.search(
  query: 'quarterly goals',
  search_method: 'chunk_vector_search',
  limit: 10
)

# Search with filters
filtered = skald.search(
  query: 'python tutorial',
  search_method: 'title_contains',
  filters: [
    {
      field: 'source',
      operator: 'eq',
      value: 'notion',
      filter_type: 'native_field'
    },
    {
      field: 'level',
      operator: 'eq',
      value: 'beginner',
      filter_type: 'custom_metadata'
    }
  ]
)

puts "Found #{filtered[:results].length} results"
filtered[:results].each do |memo|
  puts "- #{memo[:title]} (distance: #{memo[:distance]})"
end

​
Search Methods

  • chunk_vector_search - Semantic search on memo chunks for detailed content search
  • title_contains - Case-insensitive substring match on memo titles
  • title_startswith - Case-insensitive prefix match on memo titles

​
Search Parameters

  • query (string, required) - The search query
  • search_method (SearchMethod, required) - One of the search methods above
  • limit (integer, optional) - Maximum results to return (1-50, default 10)
  • filters (array, optional) - Array of filter hashes to narrow results (see Filters section below)

​
Search Response

{
  results: [
    {
      uuid: "550e8400-...",
      title: "Project Planning Meeting",
      summary: "Discussed Q1 goals...",
      content_snippet: "...relevant excerpt from the content...",
      distance: 0.45  # For vector search: 0-2, lower is better. nil for title searches
    }
  ]
}
  • uuid - Unique identifier for the memo
  • title - Memo title
  • summary - Auto-generated summary for the memo
  • content_snippet - A snippet containing the beginning of the memo
  • distance - A decimal from 0 to 2 determining how close the result was deemed to be to the query when using semantic search (chunk_vector_search). The closer to 0 the more related the content is to the query. nil if using title_contains or title_startswith.

​
Chat with Your Knowledge Base

Ask questions about your memos using an AI agent. The agent retrieves relevant context and generates answers with inline citations.

​
Non-Streaming Chat

result = skald.chat(
  query: 'What were the main points discussed in the Q1 meeting?'
)

puts result[:response]
# "The main points discussed in the Q1 meeting were:
# 1. Revenue targets [[1]]
# 2. Hiring plans [[2]]
# 3. Product roadmap [[1]][[3]]"

puts result[:ok] # true

​
Streaming Chat

For real-time responses, use streaming chat: 
skald.streamed_chat(
  query: 'What are our quarterly goals?'
).each do |event|
  if event[:type] == 'token'
    # Write each token as it arrives
    print event[:content]
  elsif event[:type] == 'done'
    puts "\nDone!"
  end
end

​
Chat Parameters

  • query (string, required) - The question to ask
  • filters (array, optional) - Array of filter hashes to focus chat context on specific sources (see Filters section below)

​
Chat Response

Non-streaming responses include:
  • ok (boolean) - Success status
  • response (string) - The AI’s answer with inline citations in format [[N]]
  • intermediate_steps (array) - Steps taken by the agent (for debugging)
Streaming responses yield events:
  • { type: 'token', content: string } - Each text token as it’s generated
  • { type: 'done' } - Indicates the stream has finished

​
Generate Documents

Generate documents based on prompts and retrieved context from your knowledge base. Similar to chat but optimized for document generation with optional style/format rules.

​
Non-Streaming Document Generation

result = skald.generate_doc(
  prompt: 'Create a product requirements document for a new mobile app',
  rules: 'Use formal business language. Include sections for: Overview, Requirements, Technical Specifications, Timeline'
)

puts result[:response]
# "# Product Requirements Document
#
# ## Overview
# This document outlines the requirements for...
#
# ## Requirements
# 1. User authentication [[1]]
# 2. Push notifications [[2]]..."

puts result[:ok] # true

​
Streaming Document Generation

For real-time document generation, use streaming: 
skald.streamed_generate_doc(
  prompt: 'Write a technical specification for user authentication',
  rules: 'Include sections for: Architecture, Security, API Endpoints, Data Models'
).each do |event|
  if event[:type] == 'token'
    # Write each token as it arrives
    print event[:content]
  elsif event[:type] == 'done'
    puts "\nDone!"
  end
end

​
Generate Document Parameters

  • prompt (string, required) - The prompt describing what document to generate
  • rules (string, optional) - Optional style/format rules (e.g., “Use formal language. Include sections: X, Y, Z”)
  • filters (array, optional) - Array of filter hashes to control which memos are used for generation (see Filters section below)

​
Generate Document Response

Non-streaming responses include:
  • ok (boolean) - Success status
  • response (string) - The generated document with inline citations in format [[N]]
  • intermediate_steps (array) - Steps taken by the agent (for debugging)
Streaming responses yield events:
  • { type: 'token', content: string } - Each text token as it’s generated
  • { type: 'done' } - Indicates the stream has finished

​
Filters

Filters allow you to narrow down results based on memo metadata. You can filter by native fields or custom metadata fields. Filters are supported in search(), chat(), generate_doc(), and their streaming variants. See Filters for complete documentation.

​
Filter Structure

{
  field: "field_name",          # Field name to filter on
  operator: "eq",               # Comparison operator
  value: "value",               # Value(s) to compare against
  filter_type: "native_field"   # 'native_field' or 'custom_metadata'
}

​
Native Fields

Native fields are built-in memo properties:
  • title - Memo title
  • source - Source system (e.g., “notion”, “confluence”)
  • client_reference_id - Your external reference ID
  • tags - Memo tags (array)

​
Custom Metadata Fields

You can filter on any field from the metadata hash you provided when creating the memo.

​
Filter Operators

  • eq - Equals (exact match)
  • neq - Not equals
  • contains - Contains substring (case-insensitive)
  • startswith - Starts with prefix (case-insensitive)
  • endswith - Ends with suffix (case-insensitive)
  • in - Value is in array (requires array value)
  • not_in - Value is not in array (requires array value)

​
Filter Examples

# Filter by source
{
  field: 'source',
  operator: 'eq',
  value: 'notion',
  filter_type: 'native_field'
}

# Filter by multiple tags
{
  field: 'tags',
  operator: 'in',
  value: ['security', 'compliance'],
  filter_type: 'native_field'
}

# Filter by title containing text
{
  field: 'title',
  operator: 'contains',
  value: 'meeting',
  filter_type: 'native_field'
}

# Filter by custom metadata field
{
  field: 'department',
  operator: 'eq',
  value: 'engineering',
  filter_type: 'custom_metadata'
}

# Exclude specific sources
{
  field: 'source',
  operator: 'not_in',
  value: ['draft', 'archive'],
  filter_type: 'native_field'
}

​
Combining Multiple Filters

When you provide multiple filters, they are combined with AND logic (all filters must match): 
results = skald.search(
  query: 'security best practices',
  search_method: 'chunk_vector_search',
  filters: [
    {
      field: 'source',
      operator: 'eq',
      value: 'security-docs',
      filter_type: 'native_field'
    },
    {
      field: 'tags',
      operator: 'in',
      value: ['approved', 'current'],
      filter_type: 'native_field'
    },
    {
      field: 'status',
      operator: 'neq',
      value: 'draft',
      filter_type: 'custom_metadata'
    }
  ]
)

​
Filters with Chat

Focus chat context on specific sources: 
result = skald.chat(
  query: 'What are our security practices?',
  filters: [
    {
      field: 'tags',
      operator: 'in',
      value: ['security', 'compliance'],
      filter_type: 'native_field'
    }
  ]
)

​
Filters with Document Generation

Control which memos are used for document generation: 
doc = skald.generate_doc(
  prompt: 'Create an API integration guide',
  rules: 'Use technical language with code examples',
  filters: [
    {
      field: 'source',
      operator: 'in',
      value: ['api-docs', 'technical-specs'],
      filter_type: 'native_field'
    },
    {
      field: 'document_type',
      operator: 'eq',
      value: 'specification',
      filter_type: 'custom_metadata'
    }
  ]
)

​
Error Handling

begin
  result = skald.create_memo(
    title: 'My Memo',
    content: 'Content here'
  )
  puts "Success: #{result}"
rescue => e
  puts "Error: #{e.message}"
end
⌘I