# Cognitive Canvas

A comprehensive Model Context Protocol (MCP) server that transforms AI assistants into research-grade cognitive workspaces with systematic reasoning, evidence-based analysis, persistent memory management, and intelligent knowledge discovery.

## Overview

Cognitive Canvas is an advanced MCP server that provides AI agents with human-like organizational abilities for complex problem-solving. It transforms simple chat assistants into sophisticated research agents capable of systematic thinking, statistical evidence generation, persistent knowledge building, and intelligent knowledge retrieval through semantic search.

**Core Philosophy**: Transform any AI from a basic chat interface into a comprehensive research laboratory with structured reasoning, dependency mapping, statistical validation, context management, and intelligent knowledge discovery capabilities.

### Key Transformations

**From Simple Chat to Research Agent**
- Before: AI gives quick answers and forgets context
- After: AI builds knowledge systematically, maintains research state, develops insights over time, and discovers relevant past solutions

**From Linear Responses to Deep-Thinking Mode**
- Before: AI provides immediate, surface-level responses
- After: AI breaks down complex problems, maps dependencies, validates hypotheses with statistical evidence, and leverages historical knowledge

**From Stateless to Persistent Intelligence**
- Before: Each conversation starts from scratch
- After: AI accumulates knowledge, tracks progress, maintains statistical evidence, builds upon previous work, and discovers relevant past insights through semantic search

**From Opinion-Based to Evidence-Driven**
- Before: AI provides subjective recommendations
- After: AI generates statistical evidence, calculates significance levels, provides data-backed conclusions, and leverages documented solutions from past experiences

**From Isolated Knowledge to Connected Intelligence**
- Before: AI cannot access or learn from previous problem-solving sessions
- After: AI searches through accumulated knowledge using semantic similarity, finds relevant solutions even with partial matches, and builds upon documented experiences

## Example Prompts

Your AI assistant will automatically use these tools when you include the trigger phrase **"use cognitive canvas"** along with specific cognitive requests. To ensure optimal tool usage, always include **"use cognitive canvas"** followed by specific actions like **task management**, **knowledge recording**, **intelligent search**, **statistical analysis**, **relationship mapping**, **structured data**, or **context switching**.

### Strategic Planning and Task Management
"I need to build a machine learning pipeline for customer segmentation. **Use cognitive canvas** to break this down into actionable tasks and track progress systematically."

"Can you **use cognitive canvas** to organize the steps for launching a SaaS product and help me track dependencies between different phases?"

"Let's systematically plan our Q4 product roadmap. **Use cognitive canvas** for task management and dependency visualization."

### Knowledge Management and Experience Tracking
"I just solved a complex database performance issue. **Use cognitive canvas** to record this solution with proper tags so I can find it later when similar problems occur."

"**Use cognitive canvas** to search through my previous experiences with API optimization. I remember solving something similar but need to find the exact solution."

"Record this lesson learned: **Use cognitive canvas** to document that microservice timeouts were caused by connection pool exhaustion, tagged with performance and architecture."

"**Use cognitive canvas** to find all my previous notes about React performance optimization - I need to see what techniques I've documented before."

### Intelligent Knowledge Discovery
"I'm facing a production issue with slow database queries. **Use cognitive canvas** to search through my knowledge base for any previous solutions or similar problems I've encountered."

"**Use cognitive canvas** to search for any documented solutions related to API rate limiting and caching strategies from my past work."

"Before implementing this new feature, **use cognitive canvas** to find relevant insights from previous similar implementations I've documented."

"**Use cognitive canvas** to search across all my conversations for any experience with Kubernetes scaling issues - semantic search should find related solutions even if I use different terminology."

### Research and Evidence-Based Analysis
"I collected survey data on employee satisfaction vs productivity. **Use cognitive canvas** to analyze with statistical evidence - are these factors significantly related?"

"Help me analyze this A/B test data. **Use cognitive canvas** to calculate statistical significance and effect size of our new feature."

"I have customer feedback data across different age groups and product preferences. **Use cognitive canvas** for systematic statistical analysis and pattern detection."

### Data-Driven Decision Making
"We tested three teaching methods with student performance data. **Use cognitive canvas** to generate statistical evidence and determine which approach works best."

"I need comprehensive analysis of our user engagement metrics. **Use cognitive canvas** to calculate confidence intervals and significance levels."

"Does our new onboarding process significantly improve user retention rates? **Use cognitive canvas** for evidence-based statistical conclusions."

### Complex Problem Mapping and Visualization
"**Use cognitive canvas** to map the relationships between our microservices architecture. I need to visualize dependencies and potential bottlenecks."

"Help me organize our technical debt reduction strategy. **Use cognitive canvas** for relationship mapping and decision tree visualization."

"**Use cognitive canvas** to create a systematic diagram showing how our marketing funnel stages connect and influence each other."

### Context Management and Multi-Topic Reasoning
"I'm working on database optimization but need to switch topics to handle a production incident. **Use cognitive canvas** to preserve context and manage topic switching."

"**Use cognitive canvas** to track multiple conversation threads - I want to discuss API design while keeping my ML model training discussion accessible."

"**Use cognitive canvas** to organize my research topics into manageable branches so I can seamlessly switch between different projects."

### Structured Knowledge Building
"**Use cognitive canvas** to transform this information into an organized comparison table of cloud providers with automatic progress tracking."

"Help me structure my market research findings. **Use cognitive canvas** to create categorized lists with completion metrics and voting tables."

"**Use cognitive canvas** to build a comprehensive table tracking our experiment results with automatic statistical summaries."

### Comprehensive Project Analysis
"Systematic project review needed: **Use cognitive canvas** to analyze our development workflow, track task completion, map dependencies, and provide statistical insights on team performance."

"**Use cognitive canvas** for deep organizational analysis: Break down our customer onboarding process, create relationship maps, track success metrics, and generate evidence-based improvement recommendations."

"**Use cognitive canvas** for full cognitive workspace approach: Help me plan, execute, and analyze our product launch strategy with integrated task management, dependency mapping, and statistical validation."

### Academic and Research Excellence
"**Use cognitive canvas** for research-grade analysis of my thesis data: systematic breakdown, statistical evidence generation, relationship mapping, and comprehensive reporting."

"PhD-level systematic thinking needed for my literature review. **Use cognitive canvas** to organize findings, track research progress, map concept relationships, and validate hypotheses statistically."

"**Use cognitive canvas** for evidence-driven research planning: Structure my experiment design, track methodology steps, analyze results with statistical rigor, and organize findings systematically."

## Key Features

### Intelligent Knowledge Management and Experience Tracking
- Record solutions, problems, experiences, and insights with automatic title generation
- Intelligent semantic search using TF-IDF vectorization for finding relevant knowledge
- Score-based relevance filtering (threshold ≥ 0.1) ensures quality search results
- Combined search that boosts documents with matching tags for enhanced relevance
- Cross-conversation search capabilities for global knowledge retrieval
- Support for multiple note types: problems, solutions, experiences, progress, general
- Update effectiveness scores for solution tracking and continuous improvement
- Metadata support for rich context and advanced filtering capabilities

### Task Management and Action Planning
- Break down complex problems into actionable tasks with batch operations
- Track progress with status tracking (pending, in_progress, completed, blocked)
- Add, update, delete, and organize tasks efficiently
- List and retrieve specific tasks for project management

### Conversation Context Management
- Create conversation branches for handling interruptions and topic switches
- Pause current discussions and seamlessly switch to new topics
- Resume previous conversations with full context restoration
- Search and visualize conversation trees with bookmark functionality
- Support for nested drilling and parallel topic switching

### Dependency and Relationship Mapping
- Create visual diagrams of task dependencies and relationships
- Support for multiple diagram types: flowcharts, sequence diagrams, mindmaps, org charts, and trees
- Batch operations for adding nodes and edges efficiently
- Generate both structured relationship tables and readable text-based graphs
- Visualize system architecture and process flows

### Structured Knowledge Building
- Transform unstructured information into organized tables and lists
- Support for various template types: simple tables, task lists, checklists, numbered/bulleted lists, voting tables, progress tables
- Batch operations for adding and updating data efficiently
- Automatic metrics calculation (completion rates, voting distributions, progress tracking)
- JSON and Markdown export capabilities for structured presentation

