Skip to content

Releases: jjyaoao/HelloAgents

V0.2.0

30 Sep 16:29
@jjyaoao jjyaoao
V0.2.0
de9cf50

Choose a tag to compare

View all tags
V0.2.0

HelloAgents V0.2.0 Release Notes

📅 Last Updated: 2025-10-01
📦 Package: pip install hello-agents[mem-rag]
🔗 GitHub: https://github.com/jjyaoao/HelloAgents

🎯 Overview

The HelloAgents memory system provides complete memory and RAG (Retrieval-Augmented Generation) capabilities to enhance Agent abilities through a tooling approach. The system adopts a layered architecture design, implementing four memory types and hybrid storage backends according to Chapter 8 architecture.

✨ Core Features

  • 🧠 Four Memory Types: Working Memory, Episodic Memory, Semantic Memory, Perceptual Memory
  • 💾 Hybrid Storage Architecture: SQLite (document store) + Qdrant (vector retrieval) + Neo4j (knowledge graph)
  • 🔍 Intelligent Retrieval: Vector retrieval + Graph retrieval + Fusion ranking
  • 🌐 Multilingual Support: Default paraphrase-multilingual-MiniLM-L12-v2 multilingual embedding model
  • 🎨 Multimodal Support: Text, Image, Audio (Perceptual Memory)
  • 🔧 Tool Interface: MemoryTool and RAGTool fully compliant with HelloAgents framework

🔧 Installation & Dependencies

Installation

# Basic memory system
pip install hello-agents[memory]

# With RAG capabilities
pip install hello-agents[rag]

# Full installation (memory + RAG + multimodal)
pip install hello-agents[mem-rag]

Dependencies

Component Packages Description
Memory System qdrant-client, neo4j, spacy Qdrant vector store, Neo4j graph store, entity recognition
RAG System transformers, sentence-transformers, scikit-learn Multilingual embedding models, intelligent fallback
Document Processing markitdown, pypdf, python-docx Multi-format document conversion and processing
Multimodal torch, librosa (optional) CLIP/CLAP model support
Intelligent Fallback Auto-select sentence-transformers → transformers → tfidf

Environment Configuration

Optional Environment Variables:

# Qdrant Configuration
QDRANT_URL="https://<your-qdrant-endpoint>:6333"
QDRANT_API_KEY="<your-api-key>"
QDRANT_COLLECTION="hello_agents_vectors"
QDRANT_DISTANCE="cosine"

# Neo4j Configuration
NEO4J_URI="bolt://localhost:7687"
NEO4J_USER="neo4j"
NEO4J_PASSWORD="<your-password>"

# Embedding Model Configuration
EMBED_MODEL_TYPE="local"  # local/dashscope/tfidf
EMBED_MODEL_NAME="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"

🏗️ System Architecture

Layered Architecture (Chapter 8 Design)

Memory System Architecture
├── Tools Layer
│   ├── MemoryTool - Unified memory interface
│   └── RAGTool - Retrieval-Augmented Generation tool
│
├── Memory Core Layer
│   └── MemoryManager - Memory lifecycle management
│       ├── Memory lifecycle management
│       ├── Priority evaluation
│       ├── Forgetting and cleanup
│       └── Multi-type coordination
│
├── Memory Types Layer
│   ├── WorkingMemory - Short-term memory
│   │   └── Pure in-memory + TTL auto-expiration
│   ├── EpisodicMemory - Event memory
│   │   └── SQLite (authoritative) + Qdrant (vector index)
│   ├── SemanticMemory - Knowledge memory
│   │   └── Qdrant (vectors) + Neo4j (knowledge graph)
│   └── PerceptualMemory - Sensory memory
│       └── SQLite (metadata) + Qdrant (multimodal vectors)
│
├── Storage Layer
│   ├── QdrantVectorStore - Vector storage
│   │   ├── Multilingual embeddings (default 384-dim)
│   │   ├── Modality-based collections (text/image/audio)
│   │   └── Efficient vector retrieval
│   ├── Neo4jGraphStore - Graph storage
│   │   ├── spaCy entity recognition
│   │   ├── Co-occurrence relationship graph
│   │   └── Graph retrieval and reasoning
│   └── SQLiteDocumentStore - Document storage
│       ├── Structured metadata
│       ├── Time/session/importance filtering
│       └── Authoritative data source
│
└── RAG Layer
    ├── DocumentProcessor - Document processing
    │   ├── Multi-format support (PDF/Word/Excel/PPT)
    │   ├── Intelligent chunking
    │   └── Language tagging and deduplication
    ├── EmbeddingModel - Embedding models
    │   ├── LocalTransformerEmbedding (default)
    │   ├── TFIDFEmbedding (fallback)
    │   └── Intelligent degradation
    └── RAGPipeline - RAG pipeline
        ├── Vector retrieval
        ├── Graph-enhanced retrieval
        ├── Fusion ranking
        └── Snippet merging

