@temporal.ai/chronos-minds

Advanced Temporal AI SDK - Build intelligent minds that transcend time, retain perfect context, and evolve through every interaction

🌟 Features

• Temporal Memory: AI agents that remember past conversations and learn from every interaction
• Perfect Context: Maintain conversation continuity across sessions with intelligent memory retrieval
• Vector Search: Advanced semantic search through stored memories and conversations
• React Components: Pre-built UI components for chat interfaces and memory visualization
• CLI Tools: Command-line interface for managing agents, memories, and configurations
• TypeScript First: Full type safety with comprehensive TypeScript definitions
• Database Agnostic: Works with PostgreSQL, Supabase, and other compatible databases

🚀 Quick Start

Installation

npm install @temporal.ai/chronos-minds

Basic Usage

import { MemoryAgent, TemporalVault } from '@temporal.ai/chronos-minds';

// Initialize a memory agent
const agent = new MemoryAgent({
  openaiApiKey: 'your-openai-api-key',
  supabaseUrl: 'your-supabase-url',
  supabaseKey: 'your-supabase-key'
});

// Create a conversation with memory
const response = await agent.chat('user123', 'Hello! Remember that I love pizza.');
console.log(response.message);

// Later conversation - the agent remembers!
const laterResponse = await agent.chat('user123', 'What do you know about my food preferences?');
// Agent will recall the pizza preference from memory

📦 What's Included

Core SDK

• MemoryAgent: Main class for creating AI agents with temporal memory
• TemporalVault: Advanced memory storage and retrieval system
• OpenAI Integration: Streamlined chat completions with context injection
• Database Schema: Pre-built schema for PostgreSQL with Drizzle ORM

React Components

import { ChatHistory, ChatInput, MemoryPanel } from '@temporal.ai/chronos-minds/components';

function MyApp() {
  return (
    <div>
      <ChatHistory messages={messages} />
      <ChatInput onSend={handleSend} />
      <MemoryPanel memories={memories} />
    </div>
  );
}

CLI Tools

# Initialize configuration
npx chronos config init

# Create a new agent
npx chronos agent create "My Assistant" --personality="helpful and creative"

# Chat with an agent
npx chronos chat --agent="My Assistant" "Hello there!"

# Search memories
npx chronos memory search "pizza preferences"

# Database operations
npx chronos database migrate

🛠️ Configuration

Environment Variables

Create a .env file with your API keys:

OPENAI_API_KEY=your_openai_api_key
SUPABASE_URL=your_supabase_project_url  
SUPABASE_KEY=your_supabase_anon_key
DATABASE_URL=postgresql://user:pass@host:port/db

Initialization

import { ChronosSDK } from '@temporal.ai/chronos-minds';

const chronos = new ChronosSDK({
  openai: {
    apiKey: process.env.OPENAI_API_KEY,
    model: 'gpt-4o-mini' // or your preferred model
  },
  memory: {
    supabaseUrl: process.env.SUPABASE_URL,
    supabaseKey: process.env.SUPABASE_KEY
  }
});

📖 API Reference

MemoryAgent

class MemoryAgent {
  // Create a new agent
  constructor(config: AgentConfig)
  
  // Send a message and get response with memory
  async chat(userId: string, message: string): Promise<ChatResponse>
  
  // Store a specific memory
  async storeMemory(userId: string, memory: Memory): Promise<void>
  
  // Search through memories
  async searchMemories(userId: string, query: string): Promise<Memory[]>
}

TemporalVault

class TemporalVault {
  // Store time-capsule memories
  async storeTimeCapsule(capsule: TimeCapsule): Promise<void>
  
  // Retrieve memories by timeframe
  async getMemoriesByTimeframe(userId: string, start: Date, end: Date): Promise<TimeCapsule[]>
  
  // Search temporal records
  async searchTemporalRecords(userId: string, query: string): Promise<TimeCapsule[]>
}

🎯 Advanced Usage

Custom Memory Types

// Store different types of memories
await agent.storeMemory(userId, {
  type: 'preference',
  content: 'User prefers dark mode UI',
  metadata: { category: 'ui', importance: 'high' }
});

await agent.storeMemory(userId, {
  type: 'decision',
  content: 'User decided to use React for frontend',
  metadata: { project: 'web-app', date: new Date() }
});

Memory Search with Filters

// Search with semantic similarity
const memories = await vault.searchMemories(userId, 'food preferences');

// Filter by metadata
const recentDecisions = await vault.searchMemories(userId, 'decisions', {
  type: 'decision',
  timeframe: 'last_week'
});

React Integration

import { useTemporalAgent } from '@temporal.ai/chronos-minds/hooks';

function ChatInterface() {
  const { agent, sendMessage, messages, memories } = useTemporalAgent({
    userId: 'user123',
    agentId: 'my-agent'
  });

  return (
    <div>
      <ChatHistory messages={messages} />
      <MemoryPanel memories={memories} />
      <ChatInput onSend={sendMessage} />
    </div>
  );
}

🗄️ Database Setup

Using Drizzle ORM

import { migrate } from '@temporal.ai/chronos-minds/database';

// Run migrations
await migrate();

Schema Overview

• Users: User accounts and profiles
• Agents: Memory agents with personalities and configurations
• Messages: Chat messages with context and responses
• Memories: Stored memories with semantic embeddings
• TimeCapsules: Temporal memory storage with metadata

🔧 CLI Reference

# Configuration
chronos config init              # Initialize config file
chronos config show              # Show current config
chronos config delete            # Delete config file

# Agent Management
chronos agent create <name>      # Create new agent
chronos agent list               # List all agents
chronos agent delete <id>        # Delete agent

# Memory Operations
chronos memory search <query>    # Search memories
chronos memory store <content>   # Store new memory
chronos memory list              # List all memories

# Chat Interface
chronos chat                     # Start interactive chat
chronos chat --agent=<name>      # Chat with specific agent

# Database
chronos database migrate         # Run database migrations
chronos database seed            # Seed with sample data

🎨 Demo Application

This package includes a full Next.js demo application called "Temporal Assistants" that showcases all features:

• Dashboard: Manage multiple memory agents
• Chat Interface: Real-time conversations with memory
• Memory Visualization: Browse and search stored memories
• Agent Configuration: Customize personalities and behaviors

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🆘 Support

• Issues: GitHub Issues
• Documentation: Full Documentation
• Examples: Check the /examples directory for more use cases

🚀 Deploy on Replit

This package is designed to work seamlessly on Replit. Simply fork the repository and start building your temporal AI applications!

Built with ❤️ by Temporal AI Technologies Inc