Lab Walkthrough Add Persistent Memory

Time for a lab. In this lesson you’ll add long-term persistence to an agent so preferences survive after the terminal closes. The pattern is simple:

Save user preferences to a JSON file on disk.
Load that JSON at startup.
Inject the loaded preferences into the system prompt so the model has awareness of previously saved state.

Environment & assumptions

Python and a virtual environment are available.
The OpenAI Python SDK is installed.
Your working directory is /root/code.
This walkthrough creates a single file: persistent_agent.py.

A retro, pixel-art UI screen that says "ADD PERSISTENT MEMORY" with the subtitle "Give your agent long-term memory" and a small "HANDS‑ON LAB" badge. It shows neon buttons labeled SAVE, LOAD, and INJECT on a dark grid background.

What you’ll build

A safe-agent pattern with a simple check_calendar tool and a try_call_tool wrapper.
A persistent memory layer backed by agent_memory.json.
save_preference and forget_preference handlers.
System prompt injection of loaded preferences at startup.
A small main loop demonstrating the flow.

This lab focuses on the memory pattern and safe tool execution. In production, replace the local JSON file with a secure database and ensure sensitive information is encrypted.

Step-by-step implementation

File and client setup Create persistent_agent.py and start with imports, client initialization, and constants:

# persistent_agent.py
import os
import json
from openai import OpenAI
from typing import Dict, Any

# Client setup (reads environment variables)
client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url=os.getenv("OPENAI_API_BASE"),
)

MAX_ITERATIONS = 10
MEMORY_FILE = "agent_memory.json"

Safe tool pattern Define a simple calendar “tool” and a try_call_tool helper that catches exceptions and returns a safe string. This keeps the agent robust when tools fail.

def check_calendar(date: str) -> str:
    """
    A baseline 'tool' that simulates checking the calendar.
    In production this would call a real calendar API.
    """
    # Simulated response
    return f"Checked calendar for {date}: 1pm available."

def try_call_tool(func, *args, **kwargs):
    """
    Call a tool handling exceptions and returning a safe string result.
    """
    try:
        return func(*args, **kwargs)
    except Exception as e:
        return f"Tool error: {e}"

Persistent memory layer Add the functions to load/save JSON and the two preference handlers: save_preference and forget_preference. These read/write agent_memory.json and return human-readable status strings for the agent.

def load_memory() -> Dict[str, Any]:
    """
    Loads memory from MEMORY_FILE and returns a dict.
    Returns an empty dict if the file does not exist or is invalid.
    """
    if not os.path.exists(MEMORY_FILE):
        return {}
    try:
        with open(MEMORY_FILE, "r", encoding="utf-8") as f:
            return json.load(f)
    except Exception:
        # In case of parse error or other IO issue, return empty memory
        return {}

def save_memory(memory: Dict[str, Any]) -> None:
    """
    Saves memory dict to MEMORY_FILE as formatted JSON.
    """
    with open(MEMORY_FILE, "w", encoding="utf-8") as f:
        json.dump(memory, f, indent=2, ensure_ascii=False)

def save_preference(key: str, value: Any) -> str:
    """
    Adds or updates a preference in memory and persists it.
    """
    memory = load_memory()
    memory[key] = value
    save_memory(memory)
    return f"Saved: {key} = {value}"

def forget_preference(key: str) -> str:
    """
    Removes a key from memory if present and persists the change.
    """
    memory = load_memory()
    if key in memory:
        del memory[key]
        save_memory(memory)
        return f"{key} removed from memory"
    return f"{key} not found in memory"

Optional: expose tool metadata If your agent framework expects a tool registry, provide metadata for save_preference and forget_preference. This is optional but helpful for structured agent orchestrators.

