Olric: An Embedded Distributed Cache Written in Go

The Problem Olric Solves: A Shared Pool of RAM Without an External Coordinator

Most Go services that need a cache start with a map guarded by a mutex. That works until the service runs on more than one machine, at which point each process has its own copy of the data and no way to agree on what the current value is. The usual answer is to put Redis in front of everything. That works, but it adds a separate deployment, a separate failure domain, and a separate set of capacity decisions.

Olric's answer is to make the cache itself the cluster. The README describes it as "a fast, scalable, and shared pool of RAM across a cluster of machines." Nodes discover each other, partition the keyspace, and rebalance when capacity changes, with no external coordination service in the loop. The project targets Go teams first, because it is embeddable as a library, but the RESP protocol means a Python or Java client can talk to the same cluster through olric-server.

The intended data is transient and approximate. Olric is built to share "some transient, approximate, fast-changing data between servers." It is not a system of record. If a value must survive a process restart or a disk failure, Olric is the wrong layer, because the storage engine is only in-memory.

How Olric Partitions Data: Consistent Hashing, Backups, and Read-Repair

The repository layout shows the mechanism. The go.mod file pulls in github.com/buraksezer/consistent, a consistent hashing library, and github.com/hashicorp/memberlist, which handles cluster membership and failure detection. Those two dependencies explain most of Olric's behavior: memberlist tells each node who else is alive, and the consistent hashing ring decides which node owns each key.

Ownership is not single-copy. The README states that replication is on by default, with sync and async options, and that replica control uses quorum-based voting for reads and writes. A write goes to the primary and its backups, and the configured write quorum decides how many acknowledgements count as success. Reads can consult a quorum as well. When replicas disagree, the README names the resolution rule directly: last-write-wins.

The consistency model is stated in the project's own terms. Olric provides "best-effort consistency guarantees without being a complete CP (indeed PA/EC) solution." In practice that means during a network partition the cluster keeps accepting reads and writes on the available side, and reconciliation happens afterward. The README also mentions read-repair on distributed maps and a simple split-brain protection mechanism, which are the pieces that pull replicas back toward agreement once the partition heals.

For eviction, there are three documented paths: TTL expiry, MaxIdleDuration expiry, and LRU. The storage engine is described as GC-friendly, and lookups are documented as O(1). That combination matters for a cache holding millions of small entries, because a storage engine that generates garbage on every operation turns into a GC problem before it turns into a memory problem.

Installing Olric and Running a First Distributed Map

The Makefile exposes an install target that builds the command-line tools, including olric-server, from the cmd directory. Running it requires a Go toolchain; the module declares go 1.25.0 in go.mod.

make install

After that, olric-server is on your PATH. The Dockerfile shows the standalone service listening on two ports, 3320 and 3322, and starting with a config file at /etc/olric-server.yaml. The repository ships olric-server-docker.yaml at the top level as the default configuration used by that image.

docker build -t olric-server .
docker run -p 3320:3320 -p 3322:3322 olric-server

The first port is the one clients connect to. Because Olric speaks RESP, any Redis client can be pointed at it. The README's Go client section is built around github.com/redis/go-redis/v9, which is listed as a direct dependency in go.mod. The commands themselves are Olric's own, documented in the README under the Distributed Map heading: DM.PUT, DM.GET, DM.DEL, DM.EXPIRE, DM.PEXPIRE and DM.DESTROY for basic map access, the atomic operations DM.INCR, DM.DECR, DM.GETPUT, DM.CAS and DM.INCRBYFLOAT, the locking commands DM.LOCK, DM.UNLOCK, DM.LOCKLEASE and DM.PLOCKLEASE, and DM.SCAN for iteration. Publish and subscribe use SUBSCRIBE, PSUBSCRIBE, UNSUBSCRIBE, PUNSUBSCRIBE, PUBSUB CHANNELS, PUBSUB NUMPAT and PUBSUB NUMSUB. Cluster introspection is CLUSTER.ROUTINGTABLE and CLUSTER.MEMBERS, with STATS for counters and AUTH for authentication.

If you would rather not run a separate process, the embedded mode skips the network hop entirely. The README says configuration can be programmatic or declarative, and that embedded members can also be configured from YAML.

Where Olric Breaks Down: Consistency, Durability, and the RESP Assumption

