1 of 12

Akrasia

Introduction

Welcome to Liz, a lightweight framework for building AI agents.

What is Liz?

Liz is a lightweight framework for building AI agents, inspired by Eliza from AI16Z but rebuilt with a strong focus on developer experience and control. Unlike other agent frameworks that abstract away the complexities, Liz provides direct access to prompts and model interactions, giving developers the power to build exactly what they need.

Documentation

Overview

What is Liz?

Key Motivations

Direct LLM Control: Full access to prompts and model interactions
Zero Magic: Minimal abstractions for maximum understanding
Ultimate Flexibility: Build exactly what you need, how you need it

Core Philosophy

Liz follows an Express-style architecture, using middleware chains for processing agent interactions. This approach provides a clear, linear flow that developers are already familiar with, making it easy to understand and extend.

We believe the best way to build AI agents is to work closely with the prompts and build a set of composable units that can be strung together to make powerful agentic loops. Our approach is informed by Anthropic's research on constructing reliable AI systems.

Key Features

Agent-based Architecture

Build agents with distinct personalities, capabilities, and interaction styles using a flexible character system.

Composable Middleware

Process interactions through customizable middleware chains for validation, memory loading, context wrapping, and more.

Memory System

Built-in Prisma-based memory system for storing and retrieving agent interactions with flexible querying.

LLM Integration

Support for multiple LLM providers through a unified interface, with structured outputs and streaming capabilities.

When to Use Liz?

Liz is perfect for developers who:

Need fine-grained control over prompt engineering and LLM interactions
Want to build minimal or highly specialized AI agents
Prefer explicit, understandable code over magical abstractions

Quick Start

Installation

Environment Setup

Create a .env file in your project root with the following variables:

Initialize Database

Create Your First Agent

Create a new file src/agents/assistant.ts:

Set Up Express Server

Create src/server.ts to handle agent interactions:

Run the Server

Test Your Agent

Send a test request to your agent:

Architecture

For detailed visual representations of the system architecture, see .

Express-Inspired Flow

Liz uses an Express-style middleware architecture where each request flows through a series of middleware functions. This approach provides a clear, predictable processing pipeline that's easy to understand and extend.

System Diagrams

Overall System Architecture

Middleware Flow

Memory System

Agent Interaction Flow

Agents

Character Definition

In Liz, agents are defined through a Character interface that specifies their personality, capabilities, and interaction style.

Adding Routes

Memory System

Prisma Setup

Liz uses Prisma as its ORM, supporting both SQLite and PostgreSQL databases. The schema defines the structure for storing memories and tweets.

LLM Integration

LLMUtils Overview

The LLMUtils class in src/utils/llm provides a unified interface for interacting with different LLM providers, supporting both OpenAI and OpenRouter APIs.

Twitter Integration

Configuration

Configure your Twitter client using environment variables and the twitterConfigSchema:

Setting Up the Client

Initialize and start the Twitter client with your agent:

Automated Posting

The client can automatically generate and post tweets at regular intervals:

Mention Monitoring

Monitor and respond to mentions automatically:

Thread Management

Handle tweet threads and conversations:

Memory Integration

Store tweets and maintain conversation context:

Best Practices

Rate Limiting

Use RequestQueue for API calls
Add delays between tweets
Handle API errors gracefully
Implement exponential backoff

Testing

Use dryRun mode for testing
Monitor tweet content
Test thread splitting
Verify mention handling

Examples

CLI-based Agent

Create a simple command-line interface for interacting with your agent:

Twitter Bot

Create a Twitter bot that posts regularly and responds to mentions:

Memory-Aware Agent

Create an agent that uses conversation history for context:

Custom Middleware

Create custom middleware for specialized processing:

FAQ

Installation & Setup

What are the minimum requirements?

Liz requires Node.js 18+ and either SQLite or PostgreSQL for the database. For development, SQLite is recommended as it requires no additional setup. For production, PostgreSQL is recommended for better scalability.

Why am I getting environment variable errors?

Make sure you've copied .env.example to .env and filled in all required variables:

DATABASE_URL for your database connection
OPENAI_API_KEY for OpenAI API access
OPENROUTER_API_KEY for OpenRouter API access

How do I switch from SQLite to PostgreSQL?

Update your DATABASE_URL in .env and modify prisma/schema.prisma:

Then run prisma migrate to update your database:

LLM Integration

Can I use different LLM providers?

Yes, Liz supports both OpenAI and OpenRouter APIs. OpenRouter gives you access to models from Anthropic, Google, and others. You can specify the model when calling LLMUtils methods:

