DeepAgents + Neo4j: A Three-Layer Graph Unifies Agent Memory and Knowledge

The memory problem for AI agents is becoming a bottleneck in production. Most teams stitch RAG and agent memory together as two independent modules, leaving what an agent did, why it did it, and which document it relied on fragmented from one another. The open-source project Agentic GraphRAG proposes an approach that unifies all three with a graph database: Neo4j serves as the connection layer, while DeepAgents/LangGraph provides the built-in agent runtime. The project's author shared design details on Reddit and posed a question worth discussing—how is your retrieval and long-term memory stack built?

Three-Layer Graph Structure: Knowledge, Work, and Decisions

According to the project author, the entire graph is split into three interconnected parts. The knowledge layer stores documents, passages, and extracted entities and relationships; the working memory layer records tasks and their progress, including messages and tool call results; and the decision memory layer holds conclusions, hypotheses, and open questions.

The three layers are not simply parallel. Every decision can link back to source passages, task events, or earlier decisions. The agent's built-in implementation automatically writes messages and tool activity as task events, so another session can pick up where the previous round left off—solving the old problem of "an agent losing its memory when switching sessions."

Decision revisions are also version-aware: when reviewing a decision, you can either confirm it or replace it, but the old version stays in history rather than being overwritten and deleted.

Ingestion and Extraction: Preserving Document Structure Details

The knowledge layer's preprocessing uses Docling for document parsing and Chonkie for chunking. What's worth noting is how much document structure it preserves: section hierarchy, tables, and paragraph parent-child relationships are all kept, and each passage carries source version and position information, including page location for PDFs.

Entity extraction is schema-driven. Users must define a schema of entities, attributes, and relationships for their domain, and the system uses it to guide extraction, validate results, and determine the entity labels used in retrieval. Local extraction runs through GLiNER, while structured LLM extraction is handled by BAML for selected chunks. This "define schema first, then extract" approach is more controllable than fully automatic open extraction, at the cost of upfront domain modeling work.

Docling is an open-source document parsing tool from IBM, specifically designed to convert formats like PDF, DOCX, PPTX, and HTML into structured Markdown or JSON while preserving layout information such as heading hierarchy, paragraphs, tables, lists, and reading order. Compared to libraries like PyPDF2 and pdfplumber that focus on text extraction, Docling has built-in layout analysis and table structure recognition models, and can output a document tree with parent-child relationships—making it well suited for RAG preprocessing.

Chonkie, on the other hand, is a lightweight text chunking library that supports splitting by token, sentence, semantics, or recursive structure, and offers quick comparison across multiple chunking strategies. It emphasizes chunking efficiency and configurability, and is often used together with Docling: Docling turns documents into structured blocks, and Chonkie then cuts those blocks into embedding-friendly chunks at the target granularity.

GLiNER is a general-purpose named entity recognition model based on bidirectional encoders (such as DeBERTa). It doesn't require pre-training on a fixed label set; instead, it accepts an arbitrary list of entity types at inference time and determines matches by jointly encoding entity types with text spans. This "zero-shot NER" characteristic makes it suitable for extracting entity types from a custom schema locally, without fine-tuning a model for each domain.

BAML (Boundary ML) is a domain-specific language for defining and calling LLM functions. Developers use declarative syntax to describe input/output schemas, prompts, and parsing logic, which compiles into type-safe client code. In structured extraction scenarios, BAML handles sending selected chunks along with the target schema to the LLM and enforcing JSON output that conforms to the schema, reducing parse failures and format drift.

Hybrid Retrieval: Facts Missed by Extraction Can Still Be Found

At the retrieval level, the project doesn't bet solely on the graph. It works over both raw passages and the extracted graph simultaneously, fusing Neo4j's full-text rankings with vector rankings using reciprocal rank fusion. The author's reasoning is straightforward: when extraction misses a fact, passage search still catches it.

On top of this, the agent can traverse entity relationships to jump to supporting passages, or expand reading from a search hit to adjacent sections and table rows with headers. This design targets a common limitation of pure vector retrieval—being able to see only content within chunk boundaries.

Reciprocal Rank Fusion (RRF) is a training-free method for fusing results from multiple retrieval paths. For each candidate document, its score in each ranking is recorded as 1/(k + rank), where k is typically 60, and the sum of reciprocal scores across paths is used as the final ranking score. RRF's advantage is that it doesn't depend on the scale or distribution of scores from each path—it uses only ranking information—making it especially robust in scenarios where scores are not comparable, such as full-text retrieval and vector retrieval. It also takes only a few lines of code to implement.

Citation Validation: Blocks Errors, But Not All of Them

The project performs three layers of runtime checks on citations: whether the cited evidence was actually read during this run, whether it falls within the allowed document scope, and whether it matches the cited version.

The author candidly notes the boundary—these checks cannot determine whether the evidence actually supports the conclusion. Additionally, when a cited document is updated, affected decisions and their explicit dependents are flagged for review, while existing citations still point to the original text as cited. This mechanism is more like citation integrity validation; semantic correctness still requires human or higher-level process oversight.

Open Design and Open Questions

Beyond the built-in agent, the project also provides an MCP server for easy integration with other agent frameworks. The author lists future work including a more modular pipeline, more storage backends, and domain-specific benchmarks.

From a community discussion perspective, the most interesting aspect of this project isn't any single technology, but rather treating "agent behavior" itself as a first-class citizen written into the knowledge graph. If your scenario requires auditing agent decision chains—such as compliance review, research reproducibility, or multi-session long tasks—this three-layer structure is worth learning from. Conversely, if you're just doing simple Q&A, the cost of introducing a three-layer graph and schema modeling may not be worthwhile. The author's question is also worth answering for every team building agents: in your domain, how exactly do retrieval and long-term memory divide the work?

MCP (Model Context Protocol) is an open protocol proposed by Anthropic in late 2024 for enabling LLM applications to connect to external tools, data sources, and services in a unified way. It abstracts integrators as MCP servers and callers (such as Claude Desktop, IDEs, and agent frameworks) as MCP clients, exposing three types of capabilities—resources, tools, and prompts—via JSON-RPC. Agentic GraphRAG providing an MCP server means any MCP-compatible agent runtime can call its graph retrieval and memory capabilities as tools, without being tied to DeepAgents/LangGraph.

One-line Summary

Agentic GraphRAG uses a three-layer Neo4j graph to unify knowledge, work, and decision memory, and openly shares its design details.

Paragraph Summary

Agentic GraphRAG addresses the fragmentation between RAG and memory in agent deployments by proposing a three-layer graph architecture with Neo4j as the connection layer and DeepAgents/LangGraph as the runtime. The knowledge layer stores documents, passages, and extracted entities; the working memory layer records tasks, messages, and tool calls; and the decision memory layer holds conclusions, hypotheses, and open questions, with decisions linking back to source passages and earlier decisions, supporting cross-session continuation and versioned revisions. Ingestion uses Docling for parsing and Chonkie for chunking, preserving section hierarchy and table structures; entity extraction is driven by user-defined schemas, with GLiNER for local extraction and BAML for structured LLM extraction. Retrieval operates on both raw passages and the graph, fusing full-text and vector rankings via RRF, and can expand reading along entity relationships. Citation validation only checks whether evidence was read, in scope, and version-matched—it does not judge semantic support. The project offers an MCP server for integration with other frameworks.