tools = [
    {
        "type": "function",
        "function": {
            "name": "save_preference",
            "parameters": {
                "required": ["key", "value"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "forget_preference",
            "parameters": {
                "required": ["key"]
            }
        }
    },
    # The calendar check could also be exposed here if your agent framework uses this list.
]

Inject memory into the system prompt Load the memory at startup and append known preferences to the system prompt. This ensures the model is aware of persistent state without requiring the user to repeat preferences.

def build_system_prompt() -> str:
    memory = load_memory()
    base_prompt = "You are a helpful personal assistant."
    if memory:
        # Use json.dumps to produce valid JSON for clarity
        prefs_json = json.dumps(memory, ensure_ascii=False)
        return f"{base_prompt}\nKnown user preferences: {prefs_json}"
    return base_prompt

Main loop: demonstration of flow A minimal main loop shows the overall pattern: build the system prompt (with memory injected), process messages, call tools safely, and save/forget preferences as appropriate. This example simulates agent behavior and is intentionally straightforward to illustrate the pattern.

def main():
    system_prompt = build_system_prompt()
    print("System prompt:")
    print(system_prompt)

    # Simulated user messages for demonstration purposes.
    # In practice you'd call the model and parse tool calls from its response.
    user_messages = [
        "I prefer afternoon meetings and I am vegetarian.",
        "Schedule a lunch meeting for me this week.",
        "Forget that I am vegetarian."
    ]

    # Simulated "agent" behavior: detect simple keywords and call tools
    for i, msg in enumerate(user_messages, start=1):
        print(f"\nUser: {msg}")

        # Example: detect a preference statement and save it
        if "prefer afternoon" in msg or "afternoon meetings" in msg:
            print("Calling save_preference: meeting_time = afternoon")
            print(save_preference("meeting_time", "afternoon"))

        if "vegetarian" in msg and "forget" not in msg:
            print("Calling save_preference: diet = vegetarian")
            print(save_preference("diet", "vegetarian"))

        # Example: schedule: use calendar tool and honor stored preferences
        if "Schedule a lunch" in msg or "lunch meeting" in msg:
            mem = load_memory()
            # The agent sees the memory via the system prompt; simulate using it here.
            meeting_time = mem.get("meeting_time", "no preference found")
            diet = mem.get("diet", "no preference found")
            print(f"Loaded preferences: {json.dumps(mem)}")
            # Simulate calling the calendar tool (safe call)
            cal_res = try_call_tool(check_calendar, "this Thursday")
            print(f"Agent: I'll schedule your lunch meeting for this Thursday {meeting_time} at 1pm.")
            print(f"Calendar result: {cal_res}")

        # Example: forget preference
        if "Forget" in msg or "forget" in msg:
            # find key to forget; this is a simplified example
            if "vegetarian" in msg:
                print(forget_preference("diet"))

        if i >= MAX_ITERATIONS:
            break

if __name__ == "__main__":
    main()

Running the script

Run with: python3 persistent_agent.py
Observe the printed system prompt (memory is injected) and the simulated session.

Example session output:

System prompt:
You are a helpful personal assistant.

User: I prefer afternoon meetings and I am vegetarian.
Calling save_preference: meeting_time = afternoon
Saved: meeting_time = afternoon
Calling save_preference: diet = vegetarian
Saved: diet = vegetarian

User: Schedule a lunch meeting for me this week.
Loaded preferences: {"meeting_time": "afternoon", "diet": "vegetarian"}
Agent: I'll schedule your lunch meeting for this Thursday afternoon at 1pm.
Calendar result: Checked calendar for this Thursday: 1pm available.

User: Forget that I am vegetarian.
diet removed from memory

Persisted memory file After the first run, check agent_memory.json to confirm persistence:

root@controlplane ~/code (venv) $ cat agent_memory.json
{
  "meeting_time": "afternoon",
  "diet": "vegetarian"
}

Run the script again (or change the simulated messages) to see the system prompt print the loaded preferences:

System prompt:
You are a helpful personal assistant.
Known user preferences: {"meeting_time": "afternoon", "diet": "vegetarian"}

Final notes and production guidance

Storing sensitive user data or secrets in plaintext JSON on disk is not secure. For production systems, use an encrypted store or a database with proper access controls and encryption at rest.

The pattern shown here is portable: swap agent_memory.json for a database or key-value store, and replace the simulated check_calendar tool with a real calendar API.
Consider schema validation for preferences and limits on memory size to avoid letting the system prompt become too large.

Quick reference table

Component	Purpose	Example / Notes
`MEMORY_FILE`	Path to JSON memory store	`agent_memory.json`
`load_memory()`	Read and return memory dict	Returns `{}` if missing or invalid
`save_memory()`	Persist memory dict to disk	Uses `json.dump(..., indent=2)`
`save_preference(key, value)`	Save or update a preference	`save_preference("diet", "vegetarian")`
`forget_preference(key)`	Remove a preference	`forget_preference("diet")`
`check_calendar(date)`	Simulated calendar tool	Replace with real API in production
`try_call_tool(func, ...)`	Safe tool invocation wrapper	Returns `Tool error: ...` on exceptions
`build_system_prompt()`	Injects loaded memory into system prompt	Uses `json.dumps(memory)` for readability

Links and references

Save, load, forget — that’s the persistent-memory layer. Adapt this pattern to your infrastructure and production-grade storage for robust, long-term agent memory.

LLM Fundamentals

Tools and Workflows

Building AI Agents

Introduction

Production & OpenClaw

Lab Walkthrough Add Persistent Memory

Watch Video