π§ Agentic Long-Term Memory with Notion Integration
This project explores the concept of long-term memory in AI agents and demonstrates how to build sophisticated agentic memory systems using various approaches and tools. Now featuring complete Notion workspace integration and MCP (Model Context Protocol) implementation!
Feel free to βοΈ the repo if it helps you understand long-term memory for agents!
π What's New - Enhanced Features
π₯ Complete Notion Integration
- 15+ Notion Functions: Search, read, create, update, and analyze your Notion workspace
- Smart Content Management: Add paragraphs, headings, bullets, todos with intelligent formatting
- Advanced Content Types: Bookmarks and internal page links with URL validation
- Workspace Analytics: Get insights about your Notion usage patterns
- Bulk Operations: Handle multiple pages and operations efficiently with smart pagination
- Function Chaining: Complex multi-step workflows handled automatically
- Production-Ready MCP Server: Complete Notion MCP Server V2.1 with bulletproof validation and comprehensive testing
π― MCP (Model Context Protocol) Implementation
- Multiple Transport Support: HTTP and stdio transport protocols
- Production Ready: Deployable MCP servers with fallback strategies
- Tool Discovery: Automatic tool registration and discovery
- Error Handling: Comprehensive error management and recovery
π Comprehensive Documentation
π Core Documentation
- π€ Complete System Explanation - Detailed walkthrough of the entire chatbot system
- π§ How MCP Tools Work - Deep dive into MCP implementation and tool mechanics
- π Notion Integration Guide - Complete Notion ServerV2 integration documentation
- π Notion MCP Server - Complete Notion MCP Server V2.1 - Production-ready server with bulletproof validation
π Implementation Guides
- π MCP Implementation Comparison - Comparison of different MCP implementation approaches
- π― MCP Notion README - Specific MCP Notion integration setup and usage
- βοΈ Production Configuration - Production deployment and configuration guide
π§ Memory System Research
- Memory in LLM Agents - Research paper reference
- MemGPT Paper - PDF available in the repo
π What You'll Learn
- How to design a custom agentic long-term memory system
- How to implement long-term memory using Vector DB and Graph DB with LangChain and LangGraph
- How to structure memory into semantic, episodic, and procedural components
- Complete Notion workspace integration with natural language processing
- MCP (Model Context Protocol) implementation for scalable tool integration
- Production-ready MCP server development - see our Notion MCP Server V2.1
- Advanced function chaining for complex multi-step workflows
- Production-ready deployment strategies and configurations
πΎ How to Run the Project
β οΈ Note: Please use Python 3.11 as Python 3.12 may cause compatibility issues with some dependencies.
1. Environment Setup
# Create virtual environment
python -m venv venv
source venv/bin/activate # or venv\Scripts\activate on Windows
# Install dependencies
pip install -r requirements.txt
2. Database Preparation
# Setup SQLite DB
python src/prepare_sqldb.py
# Setup Vector DB
python src/prepare_vectordb.py
# Verify databases
python src/check_sqldb.py
python src/check_vectordb.py
3. Environment Variables
# Required
export OPENAI_API_KEY="your_openai_api_key"
export NOTION_TOKEN="your_notion_integration_token"
# Optional
export NOTION_API_KEY="your_notion_integration_token" # Alternative to NOTION_TOKEN
4. Run the Enhanced Chatbot
# Terminal version with full Notion integration
python src/chat_in_terminal.py
# Gradio UI version
python src/chat_in_ui.py
5. Test the Integration
# Test Notion integration
python test_notion_integration.py
# Test MCP functionality
python test_notion_mcp.py
π― Available Chatbot Versions
Version 1: Basic Chatbot (basic_chatbot_v1.py
)
- Simple conversation handling
- Basic OpenAI integration
Version 2: Agentic Chatbot (chatbot_agentic_v2.py
)
- Function calling capabilities
- User information management
- Chat history search
Version 3: Enhanced Agentic Chatbot (chatbot_agentic_v3.py
) - β MAIN VERSION
- Complete Notion integration (15+ functions)
- Advanced memory systems (Vector DB + SQL)
- Smart function chaining
- Production-ready architecture
- MCP protocol support
π§ Key Features
π§ Memory Systems
- SQL Database: Structured user information and chat history
- Vector Database: Semantic search through conversation history
- Smart Summarization: Automatic conversation summarization
- Context Management: Intelligent context preservation
π Notion Integration
- Search & Discovery: Full-text search across pages and databases
- Content Management: Create, read, update pages with rich formatting
- Advanced Content Types: Bookmarks and internal page links with validation
- Analytics: Workspace insights and usage patterns
- Bulk Operations: Handle multiple operations efficiently
- Production MCP Server: Complete V2.1 Server with bulletproof validation and 48KB test suite
π― Function Chaining
- Multi-step Workflows: Automatic handling of complex tasks
- Context Awareness: Understanding when tasks require multiple steps
- Smart Routing: Intelligent function selection and execution
βοΈ Production Features
- Error Handling: Comprehensive error management
- Fallback Systems: Multiple backup strategies
- Scalable Architecture: Easy to extend and modify
- MCP Protocol: Standard tool integration protocol
ποΈ Project Architecture
βββββββββββββββββββββββ βββββββββββββββββββββββ βββββββββββββββββββββββ
β User Interface βββββΆβ Chatbot Agentic V3 βββββΆβ External Systems β
β (Terminal/UI) β β (Main Controller) β β (Notion, DB, etc) β
βββββββββββββββββββββββ βββββββββββββββββββββββ βββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββ
β Core Components β
β βββββββββββββββ βββββββββββββββββββ β
β β OpenAI β β Notion β β
β β Agent β β ServerV2 β β
β βββββββββββββββ βββββββββββββββββββ β
β βββββββββββββββ βββββββββββββββββββ β
β β Memory β β Vector DB β β
β β Systems β β (Embeddings) β β
β βββββββββββββββ βββββββββββββββββββ β
β βββββββββββββββ βββββββββββββββββββ β
β β MCP β β SQL Database β β
β β Protocol β β (Structured) β β
β βββββββββββββββ βββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββ
π Updated Project Structure
src/
βββ chat_in_terminal.py # Enhanced terminal chatbot
βββ chat_in_ui.py # Gradio UI version
βββ prepare_sqldb.py # Creates SQLite DB
βββ prepare_vectordb.py # Creates Vector DB
βββ check_sqldb.py # Checks SQLite DB contents
βββ check_vectordb.py # Checks Vector DB contents
βββ notion_mcp_server/ # π Complete Notion MCP Server
β βββ core_operations.py # Basic Notion operations
β βββ analytics_operations.py # Workspace analytics
β βββ bulk_operations.py # Bulk operations
β βββ update_operations.py # Content updates
β βββ notion_utils.py # Utility functions
β βββ api_serverV2.py # HTTP API server
β βββ serverV2.py # MCP server implementation
β βββ test_server.py # π 48KB comprehensive test suite
β βββ README.md # π Complete MCP Server V2.1 documentation
βββ utils/
βββ basic_chatbot_v1.py # Basic chatbot implementation
βββ chatbot_agentic_v2.py # Agentic chatbot v2
βββ chatbot_agentic_v3.py # π Main enhanced chatbot (LATEST)
βββ mcp_client_manager.py # π MCP client management
βββ chat_history_manager.py
βββ vector_db_manager.py
βββ user_manager.py
βββ prepare_system_prompt.py
βββ search_manager.py
βββ sql_manager.py
βββ config.py
βββ utils.py
# Testing Files
βββ test_notion_integration.py # π Notion integration tests
βββ test_notion_mcp.py # π MCP functionality tests
βββ test_chatbot_integration.py # π Chatbot integration tests
βββ [other test files...]
# Documentation
βββ HOW_MCP_TOOLS_WORK.md # π MCP implementation guide
βββ NOTION_INTEGRATION_README.md # π Notion integration docs
βββ MCP_IMPLEMENTATION_COMPARISON.md # π Implementation comparison
βββ MCP_NOTION_README.md # π MCP Notion setup guide
βββ PRODUCTION_CONFIG.md # π Production deployment
βββ README.md # This file
# Additional Directories
langgraph/ # LangGraph implementations
letta/ # Letta memory system
docker/ # π Docker deployment
config/ # Configuration files
data/ # Database storage
π οΈ Technologies Used
Core Technologies
- Python 3.11: Main programming language
- OpenAI API: GPT models for conversation and function calling
- Notion API: Complete workspace integration
Memory & Database
- SQLite: Structured data storage
- ChromaDB: Vector database for semantic search
- Embeddings: OpenAI text-embedding models
Integration & Protocols
- MCP (Model Context Protocol): Standard tool integration
- HTTP/stdio: Multiple transport protocols
- JSON-RPC: Communication protocol
UI & Testing
- Gradio: Web-based user interface
- Terminal: Command-line interface
- Comprehensive Testing: Integration and unit tests
π System Schemas
LLM Default Behavior
Concept of Memory
Basic Chatbot Schema
Agentic_Chatbot_v2 Schema
Agentic_Chatbot_v3 Schema (Old Version)
Longterm Memory with Graph DB and Vector DB using LangGraph
Longterm Memory (Semantic, Episodical, and Procedural) with LangGraph
Old Project Structure
π Getting Started
- Read the Documentation: Start with π€ Complete System Explanation
- Explore the MCP Server: Check out our Notion MCP Server V2.1 - production-ready with comprehensive testing
- Set up Environment: Follow the installation steps above
- Configure Notion: Set up your Notion integration token
- Run Tests: Verify everything works with the test files
- Start Chatting: Use the enhanced chatbot with natural language
π€ Contributing
Feel free to contribute by:
- Adding new Notion operations
- Improving memory systems
- Enhancing the MCP implementation
- Adding more test cases
- Improving documentation
π License
This project is open source
π This is a complete AI agent system with production-ready Notion integration, advanced memory management, and MCP protocol implementation!