This document describes the memory management system in AStack, which provides conversation context management for agents. The memory system stores message history, manages conversation state, and enables agents to maintain context across multiple interactions. For information about how agents use memory during execution, see Base Agent. For details on agent configuration and tool integration, see Tool Integration.
The memory system is defined in the @astack-tech/components package and consists of a Memory interface and default implementation that agents use to maintain conversational state.
The Memory interface defines the contract for all memory implementations in AStack. It provides a standardized API for storing and retrieving conversation messages.
Sources: packages/components/src/agents/index.ts60-87
The interface consists of four core methods:
| Method | Purpose | Return Type |
|---|---|---|
addMessage(message: Message) | Adds a new message to memory storage | void |
getMessages() | Retrieves all stored messages | Message[] |
getFormattedMemory(maxTokens?: number) | Returns formatted memory for model consumption | Message[] | string |
clear() | Empties all stored messages | void |
The Message interface represents individual conversation messages stored in memory:
Sources: packages/components/src/agents/index.ts3-38 packages/components/src/agents/index.ts64-87
The DefaultMemory class provides a simple in-memory storage implementation of the Memory interface. It stores messages in an array and returns them without modification.
Sources: packages/components/src/agents/index.ts89-127
The DefaultMemory class maintains a private messages array as its storage mechanism:
| Method | Implementation Strategy |
|---|---|
addMessage() | Appends message to internal array using push() |
getMessages() | Returns shallow copy of array using spread operator |
getFormattedMemory() | Delegates to getMessages(), ignores maxTokens parameter |
clear() | Resets internal array to empty [] |
Key Characteristics:
getFormattedMemory() returns messages without formattingSources: packages/components/src/agents/index.ts92-126
The Agent class integrates memory as a core component of its execution lifecycle. Memory initialization, usage, and management occur at specific points during agent operation.
Sources: packages/components/src/agents/index.ts273-638
Memory initialization occurs in the Agent constructor and during resets:
Constructor (packages/components/src/agents/index.ts318-336):
DefaultMemory instance if not provided in configthis.memory propertyinitializeMemory() to set initial stateinitializeMemory() (packages/components/src/agents/index.ts338-351):
this.memory.clear()System Message Creation:
Sources: packages/components/src/agents/index.ts318-351
Sources: packages/components/src/agents/index.ts397-549 packages/components/src/agents/index.ts556-585
During the run() method execution:
initializeMemory() packages/components/src/agents/index.ts558currentMessages array, not directly in memoryAgentOutput.historyImportant Note: The current implementation maintains conversation state in the local currentMessages array during execution rather than continuously updating the Memory instance. The memory primarily stores the system prompt.
Sources: packages/components/src/agents/index.ts556-585 packages/components/src/agents/index.ts397-549
The Agent class provides methods for managing memory state throughout its lifecycle.
Sources: packages/components/src/agents/index.ts630-637 packages/components/src/agents/index.ts338-351
The reset() method (packages/components/src/agents/index.ts634-637):
initializeMemory() to clear and reinitialize memoryThis is useful when reusing an agent instance across multiple independent conversations.
The Memory interface allows for custom implementations that provide advanced features like token management, message summarization, or persistent storage.
Sources: packages/components/src/agents/index.ts60-87 packages/components/src/agents/index.ts232-268
A custom memory class must implement all four methods of the Memory interface:
| Method | Custom Implementation Considerations |
|---|---|
addMessage() | - Validate message structure - Persist to external storage - Emit events for monitoring |
getMessages() | - Retrieve from storage - Apply access control - Handle pagination |
getFormattedMemory() | - Respect maxTokens limit- Truncate or summarize - Apply template formatting |
clear() | - Clean external storage - Reset internal state - Log clearing action |
Sources: packages/components/src/agents/index.ts232-268
The agent-with-tools example demonstrates how memory integrates with tool execution in practice.
Sources: examples/agent-with-tools/index.ts117-134 packages/components/src/agents/index.ts397-549
In the example at examples/agent-with-tools/index.ts117-134:
memory parameter is provided to Agent constructorDefaultMemory is automatically instantiatedbuildSystemPrompt()run() callThe system prompt stored in memory includes tool information:
你是一个代码助手，能够帮助用户读取和修改文件。 当你需要使用工具时，请提供详细的工具调用参数。 文件路径总是相对于当前目录。 可用工具： 1. readFile - 读取指定路径的文件内容 参数： - filePath: 需要读取的文件路径，相对于当前目录 2. writeFile - 将内容写入指定路径的文件 ... Sources: packages/components/src/agents/index.ts353-390 examples/agent-with-tools/index.ts125-127
This diagram illustrates how messages flow through the memory system during agent execution.
Sources: packages/components/src/agents/index.ts556-585 packages/components/src/agents/index.ts397-549
Memory instance (for system prompt) and local currentMessages array (for conversation)run() callAgentOutput.history, not persisted to memoryrun() invocation starts fresh, making the agent stateless between callsSources: packages/components/src/agents/index.ts556-585 packages/components/src/agents/index.ts397-549
The AStack memory management system provides:
Memory interface enables custom implementationsDefaultMemory provides simple array-based storagereset() method clears state for new conversationsThe current implementation focuses on system prompt management, with conversation history maintained in local execution context rather than persisted memory storage.
Sources: packages/components/src/agents/index.ts60-127 packages/components/src/agents/index.ts273-638
Refresh this wiki