### Statistical Analysis and Evidence Generation
- Automated statistical analysis and comprehensive data exploration
- Auto-detects appropriate statistical methods (t-tests, ANOVA, correlation analysis, chi-square tests) based on data structure
- Supports both numerical data analysis (descriptive statistics, hypothesis testing) and categorical data analysis (frequency distributions, chi-square independence tests)
- Advanced features: paired comparisons, group comparisons, correlation analysis, chi-square tests for categorical relationships
- Comprehensive statistical reporting with p-values, effect sizes (Cohen's d, Cramér's V), confidence intervals, and significance testing
- Batch analysis capabilities for processing multiple statistical questions efficiently
- Multiple output formats: business summaries, academic reports, comprehensive analysis with statistical interpretations

## Package Information

**PyPI Package**: [cognitive-canvas-mcp](https://pypi.org/project/cognitive-canvas-mcp/)

```bash
pip install cognitive-canvas-mcp
```

Built on the FastMCP framework with modular design, conversation scoping, and full type safety.

## Installation and Getting Started

### Prerequisites
- Python 3.7+
- MCP-compatible AI system (Claude Desktop, VS Code Copilot, or other MCP Hosts)

### Quick Installation

#### Install from PyPI (Recommended)

```bash
pip install cognitive-canvas-mcp
```

#### Development Installation

1. Clone the repository:
```bash
git clone https://github.com/OsmondJiang/Cognitive-Canvas.git
cd Cognitive-Canvas
```

2. Install dependencies:
```bash
pip install -r requirements.txt
```

3. Run the MCP server:
```bash
python cognitive_canvas_server.py
```

### MCP Host Configuration

**Standard Configuration** (works for Claude Desktop, Continue.dev, Cline, Zed Editor, and most MCP clients):

```json
{
  "mcpServers": {
    "cognitive-canvas": {
      "command": "cognitive-canvas-mcp"
    }
  }
}
```

**Alternative Configuration** (if "command not recognized" error occurs):

```json
{
  "mcpServers": {
    "cognitive-canvas": {
      "command": "python",
      "args": ["-m", "cognitive_canvas_server"]
    }
  }
}
```

**Development Setup** (for local development):

```json
{
  "mcpServers": {
    "cognitive-canvas": {
      "command": "python",
      "args": ["path/to/Cognitive-Canvas/cognitive_canvas_server.py"]
    }
  }
}
```

**Configuration Files**:
- **Claude Desktop**: `claude_desktop_config.json`
- **Continue.dev**: Continue.dev config file
- **Cline**: Cline settings
- **Zed Editor**: Zed MCP configuration
- **VS Code**: VS Code MCP configuration
- **Other MCP Clients**: Follow the standard MCP configuration pattern
```

### Usage Examples

#### Task Management
```python
# Add multiple tasks at once
todo_command("project1", "add-batch", task_list=[
    {"title": "Design database schema", "status": "pending"},
    {"title": "Implement API endpoints", "status": "pending"},
    {"title": "Write unit tests", "status": "pending"}
])

# Update task status
todo_command("project1", "update", task_id=1, status="completed")

# List all tasks
todo_command("project1", "list")
```

#### Diagram Creation
```python
# Create a dependency diagram
relationship_mapper("project1", "create", {
    "diagram_type": "flowchart",
    "title": "Development Workflow"
})

# Add nodes and relationships
relationship_mapper("project1", "add_node", {
    "node_id": "design",
    "label": "Database Design",
    "metadata": {"priority": "high"}
})
```

#### Structured Knowledge
```python
# Create a progress tracking table
table_builder("project1", "create", {
    "structure_id": "progress",
    "template_type": "progress_table",
    "title": "Project Progress"
})

# Add progress entries
table_builder("project1", "add_row", {
    "structure_id": "progress",
    "row_data": {"task": "Database Design", "progress": 80, "status": "In Progress"}
})
```

#### Statistical Evidence Analysis
```python
# Auto-detect analysis type for A/B testing
statistical_analyzer("ab_test", "analyze", 
    data={"control_group": [6.1, 5.8, 6.2], "test_group": [7.8, 8.2, 7.5]}
)

# Compare multiple groups (ANOVA)
statistical_analyzer("teaching_study", "analyze", 
    groups={
        "traditional": [72, 74, 70, 73],
        "interactive": [78, 82, 76, 80], 
        "ai_assisted": [88, 91, 86, 89]
    }
)

# Chi-square test for categorical data analysis
statistical_analyzer("customer_survey", "analyze",
    data={
        "age_group": ["18-25", "26-35", "36-45", "46-55", "18-25", "26-35"],
        "product_preference": ["Electronics", "Books", "Fashion", "Electronics", "Fashion", "Books"]
    },
    analysis_type="chi_square_test"
)
```

## Troubleshooting

### Common Installation Issues

#### Command Not Found Error
If you get "cognitive-canvas-mcp command not found":

1. **Check Python Scripts Path**: Ensure your Python Scripts folder is in PATH
2. **Use Alternative Configuration**:
   ```json
   {
     "mcpServers": {
       "cognitive-canvas": {
         "command": "python",
         "args": ["-m", "cognitive_canvas_server"]
       }
     }
   }
   ```

#### Import Errors
If you encounter import errors:

1. **Verify Installation**: Run `pip list | grep cognitive-canvas`
2. **Reinstall Package**: `pip uninstall cognitive-canvas-mcp && pip install cognitive-canvas-mcp`
3. **Check Python Version**: Ensure Python 3.7+ is installed

#### MCP Server Connection Issues
If the MCP server fails to connect:

1. **Check Configuration File**: Verify JSON syntax in your MCP client config
2. **Test Server Manually**: Run `python cognitive_canvas_server.py` directly
3. **Check Logs**: Look for error messages in your MCP client logs
4. **Verify Dependencies**: Run `pip install -r requirements.txt`

### Performance Issues

#### Memory Usage
If experiencing high memory usage:
- Cognitive Canvas stores data in memory for fast access
- Data is conversation-scoped and automatically cleaned up
- For large datasets, consider breaking analysis into smaller chunks

#### Response Time
If tools respond slowly:
- Statistical analysis can be compute-intensive for large datasets
- Consider using batch operations for multiple analyses
- Complex diagrams with many nodes may take longer to render

### Tool-Specific Issues

#### Statistical Analyzer
- **Error: "Insufficient data"**: Ensure you have enough data points for the chosen analysis
- **Error: "Invalid data format"**: Check that your data is properly formatted (arrays for numerical, proper categories for categorical)
- **Unexpected results**: Verify your data doesn't contain missing values or outliers

#### Relationship Mapper
- **Diagram not rendering**: Check that all referenced nodes exist before adding edges
- **Complex diagrams unclear**: Consider breaking large diagrams into smaller, focused sub-diagrams

#### Task Management
- **Tasks not updating**: Ensure you're using the correct conversation_id and task_id
- **Batch operations failing**: Verify the task list format matches the expected structure

### Getting Help

#### Documentation
- Check the example prompts section for proper usage patterns
- Review the API documentation in the source code
- Look at test files for additional usage examples

#### Community Support
- Create an issue on GitHub: https://github.com/OsmondJiang/Cognitive-Canvas/issues
- Include error messages, configuration details, and reproduction steps
- Check existing issues for similar problems and solutions

#### Development and Contributing

#### Running Tests
```bash
# Run all tests
python tests/run_all_tests.py

# Run specific test file
python -m unittest tests.test_todo_tool

# Run with verbose output
python tests/run_all_tests.py -v
```

#### Code Style
- Follow PEP 8 guidelines
- Use type hints for all function parameters
- Include comprehensive docstrings
- Maintain consistent error handling patterns

#### Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Built with [FastMCP](https://github.com/jlowin/fastmcp) framework
- Inspired by human cognitive processes and knowledge management systems
- Designed for the Model Context Protocol ecosystem

---

**Ready to enhance your AI's cognitive abilities?** Start using Cognitive Canvas today and experience structured, organized, and effective AI reasoning!