@matteuccimarco/slim-langchain

LangChain integration with SLIM compression. Reduce token usage and storage by 40% for chat histories and memory.

Installation

npm install @matteuccimarco/slim-langchain

Quick Start

Chat Message History

import { SlimChatMessageHistory } from '@matteuccimarco/slim-langchain';

const history = new SlimChatMessageHistory();

// Add messages
history.addUserMessage("What's the weather like?");
history.addAIMessage("It's sunny and 72°F today!");
history.addUserMessage("Should I bring an umbrella?");
history.addAIMessage("No, you won't need one. Clear skies all day.");

// Export as SLIM (40% smaller than JSON)
const slim = history.toSlim();
console.log(slim);
// {sessionId:default,messages:|4|role,content|human,What's the weather like?|ai,It's sunny and 72°F today!|...}

// Get compression stats
const stats = history.getStats();
console.log(`Saved ${stats.savings}% - ${stats.jsonSize} bytes → ${stats.slimSize} bytes`);

// Restore from SLIM
const restored = SlimChatMessageHistory.fromSlim(slim);

Conversation Memory

import { SlimConversationMemory } from '@matteuccimarco/slim-langchain';

const memory = new SlimConversationMemory();

// Save conversation turns
memory.saveContext(
  { input: "What's the capital of France?" },
  { output: "The capital of France is Paris." }
);

memory.saveContext(
  { input: "What's its population?" },
  { output: "Paris has a population of about 2.2 million in the city proper." }
);

// Load for prompt
const variables = memory.loadMemoryVariables();
console.log(variables.history);
// Human: What's the capital of France?
// AI: The capital of France is Paris.
// Human: What's its population?
// AI: Paris has a population of about 2.2 million in the city proper.

// Export for storage (Redis, DB, etc.)
const slim = memory.toSlim();

Serialization Utilities

import { slimSerialize, slimDeserialize, estimateTokenSavings } from '@matteuccimarco/slim-langchain';

// Serialize any data
const data = {
  messages: [
    { role: 'user', content: 'Hello' },
    { role: 'assistant', content: 'Hi there!' },
  ],
  metadata: { model: 'gpt-4', temperature: 0.7 }
};

const slim = slimSerialize(data);
const restored = slimDeserialize(slim);

// Estimate token savings
const json = JSON.stringify(data);
const savings = estimateTokenSavings(json, slim);
console.log(`Saved ~${savings.savedTokens} tokens (${savings.savingsPercent}%)`);

Use Cases

Storage Backend (Redis, PostgreSQL)

import { SlimChatMessageHistory } from '@matteuccimarco/slim-langchain';
import Redis from 'ioredis';

const redis = new Redis();

// Save to Redis
async function saveHistory(sessionId: string, history: SlimChatMessageHistory) {
  const slim = history.toSlim();
  await redis.set(`chat:${sessionId}`, slim, 'EX', 3600);
}

// Load from Redis
async function loadHistory(sessionId: string): Promise<SlimChatMessageHistory> {
  const slim = await redis.get(`chat:${sessionId}`);
  if (!slim) return new SlimChatMessageHistory({ sessionId });
  return SlimChatMessageHistory.fromSlim(slim);
}

Reduce Context Window Usage

import { SlimConversationMemory } from '@matteuccimarco/slim-langchain';

// For long conversations, SLIM reduces the memory footprint
const memory = new SlimConversationMemory();

// After 100 messages...
const stats = memory.getStats();
// JSON: 25,000 bytes (~6,250 tokens)
// SLIM: 15,000 bytes (~3,750 tokens)
// Saved: 2,500 tokens per request!

API Reference

SlimChatMessageHistory

class SlimChatMessageHistory {
  constructor(options?: { sessionId?: string; enabled?: boolean });

  addUserMessage(content: string): void;
  addAIMessage(content: string): void;
  addSystemMessage(content: string): void;
  addFunctionMessage(content: string, name: string): void;
  addMessage(message: Message): void;

  getMessages(): Message[];
  clear(): void;
  length: number;

  toSlim(): string;
  toJSON(): string;
  getStats(): { jsonSize: number; slimSize: number; savings: number };

  static fromSlim(slim: string): SlimChatMessageHistory;
  static fromJSON(json: string): SlimChatMessageHistory;
}

SlimConversationMemory

class SlimConversationMemory {
  constructor(options?: {
    sessionId?: string;
    humanPrefix?: string;  // default: 'Human'
    aiPrefix?: string;     // default: 'AI'
    memoryKey?: string;    // default: 'history'
  });

  saveContext(inputs: { input: string }, outputs: { output: string }): void;
  loadMemoryVariables(): Record<string, string>;
  clear(): void;
  getMessages(): Message[];

  toSlim(): string;
  getStats(): { jsonSize: number; slimSize: number; savings: number };

  static fromSlim(slim: string): SlimConversationMemory;
}

Serialization Functions

function slimSerialize(data: unknown): string;
function slimDeserialize<T>(slim: string): T;
function serializeMessages(messages: Message[]): string;
function deserializeMessages(slim: string): Message[];
function estimateTokenSavings(original: string, slim: string): {
  originalTokens: number;
  slimTokens: number;
  savedTokens: number;
  savingsPercent: number;
};

Benchmarks

| Conversation Length | JSON Size | SLIM Size | Token Savings | |--------------------|-----------|-----------|---------------| | 10 messages | 2.5 KB | 1.5 KB | ~250 tokens | | 50 messages | 12.5 KB | 7.5 KB | ~1,250 tokens | | 100 messages | 25 KB | 15 KB | ~2,500 tokens |

Cost Savings Example

1M API calls/month with 100-message context

Without SLIM:
- 6,250 tokens/call × 1M = 6.25B tokens
- GPT-4 ($30/1M): $187,500/month

With SLIM (40% reduction):
- 3,750 tokens/call × 1M = 3.75B tokens
- GPT-4 ($30/1M): $112,500/month

Monthly savings: $75,000 (40%)

License

MIT