Agentuity Documentation

KV Storage

Key-value storage is for exact lookups: save a value under a namespace and key, then read it back with that same key. This demo loads sample records, lists the keys, and shows the stored JSON value. Use KV for preferences, cache entries, counters, and short-lived state. For searching by meaning or similarity, use Vector storage instead.

Sample Data:

Keys (0)

No keys found. Click "Load Sample Data" to add a sample.

Value

Select a key to view its value

Reference Code

import { KeyValueClient } from "@agentuity/keyvalue";

const kv = new KeyValueClient();
const namespace = "explorer-" + crypto.randomUUID();
const key = "session-" + crypto.randomUUID();

const session = {
  visitorId: "visitor-abc123",
  lastActive: new Date().toISOString(),
  preferences: { theme: "dark" },
};

let summary: {
  found: boolean;
  theme: string | null;
  keys: string[];
  matches: number;
  itemCount: number;
  namespaceVisible: boolean;
};
let namespaceCreated = false;

try {
  await kv.createNamespace(namespace, { defaultTTLSeconds: 300 });
  namespaceCreated = true;
  await kv.set(namespace, key, session, { ttl: 300 });
  await kv.set(namespace, key + ":summary", {
    visitorId: session.visitorId,
    theme: session.preferences.theme,
  }, { ttl: 300 });

  const result = await kv.get<typeof session>(namespace, key);
  // get() returns a union: narrow on exists before touching data.
  const theme = result.exists ? result.data.preferences.theme : null;
  const keys = await kv.getKeys(namespace);
  const matches = await kv.search<typeof session>(namespace, "session");
  const stats = await kv.getStats(namespace);
  const namespaces = await kv.getNamespaces();

  summary = {
    found: result.exists,
    theme,
    keys,
    matches: matches.size,
    itemCount: stats.count,
    namespaceVisible: namespaces.includes(namespace),
  };
} finally {
  if (namespaceCreated) {
    await kv.deleteNamespace(namespace);
  }
}

export { summary };

Ready

Output will appear here...