The first limitation is the one the project states plainly. Olric is eventually consistent and unordered, and it is not a complete CP solution. If two clients write the same key from opposite sides of a partition, last-write-wins picks a winner and the loser's write disappears. There is no transaction log to replay and no conflict resolution callback. For a cache this is fine. For a counter that must never lose an increment, it is not.

The second is durability. The README says the store is only in-memory. A node restart loses whatever that node held, and the backups on other nodes are the only thing standing between you and a cold cache. That is a deliberate design point, not an oversight, but it means Olric cannot back a queue, a session store that must survive a deploy, or anything you would be unhappy to rebuild.

The third is the RESP compatibility claim. Olric implements a subset of the Redis command surface, and the commands it adds are namespaced under DM., CLUSTER., PUBSUB and STATS. A Redis client library will connect without complaint, but code that calls SET, LPUSH or a Lua script will not find those commands. The README's compatibility statement is about the protocol and the client libraries, not about command-level parity.

The fourth is operational. Sharding and rebalancing are automatic, which is convenient until you need to explain why a particular key lives where it does. CLUSTER.ROUTINGTABLE exists for that, and it is worth reading before an incident rather than during one. The README also notes that importing the old github.com/buraksezer/olric module path should redirect, but that import paths should be updated; the rename took effect in v0.6.0. Code pinned to a pre-0.6.0 path is on a branch that the project no longer develops as the main line.

Olric Compared With Redis and With an In-Process Cache

The obvious comparison is Redis. Both speak RESP, both keep data in memory, and both offer publish-subscribe. The difference is where the cluster logic lives. Redis Cluster requires you to run the cluster and, in many deployments, an external coordinator such as Sentinel or a managed control plane. Olric puts memberlist and the consistent hashing ring inside the same binary as the data, which is why the README can say new nodes auto-discover the cluster and rebalance with no external coordination service. The cost of that choice is consistency: Redis with a single primary gives you a clear linearizable read path, while Olric gives you quorums and last-write-wins.

The second comparison is an in-process cache such as a plain map or a library-local LRU. That approach has no network hop and no serialization cost, and it never has a partition. It also cannot share a value between two instances of your service, so a cache hit on one pod is a miss on the next. Olric's embedded mode is the middle ground: the node runs inside your process, so the local key path stays in memory, while the cluster handles keys that belong to other members. You pay a network hop only for the keys you do not own.

The third comparison is a purpose-built distributed store with strong consistency, such as etcd or Consul's KV. Those are the right tools when the data is configuration or coordination state, because they give you linearizable reads and watch semantics. They are also far slower for high-volume cache traffic and are not designed to hold millions of short-lived entries. Olric's README frames the target data as transient and approximate, which is the opposite end of that spectrum.

Maintenance, Versioning, and the Apache-2.0 Licence

The repository is not archived, and the last push was on 2026-08-20. The most recent release is v0.7.4 from 2026-06-12, following v0.7.3 in January 2026 and v0.7.2 in November 2025. That cadence is roughly a release every few months, and the README points to the v0.7 release branch as the current production version. Note the version number itself: the project is still on 0.x, which the maintainers have not declared stable in the sense that a 1.0 would.

Upgrade cost is concentrated in two places. The first is the module path. The project moved from github.com/buraksezer/olric to github.com/olric-data/olric in v0.6.0, and the README says there is no other difference between v0.5.7 and v0.6.0, so that upgrade is a find-and-replace in imports. The second is the Go version floor. go.mod declares go 1.25.0, so a team on an older toolchain will have to move before it can build the current module.

On licensing, Olric is Apache-2.0, which is a permissive licence with an explicit patent grant and a requirement to preserve notices. That is the standard choice for infrastructure libraries and is compatible with commercial use. It is not a copyleft licence, so it does not force you to publish your own code. Nothing here is legal advice; if you redistribute Olric inside a product, read the LICENSE file in the repository rather than a summary.

Editorial conclusion

Olric fits Go services that need a shared, approximate cache across a cluster and can accept last-write-wins semantics. It is the wrong tool when you need durable storage, transactions, or strong consistency, since the README describes it as an eventually consistent, unordered store that is not a complete CP solution. Before adopting it, verify the RESP command surface your client depends on, confirm the quorum settings you intend to run, and check how the storage engine's eviction options behave under your key distribution.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. olric-data/olric on GitHub
4. README
5. Releases