Teaching Agents to Remember

The Million-Token Illusion

GPT-5 supports 272,000 tokens. Gemini 2.5 accepts up to a million. Claude handles 200,000. With windows this large, why isn't the memory problem solved?

Think of it like a warehouse. A million tokens sounds enormous — that's roughly 750,000 words, over 2,500 pages. Surely you can fit everything in there. But here's the math that kills the illusion:

At that point, you have two options. Drop old information and your agent forgets — preferences, history, relationships, all gone. Or compress everything into summaries and lose the critical details that made the information useful in the first place. Neither option is acceptable for production systems.

But the problem is deeper than just running out of space. Even within the window limits, performance degrades. Research on Recursive Language Models demonstrates what's called "context rot" — performance drops as context length increases, regardless of whether you hit the hard limit. Arbitrarily filling the window with more tokens doesn't help. It hurts.

The lost in the middle problem makes this worse. LLMs attend strongly to the beginning and end of their context, but miss information buried in the middle. The very mechanism you rely on to improve memory — larger context windows — ends up hiding the information you care about most.

Eight Failure Modes

If you've been treating memory as "just store text and search it later," the failures might seem random. They're not. The Letta Leaderboard for benchmarking agentic memory identifies eight distinct failure modes that tend to show up together. Understanding them transforms debugging from whack-a-mole into systematic architecture.

The common root cause: treating memory as passive storage instead of an actively managed resource.

Five Design Tensions

Underneath the failure modes is a multi-dimensional design problem. Building a memory system isn't just a matter of choosing the right database — it's navigating five fundamental tensions that pull in opposite directions simultaneously.

Think of it like designing a city. You can't optimize for everything at once — fast traffic, green space, affordable housing, walkability. Each design choice involves tradeoffs. Memory architecture is the same. Understanding these tensions is the first step to making deliberate, defensible choices.

No single design choice optimizes for all five. Fast access sacrifices completeness. Rigid structure sacrifices flexibility. The "right" balance varies by use case — which means your architecture must make tradeoffs explicit rather than hiding them.

Git for Knowledge

The solution to these failures requires a fundamental shift in how you think about memory. Instead of treating it as a log that grows forever, treat your memory system like a git repository.

In git, you version every commit. You can see what changed, when, and why. Multiple developers can branch, work independently, and merge their changes. If something breaks, you can revert. If you need to audit, you can inspect any point in history.

Your memory system needs the same capabilities:

• Version every knowledge change — when a fact is updated, the old version isn't deleted. It's marked as superseded, with a timestamp and reason.
• Let agents branch and merge — when multiple agents process information concurrently, they write to isolated branches. Merge conflicts surface explicit contradictions rather than allowing silent overwrites.
• Run CI checks before accepting changes — validate that new facts don't violate constraints, that sources still exist, that extractions are reproducible. Schema drift becomes visible and reversible.
• Every ontological change is a commit — one you can inspect, blame, or revert. The failures described by the Letta Leaderboard are symptoms of building without version control.

The foundation your memory architecture is missing is git for knowledge. And the technology that makes this possible is the knowledge graph.

Why Graphs?

Imagine you're researching a prolific engineer at your company. You have 200 documents — project reports, meeting notes, Slack threads, design docs. You ask: "What has Dr. Amara Osei done?" With standard RAG, the system chunks those documents, embeds them into vectors, and retrieves the chunks most similar to your question.

But no single chunk comprehensively covers Osei's contributions. One mentions her work on the caching layer. Another covers her promotion to principal engineer. A third discusses her move to the AI safety team. Standard RAG might retrieve two or three of these chunks, but it can't connect the dots across documents to build a complete picture.

This is where baseline RAG breaks down:

• Connecting scattered information — when the answer requires linking facts across multiple documents
• Summarizing themes — when queries ask about higher-level patterns across a dataset
• Reasoning over narrative data — when the dataset is messy, narrative, or organized as stories rather than discrete facts

Knowledge graphs solve this by making relationships first-class citizens. Instead of treating each document as an isolated bag of text, you extract the entities (people, concepts, events, organizations) and the relationships between them (authored, promoted_to, works_on, preceded_by). Now "What has Dr. Osei done?" becomes a graph traversal: start at the Osei node, follow all outgoing edges, and synthesize what you find.

The Architecture Evolution

Most teams don't start with knowledge graphs. They evolve toward them as their requirements outgrow simpler approaches. Understanding this progression helps you decide where you are and where you need to go.

