Explanation

Understand the concepts, design decisions, and architecture behind neo4j-agent-memory.

Explanation is understanding-oriented. It clarifies and illuminates a topic. It’s about helping you understand why things work the way they do.

Core Concepts

Topic What You’ll Understand

The Three Memory Types

Why agent memory is divided into short-term, long-term, and reasoning memory. How they work together.

The POLE+O Data Model

Why we use Person-Object-Location-Event-Organization for entity classification. Origins and benefits.

Why Neo4j?

Why a graph database is ideal for agent memory. How the schema is designed.

Technical Deep Dives

Topic What You’ll Understand

How Entity Extraction Works

The multi-stage extraction pipeline. Trade-offs between speed and accuracy.

Entity Resolution Concepts

How entities are matched and merged. Fuzzy matching, embeddings, and confidence thresholds.

Key Design Decisions

Graph-Native Memory

Traditional agent memory systems use flat key-value stores or vector databases. neo4j-agent-memory uses a graph-native approach:

  • Relationships are first-class: Entities connect to messages, other entities, and reasoning traces

  • Traversal queries: Find how entities relate across conversations

  • Temporal patterns: Track how knowledge evolves over time

Three-Layer Architecture

We separate memory into three distinct layers because they have different:

  • Lifetimes: Messages are ephemeral, entities persist, reasoning traces are archival

  • Access patterns: Recent messages vs. semantic search vs. tool usage stats

  • Schemas: Conversations have structure, entities have types, traces have steps

POLE+O Classification

The POLE+O model (Person, Object, Location, Event, Organization) comes from law enforcement and intelligence analysis. We adopted it because:

  • Universal: These five categories cover most real-world entities

  • Hierarchical: Subtypes allow fine-grained classification

  • Relationships: The model defines expected relationships between types

Explanation Philosophy

Explanation documentation:

  • Discusses: The "why" behind design choices

  • Contextualizes: Connects to broader concepts and alternatives

  • Reflective: Can be read and pondered, not just executed

  • Honest: Acknowledges trade-offs and limitations

For hands-on learning, see the Tutorials.

For solving specific problems, see the How-To Guides.

For technical details and API documentation, see the Reference section.

Further Reading