Edit Contexts

Guide Overview

After this guide, you’ll be able to:

Replace messages mid-conversation (e.g. system prompts)
Delete messages mid-conversation
Track every context change

Why Edit Contexts?

You want to tweak the system prompt. But first, the ritual. Copy it somewhere. Just in case. Make the edit. Test. It’s worse. What was the prompt before? You’re debugging blind—reconstructing from memory. And editing without losing the audit trail? A pain. What if you could skip the ritual? Edit anything. Never lose the original. Every change tracked. Rewind anytime. Effortlessly. UltraContext gives you that out of the box. Update or delete any message with a single API call. Every change creates a new version. The original is preserved. Add metadata to track why. Full audit trail, full control. Zero complexity. Edit freely. The system remembers.

Editing Contexts

Updates and deletes automatically create new versions. This means you can always rewind to any mutation point.

import { UltraContext } from 'ultracontext';

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

// create context and append messages (v0)
const ctx = await uc.create();
await uc.append(ctx.id, { role: 'system', content: 'You are a helpful assistant.' });
await uc.append(ctx.id, { role: 'user', content: 'Hello!' });
await uc.append(ctx.id, { role: 'assistant', content: 'Hi there!' });

// replace system prompt (v1)
await uc.update(ctx.id, { index: 0, content: 'You are a concise assistant.' });

// delete last message (v2)
await uc.delete(ctx.id, -1);

// update with audit metadata (v3)
await uc.update(
    ctx.id,
    { index: 0, content: 'You are a concise assistant. Always cite sources.' },
    { metadata: { reason: 'Added citation requirement', author: 'alice' } }
);

// Result:
// {
//   data: [
//     { role: 'system', content: 'You are a concise assistant. Always cite sources.' },
//     { role: 'user', content: 'Hello!' }
//   ],
//   version: 3
// }

from ultracontext import UltraContext
import os

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

# create context and append messages (v0)
ctx = uc.create()
uc.append(ctx["id"], {"role": "system", "content": "You are a helpful assistant."})
uc.append(ctx["id"], {"role": "user", "content": "Hello!"})
uc.append(ctx["id"], {"role": "assistant", "content": "Hi there!"})

# replace system prompt (v1)
uc.update(ctx["id"], index=0, content="You are a concise assistant.")

# delete last message (v2)
uc.delete(ctx["id"], -1)

# update with audit metadata (v3)
uc.update(
    ctx["id"],
    index=0,
    content="You are a concise assistant. Always cite sources.",
    metadata={"reason": "Added citation requirement", "author": "alice"}
)

# Result:
# {
#   "data": [
#     { "role": "system", "content": "You are a concise assistant. Always cite sources." },
#     { "role": "user", "content": "Hello!" }
#   ],
#   "version": 3
# }

Appends don’t create new versions. Using before and at is enough to travel back in time for them.

Update Messages

Update by message ID or index:

// by ID
await uc.update(contextId, { id: 'msg_abc', content: 'Fixed content' });

// by index (0 = first, -1 = last)
await uc.update(contextId, { index: 0, content: 'Fixed first message' });
await uc.update(contextId, { index: -1, content: 'Fixed last message' });

# by ID
uc.update(context_id, id="msg_abc", content="Fixed content")

# by index (0 = first, -1 = last)
uc.update(context_id, index=0, content="Fixed first message")
uc.update(context_id, index=-1, content="Fixed last message")

Update multiple messages

await uc.update(contextId, [
    { id: 'msg_abc', content: 'Fixed content 1' },
    { id: 'msg_def', content: 'Fixed content 2' },
]);

uc.update(context_id, [
    {"id": "msg_abc", "content": "Fixed content 1"},
    {"id": "msg_def", "content": "Fixed content 2"},
])

Partial updates

Updates are partial by default. Only the fields you specify get changed. Everything else stays intact.

// original message
// {
//   role: 'assistant',
//   content: 'Hello!',
//   tool_calls: [{ id: 'call_1', name: 'search' }],
//   metadata: { model: 'gpt-4', tokens: 150 }
// }

// update only the content
await uc.update(contextId, { index: 0, content: 'Hi there!' });

// result: content changed, everything else preserved
// {
//   role: 'assistant',
//   content: 'Hi there!',
//   tool_calls: [{ id: 'call_1', name: 'search' }],
//   metadata: { model: 'gpt-4', tokens: 150 }
// }