Production memory systems like Cognee, mem0, Zep, and Letta combine these ingredients in different ways, but they all converge on the same idea: memory is not a log — it's a graph that evolves over time.

GraphRAG: The Three Components

Graph retrieval-augmented generation (GraphRAG) is the advanced extension of RAG that incorporates graph structures into the retrieval process. Where standard RAG retrieves flat text chunks, GraphRAG retrieves subgraphs — clusters of related entities and relationships that provide richer context for generation.

GraphRAG consists of three components working together:

GraphRAG supports two distinct query modes. Local queries focus on specific entities and their immediate neighbors — "Who manages the marketing team?" traverses from the marketing team node to find the manages relationship. Global queries reason over broader themes across the dataset — "What are the key concerns in this quarter's reports?" requires community detection and summarization across the entire graph.

Building Knowledge Graphs

A knowledge graph isn't magic — it's a structured pipeline that transforms raw text into queryable entities and relationships. Think of it like building a city map from satellite photos: you identify the landmarks (entities), draw the roads between them (relationships), and organize everything into neighborhoods (ontology).

The construction process follows eight steps:

The key insight: steps 3 and 4 — entity recognition and relationship extraction — are where modern LLMs shine. Foundation models can extract semantic triples (subject-predicate-object expressions, like "Alice, works at, Acme Corp") at scale. This means knowledge graphs that once required armies of human annotators can now be constructed automatically.

# pip install langchain-experimental langchain-openai
from langchain_experimental.graph_transformers import LLMGraphTransformer
from langchain_core.documents import Document
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4o", temperature=0)

transformer = LLMGraphTransformer(
    llm=llm,
    allowed_nodes=["Person", "Company", "Technology"],
    allowed_relationships=["WORKS_AT", "USES", "FOUNDED"],
)

doc = Document(page_content="Sarah Chen founded DataFlow. DataFlow uses graph databases.")
graph_docs = transformer.convert_to_graph_documents([doc])

for node in graph_docs[0].nodes:
    print(f"Entity: {node.id} ({node.type})")
for rel in graph_docs[0].relationships:
    print(f"  {rel.source.id} --[{rel.type}]--> {rel.target.id}")
# Entity: Sarah Chen (Person)
# Entity: DataFlow (Company)
# Entity: graph databases (Technology)
#   Sarah Chen --[FOUNDED]--> DataFlow
#   DataFlow --[USES]--> graph databases

# Install and set up
pip install graphrag
mkdir -p ./ragtest/input

# Add your documents
curl https://www.gutenberg.org/ebooks/103.txt.utf-8 \
  -o ./ragtest/input/book.txt

# Initialize and build the graph
graphrag init --root ./ragtest
graphrag index --root ./ragtest

# Global query (themes across the whole dataset)
graphrag query \
  --root ./ragtest \
  --method global \
  --query "What are the key themes in this novel?"

# Local query (specific entity details)
graphrag query \
  --root ./ragtest \
  --method local \
  --query "Who is Phileas Fogg and what motivates his journey?"

Neo4j in Practice

Once you outgrow experimental setups, Neo4j is the most trusted enterprise-grade graph database for production knowledge graphs. Its native graph storage and index-free adjacency architecture ensures near-constant traversal performance — even as the graph scales to billions of nodes and relationships.

Here's how knowledge graphs work in practice. Entities become labeled nodes with properties. Relationships become directed edges with types. And the graph becomes queryable through Cypher, Neo4j's query language.

// Create concept nodes
CREATE (:Concept {name: 'Artificial Intelligence'});
CREATE (:Concept {name: 'Machine Learning'});
CREATE (:Concept {name: 'Deep Learning'});
CREATE (:Tool {name: 'TensorFlow', creator: 'Google'});
CREATE (:Model {name: 'BERT', year: 2018});

// Create relationships between concepts
MATCH
  (ml:Concept {name:'Machine Learning'}),
  (ai:Concept {name:'Artificial Intelligence'})
CREATE (ml)-[:SUBSET_OF]->(ai);

MATCH
  (dl:Concept {name:'Deep Learning'}),
  (ml:Concept {name:'Machine Learning'})
CREATE (dl)-[:SUBSET_OF]->(ml);

// Multi-hop traversal
MATCH path = shortestPath(
  (c1:Concept {name: 'Natural Language Processing'})
  -[*]-
  (c2:Concept {name: 'Deep Learning'})
)
RETURN path;

