Entities and Observations in MCP Knowledge Graph: Key Differences and Usage

In the Model Context Protocol (MCP) knowledge graph, entities are structural nodes with unique identifiers and types that form the graph's backbone, while observations are mutable string facts attached to those entities that store specific knowledge without affecting the entity's identity.

The modelcontextprotocol/servers repository provides a reference implementation of this architecture in its memory server, where understanding the distinction between entities and observations in MCP knowledge graph design is essential for building robust AI applications that require structured memory and retrieval.

What Are Entities in the MCP Knowledge Graph?

Entities serve as the foundational nodes within the knowledge graph. Each entity represents a distinct object or concept with a stable identity that persists throughout the graph's lifecycle.

Entity Structure and Interface

According to the source code in src/memory/index.ts (lines 49-54), the Entity interface is defined as:

interface Entity {
  name: string;          // unique identifier
  entityType: string;    // e.g., "person", "company", "event"
  observations: string[]; // atomic facts attached to this entity
}

The name field acts as the primary key, while entityType categorizes the node. The observations array contains the factual data associated with the entity.

Entity Lifecycle

Entities are created via the create_entities tool and persist as structural elements of the graph. Once created, an entity's name and entityType remain immutable, providing stable reference points for relations and queries.

What Are Observations in the MCP Knowledge Graph?

Observations represent discrete pieces of information or atomic facts attached to entities. Unlike entities, observations do not form nodes in the graph structure; they are string payloads stored within the entity's observations array.

Each observation is a plain string that describes a specific attribute, event, or fact about the parent entity. For example, "Speaks fluent Spanish" or "Graduated in 2019" are valid observations that provide knowledge about an entity without altering its fundamental identity.

Key Differences Between Entities and Observations

Understanding the architectural distinction between these components is crucial for effective knowledge graph management.

Structural Role vs. Content Payload

Entities serve as the graph's nodes, providing identity and type classification. Observations function as mutable content payloads attached to those nodes.

Mutability and Lifecycle

Entities are created once and their core identity (name and entityType) remains fixed. Observations, however, can be added, updated, or removed independently via the add_observations and delete_observations tools without affecting the entity's existence.

Storage Implementation

In src/memory/index.ts, entities are stored as objects with the Entity interface, while observations are simple strings within the observations array (line 53).

Relation Capabilities

Entities can participate in directed relations with other entities (e.g., works_at, located_in). Observations cannot link to other nodes; they are strictly properties of their parent entity.

Working with Entities and Observations in Code

The KnowledgeGraphManager class in src/memory/index.ts provides methods for manipulating these structures.

Creating Entities

Use the create_entities tool to establish new nodes:

// Example entity creation
const newEntity = {
  name: "John_Smith",
  entityType: "person",
  observations: ["Speaks fluent Spanish"]
};

Adding Observations

The addObservations method (lines 139-148 in src/memory/index.ts) allows appending facts to existing entities:

await knowledgeGraphManager.addObservations([
  {
    entityName: "John_Smith",
    contents: ["Graduated in 2019", "Prefers morning meetings"]
  }
]);

After execution, the entity retains its original identity while the observations array contains the new facts.

Reading the Knowledge Graph

Retrieve the complete graph to inspect both entities and their observations:

const graph = await knowledgeGraphManager.readGraph();
const entity = graph.entities.find(e => e.name === "John_Smith");
console.log(entity?.observations); 
// Output: ["Speaks fluent Spanish", "Graduated in 2019", "Prefers morning meetings"]

Summary

• Entities are structural nodes with unique name identifiers and entityType classifications that form the backbone of the MCP knowledge graph.
• Observations are mutable string facts stored within entity observations arrays, providing specific knowledge without affecting entity identity.
• Entities are created via create_entities and maintain stable identities, while observations can be modified independently using add_observations and delete_observations.
• Only entities can participate in directed relations; observations are strictly properties attached to their parent entities.

Frequently Asked Questions

Can an entity exist without observations?

Yes. According to the Entity interface definition in src/memory/index.ts, the observations property is an array that can be empty upon creation. An entity retains its structural identity through its name and entityType fields regardless of whether it contains any observations.

How do I update an existing observation?

The MCP knowledge graph does not support in-place editing of individual observation strings. To update a fact, you must first use the delete_observations tool to remove the outdated string, then use add_observations to insert the corrected version. This two-step process ensures data integrity while allowing knowledge to evolve.

What is the maximum size of an observation?

The source code in src/memory/index.ts stores observations as standard JavaScript strings within the entity's observations array. While there is no explicit length constraint defined in the interface, practical limits depend on the JSON serialization context and memory availability. For optimal performance, observations should remain concise atomic facts rather than large text documents.

How do relations differ from observations?

Relations and observations serve fundamentally different purposes in the graph architecture. Relations are directed connections between two entities (defined by the Relation interface with from, to, and relationType fields) that establish how nodes interact. Observations are string properties contained within a single entity that describe attributes or facts about that specific node. While relations link entities together to form the graph structure, observations provide the knowledge content stored inside each node.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}