Skip to content

AI_INTEGRATION_GUIDE.md

Latest commit

 

History

History
450 lines (363 loc) · 13 KB

AI_INTEGRATION_GUIDE.md

File metadata and controls

450 lines (363 loc) · 13 KB

AI Integration Guide for Redstring

Overview

This guide explains how AI models can integrate with Redstring's cognitive knowledge graph system through the Model Context Protocol (MCP). The integration enables AI models to think alongside humans in spatial, networked cognitive environments.

Architecture Overview

Core Components

  1. MCP Provider (src/services/mcpProvider.js)

    • Exposes Redstring's cognitive knowledge graph through standardized MCP tools and resources
    • Handles graph traversal, entity creation, pattern recognition, and abstraction building
    • Manages AI metadata and confidence tracking

  2. MCP Client (src/services/mcpClient.js)

    • Provides high-level cognitive operations for AI models
    • Handles session management and context tracking
    • Implements collaborative reasoning workflows

  3. AI Collaboration Panel (inline in src/Panel.jsx)

    • User interface for human-AI collaboration, rendered as the left panel "AI" tab
    • Real-time chat, operation execution, and insight tracking; styles in src/ai/AICollaborationPanel.css
    • Visual feedback for AI reasoning processes

Integration Points

  • Graph Store: Direct access to Redstring's Zustand store

  • Search-first Orchestration (2025):

    • The user-facing agent resolves graph/concept references via list/search before any create operations.
    • If ambiguity remains, it reprompts for clarification instead of guessing IDs.
    • The daemon exposes HTTP search at /search (fuzzy/regex/scoped) and chat-level search ... handling.

  • Core Data Structures: Integration with Node, Edge, and Graph classes

  • Semantic Web: RDF export capabilities for external AI processing

  • Federation: Connection to external knowledge sources

LLM Provider Support

Cloud Providers

Redstring supports multiple cloud-based LLM providers:

  • OpenRouter - Access to 200+ models from various providers
  • Anthropic - Claude models (Sonnet, Haiku, Opus)
  • OpenAI - GPT models (GPT-4, GPT-3.5)
  • Google - Gemini models
  • Cohere - Command models

Local LLM Providers

Redstring also supports local LLM servers for privacy, offline use, and zero API costs:

  • Ollama - Easy-to-use local LLM runtime (default port: 11434)
  • LM Studio - User-friendly desktop app (default port: 1234)
  • LocalAI - Self-hosted AI inference server (default port: 8080)
  • vLLM - High-performance inference engine (default port: 8000)
  • Custom OpenAI-Compatible Servers - Any server implementing OpenAI API format

All local providers use the OpenAI /v1/chat/completions API format, making them compatible with Redstring's Wizard agent.

Configuration:

  1. Open AI Panel → Click 🔑 icon
  2. Select "💻 Local LLM Server" from provider dropdown
  3. Choose a preset (Ollama, LM Studio, etc.) or configure manually
  4. Enter endpoint URL and model name
  5. Test connection to verify server accessibility
  6. Save configuration

Benefits of Local LLMs:

  • ✅ Complete data privacy (no data leaves your machine)
  • ✅ Works offline (no internet required)
  • ✅ Zero API costs
  • ✅ Lower latency (no network overhead)
  • ✅ No rate limits

See LOCAL_LLM_SETUP.md for detailed setup instructions.

MCP Tools Available

Orchestration Policy

  • Preferred order for create flows:
    1. verify_state, list_available_graphs
    2. search_nodes (and/or HTTP /search when needed)
    3. If no match and user intent is explicit, create_graph / create_node_prototype
    4. create_node_instance in the resolved target graph

Graph Traversal Tools

traverse_semantic_graph

Semantically explore the knowledge graph with similarity-based navigation.

await mcpClient.executeTool('traverse_semantic_graph', {
  start_entity: 'climate_change',
  relationship_types: ['causes', 'affects'],
  semantic_threshold: 0.7,
  max_depth: 3
});

identify_patterns

Find recurring patterns in the knowledge structure.

await mcpClient.executeTool('identify_patterns', {
  pattern_type: 'semantic', // 'structural', 'temporal', 'spatial'
  min_occurrences: 2,
  graph_id: 'main-workspace'
});

Knowledge Construction Tools

