Store & Retrieve Contexts

Guide Overview

After this guide, you’ll be able to:

Persist context across sessions (e.g. chats, conversations)
Retrieve context from a specific point in time

Why Store & Retrieve Contexts?

Picture this: You build a simple AI agent. Works like a charm. As it gets more useful, you wanna save messages so you can get back to past conversations. Sounds simple, right? So you start storing them somewhere. You didn’t notice it yet, but complexity quietly added up in your system. You’re now dealing with timestamps, ordering, metadata and sessions. At some point, while implementing a tiny custom feature, you realize you’ve been wasting more time on infrastructure rather than on the agent itself. You feel frustrated. The initial excitement fades away. Welcome to the club. What if infrastructure wasn’t the bottleneck? Everything would be way simpler. With UltraContext, storing and retrieving contexts is trivial. From now on, we’ll do the heavy lifting for you. It’s time to build.

Storing Contexts

Create a context and append messages:

import { UltraContext } from 'ultracontext';

const uc = new UltraContext({ apiKey: process.env.ULTRACONTEXT_API_KEY });

// create a new context
const ctx = await uc.create();
// → { id: 'ctx_abc123', created_at: '2024-01-10T10:00:00Z' }

// append messages
await uc.append(ctx.id, { role: 'system', content: 'You are a helpful assistant.' });
await uc.append(ctx.id, { role: 'user', content: 'Hello! What is the capital of France?' });

// append multiple messages at once
await uc.append(ctx.id, [
    { role: 'assistant', content: 'Paris is the capital of France.' },
    { role: 'user', content: 'Thank you!' },
]);

// Stored as:
// {
//    data: [
//        { id: 'msg_a1b2c3', index: 0, role: 'system', content: 'You are a helpful assistant.' },
//        { id: 'msg_d4e5f6', index: 1, role: 'user', content: 'Hello! What is the capital of France?' },
//        { id: 'msg_g7h8i9', index: 2, role: 'assistant', content: 'Paris is the capital of France.' },
//        { id: 'msg_j0k1l2', index: 3, role: 'user', content: 'Thank you!' },
//    ],
//    version: 0
// }

from ultracontext import UltraContext
import os

uc = UltraContext(api_key=os.environ["ULTRACONTEXT_API_KEY"])

# create a new context
ctx = uc.create()
# → { "id": "ctx_abc123", "created_at": "2024-01-10T10:00:00Z" }

# append messages
uc.append(ctx["id"], {"role": "system", "content": "You are a helpful assistant."})
uc.append(ctx["id"], {"role": "user", "content": "Hello! What is the capital of France?"})

# append multiple messages at once
uc.append(ctx["id"], [
    {"role": "assistant", "content": "Paris is the capital of France."},
    {"role": "user", "content": "Thank you!"},
])

# Stored as:
# {
#    "data": [
#        { "id": "msg_a1b2c3", "index": 0, "role": "system", "content": "You are a helpful assistant." },
#        { "id": "msg_d4e5f6", "index": 1, "role": "user", "content": "Hello! What is the capital of France?" },
#        { "id": "msg_g7h8i9", "index": 2, "role": "assistant", "content": "Paris is the capital of France." },
#        { "id": "msg_j0k1l2", "index": 3, "role": "user", "content": "Thank you!" },
#    ],
#    "version": 0
# }

Appends don’t generate new versions—only updates and deletes do. This means you can travel back in time by index or timestamp without version overhead. See the View Context History guide for more details.

UltraContext is schema-free. Store any fields you need. Only id and index are reserved keys.

Metadata

Attach metadata at both the context level and message level:

// Metadata at context level
const ctx = await uc.create({
    metadata: { user_id: 'u_123', session_type: 'support' },
});
// → {
//     id: 'ctx_abc123',
//     created_at: '2024-01-10T10:00:00Z',
//     metadata: { user_id: 'u_123', session_type: 'support' }
//   }

// Metadata at message level
await uc.append(ctx.id, {
    role: 'user',
    content: 'Hello!',
    metadata: { source: 'web', ip: '192.168.1.1' },
});
// → stored as:
// {
//     id: 'msg_abc',
//     index: 0,
//     role: 'user',
//     content: 'Hello!',
//     metadata: { source: 'web', ip: '192.168.1.1' }
// }

