# ElizaOS Developer Update - May 29, 2025

## Core Framework

ElizaOS v2 (now referred to as 1.0.0) is set to release this week, with significant architectural improvements transforming responsive agents into intelligent agents capable of planning, coordinating, and executing complex operations across blockchains.

The v2-develop branch is considered stable enough for production use, with only minor changes expected in upcoming days:

```bash
# Clone and use the current stable branch
git clone https://github.com/elizaOS/eliza.git -b v2-develop
cd eliza
bun install
```

Key architectural enhancements include:

- **Memory System Overhaul**: Unified intelligence across channels with significant improvements to how agents retain knowledge
- **Modular GUI Architecture**: Complete redesign for better component isolation and extensibility
- **Knowledge System Migration**: Moving all knowledge functionality to plugin-knowledge (#4701, #4766), including graph view for memory visualization
- **Plugin Dependencies**: New plugin registration system to support plugin dependencies (#4789)
- **Service Registry Types**: Added service registry pattern enabling typed Services for external plugins

PR #4818 moves the message server to a self-contained database, while PR #4806 fixes critical issues with environment variable handling in deployment environments:

```javascript
// New pattern for environment variable resolution
const envVars = await findNearestEnvFile();
const mergedEnv = { ...process.env, ...envVars };
```

## New Features

### Comprehensive Media Support

PR #4750 implements complete image and video handling in the chat interface:

```javascript
// Send an image message
await runtime.sendMessage({
  content: {
    text: "Check out this image",
    attachments: [{
      type: "image",
      url: "https://example.com/image.jpg"
    }]
  }
});
```

### Real-time Log Streaming

WebSocket-based log streaming has been added with intelligent fallback to API polling (#4765):

```javascript
// Client-side log streaming implementation
const useLogStream = (enabled = true) => {
  const [logs, setLogs] = useState([]);
  
  useEffect(() => {
    if (!enabled) return;
    
    // Try WebSocket first, fall back to polling
    const ws = new WebSocket(`ws://${window.location.host}/api/logs/stream`);
    ws.onmessage = (event) => {
      const newLog = JSON.parse(event.data);
      setLogs(prev => [...prev, newLog]);
    };
    
    return () => ws.close();
  }, [enabled]);
  
  return logs;
};
```

### API Enhancements

New API endpoints have been added for room and world management:

```bash
# Create a new room for an agent
curl -X POST http://localhost:3000/api/agents/:agentId/rooms \
  -H "Content-Type: application/json" \
  -d '{"name": "New Discussion", "description": "A place to collaborate"}'

# Get all rooms for an agent
curl -X GET http://localhost:3000/api/agents/:agentId/rooms

# Delete messages
curl -X DELETE http://localhost:3000/api/agents/:agentId/memories
```

### PDF Document Support

PR #4611 adds support for extracting and uploading text content from PDF files for knowledge ingestion:

```javascript
// Example of processing a PDF document
const pdfText = await extractTextFromPDF(pdfBuffer);
const chunks = splitTextIntoChunks(pdfText);
await storeChunksAsKnowledge(chunks);
```

## Bug Fixes

Several critical bugs have been resolved in recent PRs:

### Agent Communication Issues

PR #4796 fixes a longstanding issue with the API endpoint for retrieving agent rooms:

```javascript
// Fixed room creation to properly associate agents
await createRoom({
  name: roomName,
  description: roomDescription,
  agentId: currentAgentId, // This was missing in previous implementation
  participants: [currentAgentId]
});
```

PR #4589 fixes reliability issues in message handling by ensuring callbacks are always executed:

```javascript
try {
  await handleMessage(message);
} catch (error) {
  logger.error(`Error handling message: ${error.message}`);
} finally {
  // Guarantee callback execution regardless of success or error
  onComplete();
}
```

### Database and Environment Issues

PR #4458 addresses JSON serialization in PGLite to handle invalid Unicode escape sequences:

```javascript
// Safely serialize potentially malformed JSON 
function safeJsonStringify(obj) {
  return JSON.stringify(obj, (key, value) => {
    if (typeof value === 'string') {
      // Handle malformed Unicode escape sequences
      return value.replace(/\\u[0-9a-fA-F]{0,3}([^0-9a-fA-F]|$)/g, 
        match => match.replace('\\u', '\\\\u'));
    }
    return value;
  });
}
```

PR #4529 enforces TypeScript strictness and fixes missing database functions:

```typescript
// Proper implementation of getConnection()
export async function getConnection(): Promise<Database> {
  if (!db) {
    db = await createDatabase();
  }
  return db;
}
```

## API Changes

Several significant API changes have been introduced that developers should be aware of:

### Knowledge API Migration

All knowledge functionality has been moved to plugin-knowledge (#4701), requiring code changes:

```javascript
// Old way (no longer works)
const knowledge = await runtime.getKnowledge(query);