create_cognitive_entity

Create new nodes with AI metadata.

await mcpClient.executeTool('create_cognitive_entity', {
  name: 'AI Discovered Concept',
  description: 'Concept identified through pattern analysis',
  graph_id: 'main-workspace',
  observation_metadata: {
    source: 'ai_analysis',
    confidence: 0.85,
    reasoning: 'Identified through semantic clustering'
  }
});

establish_semantic_relation

Create relationships between entities with confidence scoring.

await mcpClient.executeTool('establish_semantic_relation', {
  source_id: 'concept_a',
  target_id: 'concept_b',
  relationship_type: 'influences',
  strength_score: 0.8,
  confidence: 0.75
});

Abstraction Building Tools

build_cognitive_abstraction

Create higher-level conceptual frameworks from patterns.

await mcpClient.executeTool('build_cognitive_abstraction', {
  pattern_ids: ['pattern_1', 'pattern_2'],
  abstraction_name: 'Emergent Principle',
  abstraction_description: 'Higher-level concept derived from pattern analysis',
  confidence_threshold: 0.7
});

MCP Resources Available

Graph Schema

await mcpClient.getResource('graph://schema');
// Returns complete graph schema and ontology

Node Collections

await mcpClient.getResource('graph://nodes/all');
await mcpClient.getResource('graph://nodes/concept');
// Returns nodes filtered by type

Spatial Context

await mcpClient.getResource('spatial://position/node_id');
// Returns spatial positioning information

Cognitive Context

await mcpClient.getResource('cognitive://context/session_id');
// Returns current AI reasoning context

High-Level Cognitive Operations

Knowledge Exploration

const results = await mcpClient.exploreKnowledge('climate_change', {
  relationshipTypes: ['causes', 'affects'],
  semanticThreshold: 0.7,
  maxDepth: 3,
  includePatterns: true
});

Concept Mapping

const conceptMap = await mcpClient.createConceptMap('sustainability', [
  { name: 'Renewable Energy', description: 'Clean energy sources' },
  { name: 'Carbon Pricing', description: 'Economic incentives' }
], {
  autoConnect: true,
  confidenceThreshold: 0.7
});

Literature Analysis

const analysis = await mcpClient.analyzeLiterature('climate_economics', [
  'paper1.pdf', 'paper2.pdf'
], {
  analysisDepth: 'detailed',
  includeConceptMapping: true,
  generateHypotheses: true
});

Collaborative Reasoning

const collaboration = await mcpClient.collaborativeReasoning(
  'How do economic incentives affect climate policy adoption?',
  {
    reasoningMode: 'iterative',
    maxIterations: 3,
    confidenceThreshold: 0.8
  }
);

Spatial-Semantic Reasoning

const spatialAnalysis = await mcpClient.spatialSemanticReasoning(
  'Analyze spatial clustering of related concepts',
  {
    includeSpatialPatterns: true,
    includeSemanticPatterns: true,
    spatialThreshold: 100
  }
);

Recursive Exploration

const exploration = await mcpClient.recursiveExploration('sustainability', {
  maxDepth: 5,
  depthControl: 'adaptive',
  relevanceThreshold: 0.6,
  includeAbstractions: true
});

AI Metadata Tracking

Entity Metadata

{
  ai_metadata: {
    created_by: 'mcp_ai',
    observation_metadata: {
      source: 'pattern_analysis',
      confidence: 0.85,
      reasoning: 'Identified through semantic clustering'
    },
    created_at: '2025-01-01T12:00:00Z'
  }
}

Relationship Metadata

{
  ai_metadata: {
    created_by: 'mcp_ai',
    strength_score: 0.8,
    confidence: 0.75,
    metadata: {
      evidence_sources: ['paper1', 'paper2'],
      reasoning_method: 'semantic_similarity'
    },
    created_at: '2025-01-01T12:00:00Z'
  }
}

User Interface Integration

Keyboard Shortcuts

  • B: Toggle AI Collaboration Panel
  • Ctrl/Cmd + B: Alternative toggle

Panel Modes

  1. Chat Mode: Natural language interaction with AI
  2. Operations Mode: Direct access to AI tools
  3. Insights Mode: View AI-generated insights

Real-time Features

  • Live typing indicators
  • Session persistence
  • Collaboration history
  • Confidence scoring display

