Skip to content
BSWEN
Blog

Neo4j vs Markdown Files: Which Memory System is Better for AI Agents?

Cowrie
Cowrie
Dev @ Bswen

Should I use a graph database like Neo4j or simple markdown files for my AI agent’s memory system? This question came up when I was building an AI agent that needed to remember context, learn from interactions, and make informed decisions.

For single-user prototypes and simple workflows, markdown files offer simplicity and human-readability. For production systems with multiple users, complex relationships, or scaling requirements, Neo4j graph database provides proper memory management with conflict resolution, relationship querying, and ACID compliance.

Let me show you why this choice matters and how to pick the right one.

The Problem: Why Your AI Agent Needs Real Memory

When I started building AI agents, I thought storing memories in markdown files would be enough. But I quickly ran into problems:

  1. Context Retention: How well does the agent remember previous conversations?
  2. Relationship Understanding: Can the agent connect related pieces of information?
  3. Scalability: Does the system handle growing data volumes?
  4. Concurrency: Can multiple agents access memory simultaneously?
  5. Query Performance: How fast can the agent retrieve relevant memories?

These questions led me to compare two approaches: file-based memory (markdown) and graph database memory (Neo4j).

Markdown Files: Simple but Limited

I started with markdown because it seemed straightforward. Here’s what a typical file-based memory looks like:

file_memory.py
import os
from datetime import datetime
from pathlib import Path
import fcntl  # File locking for Unix


class FileMemory:
    def __init__(self, memory_dir="memories"):
        self.memory_dir = Path(memory_dir)
        self.memory_dir.mkdir(exist_ok=True)


    def store_memory(self, agent_id, memory_type, content):
        """Store a memory to a markdown file."""
        filename = f"{agent_id}_memory.md"
        filepath = self.memory_dir / filename


        with open(filepath, 'a') as f:
            # File locking for concurrent access (Unix only)
            fcntl.flock(f.fileno(), fcntl.LOCK_EX)
            try:
                timestamp = datetime.now().isoformat()
                f.write(f"\n## {timestamp}\n")
                f.write(f"**Type:** {memory_type}\n\n")
                f.write(f"{content}\n")
            finally:
                fcntl.flock(f.fileno(), fcntl.LOCK_UN)


    def search_memories(self, agent_id, keyword):
        """Simple text search in memory file."""
        filename = f"{agent_id}_memory.md"
        filepath = self.memory_dir / filename


        if not filepath.exists():
            return []


        with open(filepath, 'r') as f:
            content = f.read()
            # Very basic search - no relationship understanding
            return [line for line in content.split('\n')
                    if keyword.lower() in line.lower()]

This works for simple cases. But when I tried to scale it, I hit walls:

memory.md
## 2026-03-16T10:00:00
**Type:** user_preference


User Alice prefers Python for backend development.


## 2026-03-16T10:05:00
**Type:** company_info


Company TechCorp uses Neo4j for their knowledge graph.


## 2026-03-16T10:10:00
**Type:** project_update


Project X is delayed due to API integration issues.

The problem? These memories are disconnected. I can’t easily answer: “Which users who know Python work at companies using Neo4j?”

What Markdown Does Well

  • Zero setup cost - just create .md files
  • Human-readable and editable - anyone can read and modify
  • Version control friendly - git works natively
  • Portable across systems - copy files anywhere
  • No database dependencies - works offline

Where Markdown Falls Short

  • No native relationship querying - you can’t traverse connections
  • File locking issues - concurrent access causes conflicts
  • Manual conflict resolution - merge conflicts are painful
  • Limited query capabilities - grep/text search only
  • Doesn’t scale - complex interconnected data becomes unmanageable
  • No transaction support - partial writes can corrupt data

A Reddit discussion I found captured this perfectly: “A folder of markdown files is not a memory system, it’s a wiki.” This distinction matters because AI agents need to understand relationships, not just store text.

Neo4j: Real Memory for Production

When I switched to Neo4j, the difference was immediate. Here’s how graph-based memory works:

agent_memory.py
from neo4j import GraphDatabase


class AgentMemory:
    def __init__(self, uri, user, password):
        self.driver = GraphDatabase.driver(uri, auth=(user, password))


    def store_memory(self, agent_id, memory_type, content, relationships):
        """Store a memory with relationships to other entities."""
        with self.driver.session() as session:
            session.write_transaction(
                self._create_memory_node,
                agent_id, memory_type, content, relationships
            )


    @staticmethod
    def _create_memory_node(tx, agent_id, memory_type, content, relationships):
        query = """
        CREATE (m:Memory {
            agent_id: $agent_id,
            type: $memory_type,
            content: $content,
            created_at: datetime()
        })
        WITH m
        UNWIND $relationships AS rel
        MATCH (e:Entity {id: rel.entity_id})
        CREATE (m)-[:RELATES_TO {type: rel.type}]->(e)
        """
        tx.run(query, agent_id=agent_id, memory_type=memory_type,
               content=content, relationships=relationships)


    def query_related_memories(self, agent_id, entity_id):
        """Find all memories related to a specific entity."""
        with self.driver.session() as session:
            result = session.read_transaction(
                self._find_related_memories, agent_id, entity_id
            )
            return [record["m"] for record in result]


    @staticmethod
    def _find_related_memories(tx, agent_id, entity_id):
        query = """
        MATCH (m:Memory {agent_id: $agent_id})-[:RELATES_TO]->(e:Entity {id: $entity_id})
        RETURN m ORDER BY m.created_at DESC
        """
        return list(tx.run(query, agent_id=agent_id, entity_id=entity_id))


    def close(self):
        self.driver.close()

