### Local Development Setup for Graphiti MCP Server

Source: https://github.com/gifflet/graphiti-mcp-server/blob/main/README.md

Details the steps for setting up the local development environment for the Graphiti MCP Server. Includes installing dependencies using `uv` or `pip`, and running a local Neo4j instance using Docker.

```bash
# Using uv (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

# Or using pip
pip install -r requirements.txt
```

```bash
docker run -d \
  --name neo4j-dev \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/demodemo \
  neo4j:5.26.0
```

--------------------------------

### Verify Graphiti MCP Server Installation with Docker Compose

Source: https://github.com/gifflet/graphiti-mcp-server/blob/main/README.md

These commands help verify the installation by checking the status of running services and viewing the logs for the Graphiti MCP service. This is useful for troubleshooting.

```bash
# Check if services are running
docker compose ps

# Check logs
docker compose logs graphiti-mcp
```

--------------------------------

### Running Graphiti MCP Server Locally

Source: https://github.com/gifflet/graphiti-mcp-server/blob/main/README.md

Instructions for starting the Graphiti MCP Server locally using `uv`. Shows how to set necessary environment variables and run the server with different transport options like stdio and SSE.

```bash
# Set environment variables
export OPENAI_API_KEY=your_key
export NEO4J_URI=bolt://localhost:7687

# Run with stdio transport
uv run graphiti_mcp_server.py

# Or with SSE transport
uv run graphiti_mcp_server.py --transport sse --use-custom-entities
```

--------------------------------

### Set Up Environment Variables for Graphiti MCP Server

Source: https://github.com/gifflet/graphiti-mcp-server/blob/main/README.md

This snippet shows example environment variables that need to be set in the .env file for the Graphiti MCP Server. It includes OpenAI API key, model names, and Neo4j connection details. These are crucial for the server's operation, especially for LLM and database interactions.

```bash
# Required for LLM operations
OPENAI_API_KEY=your_openai_api_key_here
MODEL_NAME=gpt-4.1-mini

# Optional: Custom OpenAI endpoint (e.g., for proxies)
# OPENAI_BASE_URL=https://api.openai.com/v1

# Neo4j Configuration (defaults work with Docker)
NEO4J_URI=bolt://neo4j:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=demodemo
```

--------------------------------

### Run Graphiti MCP Server with Direct Environment Variables

Source: https://github.com/gifflet/graphiti-mcp-server/blob/main/README.md

This alternative method starts the Graphiti MCP Server using Docker Compose while directly specifying environment variables on the command line, bypassing the need for a .env file for these specific variables.

```bash
OPENAI_API_KEY=your_key MODEL_NAME=gpt-4.1-mini docker compose up
```

--------------------------------

### Start Graphiti MCP Server Services with Docker Compose

Source: https://github.com/gifflet/graphiti-mcp-server/blob/main/README.md

This command starts all the services defined in the Docker Compose file in detached mode (-d), allowing the Graphiti MCP Server and its dependencies (like Neo4j) to run in the background.

```bash
docker compose up -d
```

--------------------------------

### Run Graphiti MCP Server with Docker Compose and Custom Settings (Bash)

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Provides commands to run the Graphiti MCP Server. This includes starting the server using Docker Compose for a managed environment, or running it locally with custom settings via the `uv` command. Options allow for specifying transport protocols (SSE, stdio), group IDs, custom entities, model names, and LLM temperatures.

```bash
# Run with Docker Compose
docker compose up -d

# Run locally with custom settings
uv run graphiti_mcp_server.py \
  --transport sse \
  --group-id my_project \
  --use-custom-entities \
  --model gpt-4o \
  --temperature 0.1

# Run with stdio transport for direct MCP integration
uv run graphiti_mcp_server.py --transport stdio
```

--------------------------------

### Clone Graphiti MCP Server Repository

Source: https://github.com/gifflet/graphiti-mcp-server/blob/main/README.md

This command clones the Graphiti MCP Server repository from GitHub to your local machine, which is the first step in the installation process.

```bash
git clone https://github.com/gifflet/graphiti-mcp-server.git
cd graphiti-mcp-server
```

--------------------------------

### Viewing Logs and Debugging Graphiti MCP Server with Docker

Source: https://github.com/gifflet/graphiti-mcp-server/blob/main/README.md

Guides users on how to view logs for all services or specific services (like `graphiti-mcp` or `neo4j`) using `docker compose logs`. Also shows how to enable debug logging by setting the `LOG_LEVEL` environment variable.

```bash
# View all logs
docker compose logs -f

# View specific service logs
docker compose logs -f graphiti-mcp
docker compose logs -f neo4j

# Enable debug logging
docker compose up -e LOG_LEVEL=DEBUG
```

--------------------------------

### Neo4j Direct Queries

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Provides examples of Cypher queries to interact directly with the Neo4j graph database for advanced operations and data retrieval.

```APIDOC
## Neo4j Direct Queries

### Description
Access Neo4j directly for advanced graph operations and visualization.

### Queries

#### View all nodes and relationships
```cypher
MATCH (n) OPTIONAL MATCH (n)-[r]->(m) RETURN n,r,m
```
* **Access**: Neo4j Browser at `http://localhost:7474`

