Persistent Memory System
Relevant source files
The following files were used as context for generating this wiki page:
The Persistent Memory System is a built-in feature of the MCP Server Code Execution Mode designed to maintain state and data across different execution sessions. While the Python sandbox environment is stateful during a single container's lifecycle, this memory system ensures that structured information remains available even if the container is restarted or the bridge session ends.
The system works by serializing data into JSON files stored on the host machine, which are then mounted into the containerized sandbox. This provides a mechanism for LLMs to store project context, user preferences, and intermediate computation results that survive beyond individual tool calls.
Sources: mcp_server_code_execution_mode.py:649-650, GUIDE.md:520-523, STATUS.md:38-42
System Architecture
The memory system relies on a host-to-container volume mapping strategy. Data is physically stored on the host in a subdirectory of the bridge's state directory and presented to the sandbox at a fixed path.
Physical Storage and Mapping
Inside the container, the memory system operates within /projects/memory/. This directory is a mount point for a directory on the host machine, typically located at ~/MCPs/user_tools/memory/.
Sources: mcp_server_code_execution_mode.py:650, GUIDE.md:521-523, README.md:377-379
The diagram above illustrates how JSON files on the host are surfaced as persistent objects within the sandbox environment.
Sources: mcp_server_code_execution_mode.py:1126-1129, GUIDE.md:522-523
Core API Functions
The memory system exposes several Python functions to the sandbox's global namespace and the mcp.runtime module.
| Function | Description | Key Arguments |
|---|---|---|
save_memory | Saves JSON-serializable data to a file. | key, value, metadata |
load_memory | Retrieves data by key; returns default if not found. | key, default |
update_memory | Performs an atomic read-modify-write update. | key, updater (callable) |
list_memories | Lists all saved keys with their metadata. | None |
delete_memory | Removes a memory file from storage. | key |
memory_exists | Checks for the existence of a specific key. | key |
get_memory_info | Returns the full JSON object (value + metadata + times). | key |
Sources: mcp_server_code_execution_mode.py:672-788, GUIDE.md:527-567, tests/test_memory.py:27-107
Data Persistence Logic
When a memory is saved, the system sanitizes the key to ensure it is a valid filename, removing special characters and limiting length. Each memory is stored with internal timestamps for creation and modification.
Sources: mcp_server_code_execution_mode.py:674-683, tests/test_memory.py:34-43
This sequence shows the preservation of metadata during the saving process.
Sources: mcp_server_code_execution_mode.py:692-707, tests/test_memory.py:45-59
Data Structure
Every memory entry is stored as a structured JSON object containing more than just the user-provided value.
| Field | Type | Description |
|---|---|---|
key | String | The original unsanitized key. |
value | Any | The JSON-serializable data stored by the user. |
metadata | Object | User-provided dictionary for categorization or tagging. |
created_at | Float | Unix timestamp of the initial creation. |
updated_at | Float | Unix timestamp of the last modification. |
Sources: mcp_server_code_execution_mode.py:695-701, GUIDE.md:546-550, tests/test_memory.py:49-53
Key Implementation Details
Atomic Updates
The update_memory function prevents race conditions or data loss during read-modify-write operations by taking a lambda or function that defines the transformation.
Sources: mcp_server_code_execution_mode.py:771-788, GUIDE.md:553-567
# Example: Atomic increment of a counter
update_memory("session_count", lambda x: (x or 0) + 1)
Sources: mcp_server_code_execution_mode.py:771-788, GUIDE.md:556
Key Sanitization
Keys are passed through a regex [^a-zA-Z0-9_-] which replaces invalid characters with underscores. This prevents path injection and ensures compatibility with the underlying filesystem.
Sources: mcp_server_code_execution_mode.py:675-676, tests/test_memory.py:169-178
Metadata Management
Users can attach metadata (e.g., {"tags": ["context"]}) during the save_memory call. This metadata is returned by list_memories(), allowing for efficient filtering of stored state without loading the actual values of every entry.
Sources: mcp_server_code_execution_mode.py:691, GUIDE.md:531, tests/test_memory.py:159-166
Conclusion
The Persistent Memory System is the primary mechanism for state management in the MCP Code Execution bridge. By mapping internal container paths to persistent host storage and providing a simple Python API, it enables LLMs to maintain continuity across multiple interactions, effectively giving the agent a "long-term memory" within its sandboxed environment.
Sources: STATUS.md:38-42, README.md:353-356