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

As AI agents become more integrated into our workflows, one persistent challenge remains: memory. Without persistent memory across sessions, AI assistants are reduced to stateless chatbots, unable to build upon past interactions or maintain context. This limitation is particularly frustrating when working with powerful models like ChatGPT, Claude, or even local LLMs.

After struggling with this limitation in my own projects, I developed a 4-layer file-based memory architecture that provides true persistence for any AI agent. This system works seamlessly with major LLM APIs and local models, giving your agents continuous memory across sessions.

The Problem with Stateless AI Agents

Most AI agent implementations treat each interaction as independent, with no memory of previous conversations. While this works for simple Q&A, it's inadequate for more complex use cases like:

• Multi-step workflow automation
• Project tracking across sessions
• Personal assistant functions
• Knowledge base building

Without memory, agents can't:

• Recall previous decisions
• Maintain context between interactions
• Learn from past mistakes
• Build upon previous work

The Solution: A 4-Layer File-Based Architecture

After experimenting with various approaches, I settled on a 4-layer file-based system that balances simplicity with powerful functionality. Here's how it works:

Layer 1: Session Logs

The foundation of our architecture is session logging. Each interaction is stored as a timestamped JSON file in a dedicated directory:

memory/
  sessions/
    2023-11-15_14-30-22.json
    2023-11-15_14-45-17.json
    ...

Each file contains:

• User input
• Agent response
• Metadata (timestamp, session ID, etc.)

{
  "session_id": "sess_abc123",
  "timestamp": "2023-11-15T14:30:22Z",
  "user_input": "Create a project plan for our new API",
  "agent_response": "Here's a draft project plan...",
  "metadata": {
    "tokens_used": 456,
    "model": "gpt-4"
  }
}

Layer 2: Context Graph

The second layer builds relationships between sessions using a graph structure. We maintain an edges.json file that maps how sessions relate to each other:

{
  "sess_abc123": {
    "next": ["sess_def456", "sess_ghi789"],
    "prev": [],
    "related": ["sess_jkl012"]
  },
  "sess_def456": {
    "next": ["sess_mno345"],
    "prev": ["sess_abc123"],
    "related": []
  }
}

This allows the agent to:

• Follow conversation threads
• Understand chronological order
• Find related discussions

Layer 3: Entity Extraction

The third layer focuses on extracting and storing key entities from conversations. We maintain a entities.json file that tracks:

• People
• Projects
• Concepts
• Actions

json
{
  "people": {
    "John Doe": {
      "first_seen": "2023-11-15",
      "last_seen": "2023-11-16",
      "roles": ["Project Manager"],
      "sessions": ["sess_abc12