Whatever message this page gives is out now! Go check it out!
Chat memory
Last update:
May 18, 2026
Chat memory allows conversational AI systems built with ColdFusion to remember previous interactions within a conversation. Instead of treating every prompt as a standalone request, chat memory stores and retrieves conversation history so that each new request is enriched with relevant prior messages.
This enables the AI to maintain context, recall user preferences, and behave coherently over multiple turns — essential for building assistants, chatbots, or workflow agents.
Chat memory is managed by the Agent layer. It is not part of the LLMModel (
ChatModel()) itself. A stateless ChatModel() has no memory; memory is only available when you use Agent().Memory types
ColdFusion supports two memory window strategies:
| Type | Parameter | Description |
|---|---|---|
messageWindowChatMemory | maxMessages | Retains the last N messages in history. Simple and predictable — oldest messages are dropped when the limit is reached. |
tokenWindowChatMemory | maxTokens | Retains messages up to a maximum token count. Useful when you need to stay within a provider's context window limit. Oldest messages are dropped to stay within the token budget. |
Choose
messageWindowChatMemory for most use cases. Use tokenWindowChatMemory when working with models that have strict context window limits and you need precise control over token usage.Storage options
Chat history can be stored in-memory or persisted to an external cache store.
In-memory (default)
If no
persistenceStore is specified, history is held in the server's JVM memory. It is fast and requires no external setup, but history is lost when the ColdFusion server restarts or the application session ends. Suitable for development and short-lived sessions.
<cfscript>
chatModelConfig = {
provider : "openAI",
modelName : "gpt-5-nano",
apiKey : "#application.apiKey#"
}
chatModel = ChatModel(chatModelConfig);
agent = Agent({
CHATMODEL : chatModel,
CHATMEMORY : {
TYPE : "messageWindowChatMemory",
MAXMESSAGES : 20,
PERUSER : true
}
});
response1 = agent.chat("Why is the sky blue?", "user1");
writeDump(var=response1.message, label="User1");
</cfscript>
Persistent storage (Redis, Memcache, Ehcache)
For production applications where conversation history must survive server restarts or be shared across a cluster, configure a persistent cache store.
Note:
Pre-requisite: The cache store (Redis, Memcache, or Ehcache) must first be configured at the server level in the ColdFusion Administrator under Server Settings > Caching. Once configured there, reference it in
CHATMEMORY by the cache name you assigned it.
agent = Agent({
CHATMODEL : chatModel,
CHATMEMORY : {
TYPE : "messageWindowChatMemory",
MAXMESSAGES : 20,
PERUSER : true,
PERSISTENCESTORE : "myRedisCache" // cache name from CF Admin > Caching. Persistencestore values can be REDIS/MEMCACHED/EHCACHE
}
});
| Store | When to use |
|---|---|
| Redis | Recommended for production and clustered deployments. Fast, durable, supports TTL. |
| Memcache | High-throughput, low-latency use cases. Note: data is volatile and not durable across restarts. |
| Ehcache | Single-server deployments. Configured and managed within ColdFusion. |
Per-user memory
Setting
PERUSER : true isolates each user's conversation history. Each unique userId passed to agent.chat() gets its own memory context. Without this, all calls share the same global memory.
// User 1's conversation
agent.chat("My name is Alice.", "user-alice");
// User 2's conversation — completely separate history
agent.chat("My name is Bob.", "user-bob");
// Alice's follow-up — only recalls Alice's history
response = agent.chat("What is my name?", "user-alice");
// Returns: "Alice"
CHATMEMORY parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| TYPE | String | Yes | Memory window strategy. messageWindowChatMemory or tokenWindowChatMemory. |
| MAXMESSAGES | Number | Conditional | Maximum number of messages to retain. Required when TYPE is messageWindowChatMemory. |
| MAXTOKENS | Number | Conditional | Maximum number of tokens to retain. Required when TYPE is tokenWindowChatMemory. |
| PERUSER | Boolean | No | When true, memory is scoped per userId. When false or omitted, all calls share one global memory. Default: false. |
| PERSISTENCESTORE | String | No | Name of the cache store configured in ColdFusion Administrator (Caching page). If omitted, in-memory storage is used. |
Examples
messageWindowChatMemory - in-memory, per user
<cfscript>
chatModelConfig = {
provider : "openAI",
modelName : "gpt-5-nano",
apiKey : "#application.apiKey#"
}
chatModel = ChatModel(chatModelConfig);
agent = Agent({
CHATMODEL : chatModel,
CHATMEMORY : {
TYPE : "messageWindowChatMemory",
MAXMESSAGES : 20,
PERUSER : true
}
});
agent.chat("My name is Alice and I live in Paris.", "user123");
response = agent.chat("What is my name and where do I live?", "user123");
writeOutput(response.message); // Your name is Alice, and you live in Paris.
</cfscript>
tokenWindowChatMemory - persistent (Redis), per user
<cfscript>
chatModelConfig = {
provider : "openAI",
modelName : "gpt-5-nano",
apiKey : "#application.apiKey#"
}
chatModel = ChatModel(chatModelConfig);
agent = Agent({
CHATMODEL : chatModel,
CHATMEMORY : {
TYPE : "tokenWindowChatMemory",
MAXTOKENS : 4000,
PERUSER : true,
PERSISTENCESTORE : "myRedisCache"
}
});
agent.chat("Summarize the quarterly sales report for Q1.", "user456");
response = agent.chat("Now compare it with Q2.", "user456");
writeOutput(response.message);
</cfscript>
Shared global memory (no per-user isolation)
agent = Agent({
CHATMODEL : chatModel,
CHATMEMORY : {
TYPE : "messageWindowChatMemory",
MAXMESSAGES : 10
// PERUSER omitted — all users share one memory context
}
});
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Share additional feedback to help us improve.
0/255
|