#  Metadata at context level
ctx = uc.create(metadata={"user_id": "u_123", "session_type": "support"})
# → {
#     "id": "ctx_abc123",
#     "created_at": "2024-01-10T10:00:00Z",
#     "metadata": { "user_id": "u_123", "session_type": "support" }
#   }

# Metadata at message level
uc.append(ctx["id"], {
    "role": "user",
    "content": "Hello!",
    "metadata": {"source": "web", "ip": "192.168.1.1"},
})
# → stored as:
# {
#     "id": "msg_abc",
#     "index": 0,
#     "role": "user",
#     "content": "Hello!",
#     "metadata": { "source": "web", "ip": "192.168.1.1" }
# }

Context level metadata is useful for:

User IDs
Session types

Message level metadata is great for:

Marking checkpoints
Token usage
Model

Retrieving Contexts

Multiple ways to fetch context: current state, specific version, point in time, or by message index.

// current state
const { data, version } = await uc.get(contextId);

// by index — first N messages (0 to at)
const { data } = await uc.get(contextId, { at: 5 });

// by timestamp — state at that moment. Uses ISO 8601 format
const { data } = await uc.get(contextId, { before: '2024-01-10T10:30:00Z' });

// by version — exact state after that mutation
const { data } = await uc.get(contextId, { version: 1 });

// with history — see all mutations
const { data, version, versions } = await uc.get(contextId, { history: true });

# current state
result = uc.get(context_id)

# by index — first N messages (0 to at)
result = uc.get(context_id, at=5)

# by timestamp — state at that moment. Uses ISO 8601 format
result = uc.get(context_id, before="2024-01-10T10:30:00Z")

# by version — exact state after that mutation
result = uc.get(context_id, version=1)

# with history — see all mutations
result = uc.get(context_id, history=True)

Get current state

const { data, version } = await uc.get(contextId);

result = uc.get(context_id)
data, version = result["data"], result["version"]

Retrieve by index

Get messages 0 through a specific index:

// first 6 messages (indices 0-5)
const { data } = await uc.get(contextId, { at: 5 });

# first 6 messages (indices 0-5)
result = uc.get(context_id, at=5)

Retrieve by timestamp

Get state at any point in time:

const { data } = await uc.get(contextId, { before: '2024-01-10T10:30:00Z' });

result = uc.get(context_id, before="2024-01-10T10:30:00Z")

Retrieve by version

Use history: true to see what mutations happened and which versions exist:

const { data, version, versions } = await uc.get(contextId, { history: true });

// → versions: [
//    { version: 0, operation: 'create', affected: null, created_at: '...' },
//    { version: 1, operation: 'update', affected: ['msg_abc'], created_at: '...' },
// ]

result = uc.get(context_id, history=True)

# → result["versions"]: [
#     { "version": 0, "operation": "create", "affected": None, "created_at": "..." },
#     { "version": 1, "operation": "update", "affected": ["msg_abc"], "created_at": "..." },
#   ]

Then you can retrieve the state at a specific version:

const { data } = await uc.get(contextId, { version: 1 });

result = uc.get(context_id, version=1)

See View Context History for advanced time-travel patterns.

Listing Contexts

List all contexts in your project. By default, contexts are sorted by created_at in descending order (newest first).

const { data } = await uc.get();
// → {
//     data: [
//       { id: 'ctx_xyz789', created_at: '2024-01-15T10:00:00Z', metadata: {} },
//       { id: 'ctx_abc123', created_at: '2024-01-10T10:00:00Z', metadata: { user_id: '123' } },
//     ]
//   }

// with limit
const { data } = await uc.get({ limit: 10 });

result = uc.get()
# → {
#     "data": [
#       { "id": "ctx_xyz789", "created_at": "2024-01-15T10:00:00Z", "metadata": {} },
#       { "id": "ctx_abc123", "created_at": "2024-01-10T10:00:00Z", "metadata": { "user_id": "123" } },
#     ]
#   }

# with limit
result = uc.get(limit=10)

Filter by metadata

Filter contexts by metadata fields stored at creation time. All filters are optional and can be combined.

// by source
const { data } = await uc.get({ source: 'claude' });

// by project
const { data } = await uc.get({ project_path: '/Users/alice/Code/myapp' });

// by machine
const { data } = await uc.get({ host: 'Mac-mini.local' });

