Skip to main content
Acontext provides a flexible message storage system that supports multiple LLM providers (OpenAI, Anthropic, Google Gemini). You can store messages then retrieve them later for analysis, debugging, or continuing conversations.

​
Prerequisites

Before storing messages, you need:
  • A running Acontext server (run locally)
  • An Acontext API key (default is sk-ac-your-root-api-bearer-token)
Messages are stored within sessions. Create a session first, then store messages to it.

​
Storing messages

​
Create a session first

Before storing messages, create a session: 
from acontext import AcontextClient

client = AcontextClient(
    api_key="sk-ac-your-root-api-bearer-token",
    base_url="http://localhost:8029/api/v1"
)
client.ping()
# Create a session
session = client.sessions.create()
print(f"Session created: {session.id}")

​
Store a single message

Store messages in OpenAI, Anthropic, or Gemini format: 
from acontext import AcontextClient

client = AcontextClient(
    api_key="sk-ac-your-root-api-bearer-token",
    base_url="http://localhost:8029/api/v1"
)
session = client.sessions.create()

# Store a message in OpenAI format
message = client.sessions.store_message(
    session_id=session.id,
    blob={
        "role": "user",
        "content": "What is the capital of France?"
    },
    format="openai"
)

print(f"Message stored: {message.id}")

​
Store multiple messages

You can store multiple messages sequentially to build a conversation: 
from acontext import AcontextClient

client = AcontextClient(
    api_key="sk-ac-your-root-api-bearer-token",
    base_url="http://localhost:8029/api/v1"
)
session = client.sessions.create()

# Store multiple messages to build a conversation
messages_to_store = [
    {"role": "user", "content": "Hello! Can you help me with Python?"},
    {"role": "assistant", "content": "Of course! I'd be happy to help with Python. What would you like to know?"},
    {"role": "user", "content": "How do I read a JSON file?"},
    {"role": "assistant", "content": "You can use the json module: import json; with open('file.json') as f: data = json.load(f)"}
]

for msg in messages_to_store:
    message = client.sessions.store_message(
        session_id=session.id,
        blob=msg,
        format="openai"
    )
    print(f"Stored message: {message.id}")

print(f"Total messages stored: {len(messages_to_store)}")
Each message receives a unique ID upon creation. You can use these IDs to reference specific messages later.

​
Retrieving messages

​
Get all messages from a session

Retrieve messages from a session: 
from acontext import AcontextClient

client = AcontextClient(
    api_key="sk-ac-your-root-api-bearer-token",
    base_url="http://localhost:8029/api/v1"
)

# Get messages from a session
result = client.sessions.get_messages(
    session_id="session_uuid",
    format="openai"
)

print(f"Retrieved {len(result.items)} messages")
for msg in result.items:
    print(f"- {msg.role}: {msg.content[:50]}...")

​
Session observability

Acontext provides built-in observability features to help you monitor and analyze your message sessions in real-time.
You can track various metrics and insights about your sessions:

Message Observing Status

Monitor the processing status of messages in your session: observed, in_process, and pending counts.

Session Tasks

View all tasks and agent operations associated with a session for debugging and analysis.

Dashboard Visualization

Access the Acontext dashboard to visualize message flows, traces, and session analytics.

Disable Task Tracking

Disable automatic task tracking for sessions that don’t need task analysis or monitoring.

​
Message format compatibility

Acontext supports three message formats for maximum compatibility:

OpenAI Format

Compatible with OpenAI’s Chat Completion API format. Use for GPT-3.5, GPT-4, and similar models.

Anthropic Format

Compatible with Anthropic’s Messages API format. Use for Claude models.

Gemini Format

Compatible with Google’s Gemini API format. Use for Gemini Pro, Gemini Flash, and other Gemini models.
You can store messages in one format and retrieve them in another. Acontext automatically handles format conversion.

​
Complete workflow example

Here’s a complete example showing how to store and retrieve a conversation: 
from acontext import AcontextClient

# Initialize client
client = AcontextClient(
    api_key="sk-ac-your-root-api-bearer-token",
    base_url="http://localhost:8029/api/v1"
)

try:
    # 1. Create a session
    session = client.sessions.create()
    
    # 2. Store multiple messages
    conversation = [
        {"role": "user", "content": "I'm having trouble logging in"},
        {"role": "assistant", "content": "I can help with that. What error are you seeing?"},
        {"role": "user", "content": "It says 'Invalid credentials'"},
        {"role": "assistant", "content": "Try resetting your password using the forgot password link."}
    ]
    
    for msg in conversation:
        client.sessions.store_message(
            session_id=session.id,
            blob=msg,
            format="openai"
        )
    
    print(f"Stored {len(conversation)} messages in session {session.id}")
    
    # 3. Retrieve messages later
    result = client.sessions.get_messages(
        session_id=session.id,
        format="openai"
    )
    
    print(f"\nRetrieved conversation ({len(result.items)} messages):")
    for msg in result.items:
        print(f"{msg.role}: {msg.content}")
        
finally:
    client.close()

​
Managing sessions

​
Delete a session

When you’re done with a conversation or workflow, you can delete the session to clean up storage: 
from acontext import AcontextClient

client = AcontextClient(
    api_key="sk-ac-your-root-api-bearer-token",
    base_url="http://localhost:8029/api/v1"
)

# Delete a session when you're done with it
session_id = "session_uuid"
client.sessions.delete(session_id)

print(f"Session {session_id} deleted successfully")
Deleting a session permanently removes all associated messages. This action cannot be undone.

​
List and clean up old sessions

You can list sessions and delete the ones you no longer need: 
from acontext import AcontextClient

client = AcontextClient(
    api_key="sk-ac-your-root-api-bearer-token",
    base_url="http://localhost:8029/api/v1"
)

# List all sessions
sessions = client.sessions.list(limit=100, time_desc=True)

print(f"Found {len(sessions.items)} sessions")

# Delete old sessions (example: delete all except the most recent 10)
for session in sessions.items[10:]:
    client.sessions.delete(session.id)
    print(f"Deleted session {session.id}")

​
Best practices

  • Use sessions to group related messages (e.g., one conversation, one task)
  • Create a new session for each distinct conversation or workflow
  • Use OpenAI format if you’re working with OpenAI models or want broad compatibility
  • Use Anthropic format if you’re primarily using Claude models
  • Use Gemini format if you’re working with Google Gemini models (Gemini Pro, Gemini Flash, etc.)
  • You can convert between formats when retrieving messages
  • Use message observing status to track message processing states in real-time
  • Monitor token counts to stay within context limits and manage API costs
  • Review session tasks to understand agent behavior and debug issues
  • Leverage the dashboard for visual insights into message flows and patterns

​
Next steps

Store Artifacts

Learn how to store files and documents alongside your messages

Dashboard

View and analyze your messages with visual insights and metrics

Traces

Debug and monitor message flows with detailed execution traces

Agent Tasks

Track and observe agent operations and task executions