# Where to start for implementing custom memory-block–aware scheduling in vLLM?

**URL:** <https://discuss.vllm.ai/t/where-to-start-for-implementing-custom-memory-block-aware-scheduling-in-vllm/2157>\
**Category:** General\
**Created:** [December 26, 2025, 1:23pm UTC](https://discuss.vllm.ai/t/where-to-start-for-implementing-custom-memory-block-aware-scheduling-in-vllm/2157 "2025-12-26T13:23:36Z")\
**Posts on this page:** 4\
**Page:** 1

<div class="post-metadata">

**Author:** ![s-sepehr-razavi](https://yyz2.discourse-cdn.com/flex036/user_avatar/discuss.vllm.ai/s-sepehr-razavi/32/1032_2.png) [@s-sepehr-razavi](https://discuss.vllm.ai/u/s-sepehr-razavi)\
**Post date:** [December 26, 2025, 1:23pm UTC](https://discuss.vllm.ai/t/where-to-start-for-implementing-custom-memory-block-aware-scheduling-in-vllm/2157/1 "2025-12-26T13:23:36Z")

</div>

Hi everyone,

I want to **implement and experiment with different scheduling algorithms on top of the vLLM framework**. More specifically, my goal is to **tweak the way memory (KV cache) blocks are assigned to each incoming prompt**, and to be able to write custom logic that assigns memory blocks in a controlled, algorithm-defined manner.

I have started reading the vLLM codebase, but it is fairly large, and I am not sure where the _right entry points_ are. At the moment, I only have a rough guess that the **scheduler** and **block manager** related classes are the main components I should focus on.

My questions are:

1. Which parts of the codebase should I study first to understand how memory blocks are allocated to requests/prompts?

2. Is the scheduler the correct place to implement custom logic for memory-block assignment, or is this primarily handled elsewhere (e.g., block managers / KV cache managers)?

3. Are there recommended extension points or abstractions for experimenting with new scheduling or memory allocation policies without heavily modifying the core engine?

4. Any pointers to specific files, classes, or prior discussions would be greatly appreciated.

Thanks in advance — any guidance on how to approach this systematically would be very helpful.

---

<div class="post-metadata">

**Author:** ![RunLLM](https://yyz2.discourse-cdn.com/flex036/user_avatar/discuss.vllm.ai/runllm/32/233_2.png) [@RunLLM](https://discuss.vllm.ai/u/RunLLM)\
**Post date:** [December 26, 2025, 1:23pm UTC](https://discuss.vllm.ai/t/where-to-start-for-implementing-custom-memory-block-aware-scheduling-in-vllm/2157/2 "2025-12-26T13:23:58Z")

</div>

To experiment with custom scheduling and memory (KV cache) allocation in vLLM, you should focus on the Scheduler and KV cache manager components. The scheduler determines which requests are scheduled, while the actual memory block allocation is handled by the KV cache manager and its underlying block manager classes. The main extension points for memory allocation logic are in the KV cache manager, not the scheduler itself. For scheduling policies, vLLM provides a pluggable scheduler interface, and for memory allocation, the block manager (e.g., `SelfAttnBlockSpaceManager`) is the key abstraction to study and potentially extend. See [block manager API docs](https://docs.vllm.ai/en/latest/api/vllm/vllm.core.block_manager.html) and [hybrid KV cache manager design](https://docs.vllm.ai/en/latest/design/hybrid_kv_cache_manager/#case-2-sliding-window-attention-full-attention-models) for details.

Recommended files to start with are `vllm/core/block_manager.py` (block allocation logic), `vllm/v1/core/kv_cache_manager.py` (KV cache management), and `vllm/v1/core/scheduler.py` (scheduling policies). For experimenting, vLLM supports pluggable scheduling policies and modular block manager implementations, so you can subclass or swap these components without heavy core modifications. See also the [priority scheduling RFC](https://github.com/vllm-project/vllm/issues/6077) and [adaptive scheduler RFC](https://github.com/vllm-project/vllm/issues/24484) for examples of custom scheduling logic.

Would you like a step-by-step breakdown of how a request flows through these components or example code for a custom scheduler?

Sources:

- [block manager API docs](https://docs.vllm.ai/en/latest/api/vllm/vllm.core.block_manager.html)
- [hybrid KV cache manager design](https://docs.vllm.ai/en/latest/design/hybrid_kv_cache_manager/#case-2-sliding-window-attention-full-attention-models)
- [priority scheduling RFC](https://github.com/vllm-project/vllm/issues/6077)
- [adaptive scheduler RFC](https://github.com/vllm-project/vllm/issues/24484)

Hint: Mention @RunLLM in the post for followups.

---

<div class="post-metadata">

**Author:** ![s-sepehr-razavi](https://yyz2.discourse-cdn.com/flex036/user_avatar/discuss.vllm.ai/s-sepehr-razavi/32/1032_2.png) [@s-sepehr-razavi](https://discuss.vllm.ai/u/s-sepehr-razavi)\
**Post date:** [December 26, 2025, 1:41pm UTC](https://discuss.vllm.ai/t/where-to-start-for-implementing-custom-memory-block-aware-scheduling-in-vllm/2157/3 "2025-12-26T13:41:15Z")

</div>

@RunLLM Yes that would be nice!

---

<div class="post-metadata">

**Author:** ![RunLLM](https://yyz2.discourse-cdn.com/flex036/user_avatar/discuss.vllm.ai/runllm/32/233_2.png) [@RunLLM](https://discuss.vllm.ai/u/RunLLM)\
**Post date:** [December 26, 2025, 1:41pm UTC](https://discuss.vllm.ai/t/where-to-start-for-implementing-custom-memory-block-aware-scheduling-in-vllm/2157/4 "2025-12-26T13:41:48Z")

</div>

Certainly! Here’s a step-by-step breakdown of how a request flows through vLLM’s scheduling and memory allocation components, with pointers to the relevant files and extension points:

1. **Request Arrival & Scheduling**

2. **KV Cache Block Allocation**

3. **Custom Memory Allocation Logic**

4. **Extension Points**

**Summary Diagram:**

```auto
Request → Scheduler (customizable) → KVCacheManager → BlockManager (customizable) → Memory Blocks

```

**Example:**

```python
# Example: Custom scheduler class
from vllm.v1.core.sched.scheduler import Scheduler

class MyCustomScheduler(Scheduler):
    def schedule(self):
        # Custom logic here
        pass

# Set in config: scheduler_cls=MyCustomScheduler

```

Let me know if you want a code example for a custom block manager or more details on a specific step!

Sources:

- [block manager API docs](https://docs.vllm.ai/en/latest/api/vllm/vllm.core.block_manager.html)
- [hybrid KV cache manager design](https://docs.vllm.ai/en/latest/design/hybrid_kv_cache_manager/)
- [pluggable scheduler PR](https://github.com/vllm-project/vllm/pull/13161)
- [scheduler source code](https://github.com/vllm-project/vllm/blob/main/vllm/v1/core/sched/scheduler.py)

Hint: Mention @RunLLM in the post for followups.