Lightweight TypeScript Framework for Stateful AI Agents
Features • Quick Start • Docs • Examples • Contributing
⚠️ Alpha Software: This framework is under active development. APIs may change between versions.
Daydreams is a lightweight TypeScript framework for building autonomous AI agents with persistent state and multi-context capabilities. Built for both Node.js and browser environments.
- 🔄 Multi-Context System: Manage multiple stateful conversations and agent contexts simultaneously
- 💾 Long-Running State: Agents maintain memory and context across sessions, enabling complex multi-step workflows
- 🔌 Framework Agnostic: Seamlessly integrates with LangChain, Vercel AI SDK, and other popular AI frameworks
- 🌐 Universal Compatibility: Runs in Node.js, browsers, Deno, Bun, and edge runtimes
- 🪶 Lightweight Core: Minimal dependencies, tree-shakeable
- 🤖 Any LLM Provider: Works with OpenAI, Anthropic, Groq, local models, or any provider via adapters
- TypeScript First: Full type safety with excellent IntelliSense support
- Simple API: Intuitive context and action system
- Modular Design: Use only what you need
- Framework Composition: Combine with LangChain tools, Vercel AI SDK, or custom implementations
- Streaming Support: Real-time response streaming out of the box
- Stateful Contexts: Maintain conversation history and agent state
- Action System: Define custom functions agents can execute
- Memory Persistence: Store and retrieve information across sessions
- Task Management: Handle complex multi-step operations
- Event-Driven: React to inputs from multiple sources
- Multi-Platform: Discord, Twitter, Telegram, CLI, and more via extensions
- Blockchain Ready: Optional modules for Web3 interactions
- API Integration: Connect to any REST or GraphQL API
- Database Support: Works with any database through adapters
- Node.js 18+ or modern browser environment
- TypeScript 4.5+ (optional but recommended)
- LLM API Key from any supported provider
npm install @daydreamsai/core
# or
yarn add @daydreamsai/core
# or
pnpm add @daydreamsai/coreimport { createDreams, context } from "@daydreamsai/core";
import { anthropic } from "@ai-sdk/anthropic";
import { z } from "zod";
// Define a stateful context
const chatContext = context({
type: "chat",
schema: z.object({
userId: z.string(),
}),
create() {
return {
messages: [],
metadata: {},
};
},
});
// Create an agent with persistent state
const agent = await createDreams({
model: anthropic("claude-3-5-sonnet-latest"),
context: chatContext,
actions: [
// Define custom actions your agent can take
],
}).start({ userId: "user-123" });
// Send messages - state is maintained across calls
await agent.send({
context: chatContext,
args: { userId: "user-123" },
input: {
type: "text",
data: "Remember that I prefer Python for data analysis",
},
});// Works with LangChain
import { ChatOpenAI } from "@langchain/openai";
const agent = await createDreams({
model: new ChatOpenAI({ modelName: "gpt-4" }),
// ... rest of config
});
// Works with Vercel AI SDK
import { openai } from "@ai-sdk/openai";
const agent = await createDreams({
model: openai("gpt-4-turbo"),
// ... rest of config
});
// Works with any LLM provider
import { createCustomProvider } from "./my-provider";
const agent = await createDreams({
model: createCustomProvider(),
// ... rest of config
});- 🚀 Build a simple chatbot → Start with the Basic Chat Example
- 🔌 Integrate with Discord/Twitter → Check out Platform Extensions
- 🧠 Understand how it works → Read Core Concepts
- ⚙️ Extend with custom actions → See Action System
- 🏗️ Contribute or modify core → Study Detailed Architecture
- 💾 Add custom storage → Explore Memory Architecture
Visit our comprehensive documentation to learn more:
- Getting Started Guide - Set up your first agent
- Core Concepts - Understand contexts, actions, and memory
- API Reference - Detailed API documentation
- Examples - Learn from working code
- Integration Guide - Connect with other frameworks
Explore our example implementations:
| Example | Description | Location |
|---|---|---|
| Basic Chat | Simple chat interface with personality traits | examples/basic/ |
| Discord Bot | Multi-functional Discord bot | examples/discord/ |
| Twitter Agent | Autonomous Twitter/X agent | examples/twitter/ |
| Telegram Bot | Telegram bot integration | examples/telegram/ |
| Task Management | Task planning and execution | examples/tasks/ |
| Deep Research | Advanced research capabilities | examples/deep-research/ |
| Blockchain Interactions | Cross-chain operations | examples/chains/<
9E7A
/code> |
| Game Agents | Agents for on-chain games (Gigaverse, Lootsurvivor) | examples/games/ |
| MCP Integration | Model Context Protocol examples | examples/mcp/ |
| Composio | Composio integration examples | examples/composio/ |
Daydreams uses a modular, event-driven architecture designed for flexibility and composability:
graph TB
A[Input Sources] --> B[Dreams Engine]
B --> C[Context Manager]
B --> D[Memory System]
B --> E[Action Registry]
C --> F[Context State]
C --> G[Working Memory]
E --> H[User Actions]
E --> I[System Actions]
D --> J[Vector Store]
D --> K[KV Store]
B --> L[Task Runner]
L --> M[LLM Provider]
B --> N[Extensions]
N --> O[Platform Extensions]
N --> P[Storage Extensions]
- Dreams Engine: Lightweight orchestrator managing agent lifecycle and message flow
- Context Manager: Handles multiple concurrent stateful conversations with type safety
- Memory System: Pluggable storage layer supporting both KV and vector stores
- Action Registry: Type-safe action system for extending agent capabilities
- Task Runner: Manages async operations with concurrency control
- Extensions: Plugin architecture for platforms, storage, and custom features
Before diving into the detailed architecture, let's understand the key concepts:
- Agent - Your AI assistant that can maintain state and execute actions
- Context - A stateful conversation or task environment (like a chat session)
- Actions - Functions your agent can execute (like "search web" or "send email")
- Memory - Persistent storage for conversation history and learned information
- Engine - The processing core that handles inputs and coordinates execution
// 1. Create an agent
const agent = createDreams({ model: anthropic("claude-3-5-sonnet") });
// 2. Define what state it maintains (Context)
const chatContext = context({
type: "chat",
create: () => ({ messages: [], userPreferences: {} }),
});
// 3. Give it capabilities (Actions)
const searchAction = {
name: "search",
handler: async (query) => {
/* search implementation */
},
};
// 4. Start and use
await agent.start();
await agent.send({
context: chatContext,
input: { type: "text", data: "Search for AI news" },
});- Start Simple: Begin with basic chat contexts and simple actions
- Add Persistence: Learn how memory stores conversation history
- Multiple Contexts: Understand how agents can manage multiple conversations
- Custom Actions: Build your own actions for specific tasks
- Extensions: Add platform integrations (Discord, Twitter, etc.)
- Advanced Features: Explore streaming, evaluation, and custom storage
graph TB
subgraph "User Interface"
API[Agent API]
end
subgraph "Core System"
Engine[Execution Engine]
Context[Context Manager]
Memory[Memory System]
end
subgraph "Extensibility"
Actions[Action System]
Extensions[Extensions]
Providers[LLM Providers]
end
API --> Engine
Engine --> Context
Engine --> Actions
Context --> Memory
Extensions --> Actions
Extensions --> Providers
sequenceDiagram
participant User
participant Agent
participant Engine
participant Context
participant Actions
participant Memory
User->>Agent: send(input)
Agent->>Engine: process(input)
Engine->>Context: load state
Context->>Memory: retrieve
Engine->>Actions: execute
Actions-->>Engine: results
Engine->>Memory: save state
Engine-->>User: output
graph LR
subgraph "Context System"
CS[Context State]
WM[Working Memory]
CS --> WM
end
subgraph "Storage Layer"
KV[KV Store]
Vector[Vector Store]
Episodic[Episodic Memory]
end
WM --> KV
WM --> Vector
WM --> Episodic
graph TB
Agent[Agent Core]
subgraph "Custom Extensions"
CI[Custom Inputs]
CO[Custom Outputs]
CA[Custom Actions]
CC[Custom Contexts]
CS[Custom Storage]
end
Agent --> CI
Agent --> CO
Agent --> CA
Agent --> CC
Agent --> CS
Contexts maintain isolated state for different conversations or tasks:
// Define a context with typed state
const chatContext = context({
type: "chat",
schema: z.object({ userId: z.string() }),
create: () => ({
messages: [],
preferences: {},
}),
});
// Each user gets their own isolated state
const user1State = await agent.getContext({
context: chatContext,
args: { userId: "user1" },
});Actions are typed functions your agent can execute:
const searchAction = {
name: "search_web",
description: "Search the web for information",
schema: z.object({
query: z.string(),
limit: z.number().optional(),
}),
handler: async ({ query, limit = 10 }) => {
// Your implementation
return results;
},
};Flexible storage with both key-value and vector capabilities:
// Key-value storage
await agent.memory.store.set("user:preferences", { theme: "dark" });
// Vector storage for semantic search
await agent.memory.vectors.upsert("context-123", {
text: "User prefers Python for data science",
embedding: <
F951
span class="pl-k">await generateEmbedding(text),
});const researchAgent = createDreams({
/* config */
});
const writerAgent = createDreams({
/* config */
});
// Agents can share context
const sharedContext = context({ type: "project" });
const research = await researchAgent.run({ context: sharedContext });
const article = await writerAgent.run({
context: sharedContext,
input: research,
});await agent.send({
context: chatContext,
input: { type: "text", data: "Explain quantum computing" },
handlers: {
onLogStream: (log, done) => {
if (log.ref === "output") {
process.stdout.write(log.content);
}
},
},
});Daydreams can be extended with blockchain capabilities through optional packages:
@daydreamsai/discord- Discord bot integration@daydreamsai/twitter- Twitter/X automation@daydreamsai/telegram- Telegram bot support@daydreamsai/cli- Command-line interface
@daydreamsai/supabase- Supabase vector store@daydreamsai/chroma- ChromaDB integration@daydreamsai/mongo- MongoDB support
Daydreams works with any LLM provider through the AI SDK adapters:
- OpenAI - GPT-4, GPT-3.5, etc.
- Anthropic - Claude 3.5, Claude 4, etc.
- Google - Gemini Pro, Gemini Ultra
- Groq - Fast inference for open models
- OpenRouter - Access multiple providers
- Ollama - Local model support
- LangChain - Use any LangChain model
- Custom - Bring your own provider
Use Daydreams when you need:
- Stateful agents that remember context across sessions
- Multiple isolated conversation contexts
- Type-safe action system with schema validation
- Lightweight, framework-agnostic solution
- Both Node.js and browser support
Consider alternatives when:
- You only need simple, stateless chat completions
- You're heavily invested in a specific framework's ecosystem
- You need specialized features (e.g., specific to LangChain)
Daydreams uses a two-tier memory system:
- Working Memory: Temporary state for current execution
- Persistent Storage: Long-term memory via pluggable stores (KV, Vector, etc.)
// Memory is automatically persisted between sessions
const agent = await createDreams({
/* config */
}).start();
// ... agent processes requests ...
await agent.stop(); // State is saved
// Later, restart and state is restored
const agent2 = await createDreams({
/* config */
}).start();
// Previous conversations and state are availableYes! You can use different models for different purposes:
const agent = await createDreams({
model: openai("gpt-4"), // Primary model
reasoningModel: anthropic("claude-3-opus"), // For complex reasoning
// Different contexts can use different models
contexts: [
context({
type: "analysis",
model: groq("mixtral-8x7b"), // Fast model for data analysis
}),
],
});Daydreams provides multiple debugging options:
const agent = await createDreams({
logLevel: LogLevel.DEBUG,
debugger: (contextId, keys, data) => {
console.log(`[${contextId}]`, keys.join("."), data);
},
});
// Use handlers to trace execution
await agent.send({
handlers: {
onLogStream: (log, done) => {
console.log(`${log.ref}: ${JSON.stringify(log.data)}`);
},
},
});We love contributions! Whether you're fixing bugs, adding features, or improving documentation, we'd appreciate your help.
- Check existing issues or create a new one to discuss your ideas
- Fork the repository and create your branch from
main - Make your changes and ensure tests pass
- Submit a pull request with a clear description
See our Contributing Guide for detailed instructions.
# Clone the repository
git clone https://github.com/daydreamsai/daydreams.git
cd daydreams
# Install dependencies
pnpm install
# Build packages in watch mode
pnpm build:packages --watch
# Run tests
pnpm testNew to the project? Check out our
good first issue
label for beginner-friendly tasks.
Join our growing community:
- Discord - Chat with other developers
- Twitter - Stay updated with announcements
- GitHub Discussions - Ask questions and share ideas
Daydreams is MIT licensed.
Built with ❤️ by the Daydreams team