# pip install "neo4j-graphrag[openai]"
import asyncio
from neo4j import GraphDatabase
from neo4j_graphrag.llm import OpenAILLM
from neo4j_graphrag.embeddings import OpenAIEmbeddings
from neo4j_graphrag.experimental.pipeline.kg_builder import SimpleKGPipeline

driver = GraphDatabase.driver("neo4j://localhost:7687", auth=("neo4j", "password"))
llm = OpenAILLM(model_name="gpt-4o", model_params={"temperature": 0})

kg_builder = SimpleKGPipeline(
    llm=llm,
    driver=driver,
    embedder=OpenAIEmbeddings(model="text-embedding-3-large"),
    schema={
        "node_types": ["Person", "Company", "Technology"],
        "relationship_types": ["WORKS_AT", "USES", "FOUNDED"],
        "patterns": [("Person", "WORKS_AT", "Company"),
                     ("Company", "USES", "Technology")],
    },
    perform_entity_resolution=True,  # merges duplicate entities
)

# From text
asyncio.run(kg_builder.run_async(text="Alice is a CTO at Acme Corp. They use Neo4j."))

# From PDF
asyncio.run(kg_builder.run_async(file_path="company_docs.pdf"))

# pip install langchain-experimental langchain-neo4j
from langchain_experimental.graph_transformers import LLMGraphTransformer
from langchain_neo4j import Neo4jGraph

transformer = LLMGraphTransformer(llm=llm,
    allowed_nodes=["Person", "Company"],
    allowed_relationships=["WORKS_AT", "FOUNDED"])
graph_docs = transformer.convert_to_graph_documents(documents)

graph = Neo4jGraph(url="neo4j://localhost:7687", username="neo4j", password="password")
graph.add_graph_documents(graph_docs)

Once loaded, your knowledge graph supports multi-hop traversals that far exceed what a flat table or vector store can express. When answering complex queries, the agent traverses the graph, expanding the range of questions these systems can answer. It is now possible to search for elements on the graph, then retrieve all elements one or more links away from that node.

# pip install "neo4j-graphrag[openai]"
from neo4j import GraphDatabase
from neo4j_graphrag.retrievers import Text2CypherRetriever
from neo4j_graphrag.llm import OpenAILLM
from neo4j_graphrag.generation import GraphRAG

driver = GraphDatabase.driver("neo4j://localhost:7687", auth=("neo4j", "password"))
llm = OpenAILLM(model_name="gpt-4o")

# Few-shot examples dramatically improve accuracy
examples = [
    "USER: 'Who founded DataFlow?' CYPHER: MATCH (p:Person)-[:FOUNDED]->(c:Company {name: 'DataFlow'}) RETURN p.name",
    "USER: 'What did Alice work on?' CYPHER: MATCH (p:Person {name: 'Alice'})-[:WORKED_ON]->(proj) RETURN proj.name",
]

retriever = Text2CypherRetriever(
    driver=driver, llm=llm,
    # neo4j_schema auto-introspects if omitted; pass a string to override:
    # neo4j_schema="Node: Person(name, role), Company(name); Rel: WORKS_AT, FOUNDED"
    examples=examples,
)

# Full GraphRAG: retrieve from graph → generate answer with LLM
rag = GraphRAG(retriever=retriever, llm=llm)
response = rag.search("What technical decisions in Q1 affected performance?")
print(response.answer)

Graph Building Blocks

A graph-based memory system is built from three core pieces: nodes, edges, and subgraphs. Nodes hold the things you care about. Edges describe how those things relate. Subgraphs bundle related pieces of memory into coherent contexts.

The critical design pattern is find-or-create. Every time "John from marketing" appears, the system either reuses the existing John node or creates a new one in a controlled way. This is what makes consolidation and entity-centric reasoning possible — without it, you scatter facts across disconnected nodes and lose the ability to reason about any single entity.

class MemoryNode:
    def __init__(self, content, node_type):
        self.id = generate_uuid()
        self.content = content
        self.type = node_type
        self.created_at = datetime.now()
        self.embedding = generate_embedding(content)
        self.metadata = {}
        self.edges = []

    def add_edge(self, target_node, relationship_type,
                 metadata=None):
        edge = Edge(
            source=self.id,
            target=target_node.id,
            type=relationship_type,
            created_at=datetime.now(),
            metadata=metadata or {},
        )
        self.edges.append(edge)
        return edge

Temporal Awareness: Making Memory Evolve

So far, our graph is timeless. It tells you that Sarah manages marketing, but not whether she still does. In real systems, this quickly becomes a problem. Your agent needs to answer both "Who manages marketing now?" and "Who managed marketing in January?" — and it needs to understand when it learned each fact.

