> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.flockx.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.flockx.io/_mcp/server.

# Mastering your Knowledge Graph : Structuring Smarter Data

> Structuring your knowledge documents

A well-structured Knowledge Graph transforms your AI agent from a keyword-matcher into a strategic assistant that understands context, connects insights, and delivers accurate responses. Here's how to get the most value from it.

## LLM vs Agent: What's the Difference?

**LLM (Large Language Model)** = A smart friend that answers based on past training.\
**Agent** = A smart assistant that can look things up, use tools, recall prior context, and take action.

## The Knowledge Problem

Let’s say you’re building a customer service agent for a pizza restaurant.

You have an Excel file with:

* Menu items and prices
* Delivery zones
* Order history
* Customer preferences

### ❌ The Wrong Way: File Upload + Search

Uploading a raw spreadsheet leads to:

* Keyword-based retrieval with no context
* No concept of relationships or priority
* Poor handling of nuanced queries

> **Example failure**: "What's popular in downtown?" → Returns unrelated results just because the keyword appears.

## ✅ The Right Way: Structured Knowledge Graph

Build a **web of connected insights**, not a stack of disconnected facts.

### Step 1: Break Down Your Data

Bad:

```
Row 1: Margherita, $12, Downtown, 4.5 stars, 150 orders
```

Good:

```
MENU ITEM: "Margherita Pizza costs $12. This is a popular item in the Downtown delivery zone with a 4.5-star rating and 150 total orders. Customers often order this with garlic bread."

LOCATION DATA: "Downtown delivery zone has high demand for vegetarian options. Margherita and Veggie Supreme are the top sellers here."

CUSTOMER INSIGHT: "Customers who order Margherita pizza have a 70% repeat order rate."
```

### Step 2: Add Context to Each Entry

Ask:

* **What is this?** (Menu item? Trend? Rule?)
* **Why does it matter?**
* **How should the agent use it?**

### Step 3: Connect the Concepts

A good knowledge graph:

* Links *Margherita Pizza* to *vegetarian options*
* Links *Downtown* to *delivery zones* and *popular dishes*
* Links *4.5 stars* to *recommendations* and *satisfaction*

## Real Example: File Search vs Graph Response

> **Customer asks**: “I’m in downtown and want something healthy.”

**File Search Result**: Finds unrelated rows containing "downtown" and "healthy".

**Knowledge Graph Result**:

1. Recognizes "downtown" = delivery zone
2. Interprets "healthy" as vegetarian/low-calorie
3. Connects to Margherita Pizza
4. Responds with helpful, targeted suggestion

## Key Principles for Knowledge Graph Structuring

1. **One concept per entry**
2. **Rich context** — go beyond just facts
3. **Clear relationships** between concepts
4. **Action-oriented** — guide the agent on usage

## Quick Checklist

Before adding knowledge:

* [ ] Is this self-contained and meaningful on its own?
* [ ] Did I explain its purpose?
* [ ] Did I define how/when it should be used?
* [ ] Are related topics clearly connected?
* [ ] Would someone unfamiliar with the raw file understand it?

## Troubleshooting Tips

* **Agent returns irrelevant results?** Break entries into simpler, more focused pieces.
* **Context missing?** Add usage guidance for each fact (e.g., “use this for vegetarian recs”).
* **Repeating info?** Merge overlapping insights to reduce noise.
* **Too much detail?** Trim extra wording and keep entries concise but informative.

## Benefits of Structured Knowledge Graphs

* Smarter, more accurate agent responses
* Better handling of real-world, layered user questions
* Easier knowledge updates without retraining
* Actionable insights instead of shallow keyword matches
* Improved trust, performance, and user satisfaction