---
title: MemEngine Library
url: https://www.emergentmind.com/topics/memengine-library
type: topic
---

# MemEngine Library

MemEngine is a unified and modular software library designed for development, composition, and deployment of advanced memory models in LLM-based agents. Its framework supplies a hierarchical architecture with extensible components, enabling researchers and practitioners to implement, benchmark, and customize multiple recent memory schemes using a consistent API. MemEngine emphasizes modularity, pluggability, and completeness, supporting rapid prototyping and scalable deployment across research and production contexts [2505.02099].

## 1. Architectural Structure

MemEngine’s architecture organizes all logic and components hierarchically into three core layers, with auxiliary modules for configuration and utilities. Every element is designed to be modular and interchangeable.

- **Layer 1: Memory Functions**  
  This layer exposes atomic capabilities including Encoder, Retrieval, Summarizer, Judge, Reflector, Trigger, Forget, Truncation, Utilization, and LLM-wrapper. Each function operates at a granular level, e.g., `Encoder.embed(text) → ℝᵈ`.

- **Layer 2: Memory Operations**  
  Operations orchestrate combinations of Memory Functions into behaviors such as Store, Recall, Manage, and Optimize. For example, `LTMemoryRecall` composes Encoder + Retrieval, whereas `GAMemoryStore` utilizes Judge + Summarizer.

- **Layer 3: Memory Models**  
  Built-in models wire together operations to realize memory mechanisms. Each exposes a standardized interface:  
    • `reset()`  
    • `store(observation: str)`  
    • `recall(query: str) → str or List[str]`  
    • `manage()`  
    • `optimize()`

- **Configuration Module**  
  The hierarchical config system (YAML/JSON/Python-dict) enables override of defaults at any granularity and validates structure via schema mechanisms.

- **Utility Module**  
  Supports storage backends (in-memory, SQLite, Redis), HTML/CLI visualization, FastAPI remote client/server, and automatic model selector for new tasks.

High-level schema:

```
+-----------------------------+
|        Memory Models        |
|  FUMemory, LTMemory, ...    |
+---------------+-------------+
                |
+---------------v-------------+
|       Memory Operations     |
| Store, Recall, Manage, ...  |
+---------------+-------------+
                |
+---------------v-------------+
|       Memory Functions      |
| Encoder, Retrieval, ...     |
+-----------------------------+
```

## 2. Built-in Memory Model Implementations

MemEngine provides nine memory models, each combining functions and operations through composition. All models implement the five-standard methods listed above, differing in algorithmic internals and operational wiring.

| Model     | Key Mechanism       | Notable Equation / Feature           |
|-----------|--------------------|--------------------------------------|
| FUMemory  | Full buffer        | $M = \text{concat}(m_1, m_2, \dots, m_t)$ |
| LTMemory  | Embedding recall   | $s_i = \frac{\mathbf{q}\cdot\mathbf{k}_i}{\|\mathbf{q}\|\|\mathbf{k}_i\|}$ |
| STMemory  | Recent utterances  | $M = [m_{t-L+1},\dots, m_t]$         |
| GAMemory  | Weighted/contextual| $\lambda_i = \mathrm{LLMJudge}(m_i\mid \text{context}),\ C=\sum_i \lambda_i m_i$ |
| MBMemory  | Multi-layer bank   | Summary: $s = \mathrm{Summarizer}(\{m_i\})$ |
| SCMemory  | Minimal covering   | $\sum_{i=1}^k \lambda_i \ge \tau$    |
| MGMemory  | Hierarchical/OS    | Process, schedule, I/O primitives    |
| RFMemory  | Learn-to-memorize  | $\mathcal{L}_{mem} = -\mathbb{E}_\tau[R(\tau)\log p_\theta(\tau|M)]$ |
| MTMemory  | Semantic tree      | $\text{parent} = \arg\max_v \cos(\mathrm{Encoder}(m_{new}),\,\mathrm{Encoder}(v))$; nodes summarized |

The design enables empirical comparison and ablation within a uniform agent context.

## 3. Programming Interface and Usage Patterns