Temporal awareness solves this by tracking three different notions of time:

This bi-temporal model, popularized by Zep's Graphiti framework, is what makes temporal reasoning possible. When you first learn "Sarah manages the marketing team," you set valid_from to now and leave valid_until as None. When Sarah changes roles, you call invalidate(), which closes the window without deleting history. The invalidation_reason field creates an audit trail — "role change," "project completion," "correction of bad data."

Now questions like "What did our infrastructure look like right before the outage?" or "Who did the agent think owned this service when it made that prediction?" become first-class queries rather than forensic guesswork.

class TemporalEdge:
    def __init__(self, source, target, relationship):
        self.source = source
        self.target = target
        self.relationship = relationship
        self.valid_from = datetime.now()
        self.valid_until = None  # None = currently valid
        self.ingested_at = datetime.now()
        self.invalidation_reason = None

    def invalidate(self, reason=None):
        """Mark this relationship as no longer valid."""
        self.valid_until = datetime.now()
        self.invalidation_reason = reason

    def was_valid_at(self, timestamp):
        """Check if relationship was valid at a time."""
        return (
            self.valid_from <= timestamp
            and (self.valid_until is None
                 or timestamp < self.valid_until)
        )

Hypergraph Memory

So far, every relationship links exactly two nodes. Real life is rarely that simple. A single incident can involve many services, multiple people, and a series of decisions. Modeling this as pairwise edges quickly becomes unwieldy: for a meeting with ten participants, you'd need forty-five edges just to represent "attended together."

A hypergraph solves this by allowing edges that connect more than two nodes. Instead of forty-five pairwise edges, a single hyperedge connects all ten participants. Its metadata holds the shared context: agenda, decisions made, action items, timestamps. Starting from any participant, you can traverse to the hyperedge and then to all other participants and topics.

class HypergraphMemory(GraphMemory):
    def create_multi_entity_relationship(
        self, entities, relationship_type, metadata
    ):
        # One hyperedge connecting all participants
        hyperedge = HyperEdge(
            id=generate_uuid(),
            type=relationship_type,
            participants=[e.id for e in entities],
            metadata=metadata,
            created_at=datetime.now(),
        )

        # Link all participants
        for entity in entities:
            entity.add_hyperedge(hyperedge)

        # Enable efficient queries
        self.index_hyperedge(hyperedge)
        return hyperedge

Four Essential Memory Operations

You know what to store and how to represent it. The next question is how your agent actually uses memory over time. Robust memory systems come down to four essential operations: consolidating noisy experiences into stable knowledge, indexing for fast access, updating as reality changes, and retrieving the right slice at the right moment.

Consolidation: Your Agent's Sleep Phase

Your agent accumulates many interactions, but most are redundant, overlapping, or partially inconsistent. Consolidation transforms these raw experiences into structured, durable knowledge. Instead of storing "on Monday you said the deadline is Friday, on Tuesday you confirmed Friday, on Wednesday you mentioned Friday again," consolidation produces a single fact: "Project deadline: Friday (confirmed multiple times)."

This isn't just a metaphor about sleep. Research from Letta and UC Berkeley on sleep-time compute demonstrates that shifting heavy computation to idle periods — rather than performing it while users wait — can reduce active inference costs by 5x while maintaining accuracy. When multiple queries share the same underlying context, the cost savings compound. Accuracy improvements of 13–18% are achievable at the same computational budget when systems pre-process context during idle periods.

Retrieval: Where Memory Meets Behavior

Retrieval isn't just a database query — it's intelligent context assembly under uncertainty. No single retrieval strategy catches everything. Production systems combine semantic search, keyword search, graph traversal, and temporal filters in parallel.

HINDSIGHT formalizes this as Reciprocal Rank Fusion (RRF): run all retrieval channels in parallel, then combine results based on rank position, not raw scores. This is robust because scores don't need calibration across different systems, absent items contribute nothing, and facts appearing high in multiple lists naturally surface. After RRF, a neural cross-encoder reranks the top candidates, then token budget filtering ensures results fit the downstream model's context window.

