Entity Service

Persistent knowledge graph for AI agents. Store business objects, track relationships, search by meaning with vector embeddings, and maintain state across sessions — with zero-code persistence through TypeScript decorators.

Why It Matters

AI agents need long-term memory that goes beyond conversation. They need to track customers, orders, workflows, and the relationships between them. Building this persistence layer from scratch means designing schemas, managing migrations, wiring up graph traversals, and handling the complexity of versioned, auditable state.

The Entity Service gives you a knowledge graph with zero-code persistence. Decorate your TypeScript classes with @Entity, @Field, and @Relation — and everything is stored, versioned, and queryable automatically. Vector embeddings let agents find entities by meaning, not just by ID or exact match. The visual graph browser in the console lets you explore the full knowledge graph interactively.

Key Capabilities

• Zero-Code Persistence: TypeScript decorators (@Entity, @Field, @Relation) — no schema migrations, no ORM setup, no boilerplate
• Knowledge Graph: Nodes and edges with typed properties — traverse relationships, find connected entities, explore the full graph
• Graph Operations: Create, read, update, and archive nodes and edges through typed APIs with full input validation
• Embedding Search: Vector similarity search to find entities by meaning, not just exact match — powered by embedding vectors
• Version History: Every change is recorded with a full audit trail — roll back, compare, and debug with complete history
• Workflow State: Long-running workflows with automatic checkpointing and state recovery across agent restarts
• Human-in-the-Loop: Waitable entities that pause execution for human approval, then resume automatically when approved
• Cascading Operations: Archive or update related entities automatically when a parent entity changes
• Visual Graph Browser: Explore entities and relationships in the console's interactive graph view with drill-down
• MCP Integration: All graph operations available as MCP tools — create nodes, edges, search, and traverse via the MCP Gateway

Graph Operations

The Entity Service exposes a complete set of graph operations for creating, reading, updating, and traversing the knowledge graph. All operations are available through the SDK, the MCP Gateway, and the console's visual browser.

Entity Definitions

Define your business objects as TypeScript classes with decorators. The Entity Service automatically handles persistence, versioning, and relationship tracking. No schema files, no migration scripts, no ORM configuration.

import { Entity, Field, Relation, Workflow } from '@firefoundry/agent-sdk';

@Entity({ name: 'customer' })
class Customer {
  @Field() name: string;
  @Field() email: string;
  @Field() tier: 'free' | 'pro' | 'enterprise';
  @Field() sentiment: number; // Updated by analysis agent

  @Relation('orders')
  orders: Order[];

  @Relation('company', { direction: 'outbound' })
  company: Company;
}

@Entity({ name: 'order' })
class Order {
  @Field() total: number;
  @Field() status: 'pending' | 'shipped' | 'delivered';
  @Field() items: LineItem[];

  @Relation('customer', { direction: 'inbound' })
  customer: Customer;
}

Working with the Graph

Use the graph API to create entities, build relationships, traverse connections, and search by semantic meaning. Every operation is automatically versioned and auditable.

// Create entities
const customer = await entityGraph.createNode({
  type: 'customer',
  properties: { name: 'Acme Corp', tier: 'enterprise' }
});

// Create relationships
await entityGraph.createEdge({
  source: customer.id,
  target: orderId,
  type: 'owns',
  properties: { since: '2025-01-15' }
});

// Find related entities
const orders = await entityGraph.getConnected({
  nodeId: customer.id,
  edgeType: 'owns',
  direction: 'outbound'
});

// Semantic search — find similar entities by meaning
const similar = await entityGraph.searchByEmbedding({
  query: 'enterprise accounts with high satisfaction',
  type: 'customer',
  limit: 10
});

MCP Tools

All graph operations are available as MCP tools through the MCP Gateway. External agents and integrations can create nodes, build relationships, and search the knowledge graph using the standard MCP protocol — no SDK required.

Use Cases