GLLM Memory

Description

Memory layer for AI agents. The public API is MemoryManager. You can use it in two ways:

1. HTTP mode: use api_key and optional host
2. SDK mode: use MemoryManagerConfig and pass config=...

In SDK mode, you can register your own LLM, embedding model, memory store, and optional reranker without exposing backend-specific config to application code.

TL;DR / 30-Second Example

Fastest HTTP mode example:

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

memory_manager = MemoryManager(api_key="your_mem0_api_key")

await memory_manager.add(
    user_id="user_123",
    agent_id="agent_456",
    messages=[Message.user("I love pizza")],
    scopes={MemoryScope.USER},
)

results = await memory_manager.search(
    query="What does the user like?",
    user_id="user_123",
    scopes={MemoryScope.USER},
)

For the recommended SDK mode setup with MemoryManagerConfig, see SDK Mode.

Installation & Setup

Requirements

1. Python 3.11+ — Install here
2. pip or uv — pip, uv
3. gcloud CLI — Install here
4. Git — only needed for local development from a cloned repository

Authentication

Use this once when you need internal packages or local development setup:

gcloud auth login
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)"

Install from Artifact Registry

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

Install from Local Clone

git clone git@github.com:GDP-ADMIN/gl-sdk.git
cd gl-sdk/libs/gllm-memory
pip install -e .

For the full local development setup with project tooling:

make setup
source .venv/bin/activate

Runtime Notes

1. HTTP mode uses MEM0_API_KEY and optional MEM0_HOST.
2. SDK mode uses MemoryManagerConfig(...) and lets your app register LM, embedding, memory store, and optional retrieval reranker.

Optional Dependencies

1. OpenAI-based SDK examples require OpenAI support from gllm-inference, for example gllm-inference[openai].
2. Knowledge graph examples require the KG dependencies used by this repository setup.

Typical environment variables:

Do not commit secrets to git.

Error Handling

Public configuration and provider failures use typed errors with stable GLLM-MEM-* codes. Applications can use error.code to select a user-facing message without depending on provider-specific exception text.

See the Error Code Catalog for each code, its trigger, and recommended recovery action.

Relevant errors also include recovery metadata. Check recovery.retryable before retrying. Retryable errors use the caller_owned policy: the caller sets the retry limit and backoff. When present, wait at least recovery.retry_after_seconds before retrying and use recovery.escalate_when to decide when to escalate the failure.

For public-boundary behavior and documented exceptions, see the Error Boundary Audit.

Semantic Memory Dedupe

gllm-memory includes one internal background maintenance job for retrieval-based vector retention, semantic dedupe, and persistent Mem0 SQLite audit-history retention.

You do not call this job directly from MemoryManager. When memory maintenance is enabled, the scheduler is registered automatically during MemoryManager initialization.

What it does:

1. scans recent memories from the configured vector store
2. groups candidates inside one partition: scope + user_id + agent_id + source + target
3. finds semantically similar memories using embedding similarity
4. keeps one canonical memory and removes duplicate rows when it is safe
5. hard-deletes non-important vector memories that have not been retrieved for MEMORY_RETENTION_DAYS
6. removes persistent Mem0 SQLite audit-history events older than MEMORY_RETENTION_DAYS

Safety rules in the current implementation:

1. is_important=True memories are never deleted
2. canonical priority is: important > newer > richer content > older
3. if compatible memories are in the same context, the canonical memory can be updated with merged content before duplicate rows are deleted
4. if custom metadata conflicts, that duplicate group is skipped
5. deletion is hard delete from the vector store

Current behavior:

1. the first version uses embedding-only comparison
2. retention runs only when MEMORY_RETENTION_ENABLED=true; semantic dedupe runs only when MEMORY_DEDUP_ENABLED=true
3. the default schedule is Saturday at 01:00
4. the timezone follows the server-local timezone where gllm-memory runs
5. the default lookback window is the last 7 days using created_at OR updated_at
6. the default large-partition safeguard is MEMORY_DEDUP_MAX_TARGET_MEMORIES=5000
7. the in-process registry prevents duplicate local schedulers and Elasticsearch lease ownership permits one active run per vector-store target across pods
8. the current full-store scanner implementation is available for Elasticsearch-backed vector stores
9. SQLite history retention runs only for persistent SDK history_db_path; it skips in-memory history and does not automatically run VACUUM

Architecture

The system follows a layered architecture below:

