Understanding the Entity Graph: Persistent Agent Memory

AI agents need memory. This is not a subtle point or an advanced feature request -- it is a fundamental requirement. Without persistent state, every interaction starts from zero. A chatbot can get away with session-scoped memory because conversations are ephemeral. An agent cannot. Agents act on behalf of users across time. They manage business objects, track workflows, and make decisions based on history. If they forget everything between sessions, they are not agents -- they are expensive autocomplete.

FireFoundry's Entity Graph solves this problem. It is the persistent, relationship-aware data store at the heart of the agent runtime. It gives your agents long-term memory with zero-code persistence, relationship tracking, and deep integration with the rest of the platform. This article explains what the Entity Graph is, how it works, and why it matters for production AI systems.

The State Problem

Consider a customer service agent. It needs to know who the customer is, what their account tier is, what tickets they have open, and what conversations have already happened. Without persistent state, the agent has to ask for this information every single time -- or rely on some external system that it queries at the start of every session and hopes is up to date.

Now consider a document processing agent. It receives a PDF, extracts data, creates structured records, and routes them for human review. That workflow spans minutes or hours. The agent needs to track where each document is in the pipeline, what has been approved, and what is still pending. Lose that state and you lose the workflow.

The traditional answer is "use a database." But that pushes an enormous amount of complexity onto the developer: designing schemas, handling serialization, managing migrations, building relationship queries, implementing access control, and wiring everything into the agent runtime. For every agent project. From scratch.

What is the Entity Graph?

The Entity Graph is a persistent, relationship-aware data store designed specifically for AI agent business objects. It is not a general-purpose database. It is a domain-specific persistence layer that understands what agents need and provides it out of the box.

Here is what that means in practice:

• Zero-code persistence: Define TypeScript classes with the @EntityMixin decorator and a DTO data interface. The Entity Service handles storage, retrieval, serialization, and deserialization automatically. No schema files, no migration scripts, no ORM configuration.
• Relationships as first-class concepts: Entities connect to each other via typed edges. A Customer entity can own Document entities, which can have Review entities. These relationships form a traversable graph.
• Full CRUD with automatic serialization: Create, read, update, and delete entities through the SDK. The Entity Service manages the underlying storage and ensures consistency.
• Version history: Every change to an entity is recorded. You can audit what changed, when, and by whom -- critical for compliance and debugging.
• Integrated with the agent runtime: Bots can query and modify entities directly. The Entity Graph is not an external system your agent talks to over HTTP -- it is part of the runtime.

The Entity Definition Pattern

Defining an entity in FireFoundry is straightforward. You write a TypeScript class, apply decorators, and the platform takes care of the rest.

import { EntityMixin, RunnableEntity } from '@firebrandanalytics/ff-agent-sdk';

interface CustomerDTOData {
  name: string;
  email: string;
  tier: 'free' | 'pro' | 'enterprise';
  createdAt: Date;
}

@EntityMixin({ specificType: 'CustomerEntity', generalType: 'CustomerEntity', allowedConnections: {} })
class CustomerEntity extends RunnableEntity {
  // Properties are defined in the DTO data interface above
}

Code examples are simplified for clarity. See the full SDK tutorials for production-ready patterns.

That is it. No database schema. No migration file. No repository pattern boilerplate. The @EntityMixin decorator registers the class with the Entity Service, and properties defined in the DTO data interface are automatically persisted. When you create an instance of CustomerEntity, it is stored. When you modify it, the changes are persisted. When you query for it, it is deserialized back into a fully typed object.

This pattern scales to complex domain models. You can have dozens of entity types, each with their own properties and behaviors, and the Entity Service manages all of them.

Relationships and Edges

Isolated entities are useful, but the real power of the Entity Graph comes from relationships. Entities connect to each other via typed edges, forming a navigable graph structure.

// Create a relationship between entities
await entityService.addEdge(customer, document, 'owns');
await entityService.addEdge(document, review, 'has-review');

// Traverse the graph
const customerDocs = await entityService.getRelated(customer, 'owns');
const pendingReviews = customerDocs
  .filter(doc => doc.status === 'pending')
  .map(doc => entityService.getRelated(doc, 'has-review'));

This is where the "graph" in Entity Graph matters. When an agent needs context about a customer, it does not just look up a single record. It traverses relationships: find the customer, find their documents, find the reviews on those documents, find related tickets. The agent builds a rich, connected picture of the situation -- automatically.

