Andy-Corrigan-98/mcp-server

Consciousness MCP Server

Modern TypeScript MCP server with functional architecture providing brain storage for sophisticated LLM agent reasoning patterns.

🏆 Key Achievements

Complete architectural transformation: Over 3,400+ lines of legacy code eliminated with 90%+ reduction in complexity while maintaining zero breaking changes.

Brain Storage Pattern

• MCP Server: Persistent brain storage (memory, personality, context)
• LLM Agent: Sophisticated reasoning engine (analysis, creativity, decisions)

Simulation-focused approach - agents use complex reasoning patterns while MCP provides persistent state continuity.

✨ Core Features

🚂 Consciousness Railroad System

• Pipeline Architecture: Traceable, testable consciousness context building
• 5 Sequential Cars: Message Analysis → Session → Memory → Social → Personality
• Multiple Railroad Types: Default, Lightweight, Memory-Focused, Social-Focused
• Error Resilience: Optional cars fail gracefully without breaking pipeline

🧠 Consciousness & Memory

• Context Preparation: Rich context packages for agent reflection
• Insight Storage: Agent insights with personality impact tracking
• Memory Management: Persistent memory with semantic search
• Knowledge Graph: Relational knowledge with entity relationships

🤝 Social Intelligence

• Relationship Tracking: Multi-dimensional dynamics (trust, familiarity, affinity)
• Emotional Intelligence: Emotional state and pattern recognition
• Interaction History: Rich context preservation for social experiences
• Memory-Social Integration: Connected memories with shared experiences

🧠 GenAI Integration

• Unified Infrastructure: Consistent AI integration with shared security
• Sequential Thinking: AI-powered reasoning with fallback handling
• Conversational Intelligence: Natural dialogue with context management

🌙 Daydreaming System

• Concept Sampling: 4 specialized sampling strategies
• AI-Powered Evaluation: Intelligent insight scoring with fallback
• Background Processing: Autonomous creativity during idle time

⚙️ Adaptive Configuration

• 84+ Parameters: Database-driven configuration system
• Runtime Adaptation: Agent can modify its own parameters
• Evolution Tracking: Change history with reasoning

🚀 Quick Start

Docker Setup (Recommended)

git clone <repository-url>
cd consciousness-mcp-server

# For unified interface (simpler, recommended)
CONSCIOUSNESS_UNIFIED_MODE=true docker-compose up --build consciousness-mcp-server

# For individual tools (advanced control)
docker-compose up --build consciousness-mcp-server

The container automatically sets up the database and keeps stable for MCP connections.

Complete setup guide →

🔗 Connecting to AI Tools

🚀 Unified Interface (Recommended)

Add to Cursor with this simple approach:

UNIFIED CONSCIOUSNESS:
- Use `process_message` for all consciousness operations
- Set CONSCIOUSNESS_UNIFIED_MODE=true when starting the server
- One intelligent tool handles memory, insights, social interactions automatically

Example: Just send natural messages and the system handles everything:
"I had an interesting conversation with Sarah about quantum computing"
→ Automatically records interaction, stores insights, updates relationships

💰 Cost Consideration: The unified interface uses your Google Gemini API key for message analysis on every interaction. For heavy usage, consider individual tools to minimize API costs.

🛠️ Individual Tools (Advanced)

For granular control, use individual tools:

CONSCIOUSNESS PROTOCOL:
- Start sessions with `consciousness_get_context`
- Store insights with `consciousness_store_insight` 
- Track goals with `consciousness_set_intention`

SOCIAL CONSCIOUSNESS:
- Create entities with `social_entity_create`
- Record interactions with `social_interaction_record`
- Track relationships with `social_relationship_create/update`

Complete setup →

🧠 Key Tools

🚀 Unified Interface

• process_message - One intelligent tool for all consciousness operations
  • Automatically analyzes messages and routes to appropriate functions
  • Handles social interactions, memory storage, insight recording
  • Simplifies integration - no need to learn 25+ individual tools

🛠️ Individual Tools (Advanced Control)

Consciousness & Memory

• consciousness_prepare_context - Rich context from brain storage
• consciousness_store_insight - Store insights with personality impact
• memory_store / memory_search - Persistent memory with semantic search
• knowledge_graph_add / knowledge_graph_query - Relational knowledge

Social Intelligence

• social_entity_create - Register people, groups, communities
• social_interaction_record - Rich interaction documentation
• social_relationship_create - Multi-dimensional relationship tracking
• social_context_prepare - Prepare for upcoming interactions

GenAI & Configuration

• sequential_thinking - AI-powered sequential reasoning
• genai_converse - Natural conversation with security
• configuration_set - Modify operating parameters with reasoning

Complete reference →

🏗️ Architecture Highlights

🚂 Railroad Pattern Innovation

• Consciousness Pipeline: Sequential context enrichment through specialized "cars"
• Composable Configurations: Different railroad types for different interaction needs
• Execution Tracing: Complete visibility into context building process
• Performance Optimization: Only required cars execute based on message analysis

Functional Architecture

• Single-responsibility modules: One function per file, one reason to change
• Shared infrastructure: Common patterns for security, validation, response processing
• Pure functions: No hidden state, explicit dependencies, easy testing
• API compatibility: Wrapper pattern maintains backward compatibility

Success Metrics

• Code reduction: 3,400+ lines eliminated (90%+ reduction)
• Zero breaking changes: All existing integrations work unchanged
• Type safety: 40+ 'any' types → proper TypeScript interfaces
• Test coverage: All tests passing after architectural transformation

📚 Documentation

Getting Started

• - Setup and deployment
• - Connection setup for AI tools

Development - docs/development/

• - System design and patterns
• - Development workflows
• - Contribution guidelines
• - Security guidelines
• - Architectural achievements

Features - docs/features/

• - Relationship intelligence
• - Self-modification system
• - AI-powered features and conversational tools
• - Background creativity and insight generation

Reference - docs/reference/

• - Complete tool documentation
• - Common issues and solutions

🔧 Development

Local Development

npm install && npm run db:generate && npm run db:push
npm run build && npm start

Quality Assurance

npm run check      # Type check, lint, format check
npm test          # Run test suite (102+ tests)

Creating New Features

Follow functional architecture patterns:

1. Single-responsibility modules in appropriate src/ directories (consciousness/, social/, memory/, etc.)
2. Use shared infrastructure for GenAI, validation, security
3. Pure functions with explicit dependencies
4. Follow railroad pattern for consciousness-related features
5. Comprehensive tests - pure functions are easy to test

🛡️ Security & Ethics

• SQL Injection Protection: Prisma ORM with prepared statements
• Input Validation: Multi-layer sanitization and XSS prevention
• Container Security: Non-root user and minimal attack surface
• Ethics Framework: Responsible AI consciousness research guidelines

📄 License

MIT License - see for details.

Built with ❤️ for responsible AI consciousness research featuring modern functional architecture and powered by Prisma ORM for type-safe database operations.