TypeScript icon, indicating that this package has built-in type declarations

0.0.13 • Public • Published

Civil Memory

Short and long-term memory for your web applications.


Civil Memory is a key-value store for storing smaller snippets of data and a blob/object store that supports large file storage. It can connect to a variety of backing data stores and provides a unified interface across platforms. Civil Memory is written in TypeScript and runs on Node.


npm install --save @tagmein/civil-memory

Build from source

  • npm run build to build once
  • npm run build:watch to watch TypeScript source files for changes and rebuild

Supported backing stores

  1. volatile — stores items in the Node process memory with a limit of 64Kib for key-value values and a limit of 5MiB for objects. No information is written to disk and as such it is permanently lost when the server process exits.

    const kv = civilMemoryKV.volatile()
  2. disk — stores data in a file and folder structure with no size limits except for the limits of the available hard disk space on your computer.

    const kv = civilMemoryKV.disk({
     rootDir: '/path/to/storage/directory'
  3. http — proxies KV requests to any compatible KV HTTP server. The specification is as follows:

    Read a value:
    GET <baseUrl>?key=<key>
    Delete a value:
    DELETE <baseUrl>?key=<key>
    Set a value:
    POST <baseUrl>?key=<key> with value as request body
    const kv = civilMemoryKV.http({
     baseUrl: 'https://my-domain.com/my-kv?foo=bar'
  4. cloudflareCloudflare Workers KV with a limit of 25MiB for key-value values and Cloudflare R2 with a limit of 315MiB for objects. Note that this mode is only usable within a Cloudflare worker as Cloudflare Workers KV cannot be accessed externally.

    See Cloudflare test suite from the test/cloudflare directory running here: https://civil-memory.pages.dev/

    // see https://developers.cloudflare.com/kv/learning/kv-bindings/
    const kv = civilMemoryKV.cloudflare({
     binding: env.MY_BINDING_NAME
  5. vercelVercel KV with a limit of 100MiB for key-value values and Vercel Blob with a limit of 500 MiB for objects.

    See Vercel test suite from the test/vercel directory running here: https://civil-memory.vercel.app/

    // see https://vercel.com/docs/storage/vercel-kv/quickstart
    const kv = await civilMemoryKV.vercel({
     token: process.env.KV_REST_API_TOKEN,
     url: process.env.KV_REST_API_URL,
  6. more — to request a new backing store, open a pull request, even if there is no code, and it will be considered.

KV Usage

The structure of keys is as follows:


Both the namespace and the key should be URL-encoded to prevent unencoded # characters in them from interfering with the parsing of the key.

import { civilMemoryKV } from '@tagmein/civil-memory'

// create a kv client - pick one from the 'Supported backing stores' section above
const kv = civilMemoryKV.<mode>(...)

// use the kv client to ...

// ... read a value
const temperature = await kv.get('temperature')
console.log({ temperature })

// ... write a value
await kv.set('temperature', '40.5')

// ... remove a value
await kv.delete('temperature')

Objects Usage

Civil Memory Objects is not yet released, check back later or contribute by opening a pull request.

Package Sidebar


npm i @tagmein/civil-memory

Weekly Downloads






Unpacked Size

53.8 kB

Total Files


Last publish


  • nate.ferrero