# original message
# {
#   "role": "assistant",
#   "content": "Hello!",
#   "tool_calls": [{"id": "call_1", "name": "search"}],
#   "metadata": {"model": "gpt-4", "tokens": 150}
# }

# update only the content
uc.update(context_id, index=0, content="Hi there!")

# result: content changed, everything else preserved
# {
#   "role": "assistant",
#   "content": "Hi there!",
#   "tool_calls": [{"id": "call_1", "name": "search"}],
#   "metadata": {"model": "gpt-4", "tokens": 150}
# }

Delete Messages

Soft delete vs hard delete — one method, two behaviors.

Soft delete — uc.delete(contextId, ids). Removes messages from the current version but creates a new version; deleted messages are preserved in prior versions and recoverable via uc.get(contextId, { version: N }).
Hard delete — uc.delete(contextId, { permanent: true }). Wipes the entire context, all versions, all messages. Irreversible.

The second argument is always required — this prevents accidental context wipes from typos.

Delete by ID or index:

// by ID
await uc.delete(contextId, 'msg_abc');

// by index
await uc.delete(contextId, 0); // first message
await uc.delete(contextId, -1); // last message

# by ID
uc.delete(context_id, "msg_abc")

# by index
uc.delete(context_id, 0)  # first message
uc.delete(context_id, -1)  # last message

Delete multiple messages

// by IDs
await uc.delete(contextId, ['msg_abc', 'msg_def']);

// by indices
await uc.delete(contextId, [0, 2, 4]);

// mixed
await uc.delete(contextId, ['msg_abc', 1, -1]);

# by IDs
uc.delete(context_id, ["msg_abc", "msg_def"])

# by indices
uc.delete(context_id, [0, 2, 4])

# mixed
uc.delete(context_id, ["msg_abc", 1, -1])

Including Metadata

Include metadata to track why changes were made. It is optional, but recommended to make audit trail easier to understand.

await uc.update(contextId, { id: 'msg_abc', content: 'Fixed typo' }, { metadata: { reason: 'typo', author: 'alice' } });

await uc.delete(contextId, 'msg_xyz', {
    metadata: { reason: 'hallucination', ticket: 'JIRA-123' },
});

uc.update(context_id, id="msg_abc", content="Fixed typo", metadata={"reason": "typo", "author": "alice"})

uc.delete(context_id, "msg_xyz", metadata={"reason": "hallucination", "ticket": "JIRA-123"})

View the audit trail:

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

// versions[2] = {
//   operation: 'update',
//   affected: ['msg_abc'],
//   metadata: { reason: 'typo', author: 'alice' }
// }

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

# result["versions"][2] = {
#   "operation": "update",
#   "affected": ["msg_abc"],
#   "metadata": { "reason": "typo", "author": "alice" }
# }

Examples

Replace System Prompt

import { UltraContext } from 'ultracontext';

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

// create context with system prompt
const ctx = await uc.create();
await uc.append(ctx.id, { role: 'system', content: 'You are a helpful assistant.' });
await uc.append(ctx.id, { role: 'user', content: 'Hello!' });

// replace system prompt (index 0)
await uc.update(ctx.id, { index: 0, content: 'You are a concise assistant. Always cite sources.' });

// previous version preserved - roll back anytime
const previous = await uc.get(ctx.id, { version: 0 });

from ultracontext import UltraContext
import os

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

# create context with system prompt
ctx = uc.create()
uc.append(ctx["id"], {"role": "system", "content": "You are a helpful assistant."})
uc.append(ctx["id"], {"role": "user", "content": "Hello!"})

# replace system prompt (index 0)
uc.update(ctx["id"], index=0, content="You are a concise assistant. Always cite sources.")

# previous version preserved - roll back anytime
previous = uc.get(ctx["id"], version=0)

Track prompt_version in the message metadata. This lets you correlate agent behavior with specific prompt versions.

Undo Last Message

Remove the last message from the conversation.

import { UltraContext } from 'ultracontext';

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

// create a new context
const { id: contextId } = await uc.create();

// add messages to the context
await uc.append(contextId, { role: 'user', content: 'Hello!' });
await uc.append(contextId, { role: 'assistant', content: 'Hi there!' });

