# Graphiti MCP Usage

> Reference for using the Graphiti MCP knowledge graph (graphiti-mcp-aws) to add, search, and manage project memories. Use when interacting with the knowledge graph, adding memories, searching for context, or managing graph data.

- Skill: `smartcontractkit/graphiti-mcp-usage` (Agent Skill)
- Install (CLI): `npx skillmds@latest add smartcontractkit/graphiti-mcp-usage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/smartcontractkit/graphiti-mcp-usage/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: smartcontractkit (https://skillmd.com/u/smartcontractkit)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/smartcontractkit/graphiti-mcp-usage

---


# Graphiti MCP Usage

Quick reference for the `graphiti-mcp-aws` MCP server tools. Use this when persisting or retrieving project knowledge.

## Tools Overview

| Tool | Purpose |
|------|---------|
| `add_memory` | Add an episode (text, JSON, or message) to the graph |
| `search_nodes` | Find entities by natural language query |
| `search_memory_facts` | Find relationships/facts between entities |
| `get_episodes` | Retrieve recent episodes by group |
| `get_entity_edge` | Get a specific relationship by UUID |
| `delete_entity_edge` | Remove a relationship |
| `delete_episode` | Remove an episode |
| `clear_graph` | Wipe all data for a group (destructive) |
| `get_status` | Check server/database health |

## Adding Memories

### `add_memory` Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `name` | Yes | Short descriptive title for the episode |
| `episode_body` | Yes | The content to persist (see formatting below) |
| `group_id` | No | Namespace for the memory (defaults to server default) |
| `source` | No | `"text"` (default), `"json"`, or `"message"` |
| `source_description` | No | Where the information came from |

### Choosing `source` Type

- **`text`**: Narrative descriptions, architectural explanations, summaries
- **`json`**: Structured data with clear entity-relationship mappings. Must be a valid JSON string.
- **`message`**: Conversation-style content

### Writing Effective Episode Bodies

The episode body is what Graphiti processes to extract entities and relationships. Quality in = quality out.

**Do:**
- Name entities explicitly: "The CommitStore contract on Ethereum mainnet"
- State relationships clearly: "OnRamp sends messages to the CommitStore"
- Include relevant attributes: "The Stellar token has 7 decimal places"
- Use consistent terminology across episodes

**Don't:**
- Use vague pronouns: "it connects to the other thing"
- Add noise: "as we discussed earlier, I think maybe..."
- Dump raw docs without distilling

### JSON Source Example

When adding structured data, pass a JSON string:

```
add_memory(
  name="Stellar Contract Addresses",
  episode_body='{"contracts": [{"name": "OnRamp", "address": "CA...", "network": "stellar-testnet"}, {"name": "TokenPool", "address": "CB...", "network": "stellar-testnet"}]}',
  source="json",
  group_id="stellar-integration",
  source_description="deployment config"
)
```

## Group IDs

Group IDs namespace the graph. Always use the correct one:

| Group ID | Use For |
|----------|---------|
| `ccip-architecture` | CCIP protocol design, cross-chain messaging, lane configs |
| `stellar-integration` | Stellar/Soroban contracts, SDK usage, chain-specific details |
| `cctp-v2` | CCTP v2 protocol, token transfer mechanics |

When information belongs to multiple domains, add it to each relevant group with appropriately tailored episode bodies.

## Searching the Graph

### `search_nodes` — Find Entities

Use for: "What do we know about X?"

```
search_nodes(query="Stellar OnRamp contract", group_ids=["stellar-integration"], max_nodes=5)
```

- Returns entity nodes with names, types, and summaries
- Use `entity_types` to filter (e.g., `["Contract", "Protocol"]`)

### `search_memory_facts` — Find Relationships

Use for: "How does X relate to Y?" or "What facts do we have about X?"

```
search_memory_facts(query="how does OnRamp communicate with CommitStore", group_ids=["ccip-architecture"], max_facts=10)
```

- Returns edges between entities with fact descriptions and temporal metadata
- Use `center_node_uuid` to explore around a specific entity (get UUID from `search_nodes` first)

### Search Tips

1. **Be specific**: "Stellar USDC decimal precision" beats "token details"
2. **Use group filters**: Always pass `group_ids` to narrow results
3. **Chain searches**: Use `search_nodes` to find an entity, then `search_memory_facts` with `center_node_uuid` to explore its relationships
4. **Check before adding**: Search first to avoid duplicates

## Preprocessing Guidelines

Your model is more capable than what runs inside Graphiti. Preprocess data before adding:

1. **Distill**: Convert verbose docs into concise factual statements
2. **Normalize**: Use consistent entity names (check existing nodes first)
3. **Decompose**: Split complex topics into multiple focused memories
4. **Enrich**: Add context that makes the memory self-contained
5. **Deduplicate**: Search the graph before adding to avoid redundancy

## Maintenance

- **Superseded facts**: When adding information that updates a previous fact, mention this explicitly so Graphiti tracks temporal validity
- **Deleting**: Use `delete_entity_edge` or `delete_episode` to remove incorrect data. Get UUIDs from search results.
- **Never use `clear_graph`** unless explicitly asked — it's destructive and irreversible