Short-Term Memory

Redis-backed session context with automatic TTL expiration. Fast read/write for current conversation state and temporary working data.

What Is Short-Term Memory?

Short-term memory provides fast, ephemeral storage for session-scoped data. Backed by Redis, it offers sub-millisecond read/write performance for maintaining conversation context, temporary state, and working data that does not need to persist beyond the current session.

Every short-term memory entry has a TTL (time-to-live) that defaults to 3 hours. When the TTL expires, the data is automatically cleaned up. This makes short-term memory ideal for transient context that should not accumulate indefinitely.

When to Use

  • •Maintaining current conversation context (topic, intent, entities mentioned)
  • •Storing temporary working state during multi-step tasks
  • •Caching frequently accessed data for the current session
  • •Passing context between agent tool calls within a session
  • •Any data that should auto-expire and not accumulate

Not for persistent data

Short-term memory is ephemeral by design. For data that should survive beyond the session, use episodic or long-term memory.

Quick Example

Short-term memory operations
import Rekall from '@rekall/sdk';


const rekall = new Rekall({ apiKey: 'rk_your_api_key' });


// Store a value with default TTL (3 hours)
await rekall.shortTerm.set({
  key: 'current_topic',
  value: { topic: 'deployment', intent: 'help' },
  sessionId: 'session_abc123',
});


// Store with custom TTL (1 hour)
await rekall.shortTerm.set({
  key: 'draft_response',
  value: { text: 'Here is the deployment guide...' },
  sessionId: 'session_abc123',
  ttl: 3600,  // seconds
});


// Retrieve a value
const topic = await rekall.shortTerm.get({
  key: 'current_topic',
  sessionId: 'session_abc123',
});


console.log(topic.value); // { topic: 'deployment', intent: 'help' }


// Delete a value
await rekall.shortTerm.delete({
  key: 'draft_response',
  sessionId: 'session_abc123',
});

Fields Reference

FieldTypeRequiredDescription
keystringYesUnique key within the session. Used for get/set/delete operations.
valueanyYesThe data to store. Can be any JSON-serializable value.
session_idstringYesSession identifier. Data is scoped to the session.
ttlnumberNoTime-to-live in seconds. Defaults to 10800 (3 hours). Max: 604800 (7 days).

Advanced Usage

Session Management

Sessions group related short-term memory entries. You can list all keys in a session, clear an entire session, or extend the TTL of all entries.

Session operations
// List all keys in a session
const keys = await rekall.shortTerm.listKeys({
  sessionId: 'session_abc123',
});
console.log(keys); // ['current_topic', 'user_context', ...]


// Clear entire session
await rekall.shortTerm.clearSession('session_abc123');


// Extend TTL for all entries in a session
await rekall.shortTerm.extendSession({
  sessionId: 'session_abc123',
  ttl: 7200, // extend by 2 hours
});

TTL Configuration

You can set TTL at the entry level, session level, or context level. More specific settings override less specific ones.

LevelDefaultScope
Context default10800s (3h)Applies to all entries unless overridden.
Session TTLInherits contextApplies to all entries in the session.
Entry TTLInherits sessionApplies to a single key-value entry.

Use Cases

Conversation Context

Track the current topic, user intent, and entities mentioned in the ongoing conversation. Automatically cleared when the session ends.

Working State

During multi-step tasks, store intermediate results and progress. For example, when generating a report, store collected data points before final assembly.

Tool Call Context

Pass context between agent tool calls within a single session. Store the output of one tool to inform the input of the next.

Rate Limiting State

Track per-session counters, cooldowns, or temporary flags. The TTL ensures automatic cleanup without manual intervention.

Best Practices

  • 1.Use descriptive keys. Keys like "current_topic" or "draft_v2" are clearer than "tmp1" or "data".
  • 2.Set appropriate TTLs. Use shorter TTLs for transient data (minutes to hours) and longer TTLs for session context (hours to days).
  • 3.Keep values small. Redis is optimized for small, fast reads. For large data, store a reference and keep the payload in PostgreSQL.
  • 4.Promote important findings. If something in short-term memory turns out to be important, create an episodic memory before the TTL expires.
  • 5.Clear sessions explicitly. While TTL handles cleanup, explicitly clearing sessions when they end is cleaner and frees Redis memory sooner.
Rekall
rekall