Copy Session

Create independent copies of sessions with all messages, tasks, and configurations intact. Perfect for experimentation, checkpointing, and branching workflows.

Use Cases

Experimentation: Try different approaches without affecting the original conversation
Checkpointing: Save progress at key decision points
Branching workflows: Explore parallel conversation paths from a common starting point
Template sessions: Reuse successful session patterns

Basic Usage

from acontext import AcontextClient
import os

client = AcontextClient(api_key=os.getenv("ACONTEXT_API_KEY"))

# Copy a session
result = client.sessions.copy(session_id="session-uuid")

print(f"Original session: {result.old_session_id}")
print(f"Copied session: {result.new_session_id}")

# Now you can modify the copied session independently
client.sessions.store_message(
    session_id=result.new_session_id,
    blob={"role": "user", "content": "Let's try a different approach"},
    format="openai"
)

import { AcontextClient } from '@acontext/acontext';

const client = new AcontextClient({
    apiKey: process.env.ACONTEXT_API_KEY,
});

// Copy a session
const result = await client.sessions.copy("session-uuid");

console.log(`Original session: ${result.oldSessionId}`);
console.log(`Copied session: ${result.newSessionId}`);

// Now you can modify the copied session independently
await client.sessions.storeMessage(
    result.newSessionId,
    { role: "user", content: "Let's try a different approach" },
    { format: "openai" }
);

Async Usage

from acontext import AsyncAcontextClient
import os
import asyncio

async def copy_example():
    async with AsyncAcontextClient(api_key=os.getenv("ACONTEXT_API_KEY")) as client:
        result = await client.sessions.copy(session_id="session-uuid")
        print(f"Copied session: {result.new_session_id}")

asyncio.run(copy_example())

import { AcontextClient } from '@acontext/acontext';

const client = new AcontextClient({
    apiKey: process.env.ACONTEXT_API_KEY,
});

const result = await client.sessions.copy("session-uuid");
console.log(`Copied session: ${result.newSessionId}`);

What Gets Copied

When you copy a session, the following are duplicated:

Messages: All messages with preserved parent-child relationships
Tasks: All tasks with their order, status, and data
Configurations: Session configs and settings
User association: The copied session belongs to the same project

What Doesn't Get Copied

Asset files: S3 assets are shared (not duplicated) between sessions for efficiency
Message processing status: Copied messages are marked as "pending" for reprocessing
Task-message links: These are cleared and will be reassigned by the core service

Independence

The copied session is completely independent:

Changes to the original session don't affect the copy
Changes to the copy don't affect the original
Each session can have different messages, tasks, and configs going forward

Limitations

Size Limit

Sessions with more than 5,000 messages cannot be copied synchronously. You'll receive an error:

{
  "error": "SESSION_TOO_LARGE",
  "message": "Session exceeds maximum copyable size (5000 messages). Consider using async copy."
}

For large sessions, async copy support is planned for a future release.

Error Handling

from acontext import AcontextClient
from acontext.exceptions import AcontextError

client = AcontextClient(api_key="...")

try:
    result = client.sessions.copy(session_id="invalid-uuid")
except AcontextError as e:
    if "SESSION_NOT_FOUND" in str(e):
        print("Session does not exist or you don't have access")
    elif "SESSION_TOO_LARGE" in str(e):
        print("Session is too large to copy synchronously")
    else:
        print(f"Copy failed: {e}")

import { AcontextClient } from '@acontext/acontext';

const client = new AcontextClient({ apiKey: "..." });

try {
    const result = await client.sessions.copy("invalid-uuid");
} catch (error) {
    const message = error.message || String(error);
    
    if (message.includes("SESSION_NOT_FOUND")) {
        console.log("Session does not exist or you don't have access");
    } else if (message.includes("SESSION_TOO_LARGE")) {
        console.log("Session is too large to copy synchronously");
    } else {
        console.log(`Copy failed: ${error}`);
    }
}

Common Patterns

Experiment and Compare

Copy a session to try different approaches, then compare results:

result = client.sessions.copy(session_id=original_id)
experimental_id = result.new_session_id

client.sessions.store_message(
    session_id=experimental_id,
    blob={"role": "user", "content": "Alternative approach..."},
    format="openai"
)

original = client.sessions.get_token_counts(session_id=original_id)
experimental = client.sessions.get_token_counts(session_id=experimental_id)

print(f"Original: {original.total_tokens} tokens")
print(f"Experimental: {experimental.total_tokens} tokens")

const result = await client.sessions.copy(originalId);
const experimentalId = result.newSessionId;

await client.sessions.storeMessage(
    experimentalId,
    { role: "user", content: "Alternative approach..." },
    { format: "openai" }
);

const original = await client.sessions.getTokenCounts(originalId);
const experimental = await client.sessions.getTokenCounts(experimentalId);

console.log(`Original: ${original.totalTokens} tokens`);
console.log(`Experimental: ${experimental.totalTokens} tokens`);

Checkpoint Before Major Changes

Create a checkpoint before making significant changes:

checkpoint = client.sessions.copy(session_id=session_id)
print(f"Checkpoint created: {checkpoint.new_session_id}")

client.sessions.store_message(
    session_id=session_id,
    blob={"role": "user", "content": "Major change..."},
    format="openai"
)

const checkpoint = await client.sessions.copy(sessionId);
console.log(`Checkpoint created: ${checkpoint.newSessionId}`);

await client.sessions.storeMessage(
    sessionId,
    { role: "user", content: "Major change..." },
    { format: "openai" }
);

Template Sessions

Create a base session as a template and copy it for each new conversation:

template_id = "template-session-uuid"
client.sessions.store_message(
    session_id=template_id,
    blob={"role": "system", "content": "You are a helpful assistant..."},
    format="openai"
)

new_conversation = client.sessions.copy(session_id=template_id)

const templateId = "template-session-uuid";
await client.sessions.storeMessage(
    templateId,
    { role: "system", content: "You are a helpful assistant..." },
    { format: "openai" }
);

const newConversation = await client.sessions.copy(templateId);

Performance

Copy operations typically complete in:

< 1 second: Sessions with < 100 messages
< 3 seconds: Sessions with < 1000 messages
< 5 seconds: Sessions with < 5000 messages

The operation is atomic - either the entire copy succeeds or fails with no partial state.

Copy Session

On this page