class GraphMemory:
    def __init__(self, embedding_model):
        self.nodes = {}
        self.edges = []
        self.embedding_model = embedding_model

    def add_memory(self, content, context=None):
        # Extract entities and relationships
        entities = self.extract_entities(content)

        # Create or update nodes (find-or-create)
        for entity in entities:
            node = self.find_or_create_node(entity)

        # Identify relationships
        relationships = self.extract_relationships(
            content, entities
        )

        # Create edges with temporal awareness
        for rel in relationships:
            self.create_temporal_edge(
                rel["source"], rel["target"],
                rel["type"], context,
            )

    def query(self, question, timestamp=None):
        # Generate query embedding
        query_emb = self.embedding_model.embed(question)

        # Find relevant nodes through multiple methods
        semantic = self.semantic_search(query_emb)
        keyword = self.keyword_search(question)

        # Traverse graph for connected information
        expanded = self.expand_search_context(
            semantic + keyword, timestamp,
        )

        return self.format_memories_for_llm(expanded)

Three Production Patterns

Most teams won't build graph memory from scratch. You'll adopt an existing platform, integrate open-source components, or borrow patterns from systems already running in production. Three representative approaches show up again and again, each solving a different pain point.

Pattern 1: Hierarchical Memory (Letta/MemGPT)

Letta popularized hierarchical memory that mirrors human cognition: a small, fast working set backed by a much larger searchable archive. Think of it as the difference between your desk (core memory — the few things you need right now) and your filing cabinet (archival memory — everything else, searchable but slower to access).

The architecture has three tiers:

• Core memory (limit: ~2,000 tokens) — highest-value, frequently accessed facts. Instantly available on every turn.
• Archival memory (unlimited) — everything else, searchable via semantic or keyword queries. Slower but comprehensive.
• Recall memory — raw interaction history for questions like "What did we talk about yesterday?"

The critical design choice: when core memory is full, evict_least_used() must choose what to downgrade. A good implementation tracks usage patterns (access frequency, recency, combined score) rather than naive FIFO eviction. Facts you rely on often stay hot; everything else drifts to the archive.

Crucially, eviction is not deletion. The archival layer keeps everything searchable. If a user asks about a detail from six months ago, the system can still find it — just with a slightly slower path. You get fast responses for what matters most, without giving up full-history recall when you need it.

class HierarchicalMemory:
    def __init__(self, core_limit=2000):
        self.core_memory = CoreMemory(limit=core_limit)
        self.archival_memory = ArchivalMemory()
        self.recall_memory = RecallMemory()

    def process_interaction(self, user_input,
                            agent_response):
        # Store raw history in recall memory
        self.recall_memory.add(user_input, agent_response)

        # Extract important facts for core memory
        facts = self.extract_key_facts(
            user_input, agent_response
        )

        for fact in facts:
            if self.core_memory.is_full():
                # Move least-used items to archival
                archived = self.core_memory.evict_least_used()
                self.archival_memory.store(archived)

            self.core_memory.add(fact)

Pattern 2: Evolving Knowledge Networks (A-MEM)

Where hierarchical memory focuses on where to store information, A-MEM focuses on how new information changes what you already know. When your agent learns "Sarah now leads the product team," that should ripple through existing beliefs about Sarah, the product team, and the org chart.

The process: when a new memory arrives, find_related_memories() uses semantic similarity to locate potentially impacted nodes. determine_relationship() classifies how the new node relates to each existing one — is this an update, a refinement, a contradiction, or a new branch? Then evolve_connected_memories() revises the context of affected nodes: older memories about Sarah's previous role get marked as historical, and nodes about the product team get updated to reference new leadership.

The result: a graph that doesn't just accumulate facts but maintains an evolving worldview. Each new memory can adjust confidence scores, invalidate outdated beliefs, or mark previous assertions as superseded. For agents operating in dynamic environments, this pattern prevents your knowledge graph from slowly drifting out of sync with reality.

class EvolvingMemory:
    def add_memory(self, content):
        # Create new memory node
        new_node = self.create_node(content)

        # Find related existing memories
        related = self.find_related_memories(new_node)

        # Form connections and trigger evolution
        for related_node in related:
            relationship = self.determine_relationship(
                new_node, related_node
            )
            # update | refinement | contradiction | branch
            self.create_edge(
                new_node, related_node, relationship
            )

        # Evolve the network
        self.evolve_connected_memories(new_node, related)

Pattern 3: Real-Time Incremental (Graphiti/Zep)

As your memory graph grows, performance becomes the next challenge. Graphiti by Zep illustrates a pattern for keeping query and update times low: do everything incrementally. Instead of recomputing embeddings, entities, or neighborhoods for the entire graph, you touch only what the latest change requires.