🧠 Memory Types

WorkingMemory - Short-term Memory

Short-term memory for storing current session context information.

Architecture Features:

  • Storage: Pure in-memory (Python dict), no external database dependency
  • Capacity Limit: Default 10 items, configurable (working_memory_capacity)
  • Token Limit: Default 2000 tokens, configurable (working_memory_tokens)
  • TTL Mechanism: Default 120 minutes auto-expiration, configurable (working_memory_ttl_minutes)
  • Priority Management: importance × time decay, auto-eviction of low-priority memories
  • Session-level: Auto-cleanup on session end

Implementation Details:

  • Uses collections.deque for FIFO queue
  • Auto-cleanup of expired memories on each access (TTL check)
  • Priority-based eviction when capacity is full (importance × recency_score)
  • No vector retrieval dependency, direct time and importance-based sorting

Use Cases:

  • Conversation context tracking
  • Temporary task state management
  • Recent interaction history
  • Session-specific information

EpisodicMemory - Event Memory

Stores specific interaction events and experiences using a "authoritative store + vector index" dual-storage architecture.

Architecture Features:

  • Authoritative Storage: SQLite (structured metadata, time series, session management)
  • Vector Index: Qdrant (semantic retrieval, default 384-dim multilingual embeddings)
  • Retrieval Strategy: Structured filtering + Vector retrieval + Fusion ranking
  • Ranking Formula: vector×0.6 + recency×0.2 + importance×0.2
  • Time Series: Support for time range queries and session filtering
  • Pattern Recognition: Behavior pattern discovery based on time series

Implementation Details:

  • SQLite schema: id, content, user_id, timestamp, importance, session_id, metadata
  • Qdrant collection: <base>_episodic, payload contains memory_id, user_id, session_id
  • Write flow: SQLite first (authoritative) → Qdrant second (index)
  • Retrieval flow: SQLite filtering → Qdrant vector recall → Fusion ranking
  • Deletion strategy: Filter by payload memory_id (avoid UUID mismatch)

Use Cases:

  • User interaction history
  • Event logging and replay
  • Session-based memory retrieval
  • Temporal pattern analysis

SemanticMemory - Knowledge Memory

Stores abstract knowledge and concept relationships using a "vector + graph" hybrid retrieval architecture.

Architecture Features:

  • Vector Retrieval: Qdrant vector database (multilingual embeddings, default 384-dim)
  • Graph Retrieval: Neo4j knowledge graph (spaCy entity recognition, co-occurrence relationships)
  • Fusion Ranking: graph×0.6 + vector×0.4 + importance×0.05
  • Multilingual Support: Default paraphrase-multilingual-MiniLM-L12-v2, auto-fallback
  • Entity Recognition: spaCy NER (PERSON/ORG/GPE/PRODUCT, etc.)
  • Relationship Modeling: Co-occurrence relationships only, avoiding over-inference

