Chronicle Map: an off-heap key-value store sized by disk

The size limit is disk capacity, not heap size

One sentence in the README does more work than any other: the size of a Chronicle Map is not limited by memory, but rather by the available disk capacity.

That is the whole design in a clause. A normal Java map lives on the heap, which means it competes with your application objects, your garbage collector, and the maximum heap you configured at startup. Chronicle Map stores its entries outside the heap in memory mapped files, so the operating system pages them in as the application touches them. The consequence is that map capacity is bounded by your disk and by how much of it you are willing to let the OS page, not by JVM flags.

The project describes itself as a super-fast, in-memory, non-blocking, key-value store, designed for low-latency and multi-process applications such as trading and financial market applications. In-memory here is doing some work: the data lives in memory mapped files, which are on disk and in the page cache, so it is memory-resident in the way that matters for latency without being memory-resident in the way that matters for capacity.

The `spec/` directory at the repository root is unusual for a Java library and suggests the storage format is specified rather than emergent. There is also a `DISCLAIMER.adoc` and a `NOTICE` file alongside the Apache 2 `LICENSE`, which is worth reading before you use this in a system you have to support.

What the garbage collector stop having to do means for you

The performance claims are specific enough to be checkable, which is unusual. The README says millions of operations per second, with low and stable microsecond latencies for reads and writes, that write queries scale well up to the number of hardware execution threads on the server, and that read queries never block each other.

Read that third claim carefully. Reads never blocking each other is a consequence of where the data lives. If entries are outside the heap and the structure is built for concurrent access, two readers do not contend on a garbage collector pause or on a lock covering the whole structure. That is the property a trading system cares about, and it is the property that would be hardest to fake.

Writes scaling to hardware thread count is the other half. A write does contend, on segment-level structures rather than a single global lock, so the ceiling is the machine rather than a single writer. The README also claims support for ultra-low garbage collection, which follows from the same placement decision: the churn that would otherwise land on the heap does not happen here.

None of this is free. An off-heap structure means you are responsible for the off-heap lifecycle, and `system.properties` at the repository root suggests the project expects you to be configuring the JVM around it. That is a real cost, and it is why this class of library tends to appear in latency-sensitive systems rather than in application code generally.

Multi-master replication and the chaos monkey claim

The repository description leads with replication: replicate your key-value store across your network, with consistency, persistence and performance. The README points at `docs/CM_Replication.adoc` for the mechanism and lists multi-process, multi-machine concurrency as a use case.

What stands out is how the project substantiates reliability. The README says Chronicle Software runs a chaos monkey test which verifies Chronicle Map multi-master replication in the face of node and network failures. That is a claim about the testing approach rather than about the code, and it is the kind of claim worth asking to see a writeup of, since it describes fault injection against the actual replication path rather than unit tests with mocked failures.

The persistence side is described more briefly: the map can optionally be persisted to disk. Optional persistence plus automatic replication is a meaningful combination, because it means the map can be rebuilt from peers rather than being the sole durable copy. For a system that must survive a node loss, that changes the recovery story, though it also means you need to understand what the replication protocol guarantees before relying on it.

Documentation is organised as a short table in the README: features, replication, a tutorial, an FAQ, downloading, an update guide for people moving from version 2, and a compatibility and versioning document. That last one existing at all is a signal that version-to-version behaviour is something the project expects readers to check.

Release naming, the ea branch, and what the tags mean

The release history is short and slightly confusing, and it is worth spending a minute on. The newest tag is `chronicle-map-2026.1`, published on 2026-01-29, and its release body says only that there is no changelog for this release. Before that come `chronicle-map-3.27ea2` and `chronicle-map-3.26.8`, both published on 2025-12-16, carrying the same single entry: the ability to not attempt a put onto the map if the entry will not fit into the segment's tier, ticket CORE-48.

Two things follow from those three tags. First, the project has moved from semver-style 3.x numbering to a calendar-style 2026.x line, so any tooling or documentation that assumes 3.x will misidentify the current version. Second, the `ea2` suffix on 3.27ea2, combined with the repository's default branch being named `ea` rather than `main` or `master`, indicates that early access builds are published from the default branch.

The last push was on 2026-09-22 and the repository is not archived, so work continues between releases. But with one changelog-free release and a single-item entry before it, the release notes are not a reliable way to assess what changed. For upgrade risk you have to read the compatibility and versioning document in `docs/` and the project's own release notes subscription, which the README links to at chronicle.software.

That single CORE-48 change is still instructive. Refusing a put that cannot fit in a segment's tier converts a silent corruption or overflow scenario into a failed operation, which is the right behaviour for a structure that pages to disk.

Open source core with a commercial wrapper

The README separates what you get from what you pay for. It states the project is open source in its standard version, and in use at hundreds of sites globally, then adds a section describing what Chronicle Software provides: full support for Chronicle Map, consulting to help you get the most from the product, and delivery of projects using a mix of their resources and your own.

That is a conventional arrangement for infrastructure libraries, and the licence is Apache 2 with the required `NOTICE` and third-party notices alongside it. Licence-wise there is nothing unusual to resolve, though the disclaimer file suggests the project wants terms of use read carefully.

The wording deserves one note. The README also claims the software is in production at banks and hedge funds globally, and built using lessons learnt from real-world experience. Those are the project's own claims about its adoption, and they are the kind of statement to treat as marketing rather than as a verified fact, particularly in a document that also describes itself with phrases like super-fast. What is checkable from the repository is more useful: the Apache 2 licence, the spec directory, the chaos monkey testing claim, the documentation structure, and the release history.

Where this sits against a hosted cache

The comparison people actually make is with Redis, and the difference is architectural rather than a matter of tuning. Redis is a network service: you talk to it over a socket, pay a network hop on every operation, and your data lives wherever that service runs. Chronicle Map is a library linked into your JVM: the call is a method invocation, there is no server to run, and the data is in your process's own files.

That is an advantage when latency is measured in microseconds and a disadvantage in almost every other respect. There is no replication to configure because there is no remote peer; what the project offers instead is multi-master replication between processes that are each running their own map. There is no server to monitor, but also no server to restart, and a map that outgrows your page cache starts paying disk latency.

The honest framing is that Chronicle Map is not trying to be a cache. It is trying to be a very large concurrent hash structure with a disk-bounded capacity and predictable read latency, for processes that already decided to be JVMs. If your problem is serving many clients over a network, Redis or a similar service is the right shape and this is not. If your problem is a multi-gigabyte lookup table that has to stay inside one low-latency process, this is closer to the right shape than anything else in the Java ecosystem.

The `benchmark/` directory in the repository is where the project's own numbers would come from, and it is the first place to look if the latency claims matter to your case.

Editorial conclusion

Chronicle Map earns its place when the working set genuinely does not fit in the heap and you cannot accept garbage collection pauses on a read path, which in practice means trading, market data and similar latency-sensitive systems. What the project documents well is the design intent: off-heap storage, disk-bounded size, non-blocking reads, and a chaos monkey test for replication. What it documents thinly is the operating detail, since there is no changelog for the 2026.1 release and no code example in the repository README at all, so the tutorial in `docs/CM_Tutorial.adoc` is your starting point rather than the front page. Check the compatibility and versioning document before upgrading, since that file exists precisely because this library's behaviour has shifted across major versions. And note that the standard version is the open source one while Chronicle Software sells support around it, so read the licence before assuming the commercial and community builds are the same artefact.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. OpenHFT/Chronicle-Map on GitHub
3. Project website
4. README
5. Releases