extract_entities() processes only the new content. entity_resolution() prevents graph bloat by matching new mentions to existing nodes — if the user refers to "the marketing director" and you already have "Sarah (Director of Marketing)," this step ensures they resolve to the same entity. incremental_update() modifies only the impacted neighborhood.

Graphiti extends this to retrieval as well: instead of running one massive query over the entire graph, it uses parallel search strategies targeting different structures (vector similarity over recent episodes, graph walks over entities, keyword search over text) and merges the results. This divide-and-conquer approach lets the system maintain sub-second response times even at millions of nodes.

# pip install graphiti-core
# Requires: running Neo4j instance + OPENAI_API_KEY
from graphiti_core import Graphiti
from graphiti_core.nodes import EpisodeType
from datetime import datetime, timezone

graphiti = Graphiti("bolt://localhost:7687", "neo4j", "password")
await graphiti.build_indices_and_constraints()  # first run only

# Add an episode — Graphiti extracts entities + relationships automatically
await graphiti.add_episode(
    name="team_standup",
    episode_body="Alice completed the auth service. Bob is blocked on the DB migration.",
    source=EpisodeType.text,
    source_description="standup notes",
    reference_time=datetime(2025, 3, 1, tzinfo=timezone.utc),  # WHEN it happened
)

# Later: add contradicting information — Graphiti handles it
await graphiti.add_episode(
    name="org_update",
    episode_body="Alice is leaving Acme Corp next month. Carol will take over.",
    source=EpisodeType.text,
    source_description="team email",
    reference_time=datetime(2025, 6, 1, tzinfo=timezone.utc),
)

# Search — results include temporal validity
results = await graphiti.search("Who works on the auth service?")
for r in results:
    print(f"Fact: {r.fact}")
    print(f"Valid: {r.valid_at} → {r.invalid_at or 'present'}")

Scaling the Graph: Three Performance Optimization Strategies

As your knowledge graph grows beyond thousands of nodes, three optimization strategies keep queries fast and storage manageable:

These optimizations happen asynchronously — they don't affect real-time queries. Run path pruning as a weekly batch job. Trigger node compression when cluster sizes exceed a threshold. Move nodes to cold storage based on last-access timestamps. The key insight: premature optimization is still premature. Start simple, measure access patterns, then optimize the bottlenecks you actually see.

Production Systems Comparison

Three production platforms implement these patterns with real-world metrics. Focus on the recurring ideas — graph-first modeling, selective storage, temporal reasoning — and how they apply to your own environment.

# pip install cognee
# Set env var: LLM_API_KEY=your-openai-key (note: LLM_API_KEY, not OPENAI_API_KEY)
import cognee
import asyncio

async def main():
    await cognee.add("Your documents, text, or data here.")  # Extract
    await cognee.cognify()                                     # Cognify (build graph)
    results = await cognee.search(query_text="Your question")  # Search
    for r in results:
        print(r)

asyncio.run(main())

# pip install mem0ai
from mem0 import Memory

m = Memory()  # defaults: OpenAI gpt-4.1-nano, Qdrant on-disk

# Add memories from a conversation
m.add([
    {"role": "user", "content": "I'm Alex. I love basketball and hate mornings."},
    {"role": "assistant", "content": "Got it, Alex!"}
], user_id="alex")

# Search — mem0 extracts and returns relevant facts
results = m.search("What does Alex like?", user_id="alex")
# → "Alex loves basketball"

# Requires a running Neo4j instance
import os
from mem0 import Memory

config = {
    "graph_store": {
        "provider": "neo4j",
        "config": {
            "url": os.environ["NEO4J_URL"],       # bolt://localhost:7687
            "username": os.environ["NEO4J_USER"],
            "password": os.environ["NEO4J_PASS"],
        }
    }
}

memory = Memory.from_config(config)

memory.add([
    {"role": "user", "content": "Alice met Bob at GraphConf 2025 in San Francisco."},
], user_id="demo")

# Graph-aware search — traverses relationships
results = memory.search("Who did Alice meet?", user_id="demo")
# → Finds Bob, GraphConf, San Francisco + their connections

Choosing Your Approach

These are not mutually exclusive choices. In practice, you can combine graph-first relationship modeling from Cognee with selective storage from mem0 and temporal tracking from Zep, then tune the blend to match your domain.

Health Monitoring

A production graph is a living system: nodes and edges are constantly being added, updated, and pruned. Without explicit monitoring, you won't notice structural problems until they show up as user-visible failures or runaway costs. Six metrics form your essential monitoring dashboard:

