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