memocache

memocache is a primitive, not a product. It is to a cache what a bare Li-ion cell is to a battery pack: raw capacity with no management layer wrapped around it. It stores fixed-size byte blocks in RAM on a network-attached machine and hands them back on demand. That is the entire job. It has no eviction policy, no session concept, and no opinion about what the blocks contain. Every bit of intelligence — what to store, when to evict, where to place it, how to interpret it — lives in the caller.

The intended use is turning idle DRAM on network-attached machines into an overflow block tier. The first consumer treats memocache nodes as a spillover KV-cache tier for LLM inference, but memocache neither knows nor cares about that; it is useful to anyone who wants to treat remote RAM as a dumb block store.

Scope

memocache does exactly three things:

• Reserves blocks — a client asks for N whole blocks and receives a reservation ID.
• Stores and returns block contents — write to and read from the blocks of a reservation by index.
• Releases blocks — explicitly via Free, or implicitly when an expired reservation is reclaimed under memory pressure.

That is the whole feature set.

Out of scope — by design

These are deliberately absent. They are the caller's responsibility, not memocache's:

• Eviction policy. memocache never decides which live data to discard. The only reclamation is lease expiry (see below), and even that is lazy.
• Session management. Reservations are owned by the server, not by a connection. There is no login, no per-client namespace; the reservation ID space is global. Closing a connection frees nothing.
• Placement / sharding / replication. A node is a single slab. Spreading data across nodes, choosing nodes, and replicating are caller concerns.
• Persistence. Contents live in RAM only and are lost on shutdown.
• Security. No TLS and no authentication; deploy only on a trusted network segment.

How it works

• The operator starts a node with a fixed block size and a slab size (e.g. -block-size=2MiB -slab-size=64GiB), fixing the block granularity and the total memory ceiling. The slab holds floor(slab_size / block_size) blocks.
• A client queries the block size, then requests a reservation by block count. The server reserves that many blocks (not necessarily contiguous) and returns a never-reused reservation ID.
• Reservations carry a mandatory lease (TTL). Expiry is soft and lazy: an expired reservation stays fully usable until a later allocation actually needs its space, at which point it is reclaimed. Accessing an expired-but-not-yet- reclaimed reservation still succeeds, with a warning. This is leak protection for crashed clients, not a cache eviction policy.
• Communication is a small binary protocol over TCP (no HTTP, no external dependencies).

Protocol

The wire protocol is specified independently of this implementation in docs/protocol.md, so a non-Go client can be written against it. The spec covers the handshake, every operation's byte-level layout, status codes, the reservation lifecycle, and graceful-shutdown semantics.

Status

Spec-first. The protocol specification is complete and under review; the server binary (cmd/memocache/), client library (client/), and internal packages (internal/proto/, internal/slab/) are not yet implemented.

Project facts

• Module path: git.brooktrails.org/brooktrails/memocache
• Pure Go standard library; no external dependencies in the server binary.
• Targets recent stable Go; runs on Linux and Windows with no platform-specific code.