Building Persistent Memory for AI Agents: A 4-Layer File-Based Architecture

I've been working with AI agents for a while now, and one of the biggest challenges I've faced is giving them persistent memory across sessions. You know the feeling - you spend time teaching an agent about your project, and then the next time you interact with it, it's like starting from scratch. Frustrating, right?

After some experimentation, I developed a 4-layer file-based memory architecture that works with any AI agent, whether it's ChatGPT, Claude, Agent Zero, or even local LLMs. This system gives agents true persistence, allowing them to remember context, learn from past interactions, and build on previous knowledge.

The Four Layers of Memory

This architecture is inspired by how human memory works, but adapted for digital agents. Here's how it breaks down:

1. Immediate Context Layer: This is the agent's short-term memory, storing the current conversation or task context.
2. Session Memory Layer: This holds information from the current session, allowing the agent to remember what happened earlier in the conversation.
3. Long-Term Memory Layer: This is where the agent stores important information it needs to remember across sessions.
4. Reflection Layer: This is where the agent can review and refine its memories, learning from past experiences.

Implementing the Architecture

Let's dive into how to implement this. I'll use a file-based approach for simplicity and portability.

File Structure

Here's how the files are organized:

memory/
├── immediate/
│   └── context.json
├── session/
│   └── session_<timestamp>.json
├── long_term/
│   ├── facts.json
│   ├── skills.json
│   └── preferences.json
└── reflection/
    ├── reflections.json
    └── insights.json

Layer 1: Immediate Context

This is where we store the current context. It's a simple JSON file that gets reset after each interaction.

// memory/immediate/context.json
{
  "user": "Alice",
  "current_task": "fixing the login bug",
  "relevant_files": ["auth.py", "user_model.py"],
  "current_code_snippet": "def login(user): ..."
}

Layer 2: Session Memory

This stores the entire session history. Each session gets its own file.

// memory/session/session_1625097600.json
{
  "start_time": "2021-06-30T12:00:00Z",
  "end_time": null,
  "messages": [
    {"role": "user", "content": "Hey, I need help with the login bug", "timestamp": "2021-06-30T12:01:00Z"},
    {"role": "agent", "content": "Sure, what's the issue?", "timestamp": "2021-06-30T12:01:05Z"},
    // ... more messages
  ]
}

Layer 3: Long-Term Memory

This is where the agent stores important information. It's organized into different files for different types of knowledge.

json
// memory/long_term/facts.json
{
  "project_name": "Auth System",
  "technologies": ["Django", "PostgreSQL", "React"],
  "key_features": ["OAuth login", "2FA", "password reset"]
}

// memory/long_term/skills