Flash Memory Store

What it solves

For long-term agent memory (user preferences, learned facts, historical decisions) the access pattern is power-law:

~1% of keys are read constantly (current user’s preferences, recent decisions).
~99% are read rarely (historical facts, archived sessions).

Keeping everything in memory wastes RAM. Storing everything on disk wastes latency. FlashMemoryStore is a tiered StorageDriver:

Hot tier: in-process Map with LFU eviction. Fast.
Cold tier: LMDB on disk. Cheap, ACID, ~50,000 ops/sec on SSDs.

Inspired by Redis Iris / Flex which uses the same pattern at petabyte scale.

Architecture

                  ┌──────────────────────────────────────┐
                  │           FlashMemoryStore           │
                  │                                      │
   get(ns, key) ──┼──▶  Hot Map (LFU, hotCacheSize cap)  │
                  │                                      │
                  └──────────────┬───────────────────────┘
                                 │ miss
                                 ▼
                  ┌──────────────────────────────────────┐
                  │       LMDB (cold, on disk)            │
                  └──────────────────────────────────────┘

On a hot miss, the cold value is promoted to hot. On hot-cache overflow, the least-frequently-used entry is evicted (it’s still in cold, so no data loss).

Quick start

import { FlashMemoryStore } from "@agentium/core";

const store = new FlashMemoryStore({
  path: "./.agentium/memory",   // LMDB directory
  hotCacheSize: 10_000,
  mapSize: 2 * 1024 * 1024 * 1024, // 2 GB max cold size
});

await store.initialize();

await store.set("users", "user-123", { name: "Alice", signups: 7 });
const u = await store.get<{ name: string }>("users", "user-123");
console.log(u?.name); // "Alice"

Configuration

interface FlashMemoryStoreConfig {
  path?: string;          // LMDB dir; omit for pure in-memory
  mapSize?: number;       // LMDB max size in bytes; default 2 GiB
  hotCacheSize?: number;  // Max entries in hot tier; default 10_000
}

`path`

When omitted, falls back to pure in-memory operation. Useful for tests and serverless environments where you can’t write to disk. When set, lmdb (optional peer dep) is loaded lazily. If the package isn’t installed, a warning is printed and the store also falls back to in-memory:

[agentium/flash-memory] `lmdb` not installed - falling back to pure in-memory storage. Install with: npm install lmdb

`mapSize`

LMDB’s underlying memory-mapped file size cap. Once the file grows past mapSize, writes fail with MDB_MAP_FULL. Set it generously — LMDB only consumes actual disk space, not the full mapped size. 2 GiB default is fine for most agent memory; raise to 100+ GiB for large knowledge corpuses.

`hotCacheSize`

Bounds the hot tier. Too low → constant promotion churn. Too high → wastes RAM. Rule of thumb: set to 10× the expected working set (concurrent active users × per-user keys).

Eviction policy (LFU)

The hot tier evicts the entry with the lowest hit count, with ties broken by oldest last access. This means:

Recently written + never read → evicted soon.
Old but constantly read → kept.
Bursty access pattern → bursts survive while the burst is hot.

The hit count is monotonically increasing — there’s no decay. For decay-based LFU (FreshLFU), wrap this in your own decorator.

API (`StorageDriver`)

FlashMemoryStore implements the full StorageDriver interface, so it’s a drop-in replacement anywhere a StorageDriver is accepted:

interface StorageDriver {
  initialize?(): Promise<void>;
  get<T>(namespace: string, key: string): Promise<T | null>;
  set<T>(namespace: string, key: string, value: T): Promise<void>;
  delete(namespace: string, key: string): Promise<void>;
  list<T>(namespace: string, prefix?: string): Promise<Array<{ key: string; value: T }>>;
  close(): Promise<void>;
}

`get(namespace, key)`

Lookup order: hot map → cold LMDB. A cold hit is promoted to hot, evicting the least-used entry if hot is full.

`set(namespace, key, value)`

Writes to BOTH tiers immediately. The hot copy makes the next read instant; the cold copy survives process restart. If path is omitted (in-memory mode), only the hot map is written.

`delete(namespace, key)`

Removes from both tiers. Idempotent.

`list(namespace, prefix?)`

Returns all entries whose key (within namespace) starts with prefix. Implementation:

Range-scan the cold LMDB starting at <namespace>\u0000<prefix>.
Add any hot-only entries (e.g. set in memory before a cold flush).

Returns Array<{ key, value }> where key is the inner key (no namespace prefix). Performance: Cold range scans are O(log N) seek + O(K) scan. Don’t list over millions of keys per request — paginate with prefixes.

`close()`

Closes the LMDB env and clears the hot map. Always call this at process shutdown to flush LMDB cleanly.

Use as agent memory backend

import { Agent, FlashMemoryStore, openai } from "@agentium/core";

const storage = new FlashMemoryStore({ path: "./.agentium/memory" });
await storage.initialize();

const agent = new Agent({
  name: "long-memory-bot",
  model: openai("gpt-4o"),
  memory: { storage },
});

// All session history, learned facts, summaries persist to LMDB.

Combine with `ScopedStorage`

For multi-tenant deployments, wrap it:

import { FlashMemoryStore, ScopedStorage } from "@agentium/core";

const flash = new FlashMemoryStore({ path: "./.agentium/memory" });
await flash.initialize();

function storageFor(tenantId: string) {
  return new ScopedStorage(flash, { tenantId });
}

Each tenant’s keys are namespaced; the hot cache is still shared, so hot entries from heavy tenants stay hot.

Performance characteristics

Benchmarks on M2 Mac, 5K entries, JSON values ~1KB each:

Op	Hot hit	Cold hit	Cold miss
`get`	< 1 μs	~25 μs	~10 μs (LMDB miss)
`set`	~50 μs (LMDB sync write)	n/a	n/a
`list("ns", "pfx-")` (100 entries)	n/a	~2 ms	n/a

Disk usage is roughly 1.2× the sum of serialized values (LMDB B+tree overhead).

When to use

Persistent agent memory across process restarts
Long-running multi-day agent sessions
High-volume workloads where the default InMemoryStorage won’t survive
Edge / Raspberry Pi deployments (LMDB has tiny RAM overhead)

When NOT to use

Multi-process deployments — LMDB allows multiple readers but only one writer process at a time. Use Postgres / Mongo / DynamoDB instead.
Serverless functions — the LMDB file isn’t shared across cold starts; use a network driver.
You only need an in-memory cache — Map is simpler. Use this if you want the persistence too.

​Flash Memory Store

​What it solves

​Architecture

​Quick start

​Configuration

​path

​mapSize

​hotCacheSize

​Eviction policy (LFU)

​API (StorageDriver)

​get(namespace, key)

​set(namespace, key, value)

​delete(namespace, key)

​list(namespace, prefix?)

​close()

​Use as agent memory backend

​Combine with ScopedStorage

​Performance characteristics

​When to use

​When NOT to use

​See also