The Guitar Problem

You've built an impressive memory system — graph structures, temporal tracking, hierarchical storage. You plug it into your LLM and expect magic. Instead, it fails spectacularly.

Why? Because you're asking a concert pianist to pick up a guitar mid-performance. LLMs are trained to generate text from whatever context you hand them. They are not trained to decide what to remember, what to forget, or how to maintain a coherent internal state over time.

Out of the box, LLMs have no idea how to:

• Decide what's worth remembering ("coffee preference" vs "drinking coffee right now")
• Choose between creating new memories and updating existing ones
• Balance retrieval benefits against context pollution

The result is predictable: your carefully designed graph turns into a digital hoarder's attic. Everything saved, almost nothing truly useful.

The MEM1 Revelation

This is where MEM1 changes the game. MEM1 is a research framework that treats memory not as a static database feature, but as a behavior that agents learn through reinforcement learning. Instead of hard-coding memory policies, it trains agents end-to-end so they discover when to write, retrieve, and consolidate information in service of their tasks.

The outcomes are striking:

That last point bears repeating. A model 10x smaller, trained to manage its own memory, beats a model 10x larger running on hand-written rules. The bottleneck isn't model size — it's memory architecture.

Three Phases of Training

MEM1 offers a concrete training pattern you can adapt: start from real tasks, enforce constraints, then scale up complexity.

class ConstrainedMemoryTraining:
    def __init__(self, memory_budget=1000):
        self.budget = memory_budget

    def train_step(self, experience):
        # Agent must work within budget
        if self.memory_usage > self.budget:
            # Forces consolidation decisions
            self.agent.consolidate_or_fail()

# Key principle: reward task success, not memory
# Bad: reward for storing everything
reward = memories_stored / total_information

# Good: reward for task completion
reward = tasks_completed_successfully

What Emerges

After training, well-trained agents develop several important behaviors — none of which were explicitly programmed:

The deeper insight: dynamic memory without dynamic schemas. Maybe you don't need explicit schemas for every aspect of memory behavior. The consolidated state effectively becomes a learned schema — tightly tailored to what your tasks require and unconcerned with modeling every possible detail of the world.

DevOps Case Study: Memory in Action

Let's bring everything together with a concrete example. Imagine you're extending a DevOps agent — one that already has a knowledge graph of services, dependencies, and configurations — with graph-based memory that tracks change, learns what matters, and improves its own retention through reinforcement learning.

Schema Extensions

Memory adds three new dimensions to the existing knowledge graph: episodes that capture raw operational events, temporal edges that track when facts were true, and consolidated knowledge that distills patterns from experience.

# Episode types: raw operational events
EPISODE_TYPES = [
    "Incident", "Deployment", "ConfigChange",
    "Alert", "Conversation"
]

# Temporal relationship types
TEMPORAL_EDGES = [
    "PRECEDED_BY", "CAUSED_BY",
    "CORRELATED_WITH", "SUPERSEDES"
]

# Consolidated knowledge types
KNOWLEDGE_TYPES = [
    "Pattern", "Preference", "Runbook", "RiskFactor"
]

def ingest_episode(self, episode_type, content, metadata):
    """Record a new operational event."""
    episode = self.kg.create_node(
        node_type=episode_type,
        properties={
            "content": content,
            "embedding": self.embedder.embed(content),
            "ingested_at": datetime.now(),
            "valid_from": metadata.get(
                "event_time", datetime.now()
            ),
            **metadata
        }
    )
    # Link to affected infrastructure
    self.link_to_affected_entities(episode, metadata)
    # Connect to preceding episodes
    self.link_to_preceding_episodes(
        episode, window_hours=24
    )
    return episode

Temporal Queries for Root Cause Analysis

The bi-temporal model pays off when the agent needs to answer: "What changed recently that might explain this failure?" The query combines temporal filtering with graph traversal, then scores results by both time proximity (changes closer in time are more suspect) and relationship strength (changes with stronger causal connections matter more).

def find_changes_before_incident(self, incident_id,
                                 lookback_hours=4):
    """Find changes preceding an incident."""
    changes = self.kg.query("""
        MATCH (change)-[:AFFECTS]->(entity)
              <-[:AFFECTS]-(incident)
        WHERE incident.id = $incident_id
          AND change.valid_from >= $lookback_start
          AND change.type IN
              ['Deployment', 'ConfigChange']
        RETURN change, entity
        ORDER BY change.valid_from DESC
    """, params)

    return self.score_by_proximity_and_relationship(
        changes, incident
    )