#### Find all entities in a specific group
```cypher
MATCH (n {group_id: 'acme_project'}) RETURN n
```
* **Parameters**:
  - **`group_id`** (string) - The ID of the group to filter entities by.

#### Find shortest path between two entities
```cypher
MATCH (start {name: 'Sarah Chen'}), (end {name: 'CloudSync'})
MATCH path = shortestPath((start)-[*]-(end))
RETURN path
```
* **Parameters**:
  - **`start`** (object with `name` property) - The starting entity.
  - **`end`** (object with `name` property) - The ending entity.

#### Get temporal fact history
```cypher
MATCH ()-[r:ENTITY_EDGE]->()
WHERE r.valid_at IS NOT NULL
RETURN r.fact, r.valid_at, r.invalid_at
ORDER BY r.valid_at DESC
LIMIT 20
```
* **Description**: Retrieves temporal data for entity edges, ordered by validity date.
```

--------------------------------

### Get Episodes API

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Retrieves recent episodes for a specific group, useful for understanding conversation history and context.

```APIDOC
## GET /episodes

### Description
Retrieve the most recent episodes for a specific group, useful for understanding conversation history and context.

### Method
GET

### Endpoint
/episodes

### Parameters
#### Query Parameters
- **group_id** (string) - Optional - The ID of the group to retrieve episodes from. If not provided, uses the default group.
- **last_n** (integer) - Required - The number of most recent episodes to retrieve.

### Request Example
```python
# Get last 10 episodes for a specific group
from graphiti_mcp_server import get_episodes
episodes = await get_episodes(group_id="acme_project", last_n=10)

# Get last 5 episodes from the default group
episodes = await get_episodes(last_n=5)
```

### Response
#### Success Response (200)
- **episodes** (array of objects) - A list of episode objects.
  - **uuid** (string) - The UUID of the episode.
  - **name** (string) - The name of the episode.
  - **content** (string) - The content of the episode.
  - **source** (string) - The source of the episode (e.g., 'text').
  - **source_description** (string) - A description of the source.
  - **group_id** (string) - The ID of the group the episode belongs to.
  - **created_at** (string) - The timestamp when the episode was created.
  - **valid_at** (string) - The timestamp when the episode is considered valid.