// New way (requires plugin-knowledge)
const knowledge = await runtime.delegate(
  "plugin-knowledge", 
  "search", 
  { query }
);
```

### Database API Improvements

PR #4556 enhances database APIs with batch operations:

```javascript
// Old way (single entity)
const entity = await getEntityById(id);

// New way (optimized for batch)
const entities = await getEntitiesByIds([id1, id2, id3]);

// New batch operations
const results = await batchInsert("memories", memories);
```

### Message Handling

PR #4580 improved bootstrap plugin response parsing to support custom fields:

```javascript
// Previous implementation discarded custom fields
const reducedResponse = { text, action };

// New implementation preserves all fields
const fullResponse = { text, action, ...otherFields };
```

## Social Media Integrations

### Twitter/X Integration

Several improvements have been made to the Twitter integration:

- PR #4429 adds timeline interaction capabilities
- PR #4706 enhances tweet formatting with double newlines between sentences
- PR #4425 adds comprehensive documentation for Twitter agent setup

Configure timeline interaction with these environment variables:

```
TWITTER_TIMELINE_ENABLED=true  
TWITTER_TIMELINE_INTERVAL=300
TWITTER_TIMELINE_MAX_TWEETS=10
```

Twitter client initialization issues (#4777) have been resolved, and the plugin has been moved to a dedicated repository at [elizaos-plugins/plugin-twitter](https://github.com/elizaos-plugins/plugin-twitter).

### Discord Integration

The Discord plugin has been moved to a dedicated repository at [elizaos-plugins/plugin-discord](https://github.com/elizaos-plugins/plugin-discord) with several improvements:

- PR #4665 adds channel filtering capability:
```
DISCORD_CHANNEL_IDS=123456789,987654321
```
- PR #4450 fixes Discord service unregistration timeouts

## Model Provider Updates

### OpenAI

PR #4421 extends the OpenAI plugin to support custom embedding endpoints:

```
OPENAI_API_KEY=your-api-key
OPENAI_EMBED_API_BASE_URL=https://custom-embed-endpoint.com/v1
```

PR #4438 adds comprehensive usage tracking for embeddings and image descriptions:

```javascript
// Usage events are now emitted for all model types
runtime.on("model.used", (usageData) => {
  const { modelType, tokens, provider } = usageData;
  logger.info(`Used ${tokens} tokens with ${provider} for ${modelType}`);
});
```

### Local AI Support

Local AI configuration has been improved with clearer documentation and defaults:

```
PLUGIN_LOCAL_AI_MODEL_PATH=./models/llama-2-7b-chat.Q4_0.gguf
PLUGIN_LOCAL_AI_SERVER_URL=http://localhost:8080
```

The community manager character (ELI5) now defaults to using local AI out of the box (#4557).

## Breaking Changes

As ElizaOS moves from v1 to v2 (1.0.0), several breaking changes require developer attention:

### Plugin Structure Changes

Multiple plugins have been removed from the monorepo and relocated to standalone repositories:

- Twitter: [elizaos-plugins/plugin-twitter](https://github.com/elizaos-plugins/plugin-twitter)
- Discord: [elizaos-plugins/plugin-discord](https://github.com/elizaos-plugins/plugin-discord)
- Farcaster: [elizaos-plugins/plugin-farcaster](https://github.com/elizaos-plugins/plugin-farcaster)
- Telegram: [elizaos-plugins/plugin-telegram](https://github.com/elizaos-plugins/plugin-telegram)

### CLI Command Changes

The CLI command structure has been updated and consolidated:

```bash
# Old way
npx elizaos plugins install @elizaos-plugins/client-twitter

# New way
elizaos plugins install plugin-twitter
```

The update-cli command has been merged into the update command:

```bash
# Old way
elizaos update-cli

# New way
elizaos update --cli
```

### Agent Implementation

Plugin-bootstrap is now activated by default in agent creation flows:

```javascript
// This is now automatic and doesn't need explicit configuration
agent.registerPlugin("plugin-bootstrap");
```

Database configuration has changed to prefer project-local storage:

```
# Database now defaults to project directory
# Set custom path if needed
PGLITE_DATA_DIRECTORY=./mydb
```

Developers migrating from v1 to v2 should review their agent implementations, particularly around knowledge handling, database operations, and plugin usage to ensure compatibility with the new architecture.