Guide
This guide covers installation, configuration, and usage patterns for recursive-llm-ts.
Installation
npm install recursive-llm-ts
The postinstall script automatically builds the Go binary. If Go is not available, it will warn but not fail.
Prerequisites
- Node.js 16+ or Bun 1.0+
- Go 1.25+ — only needed if building the Go binary from source
- An OpenAI API key (or key for any OpenAI-compatible provider)
On supported targets, npm installs a matching @recursive-llm/<platform> package automatically. For manual deployments, you can still use GitHub Releases and point RLM_GO_BINARY at the downloaded binary.
Configuration
Set your API key as an environment variable or pass it in the configuration.
export OPENAI_API_KEY='sk-...'
Or pass it directly:
const rlm = new RLM('gpt-4o-mini', {
api_key: 'sk-...',
max_iterations: 15,
max_depth: 5,
});
First Completion
The simplest usage — pass a query and a large context string:
import { RLM } from 'recursive-llm-ts';
const rlm = new RLM('gpt-4o-mini', {
api_key: process.env.OPENAI_API_KEY,
});
const result = await rlm.completion(
'What are the key findings?',
veryLargeDocument // Any size - no token limit
);
console.log(result.result);
console.log('Stats:', result.stats);
// { llm_calls: 8, iterations: 12, depth: 2 }
await rlm.cleanup();
The engine automatically:
- Splits the context into manageable chunks
- Uses the LLM to write JavaScript analysis code
- Executes the code in a sandboxed REPL
- Recursively combines results
Recursive Decomposition
The core innovation from the RLM paper. When a context is too large for a single LLM call, the engine:
- Splits the context into chunks that fit the model's context window
- Processes each chunk with the LLM, which writes JavaScript code to analyze it
- Executes the code in a sandboxed JavaScript REPL (goja engine)
- Recurses if needed — results from subchunks become context for the next level
- Merges results back up the tree to produce the final answer
Control recursion with max_depth (default: 5) and max_iterations (default: 30).
Structured Outputs
Extract typed data using Zod schemas. The engine converts your schema to JSON Schema, decomposes complex schemas into subtasks, and validates results with retry logic.
import { z } from 'zod';
const schema = z.object({
sentiment: z.number().min(1).max(5),
summary: z.string(),
topics: z.array(z.enum(['pricing', 'features', 'support'])),
keyPhrases: z.array(z.object({
phrase: z.string(),
weight: z.number(),
})),
});
const result = await rlm.structuredCompletion(
'Analyze this transcript',
transcript,
schema,
{ parallelExecution: true, maxRetries: 3 }
);
// result.result is typed as z.infer<typeof schema>
How it works under the hood:
- Zod schema is converted to JSON Schema
- Meta-agent optimizes the query for extraction (if enabled)
- Complex schemas are decomposed into per-field subtasks
- Subtasks run in parallel via goroutines
- Each field is validated against its JSON Schema
- Failed fields get retried with error feedback (instructor-style)
- Results are merged into the final typed object
Supported Zod types: objects, arrays, strings, numbers, booleans, enums, unions (z.union), intersections (z.intersection), optionals, nullables, and all constraints (min, max, length, pattern, etc.).
File Storage Context
Process files from local directories or S3-compatible storage as LLM context. Added in v4.4.0.
Local Files
const result = await rlm.completionFromFiles(
'Describe the architecture',
{
type: 'local',
path: './src',
extensions: ['.ts', '.tsx'],
excludePatterns: ['*.test.ts', 'node_modules/**'],
maxFileSize: 100_000,
maxTotalSize: 5_000_000,
maxFiles: 100,
}
);
S3 Storage
Works with AWS S3, MinIO, LocalStack, DigitalOcean Spaces, and Backblaze B2.
// AWS S3
const result = await rlm.completionFromFiles(
'Summarize reports',
{
type: 's3',
path: 'my-bucket',
prefix: 'reports/',
extensions: ['.md', '.txt'],
region: 'us-west-2',
// Credentials: explicit > env vars > AWS SDK chain
}
);
// MinIO
const result2 = await rlm.completionFromFiles(
'Analyze data',
{
type: 's3',
path: 'local-bucket',
endpoint: 'http://localhost:9000',
credentials: {
accessKeyId: 'minioadmin',
secretAccessKey: 'minioadmin',
},
}
);
Credentials are resolved in order: (1) explicit credentials in config, (2) environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN), (3) AWS SDK default chain (IAM role, ~/.aws/credentials, ECS task role).
Meta-Agent
The meta-agent automatically optimizes queries before processing. Useful for vague or non-specific queries.
const rlm = new RLM('gpt-4o-mini', {
api_key: process.env.OPENAI_API_KEY,
meta_agent: {
enabled: true,
model: 'gpt-4o', // Stronger model for optimization
max_optimize_len: 10000, // Skip for short contexts
},
});
// "what happened?" becomes:
// "Provide a detailed summary including: key decisions,
// action items, participants, and unresolved issues."
const result = await rlm.completion('what happened?', transcript);
Observability
Three observability backends available simultaneously:
Debug Logging
const rlm = new RLM('gpt-4o-mini', {
debug: true, // Shorthand for observability.debug
});
OpenTelemetry
const rlm = new RLM('gpt-4o-mini', {
observability: {
trace_enabled: true,
trace_endpoint: 'http://localhost:4318',
service_name: 'my-service',
},
});
Langfuse
const rlm = new RLM('gpt-4o-mini', {
observability: {
langfuse_enabled: true,
langfuse_public_key: process.env.LANGFUSE_PUBLIC_KEY,
langfuse_secret_key: process.env.LANGFUSE_SECRET_KEY,
},
});
Accessing Trace Events
const result = await rlm.completion('Summarize', doc);
const events = rlm.getTraceEvents();
for (const e of events) {
console.log(`[${e.type}] ${e.name}`, e.attributes);
// [span_start] rlm.completion {trace_id: "abc..."}
// [llm_call] gpt-4o-mini {tokens: 1247, duration_ms: 2341}
// [span_end] rlm.completion {total_duration_ms: 5218}
}
Context Overflow Recovery
When your context exceeds the model's token limit, RLM automatically detects the overflow and reduces the context using one of 6 strategies. This works with any OpenAI-compatible API including vLLM, Ollama, and Azure.
Context overflow recovery is enabled by default. No configuration needed — it detects overflow errors from the API and automatically retries with reduced context.
How It Works
- RLM sends the full context to the LLM API
- If the API returns a context overflow error, RLM parses the token counts
- The configured strategy reduces the context to fit within the model's limit
- The reduced context is sent to the LLM for processing
- Up to 3 reduction attempts (configurable) before giving up
Strategy Comparison
| Strategy | How It Works | LLM Calls | Best For |
|---|---|---|---|
mapreduce |
Splits context into chunks, summarizes each with the LLM, combines summaries | N + 1 | General purpose, preserves key info across full document |
truncate |
Keeps beginning and end of context, removes the middle | 0 | Fast, zero-cost; good when key info is at start/end |
chunked |
Extracts relevant chunks via LLM, merges the best ones | N + 1 | Query-focused extraction from large documents |
tfidf |
Scores sentences by TF-IDF relevance to the query, keeps top sentences | 0 | Fast, zero-cost; good for keyword-heavy queries |
textrank |
Graph-based sentence ranking (like PageRank for text), keeps top sentences | 0 | Fast, zero-cost; good for extracting important sentences |
refine |
Processes chunks sequentially, refining a running summary | N | Best quality for narrative/sequential content |
Which Strategy to Use
- Default (mapreduce) — Best all-around choice. Processes all chunks in parallel and combines results.
- Cost-sensitive? Use
truncate,tfidf, ortextrank— zero LLM calls for reduction. - Query-focused? Use
tfidforchunked— they prioritize content relevant to your query. - Narrative content? Use
refine— processes sequentially to maintain document flow. - Small models (<8K)? Use
tfidfortextrank— pure algorithmic, no risk of recursive overflow.
Configuration
const rlm = new RLM('gpt-4o-mini', {
api_key: process.env.OPENAI_API_KEY,
max_tokens: 10000,
// Context overflow configuration
context_overflow: {
enabled: true, // Default: true
strategy: 'mapreduce', // Default: 'mapreduce'
safety_margin: 0.15, // Reserve 15% for overhead (default)
max_reduction_attempts: 3, // Max retries (default: 3)
max_model_tokens: 0, // 0 = auto-detect from API errors
},
});
Strategy Examples
// Zero-cost TF-IDF for budget-conscious workloads
const rlm = new RLM('qwen3-8b', {
api_base: 'http://localhost:8000/v1',
max_tokens: 10000,
context_overflow: {
strategy: 'tfidf', // No extra LLM calls
},
});
// Refine for high-quality narrative summarization
const rlm2 = new RLM('gpt-4o', {
context_overflow: {
strategy: 'refine',
safety_margin: 0.2, // More headroom for longer responses
},
});
// Disable overflow recovery (fail fast)
const rlm3 = new RLM('gpt-4o-mini', {
context_overflow: { enabled: false },
});
Works with Structured Outputs
Context overflow recovery works seamlessly with structuredCompletion(). If the context overflows during structured extraction, the engine reduces context first, then retries the extraction.
// Even with 100K+ tokens of data, this works
const result = await rlm.structuredCompletion(
'Extract customer insights',
hugeDataset, // Exceeds model limit
schema,
{ parallelExecution: true }
);
// Context is automatically reduced before extraction
If you set max_tokens, the overflow handler accounts for it when sizing chunks. For example, with a 32K model and max_tokens: 10000, only ~22K tokens are available for context. The handler automatically detects this from API errors like "max_tokens is too large".
Streaming
Stream completions in real-time using async iterables. Supports both text and structured object streaming with AbortController integration.
// Stream text tokens
const stream = await rlm.streamCompletion(
'Summarize this document',
longDocument
);
for await (const chunk of stream) {
if (chunk.type === 'text') {
process.stdout.write(chunk.text);
}
}
// Collect all text at once
const text = await stream.toText();
// Stream structured objects
const objStream = await rlm.streamStructuredCompletion(
'Extract key info', context, schema
);
const result = await objStream.toObject();
// With abort support
const controller = new AbortController();
setTimeout(() => controller.abort(), 30000);
const stream2 = await rlm.streamCompletion(
'Summarize', doc, controller.signal
);
Caching
Enable response caching to avoid redundant LLM calls. Two backends available: in-memory (LRU with TTL) and file-based persistent cache.
const rlm = new RLM('gpt-4o-mini', {
api_key: process.env.OPENAI_API_KEY,
cache: {
enabled: true,
maxEntries: 1000, // LRU eviction limit
ttl: 3600000, // 1 hour TTL
backend: 'memory', // or 'file'
directory: '.rlm-cache', // for file backend
},
});
// First call hits the LLM
const result1 = await rlm.completion('Summarize', doc);
console.log(result1.cached); // false
// Second identical call returns from cache
const result2 = await rlm.completion('Summarize', doc);
console.log(result2.cached); // true
// Check cache stats
const stats = rlm.getCacheStats();
console.log(stats); // { hits: 1, misses: 1, hitRate: 0.5, ... }
// Clear cache when needed
rlm.clearCache();
Retry & Resilience
Built-in retry logic with multiple backoff strategies. Rate-limit aware with automatic delay adjustment. Multi-provider fallback chains for high availability.
const rlm = new RLM('gpt-4o-mini', {
api_key: process.env.OPENAI_API_KEY,
retry: {
maxRetries: 3,
baseDelay: 1000,
backoff: 'exponential', // or 'linear', 'fixed'
jitter: true,
onRetry: (attempt, error, delay) => {
console.log(`Retry ${attempt} after ${delay}ms: ${error.message}`);
},
},
fallback: {
models: ['gpt-4o-mini', 'gpt-4o', 'claude-sonnet-4-20250514'],
},
});
// Standalone retry utility
import { withRetry, withFallback } from 'recursive-llm-ts';
const result = await withRetry(
() => fetch('https://api.example.com/data'),
{ maxRetries: 3, backoff: 'exponential' }
);
Error Handling
Structured error hierarchy with 9 typed error classes. Each error includes a code, retryability flag, and an actionable suggestion for resolution.
import {
RLMError,
RLMValidationError,
RLMRateLimitError,
RLMTimeoutError,
RLMProviderError,
RLMBinaryError,
RLMConfigError,
RLMSchemaError,
RLMAbortError,
classifyError,
} from 'recursive-llm-ts';
try {
const result = await rlm.completion('query', context);
} catch (err) {
if (err instanceof RLMRateLimitError) {
console.log(`Rate limited. Retry after: ${err.retryAfter}s`);
} else if (err instanceof RLMValidationError) {
console.log(`Schema validation failed: ${err.field}`);
console.log(`Suggestion: ${err.suggestion}`);
} else if (err instanceof RLMTimeoutError) {
console.log(`Timed out after ${err.timeout}ms`);
} else if (err instanceof RLMError) {
console.log(`RLM error [${err.code}]: ${err.message}`);
console.log(`Retryable: ${err.retryable}`);
}
}
// Auto-classify raw errors
const classified = classifyError(new Error('connection timeout'));
console.log(classified instanceof RLMTimeoutError); // true
Events
Subscribe to lifecycle events for monitoring, logging, and custom integrations. The typed event emitter supports 10 event types.
// Subscribe to events
rlm.on('llm_call', (event) => {
console.log(`LLM call to ${event.model}, context: ${event.contextLength}`);
});
rlm.on('error', (event) => {
console.error(`Error in ${event.operation}:`, event.error);
});
rlm.on('cache', (event) => {
console.log(`Cache ${event.action}`); // 'hit' | 'miss' | 'set'
});
rlm.on('retry', (event) => {
console.log(`Retry attempt ${event.attempt} after ${event.delay}ms`);
});
// One-time listener
rlm.once('completion_end', (event) => {
console.log(`First completion done in ${event.duration}ms`);
});
// Remove listeners
const handler = (e: any) => console.log(e);
rlm.on('llm_call', handler);
rlm.off('llm_call', handler);
// Remove all listeners for an event
rlm.removeAllListeners('error');
Builder API
Fluent builder for complex configurations. Factory methods for common setups.
// Fluent builder
const rlm = RLM.builder()
.model('gpt-4o-mini')
.apiKey(process.env.OPENAI_API_KEY!)
.maxDepth(5)
.maxIterations(20)
.enableMetaAgent('gpt-4o')
.enableDebug()
.enableCache({ maxEntries: 500 })
.enableRetry({ maxRetries: 3, backoff: 'exponential' })
.build();
// Factory methods
const rlm1 = RLM.fromEnv(); // Auto-detect from env
const rlm2 = RLM.withDebug('gpt-4o'); // Quick debug setup
const rlm3 = RLM.forAzure( // Azure-specific
'my-deployment',
'https://my.openai.azure.com',
process.env.AZURE_API_KEY!
);
Batch Operations
Process multiple queries concurrently with configurable concurrency limits.
// Batch text completions
const results = await rlm.batchCompletion([
{ query: 'Summarize chapter 1', context: chapter1 },
{ query: 'Summarize chapter 2', context: chapter2 },
{ query: 'Summarize chapter 3', context: chapter3 },
], { concurrency: 3 });
for (const r of results) {
console.log(r.result);
}
// Batch structured completions
const structured = await rlm.batchStructuredCompletion(
[
{ query: 'Extract from doc1', context: doc1 },
{ query: 'Extract from doc2', context: doc2 },
],
schema,
{ concurrency: 2 }
);
Config Validation
Validate configuration before use. Catches typos, invalid values, and missing settings with actionable messages.
import { validateConfig, assertValidConfig } from 'recursive-llm-ts';
// Get detailed validation results
const result = validateConfig({
api_key: 'sk-...',
max_detph: 5, // typo!
max_iterations: -1, // invalid!
});
for (const issue of result.issues) {
console.log(`[${issue.level}] ${issue.field}: ${issue.message}`);
}
// [warning] max_detph: Unknown config key "max_detph" (possible typo for "max_depth")
// [error] max_iterations: max_iterations must be positive
// Or throw on errors
assertValidConfig({ max_depth: -1 });
// throws RLMConfigError
Lossless Context Management (LCM)
LCM is an opt-in context management layer that replaces legacy message pruning with a deterministic, DAG-based architecture. Every message is persisted in an immutable store, and context is managed via a hierarchical summary DAG.
LCM is optional and backward-compatible. Enable it by setting lcm.enabled: true in your config. Without it, the engine behaves exactly as before.
LCM Configuration
const rlm = new RLM('gpt-4o', {
api_key: process.env.OPENAI_API_KEY,
lcm: {
enabled: true,
soft_threshold: 90000, // 70% of 128k (async compaction)
hard_threshold: 115000, // 90% of 128k (blocking compaction)
compaction_block_size: 10,
summary_target_tokens: 500,
episodes: {
max_episode_tokens: 2000,
max_episode_messages: 20,
auto_compact_after_close: true,
},
store_backend: {
type: 'sqlite',
path: './data/session.db',
},
},
});
The context control loop has three zones:
| Zone | Condition | Behavior |
|---|---|---|
| Green | tokens < soft_threshold | Zero-cost continuity — no overhead |
| Yellow | soft ≤ tokens < hard | Async compaction between turns |
| Red | tokens ≥ hard_threshold | Blocking compaction before LLM call |
Episodic Memory
Episodes group related messages into coherent interaction units for compression and retrieval.
// Episodes are configured via the lcm.episodes block
const rlm = new RLM('gpt-4o', {
lcm: {
enabled: true,
episodes: {
max_episode_tokens: 2000, // Auto-rotate when exceeded
max_episode_messages: 20, // Auto-rotate when exceeded
auto_compact_after_close: true, // Generate summary on close
},
},
});
Episode lifecycle: active → compacted (has summary) → archived. Budget-based retrieval selects episodes that fit within the token budget, always including the active episode.
BPE Tokenizer
RLM uses model-specific BPE tokenization via tiktoken-go, automatically selected during engine creation:
| Model Family | Encoding | Examples |
|---|---|---|
| o200k_base | GPT-4o, O1, O3 | gpt-4o, gpt-4o-mini, o1, o3-mini |
| cl100k_base | GPT-4, GPT-3.5, Claude | gpt-4, gpt-3.5-turbo, claude-3-opus |
Token counting is cached with xxhash-keyed sync.Map (10K entries). Falls back to a ~3.5 chars/token heuristic when BPE encoding is unavailable.
Five-Level Summarization
When context exceeds thresholds, LCM escalates through five compression levels. Level 5 is deterministic — guaranteed convergence with no LLM calls:
| Level | Strategy | LLM? | Description |
|---|---|---|---|
| 1 | Normal | Yes | LLM summarize with detail preservation |
| 2 | Aggressive | Yes | LLM summarize as bullet points, target T/2 |
| 3 | TF-IDF | No | Extractive compression via sentence scoring |
| 4 | TextRank | No | Graph-based PageRank sentence ranking |
| 5 | Truncate | No | Keep 2/3 start + 1/3 end, deterministic |
LLM-Map & Agentic-Map
LLM-Map processes items in parallel with schema validation per item:
result, err := engine.LLMMap(rlm.LLMMapConfig{
InputPath: "data/items.jsonl",
OutputPath: "data/results.jsonl",
Prompt: "Classify this item: {{item}}",
OutputSchema: &rlm.JSONSchema{Type: "object", Properties: map[string]*rlm.JSONSchema{
"category": {Type: "string"},
}},
Concurrency: 16,
})
Agentic-Map spawns full sub-agent RLM sessions per item with tool access:
result, err := engine.AgenticMap(rlm.AgenticMapConfig{
InputPath: "data/repos.jsonl",
OutputPath: "data/analyses.jsonl",
Prompt: "Analyze this repository: {{item}}",
Concurrency: 4,
ReadOnly: true,
})
Task Delegation
The infinite delegation guard prevents unbounded recursion by requiring sub-agents to declare scope reduction:
result, stats, err := engine.DelegateTask(rlm.DelegationRequest{
Prompt: "Parse the config files",
DelegatedScope: "Parse config/ directory files",
KeptWork: "Validate and apply extracted settings",
})
If KeptWork is trivial (e.g., "none", "waiting"), the delegation is rejected. Root agents (depth 0), read-only agents, and parallel decomposition are exempt.
SQLite Persistence
LCM supports two storage backends:
| Backend | Config | Use Case |
|---|---|---|
| Memory | type: 'memory' | Default, zero dependencies, ephemeral |
| SQLite | type: 'sqlite' | Persistent, FTS5 search, WAL mode, crash recovery |
const rlm = new RLM('gpt-4o', {
lcm: {
enabled: true,
store_backend: {
type: 'sqlite',
path: './data/session.db', // or ':memory:' for in-memory SQLite
},
},
});
SQLite features: WAL mode for concurrent reads, FTS5 virtual tables for full-text message search, indexed lookups by ID/role/timestamp, transactional writes for crash recovery.
LLM Providers
The Go binary uses an OpenAI-compatible chat completion API. Any provider that supports the /chat/completions schema works:
| Provider | Configuration |
|---|---|
| OpenAI | Default. Just set api_key. |
| Azure OpenAI | api_base + api_key + api_version |
| Bedrock | Via LiteLLM proxy: api_base pointing to proxy |
| Anthropic | Via LiteLLM proxy |
| Ollama | api_base: 'http://localhost:11434/v1' |
| vLLM | api_base pointing to vLLM server |
| Any OpenAI-compatible | api_base + api_key |
Docker
For Linux containers, you have three supported paths: use the published platform package, point to a custom binary, or build from source in a multi-stage image.
Option 1: Use the published Linux binary package
On linux-x64 and linux-arm64, npm ci --omit=dev installs the matching @recursive-llm/linux-* binary automatically. No Go toolchain or RLM_GO_BINARY override is required.
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
ENV NODE_ENV=production
CMD ["node", "your-app.js"]
Option 2: Copy or mount a custom binary
Use this when you build the Go binary elsewhere and want to pin a specific binary path inside the container.
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev --ignore-scripts
COPY . .
COPY ./bin/rlm-go /app/bin/rlm-go
RUN chmod +x /app/bin/rlm-go
ENV NODE_ENV=production
ENV RLM_GO_BINARY=/app/bin/rlm-go
CMD ["node", "your-app.js"]
Option 3: Build from source in a multi-stage image
Use this for unsupported targets or when you want a custom-compiled binary.
# Build Go binary
FROM golang:1.25-alpine AS go-builder
WORKDIR /build
COPY go/go.mod go/go.sum ./
RUN go mod download
COPY go/ ./
RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o rlm-go ./cmd/rlm
# Build Node.js
FROM node:22-alpine AS node-builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev --ignore-scripts
# Runtime
FROM node:22-alpine
WORKDIR /app
COPY --from=node-builder /app/node_modules ./node_modules
COPY --from=go-builder /build/rlm-go ./bin/rlm-go
RUN chmod +x ./bin/rlm-go
COPY . .
ENV RLM_GO_BINARY=/app/bin/rlm-go
ENV NODE_ENV=production
CMD ["node", "your-app.js"]
Go Module
Import the Go implementation directly in Go projects:
go get github.com/howlerops/recursive-llm-ts/go
See the Go examples for usage.
Environment Variables
OPENAI_API_KEY must be set (or passed via config.api_key) for the LLM to work. All other variables are optional.
| Variable | Required | Description |
|---|---|---|
OPENAI_API_KEY |
Required | API key for the LLM provider |
AZURE_API_KEY |
Optional | Azure OpenAI API key |
RLM_GO_BINARY |
Optional | Custom path to Go binary |
RLM_DEBUG |
Optional | Enable debug mode (1) |
OTEL_EXPORTER_OTLP_ENDPOINT |
Optional | OTLP endpoint (auto-enables OTEL) |
LANGFUSE_PUBLIC_KEY |
Optional | Langfuse public key |
LANGFUSE_SECRET_KEY |
Optional | Langfuse secret key |
LANGFUSE_HOST |
Optional | Langfuse API host |
AWS_ACCESS_KEY_ID |
Optional | AWS access key for S3 |
AWS_SECRET_ACCESS_KEY |
Optional | AWS secret key for S3 |
AWS_SESSION_TOKEN |
Optional | AWS session token |
AWS_REGION |
Optional | AWS region for S3 |
AWS_DEFAULT_REGION |
Optional | Fallback AWS region |
Binary Resolution
The Go bridge looks for the binary in this order:
RLMConfig.go_binary_pathparameterRLM_GO_BINARYenvironment variable- Matching
@recursive-llm/<platform>package ./bin/rlm-go(npm package location)./go/rlm-go(development location)
Troubleshooting
Go binary not found
If you see "Go binary not found" errors:
- On supported targets, confirm the matching
@recursive-llm/<platform>package installed successfully - Ensure Go 1.25+ is installed:
go version - Manually build:
cd go && go build -o ../bin/rlm-go ./cmd/rlm - Or set
RLM_GO_BINARYto a custom or downloaded binary path
S3 authentication errors
The S3StorageError class provides actionable remediation messages:
- AUTH_FAILED: Check credentials config or
AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY - ACCESS_DENIED: Verify IAM permissions for the bucket
- BUCKET_NOT_FOUND: Verify the bucket name and region
- REGION_MISMATCH: The bucket is in a different region
Timeout errors
For very large documents, increase the timeout:
const rlm = new RLM('gpt-4o-mini', {
max_iterations: 50,
timeout: 300, // 5 min for LLM calls
pythonia_timeout: 600000, // 10 min for bridge
});