// At this point, the context looks like this (v0):
// {
//   version: 0,
//   data: [
//     { role: 'user', content: 'Hello!' },
//     { role: 'assistant', content: 'Hi there!' }
//   ]
// }

// oops, undo the last message
await uc.delete(contextId, -1);

// After deleting the last message, the context looks like this (v1):
// {
//   version: 1,
//   data: [
//     { role: 'user', content: 'Hello!' }
//   ]
// }

from ultracontext import UltraContext
import os

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

# create a new context
ctx = uc.create()
context_id = ctx["id"]

# add messages to the context
uc.append(context_id, {"role": "user", "content": "Hello!"})
uc.append(context_id, {"role": "assistant", "content": "Hi there!"})

# At this point, the context looks like this (v0):
# {
#   "version": 0,
#   "data": [
#     { "role": "user", "content": "Hello!" },
#     { "role": "assistant", "content": "Hi there!" }
#   ]
# }

# oops, undo the last message
uc.delete(context_id, -1)

# After deleting the last message, the context looks like this (v1):
# {
#   "version": 1,
#   "data": [
#     { "role": "user", "content": "Hello!" }
#   ]
# }

Deleting a message creates a new version of the conversation. The original is always preserved in the version history. Notice that after deleting the last message, the version number is incremented by 1 in our example, so v0 is completely preserved.

Delete Entire Context

Permanently delete a context and all its versions.

import { UltraContext } from 'ultracontext';

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

// permanent delete — irreversible
await uc.delete('ctx_abc123', { permanent: true });

// with audit metadata (echoed in response + logged server-side)
await uc.delete('ctx_abc123', {
    permanent: true,
    metadata: { reason: 'GDPR request', author: 'alice' },
});
// { deleted: true, id: 'ctx_abc123', metadata: { reason: 'GDPR request', author: 'alice' } }

from ultracontext import UltraContext
import os

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

# permanent delete — irreversible
result = uc.delete("ctx_abc123", permanent=True)

# with audit metadata
result = uc.delete("ctx_abc123", permanent=True, metadata={"reason": "GDPR request", "author": "alice"})
# {"deleted": True, "id": "ctx_abc123", "metadata": {"reason": "GDPR request", "author": "alice"}}

This is irreversible. The context, all its versions, and all messages are permanently deleted. Audit metadata is echoed in the response and logged server-side, but no DB row survives to hold it.

Delete Multiple Contexts

Permanently delete up to 100 contexts in one call.

import { UltraContext } from 'ultracontext';

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

const { results, deleted_count } = await uc.deleteMany(['ctx_abc123', 'ctx_def456']);

for (const r of results) {
    if (r.deleted) console.log(`Deleted ${r.id}`);
    else console.log(`Failed ${r.id}: ${r.error}`);
}

from ultracontext import UltraContext
import os

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

result = uc.delete_many(["ctx_abc123", "ctx_def456"])

for r in result["results"]:
    if r["deleted"]:
        print(f"Deleted {r['id']}")
    else:
        print(f"Failed {r['id']}: {r.get('error')}")

Returns per-context results so partial failures don’t block the entire operation. Status code is 200 on full success, 207 on partial, 500 when every item fails — SDKs pass through the response body in all three cases.

Context API

Fundamentals

Guides

Guide Overview

Why Edit Contexts?

Editing Contexts

Update Messages

Update multiple messages

Partial updates

Delete Messages

Delete multiple messages

Including Metadata

Examples

Replace System Prompt

Undo Last Message

Delete Entire Context

Delete Multiple Contexts

See also: Fork & Clone Contexts

​Guide Overview

​Why Edit Contexts?

​Editing Contexts

​Update Messages

​Update multiple messages

​Partial updates

​Delete Messages

​Delete multiple messages

​Including Metadata

​Examples

​Replace System Prompt

​Undo Last Message

​Delete Entire Context

​Delete Multiple Contexts

See also: Fork & Clone Contexts

Guide Overview

Why Edit Contexts?

Editing Contexts

Update Messages

Update multiple messages

Partial updates

Delete Messages

Delete multiple messages

Including Metadata

Examples

Replace System Prompt

Undo Last Message

Delete Entire Context

Delete Multiple Contexts