Implementation Details:

  • Qdrant collection: <base>_semantic, payload contains memory_id, user_id, concepts
  • Neo4j graph: Nodes (entities + concepts), Edges (co-occurrence + weights)
  • Write flow:
    1. spaCy entity extraction → Neo4j graph building (entity nodes + co-occurrence edges)
    2. Generate embeddings → Qdrant indexing
  • Retrieval flow:
    1. Qdrant vector recall (top-k candidates)
    2. Neo4j graph expansion (related entities + concepts)
    3. Fusion ranking (vector similarity + graph signal + importance)
  • Graph signal: PageRank centrality + co-occurrence frequency

Use Cases:

  • Knowledge base management
  • Concept relationship discovery
  • Entity-centric retrieval
  • Semantic reasoning and inference

PerceptualMemory - Sensory Memory

Designed for "long-term multimodal" data (text/image/audio).

Architecture Features:

  • Storage: SQLite (authoritative) + Qdrant (vector index)
  • Modality-based Collections: Avoid vector dimension conflicts
    • <base>_perceptual_text (text)
    • <base>_perceptual_image (image)
    • <base>_perceptual_audio (audio)
  • Encoding Strategy (lazy loading):
    • Text: sentence-transformers (default paraphrase-multilingual-MiniLM-L12-v2)
    • Image (optional): CLIP (e.g., openai/clip-vit-base-patch32); fallback to deterministic hash vectors
    • Audio (optional): CLAP (e.g., laion/clap-htsat-unfused, requires librosa); fallback to deterministic hash vectors
  • Same-modality Retrieval: Vector retrieval + time/importance fusion (0.6*vector + 0.2*recency + 0.2*importance)
  • Cross-modality Retrieval: Requires CLIP/CLAP; hash fallback only supports "same-source file" matching

Implementation Details:

  • SQLite schema: id, content, user_id, timestamp, importance, modality, raw_data, metadata
  • Qdrant collections: Separate collections per modality to avoid dimension conflicts
  • Write flow: SQLite metadata storage → Modality-based encoding → Qdrant indexing
  • Retrieval flow: Determine target modality → Qdrant vector recall → Fusion ranking
  • Cross-modality: Requires CLIP/CLAP support, otherwise only same-source file matching

Use Cases:

  • Image memory and retrieval
  • Audio recording and search
  • Multimodal content management
  • Cross-modal semantic search

🔍 RAG System

RAGTool - Retrieval-Augmented Generation Too...

Read more
Loading

V0.1.1

22 Sep 11:56
@jjyaoao jjyaoao
V0.1.1
28e38ac

Choose a tag to compare

View all tags
V0.1.1

HelloAgents V0.1.1 Release Notes

🎉 Release Date: 2025-9-22
📦 Package: pip install hello-agents==0.1.1
🔗 GitHub: https://github.com/jjyaoao/HelloAgents

🚀 What's New in v0.1.1

HelloAgents v0.1.1 is a major update that introduces advanced tool system capabilities, enhanced search functionality, and comprehensive framework improvements. This release represents a significant step forward in building production-ready AI agent applications.

✨ Major Features

🔧 Advanced Tool System

  • Tool Chain Management: New ToolChain and ToolChainManager classes for sequential tool execution
  • Async Tool Execution: AsyncToolExecutor for parallel and batch tool processing
  • Enhanced Tool Registry: Improved function registration with better error handling
  • Tool Workflow Support: Variable passing between tool execution steps

🔍 Enhanced Search Capabilities

  • Multi-Source Search Integration: Support for Tavily and SerpAPI with intelligent fallback
  • Smart Backend Selection: Automatic selection of best available search source
  • User-Friendly Error Messages: Clear API configuration guidance instead of mock results
  • Professional Error Handling: Detailed setup instructions for missing dependencies

🏗️ Framework Architecture Improvements

  • Five-Layer Architecture: Clean separation of concerns across all framework layers
  • Unified LLM Interface: Enhanced HelloAgentsLLM with multi-provider support
  • Standardized Message System: Consistent message handling across all agent types
  • Comprehensive Exception System: Professional error handling and user feedback

🎯 Agent Implementations