How do I handle rate limits?

Implement exponential backoff and retry logic in your routes:

Performance

How can I optimize memory usage?

Several strategies can help manage memory usage:

Limit the number of memories loaded per request
Implement memory pruning for old conversations
Use database indexing effectively

How do I handle high traffic?

For high-traffic applications:

Use PostgreSQL instead of SQLite
Implement request queuing
Cache common responses
Use load balancing with multiple instances

Twitter Integration

Why is my Twitter bot not working?

Common Twitter integration issues:

Incorrect credentials in environment variables
Missing 2FA secret for accounts with 2FA enabled
Rate limiting from too frequent posting

Use dryRun mode to test your bot without posting:

Contributing

How can I contribute to Liz?

We welcome contributions! Here's how to get started:

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable

Please follow our coding standards and include clear commit messages.

Overview

What is Liz?

Key Motivations

Direct LLM Control: Full access to prompts and model interactions
Zero Magic: Minimal abstractions for maximum understanding
Ultimate Flexibility: Build exactly what you need, how you need it

Core Philosophy

Key Features

Agent-based Architecture

Build agents with distinct personalities, capabilities, and interaction styles using a flexible character system.

Composable Middleware

Process interactions through customizable middleware chains for validation, memory loading, context wrapping, and more.

Memory System

Built-in Prisma-based memory system for storing and retrieving agent interactions with flexible querying.

LLM Integration

Support for multiple LLM providers through a unified interface, with structured outputs and streaming capabilities.

When to Use Liz?

Liz is perfect for developers who:

Need fine-grained control over prompt engineering and LLM interactions
Want to build minimal or highly specialized AI agents
Prefer explicit, understandable code over magical abstractions

FAQ

Installation & Setup

What are the minimum requirements?

Why am I getting environment variable errors?

Make sure you've copied .env.example to .env and filled in all required variables:

DATABASE_URL for your database connection
OPENAI_API_KEY for OpenAI API access
OPENROUTER_API_KEY for OpenRouter API access

How do I switch from SQLite to PostgreSQL?

Update your DATABASE_URL in .env and modify prisma/schema.prisma:

Then run prisma migrate to update your database:

LLM Integration

Can I use different LLM providers?

Yes, Liz supports both OpenAI and OpenRouter APIs. OpenRouter gives you access to models from Anthropic, Google, and others. You can specify the model when calling LLMUtils methods:

How do I handle rate limits?

Implement exponential backoff and retry logic in your routes:

Performance

How can I optimize memory usage?

Several strategies can help manage memory usage:

Limit the number of memories loaded per request
Implement memory pruning for old conversations
Use database indexing effectively

How do I handle high traffic?

For high-traffic applications:

Use PostgreSQL instead of SQLite
Implement request queuing
Cache common responses
Use load balancing with multiple instances

Twitter Integration

Why is my Twitter bot not working?

Common Twitter integration issues:

Incorrect credentials in environment variables
Missing 2FA secret for accounts with 2FA enabled
Rate limiting from too frequent posting

Use dryRun mode to test your bot without posting:

Contributing

How can I contribute to Liz?

We welcome contributions! Here's how to get started:

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable

Please follow our coding standards and include clear commit messages.

Examples

CLI-based Agent

Create a simple command-line interface for interacting with your agent:

// src/example/cli.ts
import express from "express";
import { AgentFramework } from "../framework";
import { standardMiddleware } from "../middleware";
import { Character, InputSource, InputType } from "../types";
import { BaseAgent } from "../agent";
import readline from "readline";

// Define your agent
const assistant: Character = {
	name: "Assistant",
	agentId: "cli_assistant",
	system: "You are a helpful CLI assistant.",
	bio: ["A command-line AI assistant"],
	lore: ["Created to help users through the terminal"],
	messageExamples: [
		[
			{ user: "user1", content: { text: "Hello!" } },
			{ user: "Assistant", content: { text: "Hi! How can I help?" } },
		],
	],
	postExamples: [],
	topics: ["general help", "cli", "terminal"],
	style: {
		all: ["helpful", "concise"],
		chat: ["friendly"],
		post: ["clear"],
	},
	adjectives: ["helpful", "efficient"],
	routes: [],
};

// Initialize framework
const app = express();
app.use(express.json());
const framework = new AgentFramework();
standardMiddleware.forEach((middleware) => framework.use(middleware));

// Create agent instance
const agent = new BaseAgent(assistant);

// Add conversation route
agent.addRoute({
	name: "conversation",
	description: "Handle natural conversation",
	handler: async (context, req, res) => {
		const response = await llmUtils.getTextFromLLM(
			context,
			"anthropic/claude-3-sonnet"
		);
		await res.send(response);
	},
});

