452 lines
15 KiB
Text
452 lines
15 KiB
Text
{
|
|
"cells": [
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {},
|
|
"source": [
|
|
"# Memora-OpenAI Tutorial\n",
|
|
"\n",
|
|
"**A drop-in replacement for the OpenAI Python client with automatic memory integration**\n",
|
|
"\n",
|
|
"## What is Memora-OpenAI?\n",
|
|
"\n",
|
|
"`memora-openai` is a transparent wrapper around the official OpenAI Python client that automatically:\n",
|
|
"\n",
|
|
"- 🧠 **Injects relevant memories** from your Memora system into conversations\n",
|
|
"- 💾 **Stores conversation history** to Memora for future retrieval \n",
|
|
"- 🔄 **Works seamlessly** with existing OpenAI code (just change the import)\n",
|
|
"- ⚡ **Supports both sync and async** clients\n",
|
|
"\n",
|
|
"## Why Use It?\n",
|
|
"\n",
|
|
"### The Problem\n",
|
|
"\n",
|
|
"AI assistants typically have no memory of previous conversations. Each interaction starts fresh, requiring you to:\n",
|
|
"- Repeat context manually\n",
|
|
"- Copy-paste relevant information\n",
|
|
"- Build custom RAG pipelines\n",
|
|
"- Manage conversation history yourself\n",
|
|
"\n",
|
|
"### The Solution\n",
|
|
"\n",
|
|
"Memora-OpenAI gives your AI **automatic long-term memory**:\n",
|
|
"- Remembers past conversations\n",
|
|
"- Recalls user preferences and facts\n",
|
|
"- Maintains context across sessions\n",
|
|
"- Zero code changes to your existing OpenAI usage\n",
|
|
"\n",
|
|
"## Prerequisites\n",
|
|
"\n",
|
|
"1. **Memora API server running** (see main Memora README)\n",
|
|
"2. **OpenAI API key** or compatible API (Groq, OpenRouter, etc.)\n",
|
|
"3. **Python >= 3.10**"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Installation\n",
|
|
"\n",
|
|
"```bash\n",
|
|
"cd memora-openai\n",
|
|
"uv pip install -e .\n",
|
|
"```"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Setup\n",
|
|
"\n",
|
|
"First, let's set up our environment and configure Memora integration:"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {},
|
|
"outputs": [],
|
|
"source": [
|
|
"import os\n",
|
|
"from memora_openai import configure, OpenAI\n",
|
|
"\n",
|
|
"# Set your API keys\n",
|
|
"# Option 1: Use Groq (fast and free)\n",
|
|
"GROQ_API_KEY = os.getenv(\"GROQ_API_KEY\", \"your-groq-api-key\")\n",
|
|
"\n",
|
|
"# Option 2: Use OpenAI\n",
|
|
"# OPENAI_API_KEY = os.getenv(\"OPENAI_API_KEY\", \"sk-...\")\n",
|
|
"\n",
|
|
"# Configure Memora integration\n",
|
|
"configure(\n",
|
|
" memora_api_url=\"http://localhost:8000\", # Your Memora API server\n",
|
|
" agent_id=\"tutorial-user\", # Unique ID for this user/agent\n",
|
|
" store_conversations=True, # Auto-save conversations\n",
|
|
" inject_memories=True, # Auto-inject relevant context\n",
|
|
" memory_search_budget=10, # Number of memories to retrieve\n",
|
|
")\n",
|
|
"\n",
|
|
"print(\"✓ Memora configured successfully!\")"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Example 1: Basic Usage (No Changes Needed!)\n",
|
|
"\n",
|
|
"Use the OpenAI client exactly as you normally would. Memora works transparently in the background."
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {},
|
|
"outputs": [],
|
|
"source": [
|
|
"# Create client (using Groq's OpenAI-compatible API)\n",
|
|
"client = OpenAI(\n",
|
|
" api_key=GROQ_API_KEY,\n",
|
|
" base_url=\"https://api.groq.com/openai/v1\",\n",
|
|
")\n",
|
|
"\n",
|
|
"# First conversation - establish some facts\n",
|
|
"print(\"=== First Conversation ===\")\n",
|
|
"response = client.chat.completions.create(\n",
|
|
" model=\"llama-3.1-8b-instant\",\n",
|
|
" messages=[\n",
|
|
" {\"role\": \"user\", \"content\": \"My name is Alice and I love Python programming!\"}\n",
|
|
" ],\n",
|
|
")\n",
|
|
"\n",
|
|
"print(f\"Assistant: {response.choices[0].message.content}\\n\")\n",
|
|
"print(\"→ This conversation is now stored in Memora!\")"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Example 2: Memory Injection in Action\n",
|
|
"\n",
|
|
"Now ask a question that requires remembering the previous conversation:"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {},
|
|
"outputs": [],
|
|
"source": [
|
|
"print(\"=== Second Conversation (with memory) ===\")\n",
|
|
"response = client.chat.completions.create(\n",
|
|
" model=\"llama-3.1-8b-instant\",\n",
|
|
" messages=[\n",
|
|
" {\"role\": \"user\", \"content\": \"What's my name and what do I like?\"}\n",
|
|
" ],\n",
|
|
")\n",
|
|
"\n",
|
|
"print(f\"Assistant: {response.choices[0].message.content}\\n\")\n",
|
|
"print(\"→ Memora automatically injected relevant memories before this request!\")\n",
|
|
"print(\"→ The AI knew your name and preferences without you repeating them.\")"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {},
|
|
"source": [
|
|
"## How It Works\n",
|
|
"\n",
|
|
"Behind the scenes, Memora-OpenAI:\n",
|
|
"\n",
|
|
"### 1. **Memory Storage**\n",
|
|
"After each API call:\n",
|
|
"- Captures the full conversation context\n",
|
|
"- Stores it in Memora's semantic memory system\n",
|
|
"- Indexes it for fast retrieval\n",
|
|
"\n",
|
|
"### 2. **Memory Injection**\n",
|
|
"Before each API call:\n",
|
|
"- Extracts the user's query\n",
|
|
"- Searches Memora for relevant past conversations\n",
|
|
"- Injects top memories as a system message\n",
|
|
"\n",
|
|
"### What Gets Sent to OpenAI\n",
|
|
"\n",
|
|
"Without Memora:\n",
|
|
"```python\n",
|
|
"messages = [\n",
|
|
" {\"role\": \"user\", \"content\": \"What's my name?\"}\n",
|
|
"]\n",
|
|
"```\n",
|
|
"\n",
|
|
"With Memora (automatic):\n",
|
|
"```python\n",
|
|
"messages = [\n",
|
|
" {\n",
|
|
" \"role\": \"system\",\n",
|
|
" \"content\": \"Relevant context from your memory:\\n\\n1. User's name is Alice\\n (Date: 2024-11-18)\\n (Type: world)\"\n",
|
|
" },\n",
|
|
" {\"role\": \"user\", \"content\": \"What's my name?\"}\n",
|
|
"]\n",
|
|
"```"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Example 3: Multi-Turn Conversations\n",
|
|
"\n",
|
|
"Build up context over multiple interactions:"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {},
|
|
"outputs": [],
|
|
"source": [
|
|
"# Conversation 1: Share a preference\n",
|
|
"print(\"=== Conversation 1: Sharing preferences ===\")\n",
|
|
"response = client.chat.completions.create(\n",
|
|
" model=\"llama-3.1-8b-instant\",\n",
|
|
" messages=[\n",
|
|
" {\"role\": \"user\", \"content\": \"I'm working on a machine learning project using PyTorch.\"}\n",
|
|
" ],\n",
|
|
")\n",
|
|
"print(f\"Assistant: {response.choices[0].message.content}\\n\")\n",
|
|
"\n",
|
|
"# Conversation 2: Different topic\n",
|
|
"print(\"=== Conversation 2: Different topic ===\")\n",
|
|
"response = client.chat.completions.create(\n",
|
|
" model=\"llama-3.1-8b-instant\",\n",
|
|
" messages=[\n",
|
|
" {\"role\": \"user\", \"content\": \"I prefer functional programming over OOP.\"}\n",
|
|
" ],\n",
|
|
")\n",
|
|
"print(f\"Assistant: {response.choices[0].message.content}\\n\")\n",
|
|
"\n",
|
|
"# Conversation 3: Ask for recommendations\n",
|
|
"print(\"=== Conversation 3: Getting personalized advice ===\")\n",
|
|
"response = client.chat.completions.create(\n",
|
|
" model=\"llama-3.1-8b-instant\",\n",
|
|
" messages=[\n",
|
|
" {\"role\": \"user\", \"content\": \"Can you recommend a good book for me based on what you know?\"}\n",
|
|
" ],\n",
|
|
")\n",
|
|
"print(f\"Assistant: {response.choices[0].message.content}\\n\")\n",
|
|
"print(\"→ The AI used your programming interests and preferences to make recommendations!\")"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Example 4: Document Grouping\n",
|
|
"\n",
|
|
"Group related conversations using `document_id`:"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {},
|
|
"outputs": [],
|
|
"source": [
|
|
"from memora_openai import configure\n",
|
|
"\n",
|
|
"# Configure with document ID for a specific project\n",
|
|
"configure(\n",
|
|
" memora_api_url=\"http://localhost:8000\",\n",
|
|
" agent_id=\"tutorial-user\",\n",
|
|
" document_id=\"ml-project-2024\", # All conversations tagged with this ID\n",
|
|
")\n",
|
|
"\n",
|
|
"# All these conversations will be grouped together\n",
|
|
"conversations = [\n",
|
|
" \"I'm using ResNet for image classification\",\n",
|
|
" \"My dataset has 10,000 images\",\n",
|
|
" \"Training accuracy is stuck at 65%\",\n",
|
|
"]\n",
|
|
"\n",
|
|
"for msg in conversations:\n",
|
|
" response = client.chat.completions.create(\n",
|
|
" model=\"llama-3.1-8b-instant\",\n",
|
|
" messages=[{\"role\": \"user\", \"content\": msg}],\n",
|
|
" )\n",
|
|
" print(f\"User: {msg}\")\n",
|
|
" print(f\"Assistant: {response.choices[0].message.content}\\n\")\n",
|
|
"\n",
|
|
"print(\"→ All these conversations are grouped under document 'ml-project-2024'\")"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Example 5: Async Support\n",
|
|
"\n",
|
|
"Works perfectly with AsyncOpenAI for high-throughput applications:"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {},
|
|
"outputs": [],
|
|
"source": [
|
|
"from memora_openai import AsyncOpenAI\n",
|
|
"import asyncio\n",
|
|
"\n",
|
|
"async def async_example():\n",
|
|
" # Create async client\n",
|
|
" async_client = AsyncOpenAI(\n",
|
|
" api_key=GROQ_API_KEY,\n",
|
|
" base_url=\"https://api.groq.com/openai/v1\",\n",
|
|
" )\n",
|
|
" \n",
|
|
" # Store a fact\n",
|
|
" print(\"=== Storing fact ===\")\n",
|
|
" response = await async_client.chat.completions.create(\n",
|
|
" model=\"llama-3.1-8b-instant\",\n",
|
|
" messages=[{\"role\": \"user\", \"content\": \"My favorite color is blue.\"}],\n",
|
|
" )\n",
|
|
" print(f\"Assistant: {response.choices[0].message.content}\\n\")\n",
|
|
" \n",
|
|
" # Query with memory\n",
|
|
" print(\"=== Querying with memory ===\")\n",
|
|
" response = await async_client.chat.completions.create(\n",
|
|
" model=\"llama-3.1-8b-instant\",\n",
|
|
" messages=[{\"role\": \"user\", \"content\": \"What's my favorite color?\"}],\n",
|
|
" )\n",
|
|
" print(f\"Assistant: {response.choices[0].message.content}\\n\")\n",
|
|
"\n",
|
|
"# Run async example\n",
|
|
"await async_example()\n",
|
|
"print(\"→ Async operations work seamlessly with Memora!\")"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Configuration Options\n",
|
|
"\n",
|
|
"Fine-tune Memora's behavior:"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "code",
|
|
"execution_count": null,
|
|
"metadata": {},
|
|
"outputs": [],
|
|
"source": [
|
|
"from memora_openai import configure\n",
|
|
"\n",
|
|
"# Full configuration example\n",
|
|
"configure(\n",
|
|
" memora_api_url=\"http://localhost:8000\", # Memora API URL\n",
|
|
" agent_id=\"my-agent\", # Agent identifier (required)\n",
|
|
" api_key=None, # Optional Memora API key\n",
|
|
" \n",
|
|
" # Features\n",
|
|
" store_conversations=True, # Store conversations automatically\n",
|
|
" inject_memories=True, # Inject memories automatically\n",
|
|
" \n",
|
|
" # Memory retrieval\n",
|
|
" memory_search_budget=10, # Number of memories to retrieve\n",
|
|
" \n",
|
|
" # Context management\n",
|
|
" context_window=10, # Recent conversation turns to store\n",
|
|
" \n",
|
|
" # Organization\n",
|
|
" document_id=\"session-123\", # Optional document grouping\n",
|
|
" event_timestamp=None, # Optional custom timestamp\n",
|
|
" \n",
|
|
" # Control\n",
|
|
" enabled=True, # Master on/off switch\n",
|
|
")\n",
|
|
"\n",
|
|
"print(\"Configuration options explained:\")\n",
|
|
"print(\"- memory_search_budget: Higher = more context, but more tokens\")\n",
|
|
"print(\"- context_window: How many recent messages to include when storing\")\n",
|
|
"print(\"- document_id: Group related conversations together\")\n",
|
|
"print(\"- enabled=False: Disable Memora without changing code\")"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {},
|
|
"source": [
|
|
"## Use Cases\n",
|
|
"\n",
|
|
"### 1. **Personal AI Assistant**\n",
|
|
"- Remembers your preferences, work history, and interests\n",
|
|
"- Provides personalized recommendations\n",
|
|
"- Maintains context across days/weeks\n",
|
|
"\n",
|
|
"### 2. **Customer Support Chatbot**\n",
|
|
"- Recalls previous support tickets\n",
|
|
"- Knows customer preferences and history\n",
|
|
"- Provides consistent, context-aware responses\n",
|
|
"\n",
|
|
"### 3. **Research Assistant**\n",
|
|
"- Remembers documents you've discussed\n",
|
|
"- Connects related topics from different sessions\n",
|
|
"- Builds knowledge over time\n",
|
|
"\n",
|
|
"### 4. **Code Review Tool**\n",
|
|
"- Remembers project architecture decisions\n",
|
|
"- Recalls past code review comments\n",
|
|
"- Maintains consistency across reviews\n",
|
|
"\n",
|
|
"## Benefits Summary\n",
|
|
"\n",
|
|
"✅ **Zero Code Changes** - Drop-in replacement for OpenAI client \n",
|
|
"✅ **Automatic Context** - No manual RAG pipeline needed \n",
|
|
"✅ **Long-term Memory** - Conversations persist across sessions \n",
|
|
"✅ **Smart Retrieval** - Semantic search finds relevant context \n",
|
|
"✅ **Both Sync/Async** - Works with any OpenAI client pattern \n",
|
|
"✅ **Configurable** - Fine-tune behavior to your needs \n",
|
|
"✅ **Transparent** - Original OpenAI responses unchanged \n",
|
|
"\n",
|
|
"## Next Steps\n",
|
|
"\n",
|
|
"- **Explore Memora API**: Check out `memora/README.md` for advanced features\n",
|
|
"- **Customize Search**: Tune `memory_search_budget` for your use case\n",
|
|
"- **Use Document IDs**: Organize conversations by project/session\n",
|
|
"- **Try Different Models**: Works with OpenAI, Groq, Ollama, and more\n",
|
|
"\n",
|
|
"## Resources\n",
|
|
"\n",
|
|
"- [Memora Main README](../README.md) - Core memory system docs\n",
|
|
"- [Memora-OpenAI README](README.md) - Package documentation\n",
|
|
"- [OpenAI API Docs](https://platform.openai.com/docs/api-reference) - Original API reference\n"
|
|
]
|
|
}
|
|
],
|
|
"metadata": {
|
|
"kernelspec": {
|
|
"display_name": "Python 3",
|
|
"language": "python",
|
|
"name": "python3"
|
|
},
|
|
"language_info": {
|
|
"codemirror_mode": {
|
|
"name": "ipython",
|
|
"version": 3
|
|
},
|
|
"file_extension": ".py",
|
|
"mimetype": "text/x-python",
|
|
"name": "python",
|
|
"nbconvert_exporter": "python",
|
|
"pygments_lexer": "ipython3",
|
|
"version": "3.11.0"
|
|
}
|
|
},
|
|
"nbformat": 4,
|
|
"nbformat_minor": 4
|
|
}
|