Memory Agents
Relevant source files
The following files were used as context for generating this wiki page:
Memory Agents are specialized components within the DeepCode ecosystem designed to manage the conversational context and implementation state during long-running code generation tasks. Their primary purpose is to reduce token usage while preserving essential technical information, ensuring that large-scale implementations—such as research paper reproductions—can proceed without hitting context window limits or losing critical architectural details.
The system utilizes a "Concise Memory" philosophy, which shifts from traditional full-history retention to a focused retention model. After the first file is generated, the agent discards conversational clutter and maintains only the system prompt, the initial implementation plan, and current-round tool results. This provides a "clean slate" for each subsequent code file implementation while keeping the LLM grounded in the project's overall objectives.
Sources: workflows/agents/memory_agent_concise.py:1-18, workflows/code_implementation_workflow.py:175-185
Architecture and Core Philosophy
The Memory Agent architecture centers on the ConciseMemoryAgent class. It manages state transitions based on tool usage, specifically triggering "concise mode" once a write_file operation is detected.
Logic Flow and Triggers
The agent operates in two distinct phases:
- Normal Flow: Prior to any file creation, the full conversation history is preserved to allow for initial analysis and planning.
- Concise Mode: Triggered by the
write_filetool. In this mode, the history is optimized to retain only essential "Knowledge Base" entries and the implementation plan.
This diagram illustrates the state transition from a standard dialogue model to a concise, file-centric memory model.
Sources: workflows/agents/memory_agent_concise.py:40-65, workflows/agents/memory_agent_concise_index.py:432-450
Key Components and Functions
ConciseMemoryAgent Class
The class tracks implemented files, unimplemented files from the initial plan, and results from "essential" tools.
| Component | Description |
|---|---|
initial_plan | The master blueprint extracted from initial_plan.txt. |
implemented_files | A list of files successfully written to the workspace. |
current_round_tool_results | A buffer for tool outputs (e.g., execute_python) in the active round. |
code_summary_path | Path to implement_code_summary.md which acts as the persistent Knowledge Base. |
Sources: workflows/agents/memory_agent_concise.py:75-105
Essential Tool Tracking
The agent specifically monitors "essential tools" that provide critical technical context for future implementation steps.
| Tool Name | Purpose in Memory |
|---|---|
read_code_mem | Retrieves technical summaries of already-implemented files. |
write_file | Records completion of a file and triggers memory clearing. |
execute_python / execute_bash | Provides validation results for the code implementation. |
search_reference_code | Identifies patterns used for current implementation inspiration. |
Sources: workflows/agents/memory_agent_concise.py:650-670, workflows/agents/memory_agent_concise_index.py:655-675
Knowledge Base and Summarization
A critical feature of the Memory Agent is its ability to generate LLM-based summaries of implemented code. These summaries are stored in implement_code_summary.md and serve as the "Code Knowledge Base."
Summary Structure
When a file is implemented, the agent calls an LLM to extract:
- Implementation Progress: Core ideas and completion status.
- Dependencies: Exported functions, parameters, return values, and required packages.
- Next Steps: A logical suggestion for the next file to implement (filtered against the unimplemented files list).
The sequence above shows how implementation details are processed into a persistent technical memory.
Sources: workflows/agents/memory_agent_concise.py:270-320, workflows/agents/memory_agent_concise_index.py:270-325
Implementation Workflow Integration
The Memory Agent is integrated into the CodeImplementationWorkflow. During the implementation loop, the workflow manager coordinates between the specialized agents.
The Memory Optimization Cycle
The workflow applies a specific cycle to ensure the LLM remains focused:
- Start Round: Clear previous tool results (
start_new_round). - Execute Tools: Assistant calls tools; Memory Agent records results.
- Check Trigger: If
write_fileoccurred,should_trigger_memory_optimizationreturns True. - Optimize:
apply_memory_optimizationreplaces the message history with a concise prompt containing the Plan, Knowledge Base, and Tool results.
Sources: workflows/code_implementation_workflow.py:190-250, workflows/code_implementation_workflow_index.py:200-260
Message Construction in Concise Mode
In concise mode, the history is rebuilt with the following specific blocks:
- Initial Plan: Task overview and progress tracking.
- Knowledge Base: The summary of the latest implemented code entry from
implement_code_summary.md. - Development Cycle Guidance: Strict instructions on using
read_code_membeforewrite_file.
Sources: workflows/agents/memory_agent_concise.py:730-800, prompts/code_prompts.py:530-580
Implementation Progress Tracking
The agent parses the initial plan to extract all required file paths. This allows it to calculate implementation percentages and ensure that "Next Steps" never suggest a file that has already been completed.
Summary
Memory Agents in the DeepCode project represent a sophisticated approach to context window management for automated software engineering. By specifically targeting file write operations as triggers for memory optimization and maintaining a persistent, LLM-summarized Knowledge Base of implemented code, they enable the system to handle complex, multi-file projects while maintaining technical consistency and reducing token-related overhead.