Four Complete Agent Paradigms

  • SimpleAgent: Basic conversational agent with tool integration
  • ReActAgent: Reasoning and Acting agent with Think-Act-Observe cycles
  • ReflectionAgent: Self-reflection and iterative improvement capabilities
  • PlanAndSolveAgent: Task decomposition and step-by-step execution

🛠️ Developer Experience

Enhanced Development Tools

  • Complete Test Suite: Comprehensive testing in examples/chapter07_basic_setup.py
  • Interactive Demos: Real-time agent testing and comparison
  • Professional Documentation: Detailed API docs and usage examples
  • Type Safety: Full type hints and validation throughout the codebase

Package Management

  • Optional Dependencies: pip install hello-agents[search] for search capabilities
  • Clean Imports: All major components available from main package
  • Version Compatibility: Stable API with backward compatibility guarantees

🔄 Breaking Changes

Tool System Updates

  • Removed Mock Search: Replaced mock search functionality with user-friendly API configuration guidance
  • Updated Import Paths: Some internal imports have been reorganized for better structure
  • Enhanced Error Messages: More specific and actionable error information

API Improvements

  • Standardized Tool Registration: Consistent function registration across all tool types
  • Unified Exception Handling: All exceptions now inherit from HelloAgentsException
  • Enhanced Configuration: Better environment variable handling and validation

🐛 Bug Fixes

  • Fixed Chinese font rendering issues in architecture diagrams
  • Resolved tool execution error handling in edge cases
  • Improved memory management in async tool execution
  • Fixed import issues when using pip-installed packages
  • Enhanced error messages for missing API keys and dependencies

📈 Performance Improvements

  • Async Tool Execution: Up to 4x faster parallel tool processing
  • Optimized Tool Registry: Improved tool lookup and execution performance
  • Memory Efficiency: Better resource management in long-running applications
  • Connection Pooling: Efficient handling of external API connections

📚 Documentation & Examples

New Documentation

  • Complete API Reference: Detailed documentation for all classes and methods
  • Architecture Diagrams: Visual representation of framework structure and execution flow
  • Best Practices Guide: Professional development guidelines and patterns
  • Migration Guide: Step-by-step upgrade instructions from previous versions

Enhanced Examples

  • Interactive Demo: chapter07_basic_setup.py with full framework demonstration
  • Tool Development Guide: Step-by-step custom tool creation examples
  • Agent Comparison: Side-by-side comparison of different agent paradigms
  • Production Deployment: Real-world usage patterns and configurations

🔧 Installation & Upgrade

New Installation

# Basic installation
pip install hello-agents==0.1.1

# With search capabilities
pip install hello-agents[search]==0.1.1

# Full installation with all features
pip install hello-agents[all]==0.1.1

Upgrade from v0.1.0

pip install --upgrade hello-agents==0.1.1

Dependencies

  • Core: openai>=1.0.0, pydantic>=2.0.0, requests>=2.25.0
  • Search: tavily-python>=0.3.0, serpapi>=0.1.0 (optional)
  • Development: pytest>=7.0.0, black>=22.0.0 (optional)

🎯 What's Next

Upcoming in v0.2.0

  • Memory & RAG System: Advanced context management and retrieval capabilities
  • Multi-Agent Orchestration: Agent-to-agent communication and coordination
  • Enhanced Context Engineering: Advanced prompt management and optimization
  • Production Monitoring: Logging, metrics, and observability features

Community & Contributions

  • GitHub Discussions: Join our community for questions and feature requests
  • Contributing Guide: Help us improve HelloAgents with your contributions
  • Issue Tracking: Report bugs and request features on GitHub
  • Documentation: Help us improve documentation and examples

🙏 Acknowledgments

Special thanks to all contributors, testers, and community members who made this release possible. Your feedback and contributions have been invaluable in shaping HelloAgents into a robust and user-friendly framework.

Key Contributors

  • Framework Architecture & Core Implementation
  • Tool System Design & Advanced Features
  • Documentation & Examples
  • Testing & Quality Assurance

📞 Support & Community

Happy Building with HelloAgents! 🤖✨

Loading