Skip to main content

​
Session Message Buffer

Acontext will track the agent task and user feedback in the session, the following settings are used to decide how and when the tracking will be conducted.
​
PROJECT_SESSION_MESSAGE_USE_PREVIOUS_MESSAGES_TURNS
integer
default:"3"
Number of previous message turns to include in the context when processing new incoming messages.Higher values provide more context for task maintaining but consume more tokens.
​
PROJECT_SESSION_MESSAGE_BUFFER_MAX_TURNS
integer
default:"16"
Maximum number of untracked message turns to keep in the session buffer.This controls the size of the messages we want to process at the same time, the larger the buffer, the longer context we can use for once for task maintaining, and the less total token costs.
​
PROJECT_SESSION_MESSAGE_BUFFER_TTL_SECONDS
integer
default:"4"
Time-to-live in seconds for the session buffer.If the session buffer haven’t received any new messsages for the TTL seconds, it will start the process the current messages. This parameter + the max turns parameters make sure the session buffer is not too large and the messages are not too old.

​
Agent Iteration Limits

​
DEFAULT_TASK_AGENT_MAX_ITERATIONS
integer
default:"4"
Maximum number of iterations a task agent can perform before stopping. Prevents infinite loops in task execution.
​
DEFAULT_SOP_AGENT_MAX_ITERATIONS
integer
default:"4"
Maximum number of iterations for Standard Operating Procedure (SOP) agents. Controls how many steps an SOP agent can take.
​
DEFAULT_SPACE_CONSTRUCT_AGENT_MAX_ITERATIONS
integer
default:"16"
Maximum iterations for space construction agents. These agents typically need more iterations to build complex knowledge spaces.

​
.env Examples

# Session Management
PROJECT_SESSION_MESSAGE_USE_PREVIOUS_MESSAGES_TURNS=3
PROJECT_SESSION_MESSAGE_BUFFER_MAX_TURNS=16
PROJECT_SESSION_MESSAGE_BUFFER_MAX_OVERFLOW=16
PROJECT_SESSION_MESSAGE_BUFFER_TTL_SECONDS=4

# Agent Limits
DEFAULT_TASK_AGENT_MAX_ITERATIONS=4
DEFAULT_SOP_AGENT_MAX_ITERATIONS=4
DEFAULT_SPACE_CONSTRUCT_AGENT_MAX_ITERATIONS=16
Setting iteration limits too high may lead to excessive API usage and longer response times. Setting them too low may prevent agents from completing complex tasks.

​
Message Buffer Tuning

​
Buffer Size Impact

  • Small buffers (8-16 turns):
    • ✅ Lower update latency - Tasks and skills update faster
    • ❌ Higher token cost - More frequent processing with less context sharing
  • Large buffers (32+ turns):
    • ✅ Lower token cost - Batch processing with shared context
    • ❌ Higher update latency - Tasks and skills update less frequently

​
TTL Configuration Impact

  • Short TTL (1-4 seconds):
    • ✅ Near real-time task extraction and skill updates
    • ❌ Higher costs due to frequent processing of smaller batches
  • Long TTL (10+ seconds):
    • ✅ Cost efficient batch processing
    • ❌ Delayed updates for tasks and skills
For development: Use shorter TTL (2-4s) and smaller buffers (8-16) for faster feedback loops. For production: Use longer TTL (6-10s) and larger buffers (24-32) to optimize costs.