llm-core

Appearance

Storage and memory ​

Storage ports describe host-owned persistence without choosing a database. Conversation memory is a separate portable contract layered over those storage concerns.

ts
import {
  conversationId,
  type ConversationMessage,
  type ConversationStore,
} from "@geekist/llm-core/memory";
import { newCoreId, type InvocationContext, type InvocationId } from "@geekist/llm-core/contracts";
import { jsonStorageValue, type CacheStore } from "@geekist/llm-core/storage";

declare const cache: CacheStore;
declare const conversations: ConversationStore;
const message: ConversationMessage = {
  role: "user",
  content: [{ kind: "text", text: "Remember this." }],
  occurredAt: new Date().toISOString(),
};

const context: InvocationContext = {
  invocationId: newCoreId<InvocationId>("018f0f4e-8c5b-7a91-8c3b-123456789c01"),
};
const id = conversationId("018f0f4e-8c5b-7a91-8c3b-123456789c02");

await cache.set({
  context,
  key: "tenant-a:answer",
  value: jsonStorageValue({ answer: 42 }),
  ttlMs: 60_000,
});

await conversations.append({
  context,
  conversationId: id,
  turn: message,
});

CacheStore is TTL-oriented, KeyValueStore is batched named storage, and ResourceStore owns live bytes behind portable ResourceRef values. The agent-memory ConversationStore owns ordered ConversationMessage values; its serialized append field remains turn for wire compatibility. ConversationStateStore owns application state derived for a conversation. These extension ports are distinct from the reservation-capable ConversationStore used by an explicit InteractionSession. None of them expose credentials, database handles or provider-native messages.

Validate values before persistence. Sensitive-looking portable keys and strings are rejected by the registration helpers, and native data must be redacted and namespaced before it reaches portable state or evidence.

These ports do not promise a particular consistency model beyond their exact method contracts. A storage adapter owns database selection, credentials, transactions, and operational guarantees. Capability evidence records which additional guarantees a configured binding has demonstrated.