---
title: "Cap every collection that grows with use · Agent Wranglers"
url: https://agentwranglers.se/playbook/architecture/errors-and-nulls/bounded-collections
updated: 2026-10-21
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Cap every collection that grows with use

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Errors and nulls](https://agentwranglers.se/playbook/architecture/errors-and-nulls.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers). Updated 2026-10-21.

- Level: Required
- Chapter: [Errors and nulls](https://agentwranglers.se/playbook/architecture/errors-and-nulls)
- Rule: Give every in-memory cache, queue, buffer and batch of parallel work a maximum size. Nothing in a long-running process may grow without a limit.
- Risk: The app down or unusable
- How: Use a cache with a size cap and an eviction rule, such as Python's `functools.lru_cache` with a `maxsize`. Give each queue a maximum length, and wait or reject when it is full. Run a large batch with a fixed number of parallel tasks, never one task per item. A leak you miss then hits the ceiling from [Set limits on memory and processes](https://agentwranglers.se/playbook/operations/running-the-service/resource-limits). Limits on what a client may ask for live in [Cap the size of every request and answer](https://agentwranglers.se/playbook/adversarial-testing/abuse-and-limits/resource-limits).
- Check: A grep fails `lru_cache(maxsize=None)` and `@functools.cache` in server code. A test inserts 10 times the cap in distinct keys, and the size stays at or below the cap.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### Python example

```python
# Bad: one entry per customer, forever, in a server that runs for weeks
@functools.cache
def price_list(customer_id: str) -> PriceList: ...

# Good: the oldest entries leave once 1,024 are stored
@functools.lru_cache(maxsize=1024)
def price_list(customer_id: str) -> PriceList: ...
```

### TypeScript example

```ts
// Good: a Map keeps insertion order, so the first key is the oldest
const MAX_PRICE_LISTS = 1024;
const priceLists = new Map<CustomerId, PriceList>();

function rememberPriceList(customerId: CustomerId, list: PriceList) {
  if (priceLists.size >= MAX_PRICE_LISTS) priceLists.delete(priceLists.keys().next().value!);
  priceLists.set(customerId, list);
}
```

## Sources

- [Python functools.lru_cache](https://docs.python.org/3/library/functools.html#functools.lru_cache)

## Related rules

- [Set limits on memory and processes](https://agentwranglers.se/playbook/operations/running-the-service/resource-limits) in Operations
- [Cap the size of every request and answer](https://agentwranglers.se/playbook/adversarial-testing/abuse-and-limits/resource-limits) in Security testing

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/architecture/errors-and-nulls/bounded-collections">Agent Wranglers architecture playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Await every async call](https://agentwranglers.se/playbook/architecture/errors-and-nulls/await-every-promise)
- [Errors and nulls](https://agentwranglers.se/playbook/architecture/errors-and-nulls)