#### Response Example
```json
[
  {
    "uuid": "episode_001",
    "name": "Company Announcement",
    "content": "Acme Corp launched CloudSync v2.0...",
    "source": "text",
    "source_description": "press release",
    "group_id": "acme_project",
    "created_at": "2025-01-01T18:30:00Z",
    "valid_at": "2025-01-01T18:30:00Z"
  }
]
```
```

--------------------------------

### Neo4j Direct Queries for Graph Operations

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Provides examples of direct Cypher queries to interact with the Neo4j graph database. These queries cover viewing all graph data, finding entities within a specific group, determining the shortest path between entities, and retrieving temporal fact history.

```cypher
-- View all nodes and relationships (Neo4j Browser at http://localhost:7474)
MATCH (n) OPTIONAL MATCH (n)-[r]->(m) RETURN n,r,m

-- Find all entities in a specific group
MATCH (n {group_id: 'acme_project'}) RETURN n

-- Find shortest path between two entities
MATCH (start {name: 'Sarah Chen'}), (end {name: 'CloudSync'})
MATCH path = shortestPath((start)-[*]-(end))
RETURN path

-- Get temporal fact history
MATCH ()-[r:ENTITY_EDGE]->()
WHERE r.valid_at IS NOT NULL
RETURN r.fact, r.valid_at, r.invalid_at
ORDER BY r.valid_at DESC
LIMIT 20
```

--------------------------------

### Get Graphiti MCP Server Status

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Demonstrates how to retrieve the current status of the Graphiti MCP server and its connection to Neo4j. The function returns a status object indicating whether the server is operational and connected.

```python
from graphiti_mcp_server import get_status

# Check server status
status = await get_status()
# Returns: {
#   "status": "ok",
#   "message": "Graphiti MCP server is running and connected to Neo4j"
# }

# On connection failure:
# {
#   "status": "error",
#   "message": "Graphiti MCP server is running but Neo4j connection failed: ..."
# }
```

--------------------------------

### Get Entity Edge API

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Retrieves a specific fact (entity edge) from the knowledge graph by its unique identifier (UUID).

```APIDOC
## GET /entity_edges/{uuid}

### Description
Retrieves a specific fact (entity edge) by its UUID.

### Method
GET

### Endpoint
/entity_edges/{uuid}

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The UUID of the entity edge to retrieve.

### Response
#### Success Response (200)
- **uuid** (string) - The UUID of the entity edge.
- **source_node_uuid** (string) - The UUID of the source node.
- **target_node_uuid** (string) - The UUID of the target node.
- **name** (string) - The name or type of the relationship.
- **fact** (string) - A textual description of the fact.
- **episodes** (array of strings) - A list of episode UUIDs associated with this fact.
- **valid_at** (string) - The timestamp when the fact becomes valid.
- **invalid_at** (string or null) - The timestamp when the fact becomes invalid.
- **created_at** (string) - The timestamp when the fact was created.

#### Response Example
```json
{
  "uuid": "edge_456def",
  "source_node_uuid": "node_789ghi",
  "target_node_uuid": "node_123abc",
  "name": "USES_PRODUCT",
  "fact": "TechStart Inc uses CloudSync (active subscription)",
  "episodes": ["episode_001", "episode_002"],
  "valid_at": "2025-01-01T18:30:00Z",
  "invalid_at": null,
  "created_at": "2025-01-01T18:30:00Z"
}
```
```

--------------------------------

### Get Episodes from Graphiti MCP Server (Python)

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Fetches recent episodes for a specified group, which is useful for understanding conversation history and context. You can retrieve a specific number of the latest episodes or episodes from the default group. The function returns a list of episode objects, each containing details like UUID, name, content, source, and timestamps.

```python
from graphiti_mcp_server import get_episodes

# Get last 10 episodes
episodes = await get_episodes(
    group_id="acme_project",
    last_n=10
)

# Get recent episodes from default group
episodes = await get_episodes(last_n=5)
```

--------------------------------

### Get Entity Edge Details from Graphiti MCP Server (Python)

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Retrieves the details of a specific entity edge (relationship) using its unique UUID. The function returns a dictionary containing information about the edge, including source and target nodes, name, fact description, associated episodes, and validity timestamps. This is a core function for accessing relationship data.

```python
from graphiti_mcp_server import get_entity_edge

# Get specific relationship details
edge = await get_entity_edge(uuid="edge_456def")
```

--------------------------------

### Copy Environment Sample File

Source: https://github.com/gifflet/graphiti-mcp-server/blob/main/README.md

This command copies the sample environment file to a new file named .env, which will be used to store your project's configuration variables.

```bash
cp .env.sample .env
```

--------------------------------

### Running Graphiti MCP Server with Docker Environment Variables

Source: https://github.com/gifflet/graphiti-mcp-server/blob/main/README.md

Demonstrates how to configure and run the Graphiti MCP Server using Docker Compose with environment variables for OpenAI API keys and model names. Supports both standard OpenAI and Azure OpenAI configurations.

```bash
OPENAI_API_KEY=your_key MODEL_NAME=gpt-4.1-mini docker compose up
```

```bash
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com \
AZURE_OPENAI_API_VERSION=2024-02-01 \
AZURE_OPENAI_DEPLOYMENT_NAME=your-deployment \
OPENAI_API_KEY=your_key \
docker compose up
```

--------------------------------

### Run Graphiti MCP Server with Custom Entities

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Demonstrates how to run the Graphiti MCP server with custom entity extraction enabled using a command-line flag. This configuration allows the server to process and interpret custom data models.

```bash
uv run graphiti_mcp_server.py --use-custom-entities --transport sse
```

--------------------------------

### Configure Graphiti MCP Server with Environment Variables (Bash/INI)

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Sets up the Graphiti MCP Server by configuring environment variables, typically stored in a .env file or passed via command line. This includes API keys for OpenAI or Azure OpenAI, model names, database connection details for Neo4j, and semaphore limits. These settings control the server's behavior and integration with external services.

```bash
# Basic OpenAI configuration (.env file)
OPENAI_API_KEY=sk-proj-xxxxx
MODEL_NAME=gpt-4.1-mini
SMALL_MODEL_NAME=gpt-4.1-nano
LLM_TEMPERATURE=0.0
EMBEDDER_MODEL_NAME=text-embedding-3-small

NEO4J_URI=bolt://neo4j:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=demodemo

SEMAPHORE_LIMIT=10

# Azure OpenAI configuration
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
AZURE_OPENAI_API_VERSION=2024-02-01
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4o-deployment
AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME=text-embedding-3-large
AZURE_OPENAI_USE_MANAGED_IDENTITY=false
OPENAI_API_KEY=your_azure_key
```

--------------------------------

### Configuring Cursor IDE Integration for Graphiti MCP Server

Source: https://github.com/gifflet/graphiti-mcp-server/blob/main/README.md

Provides JSON configurations for integrating the Graphiti MCP Server with the Cursor IDE. Covers settings for direct command execution and for connecting to a running Docker-based server via SSE.

```json
{
  "mcpServers": {
    "Graphiti": {
      "command": "uv",
      "args": ["run", "graphiti_mcp_server.py"],
      "env": {
        "OPENAI_API_KEY": "your_key_here"
      }
    }
  }
}
```

```json
{
  "mcpServers": {
    "Graphiti": {
      "url": "http://localhost:8000/sse"
    }
  }
}
```

--------------------------------

### Manage Docker Services for Graphiti MCP

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Provides essential Docker commands for managing the Graphiti MCP server and its associated services, including checking the status of running containers, and viewing logs for both the Graphiti server and the Neo4j database.

```bash
# Check Docker services
docker compose ps
docker compose logs graphiti-mcp
docker compose logs neo4j

# View Neo4j metrics
# Open http://localhost:7474 in browser
# Login: neo4j / demodemo
```

--------------------------------

### Troubleshooting Docker Issues with Graphiti MCP Server

Source: https://github.com/gifflet/graphiti-mcp-server/blob/main/README.md

Offers commands for troubleshooting common Docker-related issues when running the Graphiti MCP Server, including cleaning up and rebuilding containers, and checking Docker disk space.

```bash
# Clean up and restart
docker compose down -v
docker compose up --build

# Check disk space
docker system df
```

--------------------------------

### Server Configuration

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Configure the Graphiti MCP Server using environment variables or command-line arguments for various settings like LLM providers, database connections, and concurrency limits.

```APIDOC
## Server Configuration

### Description
Configure the Graphiti MCP Server via environment variables or command-line arguments.

### Environment Variables
#### General
- **SEMAPHORE_LIMIT** (integer) - Sets the concurrency limit for processing requests.

#### OpenAI Configuration
- **OPENAI_API_KEY** (string) - Your OpenAI API key.
- **MODEL_NAME** (string) - The primary language model to use (e.g., `gpt-4.1-mini`).
- **SMALL_MODEL_NAME** (string) - A smaller, potentially faster model for specific tasks (e.g., `gpt-4.1-nano`).
- **LLM_TEMPERATURE** (float) - Controls the randomness of the model's output (0.0 to 1.0).
- **EMBEDDER_MODEL_NAME** (string) - The model to use for generating embeddings (e.g., `text-embedding-3-small`).

#### Azure OpenAI Configuration
- **AZURE_OPENAI_ENDPOINT** (string) - The Azure OpenAI service endpoint.
- **AZURE_OPENAI_API_VERSION** (string) - The API version for Azure OpenAI.
- **AZURE_OPENAI_DEPLOYMENT_NAME** (string) - The deployment name for the chat model.
- **AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME** (string) - The deployment name for the embedding model.
- **AZURE_OPENAI_USE_MANAGED_IDENTITY** (boolean) - Whether to use managed identity for authentication.

#### Neo4j Configuration
- **NEO4J_URI** (string) - The connection URI for the Neo4j database (e.g., `bolt://neo4j:7687`).
- **NEO4J_USER** (string) - The username for Neo4j authentication.
- **NEO4J_PASSWORD** (string) - The password for Neo4j authentication.

### Command-Line Arguments
Run the server using `uv run graphiti_mcp_server.py` with the following optional arguments:

- **--transport** (string) - Specifies the transport protocol (e.g., `sse`, `stdio`). Default is `sse`.
- **--group-id** (string) - Sets the default group ID for operations.
- **--use-custom-entities** - Enables the use of custom entity definitions.
- **--model** (string) - Overrides the default `MODEL_NAME` environment variable.
- **--temperature** (float) - Overrides the `LLM_TEMPERATURE` environment variable.

### Examples
#### Basic OpenAI Configuration (.env file)
```dotenv
OPENAI_API_KEY=sk-proj-xxxxx
MODEL_NAME=gpt-4.1-mini
SMALL_MODEL_NAME=gpt-4.1-nano
LLM_TEMPERATURE=0.0
EMBEDDER_MODEL_NAME=text-embedding-3-small
NEO4J_URI=bolt://neo4j:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=demodemo
SEMAPHORE_LIMIT=10
```

#### Azure OpenAI Configuration
```dotenv
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
AZURE_OPENAI_API_VERSION=2024-02-01
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4o-deployment
AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME=text-embedding-3-large
AZURE_OPENAI_USE_MANAGED_IDENTITY=false
OPENAI_API_KEY=your_azure_key
```

#### Run with Docker Compose
```bash
docker compose up -d
```

#### Run locally with custom settings
```bash
uv run graphiti_mcp_server.py \
  --transport sse \
  --group-id my_project \
  --use-custom-entities \
  --model gpt-4o \
  --temperature 0.1
```

#### Run with stdio transport
```bash
uv run graphiti_mcp_server.py --transport stdio
```
```

--------------------------------

### Error Handling

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Demonstrates how to handle common error scenarios, such as uninitialized clients, search failures, and invalid parameters.

```APIDOC
## Error Handling

### Description
Handle common error scenarios when working with the MCP server.

### Scenarios

#### Client Initialization Error
```python
from graphiti_mcp_server import add_memory, ErrorResponse

result = await add_memory(
    name="Test",
    episode_body="content",
    group_id="test"
)
if isinstance(result, ErrorResponse):
    # Expected Error Response:
    # {"error": "Graphiti client not initialized"}
    print(f"Error: {result['error']}")
```

#### Search Failures
```python
from graphiti_mcp_server import search_memory_nodes

result = await search_memory_nodes(
    query="test query",
    group_ids=["nonexistent"] # Assuming this group does not exist
)
if result["nodes"]:
    print(f"Found {len(result['nodes'])} nodes")
else:
    # Expected Response:
    # {"message": "No relevant nodes found", "nodes": []}
    print("No results")
```

#### Parameter Validation Error
```python
from graphiti_mcp_server import search_memory_facts

result = await search_memory_facts(
    query="test",
    max_facts=-1 # Invalid value
)
# Expected Error Response:
# {"error": "max_facts must be a positive integer"}
```
```

--------------------------------

### Error Handling in Graphiti MCP Server

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Illustrates how to handle common error responses from the Graphiti MCP server, such as initialization failures, search result issues, and parameter validation errors. This code demonstrates checking the type of the returned result and accessing error messages.

```python
from graphiti_mcp_server import add_memory, search_memory_nodes, ErrorResponse

# Check initialization
result = await add_memory(
    name="Test",
    episode_body="content",
    group_id="test"
)
if isinstance(result, ErrorResponse):
    # Returns: {"error": "Graphiti client not initialized"}
    print(f"Error: {result['error']}")

# Handle search failures
result = await search_memory_nodes(
    query="test query",
    group_ids=["nonexistent"]
)
if result["nodes"]:
    print(f"Found {len(result['nodes'])} nodes")
else:
    # Returns: {"message": "No relevant nodes found", "nodes": []}
    print("No results")

# Validate parameters
result = await search_memory_facts(
    query="test",
    max_facts=-1
)
# Returns: {"error": "max_facts must be a positive integer"}
```

--------------------------------

### MCP Client Integration

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Integrate the Graphiti MCP Server with clients like Cursor IDE using various connection methods, including direct command execution, SSE, and WebSockets.

```APIDOC
## MCP Client Integration

### Description
Integrate Graphiti MCP Server with Cursor IDE or other MCP clients.

### Configuration Methods
#### 1. Direct Command Execution (e.g., for Cursor IDE)
Specify the command and arguments to run the server, along with necessary environment variables.

**cursor_settings.json**
```json
{
  "mcpServers": {
    "Graphiti": {
      "command": "uv",
      "args": ["run", "graphiti_mcp_server.py"],
      "env": {
        "OPENAI_API_KEY": "sk-proj-xxxxx",
        "MODEL_NAME": "gpt-4.1-mini",
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "demodemo"
      }
    }
  }
}
```

#### 2. SSE (Server-Sent Events) Connection
Connect to the server via Server-Sent Events, typically used when the server is run in a separate process or container.

**cursor_settings.json**
```json
{
  "mcpServers": {
    "Graphiti": {
      "url": "http://localhost:8000/sse"
    }
  }
}
```

#### 3. WebSocket Connection
Connect to the server using a WebSocket connection.

**cursor_settings.json**
```json
{
  "mcpServers": {
    "Graphiti": {
      "url": "ws://localhost:8000/ws"
    }
  }
}
```
```

--------------------------------

### Define Custom Entity Extraction Models (Python)

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Illustrates the initial step for defining custom entity types using Pydantic models in Python. This is the foundation for enabling domain-specific knowledge extraction within the Graphiti MCP Server, allowing users to tailor the system to recognize and process unique data structures.

```python
from pydantic import BaseModel, Field
```

--------------------------------

### Search Memory Facts in Python

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Searches for facts (relationships between entities) in the knowledge graph using semantic search. Returns edges with temporal metadata, including creation and validity times. Requires the graphiti_mcp_server library.

```python
from graphiti_mcp_server import search_memory_facts

# Search for specific relationships
result = await search_memory_facts(
    query="What products does TechStart Inc use?",
    group_ids=["customer_data"],
    max_facts=10
)
# Returns: {
#   "message": "Facts retrieved successfully",
#   "facts": [
#     {
#       "uuid": "edge_456def",
#       "source_node_uuid": "node_789ghi",
#       "target_node_uuid": "node_123abc",
#       "name": "USES_PRODUCT",
#       "fact": "TechStart Inc uses CloudSync (active subscription)",
#       "valid_at": "2025-01-01T18:30:00Z",
#       "invalid_at": null,
#       "created_at": "2025-01-01T18:30:00Z",
#       "expired_at": null
#     }
#   ]
# }
```

--------------------------------

### Search Memory Nodes in Python

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Searches for entities (nodes) within the knowledge graph using semantic search. Returns node summaries, including relationship information. Supports basic queries, entity type filtering, and searching around a specific node. Requires the graphiti_mcp_server library.

```python
from graphiti_mcp_server import search_memory_nodes

# Basic node search
result = await search_memory_nodes(
    query="Find all people working on the CloudSync project",
    group_ids=["acme_project"],
    max_nodes=10
)
# Returns: {
#   "message": "Nodes retrieved successfully",
#   "nodes": [
#     {
#       "uuid": "node_123abc",
#       "name": "Sarah Chen",
#       "summary": "Product manager at Acme Corp who announced CloudSync v2.0",
#       "labels": ["Person"],
#       "group_id": "acme_project",
#       "created_at": "2025-01-01T18:30:00Z",
#       "attributes": {}
#     }
#   ]
# }

# Search with entity type filter
result = await search_memory_nodes(
    query="user preferences for notifications",
    group_ids=["user_settings"],
    max_nodes=5,
    entity="Preference"
)

# Search centered around a specific node
result = await search_memory_nodes(
    query="related projects",
    center_node_uuid="node_123abc",
    max_nodes=15
)
```

--------------------------------

### Add Memory with Custom Entity Extraction

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Shows how to add memory to the Graphiti MCP server, enabling automatic extraction of custom entities like 'Requirement' and 'Preference' from the provided episode body. The result of this operation is automatically processed to identify and categorize specific data points.

```python
result = await add_memory(
    name="Feature Discussion",
    episode_body="The system must support OAuth2 authentication for the mobile app project. Users prefer dark mode by default.",
    source="text",
    group_id="mobile_app_project"
)
# Automatically extracts:
# - Requirement: "OAuth2 authentication" for project "mobile app"
# - Preference: category="UI", description="prefers dark mode by default"
```

--------------------------------

### Testing Graphiti MCP Server Endpoints

Source: https://github.com/gifflet/graphiti-mcp-server/blob/main/README.md

Provides `curl` commands to test the health and MCP (Server-Sent Events) endpoints of the running Graphiti MCP Server.

```bash
# Run basic connectivity test
curl http://localhost:8000/health

# Test MCP endpoint
curl http://localhost:8000/sse
```

--------------------------------

### Add Memory Episode in Python

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Ingests information into the knowledge graph as episodes. Supports plain text, JSON, and message formats. Episodes are processed sequentially per group_id to prevent race conditions. Requires the graphiti_mcp_server library.

```python
import asyncio
from graphiti_mcp_server import add_memory

# Add plain text memory
result = await add_memory(
    name="Company Announcement",
    episode_body="Acme Corp launched CloudSync v2.0 with real-time collaboration features. The product manager Sarah Chen announced it at the conference.",
    source="text",
    source_description="press release",
    group_id="acme_project"
)
# Returns: {"message": "Episode 'Company Announcement' queued for processing (position: 1)"}

# Add structured JSON data (note the triple-escaped JSON string)
result = await add_memory(
    name="Customer Profile",
    episode_body="{\"customer\": {\"name\": \"TechStart Inc\", \"tier\": \"Enterprise\"}, \"products\": [{\"id\": \"P001\", \"name\": \"CloudSync\", \"active\": true}, {\"id\": \"P002\", \"name\": \"DataMiner\", \"active\": false}]}",
    source="json",
    source_description="CRM database export",
    group_id="customer_data"
)

# Add conversation message
result = await add_memory(
    name="Support Ticket",
    episode_body="user: I can't access the dashboard\nagent: Let me check your permissions. Can you confirm your email?\nuser: john@techstart.com",
    source="message",
    source_description="support chat log",
    group_id="support_tickets"
)
```

--------------------------------

### Search Memory Nodes

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Searches for entities (nodes) in the knowledge graph using semantic search. Returns node summaries including relationship information.

```APIDOC
## Search Memory Nodes

### Description
Searches for entities (nodes) in the knowledge graph using semantic search. Returns node summaries containing relationship information.

### Method
POST (Assumed, based on 'search' operation)

### Endpoint
`/memory/nodes/search` (Assumed)

### Parameters
#### Request Body
- **query** (string) - Required - The semantic search query to find nodes.
- **group_ids** (array of strings) - Optional - Filters search results to specific group IDs.
- **max_nodes** (integer) - Optional - The maximum number of nodes to return. Defaults to 10.
- **entity** (string) - Optional - Filters search results to a specific entity type (e.g., "Preference").
- **center_node_uuid** (string) - Optional - Performs a search centered around a specific node.

### Request Example
```json
{
  "query": "Find all people working on the CloudSync project",
  "group_ids": ["acme_project"],
  "max_nodes": 10
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating nodes were retrieved.
- **nodes** (array of objects) - A list of matching nodes, each containing:
  - **uuid** (string) - The unique identifier of the node.
  - **name** (string) - The name of the node.
  - **summary** (string) - A brief summary of the node and its context.
  - **labels** (array of strings) - The types or labels of the node.
  - **group_id** (string) - The group ID the node belongs to.
  - **created_at** (string) - The timestamp when the node was created.
  - **attributes** (object) - Additional attributes of the node.

#### Response Example
```json
{
  "message": "Nodes retrieved successfully",
  "nodes": [
    {
      "uuid": "node_123abc",
      "name": "Sarah Chen",
      "summary": "Product manager at Acme Corp who announced CloudSync v2.0",
      "labels": ["Person"],
      "group_id": "acme_project",
      "created_at": "2025-01-01T18:30:00Z",
      "attributes": {}
    }
  ]
}
```
```

--------------------------------

### Define Custom Entities for Requirements and Preferences

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Defines custom entity types 'Requirement' and 'Preference' using Pydantic's BaseModel for structured data extraction. These models specify fields with descriptions and constraints, enabling the server to parse and store specific types of information from text.

```python
from pydantic import BaseModel, Field

class Requirement(BaseModel):
    """Extract project requirements from conversations and documents."""
    project_name: str = Field(
        ...,
        description='The name of the project to which the requirement belongs.'
    )
    description: str = Field(
        ...,
        description='Description of the requirement from the context.'
    )

class Preference(BaseModel):
    """Extract user preferences and settings."""
    category: str = Field(..., description="Category like 'Brands', 'Food', 'Music'")
    description: str = Field(..., description='Brief description of the preference')
```

--------------------------------

### Search Memory Facts API

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Searches for facts within the knowledge graph related to a specific entity, allowing for flexible querying and filtering.

```APIDOC
## POST /search/memory_facts

### Description
Searches for facts within the knowledge graph related to a specific entity.

### Method
POST

### Endpoint
/search/memory_facts

### Parameters
#### Query Parameters
- **query** (string) - Required - The search query.
- **center_node_uuid** (string) - Required - The UUID of the entity to search around.
- **max_facts** (integer) - Optional - The maximum number of facts to return.
- **group_ids** (array of strings) - Optional - A list of group IDs to filter the search.

### Request Example
```json
{
  "query": "all relationships",
  "center_node_uuid": "node_789ghi",
  "max_facts": 20,
  "group_ids": ["customer_data"]
}
```

### Response
#### Success Response (200)
- **result** (object) - The search results containing facts.

#### Response Example
```json
{
  "result": [
    {
      "uuid": "edge_456def",
      "source_node_uuid": "node_789ghi",
      "target_node_uuid": "node_123abc",
      "name": "USES_PRODUCT",
      "fact": "TechStart Inc uses CloudSync (active subscription)",
      "episodes": ["episode_001", "episode_002"],
      "valid_at": "2025-01-01T18:30:00Z",
      "invalid_at": null,
      "created_at": "2025-01-01T18:30:00Z"
    }
  ]
}
```
```

--------------------------------

### Search Memory Facts

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Searches for facts (relationships between entities) in the knowledge graph using semantic search. Returns edges with temporal metadata.

```APIDOC
## Search Memory Facts

### Description
Searches for facts (relationships between entities) in the knowledge graph using semantic search. Returns edges with temporal metadata.

### Method
POST (Assumed, based on 'search' operation)

### Endpoint
`/memory/facts/search` (Assumed)

### Parameters
#### Request Body
- **query** (string) - Required - The semantic search query to find facts.
- **group_ids** (array of strings) - Optional - Filters search results to specific group IDs.
- **max_facts** (integer) - Optional - The maximum number of facts to return. Defaults to 10.

### Request Example
```json
{
  "query": "What products does TechStart Inc use?",
  "group_ids": ["customer_data"],
  "max_facts": 10
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating facts were retrieved.
- **facts** (array of objects) - A list of matching facts, each containing:
  - **uuid** (string) - The unique identifier of the fact (edge).
  - **source_node_uuid** (string) - The UUID of the source node in the relationship.
  - **target_node_uuid** (string) - The UUID of the target node in the relationship.
  - **name** (string) - The name or type of the relationship.
  - **fact** (string) - A descriptive string of the fact.
  - **valid_at** (string) - The timestamp when the fact became valid.
  - **invalid_at** (string) - The timestamp when the fact became invalid (null if still valid).
  - **created_at** (string) - The timestamp when the fact was created.
  - **expired_at** (string) - The timestamp when the fact expired (null if not expired).

#### Response Example
```json
{
  "message": "Facts retrieved successfully",
  "facts": [
    {
      "uuid": "edge_456def",
      "source_node_uuid": "node_789ghi",
      "target_node_uuid": "node_123abc",
      "name": "USES_PRODUCT",
      "fact": "TechStart Inc uses CloudSync (active subscription)",
      "valid_at": "2025-01-01T18:30:00Z",
      "invalid_at": null,
      "created_at": "2025-01-01T18:30:00Z",
      "expired_at": null
    }
  ]
}
```
```

--------------------------------

### Custom Entity Definition and Usage

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Define custom entities like Requirement and Preference for enhanced memory extraction. The server automatically extracts these entities when enabled via the command line.

```APIDOC
## Custom Entity Definition

### Description
Custom entities allow the server to extract specific types of information from text.

### Classes

#### `Requirement`
- **Description**: `Extract project requirements from conversations and documents.`
  - **`project_name`** (str) - Required - The name of the project to which the requirement belongs.
  - **`description`** (str) - Required - Description of the requirement from the context.

#### `Preference`
- **Description**: `Extract user preferences and settings.`
  - **`category`** (str) - Required - Category like 'Brands', 'Food', 'Music'.
  - **`description`** (str) - Required - Brief description of the preference.

### Server Configuration

#### Command Line
```bash
uv run graphiti_mcp_server.py --use-custom-entities --transport sse
```

### Example Usage

```python
from graphiti_mcp_server import add_memory

result = await add_memory(
    name="Feature Discussion",
    episode_body="The system must support OAuth2 authentication for the mobile app project. Users prefer dark mode by default.",
    source="text",
    group_id="mobile_app_project"
)
# Automatically extracts:
# - Requirement: "OAuth2 authentication" for project "mobile app"
# - Preference: category="UI", description="prefers dark mode by default"
```
```

--------------------------------

### Search Memory Facts in Graphiti MCP Server (Python)

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Searches for facts related to a specific entity in the knowledge graph. It requires a query string, the UUID of the center node, the maximum number of facts to retrieve, and optionally a list of group IDs. This function is part of the Graphiti MCP Server library.

```python
result = await search_memory_facts(
    query="all relationships",
    center_node_uuid="node_789ghi",
    max_facts=20,
    group_ids=["customer_data"]
)
```

--------------------------------

### Health Check and Status

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

APIs and tools to monitor the health of the Graphiti MCP server and its connection to Neo4j.

```APIDOC
## Health Check and Status

### Description
Monitor server health and Neo4j connectivity.

### API Endpoint

#### `get_status()`

```python
from graphiti_mcp_server import get_status

status = await get_status()
# Expected Success Response:
# {
#   "status": "ok",
#   "message": "Graphiti MCP server is running and connected to Neo4j"
# }

# Expected Error Response (on connection failure):
# {
#   "status": "error",
#   "message": "Graphiti MCP server is running but Neo4j connection failed: ..."
# }
```

### HTTP Health Check

- **Method**: `GET`
- **Endpoint**: `/health`
- **Description**: Provides a quick HTTP check for the server's status, especially useful when using SSE transport.
- **Example**: 
```bash
curl http://localhost:8000/health
```

### Docker Monitoring

- **Check Services**: 
```bash
docker compose ps
```

- **View Logs**: 
```bash
docker compose logs graphiti-mcp
docker compose logs neo4j
```

### Neo4j Metrics

- **Access**: Open `http://localhost:7474` in your web browser.
- **Default Credentials**: `neo4j` / `demodemo`
```

--------------------------------

### Custom Entity Extraction

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Define and utilize custom entity types for domain-specific knowledge extraction, enabling tailored data modeling and analysis.

```APIDOC
## Custom Entity Extraction

### Description
Define and use custom entity types for domain-specific knowledge extraction.

### Usage
Custom entities are defined using Pydantic models. This allows for structured definition of entity schemas and validation of extracted data.

### Example
```python
from pydantic import BaseModel, Field

class Product(BaseModel):
    name: str = Field(description="The name of the product.")
    version: str = Field(description="The version of the product.")
    manufacturer: str = Field(description="The company that manufactured the product.")

# Example of how this might be used in extraction (implementation details vary)
# extracted_product = extract_entity(data, Product)
```
```

--------------------------------

### Add Memory Episode

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Adds a new memory episode to the knowledge graph. Supports plain text, JSON, and message formats. Episodes are processed sequentially per group_id.

```APIDOC
## Add Memory Episode

### Description
Adds an episode (memory) to the knowledge graph. This is the primary method for ingesting information and supports text, JSON, and message formats. Episodes are processed sequentially per group_id to avoid race conditions.

### Method
POST (Assumed, based on 'add' operation)

### Endpoint
`/memory/episode` (Assumed)

### Parameters
#### Request Body
- **name** (string) - Required - The name or title of the memory episode.
- **episode_body** (string) - Required - The content of the memory episode. Can be text, JSON string, or message format.
- **source** (string) - Required - The type of the source (e.g., "text", "json", "message").
- **source_description** (string) - Optional - A description of the source.
- **group_id** (string) - Required - An identifier for grouping related episodes.

### Request Example
```json
{
  "name": "Company Announcement",
  "episode_body": "Acme Corp launched CloudSync v2.0 with real-time collaboration features. The product manager Sarah Chen announced it at the conference.",
  "source": "text",
  "source_description": "press release",
  "group_id": "acme_project"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the episode is queued for processing.

#### Response Example
```json
{
  "message": "Episode 'Company Announcement' queued for processing (position: 1)"
}
```
```

--------------------------------

### Clear Graph API

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Removes all data from the knowledge graph and rebuilds indices. This operation should be used with caution in production environments.

```APIDOC
## POST /clear

### Description
Remove all data from the knowledge graph and rebuild indices. Use with caution in production.

### Method
POST

### Endpoint
/clear

### Request Example
```python
from graphiti_mcp_server import clear_graph

# Reset entire graph database
result = await clear_graph()
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the graph has been cleared.

#### Response Example
```json
{
  "message": "Graph cleared successfully and indices rebuilt"
}
```
```

--------------------------------

### Clear Graph Data in Graphiti MCP Server (Python)

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Removes all data from the knowledge graph and rebuilds its indices. This operation is irreversible and should be used with extreme caution, especially in production environments. The function returns a success message indicating the graph has been cleared.

```python
from graphiti_mcp_server import clear_graph

# Reset entire graph database
result = await clear_graph()
```

--------------------------------

### Delete Episode API

Source: https://context7.com/gifflet/graphiti-mcp-server/llms.txt

Removes an episode from the knowledge graph, including associated entities and relationships.

```APIDOC
## DELETE /episodes/{uuid}

### Description
Remove an episode from the knowledge graph, including associated entities and relationships.

### Method
DELETE

### Endpoint
/episodes/{uuid}

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The UUID of the episode to delete.

### Request Example
```python
from graphiti_mcp_server import delete_episode

# Delete outdated episode
result = await delete_episode(uuid="episode_001")
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating successful deletion.

#### Response Example
```json
{
  "message": "Episode with UUID episode_001 deleted successfully"
}
```
```