API Reference

Complete forgetless API documentation.

Basic Usage

rust

use forgetless::{Forgetless, Config, WithPriority, FileWithPriority};

let result = Forgetless::new()
    .config(Config::default().context_limit(128_000))
    .add(WithPriority::critical(&system_prompt))
    .add(&conversation)
    .add_file("research.pdf")
    .add_file("screenshot.png")
    .add_file(FileWithPriority::high("important.md"))
    .query("What are the key findings?")
    .run()
    .await?;

println!("Output: {} tokens", result.total_tokens);
println!("Compression: {:.1}x", result.stats.compression_ratio);

Config

rust

use forgetless::{Forgetless, Config};

let result = Forgetless::new()
    .config(Config::default()
        .context_limit(128_000)  // Max output tokens
        .vision_llm(true)        // LLM for image descriptions
        .context_llm(true)       // LLM for scoring/summarization
        .chunk_size(256)         // Target chunk size in tokens
        .parallel(true)          // Parallel file processing
        .cache(true))            // Embedding cache
    .add_file("diagram.png")
    .run()
    .await?;

Option	Default	Description
context_limit	128,000	Maximum output tokens
vision_llm	false	Use LLM for image descriptions
context_llm	false	Use LLM for scoring/summarization
chunk_size	512	Target chunk size in tokens
parallel	true	Enable parallel file processing
cache	true	Enable embedding cache

Priority Levels

Priority	Behavior	Use Case
critical	Always included, never dropped	System prompts, user queries
high	Preferred during selection	Recent conversation, important context
medium	Standard priority (default)	General documents, background info
low	Dropped first when over budget	Optional context, older history

rust

// Content priority
WithPriority::critical(content)  // Always kept
WithPriority::high(content)      // High preference
WithPriority::medium(content)    // Default
WithPriority::low(content)       // Dropped first

// File priority
FileWithPriority::critical(path)
FileWithPriority::high(path)
FileWithPriority::medium(path)
FileWithPriority::low(path)

Supported File Types

Type	Extensions	Processing
PDF	.pdf	Text extraction (pdftotext)
Images	.png, .jpg, .webp, .gif, .bmp	Metadata or LLM description
Code	.rs, .py, .js, .ts, .go, etc.	Function/class boundary chunking
Markdown	.md	Header-based chunking
Text	.txt	Sentence boundary chunking
Structured	.json, .yaml, .toml	Object boundary chunking

Result Structure

rust

result.content         // Optimized content string
result.total_tokens    // Output token count
result.chunks          // Vec<ScoredChunk>

result.stats.input_tokens       // Total input tokens
result.stats.output_tokens      // Total output tokens
result.stats.compression_ratio  // e.g., 14.5
result.stats.chunks_processed   // Total chunks created
result.stats.chunks_selected    // Chunks in output
result.stats.processing_time_ms // Processing time

Error Handling

rust

use forgetless::{Forgetless, Config, Error};

match Forgetless::new()
    .config(Config::default().context_limit(128_000))
    .add(content)
    .run()
    .await
{
    Ok(result) => {
        println!("Success: {} tokens", result.total_tokens);
    }
    Err(Error::TokenCountError(msg)) => {
        eprintln!("Tokenizer error: {}", msg);
    }
    Err(Error::ContextBuildError(msg)) => {
        eprintln!("Build error: {}", msg);
    }
    Err(e) => {
        eprintln!("Error: {}", e);
    }
}

HTTP Server

Optional HTTP server for non-Rust clients.

bash

# Build and run server
cargo run --features server --bin forgetless-server

# Request
curl -X POST http://localhost:8080 \
  -F 'metadata={"context_limit":128000,"query":"key findings"}' \
  -F 'file:[email protected]' \
  -F '[email protected]'