// Set up CLI interface
async function startCLI() {
	const rl = readline.createInterface({
		input: process.stdin,
		output: process.stdout,
	});

	console.log("\nCLI Assistant");
	console.log("=============");

	async function prompt() {
		rl.question("\nYou: ", async (text) => {
			try {
				const response = await framework.process(
					{
						source: InputSource.NETWORK,
						userId: "cli_user",
						agentId: agent.getAgentId(),
						roomId: "cli_session",
						type: InputType.TEXT,
						text: text,
					},
					agent
				);

				console.log("\nAssistant:", response);
				prompt();
			} catch (error) {
				console.error("\nError:", error);
				prompt();
			}
		});
	}

	prompt();
}

// Start server and CLI
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
	console.log(`Server running on http://localhost:${PORT}`);
	startCLI();
});

Twitter Bot

Create a Twitter bot that posts regularly and responds to mentions:

Memory-Aware Agent

Create an agent that uses conversation history for context:

Custom Middleware

Create custom middleware for specialized processing:

// src/example/cli.ts
import express from "express";
import { AgentFramework } from "../framework";
import { standardMiddleware } from "../middleware";
import { Character, InputSource, InputType } from "../types";
import { BaseAgent } from "../agent";
import readline from "readline";

// Define your agent
const assistant: Character = {
	name: "Assistant",
	agentId: "cli_assistant",
	system: "You are a helpful CLI assistant.",
	bio: ["A command-line AI assistant"],
	lore: ["Created to help users through the terminal"],
	messageExamples: [
		[
			{ user: "user1", content: { text: "Hello!" } },
			{ user: "Assistant", content: { text: "Hi! How can I help?" } },
		],
	],
	postExamples: [],
	topics: ["general help", "cli", "terminal"],
	style: {
		all: ["helpful", "concise"],
		chat: ["friendly"],
		post: ["clear"],
	},
	adjectives: ["helpful", "efficient"],
	routes: [],
};

// Initialize framework
const app = express();
app.use(express.json());
const framework = new AgentFramework();
standardMiddleware.forEach((middleware) => framework.use(middleware));

// Create agent instance
const agent = new BaseAgent(assistant);

// Add conversation route
agent.addRoute({
	name: "conversation",
	description: "Handle natural conversation",
	handler: async (context, req, res) => {
		const response = await llmUtils.getTextFromLLM(
			context,
			"anthropic/claude-3-sonnet"
		);
		await res.send(response);
	},
});

// Set up CLI interface
async function startCLI() {
	const rl = readline.createInterface({
		input: process.stdin,
		output: process.stdout,
	});

	console.log("\nCLI Assistant");
	console.log("=============");

	async function prompt() {
		rl.question("\nYou: ", async (text) => {
			try {
				const response = await framework.process(
					{
						source: InputSource.NETWORK,
						userId: "cli_user",
						agentId: agent.getAgentId(),
						roomId: "cli_session",
						type: InputType.TEXT,
						text: text,
					},
					agent
				);

				console.log("\nAssistant:", response);
				prompt();
			} catch (error) {
				console.error("\nError:", error);
				prompt();
			}
		});
	}

	prompt();
}

// Start server and CLI
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
	console.log(`Server running on http://localhost:${PORT}`);
	startCLI();
});

// src/example/memory-agent.ts
import { AgentFramework } from "../framework";
import { standardMiddleware } from "../middleware";
import { Character, InputSource, InputType } from "../types";
import { BaseAgent } from "../agent";
import { prisma } from "../utils/db";

// Define memory-aware agent
const memoryAgent: Character = {
	name: "Mentor",
	agentId: "mentor_agent",
	system:
		"You are a mentor who remembers past conversations to provide personalized guidance.",
	bio: ["An AI mentor with perfect memory"],
	lore: ["Uses conversation history to give contextual advice"],
	messageExamples: [],
	postExamples: [],
	topics: ["mentoring", "personal growth"],
	style: {
		all: ["personalized", "thoughtful"],
		chat: ["empathetic"],
		post: ["reflective"],
	},
	adjectives: ["understanding", "wise"],
	routes: [],
};

const agent = new BaseAgent(memoryAgent);

