@fractal-synapse/agent-history

Storage-abstracted history plugin for Fractal Synapse agents. This plugin automatically saves and manages conversation history using any storage backend that implements the PluginStorageInterface.

Installation

npm install @fractal-synapse/agent-history

You'll also need a storage implementation. The most common one is:

npm install @fractal-synapse/storage-fs

Basic Usage

import { Agent, AgentDefinition } from '@fractal-synapse/agent-core';
import { AgentHistoryPlugin, AgentHistoryConfig } from '@fractal-synapse/agent-history';
import { StorageFsPlugin } from '@fractal-synapse/storage-fs';

// Create a storage instance
const storage = new StorageFsPlugin({ appName: 'my-app' });

// Create the history plugin with configuration
const config: AgentHistoryConfig = {
  storage,
  // logger is optional - will use default console logger if not provided
};

const historyPlugin = new AgentHistoryPlugin(config);

// Create and configure your agent
const agentDefinition = new AgentDefinition(
  'my-agent',
  'My Assistant',
  'You are a helpful assistant',
  [],
  'openai-gpt-4o'
);

const agent = new Agent({ agentDefinition });

// Add the history plugin
agent.addPlugin(historyPlugin);

Features

• Automatic Saving: Conversations are automatically saved after each user message, assistant response, and tool usage
• Storage Abstraction: Works with any storage backend through PluginStorageInterface
• Conversation Management: Load, list, and delete conversations programmatically
• Error Resilient: Handles storage errors gracefully without crashing your agent

API

Load a Conversation

const conversation = await historyPlugin.loadConversation('agent-id-123');
if (conversation) {
  console.log('Found conversation with', conversation.messages.length, 'messages');
}

List All Conversations

const conversationIds = await historyPlugin.listConversations();
console.log('Found conversations:', conversationIds);

Delete a Conversation

const deleted = await historyPlugin.deleteConversation('agent-id-123');
console.log('Conversation deleted:', deleted);

Get Storage Directory

const storageDir = historyPlugin.getStorageDirectory();
console.log('Conversations stored in:', storageDir);

Storage Backends

This plugin works with any storage implementation that implements PluginStorageInterface:

Filesystem Storage (Default)

import { StorageFsPlugin } from '@fractal-synapse/storage-fs';
import { AgentHistoryConfig } from '@fractal-synapse/agent-history';

const storage = new StorageFsPlugin({ appName: 'my-app' });
const config: AgentHistoryConfig = { storage };
const historyPlugin = new AgentHistoryPlugin(config);

With Custom Logger

import { WinstonLoggerPlugin } from '@fractal-synapse/winston-logger';
import { StorageFsPlugin } from '@fractal-synapse/storage-fs';
import { AgentHistoryConfig } from '@fractal-synapse/agent-history';

const storage = new StorageFsPlugin({ appName: 'my-app' });
const logger = new WinstonLoggerPlugin({ logToConsole: true });

const config: AgentHistoryConfig = {
  storage,
  logger
};

const historyPlugin = new AgentHistoryPlugin(config);

Custom Storage

You can implement your own storage backend:

import { PluginStorageInterface } from '@fractal-synapse/agent-core';

class MyCustomStorage implements PluginStorageInterface {
  async saveFile(filePath: string, data: string | Buffer): Promise<void> {
    // Your custom save logic (database, cloud storage, etc.)
  }
  
  async loadFile(filePath: string): Promise<string | Buffer | null> {
    // Your custom load logic
  }
  
  async deleteFile(filePath: string): Promise<boolean> {
    // Your custom delete logic
  }
  
  async exists(filePath: string): Promise<boolean> {
    // Your custom exists check
  }
  
  async listFiles(dirPath?: string): Promise<string[]> {
    // Your custom file listing
  }
}

const storage = new MyCustomStorage();
const config: AgentHistoryConfig = { storage };
const historyPlugin = new AgentHistoryPlugin(config);

File Structure

Conversations are stored as JSON files in the following structure:

storage-root/
├── conversations/
│   ├── agent-2023-12-01-123.json
│   ├── agent-2023-12-01-456.json
│   └── agent-2023-12-01-789.json

Each conversation file contains:

{
  "id": "agent-2023-12-01-123",
  "messages": [
    {
      "id": "msg-1",
      "role": "user",
      "parts": [{ "type": "text", "text": "Hello!" }]
    },
    {
      "id": "msg-2",
      "role": "assistant",
      "parts": [{ "type": "text", "text": "Hi there!" }]
    }
  ]
}

Migration from v0.x

If you're upgrading from an earlier version, note the breaking changes:

Before (v0.x):

const storage = new StorageFsPlugin('my-app');
const historyPlugin = new AgentHistoryPlugin(storage);

After (v1.x):

const storage = new StorageFsPlugin({ appName: 'my-app' });
const config: AgentHistoryConfig = { storage };
const historyPlugin = new AgentHistoryPlugin(config);

Benefits of the new pattern:

• Improved testability with dependency injection
• Optional logger configuration for better debugging
• More flexible configuration options
• Consistent with other Fractal Synapse plugins

License

Part of the Fractal Synapse project.