gllm-memory-binary 0.1.9

A flexible memory system for Gen AI applications

GLLM Memory

Description

A flexible and extensible memory system for AI Agents with Mem0 Platform integration (both cloud and self-hosted), designed following SOLID principles and clean architecture patterns.

Prerequisites

Mandatory

1. Python 3.11+ — Install here
2. pip — Install here
3. uv — Install here
4. gcloud CLI (for authentication) — Install here, then log in using:

   gcloud auth login
   

Mem0 Configuration

Mem0 API Key:

• Get your API key from https://app.mem0.ai/dashboard/api-keys
• For self-hosted deployments, use your server's API key

Optional Self-Hosted Server:

• If using self-hosted Mem0, provide your server URL via MEM0_HOST environment variable

Keep your API key secure and never commit it to version control.

---

📦 Installation

Install from Artifact Registry

This requires authentication via the gcloud CLI.

uv pip install \
  --extra-index-url "https://oauth2accesstoken:$(gcloud auth print-access-token)@glsdk.gdplabs.id/gen-ai-internal/simple/" \
  gllm-memory

---

🔧 Local Development Setup

Prerequisites

1. Python 3.11+ — Install here
2. pip — Install here
3. uv — Install here
4. gcloud CLI — Install here, then log in using:

   gcloud auth login
   

5. Git — Install here
6. Access to the GDP Labs SDK GitHub repository

---

1. Clone Repository

git clone [e-mail]:GDP-ADMIN/gl-sdk.git
cd gl-sdk/libs/gllm-memory

---

2. Setup Authentication

Set the following environment variables to authenticate with internal package indexes:

export UV_INDEX_GEN_AI_INTERNAL_USERNAME=oauth2accesstoken
export UV_INDEX_GEN_AI_INTERNAL_PASSWORD="$(gcloud auth print-access-token)"
export UV_INDEX_GEN_AI_USERNAME=oauth2accesstoken
export UV_INDEX_GEN_AI_PASSWORD="$(gcloud auth print-access-token)"

---

3. Quick Setup

Run:

make setup

---

4. Activate Virtual Environment

source .venv/bin/activate

---

🚀 Quick Start

For Using the Library

1. Install the package:

   uv pip install gllm-memory
   

2. Set your Mem0 API key:

   export MEM0_API_KEY="your_api_key_here"
   

3. For Self-Hosted Mem0 (Optional):

   export MEM0_API_KEY="your_api_key_here"
   export MEM0_HOST="https://your-mem0-server.com"
   

For Development

1. Complete setup (this will install all dependencies, setup pre-commit, and activate the environment):

   make setup
   source .venv/bin/activate
   

2. Set your Mem0 API key:

   export MEM0_API_KEY="your_api_key_here"
   

3. Run the basic usage example:

   # Run the example (includes add, search, list, delete_by_user_query, and delete operations)
   python examples/simple_usage.py
   

Architecture

The system follows a layered architecture below:

┌─────────────────────────────────────────────────────────────┐
│                    Application Layer                        │
├─────────────────────────────────────────────────────────────┤
│                    Memory Manager                           │
├─────────────────────────────────────────────────────────────┤
│                    Memory Client (Base)                     │
├─────────────────────────────────────────────────────────────┤
│                    Provider Layer (Mem0)                    │
├─────────────────────────────────────────────────────────────┤
│                    Mem0 Platform                            │
└─────────────────────────────────────────────────────────────┘

🌐 Self-Hosted Mem0 Support

In addition to the cloud Mem0 Platform, this library supports self-hosted Mem0 servers. You can connect to your own Mem0 deployment by specifying a custom host:

from gllm_memory import MemoryManager

# Cloud usage (default)
manager = MemoryManager(api_key="your-api-key")

# Self-hosted usage
manager = MemoryManager(
    api_key="your-api-key",
    host="https://your-mem0-server.com"
)

Environment Variables:

• MEM0_API_KEY: Your Mem0 API key
• MEM0_HOST: Your self-hosted Mem0 server URL (optional, defaults to cloud)