// Add conversation route with memory context
agent.addRoute({
	name: "conversation",
	description: "Handle conversation with memory context",
	handler: async (context, req, res) => {
		// Get recent memories for this user
		const memories = await prisma.memory.findMany({
			where: {
				userId: req.input.userId,
				agentId: req.input.agentId,
			},
			orderBy: {
				createdAt: "desc",
			},
			take: 10,
		});

		// Format memories for context
		const memoryContext = memories
			.map((m) => {
				const content = JSON.parse(m.content);
				return `[${m.createdAt}] ${content.text}`;
			})
			.join("\n");

		// Add memory context to prompt
		const promptWithMemory = `
Previous interactions:
${memoryContext}

Current conversation:
${context}`;

		const response = await llmUtils.getTextFromLLM(
			promptWithMemory,
			"anthropic/claude-3-sonnet"
		);

		// Store response in memory
		await prisma.memory.create({
			data: {
				userId: req.input.userId,
				agentId: req.input.agentId,
				roomId: req.input.roomId,
				type: "response",
				generator: "llm",
				content: JSON.stringify({ text: response }),
			},
		});

		await res.send(response);
	},
});

// Initialize framework
const framework = new AgentFramework();
standardMiddleware.forEach((middleware) => framework.use(middleware));

// Example usage
async function chat(text: string) {
	return framework.process(
		{
			source: InputSource.NETWORK,
			userId: "example_user",
			agentId: agent.getAgentId(),
			roomId: "example_room",
			type: InputType.TEXT,
			text,
		},
		agent
	);
}

// src/example/memory-agent.ts
import { AgentFramework } from "../framework";
import { standardMiddleware } from "../middleware";
import { Character, InputSource, InputType } from "../types";
import { BaseAgent } from "../agent";
import { prisma } from "../utils/db";

// Define memory-aware agent
const memoryAgent: Character = {
	name: "Mentor",
	agentId: "mentor_agent",
	system:
		"You are a mentor who remembers past conversations to provide personalized guidance.",
	bio: ["An AI mentor with perfect memory"],
	lore: ["Uses conversation history to give contextual advice"],
	messageExamples: [],
	postExamples: [],
	topics: ["mentoring", "personal growth"],
	style: {
		all: ["personalized", "thoughtful"],
		chat: ["empathetic"],
		post: ["reflective"],
	},
	adjectives: ["understanding", "wise"],
	routes: [],
};

const agent = new BaseAgent(memoryAgent);

// Add conversation route with memory context
agent.addRoute({
	name: "conversation",
	description: "Handle conversation with memory context",
	handler: async (context, req, res) => {
		// Get recent memories for this user
		const memories = await prisma.memory.findMany({
			where: {
				userId: req.input.userId,
				agentId: req.input.agentId,
			},
			orderBy: {
				createdAt: "desc",
			},
			take: 10,
		});

		// Format memories for context
		const memoryContext = memories
			.map((m) => {
				const content = JSON.parse(m.content);
				return `[${m.createdAt}] ${content.text}`;
			})
			.join("\n");

		// Add memory context to prompt
		const promptWithMemory = `
Previous interactions:
${memoryContext}

Current conversation:
${context}`;

		const response = await llmUtils.getTextFromLLM(
			promptWithMemory,
			"anthropic/claude-3-sonnet"
		);

		// Store response in memory
		await prisma.memory.create({
			data: {
				userId: req.input.userId,
				agentId: req.input.agentId,
				roomId: req.input.roomId,
				type: "response",
				generator: "llm",
				content: JSON.stringify({ text: response }),
			},
		});

		await res.send(response);
	},
});

// Initialize framework
const framework = new AgentFramework();
standardMiddleware.forEach((middleware) => framework.use(middleware));

// Example usage
async function chat(text: string) {
	return framework.process(
		{
			source: InputSource.NETWORK,
			userId: "example_user",
			agentId: agent.getAgentId(),
			roomId: "example_room",
			type: InputType.TEXT,
			text,
		},
		agent
	);
}

Twitter Integration

Configuration

Configure your Twitter client using environment variables and the twitterConfigSchema:

// Environment variables
TWITTER_USERNAME="your-username"
TWITTER_PASSWORD="your-password"
TWITTER_EMAIL="your-email"
TWITTER_2FA_SECRET="optional-2fa-secret"
TWITTER_POST_INTERVAL_HOURS=4
TWITTER_POLLING_INTERVAL=5 # minutes
TWITTER_DRY_RUN=true # For testing

// Configuration schema
const twitterConfigSchema = z.object({
  username: z.string().min(1, "Twitter username is required"),
  password: z.string().min(1, "Twitter password is required"),
  email: z.string().email("Valid email is required"),
  twoFactorSecret: z.string().optional(),
  retryLimit: z.number().int().min(1).default(5),
  postIntervalHours: z.number().int().min(1).default(4),
  enableActions: z.boolean().default(false)
});