The key difference is relationships. In Neo4j, I can store that “User Alice” knows “Python” and works at “TechCorp” which uses “Neo4j” - and then query these connections.

Visualizing the Difference

Here’s how the same data looks in each system:

Architecture Comparison
+-------------------+          +-------------------+
|   MARKDOWN FILES  |          |      NEO4J        |
+-------------------+          +-------------------+
|                   |          |                   |
| memory.md         |          |    (Alice)        |
|   - entry 1       |          |       |           |
|   - entry 2       |          |       v           |
|   - entry 3       |          |    (Python)       |
|                   |          |       ^           |
| No relationships  |          |       |           |
| Linear structure  |          |    (TechCorp)     |
|                   |          |       |           |
| Query: grep       |          |       v           |
| "find Python"     |          |    (Neo4j)        |
|                   |          |                   |
| Result: lines     |          | Query: graph      |
| with "Python"     |          | traversal         |
|                   |          |                   |
|                   |          | Result: connected |
|                   |          | entities          |
+-------------------+          +-------------------+

What Neo4j Does Well

  • Native graph querying - Cypher makes relationship traversal easy
  • ACID transactions - data integrity guaranteed
  • Built-in relationship traversal - find connected data instantly
  • Multi-user concurrent access - no file locking issues
  • Scalable to millions - handles growth without redesign
  • Pattern matching - complex queries in single statements

Where Neo4j Requires Investment

  • Database setup and maintenance - infrastructure overhead
  • Learning Cypher - new query language to learn
  • Resource overhead - heavier than files for small datasets
  • Additional dependency - one more thing to manage

The Query Difference: A Real Example

Let me show you the exact query that convinced me to switch. I wanted to find all users who share technologies with a target user.

With markdown, I’d need to:

  1. Parse all memory files
  2. Extract user-technology mappings
  3. Compare in application code
  4. Handle edge cases manually

With Neo4j, it’s one Cypher query:

find_shared_tech.cql
// Find all users who share technologies with a target user
MATCH (target:User {id: 'user-123'})-[:KNOWS]->(tech:Technology)
MATCH (other:User)-[:KNOWS]->(tech)
WHERE other <> target
RETURN other.name, collect(DISTINCT tech.name) as shared_technologies
ORDER BY size(shared_technologies) DESC
LIMIT 10

This returns users sorted by how many technologies they share with the target. With markdown, I’d write 50+ lines of Python to do the same thing.

The Concurrency Problem

One issue I didn’t anticipate: concurrent access. When I had multiple agents trying to write to MEMORY.md simultaneously, conflicts happened.

Concurrency Comparison
MARKDOWN (File Locking):
+----------+     +----------+
| Agent A  |---->|          |
+----------+     |  WAIT   |
                 |  QUEUE  |
+----------+     |         |
| Agent B  |---->|         |
+----------+     +----------+
                      |
                      v
              [Sequential writes]
              [Manual merge needed]


NEO4J (ACID Transactions):
+----------+     +----------+
| Agent A  |---->|          |
+----------+     | CONCURRENT|
                 | TRANSACTIONS|
+----------+     |         |
| Agent B  |---->|         |
+----------+     +----------+
                      |
                      v
              [Parallel commits]
              [Auto conflict resolution]

As one Reddit commenter noted: “Plain md files is a simple solution, but it doesn’t scale at all.”

When to Use Each

After building both systems, here’s my decision matrix:

Choose Markdown Files When:

  • Building a personal prototype
  • Single-user system with no concurrency needs
  • You need human-readable, git-trackable memory
  • Your data is primarily sequential (logs, conversation history)
  • You value simplicity over functionality

Choose Neo4j Graph Database When:

  • Building production multi-user systems
  • Your AI agent needs to understand relationships
  • You require concurrent access without conflicts
  • You need complex queries and pattern matching
  • Scale and performance matter
  • You want proper ACID transactions

The Middle Ground: Export and Hybrid Approaches

One thing I discovered: you don’t have to choose permanently. Neo4j can export its database as human-readable Cypher script files. The OpenLobster project mentions a file backend for local use that doesn’t require Neo4j for development.

Hybrid Architecture
+-------------------+
|   Production      |
|   +---------+     |
|   | Neo4j   |     |
|   +---------+     |
|        |          |
|        v          |
|   +----------+    |
|   | Export   |    |
|   | Cypher   |    |
|   +----------+    |
+-------------------+
        |
        v
+-------------------+
|   Development     |
|   +---------+     |
|   | File    |     |
|   | Backend |     |
|   +---------+     |
+-------------------+

This gives you the best of both: production-grade memory and development simplicity.

Summary

In this post, I compared Neo4j and markdown files for AI agent memory. The key point is that markdown files are wikis, not memory systems. They work for human-readable documentation but fail when AI agents need to store, query, and reason about interconnected information at scale.

For serious AI agents that need to remember relationships, handle concurrent access, and scale to production, Neo4j provides the architecture needed. For personal prototypes and simple workflows, markdown offers quick setup and human readability.

My recommendation: start with your production requirements in mind. If you’re building an AI agent that needs real memory, choose Neo4j from the start. Migrating later is harder than setting it up correctly the first time.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: