diff --git a/documentation/docs/mcp/cognee-mcp.md b/documentation/docs/mcp/cognee-mcp.md new file mode 100644 index 00000000..0ddb6a1b --- /dev/null +++ b/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: +EMBEDDING_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`. +::: + + + + +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 +``` + + + + +## 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 + +
+ Tool Calls + + ─── 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 + +
+ +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. + +::: diff --git a/documentation/docs/tutorials/advanced-cognee-usage.md b/documentation/docs/tutorials/advanced-cognee-usage.md new file mode 100644 index 00000000..34fc42a2 --- /dev/null +++ b/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 + + + + +### 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 +``` + + + + +### 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 +``` + + + + +### 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.