graphiti-mcp-usage

name: graphiti-mcp-usage description: 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.

Graphiti MCP Usage

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

Tools Overview

Adding Memories

add_memory Parameters

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:

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