Core API Methods

The MemoryManager provides a simple, platform-agnostic interface for memory operations:

Available Methods

• add(user_id, agent_id, messages, scopes, metadata, infer) - Add new memories from message objects
• search(query, user_id, agent_id, scopes, metadata, threshold, top_k) - Search and retrieve memories by query (query is required)
• list_memories(user_id, agent_id, scopes, metadata, keywords, page, page_size) - Get all memories with pagination and keywords filtering
• update(memory_id, new_content, metadata, user_id, agent_id, scopes) - Update an existing memory by ID
• delete(memory_ids, user_id, agent_id, scopes, metadata) - Delete memories by IDs or by user/agent identifiers
• delete_by_user_query(query, user_id, agent_id, scopes, metadata, threshold, top_k) - Delete memories by query (query is required)

Method Details

from gllm_memory import MemoryManager
from gllm_inference.schema.message import Message
from gllm_memory.enums import MemoryScope

# Initialize
memory_manager = MemoryManager()

# Add memories using Message objects
messages = [
    Message.user("I love pizza and Italian food"),
    Message.assistant("I'll remember that you love pizza and Italian food"),
]
await memory_manager.add(
    user_id="user_123",
    messages=messages,
    scopes=[MemoryScope.USER],
    metadata={"conversation_id": "chat_001"},  # Optional
    infer=True  # Optional, defaults to True
)

# Retrieve memories (query is required)
memories = await memory_manager.search(
    query="What does the user like to eat?",
    user_id="user_123",
    scopes=[MemoryScope.USER],
    metadata=None,  # Optional
    threshold=0.3,  # Optional, defaults to 0.3
    top_k=10  # Optional, defaults to 10
)

# List all memories with pagination and keywords filtering
all_memories = await memory_manager.list_memories(
    user_id="user_123",
    scopes=[MemoryScope.USER],
    metadata=None,  # Optional
    keywords="food",  # Optional
    page=1,  # Optional, defaults to 1
    page_size=100  # Optional, defaults to 100
)

# Update an existing memory by ID
updated_memory = await memory_manager.update(
    memory_id="memory_uuid_123",
    new_content="Updated memory content",  # Optional
    metadata={"category": "updated_preferences"},  # Optional
    user_id="user_123",
    agent_id="agent_456",
    scopes=[MemoryScope.USER, MemoryScope.ASSISTANT]  # Optional
)

# Delete memories by query (query is required)
deleted = await memory_manager.delete_by_user_query(
    query="food preferences",
    user_id="user_123",
    scopes=[MemoryScope.USER, MemoryScope.ASSISTANT],
    metadata=None,  # Optional
    threshold=0.3,  # Optional, defaults to 0.3
    top_k=10  # Optional, defaults to 10
)

# Delete memories by identifiers
delete_result = await memory_manager.delete(
    memory_ids=None,  # Optional
    user_id="user_123",
    scopes=[MemoryScope.USER, MemoryScope.ASSISTANT],
    metadata=None  # Optional
)

🔧 Code Quality

# Format code with ruff
ruff format gllm_memory/ tests/

# Check code quality
ruff check gllm_memory/ tests/

# Fix auto-fixable issues
ruff check gllm_memory/ tests/ --fix

---

Local Development Utilities

The following Makefile commands are available for quick operations:

Install uv

make install-uv

Install Pre-Commit

make install-pre-commit

Install Dependencies

make install

Update Dependencies

make update

Run Tests

make test

---

Contributing

Please refer to the Python Style Guide for information about code style, documentation standards, and SCA requirements.

Contributing Steps

1. Fork and clone the repository

2. Set up development environment:

   # Complete setup: installs uv, configures auth, installs packages, sets up pre-commit
   make setup
   

3. Activate virtual environment:

   source .venv/bin/activate
   

4. Run tests to ensure everything works:

   make test
   

5. Make your changes and ensure tests pass:

   # Make your changes
   # Ensure tests pass
   make test
   

6. Submit a pull request:

   # Submit a pull request
   git push origin your-branch