<div align="center">
<!--<h1 style="display: flex; align-items: center; gap: 10px;">
<img src="https://github.com/user-attachments/assets/3fb24490-b5f9-4af1-b2eb-8f2f24a6e6b8" alt="Logo" width="25">
GPT Memory
</h1>-->
<h1>🧠 GPT Memory</h1>
<h3>Memory Driven Reasoning for Smarter AI Agents</h3>
GPT Memory is a library powered by Tovana that introduces a new approach to improving LLM reasoning through actionable insights (aka beliefs) derived from continuous interactions and long term memory.
[](https://badge.fury.io/py/tovana)
[](https://opensource.org/license/apache-2-0)
</div>
## Why GPT Memory?
Current LLMs face significant limitations in their ability to learn and adapt from user-specific interactions over time. While LLMs excel at processing vast amounts of data, they struggle with ongoing personalization and context-aware learning. This gap restricts their ability to provide truly adaptive and evolving AI experiences.
Our Memory manager aims to address these challenges by providing a comprehensive memory and belief management framework for AI agents. Its core concept revolves around converting experiences (events) into memories, which in turn shape beliefs. These beliefs then influence the agent's reasoning, responses, and actions.
By simulating human-like memory processes, GPT Memory enables more personalized, adaptive, and context-aware AI interactions. This framework bridges the gap between static knowledge bases and dynamic, experience-based learning, allowing AI agents to evolve their understanding and behavior over time.
## 🌟 Features
| Feature | Status | Description |
|----------------------------------|-------------|---------------------------------------------------------------------------------------------|
| 🧠 Human-like Memory | ✅ Available | Transform interactions into lasting memories and actionable beliefs |
| 🔍 Smart Information Extraction | ✅ Available | Automatically capture and store relevant user details from conversations |
| 💡 Dynamic Belief Generation | ✅ Available | Create personalized, context-aware insights to guide AI responses |
| 🤖 LLM-Friendly Context | ✅ Available | Seamlessly integrate memory and beliefs into your AI's decision-making process |
| 🔌 Easy Integration | ✅ Available | Plug into your AI applications with a straightforward API |
| 🎭 Conflict Resolution | ✅ Available | Intelligently handle contradictions in user information |
| 🌐 Flexible Architecture | ✅ Available | Designed to work with various LLM providers and models |
| 📊 Memory Management | ✅ Available | Process events, store short-term and long-term memories, and manage beliefs |
| 🔗 Advanced Association Creation | ✅ Available | Form connections between memories and beliefs for more nuanced understanding |
| 🧵 Async Functionality | ✅ Available | Support for asynchronous operations to enhance performance in concurrent environments |
| ⛁ Persistent Database Support | 🔜 Coming Soon | Integration with persistent databases for long-term storage and retrieval of memory data |
| 🎛️ Custom Belief Generation | 🔜 Coming Soon | User-generated beliefs offering end-to-end flexibility in shaping the belief system reasoning|
## 🏗️ Architecture
<img width="663" alt="Screenshot 2024-08-21 at 9 04 07" src="https://github.com/user-attachments/assets/2bdfdaa8-e91c-45b0-b200-2e567daadc5d">
## 🚀 Quick Start
1. Install Tovana:
```bash
pip install tovana
```
2. Use it in your project:
```python
from tovana import MemoryManager
business_description = "a commerce shopping assistant"
message = "I just moved from New York to Paris for work."
user_id = "user123"
# Initialize with your preferred LLM provider and API key (Refer to the documentation for specific models)
memory_manager = MemoryManager(api_key="your-llm-provider-api-key-here", provider="openai",
business_description=business_description, include_beliefs=True)
# Update user memory
memory_manager.update_user_memory(user_id=user_id, message=message)
# Get user memory
user_memory = memory_manager.get_user_memory(user_id=user_id)
print(user_memory) # Output: {'location': 'Paris', 'previous_location': 'New York'}
# Get memory context for LLM
context = memory_manager.get_memory_context(user_id=user_id)
print(context) # Output: 'User Memory:\n location: Paris,\n previous_location: New York'
# Get beliefs
beliefs = memory_manager.get_beliefs(user_id=user_id)
print(beliefs) # Output: {"beliefs": "- Provide recommendations for products shipping to Paris"}
```
## 🧠 Belief Generation
GPT memory introduces a new approach to LLM reasoning: actionable beliefs generated from user memory. These beliefs provide personalized insights that can significantly enhance your agent's planning, reasoning and responses.
### Examples
#### Input:
- `business_description`: "a commerce site"
- `memory`: {'pets': ['dog named charlie', 'horse named luna']}
#### Output:
```json
{"beliefs": ",- suggest pet products for dogs and horses"}
```
#### Input:
- `business_description`: "an AI therapist"
- `memory`: {'pets': ['dog named charlie', 'horse named luna', 'sleep_time: 10pm']}
#### Output:
```json
{"beliefs": ",- Suggest mediation at 9:30pm\n- Suggest spending time with Charlie and Luna for emotional well-being"}
```
## 🛠️ API Reference
### MemoryManager
- `get_memory(user_id: str) -> JSON`: Fetch user memory
- `delete_memory(user_id: str) -> bool`: Delete user memory
- `update_memory(user_id: str, message: str) -> JSON`: Update memory with relevant information if found in message
- `batch_update_memory(user_id: str, messages: List[Dict[str, str]]) -> JSON`: Update memory with relevant information if found in message
- `get_memory_context(user_id: str, message: Optiona[str]) -> str`: Get formatted memory context, general or message specific
- `get_beliefs(user_id: str) -> str`: Get actionable beliefs context
### Batch Update Memory
Traditional per-message memory updates can be costly and inefficient, especially in longer conversations. They often miss crucial context, leading to suboptimal information retrieval.
Our batch memory update method addresses these challenges by processing entire conversations at once. This approach not only improves performance and reduces costs but also enhances the quality of extracted information. This results in a more coherent and accurate user memory, ultimately leading to better AI reasoning.
#### Example
```python
user_id = "user123"
messages = [
{"role": "user", "content": "Hi, I'm planning a trip to Japan."},
{"role": "assistant", "content": "That's exciting! When are you planning to go?"},
{"role": "user", "content": "I'm thinking about next spring. I love sushi and technology."}
]
await memory_manager.batch_update_memory(user_id, messages)
```
### Sync vs Async Updates
This library provides both synchronous and asynchronous update methods to cater to different use cases and application architectures:
1. **Asynchronous Updates (`AsyncMemoryManager`)**: Ideal for applications built on asynchronous frameworks like FastAPI or asynchronous Python scripts. This allows for non-blocking memory updates, improving overall application performance, especially when dealing with I/O-bound operations or high-concurrency scenarios.
2. **Synchronous Updates (`MemoryManager`)**: Suitable for traditional synchronous applications or when you need to ensure that memory updates are completed before proceeding with other operations. This can be useful in scripts or applications where the order of operations is critical.
By providing both options, our library offers flexibility, allowing to choose the most appropriate method based on your specific application requirements and architecture.
## 🤝 Contributing
We welcome contributions! Found a bug or have a feature idea? Open an issue or submit a pull request. Let's make Tovana even better together! 💪
## 📄 License
Tovana is Apache-2.0 licensed. See the [LICENSE](LICENSE) file for details.
---
Ready to empower your AI agents with memory-driven reasoning? Get started with GPT Memory! 🚀 If you find it useful, don't forget to star the repo! ⭐
Raw data
{
"_id": null,
"home_page": "https://github.com/assafelovic/tovana",
"name": "tovana",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Assaf Elovic",
"author_email": "assaf.elovic@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c5/75/3890a2a3f5861332ca544d1cb8ebf970833896226261a9b6908c73f8bbd1/tovana-0.0.9.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n<!--<h1 style=\"display: flex; align-items: center; gap: 10px;\">\n <img src=\"https://github.com/user-attachments/assets/3fb24490-b5f9-4af1-b2eb-8f2f24a6e6b8\" alt=\"Logo\" width=\"25\">\n GPT Memory\n</h1>-->\n<h1>\ud83e\udde0 GPT Memory</h1>\n\n<h3>Memory Driven Reasoning for Smarter AI Agents</h3>\n\nGPT Memory is a library powered by Tovana that introduces a new approach to improving LLM reasoning through actionable insights (aka beliefs) derived from continuous interactions and long term memory.\n\n[](https://badge.fury.io/py/tovana)\n[](https://opensource.org/license/apache-2-0)\n</div>\n\n## Why GPT Memory?\n\nCurrent LLMs face significant limitations in their ability to learn and adapt from user-specific interactions over time. While LLMs excel at processing vast amounts of data, they struggle with ongoing personalization and context-aware learning. This gap restricts their ability to provide truly adaptive and evolving AI experiences.\n\nOur Memory manager aims to address these challenges by providing a comprehensive memory and belief management framework for AI agents. Its core concept revolves around converting experiences (events) into memories, which in turn shape beliefs. These beliefs then influence the agent's reasoning, responses, and actions.\n\nBy simulating human-like memory processes, GPT Memory enables more personalized, adaptive, and context-aware AI interactions. This framework bridges the gap between static knowledge bases and dynamic, experience-based learning, allowing AI agents to evolve their understanding and behavior over time.\n## \ud83c\udf1f Features\n\n| Feature | Status | Description |\n|----------------------------------|-------------|---------------------------------------------------------------------------------------------|\n| \ud83e\udde0 Human-like Memory | \u2705 Available | Transform interactions into lasting memories and actionable beliefs |\n| \ud83d\udd0d Smart Information Extraction | \u2705 Available | Automatically capture and store relevant user details from conversations |\n| \ud83d\udca1 Dynamic Belief Generation | \u2705 Available | Create personalized, context-aware insights to guide AI responses |\n| \ud83e\udd16 LLM-Friendly Context | \u2705 Available | Seamlessly integrate memory and beliefs into your AI's decision-making process |\n| \ud83d\udd0c Easy Integration | \u2705 Available | Plug into your AI applications with a straightforward API |\n| \ud83c\udfad Conflict Resolution | \u2705 Available | Intelligently handle contradictions in user information |\n| \ud83c\udf10 Flexible Architecture | \u2705 Available | Designed to work with various LLM providers and models |\n| \ud83d\udcca Memory Management | \u2705 Available | Process events, store short-term and long-term memories, and manage beliefs |\n| \ud83d\udd17 Advanced Association Creation | \u2705 Available | Form connections between memories and beliefs for more nuanced understanding |\n| \ud83e\uddf5 Async Functionality | \u2705 Available | Support for asynchronous operations to enhance performance in concurrent environments |\n| \u26c1 Persistent Database Support | \ud83d\udd1c Coming Soon | Integration with persistent databases for long-term storage and retrieval of memory data |\n| \ud83c\udf9b\ufe0f Custom Belief Generation | \ud83d\udd1c Coming Soon | User-generated beliefs offering end-to-end flexibility in shaping the belief system reasoning|\n\n## \ud83c\udfd7\ufe0f Architecture\n<img width=\"663\" alt=\"Screenshot 2024-08-21 at 9 04 07\" src=\"https://github.com/user-attachments/assets/2bdfdaa8-e91c-45b0-b200-2e567daadc5d\">\n\n\n\n## \ud83d\ude80 Quick Start\n\n1. Install Tovana:\n```bash\npip install tovana\n```\n\n2. Use it in your project:\n\n```python\nfrom tovana import MemoryManager\n\nbusiness_description = \"a commerce shopping assistant\"\nmessage = \"I just moved from New York to Paris for work.\"\nuser_id = \"user123\"\n\n# Initialize with your preferred LLM provider and API key (Refer to the documentation for specific models)\nmemory_manager = MemoryManager(api_key=\"your-llm-provider-api-key-here\", provider=\"openai\",\n business_description=business_description, include_beliefs=True)\n\n# Update user memory\nmemory_manager.update_user_memory(user_id=user_id, message=message)\n\n# Get user memory\nuser_memory = memory_manager.get_user_memory(user_id=user_id)\nprint(user_memory) # Output: {'location': 'Paris', 'previous_location': 'New York'}\n\n# Get memory context for LLM\ncontext = memory_manager.get_memory_context(user_id=user_id)\nprint(context) # Output: 'User Memory:\\n location: Paris,\\n previous_location: New York'\n\n# Get beliefs\nbeliefs = memory_manager.get_beliefs(user_id=user_id)\nprint(beliefs) # Output: {\"beliefs\": \"- Provide recommendations for products shipping to Paris\"}\n```\n\n## \ud83e\udde0 Belief Generation\n\nGPT memory introduces a new approach to LLM reasoning: actionable beliefs generated from user memory. These beliefs provide personalized insights that can significantly enhance your agent's planning, reasoning and responses.\n\n### Examples\n#### Input:\n- `business_description`: \"a commerce site\"\n- `memory`: {'pets': ['dog named charlie', 'horse named luna']}\n#### Output:\n\n```json\n{\"beliefs\": \",- suggest pet products for dogs and horses\"}\n```\n\n#### Input:\n\n- `business_description`: \"an AI therapist\"\n- `memory`: {'pets': ['dog named charlie', 'horse named luna', 'sleep_time: 10pm']}\n#### Output:\n\n```json\n{\"beliefs\": \",- Suggest mediation at 9:30pm\\n- Suggest spending time with Charlie and Luna for emotional well-being\"}\n```\n\n## \ud83d\udee0\ufe0f API Reference\n\n### MemoryManager\n\n- `get_memory(user_id: str) -> JSON`: Fetch user memory\n- `delete_memory(user_id: str) -> bool`: Delete user memory\n- `update_memory(user_id: str, message: str) -> JSON`: Update memory with relevant information if found in message\n- `batch_update_memory(user_id: str, messages: List[Dict[str, str]]) -> JSON`: Update memory with relevant information if found in message\n- `get_memory_context(user_id: str, message: Optiona[str]) -> str`: Get formatted memory context, general or message specific\n- `get_beliefs(user_id: str) -> str`: Get actionable beliefs context\n\n### Batch Update Memory\nTraditional per-message memory updates can be costly and inefficient, especially in longer conversations. They often miss crucial context, leading to suboptimal information retrieval. \n\nOur batch memory update method addresses these challenges by processing entire conversations at once. This approach not only improves performance and reduces costs but also enhances the quality of extracted information. This results in a more coherent and accurate user memory, ultimately leading to better AI reasoning.\n\n#### Example\n\n```python\nuser_id = \"user123\"\nmessages = [\n {\"role\": \"user\", \"content\": \"Hi, I'm planning a trip to Japan.\"},\n {\"role\": \"assistant\", \"content\": \"That's exciting! When are you planning to go?\"},\n {\"role\": \"user\", \"content\": \"I'm thinking about next spring. I love sushi and technology.\"}\n]\n\nawait memory_manager.batch_update_memory(user_id, messages)\n```\n\n### Sync vs Async Updates\nThis library provides both synchronous and asynchronous update methods to cater to different use cases and application architectures:\n\n1. **Asynchronous Updates (`AsyncMemoryManager`)**: Ideal for applications built on asynchronous frameworks like FastAPI or asynchronous Python scripts. This allows for non-blocking memory updates, improving overall application performance, especially when dealing with I/O-bound operations or high-concurrency scenarios.\n2. **Synchronous Updates (`MemoryManager`)**: Suitable for traditional synchronous applications or when you need to ensure that memory updates are completed before proceeding with other operations. This can be useful in scripts or applications where the order of operations is critical.\n\nBy providing both options, our library offers flexibility, allowing to choose the most appropriate method based on your specific application requirements and architecture.\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Found a bug or have a feature idea? Open an issue or submit a pull request. Let's make Tovana even better together! \ud83d\udcaa\n\n## \ud83d\udcc4 License\n\nTovana is Apache-2.0 licensed. See the [LICENSE](LICENSE) file for details.\n\n---\n\nReady to empower your AI agents with memory-driven reasoning? Get started with GPT Memory! \ud83d\ude80 If you find it useful, don't forget to star the repo! \u2b50\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Memory management library to enhance AI agents with smarter, personalized, context-aware responses",
"version": "0.0.9",
"project_urls": {
"Homepage": "https://github.com/assafelovic/tovana"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a0fd8e7e036d532c264b4cbb23d543704f0147a7075ef32ff2c51ac03dc0e0d9",
"md5": "7bf8bf93d09ea4e544cd5ad7a2d16bba",
"sha256": "98e5c6f4ded5472a900b25f8eaa0f98f49b40b07410c1ff187672b13942708b3"
},
"downloads": -1,
"filename": "tovana-0.0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7bf8bf93d09ea4e544cd5ad7a2d16bba",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 14070,
"upload_time": "2024-08-23T17:27:34",
"upload_time_iso_8601": "2024-08-23T17:27:34.701203Z",
"url": "https://files.pythonhosted.org/packages/a0/fd/8e7e036d532c264b4cbb23d543704f0147a7075ef32ff2c51ac03dc0e0d9/tovana-0.0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c5753890a2a3f5861332ca544d1cb8ebf970833896226261a9b6908c73f8bbd1",
"md5": "65629df1e2a04419a69e6112f319cf1f",
"sha256": "fbe24c3884b807299fa58fedc5a7bcc58bbfc89521589051b4e0ff9fe46c3638"
},
"downloads": -1,
"filename": "tovana-0.0.9.tar.gz",
"has_sig": false,
"md5_digest": "65629df1e2a04419a69e6112f319cf1f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 18074,
"upload_time": "2024-08-23T17:27:35",
"upload_time_iso_8601": "2024-08-23T17:27:35.662736Z",
"url": "https://files.pythonhosted.org/packages/c5/75/3890a2a3f5861332ca544d1cb8ebf970833896226261a9b6908c73f8bbd1/tovana-0.0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-23 17:27:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "assafelovic",
"github_project": "tovana",
"github_not_found": true,
"lcname": "tovana"
}
JSON
