# Redis Memory Limit: maxmemory Configuration, Eviction Policies, and OOM Prevention

The Redis memory limit is configured via the maxmemory directive, defining the absolute ceiling of RAM Redis can allocate before triggering key eviction policies or throwing OOM errors. Without an explicit memory ceiling, 64-bit systems consume all available host RAM until the operating system terminates the process. Choosing the correct eviction policy and reserving headroom for allocator fragmentation prevents write rejections and protects critical session state.

Source: https://fast.io/resources/redis-memory-limit/
Author: [Derek Labian](https://fast.io/authors/derek-labian/)
Last reviewed: 2026-10-18

## How Redis Allocates Memory and Configures Default Limits

According to official Redis documentation on key eviction, 64-bit operating systems default to a maxmemory setting of zero, allowing the database process to allocate memory without an internal ceiling until the host exhausts physical RAM. In contrast, 32-bit systems enforce an implicit 3GB memory ceiling. When an unconstrained instance consumes all host memory, the Linux kernel Out-Of-Memory killer abruptly terminates the redis-server process, causing immediate downtime and data loss.

The Redis memory limit is configured via the maxmemory directive, defining the absolute ceiling of RAM Redis can allocate before triggering key eviction policies or throwing OOM errors.

Redis tracks allocated memory through its internal memory allocator, which defaults to jemalloc on Linux builds. The `used_memory` metric measures the raw bytes allocated for user data, keys, and internal data structures. However, operating systems measure memory consumption in terms of Resident Set Size (RSS), representing the physical RAM pages assigned to the process. Because memory allocators manage memory in discrete pages and arenas, `used_memory_rss` is almost always higher than `used_memory`.

### Setting maxmemory in Configuration and at Runtime

You can define the memory limit statically in your `redis.conf` configuration file:

```text
maxmemory 4gb
```

Redis parses standard memory units:
- `b` for bytes
- `k` and `kb` for kilobytes
- `m` and `mb` for megabytes
- `g` and `gb` for gigabytes

Memory unit designations are case-insensitive (`4gb`, `4GB`, `4096mb`).

To configure the memory limit on a running production instance without restarting the process, execute `CONFIG SET` using `redis-cli`:

```bash
redis-cli CONFIG SET maxmemory 4gb
redis-cli CONFIG REWRITE
```

Running `CONFIG REWRITE` persists the runtime change to your active `redis.conf` file, ensuring that the setting survives server restarts.

### Sizing Guidelines: The Sizing Headroom Rule

A common operational mistake is setting `maxmemory` to match total physical RAM. Doing so exposes the instance to operating system termination because Redis requires auxiliary memory beyond its raw key-value store:

1. **Memory Allocator Fragmentation:** Allocators like jemalloc group allocations into fixed-size bins. Freeing keys does not always release memory pages back to the kernel immediately, creating fragmentation gaps.
2. **Replication Output Buffers:** When replicas fall behind or execute initial synchronization, the primary node buffers commands in memory (`client-output-buffer-limit`).
3. **Copy-on-Write (CoW) Overhead:** Background persistence snapshots (`BGSAVE`) and Append Only File rewrites (`BGREWRITEAOF`) invoke `fork()`. While modern kernels share pages between parent and child processes, incoming write operations force page duplicates, temporarily expanding physical memory usage.
4. **Client Connection Overhead:** Each connected client consumes memory for input query buffers and output response buffers.

In production environments, set `maxmemory` to roughly three-quarters of total system RAM, reserving the remaining headroom for system processes, replication streams, and allocator overhead. The table below outlines recommended allocation thresholds for dedicated Redis hosts:

| Total Host RAM | Recommended maxmemory | Headroom Reserved | Primary Risk if Over-Allocated |
|---|---|---|---|
| 8 GB | 5.5 GB | 2.5 GB | Kernel OOM termination during background AOF rewrite |
| 16 GB | 11.5 GB | 4.5 GB | Replication buffer spikes during cluster resync |
| 32 GB | 24 GB | 8 GB | jemalloc page fragmentation under high key churn |
| 64 GB | 48 GB | 16 GB | Copy-on-Write expansion during heavy persistence writes |
| 128 GB | 96 GB | 32 GB | Connection buffer spikes and large vector index rebuilds |

## How to Choose the Right Redis maxmemory-policy

When the memory consumed by Redis reaches the threshold defined by `maxmemory`, the server inspects the `maxmemory-policy` configuration directive. This setting determines whether Redis frees space by deleting existing keys or rejects incoming write operations.

Redis supports 8 standard eviction policies:

1. **`noeviction`:** Redis never evicts data. When the memory limit is reached, write commands fail with an out-of-memory error. Read-only commands continue to execute. This is the default policy in Redis 6.2 and later releases.
2. **`allkeys-lru`:** Evicts the least recently used keys across the entire database, regardless of whether a Time-To-Live (TTL) is set.
3. **`allkeys-lfu`:** Evicts the least frequently used keys across the entire dataset, tracking access frequency via a logarithmic counter.
4. **`allkeys-random`:** Deletes keys chosen at random across the entire dataset to recover memory.
5. **`volatile-lru`:** Evicts the least recently used keys, but only evaluates keys that have an explicit expiration set via `EXPIRE` or `SETEX`.
6. **`volatile-lfu`:** Evicts the least frequently used keys among those with an expiration set.
7. **`volatile-random`:** Randomly deletes keys from the pool of keys that possess an expiration.
8. **`volatile-ttl`:** Evicts keys with an explicit expiration, prioritizing keys with the shortest remaining time-to-live.

Recent Redis versions also introduce `allkeys-lrm` and `volatile-lrm`, which evict keys based on the least recently modified timestamp rather than read access.

### Top Three Eviction Policies for Production Architectures

Choosing the appropriate policy depends on your data model and failure tolerance:

- **`allkeys-lru`:** Recommended for general web caching, API response caches, and transient session stores. When access patterns follow a power-law distribution where a subset of keys receives the majority of traffic, LRU keeps hot items in memory while shedding stale records.
- **`volatile-ttl`:** Recommended when keys have variable lifespans and your application can identify natural candidates for deletion. For instance, temporary authentication tokens with near-term expirations are evicted before longer-lived session caches.
- **`noeviction`:** Mandatory when Redis acts as a primary datastore, message broker, or stateful job queue. In these systems, losing a key silently corrupts application state, making explicit write errors preferable to silent data loss.

### The Volatile Eviction Trap

A frequent operational failure occurs when operators configure a volatile policy (`volatile-lru` or `volatile-ttl`) on a database where keys lack TTL assignments. If an application writes keys without an expiration timestamp, Redis finds zero eligible candidates during eviction evaluation.

Under this condition, volatile policies behave identically to `noeviction`: Redis refuses write commands and emits out-of-memory errors once `maxmemory` is reached. If you select a volatile eviction policy, audit your application code to confirm that every written key sets a corresponding expiration.

### How Approximated LRU and LFU Operate

Redis does not compute a true mathematical Least Recently Used algorithm. Maintaining a doubly linked list of millions of keys ordered by access timestamp would require substantial memory overhead per key and introduce thread contention during reads.

Instead, Redis uses an approximated algorithm. When an eviction occurs, Redis samples a configurable number of random keys (controlled by `maxmemory-samples`, which defaults to 5). It inspects the access time of those sampled keys and evicts the oldest entry.

```text
maxmemory-samples 5
```

You can tune this parameter based on your performance requirements:

- **5 samples (default):** Provides a close approximation of true LRU while maintaining negligible CPU overhead during writes.
- **10 samples:** Produces an eviction distribution that closely mirrors exact LRU, useful for workloads with sensitive cache hit requirements, at the cost of modest additional CPU usage during eviction cycles.
- **3 samples:** Minimizes CPU consumption during evictions at the expense of eviction precision.

## What Happens When Redis Reaches Memory Limit: OOM Errors and Write Rejections

When memory consumption reaches the configured `maxmemory` ceiling, Redis executes a strict sequence of checks before accepting incoming commands:

1. **Memory Evaluation:** Redis checks whether current memory consumption exceeds `maxmemory`.
2. **Eviction Attempt:** If `maxmemory-policy` allows eviction, Redis samples candidate keys and deletes them until used memory drops below the threshold.
3. **Command Evaluation:** If eviction is disabled (`noeviction`), if no candidate keys exist, or if memory remains above `maxmemory` after eviction cycles, Redis evaluates the incoming command type.
4. **Execution or Rejection:** Read commands proceed normally. Write commands that allocate memory are rejected immediately.

### The Standard OOM Error Response

When Redis rejects a command due to memory constraints, it returns an explicit error string to the connected client:

```text
OOM command not allowed when used memory > 'maxmemory'
```

Client libraries receive this response and raise runtime exceptions (such as `redis.exceptions.ResponseError` in Python or `Redis::CommandError` in Ruby).

Commands that modify existing keys without expanding allocated bytes, as well as commands that delete keys, continue to function. The table below illustrates command handling under memory saturation:

| Command Type | Example Commands | Behavior at maxmemory (noeviction) | Reason |
|---|---|---|---|
| Memory-Allocating Writes | `SET`, `HSET`, `LPUSH`, `SADD`, `ZADD`, `MSET` | Rejected with OOM error | Attempts to allocate additional RAM pages |
| Read-Only Queries | `GET`, `HGET`, `LRANGE`, `SMEMBERS`, `ZRANGE`, `EXISTS` | Allowed | Consumes no additional datastore memory |
| Deletions and Pops | `DEL`, `UNLINK`, `HDEL`, `LPOP`, `RPOP`, `SPOP` | Allowed | Reduces overall memory footprint |
| Key Expirations | `EXPIRE`, `PEXPIRE`, `PERSIST` | Allowed | Updates metadata without growing data allocations |

### Replication Buffers and the mem_not_counted_for_evict Metric

Redis isolates certain internal buffers from eviction calculations. In particular, the memory consumed by replication backlogs and client output buffers is reported under `mem_not_counted_for_evict` in the `INFO memory` output.

This design prevents a destructive feedback loop in replicated clusters:

1. Redis evicts a key to free memory.
2. The eviction event generates a replication stream command (`DEL`) that must be sent to all attached replicas.
3. The replication command is added to the primary node's replication output buffer.
4. If replication buffers counted toward `maxmemory`, the memory freed by evicting the key would be immediately consumed by the replication buffer.
5. This would trigger another eviction, which generates another replication command, cascading until the dataset is completely drained.

By excluding replication buffers from the eviction threshold, Redis avoids self-induced cache draining. However, this means physical RSS can continue climbing above `maxmemory` when replication lag occurs, reinforcing the requirement to reserve host memory headroom.

### Active-Active Multi-Cluster OOM Safeguards

In distributed deployments with Active-Active replication, memory saturation introduces cross-cluster synchronization risks. If a single shard runs out of memory and rejects writes while peer clusters continue accepting writes, datasets diverge.

To manage this condition, enterprise clusters monitor replication thresholds and activate garbage collection routines before memory reaches exhaustion. Setting aside dedicated replication headroom prevents cross-region network partitions from stalling local caching tiers.

## How to Monitor Redis Memory, Fragmentation, and Evictions

Effective memory management requires monitoring the Redis keyspace before write errors impact production applications. The Redis CLI provides built-in diagnostic tools to inspect memory allocation, allocator efficiency, and eviction frequency.

### Inspecting Real-Time Metrics with INFO memory

Execute `INFO memory` to retrieve operational telemetry from the database engine:

```bash
redis-cli INFO memory
```

Focus on the following operational fields:

- **`used_memory`:** The total number of bytes allocated by Redis using its memory allocator (jemalloc). This figure reflects the actual dataset size plus internal data structures.
- **`used_memory_rss`:** Resident Set Size, representing the bytes of memory allocated by the operating system to the `redis-server` process.
- **`used_memory_peak`:** The historical peak memory consumed by the instance.
- **`mem_fragmentation_ratio`:** The ratio of `used_memory_rss` to `used_memory`.
- **`mem_not_counted_for_evict`:** The bytes used by internal replication and AOF rewrite buffers that are excluded from eviction calculations.

### Evaluating the Memory Fragmentation Ratio

The `mem_fragmentation_ratio` indicates allocator efficiency:

$$\text{Fragmentation Ratio} = \frac{\text{used\_memory\_rss}}{\text{used\_memory}}$$

Interpret the ratio using these operational thresholds:

- **1.0 to 1.5:** Indicates healthy memory usage. Memory overhead is proportional to the dataset.
- **Greater than 1.5:** Indicates significant memory fragmentation. The operating system has reserved far more physical RAM than Redis is actively using. This occurs when an application writes and deletes high volumes of variable-sized keys, leaving allocated pages partially occupied.
- **Less than 1.0:** Indicates that physical RAM has been exhausted and the operating system is swapping memory pages to disk. Disk swapping causes severe latency spikes and requires immediate intervention (either increasing host RAM or reducing `maxmemory`).

### Tracking Cache Performance with INFO stats

To monitor whether your configured memory limit and eviction policy are operating efficiently, inspect `INFO stats`:

```bash
redis-cli INFO stats | grep -E "evicted_keys|keyspace_"
```

Key metrics include:

- **`evicted_keys`:** The cumulative count of keys removed due to reaching `maxmemory`. A steadily increasing number indicates that your working dataset exceeds available cache RAM.
- **`keyspace_hits` and `keyspace_misses`:** Measures cache efficacy. Calculate the hit ratio using the standard formula:

```text
Cache Hit Ratio = keyspace_hits / (keyspace_hits + keyspace_misses)
```

If the hit ratio falls while `evicted_keys` accelerates, the cache is thrashing: newly written items immediately force older, actively queried items out of memory.

### Diagnosing Key Sizes and Memory Health

When diagnosing unexpected memory spikes, locate oversized keys and review overall instance health using specialized memory commands:

```bash
redis-cli MEMORY USAGE user:profile:9482
redis-cli --bigkeys
redis-cli MEMORY DOCTOR
```

The `MEMORY DOCTOR` command analyzes current metrics and outputs concrete advice, flagging high fragmentation, aggressive client buffer expansion, or inappropriate eviction policies.

### Resolving Fragmentation with Active Defragmentation

If `mem_fragmentation_ratio` exceeds 1.5 while `used_memory` is well below `maxmemory`, restart-free memory defragmentation can reclaim memory pages. Redis integrates active defragmentation support for jemalloc:

```text
activedefrag yes
active-defrag-ignore-bytes 100mb
active-defrag-threshold-lower 10
active-defrag-threshold-upper 30
active-defrag-cycle-min 5
active-defrag-cycle-max 50
```

Active defragmentation works in the background: while the engine processes queries, it allocates new copies of values stored in fragmented memory pages into contiguous blocks, then releases the fragmented pages back to the kernel.

## Why Decouple AI Agent Context from Redis In-Memory Storage

A growing architectural pattern places Redis at the center of AI agent systems, using it as a shared state cache, message queue, conversation buffer, and vector index. Autonomous frameworks such as LangChain, AutoGen, and CrewAI frequently write conversational turns, tool execution logs, and full document attachments into Redis keys.

However, storing multi-megabyte document context, PDF extracts, and high-dimensional vector embeddings in Redis introduces acute memory failure modes:

1. **Extreme Memory Fragmentation:** Agent payloads vary wildly in size, ranging from small 50-byte status flags to 5-megabyte document chunks. This variance causes allocator fragmentation, driving `used_memory_rss` far above `used_memory`.
2. **Pipeline Collapse Under noeviction:** When Redis runs with default `noeviction` settings, an agent storing a document batch hits `maxmemory` and immediately crashes with write rejections, aborting complex multi-step reasoning tasks.
3. **Silent Session Eviction Under allkeys-lru:** When configured with `allkeys-lru`, Redis attempts to fit incoming document embeddings by evicting older keys. Because document payloads are massive compared to lightweight session tokens, a single document ingest can flush thousands of active agent session keys and coordination locks.

### Architectural Separation: Ephemeral Caching Versus Persistent Context

Production systems avoid memory exhaustion by decoupling ephemeral operational caching from persistent document context:

- **Redis Tier:** Dedicated to transient, fixed-structure key-value pairs. Configure Redis with `maxmemory`, `allkeys-lru`, and short TTLs for rate limiting, distributed locking, and active execution flags.
- **Persistent Storage Tier:** Dedicated to unstructured documents, research archives, compliance files, and full-text knowledge bases.

For persistent corpora, teams typically evaluate three primary storage options:

1. **Local Disk or Object Storage (such as Amazon S3):** Provides inexpensive raw storage, but lacks native semantic search. Developers must build, deploy, and maintain custom chunking, vector embedding, and indexing pipelines.
2. **Standalone Vector Databases:** Store dense vector embeddings for nearest-neighbor lookups, but do not manage source document versioning, collaboration permissions, or direct file delivery.
3. **Fast.io Intelligent Workspaces:** Provide persistent, organization-owned workspaces where files are stored durably, versioned per file, and indexed for search without custom vector infrastructure.

### Connecting AI Agents to Fast.io via Remote MCP

Fast.io provides [intelligent workspaces](/product/workspaces/) designed for agentic teams and automated systems. Instead of loading raw document files and massive context payloads into Redis memory, agents deposit source files into a shared workspace.

When [workspace intelligence](/product/ai/) is enabled, incoming documents are indexed automatically for hybrid search, combining exact keyword matching with semantic vector retrieval.

Agents connect directly to Fast.io using the remote Model Context Protocol (MCP) server over Streamable HTTP:

- **General Agent Runtimes and Claude:** Connect using the remote MCP endpoint at `https://mcp.fast.io/mcp/tools`.
- **Coding Agents and IDEs:** Connect using `https://mcp.fast.io/mcp/code`.
- **ChatGPT and Codex Custom Connections:** Connect using `https://mcp.fast.io/mcp/operations`.

Setup instructions and endpoint documentation are available at [Fast.io MCP documentation](https://mcp.fast.io/docs) and the [agent skill reference](https://mcp.fast.io/skill.md).

When an agent needs factual context to answer a query, it calls the MCP search tool rather than scanning multi-megabyte strings in Redis. The search tool returns concise excerpts backed by citations, consuming only a few hundred tokens of context window without expanding Redis memory.

```json
{
  "mcpServers": {
    "fastio": {
      "url": "https://mcp.fast.io/mcp/tools",
      "headers": {
        "Authorization": "Bearer YOUR_FASTIO_API_KEY"
      }
    }
  }
}
```

### Managing Structured Data with Metadata Views

When agents process recurring document sets like invoices, legal agreements, or technical specifications, [Metadata Views](/product/document-data-extraction/) extract structured attributes into queryable schemas. Users specify desired fields in natural language, and the extraction engine populates typed columns (text, integers, decimals, booleans, dates) across PDFs, spreadsheets, and scanned documents.

Software agents query extracted metadata directly through MCP actions without parsing full raw documents or storing large JSON blobs in Redis.

Every document stored in a Fast.io workspace retains a complete version history. If an agent or human team member updates a file, previous revisions remain accessible, and the detailed activity log records every modification, edit, and move. Permissions are managed at the organization, workspace, and share levels through member roles.

Monthly plans start with a 14-day free trial that requires a credit card. Review [Fast.io pricing](/pricing/) for plan options:

| Plan Tier | Monthly Price | Included Workspaces | Target Workload |
|---|---|---|---|
| Starter | $9.99/mo | 5 | Developers and early agent pilots |
| Business | $49.99/mo | 50 | Teams running shared agent workspaces |
| Enterprise | $199.99/mo | 200 | Production multi-agent deployments |

By isolating transient session state in a properly bounded Redis instance and delegating large context archives to Fast.io workspaces, engineering teams eliminate OOM write failures while scaling persistent document access.

## Frequently asked questions

### What happens when Redis reaches maxmemory?

When Redis reaches maxmemory, its behavior depends on the configured maxmemory-policy. Under the default noeviction policy, Redis refuses write commands that allocate additional memory (such as SET, HSET, and LPUSH) and returns an OOM command not allowed error to the client, while read-only queries continue to function. If an eviction policy like allkeys-lru is active, Redis deletes keys according to that policy to free space for new writes.

### How do I set the memory limit in Redis?

You can set the memory limit in Redis statically by adding a maxmemory directive to your redis.conf file. To configure it dynamically without restarting the server, execute `redis-cli CONFIG SET maxmemory 4gb` followed by `redis-cli CONFIG REWRITE` to persist the change to disk.

### What is the best maxmemory-policy for Redis caching?

For general caching workloads where hot items should remain accessible while stale items are purged, allkeys-lru is the industry standard choice. If your keys have predictable lifespans and set explicit expirations, volatile-ttl is preferred because it evicts keys closest to expiration first. For primary databases where silent data loss is unacceptable, keep noeviction configured.

### Why does Redis use more physical RAM than the maxmemory setting?

Redis uses more physical RAM (RSS) than maxmemory because maxmemory only limits memory allocated for user keys and data structures. Additional physical RAM is consumed by memory allocator fragmentation in jemalloc, replication output buffers, client connection buffers, and Copy-on-Write memory overhead during background snapshotting or AOF rewrites.

### How does Redis approximated LRU differ from true LRU?

True LRU maintains an exact linked list of every key ordered by access time, which requires significant memory pointer overhead per key and introduces lock contention. Redis instead approximates LRU by sampling a configurable number of random keys (defaulting to 5 via maxmemory-samples) and evicting the least recently accessed key from that sample, achieving near-identical cache hit rates without memory bloat.

### How can AI agents avoid Redis out of memory errors when handling large documents?

AI agents should keep Redis restricted to lightweight operational caching, session tokens, and coordination locks. Large document corpora, PDF attachments, and historical context should be stored in persistent workspaces like Fast.io. Connecting the agent via remote Model Context Protocol (MCP) endpoints allows the agent to search and retrieve targeted excerpts with citations, preventing large payload bloat in Redis.

## Sources

- [Redis Documentation: Key Eviction](https://redis.io/docs/latest/develop/reference/eviction/): On 64-bit architectures, Redis defaults to a maxmemory value of zero, meaning no memory ceiling is enforced until system memory is exhausted, whereas 32-bit systems enforce an implicit 3GB memory ceiling.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli. MCP setup is at https://mcp.fast.io/docs: Claude and most MCP clients connect to https://mcp.fast.io/mcp/tools, ChatGPT to https://mcp.fast.io/mcp/operations, and coding agents to https://mcp.fast.io/mcp/code.