// by time range
const { data } = await uc.get({ after: '2026-03-01T00:00:00Z', before: '2026-03-08T00:00:00Z' });

// combine filters
const { data } = await uc.get({ source: 'codex', host: 'Mac-mini.local', limit: 5 });

# by source
result = uc.get(source="claude")

# by project
result = uc.get(project_path="/Users/alice/Code/myapp")

# by machine
result = uc.get(host="Mac-mini.local")

# by time range
result = uc.get(after="2026-03-01T00:00:00Z", before="2026-03-08T00:00:00Z")

# combine filters
result = uc.get(source="codex", host="Mac-mini.local", limit=5)

Filter	Description
`source`	Agent source (`claude`, `codex`, `openclaw`)
`user_id`	User identifier
`host`	Machine hostname
`project_path`	Project directory path
`session_id`	Session identifier
`after`	Only contexts created after this ISO 8601 timestamp
`before`	Only contexts created before this ISO 8601 timestamp

Metadata filters use a GIN index on the metadata JSONB column for fast lookups.

Examples

Resume Chats

Resuming chats is simple. Just retrieve the associated context and continue the conversation from there.

import { UltraContext } from 'ultracontext';

const uc = new UltraContext({ apiKey: process.env.ULTRACONTEXT_API_KEY });

// on first visit: create context, store ID in your session/database
const ctx = await uc.create();

// on each message exchange: append both sides
await uc.append(ctx.id, { role: 'user', content: userMessage });
await uc.append(ctx.id, { role: 'assistant', content: assistantResponse });

// on return visit: retrieve existing context
const { data: messages } = await uc.get(ctx.id);
// → ready to send to LLM or display in UI

from ultracontext import UltraContext
import os

uc = UltraContext(api_key=os.environ["ULTRACONTEXT_API_KEY"])

# on first visit: create context, store ID in your session/database
ctx = uc.create()

# on each message exchange: append both sides
uc.append(ctx["id"], {"role": "user", "content": user_message})
uc.append(ctx["id"], {"role": "assistant", "content": assistant_response})

# on return visit: retrieve existing context
result = uc.get(ctx["id"])
# → ready to send to LLM or display in UI

Store the contextId in your session, database, or URL. Retrieve it on return visits to resume the conversation.

Retrieve to Checkpoint

Retrieve the context up to a specific checkpoint.

Mark your checkpoint with metadata as you go

await uc.append(contextId, {
    role: 'assistant',
    content: 'I now have full context of your codebase.',
    metadata: { checkpoint: 'codebase_indexed' },
});

uc.append(context_id, {
    "role": "assistant",
    "content": "I now have full context of your codebase.",
    "metadata": {"checkpoint": "codebase_indexed"},
})

Find checkpoint index

const { data: history } = await uc.get(contextId);
const checkpointIndex = history.findIndex((m) => m.metadata?.checkpoint === 'codebase_indexed');

result = uc.get(context_id)
history = result["data"]
checkpoint_index = next(i for i, m in enumerate(history) if m.get("metadata", {}).get("checkpoint") == "codebase_indexed")

Retrieve messages up to checkpoint

const { data: messages } = await uc.get(contextId, { at: checkpointIndex });

result = uc.get(context_id, at=checkpoint_index)
messages = result["data"]

(Optional) Fork context from checkpoint

const fork = await uc.create({ from: contextId, at: checkpointIndex });

fork = uc.create(from_=context_id, at=checkpoint_index)

You can use metadata to retrieve a context up to a specific relevant part, discard everything after that point to start a fresh context from there.Forking is a great way to carry context over new sessions while maintaining a high signal-to-noise token ratio (and still preserving the original).See the Fork & Clone Contexts guide for this pattern.

Start Fresh with Summary

Start a new context with a summary of the previous one.

Get latest context

// list all contexts (newest first)
const { data: contexts } = await uc.get();

// get messages from the latest
const { data: messages } = await uc.get(contexts[0].id);

# list all contexts (newest first)
contexts = uc.get()["data"]

# get messages from the latest
messages = uc.get(contexts[0]["id"])["data"]

Summarize context

const summary = await generateSummary(messages);

summary = generate_summary(messages)

Create new context

const ctx = await uc.create();

ctx = uc.create()

Append summary

