A flexible multi-interface AI agent framework that can interact through various platforms including Telegram, Discord, Twitter, Farcaster, REST API, and MCP.

Grab a Heurist API Key instantly for free by using the code 'agent' while submitting the form on https://heurist.ai/dev-access

The Heurist Agent Framework is built on a modular architecture that allows an AI agent to:

• Process text and voice messages
• Generate images and videos
• Interact across multiple platforms with consistent behavior
• Fetch and store information in a knowledge base (Postgres and SQLite supported)
• Access external APIs, tools, and a wide range of Mesh Agents to compose complex workflows

• Features
• Heurist Mesh
  • Why Heurist Mesh?
  • Agent Categories
  • Get Started with Mesh
  • MCP Support
  • Usage and Development Guide
• Heurist Agent Framework Architecture
  • Agent Structure
  • Agent Interfaces
  • Heurist Core
    • Components
    • Workflows
    • Tool Management
    • External Clients
  • Agent Usage and Development Guide
• Development Setup
• How to Use GitHub Issues
• License
• Contributing
• Support
• Star History

• 🤖 Core Agent - Modular framework with advanced LLM integration
• 🧩 Component Architecture - Plug-and-play components for flexible agent or agentic application design
• 🔄 Workflow System - RAG, Chain of Thought, and Research workflows
• 🖼️ Media Generation - Image creation and processing capabilities
• 🎤 Voice Processing - Audio transcription and text-to-speech
• 💾 Vector Storage - Knowledge retrieval with PostgreSQL/SQLite support
• 🛠️ Tool Integration - Extensible tool framework with MCP support
• 🌐 Mesh Agent Access - Connect to community-contributed specialized agents via API or MCP
• 🔌 Multi-platform Support:
  • Telegram bot
  • Discord bot
  • Twitter automation
  • Farcaster integration
  • REST API
  • MCP integration

Heurist Mesh is the skills marketplace for AI agents - your gateway to Web3 intelligence. General-purpose AI models lack specialized knowledge about Web3 and often fail to deliver accurate results. Heurist Mesh solves this by providing 30+ specialized AI agents that are experts in crypto analytics, ready to give your applications or AI agents the Web3 expertise they need.

• Curated Web3 Tools: We curate the best Web3 data sources and APIs, constantly monitored and updated for reliable performance.
• Optimized for Agents: Input/output formats optimized for AI agents - 70% fewer tool calls, 30-50% less token usage vs simple API wrappers.
• Composable Architecture: Mix and match specialized agents to build powerful workflows.
• Flexible Access: REST API with API key, x402-enabled pay-per-use with USDC on Base, and MCP access.
• Trusted Agent Standard: Every agent MCP is registered on the ERC-8004 trusted agent standard on Ethereum.

• Mesh Portal: mesh.heurist.ai - Browse agents and deploy dedicated MCP servers
• REST API: API Documentation
• X402 API: mesh.heurist.xyz/x402/agents - Pay-per-use with USDC on Base
• Full Agent List: View all agents

All Heurist Mesh agents are accessible via MCP. This means you can access them from any AI clients and frameworks that support MCP, including Claude, ChatGPT, Cursor, LangChain, Google ADK, n8n, etc.

Visit Heurist Mesh Console to view all MCP endpoints, and create private dedicated MCP servers by mixing and matching the agents that you need. The MCP server source code is available at Github: heurist-mesh-mcp-server.

Read the Mesh documentation

🔍 Click the badge to explore technical insights, ask questions.

The framework follows a modular, component-based architecture:

1. BaseAgent (Abstract Base Class)

   • Defines the interface and common functionality
   • Manages component initialization and lifecycle
   • Implements core messaging patterns

2. CoreAgent (Concrete Implementation)

   • Implements BaseAgent functionality
   • Orchestrates components and workflows
   • Handles decision-making for workflow selection

Each interface inherits from BaseAgent and implements platform-specific handling:

• Telegram (interfaces/telegram_agent.py)
• Discord (interfaces/discord_agent.py)
• API (interfaces/flask_agent.py)
• Twitter (interfaces/twitter_agent.py)
• Farcaster (interfaces/farcaster_agent.py)

Heurist Core provides a set of core components, tools, and workflows for building LLM-powered agents or agentic applications. It can be used as a standalone package or as part of the Heurist Agent Framework.

Read the Heurist Core documentation

The framework uses a modular component system:

• PersonalityProvider: Manages agent personality and system prompts
• KnowledgeProvider: Handles knowledge retrieval from vector database
• ConversationManager: Manages conversation history and context
• ValidationManager: Validates inputs and outputs
• MediaHandler: Processes images, audio, and other media
• LLMProvider: Interfaces with language models
• MessageStore: Stores and retrieves messages with vector search

Workflows provide higher-level reasoning patterns:

• AugmentedLLMCall: Standard RAG + tools pattern for context-aware responses
• ChainOfThoughtReasoning: Multi-step reasoning with planning and execution phases
• ResearchWorkflow: Deep web search and analysis with hierarchical exploration

• ToolBox: Base framework for tool definition and registration
• Tools: Tool management and execution layer
• ToolsMCP: Integration with MCP Protocol for tool execution

• SearchClient: Unified client for web search (Firecrawl/Exa)
• MCPClient: Client for MCP Protocol for local or remote servers.

Read the Agent Usage and Development Guide

To set up your development environment:

1. Install dependencies using uv:

   uv sync

2. Activate the virtual environment:

   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

We encourage the community to open GitHub issues whenever you have a new idea or find something that needs attention. When creating an issue, please use our Issue Template and select one of the following categories:

1. Integration Request

   • For requests to integrate with a new data source (e.g., CoinGecko, arXiv) or a new AI use case.
   • Most important for the community, as these issues help drive the direction of our framework's evolution.
   • If you have an idea but aren't sure how to implement it, open an issue under this label so others can pick it up or offer suggestions.

2. Bug

   • For reporting errors or unexpected behavior in the framework.
   • Provide as much detail as possible (logs, steps to reproduce, environment, etc.).

3. Question

   • For inquiries about usage, best practices, or clarifications on existing features.

4. Bounty

   • For tasks with a reward (e.g., tokens, NFTs, or other benefits).
   • The bounty label indicates that Heurist team or another community member are offering a reward to whoever resolves the issue.
   • Bounty Rules:
     • Make sure to read the issue description carefully for scope and acceptance criteria.
     • Once your Pull Request addressing the bounty is merged, we'll follow up on fulfilling the reward.
     • Additional instructions (e.g., contact method) may be included in the issue itself.

• Look for Integration Requests or Bounty issues if you want to contribute new features or earn rewards.
• Feel free to discuss approaches in the comments. If you're ready to tackle it, mention "I'm working on this!" so others know it's in progress.

This process helps us stay organized, encourages community involvement, and keeps development transparent.

BSL 1.1 - See LICENSE file for details.

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

For Heurist Mesh agents or to learn about contributing specialized community agents, please refer to the Mesh README

For support, please open an issue in the GitHub repository or contact the maintainers. Join the Heurist Ecosystem Builder telegram https://t.me/heuristsupport