All essential classes are available via the `memengine` Python package. Agent workflows leverage the following standardized operations:

```python
from memengine import MemEngine, MemoryConfig
from memengine.models import LTMemory, MTMemory
cfg = MemoryConfig.load("ltmemory_default.yaml")
engine = MemEngine(config=cfg)
lt = LTMemory(name="longterm", config=cfg.models.LTMemory)
mt = MTMemory(name="treemem", config=cfg.models.MTMemory)
engine.register(lt)
engine.register(mt)
engine.store(observation_text)
response = some_llm(prompt + engine.recall(query_text))
engine.manage()
engine.optimize()
raw_items = engine.get_storage("longterm").all()
```

Custom model configuration (e.g., GAMemory threshold adjustment) and interactive loops are facilitated directly in Python, with hooks for summarization, reflection, and selective recall.

## 4. Extensibility and Customization Mechanisms

MemEngine’s internals are designed for arbitrary extension at the function, operation, or model level.

- **Base Abstractions**:  
  • `BaseMemoryFunction`, `BaseMemoryOperation`, `BaseMemoryModel`  
- **New Functions**:  
  Subclass, implement `forward`, and register via decorator.
- **New Operations**:  
  Subclass, define `execute`, compose functions as required.
- **New Models**:  
  Subclass, implement five interface methods, aggregate operations via composition.

Additional extension points comprise pipeline hooks (e.g., on_before_store), Pydantic-based config validation, and custom FastAPI endpoint integration for distributed/remote use. This design fosters incorporation of novel mechanisms, functions, and workflows with minimal friction.

## 5. Evaluation and Benchmarking

MemEngine has been evaluated in representative agent-centric tasks:

- Synthetic long-context QA (10K tokens)
- Multi-round dialogue (20 turns)
- Role-playing simulation (50 steps, memory intensity)

Benchmarked metrics:

- Recall Accuracy @ K
- BLEU/ROUGE response quality
- Latency per recall (ms)
- Memory footprint (KB per 1000 tokens)

Selected model results (averaged over five runs):

| Model     | Recall@5 | BLEU-2 | Latency (ms) | Footprint |
|-----------|----------|--------|--------------|-----------|
| FUMemory  | 0.72     | 18.4   | 22           | 512 KB    |
| LTMemory  | 0.85     | 21.7   | 33           | 128 KB    |
| MBMemory  | 0.88     | 23.1   | 47           | 96 KB     |
| MTMemory  | 0.91     | 24.5   | 37           | 112 KB    |
| RFMemory  | 0.89     | 23.8   | 62           | 128 KB    |

Tree-structured memory models (MTMemory) achieve the highest Recall@5, while Reflexion models (RFMemory) demonstrate superior learning-to-memorize capability at increased optimization cost.

## 6. Deployment, Best Practices, and Limitations

- **Dependencies**: Python ≥ 3.8; PyTorch/TensorFlow for LLM wrappers; HuggingFace Transformers > 4.30; FastAPI (optional); Redis/SQLite (backend).
- **Deployment**:  
  • Local install: `pip install memengine`  
  • Remote: `memengine serve --port 8000`
- **Practical Guidance**:  
  Pre-warm encoders; batch memory operations; tune summarization thresholds; monitor database size; prune/summarize regularly; accelerate embeddings/judging with GPU.
- **Common Pitfalls**:  
  Unbounded FUMemory may cause token overflow—truncate buffers. Excessive forgetting can drop salient facts—validate retention on held-out data. Configuration mismatches require strict version locking across experiments.

A plausible implication is that MemEngine’s modularity facilitates comparative and incremental research in agent memory while lowering implementation cost and risk of error.

## 7. Source Availability and Community Usage

MemEngine is distributed open source and publicly accessible at https://github.com/nuster1128/MemEngine. Comprehensive documentation, code examples, and demonstration scripts are provided, supporting both basic and advanced agent architectures.

MemEngine’s standardized interface and extensibility make it a foundational resource for evaluating, composing, and contrasting agent memory models under identical operational conditions [2505.02099].

Source: https://www.emergentmind.com/topics/memengine-library