Edge types are arbitrary strings, so you can model whatever relationships your domain requires: owns, created-by, assigned-to, depends-on, parent-of. The graph structure makes it natural to represent real-world business relationships that would be awkward in a flat relational schema.

Entity Mixins for Behavior

Persistence and relationships are the foundation. Mixins add behavior. FireFoundry provides built-in mixins that extend entities with common patterns:

• ReviewableEntity: Adds a complete human-in-the-loop review workflow. The entity can be submitted for review, approved, rejected, or sent back for revision. The agent pauses and waits for a human decision -- then resumes automatically when the review is complete.
• FeedbackBotMixin: Enables feedback cycles where an entity is iteratively refined based on input. Useful for content generation workflows where drafts go through multiple rounds of improvement.
• StructuredOutputBotMixin: Ensures that LLM outputs conform to a defined schema using Zod validation. If the model returns invalid data, the mixin automatically retries with corrective guidance.

You can also build custom mixins for domain-specific behavior. A legal document processing system might have a ComplianceCheckMixin that runs regulatory validation before an entity can be finalized. A healthcare system might have a ClinicalReviewMixin that enforces a specific approval chain.

@EntityMixin({ specificType: 'InvoiceEntity', generalType: 'InvoiceEntity', allowedConnections: {} })
class InvoiceEntity extends RunnableEntity {
  // DTO data interface defines: amount, vendor, lineItems
  // ReviewableEntity mixin adds:
  // - submit(), approve(), reject()
  // - status tracking
  // - automatic wait-for-human behavior
}

Why Not Just Use a Database?

This is the question we hear most often. If entities are just objects with properties, why not use a database directly?

Here is the thing: you could, but you should not have to. The Entity Graph is backed by a production-grade, ACID-compliant relational database. What the Entity Graph adds is a purpose-built abstraction layer that handles the things agent developers should not have to think about:

• Serialization and typing: The Entity Graph handles the conversion between TypeScript objects and storage automatically. No ORM configuration, no mapping files, no serialization bugs.
• Versioning: Every entity change is versioned. You get a full audit trail without building one. Roll back to a previous state if something goes wrong.
• Access control: Entity access is governed by the platform's RBAC system. You do not need to implement authorization checks in your agent code.
• Runtime integration: Bots can query entities directly within the agent runtime. There is no network hop, no connection pool management, no database driver to configure. Entities are native objects in your agent's execution context.
• Relationship awareness: Agents understand connections between entities, not just isolated rows. Graph traversal is a first-class operation, not a series of JOIN queries you have to write and optimize.
• Observability: Entity changes flow through the platform's telemetry system. You can see what entities were modified during any agent interaction, trace state changes across workflows, and debug with full context.

You get production-grade database reliability without the boilerplate. A raw database gives you storage. The Entity Graph gives you a state management system that is purpose-built for how agents actually work.

For organizations with larger datasets that outgrow a single node, our Enterprise tier includes the option to run on a distributed database backend that scales horizontally across multiple nodes. Same Entity Graph API, same developer experience, but with the ability to handle significantly larger workloads. Your agent code does not change; the scaling happens at the infrastructure layer.

Real-World Patterns

The Entity Graph supports a wide range of production use cases. Here are three patterns we see most often:

Document Processing Pipelines

An agent receives documents (PDFs, images, emails), extracts structured data, and routes the results for human review. Each document is a ReviewableEntity with edges connecting it to the source, the extracted data, and the reviewer. The agent knows the state of every document in the pipeline at all times.

Game and Simulation State

AI-powered games and simulations use interconnected entities for world state: characters, items, locations, quests. Each entity has properties and relationships to other entities. An NPC character entity connects to its inventory (items), its location (a place entity), and its quest progress (quest entities). The agent traverses this graph to make contextual decisions.

Customer Service Systems

A customer service agent manages customer entities connected to conversation histories, open tickets, and account details. When a customer reaches out, the agent traverses the graph to understand the full context: past interactions, unresolved issues, account tier, and related cases. No manual context assembly required.

Getting Started

The Entity Graph is available to all FireFoundry beta partners. To start building with entities:

• Read the Entity Service documentation for detailed API reference and examples.
• Explore the developer hub for SDK guides, tutorials, and sample projects.
• Check out the Context Service to understand how conversation memory complements entity persistence.

The Entity Graph is one piece of the FireFoundry platform, but it is a foundational one. Persistent, relationship-aware state is what separates agents that merely respond from agents that truly understand. If you are building production AI systems, this is where your agent's memory lives.