Setting Up the Client

Initialize and start the Twitter client with your agent:

Automated Posting

The client can automatically generate and post tweets at regular intervals:

Mention Monitoring

Monitor and respond to mentions automatically:

Thread Management

Handle tweet threads and conversations:

Memory Integration

Store tweets and maintain conversation context:

Best Practices

Rate Limiting

Use RequestQueue for API calls
Add delays between tweets
Handle API errors gracefully
Implement exponential backoff

Testing

Use dryRun mode for testing
Monitor tweet content
Test thread splitting
Verify mention handling

Akrasia

Introduction

hashtagWhat is Liz?

Documentation

Overview

hashtagWhat is Liz?

hashtagKey Motivations

hashtagCore Philosophy

hashtagKey Features

hashtagAgent-based Architecture

hashtagComposable Middleware

hashtagMemory System

hashtagLLM Integration

hashtagWhen to Use Liz?

Quick Start

hashtagInstallation

hashtagEnvironment Setup

hashtagInitialize Database

hashtagCreate Your First Agent

hashtagSet Up Express Server

hashtagRun the Server

hashtagTest Your Agent

Architecture

hashtagExpress-Inspired Flow

System Diagrams

hashtagOverall System Architecture

hashtagMiddleware Flow

hashtagMemory System

hashtagAgent Interaction Flow

Agents

hashtagCharacter Definition

hashtagAdding Routes

Memory System

hashtagPrisma Setup

hashtag

LLM Integration

hashtagLLMUtils Overview

hashtag

Twitter Integration

hashtagConfiguration

hashtagSetting Up the Client

hashtagAutomated Posting

hashtagMention Monitoring

hashtagThread Management

hashtagMemory Integration

hashtagBest Practices

hashtagRate Limiting

hashtagTesting

Examples

hashtagCLI-based Agent

hashtagTwitter Bot

hashtagMemory-Aware Agent

hashtagCustom Middleware

FAQ

hashtagInstallation & Setup

hashtagWhat are the minimum requirements?

hashtagWhy am I getting environment variable errors?

hashtagHow do I switch from SQLite to PostgreSQL?

hashtagLLM Integration

hashtagCan I use different LLM providers?

hashtagHow do I handle rate limits?

hashtagPerformance

hashtagHow can I optimize memory usage?

hashtagHow do I handle high traffic?

hashtagTwitter Integration

hashtagWhy is my Twitter bot not working?

hashtagContributing

hashtagHow can I contribute to Liz?

Overview

hashtagWhat is Liz?

hashtagKey Motivations

hashtagCore Philosophy

hashtagKey Features

hashtagAgent-based Architecture

hashtagComposable Middleware

hashtagMemory System

hashtagLLM Integration

hashtagWhen to Use Liz?

System Diagrams

hashtagOverall System Architecture

What is Liz?

What is Liz?

Key Motivations

Core Philosophy

Key Features

Agent-based Architecture

Composable Middleware

Memory System

LLM Integration

When to Use Liz?

Installation

Environment Setup

Initialize Database

Create Your First Agent

Set Up Express Server

Run the Server

Test Your Agent

Express-Inspired Flow

Overall System Architecture

Middleware Flow

Memory System

Agent Interaction Flow

Character Definition

Adding Routes

Prisma Setup

LLMUtils Overview

Configuration

Setting Up the Client

Automated Posting

Mention Monitoring

Thread Management

Memory Integration

Best Practices

Rate Limiting

Testing

CLI-based Agent

Twitter Bot

Memory-Aware Agent

Custom Middleware

Installation & Setup

What are the minimum requirements?

Why am I getting environment variable errors?

How do I switch from SQLite to PostgreSQL?

LLM Integration

Can I use different LLM providers?

How do I handle rate limits?

Performance

How can I optimize memory usage?

How do I handle high traffic?

Twitter Integration

Why is my Twitter bot not working?

Contributing

How can I contribute to Liz?

What is Liz?

Key Motivations

Core Philosophy

Key Features

Agent-based Architecture

Composable Middleware

Memory System

LLM Integration

When to Use Liz?

Overall System Architecture

Middleware Flow

Memory System

Agent Interaction Flow

What is Liz?

Core Philosophy

Key Features

Agent-based Architecture

Composable Middleware

Memory System

LLM Integration

When to Use Liz?

Installation & Setup

What are the minimum requirements?

Why am I getting environment variable errors?

How do I switch from SQLite to PostgreSQL?

LLM Integration

Can I use different LLM providers?