Pattern Consolidation

Raw episodes are too noisy for direct reasoning. Consolidation extracts durable patterns that generalize across incidents — patterns are derived from clusters of similar episodes, not individual events. Each pattern maintains provenance links back to its source episodes, so you can always explain why the agent believes a particular risk factor matters.

Training with Reinforcement Learning

The final step: frame memory management as an RL problem. The agent takes actions (store, retrieve, consolidate, forget) and receives rewards based on incident resolution performance. The memory budget constraint forces tradeoffs — when working memory is full, the agent must consolidate or forget something before storing new information.

After training on hundreds of incident sequences, several behaviors consistently emerge:

• Selective storage becomes context-dependent. Deployment metadata is high-value immediately after release but can be consolidated once stable. Isolated alerts get lower retention priority.
• Retrieval becomes multi-stage. Instead of a single similarity query, trained agents learn to first retrieve broad context, then narrow based on findings, then expand along causal edges.
• Consolidation timing adapts to workload. During quiet periods, the agent consolidates aggressively. During incident storms, it defers consolidation to preserve raw context.
• Forgetting becomes strategic. Successfully resolved incidents are forgotten faster than unresolved ones. High-severity service information is retained longer.

These behaviors emerge from the reward signal, not from rules you wrote. The agent discovers them because they improve incident resolution performance.

class DevOpsMemoryEnvironment:
    """RL environment for training memory behavior."""

    def __init__(self, knowledge_graph, incident_dataset):
        self.memory = DevOpsMemory(knowledge_graph)
        self.incidents = incident_dataset
        self.memory_budget = 1000  # Max working memory

    def step(self, action):
        """Execute memory action and return reward."""
        self.execute_action(action)

        if self.memory.working_memory_size() > self.budget:
            return {
                "reward": -1.0,
                "done": False,
                "info": "budget_exceeded"
            }

        # Reward based on incident resolution
        reward = self.evaluate_incident_resolution()
        return {"reward": reward, "done": False}

Putting It All Together: The PersonalAssistant Pattern

What does a production-ready graph memory architecture actually look like when you combine all the patterns? Here's a blueprint that synthesizes hierarchical storage, graph-based relationships, temporal tracking, and memory evolution into a single system:

The key design decisions: working memory is deliberately small (10 items forces prioritization), episodic and semantic memories live in separate graph stores (different access patterns, different retention policies), and the evolution engine runs asynchronously — consolidating related memories, promoting frequently-accessed items to warmer tiers, and eventually archiving cold data.

This is the architecture to aim for when "add some memory to the chatbot" eventually grows into a real system. You don't build all six tiers on day one. You start with working memory (conversation history), add episodic graph memory when users need cross-session continuity, add semantic graph memory when the domain requires relationship reasoning, and layer in temporal tracking and evolution as the system matures.

Intelligent Recommendations from Graph Traversal

One of the most powerful capabilities of a graph memory system is generating structured analogies and recommendations by traversing connections. Unlike keyword-based recommendations ("people who bought X also bought Y"), graph traversal can discover non-obvious patterns:

These recommendations emerge naturally from graph traversal — the system doesn't need to be explicitly programmed with recommendation rules. It follows connections: (current_issue)-[:SIMILAR_TO]->(past_issue)-[:SOLVED_BY]->(person)-[:USED]->(technique). The graph structure itself encodes the organizational knowledge that makes these recommendations possible.

Future-Proofing Your Implementation

Three themes will shape how your memory architecture evolves:

Neurosymbolic integration. The next wave blends neural networks (pattern recognition, natural language) with symbolic reasoning (explicit, inspectable logic). Together, they handle queries that neither approach can solve alone. The practical benefit: symbolic reasoners emit traceable steps — which nodes were traversed, which rules fired, how a conclusion followed from prior facts. Users can see not just what the system decided, but why. For graph memory, this means your traversal logic can be inspected and audited — a critical requirement in regulated industries.

Distributed scaling. As knowledge graphs grow beyond a single machine, sharding decisions become architectural. Partition along natural boundaries (tenants, domains, entity types). Smart routing sends each request only to shards with relevant information. Asynchronous processing returns partial results quickly, then streams more complete answers as deeper traversals finish.

Continual learning. A good memory system doesn't just store more data — it learns how to use data more effectively. Track query patterns to discover common paths worth precomputing. Monitor which memories users actually engage with. Adjust indices and cache strategies based on real access patterns, not your initial assumptions.