Implementation Examples

Example 1: AI-Assisted Research

// Initialize AI collaboration
const ai = await mcpClient.initialize();

// Explore research topic
const exploration = await ai.exploreKnowledge('machine_learning');

// Create concept map from findings
const conceptMap = await ai.createConceptMap('ml_research', 
  exploration.insights.map(insight => ({
    name: insight.concept,
    description: insight.description
  }))
);

// Generate hypotheses
const hypotheses = await ai.analyzeLiterature('machine_learning', [], {
  generateHypotheses: true
});

Example 2: Collaborative Problem Solving

// Start collaborative reasoning session
const collaboration = await ai.collaborativeReasoning(
  'How can we improve renewable energy adoption?',
  {
    reasoningMode: 'iterative',
    maxIterations: 5
  }
);

// Extract key insights
const insights = collaboration.finalInsights;
const recommendations = collaboration.recommendations;

Example 3: Pattern Recognition

// Identify patterns in knowledge graph
const patterns = await ai.executeTool('identify_patterns', {
  pattern_type: 'semantic',
  min_occurrences: 3
});

// Build abstractions from patterns
const abstractions = await ai.buildAbstractions(
  patterns.result.patterns.map(p => p.id),
  {
    abstractionName: 'Emergent Principles',
    abstractionDescription: 'Higher-level concepts from pattern analysis'
  }
);

Best Practices

1. Confidence Management

  • Always track confidence levels for AI-generated content
  • Use confidence thresholds to filter low-quality insights
  • Provide confidence scores in user interface

2. Metadata Tracking

  • Maintain comprehensive metadata for all AI operations
  • Track reasoning chains and evidence sources
  • Enable audit trails for AI decisions

3. Human Oversight

  • Require human approval for significant graph modifications
  • Provide clear visual indicators for AI-generated content
  • Enable easy reversal of AI changes

4. Performance Optimization

  • Use semantic caching for repeated queries
  • Implement progressive loading for large graphs
  • Optimize pattern recognition algorithms

Security Considerations

1. Input Validation

  • Validate all AI inputs before processing
  • Sanitize user queries to prevent injection attacks
  • Implement rate limiting for AI operations

2. Access Control

  • Implement role-based access for AI capabilities
  • Require authentication for sensitive operations
  • Log all AI interactions for audit purposes

3. Data Privacy

  • Ensure AI metadata doesn't contain sensitive information
  • Implement data anonymization where appropriate
  • Comply with relevant privacy regulations

Future Enhancements

Planned Features

  1. Multi-Agent Collaboration: Support for multiple AI agents working together
  2. Temporal Reasoning: Advanced time-based pattern analysis
  3. Cross-Domain Federation: Integration with external knowledge bases
  4. Visual AI: AI agents that can understand and manipulate visual elements
  5. Learning Systems: AI agents that improve through interaction

Research Directions

  1. Cognitive Architecture: Advanced reasoning frameworks
  2. Semantic Embeddings: Improved similarity calculations
  3. Federated Learning: Distributed AI training across knowledge graphs
  4. Quantum Cognition: Quantum-inspired reasoning algorithms

Troubleshooting

Common Issues

  1. Connection Failures

    • Check MCP server initialization
    • Verify session state
    • Ensure proper error handling

  2. Performance Issues

    • Monitor graph size and complexity
    • Implement caching strategies
    • Optimize query patterns

  3. Memory Management

    • Clean up unused sessions
    • Implement garbage collection
    • Monitor memory usage

Debug Tools

  • Enable debug mode for detailed logging
  • Use browser developer tools for performance analysis
  • Monitor network requests for API calls

Conclusion

The AI integration with Redstring represents a significant step toward collaborative human-AI cognition. By providing standardized interfaces through MCP, we enable AI models to think alongside humans in spatial, networked environments.

This integration opens new possibilities for:

  • Collective Intelligence: Human-AI collaboration on complex problems
  • Knowledge Discovery: Automated pattern recognition and insight generation
  • Cognitive Amplification: AI augmentation of human reasoning capabilities
  • Emergent Understanding: New insights arising from human-AI interaction

The system is designed to be extensible, secure, and user-friendly, providing a foundation for the future of collaborative cognitive systems.