Arcanflows — AI Automation Platform for Business

Overview

Memory and context management determine how your AI agent maintains awareness across conversations. Proper configuration ensures coherent, personalized interactions while managing token usage efficiently.

Types of Memory

1. Conversation Memory (Short-term)

Stores the current conversation history within a single session.

How it works:

Messages are stored in order (user → assistant → user → ...)
Context window limited by model's max tokens
Cleared when conversation ends

Configuration:

json
{
  "memory": {
    "type": "conversation",
    "max_messages": 20,
    "max_tokens": 4000
  }
}

Setting	Description	Default
`max_messages`	Maximum messages to retain	20
`max_tokens`	Token limit for history	4000

2. Summary Memory

Compresses older messages into summaries to preserve context while reducing tokens.

How it works:

Recent messages kept verbatim
Older messages summarized by AI
Summary included in context

Configuration:

json
{
  "memory": {
    "type": "summary",
    "recent_messages": 5,
    "summary_max_tokens": 500,
    "summarize_after": 10
  }
}

Setting	Description	Default
`recent_messages`	Verbatim messages to keep	5
`summary_max_tokens`	Max tokens for summary	500
`summarize_after`	Messages before summarizing	10

3. Long-term Memory

Persists information across conversations for personalization.

What's stored:

User preferences
Key facts learned
Previous conversation summaries
Custom user attributes

Configuration:

json
{
  "memory": {
    "type": "long_term",
    "store_preferences": true,
    "store_facts": true,
    "max_facts": 50,
    "retention_days": 90
  }
}

4. Hybrid Memory

Combines multiple memory types for comprehensive context.

json
{
  "memory": {
    "type": "hybrid",
    "conversation": {
      "max_messages": 15
    },
    "summary": {
      "enabled": true,
      "summarize_after": 20
    },
    "long_term": {
      "enabled": true,
      "store_preferences": true
    }
  }
}

Context Window Management

Understanding Context Windows

Each model has a maximum context window:

Model	Context Window
GPT-4 Turbo	128K tokens
GPT-4	8K / 32K tokens
GPT-3.5 Turbo	16K tokens
Claude 3.5 Sonnet	200K tokens
Claude 3 Opus	200K tokens
Gemini Pro	32K tokens
Llama 3 70B	8K tokens

Token Budget Allocation

Distribute your context window wisely:

Total Context Window: 8,000 tokens
├── System Prompt:     1,000 tokens (12.5%)
├── Knowledge Context: 3,000 tokens (37.5%)
├── Conversation History: 2,500 tokens (31.25%)
├── Current Message:     500 tokens (6.25%)
└── Response Buffer:   1,000 tokens (12.5%)

Sliding Window Strategy

When context exceeds limits, oldest messages are removed:

javascript
// Pseudocode for sliding window
function manageContext(messages, maxTokens) {
  while (countTokens(messages) > maxTokens) {
    messages.shift(); // Remove oldest
  }
  return messages;
}

Session Management

Session Lifecycle

┌─────────────────────────────────────────────────────────┐
│                    Session Lifecycle                     │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  [Start] ──► [Active] ──► [Idle] ──► [Expired]          │
│     │           │           │            │               │
│     │           │           │            ▼               │
│     │           │           │      [Terminated]          │
│     │           │           │                            │
│     │           ▼           │                            │
│     │    [Message Sent]     │                            │
│     │           │           │                            │
│     └───────────┴───────────┘                            │
│                                                          │
└─────────────────────────────────────────────────────────┘

Session Configuration

json
{
  "session": {
    "timeout_minutes": 30,
    "max_duration_hours": 24,
    "persist_on_timeout": true,
    "auto_summarize_on_end": true
  }
}

Setting	Description	Default
`timeout_minutes`	Idle time before expiry	30
`max_duration_hours`	Maximum session length	24
`persist_on_timeout`	Save context on timeout	true
`auto_summarize_on_end`	Create summary on end	true

User Context

Automatic Context Variables

Arcanflows automatically provides user context:

json
{
  "user": {
    "id": "usr_abc123",
    "name": "John Doe",
    "email": "[email protected]",
    "plan": "pro",
    "timezone": "America/New_York",
    "language": "en",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Custom User Attributes

Add custom attributes for personalization:

json
{
  "user_attributes": {
    "department": "Engineering",
    "role": "Developer",
    "preferences": {
      "response_style": "technical",
      "include_examples": true
    }
  }
}

Using Context in Prompts

Reference context in your system prompt:

You are a helpful assistant for {{user.name}}.
They are on the {{user.plan}} plan.

User preferences:
- Response style: {{user_attributes.preferences.response_style}}
- Include examples: {{user_attributes.preferences.include_examples}}

Memory Storage

Database Schema

Memory is stored securely per tenant:

sql
-- Conversation memory
CREATE TABLE conversation_memory (
  id UUID PRIMARY KEY,
  agent_id UUID REFERENCES agents(id),
  user_id UUID,
  session_id UUID,
  messages JSONB,
  summary TEXT,
  created_at TIMESTAMP,
  updated_at TIMESTAMP
);

-- Long-term memory
CREATE TABLE user_memory (
  id UUID PRIMARY KEY,
  agent_id UUID REFERENCES agents(id),
  user_id UUID,
  key VARCHAR(255),
  value JSONB,
  created_at TIMESTAMP,
  expires_at TIMESTAMP
);

Data Retention

Configure retention policies:

json
{
  "retention": {
    "conversation_history_days": 30,
    "summaries_days": 90,
    "long_term_memory_days": 365,
    "auto_delete_on_user_request": true
  }
}

API for Memory Management

Get Conversation History

bash
curl -X GET "https://api.arcanflows.com/api/v1/agents/{agent_id}/conversations/{conversation_id}" \
  -H "X-API-Key: your_api_key"

Clear Conversation

bash
curl -X DELETE "https://api.arcanflows.com/api/v1/agents/{agent_id}/conversations/{conversation_id}" \
  -H "X-API-Key: your_api_key"

Get User Memory

bash
curl -X GET "https://api.arcanflows.com/api/v1/agents/{agent_id}/memory/users/{user_id}" \
  -H "X-API-Key: your_api_key"

Update User Memory

bash
curl -X PATCH "https://api.arcanflows.com/api/v1/agents/{agent_id}/memory/users/{user_id}" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "preferences": {
      "language": "es",
      "notification_style": "brief"
    }
  }'

Delete User Memory

bash
curl -X DELETE "https://api.arcanflows.com/api/v1/agents/{agent_id}/memory/users/{user_id}" \
  -H "X-API-Key: your_api_key"

Best Practices

1. Right-size Context

Don't include unnecessary history
Summarize when conversations get long
Prioritize recent and relevant messages

2. Manage Costs

Longer context = higher API costs
Use summary memory for long conversations
Set reasonable token limits

3. Privacy Considerations

Allow users to delete their memory
Don't store sensitive information unnecessarily
Implement data retention policies
Comply with GDPR/privacy regulations

4. Performance Optimization

Pre-compute summaries asynchronously
Cache frequently accessed memory
Use efficient storage formats

5. Testing

Test with various conversation lengths
Verify context is preserved correctly
Check behavior when limits are reached

Troubleshooting

Agent "forgets" earlier conversation

Increase max_messages or max_tokens
Enable summary memory
Check if session expired

Responses reference wrong context

Verify conversation_id is correct
Check for context window overflow
Review memory configuration

Memory not persisting

Ensure persist_on_timeout is enabled
Check session configuration
Verify database connectivity

High token usage

Enable summary memory
Reduce max_messages
Optimize system prompt length