Memory Stores

By default, memory lives in-process and vanishes when your server restarts. To keep it across sessions, pass a durable RecordStore: every memory block persists through that one interface, so the same record adapter can back memory records, indexing metadata, plans, flows, blackboards, and workspace metadata.

import { memory, workingState } from "@use-crux/core/memory";
import { inMemoryRecordStore } from "@use-crux/core/storage";

const records = inMemoryRecordStore();

const mem = memory({
  id: "assistant",
  namespace: "thread:123",
  records,
  blocks: [workingState({ id: "scratch", schema })],
});

For general store APIs, TTL, adapters, subscriptions, and custom database implementations, use the store reference. For vector search, use the VectorStore guide. For workspace files and generated binary outputs, use AssetStore, not memory storage.

What Memory Stores

Memory blocks write JSON records to the configured RecordStore.

const mem = memory({
  id: "support-agent",
  namespace: `user:${userId}`,
  records,
  blocks: [
    workingState({ id: "profile", schema: profileSchema }),
    episodes({ id: "history", embed: dense }),
  ],
});

The id identifies the memory collection. The namespace scopes records to a user, thread, tenant, session, or agent. Use stable namespaces so memory can be recalled on later turns.

Defaults

If you do not pass records, memory uses in-memory storage. That is useful for tests and local demos, but it is not durable.

const mem = memory({
  id: "assistant",
  namespace: "demo",
  blocks: [workingState({ id: "scratch", schema })],
});

For production, pass a durable RecordStore. Convex apps can use convexRecordStore() or convexStorage(). Upstash-backed apps can use upstashRedisRecordStore() for Redis records and upstashVectorStore() for vector recall.

Vector Recall

Some memory blocks can use vector search when configured with a vector-capable storage bundle.

const history = episodes({
  id: "history",
  embed: dense,
});

Rules:

1. If vectors is configured, embedding-backed blocks can recall semantically relevant entries.
2. If vectors is not configured, blocks that can degrade safely fall back to non-vector behavior such as recency or listing.
3. Memory vector search filters by namespace and blockId, hydrates JSON records before returning public entries, skips expired or missing records, and applies threshold and limit.

For dense, sparse, and hybrid vector capabilities, see VectorStore.

TTL And Cache-Like Memory

Memory records can use stores that support TTL. TTL is a record-store feature, not a memory-only feature.

await records.put(
  "memory:temporary-note",
  {
    content: "Remember this only briefly.",
  },
  { ttlMs: 300_000 },
);

Use TTL for short-lived scratch records, resolver caches, or temporary agent state. Do not use TTL for facts, episodes, or user preferences that should survive future sessions.

Reactive Memory UI

Memory records can be rendered reactively through the same transport layer as plans and tasks.

Use:

• Convex transport for Convex apps.
• SSE transport when the store implements subscribe().
• Polling transport for universal fallback.

import {
  CruxProvider,
  createPollingTransport,
  useWorkingMemory,
} from "@use-crux/react";

const transport = createPollingTransport(records);

function MemoryPanel() {
  const profile = useWorkingMemory<{ tone: string }>("profile");
  return <pre>{JSON.stringify(profile, null, 2)}</pre>;
}

<CruxProvider transport={transport}>
  <MemoryPanel />
</CruxProvider>;

See React reference for exact hook and transport APIs.

Production Choices

For memory, choose storage based on the behavior you need:

Related