Tutorial : cognee-mcp (#3025)

Co-authored-by: kevco <kevin.cojean@agysoft.fr>
Co-authored-by: Rizel Scarlett <rizel@squareup.com>

documentation/docs/mcp/cognee-mcp.md

@@ -0,0 +1,259 @@
+---
+title: Cognee Extension
+description: Add Cognee MCP Server as a Goose Extension
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CLIExtensionInstructions from '@site/src/components/CLIExtensionInstructions';
+
+This tutorial covers how to add the [Cognee MCP Server](https://github.com/topoteretes/cognee) as a Goose extension to enable knowledge graph memory capabilities, connecting to over 30 data sources for enhanced context and retrieval.
+
+:::tip TLDR
+**Command**
+```sh
+uv --directory /path/to/cognee-mcp run python src/server.py
+```
+**Environment Variables**
+```
+LLM_API_KEY: <YOUR_OPENAI_API_KEY>
+EMBEDDING_API_KEY: <YOUR_OPENAI_API_KEY>
+```
+:::
+
+## Configuration
+
+:::info
+Note that you'll need [uv](https://docs.astral.sh/uv/#installation) installed on your system to run this command, as it uses `uv`.
+:::
+
+<Tabs groupId="interface">
+  <TabItem value="cli" label="Goose CLI" default>
+
+1. First, install Cognee:
+```bash
+# Clone and install Cognee
+git clone https://github.com/topoteretes/cognee
+cd cognee-mcp
+uv sync --dev --all-extras --reinstall
+
+# On Linux, install additional dependencies
+sudo apt install -y libpq-dev python3-dev
+```
+
+2. Run the `configure` command:
+```sh
+goose configure
+```
+
+3. Choose to add a `Command-line Extension`
+```sh
+  ┌   goose-configure 
+  │
+  ◇  What would you like to configure?
+  │  Add Extension (Connect to a new extension) 
+  │
+  ◆  What type of extension would you like to add?
+  │  ○ Built-in Extension 
+  // highlight-start    
+  │  ● Command-line Extension (Run a local command or script)
+  // highlight-end    
+  │  ○ Remote Extension 
+  └ 
+```
+
+4. Give your extension a name
+```sh
+  ┌   goose-configure 
+  │
+  ◇  What would you like to configure?
+  │  Add Extension (Connect to a new extension) 
+  │
+  ◇  What type of extension would you like to add?
+  │  Command-line Extension 
+  │
+  // highlight-start
+  ◆  What would you like to call this extension?
+  │  Cognee
+  // highlight-end
+  └ 
+```
+
+5. Enter the command
+```sh
+  ┌   goose-configure 
+  │
+  ◇  What would you like to configure?
+  │  Add Extension (Connect to a new extension) 
+  │
+  ◇  What type of extension would you like to add?
+  │  Command-line Extension 
+  │
+  ◇  What would you like to call this extension?
+  │  Cognee
+  │
+  // highlight-start
+  ◆  What command should be run?
+  │  uv --directory /path/to/cognee-mcp run python src/server.py
+  // highlight-end
+  └ 
+```  
+
+6. Enter the number of seconds Goose should wait for actions to complete before timing out. Default is 300s
+  ```sh
+  ┌   goose-configure 
+  │
+  ◇  What would you like to configure?
+  │  Add Extension (Connect to a new extension) 
+  │
+  ◇  What type of extension would you like to add?
+  │  Command-line Extension 
+  │
+  ◇  What would you like to call this extension?
+  │  Cognee
+  │
+  ◇  What command should be run?
+  │  uv --directory /path/to/cognee-mcp run python src/server.py
+  │
+  // highlight-start
+  ◆  Please set the timeout for this tool (in secs):
+  │  300
+  // highlight-end
+  │
+  └ 
+``` 
+
+7. Choose to add a description. If you select "Yes" here, you will be prompted to enter a description for the extension.
+  ```sh
+  ┌   goose-configure 
+  │
+  ◇  What would you like to configure?
+  │  Add Extension (Connect to a new extension) 
+  │
+  ◇  What type of extension would you like to add?
+  │  Command-line Extension 
+  │
+  ◇  What would you like to call this extension?
+  │  Cognee
+  │
+  ◇  What command should be run?
+  │  uv --directory /path/to/cognee-mcp run python src/server.py
+  │
+  ◇  Please set the timeout for this tool (in secs):
+  │  300
+  │
+  // highlight-start
+  ◇  Would you like to add a description?
+  │  No
+  // highlight-end
+  │
+  └ 
+```
+
+8. Add the required environment variables:
+:::info
+You'll need OpenAI API keys for both LLM and embedding models. [Get your API keys here](https://platform.openai.com/api-keys).
+:::
+
+ ```sh
+  ┌   goose-configure 
+  │
+  ◇  What would you like to configure?
+  │  Add Extension (Connect to a new extension) 
+  │
+  ◇  What type of extension would you like to add?
+  │  Command-line Extension 
+  │
+  ◇  What would you like to call this extension?
+  │  Cognee
+  │
+  ◇  What command should be run?
+  │  uv --directory /path/to/cognee-mcp run python src/server.py
+  │     
+  ◇  Please set the timeout for this tool (in secs):
+  │  300
+  │
+  ◇  Would you like to add a description?
+  │  No
+  │    
+  // highlight-start
+  ◆  Would you like to add environment variables?
+  │  Yes 
+  │
+  ◇  Environment variable name:
+  │  LLM_API_KEY
+  │
+  ◇  Environment variable value:
+  │  ▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪
+  │
+  ◇  Add another environment variable?
+  │  Yes
+  │
+  ◇  Environment variable name:
+  │  EMBEDDING_API_KEY
+  │
+  ◇  Environment variable value:
+  │  ▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪
+  │
+  ◇  Add another environment variable?
+  │  No 
+  // highlight-end
+  └  Added Cognee extension
+```
+
+  </TabItem>
+</Tabs>
+
+## Example Usage
+
+Cognee provides knowledge graph memory capabilities for Goose, allowing it to remember and connect information across conversations and documents.
+
+:::info LLM
+OpenAI's GPT-4o was used for this task.
+:::
+
+### Goose Prompt
+
+> _Goose, please cognify this information: "I prefer Python for data analysis and use pandas extensively. My current project involves analyzing customer behavior data." Then search for information about my programming preferences._
+
+### Goose Output
+
+:::note CLI
+
+<details>
+    <summary>Tool Calls</summary>
+
+    ─── cognee_cognify | abcdefgh ──────────────────────────
+
+    data: I prefer Python for data analysis and use pandas extensively. My current project involves analyzing customer behavior data.
+
+
+    ─── cognee_search | abcdefgh ──────────────────────────
+
+    search_query: programming preferences Python data analysis
+
+    search_type: GRAPH_COMPLETION
+
+</details>
+
+I'll help you store that information in the knowledge graph and then search for your programming preferences.
+
+First, let me cognify the information about your preferences:
+
+**Cognify Status:**
+Background process launched due to MCP timeout limitations. The information about your Python and pandas preferences for data analysis has been added to the knowledge graph.
+
+Now let me search for information about your programming preferences:
+
+**Search Results:**
+Based on the knowledge graph, I found information about your programming preferences:
+
+- **Language Preference**: You prefer Python for data analysis
+- **Key Libraries**: You use pandas extensively for data manipulation
+- **Current Focus**: Your current project involves analyzing customer behavior data
+- **Domain**: Data science and analytics workflows
+- **Technical Stack**: Python + pandas for data analysis tasks
+
+The knowledge graph has successfully stored and can now retrieve your programming preferences and project context for future conversations.
+
+:::

documentation/docs/tutorials/advanced-cognee-usage.md

@@ -0,0 +1,303 @@
+---
+title: Advanced Cognee Usage with Goose
+description: Advanced patterns for using Cognee knowledge graph with Goose for enhanced memory and automation
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Advanced Cognee Usage with Goose
+
+This tutorial covers advanced usage patterns for the Cognee extension with Goose, including automated memory management, knowledge graph optimization, and various integration strategies.
+
+## Overview
+
+While the basic [Cognee MCP setup](../mcp/cognee-mcp.md) gets you started, this tutorial explores how to make Goose autonomously use the knowledge graph and optimize your workflow.
+
+## Key Concepts
+
+### Knowledge Graph Memory
+Cognee creates a structured knowledge graph that:
+- Interconnects conversations, documents, images, and audio transcriptions
+- Supports over 30 data sources
+- Replaces traditional RAG systems with dynamic relationship mapping
+- Enables complex multi-hop reasoning
+
+### Search Types
+Understanding Cognee's search types is crucial for effective usage:
+
+| Search Type | Use Case | Description |
+|-------------|----------|-------------|
+| `SUMMARIES` | Summary requests | High-level overviews |
+| `INSIGHTS` | Relationship queries | Connections between entities |
+| `CHUNKS` | Specific facts | Raw text segments |
+| `COMPLETION` | Explanations | LLM-generated responses |
+| `GRAPH_COMPLETION` | Complex relations | Multi-hop reasoning |
+| `GRAPH_SUMMARY` | Concise answers | Brief, focused responses |
+| `GRAPH_COMPLETION_COT` | Multi-hop Q&A | Chain-of-thought reasoning |
+| `GRAPH_CONTEXT_EXT` | Context extension | Expanded context |
+| `CODE` | Code examples | Programming-related queries |
+
+## Automation Strategies
+
+<Tabs>
+<TabItem value="method1" label="Method 1 (Slow)" default>
+
+### Instruction Files
+
+Use instruction files for consistent behavior across sessions. This method uses fewer tokens but has slower startup.
+
+Create `~/.config/goose/cognee-instructions.md`:
+
+```markdown
+You are an LLM agent with access to a Cognee knowledge graph for memory.
+
+**IMPORTANT RULES:**
+- Never call the `prune` command
+- Always search memory before responding to user queries
+- Automatically cognify new information you learn about the user
+
+**Memory Workflow:**
+1. **Before each response**: Search the knowledge graph
+   - Map user request to appropriate search type:
+     - Summary → SUMMARIES
+     - Relationships → INSIGHTS  
+     - Specific facts → CHUNKS
+     - Explanations → COMPLETION
+     - Complex relations → GRAPH_COMPLETION
+     - Code examples → CODE
+   
+2. **Search command**:
+   ```text
+   cognee-mcp__search(\{
+     search_query: "user prompt",
+     search_type: "mapped type"
+   \})
+   ```
+
+3. **Incorporate results** into your response
+
+**Memory Updates:**
+- When you learn new facts, preferences, or relationships about the user
+- Call: `cognee-mcp__cognify(\{ data: "information" \})`
+- Monitor with: `cognee-mcp__cognify_status()`
+
+**Code Analysis:**
+- When asked to analyze code repositories
+- Use: `cognee-mcp__codify(\{ repo_path: "path" \})`
+- Only process files returned by `rg --files`
+```
+
+Start Goose with instructions:
+```bash
+goose run -i ~/.config/goose/cognee-instructions.md -s
+```
+
+</TabItem>
+<TabItem value="method2" label="Method 2">
+
+### Goosehints File
+
+For faster startup with higher token usage, add to your `.goosehints` file:
+
+```text
+COGNEE_MEMORY_SYSTEM:
+You have access to a Cognee knowledge graph for persistent memory.
+
+MEMORY_RETRIEVAL_PROTOCOL:
+- Before responding, determine request type and map to search type
+- Search types: SUMMARIES, INSIGHTS, CHUNKS, COMPLETION, GRAPH_COMPLETION, CODE
+- Always call: cognee-mcp__search with search_query and search_type parameters
+- Incorporate memory results into responses
+
+MEMORY_STORAGE_PROTOCOL:
+- Auto-cognify new user facts, preferences, relationships
+- Call: cognee-mcp__cognify with data parameter
+- Never use prune command
+
+CODE_ANALYSIS_PROTOCOL:
+- For repositories: cognee-mcp__codify with repo_path parameter
+- Only process files from rg --files output
+```
+
+</TabItem>
+</Tabs>
+
+### Strategy 3: Memory MCP Integration
+
+Combine with the [Memory MCP extension](../mcp/memory-mcp.md) for hybrid approach:
+
+1. Store Cognee usage patterns as memories
+2. Use Memory MCP to trigger Cognee searches
+3. Lower token usage than goosehints
+4. More reliable than pure instruction files
+
+## Advanced Workflows
+
+### Developer Workflow
+
+For software development projects:
+
+```bash
+# Start Goose with Cognee
+goose session
+
+# In Goose, analyze your codebase
+> Goose, please codify this repository and then help me understand the architecture
+```
+
+Goose will:
+1. Run `cognee-mcp__codify` on your repository
+2. Build a code knowledge graph
+3. Answer architecture questions using the graph
+
+### Research Workflow
+
+For research and documentation:
+
+```bash
+# Cognify research documents
+> Goose, please cognify the contents of these research papers: paper1.pdf, paper2.pdf, paper3.pdf
+
+# Later, query relationships
+> What are the connections between the methodologies in these papers?
+```
+
+### Personal Assistant Workflow
+
+For personal productivity:
+
+```bash
+# Store preferences
+> Remember that I prefer morning meetings, work best with 2-hour focused blocks, and need 15-minute breaks between calls
+
+# Query later
+> Based on my preferences, how should I structure tomorrow's schedule?
+```
+
+## Performance Optimization
+
+### Server Configuration
+
+For optimal performance, run Cognee as a separate server:
+
+```bash
+# Create optimized startup script
+cat > start-cognee-optimized.sh << 'EOF'
+#!/bin/bash
+set -e
+
+# Performance settings
+export DEBUG=false
+export LOG_LEVEL=WARNING
+export RATE_LIMIT_INTERVAL=30
+
+# Model configuration
+export LLM_API_KEY=${OPENAI_API_KEY}
+export LLM_MODEL=openai/gpt-4o-mini  # Faster, cheaper model
+export EMBEDDING_API_KEY=${OPENAI_API_KEY}
+export EMBEDDING_MODEL=openai/text-embedding-3-small  # Faster embedding
+
+# Server settings
+export HOST=0.0.0.0
+export PORT=8000
+
+cd /path/to/cognee-mcp
+uv run python src/server.py --transport sse
+EOF
+
+chmod +x start-cognee-optimized.sh
+```
+
+### Memory Management
+
+Monitor and manage your knowledge graph:
+
+```bash
+# Check status
+> Goose, what's the status of the cognify pipeline?
+
+# Selective pruning (if needed)
+> Goose, can you help me identify outdated information in the knowledge graph?
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Slow startup**: Use Method 2 (separate server) configuration
+2. **Memory not persisting**: Check file permissions and paths
+3. **Search returning empty results**: Ensure data was properly cognified
+4. **High token usage**: Use instruction files instead of goosehints
+
+### Debug Commands
+
+```bash
+# Check Cognee logs
+tail -f ~/.local/share/cognee/logs/cognee.log
+
+# Test server connection
+curl http://localhost:8000/health
+
+# Verify knowledge graph status
+# In Goose session:
+> Goose, run cognify_status and codify_status
+```
+
+## Best Practices
+
+### Data Organization
+
+1. **Use nodesets** for organizing different types of information:
+   ```bash
+   # Developer rules
+   > Goose, add these coding standards to the 'developer_rules' nodeset
+   
+   # Project-specific info  
+   > Goose, cognify this project documentation with nodeset 'project_alpha'
+   ```
+
+2. **Regular maintenance**:
+   - Review and update stored information monthly
+   - Remove outdated preferences and facts
+   - Optimize search queries based on usage patterns
+
+### Integration Patterns
+
+1. **Layered approach**: Use both Memory MCP and Cognee for different purposes
+2. **Context switching**: Different instruction files for different workflows
+3. **Selective automation**: Not every interaction needs knowledge graph queries
+
+## Examples
+
+### Code Review Assistant
+
+```bash
+# Setup
+> Goose, codify this repository and remember that I prefer: functional programming patterns, comprehensive tests, and clear documentation
+
+# Usage
+> Review this pull request and check it against my coding preferences
+```
+
+### Meeting Assistant
+
+```bash
+# Before meeting
+> Goose, cognify the agenda and participant backgrounds from these documents
+
+# During/after meeting
+> Based on the knowledge graph, what are the key action items and how do they relate to our previous discussions?
+```
+
+### Research Assistant
+
+```bash
+# Literature review
+> Goose, cognify these 10 research papers and create a knowledge graph of the relationships between their methodologies
+
+# Synthesis
+> What are the emerging patterns in the research and what gaps exist?
+```
+
+This advanced usage guide should help you maximize the potential of Cognee with Goose for sophisticated knowledge management and automation workflows.