await uc.append(ctx.id, {
    role: 'system',
    content: `Previous context summary:\n${summary}`,
});

uc.append(ctx["id"], {
    "role": "system",
    "content": f"Previous context summary:\n{summary}",
})

Switch Frameworks

UltraContext is framework-agnostic. Switch between LLM frameworks without changing your stored data.

import { UltraContext } from 'ultracontext';
import OpenAI from 'openai';

const uc = new UltraContext({ apiKey: process.env.ULTRACONTEXT_API_KEY });
const openai = new OpenAI();

// retrieve context
const { data: messages } = await uc.get(contextId);

// prepare messages for OpenAI
const parsed = parseForOpenAI(messages);

const response = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: parsed,
});

import { UltraContext } from 'ultracontext';
import Anthropic from '@anthropic-ai/sdk';

const uc = new UltraContext({ apiKey: process.env.ULTRACONTEXT_API_KEY });
const anthropic = new Anthropic();

// retrieve context
const { data: messages } = await uc.get(contextId);

// prepare messages for Anthropic
const parsed = parseForAnthropic(messages);

const response = await anthropic.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 1024,
    ...parsed,
});

import { UltraContext } from 'ultracontext';
import { GoogleGenerativeAI } from '@google/generative-ai';

const uc = new UltraContext({ apiKey: process.env.ULTRACONTEXT_API_KEY });
const model = new GoogleGenerativeAI(process.env.GOOGLE_API_KEY).getGenerativeModel({ model: 'gemini-1.5-flash' });

// retrieve context
const { data: messages } = await uc.get(contextId);

// prepare messages for Google
const parsed = parseForGoogle(messages);

const response = await model.generateContent({
    contents: parsed,
});

import { UltraContext } from 'ultracontext';
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const uc = new UltraContext({ apiKey: process.env.ULTRACONTEXT_API_KEY });

// retrieve context
const { data: messages } = await uc.get(contextId);

// prepare messages for Vercel AI SDK
const parsed = parseForVercel(messages);

const response = await generateText({
    model: openai('gpt-4o'),
    messages: parsed,
});

from ultracontext import UltraContext
from langchain_openai import ChatOpenAI
import os

uc = UltraContext(api_key=os.environ["ULTRACONTEXT_API_KEY"])
model = ChatOpenAI(model="gpt-4o")

# retrieve context
messages = uc.get(context_id)["data"]

# prepare messages for LangChain
parsed = parse_for_langchain(messages)

response = model.invoke(parsed)

from ultracontext import UltraContext
from crewai import Agent, Task, Crew
import os

uc = UltraContext(api_key=os.environ["ULTRACONTEXT_API_KEY"])
crew = Crew(agents=[...], tasks=[...])

# retrieve context
messages = uc.get(context_id)["data"]

# prepare messages for CrewAI
parsed = parse_for_crewai(messages)

result = crew.kickoff(inputs=parsed)

The parseFor* functions are placeholders—implement based on your schema and each provider’s message format.

Store context once, use anywhere. No vendor lock-in. No data migration when switching providers.

Next: Edit Contexts

Update and delete messages with full audit trail.

Context API

Fundamentals

Guides

Store & Retrieve Contexts

Guide Overview

Why Store & Retrieve Contexts?

Storing Contexts

Metadata

Retrieving Contexts

Get current state

Retrieve by index

Retrieve by timestamp

Retrieve by version

Listing Contexts

Filter by metadata

Examples

Resume Chats

Retrieve to Checkpoint

Start Fresh with Summary

Switch Frameworks

Next: Edit Contexts

​Guide Overview

​Why Store & Retrieve Contexts?

​Storing Contexts

​Metadata

​Retrieving Contexts

​Get current state

​Retrieve by index

​Retrieve by timestamp

​Retrieve by version

​Listing Contexts

​Filter by metadata

​Examples

​Resume Chats

​Retrieve to Checkpoint

​Start Fresh with Summary

​Switch Frameworks

Next: Edit Contexts

Guide Overview

Why Store & Retrieve Contexts?

Storing Contexts

Metadata

Retrieving Contexts

Get current state

Retrieve by index

Retrieve by timestamp

Retrieve by version

Listing Contexts

Filter by metadata

Examples

Resume Chats

Retrieve to Checkpoint

Start Fresh with Summary

Switch Frameworks