---
question: Are key-value keys shared across modules?
kind: overview
---

# Key-value store

The key-value store keeps small byte values by key, with an optional expiry. It is the kernel service `services.kv`: modules use it for shared state, sessions, flags and locks. It is not a database: there are no queries beyond listing keys by prefix.

Super admins can browse, add, edit and delete keys in Nexus, under System › Data › Key-value. Compare and set is Python only.

<!-- matrix -->

## Backends

`services.kv` in `config.yaml` picks one adapter:

| Adapter | Storage | Used by |
|---|---|---|
| `python` | A SQLite file (`persistence_path`), or memory when it is not set | `config.yaml` of a new project (`abi dev up`), and the engine default |
| `redis` | A Redis server (`redis_url`) | `config.local.yaml` (Docker stack, port 6379) |
| `nats_rpc` | Another engine's store, over NATS | Engines that share one store |

A new project writes `persistence_path: storage/kv/python.sqlite3`; when the `kv:` block is missing, the engine uses the same file. The keys of each adapter are in the [Configuration Reference](/user-guide/get-started/configuration#key-value-store). On the Docker stack, Redis Commander browses Redis at `http://localhost:8082`.

## Key concepts

- **Bytes in, bytes out.** `set` takes `bytes` and `get` returns `bytes`. Encode text and JSON yourself.
- **One shared key space.** Keys are not prefixed with the module. Every module that declares the service sees the same keys, so prefix yours (`my_module:...`).
- **Expiry.** `ttl` is in seconds. An expired key reads as missing. `get_ttl` returns `None` for a key that does not expire.
- **Atomic checks.** `set_if_not_exists` and `delete_if_value_matches` are atomic. `lock` builds a lock from them. There is no call that replaces a value only when the old one matches.
- **Errors.** `get`, `delete` and `get_ttl` raise `KVNotFoundError` for a missing key. `lock` raises `KVLockTimeoutError`. Both come from `naas_abi_core.services.keyvalue.KeyValuePorts`.
- **Events.** Writes publish `KeyValueSet` and `KeyValueDeleted` when the event service is up. A failed publish never fails the write.
- **Who else uses it.** The Jena TDB2 triple store adapter takes its write lock here, and the cache can use it as a tier (`keyvalue` adapter).
- **Dependency.** A module lists `KeyValueService` in `ModuleDependencies.services`. The attribute is `self.engine.services.kv`.