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

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:

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:

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:

• How to Set Up Agentic AI Storage for Persistent Agent MemoryAgentic AI storage provides persistent file and data access that autonomous agents need to complete multi-step tasks...
• How to Build Persistent Memory in CrewAI AgentsCrewAI memory is a framework-level feature that allows agents to store and retrieve past experiences, improving...
• Gemini 2.5 Flash Context Window: Token Limits, Latency, and Memory ManagementThe Gemini 2.5 Flash context window provides 1,048,576 tokens of input capacity alongside a 65,536 token output...
• Best Cloud Storage for AI Agents: Top 7 Platforms ComparedCloud storage for AI agents provides persistent file access, version control, and API-driven operations that let...
• How to Choose the Best Vector Database for AI Agents (2026)Vector databases serve as the long-term semantic memory for AI agents, allowing them to recall context across sessions...
• How to Set Up an AI Agent Shared WorkspaceA shared workspace gives multiple AI agents a single place to read, write, and organize files without stepping on each...

More on this subject: Agent Memory and Storage (263 guides)

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.

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.

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:

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:

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.

Offload Agent Payloads and Prevent Memory Bottlenecks

Keep your Redis cache lean by offloading large document context and embeddings to persistent Fast.io workspaces with native MCP search. Monthly plans start with a 14-day free trial.

Start 14-Day Trial

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:

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:

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:

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:

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:

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.

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 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 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 and the agent skill reference.

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.

{
  "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 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 for plan options:

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.