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

> Understand the core differences between entities and observations in the MCP knowledge graph. Learn how these components structure and store vital information within the Model Context Protocol.

- Repository: [Model Context Protocol/servers](https://github.com/modelcontextprotocol/servers)
- Tags: deep-dive
- Published: 2026-03-01

---

**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`](https://github.com/modelcontextprotocol/servers/blob/main/src/memory/index.ts) (lines 49-54), the `Entity` interface is defined as:

```typescript
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`](https://github.com/modelcontextprotocol/servers/blob/main/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`](https://github.com/modelcontextprotocol/servers/blob/main/src/memory/index.ts) provides methods for manipulating these structures.

### Creating Entities

Use the `create_entities` tool to establish new nodes:

```typescript
// 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`](https://github.com/modelcontextprotocol/servers/blob/main/src/memory/index.ts)) allows appending facts to existing entities:

```typescript
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:

```typescript
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`](https://github.com/modelcontextprotocol/servers/blob/main/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`](https://github.com/modelcontextprotocol/servers/blob/main/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.