┌──────────────────────────────────────────────────────────────┐
│                    Application Layer                         │
├──────────────────────────────────────────────────────────────┤
│                    Memory Manager                            │
├──────────────────────────────────────────────────────────────┤
│                    Memory Client (Base)                      │
├──────────────────────────────────────────────────────────────┤
│                    Provider Layer (Mem0)                     │
├──────────────────────────────────────────────────────────────┤
│                    Mem0 Platform (HTTP client or Python SDK) │
└──────────────────────────────────────────────────────────────┘

🧩 SDK Mode With MemoryManagerConfig

Use this mode if you want to:

1. register memory LLM and embedding invoker runtimes
2. configure an optional reranker
3. keep application code independent from backend-specific config shape

gllm-memory does not create provider-specific LM or embedding invokers for you in normal SDK usage. Your application builds the LM invoker, optional fallback invokers, one embedding invoker, and then wraps the memory LLM path with the library-owned MemoryLMComponent.

SDK Mode Example

Recommended LLM registration:

from gllm_inference.lm_invoker.lm_invoker import BaseLMInvoker
from gllm_inference.lm_invoker.openai_lm_invoker import OpenAILMInvoker
from gllm_memory import MemoryLMComponent, MemoryManagerConfig


def build_openai_lm_invoker(model_name: str) -> OpenAILMInvoker:
    return OpenAILMInvoker(
        model_name=model_name,
        api_key="your_openai_api_key",
    )


def build_fallback_lm_invokers() -> list[BaseLMInvoker]:
    return [
        build_openai_lm_invoker("gpt-4o-mini"),
    ]


def build_lm_component() -> MemoryLMComponent:
    return MemoryLMComponent(
        lm_invoker=build_openai_lm_invoker("gpt-5-nano"),
        fallback_lms=build_fallback_lm_invokers() or None,
    )


def build_em_invoker():
    from gllm_inference.em_invoker.openai_em_invoker import OpenAIEMInvoker

    return OpenAIEMInvoker(
        model_name="text-embedding-3-small",
        api_key="your_openai_api_key",
    )


lm_component = build_lm_component()
em_invoker = build_em_invoker()

config = (
    MemoryManagerConfig.builder()
    .memory_store.elasticsearch(
        host="localhost",
        port=9200,
        collection_name="memories",
        embedding_model_dims=1536,
    )
    .embedding.register(
        em_invoker,
        embedding_dims=1536,
    )
    .llm.register_component(lm_component)
    .reranker.similarity_based(
        em_invoker,
        top_k=5,
    )
    .build()
)

In this path, em_invoker and the underlying LM invokers are created by your application, while MemoryLMComponent is owned by gllm-memory. MemoryManager.instruction remains the source of truth for memory extraction instructions, and lm_component can route from one primary LM to fallback_lms when the primary LM fails.

The reranker is optional. If you do not need retrieval reranking, omit .reranker.similarity_based(...) from the builder. When configured with similarity_based(...), reranking runs in the external retrieval layer after provider retrieval returns chunks. The provider keeps native backend rerank disabled for this path so the request does not run double reranking. If your installed gllm_inference version still has a circular import on OpenAIEMInvoker, instantiate the EM invoker with a local lazy import like the example above.

SDK Mode With Default Config

If you want to use the default SDK setup, you can build an empty config:

from gllm_memory import MemoryManager, MemoryManagerConfig

config = MemoryManagerConfig.builder().build()
memory_manager = MemoryManager(config=config)

Default SDK behavior:

1. memory store uses Elasticsearch
2. embedding uses gllm-inference: EM Invoker with OpenAI defaults
3. llm uses gllm-inference OpenAI defaults
4. reranker is omitted unless configured explicitly

Required environment variables for the default SDK config:

1. ELASTICSEARCH_HOST
2. ELASTICSEARCH_PORT
3. ELASTICSEARCH_COLLECTION_NAME
4. ELASTICSEARCH_EMBEDDING_MODEL_DIMS
5. OPENAI_API_KEY

Optional environment variables:

1. ELASTICSEARCH_USER
2. ELASTICSEARCH_PASSWORD
3. OPENAI_BASE_URL
4. OPENAI_MODEL_NAME (default SDK LLM model override)
5. OPENAI_EMBEDDING_MODEL (used by examples/example_mem0_sdk_client.py)
6. MEMORY_RETENTION_ENABLED (default false)
7. MEMORY_RETENTION_CRON_DAY (default sat)
8. MEMORY_RETENTION_CRON_HOUR (default 1)
9. MEMORY_RETENTION_CRON_MINUTE (default 0)
10. MEMORY_RETENTION_DAYS (default 90)
11. MEMORY_DEDUP_ENABLED (default false)
12. MEMORY_DEDUP_SIMILARITY_THRESHOLD (default 0.65)

Elasticsearch transport safety:

1. A host that already includes http:// or https:// keeps that scheme.
2. A hostname-only config that omits use_ssl uses the SDK default, which is HTTP.
3. For a hostname-only HTTPS deployment, set use_ssl=True explicitly in the Elasticsearch memory-store config.

🌐 HTTP Mode

Use this mode if you want to connect to the HTTP API directly. Point the client at your own server:

from gllm_memory import MemoryManager

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

If you want local SDK mode, use MemoryManager(config=...) instead of api_key and host.

HTTP Mode Example

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

memory_manager = MemoryManager(api_key="...", host="...")  # host optional

messages = [
    Message.user("I love pizza"),
    Message.assistant("Noted."),
]
await memory_manager.add(
    user_id="user_123",
    agent_id="agent_456",
    messages=messages,
    scopes={MemoryScope.USER},
    metadata={"conversation_id": "chat_001"},  # Optional
    infer=True,  # Optional, defaults to True
    is_important=False,  # Optional, defaults to False
)

memories = await memory_manager.search(
    query="What does the user like?",
    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
    include_important=False,  # Optional, defaults to False
    rerank=False,  # Optional, defaults to False; if True, applies re-ranking to results
)

🕸️ Knowledge Graph in GLLM Memory

gllm-memory can optionally use a Knowledge Graph (KG) so one search flow can combine:

1. normal memory retrieval
2. graph-based facts such as people, companies, places, and relationships

Enable it with the same public API:

memory_manager = MemoryManager(config=config)

Recommended setup:

from gllm_inference.lm_invoker.openai_lm_invoker import OpenAILMInvoker
from gllm_memory import MemoryManager, MemoryManagerConfig, Neo4jGraphStoreConfig

memory_lm_component = build_lm_component()
em_invoker = build_em_invoker()

kg_lm_invoker = OpenAILMInvoker(
    model_name="gpt-4o-mini",
    api_key="your_openai_api_key",
)

config = (
    MemoryManagerConfig.builder()
    .memory_store.elasticsearch(
        host="localhost",
        port=9200,
        collection_name="memories",
        embedding_model_dims=1536,
    )
    .embedding.register(
        em_invoker,
        embedding_dims=1536,
    )
    .llm.register_component(memory_lm_component)
    .knowledge_graph.enable(
        lm_invoker=kg_lm_invoker,
        graph_store=Neo4jGraphStoreConfig(
            uri="bolt://localhost:7687",
            user="neo4j",
            password="password",
        ),
    )
    .build()
)

memory_manager = MemoryManager(config=config)

MemoryManager enables KG automatically when the config contains a knowledge_graph section.

Detailed KG flows, storage isolation, update behavior, and delete behavior are documented in docs/knowledge-graph.md.

Core API methods

MemoryManager exposes async methods; query is required where noted.

Usage examples:

1. SDK mode example: see SDK Mode With MemoryManagerConfig
2. HTTP mode example: see 🌐 HTTP Mode

Methods

• add(user_id, agent_id, messages, scopes, metadata, infer, is_important) -> list[Chunk] - Add new memories from message objects.
• search(query, user_id, agent_id, scopes, metadata, threshold, top_k, include_important, rerank) -> list[Chunk] - Search and retrieve memories by query.
• list_memories(user_id, agent_id, scopes, metadata, keywords, page, page_size) -> list[Chunk] - Get memories with pagination and optional keyword filtering.
• update(memory_id, new_content, metadata, user_id, agent_id, scopes, is_important) -> Chunk | None - Update one existing memory by ID.
• delete(memory_ids, user_id, agent_id, scopes, metadata) -> list[Chunk] - Delete memories by IDs or by user or agent identifiers. When KG is enabled, the related KG contribution is also cleaned up.
• delete_by_user_query(query, user_id, agent_id, scopes, metadata, threshold, top_k) -> list[Chunk] - Delete memories by query. When KG is enabled, the related KG contribution is also cleaned up.

🔧 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