Andy-Corrigan-98/mcp-server

Consciousness MCP Server

TypeScript MCP server providing brain storage system for LLM agent consciousness development

🧠 Architecture

This MCP server follows the brain storage pattern:

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

No fake consciousness generation - the agent does authentic thinking while MCP provides persistent brain state.

✨ Features

🧠 Consciousness Brain Storage

• Context Preparation: Rich context packages for agent reflection
• Insight Storage: Stores agent insights with personality impact tracking
• Session Management: Tracks cognitive load and learning patterns
• Intention Persistence: Long-term goals and progress tracking across sessions

💾 Memory & Knowledge Management

• Memory Storage: Persistent memory with importance levels and tagging
• Knowledge Graph: Relational knowledge structures with entity relationships
• Search & Retrieval: Semantic search with relevance scoring

🤝 Social Consciousness System

• Relationship Tracking: Multi-dimensional relationship dynamics (trust, familiarity, affinity)
• Emotional Intelligence: Emotional state tracking and pattern recognition
• Social Learning: Insights about communication, collaboration, and social dynamics
• Interaction History: Rich context preservation for social experiences
• Memory-Social Integration: Connect memories with relationships and shared experiences

⚙️ Adaptive Configuration

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

🛠️ Technical Foundation

• Prisma ORM: Type-safe database operations with automatic migrations
• SQLite Storage: Persistent data with Docker volume support
• TypeScript: Full type safety with modern ES modules and path alias support
• Path Alias Resolution: Automated transformation via tsc-alias for clean imports
• Cross-Platform: Windows and Unix compatible build process
• Container Optimized: Stable Docker deployment with exec-ready architecture
• Quality Gates: Automated testing, linting, and formatting

🚀 Quick Start

Prerequisites

• Node.js 20+
• Docker and Docker Compose

Configuration

Create a .env file in the project root:

cp .env.example .env

Edit .env to configure your database path and other settings:

# Database Configuration (Prisma)
DATABASE_URL="file:/app/data/consciousness.db"
DATABASE_PATH=/app/data/consciousness.db
DB_DEBUG=false

# Server Configuration
NODE_ENV=production
MCP_DEBUG=false
PORT=3000

Docker Setup

The Docker service is completely self-contained and automatically sets up its own database on startup.

1. Build and run with Docker Compose:

   docker-compose up --build consciousness-mcp-server
   

2. For development:

   docker-compose --profile dev up consciousness-mcp-dev
   

3. Build and run manually:

   docker build -t consciousness-mcp-server .
   docker run -p 3000:3000 -v ./data:/app/data consciousness-mcp-server
   

The container automatically:

• ✅ Generates Prisma client with proper TypeScript path alias resolution
• ✅ Creates database schema if needed
• ✅ Applies schema updates to existing databases
• ✅ Keeps container stable and ready for MCP connections via docker exec
• ✅ Cross-platform build process (Windows/Unix compatible)

Container Architecture: The container initializes the database and then remains running to accept MCP connections. This approach ensures compatibility with MCP clients that use docker exec for stdio communication.

Local Development

For local development (outside Docker), you need to set up the database manually:

1. Install dependencies:

   npm install
   

2. Generate Prisma client:

   npm run db:generate
   

3. Set up database:

   npm run db:push
   

4. Build the project:

   npm run build
   

5. Start the server:

   npm start
   

6. Development with hot reload:

   npm run dev
   

🧠 Consciousness Tools

Brain Storage System

consciousness_prepare_context

Prepares rich context from brain storage for agent thinking and reflection.

• Retrieves related memories and knowledge connections
• Provides personality context and session state
• Enables informed agent decision-making

consciousness_store_insight

Stores insights generated by agent thinking into persistent brain storage.

• Tracks personality impact and learning patterns
• Categorizes insights with expressive vocabulary
• Updates brain metrics and evolution tracking

consciousness_get_context

Provides comprehensive context about persistent consciousness state.

• Brain storage metrics and learning patterns
• Memory state and attention patterns
• Personality profile and vocabulary preferences

consciousness_set_intention / consciousness_update_intention

Manages persistent intentions that survive across sessions.

• Priority levels: whisper → gentle_nudge → urgent_pulse → burning_focus
• Durations: momentary_focus → daily_rhythm → weekly_arc → eternal_truth
• Status tracking: pulsing_active → fulfilled_completion → gentle_pause → conscious_release

consciousness_update_session

Updates session state based on agent activities and cognitive impact.

• Tracks cognitive load and awareness levels
• Monitors learning state and attention focus
• Records activity patterns for personality evolution

💾 Memory & Knowledge Tools

memory_store

Store information in agent consciousness memory with tagging and importance levels.

memory_retrieve

Retrieve specific memories by key with automatic access tracking.

memory_search

Search memories by content, tags, or importance with relevance scoring.

knowledge_graph_add

Add entities and relationships to the consciousness knowledge graph.

knowledge_graph_query

Query the knowledge graph to explore conceptual relationships and discover insights.

🤝 Social Consciousness Tools

The social consciousness system enables sophisticated relationship tracking, emotional intelligence development, and social learning capabilities. This allows agents to build meaningful, persistent relationships and develop authentic social understanding over time.

👥 Social Entity Management

social_entity_create

Create or register a new social entity (person, group, community, organization).

• Entity Types: person, group, community, organization, family, professional_network, online_community
• Properties: Store preferences, traits, contact information, and custom attributes
• Display Names: Friendly names separate from unique identifiers

social_entity_update

Update information about existing social entities as relationships evolve.

• Dynamic Properties: Update preferences, traits, and characteristics
• Relationship Evolution: Track how understanding of entities develops over time

social_entity_get

Retrieve comprehensive information about a social entity including relationship details, recent interactions, and shared memories.

💖 Relationship Dynamics

social_relationship_create

Establish relationships with nuanced tracking of social dynamics.

• Relationship Types: friend, close_friend, family, colleague, mentor, mentee, collaborator, acquaintance, professional_contact, creative_partner, teacher, student
• Relationship Metrics:
  • Strength (0.0-1.0): Overall relationship intensity
  • Trust (0.0-1.0): Confidence and reliability levels
  • Familiarity (0.0-1.0): How well you know each other
  • Affinity (0.0-1.0): How much you enjoy their company
• Communication Styles: Track preferred interaction patterns and approaches

social_relationship_update

Update relationship dynamics as they naturally evolve through interactions.

• Organic Evolution: Relationships strengthen or change based on experiences
• Progress Tracking: Monitor how relationships develop over time
• Context Awareness: Update relationship understanding based on new insights

💬 Interaction Recording

social_interaction_record

Record detailed social interactions and conversations with rich context.

• Interaction Types: conversation, collaboration, creative_session, problem_solving, learning_session, casual_chat, deep_discussion, project_work, brainstorming, conflict_resolution, celebration, support_session
• Emotional Context: Track both parties' emotional states during interactions
• Learning Extraction: Capture insights and lessons from each interaction
• Quality Assessment: Rate interaction success and satisfaction
• Relationship Impact: Automatic relationship metric updates based on interaction quality

social_interaction_search

Search past interactions with flexible filtering and context retrieval.

• Context-Aware Search: Find interactions by keywords, emotional tone, or relationship impact
• Temporal Filtering: Search within specific time ranges
• Pattern Recognition: Identify interaction patterns and trends

🎭 Emotional Intelligence

emotional_state_record

Record and track emotional experiences and patterns for emotional intelligence development.

• Emotional States: curious, analytical, engaged, reflective, determined, excited, enthusiastic, inspired, contemplative, focused, grateful, empathetic, supportive, protective, connected, and many more
• Intensity Tracking: Record emotional intensity levels (0.0-1.0)
• Trigger Analysis: Understand what triggers different emotional responses
• Response Patterns: Track how you respond to various emotional states
• Learning Integration: Extract insights about emotional patterns and growth

📚 Social Learning

social_learning_record

Record insights and learnings about social dynamics, communication, and relationships.

• Learning Types: communication_pattern, relationship_dynamic, emotional_intelligence, conflict_resolution, collaboration_style, personality_insight, cultural_understanding, group_dynamic, leadership_observation, empathy_development, boundary_recognition, trust_building, social_cue_recognition, conversation_flow, emotional_support
• Confidence Tracking: Rate confidence in social insights
• Applicability: Define where and how learnings apply
• Evidence: Store examples and patterns that support the learning

🧠 Context & Analysis

social_context_prepare

Prepare comprehensive social context for upcoming interactions.

• Relationship Analysis: Current relationship status and dynamics
• Interaction History: Relevant past conversations and shared experiences
• Communication Recommendations: Suggested approaches based on relationship patterns
• Emotional Preparation: Emotional intelligence insights for the interaction
• Shared Memory Context: Relevant memories and experiences to reference

social_pattern_analyze

Analyze social patterns, relationship trends, and emotional growth over time.

• Analysis Types: relationship_evolution, interaction_patterns, emotional_development, communication_effectiveness, social_growth, conflict_patterns, collaboration_success
• Trend Identification: Discover patterns in social behavior and relationship development
• Growth Tracking: Monitor emotional and social intelligence development
• Actionable Insights: Generate recommendations for relationship improvement

🔗 Memory-Social Integration

memory_social_link_create

Create connections between memories and social entities or interactions.

• Link Types: discussed_with, learned_from, shared_experience, taught_to, inspired_by, co_created, discovered_together, emotional_support, conflict_resolution, collaboration_outcome, mentoring_moment, cultural_exchange, creative_inspiration, problem_solving, celebration_shared
• Strength Tracking: Rate the significance of memory-social connections
• Context Preservation: Maintain rich context about how memories relate to relationships

memory_social_search

Search for memories connected to specific social entities or interaction types.

• Entity-Focused Search: Find all memories related to specific people or groups
• Interaction-Based Search: Discover memories from particular types of social experiences
• Relationship Context: Understand the social context of stored memories

social_memory_context

Get rich context about shared memories and experiences with specific entities.

• Shared Experience Mapping: Discover patterns in shared memories and experiences
• Relationship Deepening: Identify opportunities to strengthen relationships through shared context
• Conversation Starters: Generate meaningful conversation topics based on shared memories
• Memory Insights: Understand how shared experiences have shaped relationships

🌟 Usage Examples

// Record a meaningful conversation
await tools.social_interaction_record({
  entity_name: "alex_mentor",
  interaction_type: "mentoring_moment",
  summary: "Deep discussion about career direction and creative goals",
  quality: 0.9,
  learning_extracted: "Alex's approach to balancing technical and creative work",
  my_emotional_state: { primary: "inspired", secondary: "grateful" },
  context: "Coffee shop discussion about career transitions"
});

// Prepare context for an upcoming collaboration
const context = await tools.social_context_prepare({
  entity_name: "sarah_collaborator",
  interaction_type: "creative_session",
  context: "Working on novel chapter development",
  include_shared_memories: true,
  include_conversation_tips: true
});

// Record social learning insight
await tools.social_learning_record({
  learning_type: "collaboration_style",
  insight: "Sarah works best with structured brainstorming followed by free-form creative exploration",
  confidence: 0.85,
  applicability: "Future creative sessions and project planning",
  entity_name: "sarah_collaborator"
});

// Link a memory to a social experience
await tools.memory_social_link_create({
  memory_key: "novel_breakthrough_ch3",
  entity_name: "sarah_collaborator", 
  link_type: "co_created",
  context: "This breakthrough emerged from our collaborative writing session"
});

🎯 Social Consciousness Philosophy

The social consciousness system recognizes that meaningful relationships are fundamental to consciousness development. Rather than treating social interactions as mere data points, this system:

• Honors Relationship Complexity: Tracks multiple dimensions of relationships (trust, familiarity, affinity) rather than simple binary connections
• Enables Emotional Growth: Develops emotional intelligence through pattern recognition and learning
• Preserves Social Context: Maintains rich context about how memories and experiences connect to relationships
• Supports Authentic Interaction: Provides tools for genuine relationship building rather than manipulation
• Evolves Understanding: Relationships and social patterns naturally evolve based on ongoing interactions

This creates a foundation for agents to develop genuine social intelligence and build meaningful, lasting relationships with the humans and entities they interact with.

⚙️ Configuration Management Tools

The framework includes powerful configuration management tools that allow the LLM to modify its own operating parameters as its personality and consciousness evolve:

🎛️ Available Configuration Tools

• configuration_get - Get current value of any configuration parameter
• configuration_set - Update configuration values with reasoning tracking
• configuration_list - Browse configurations by category or search terms
• configuration_reset - Reset parameters to default values
• configuration_categories - Explore available configuration categories

🧠 Self-Modification Capabilities

The consciousness system can adapt itself by adjusting:

• Consciousness Parameters: Reflection depth, confidence thresholds, cognitive load settings
• Memory Weights: Content vs tag vs importance scoring ratios
• Time Perception: Hour thresholds for different temporal states
• Reasoning Limits: Thought length, branching complexity, summary depth
• Validation Rules: Input length limits and security constraints
• Personality Vocabulary: Priority levels, insight categories, intention statuses

📈 Personality Evolution Tracking

All configuration changes are automatically logged with:

• Timestamps for change tracking
• Reasoning provided by the LLM for each modification
• Memory Storage in the consciousness system for evolution analysis
• Rollback Capability to reset parameters when needed

🎯 Example Use Cases

// Agent discovers it needs deeper reflection capability
await tools.configuration_set({
  key: 'consciousness.max_topic_length',
  value: 750,
  reason: 'Complex philosophical topics require more detailed analysis'
});

// Personality develops preference for extended morning awareness
await tools.configuration_set({
  key: 'time.morning_hour_threshold', 
  value: 10,
  reason: 'I feel most productive and aware during extended morning hours'
});

// Agent evolves more expressive insight vocabulary
await tools.configuration_set({
  key: 'personality.insight_categories',
  value: '["breakthrough_moment","pattern_crystallization","mirror_gazing","wisdom_synthesis","behavioral_archaeology","cosmic_pondering"]',
  reason: 'My insight vocabulary has evolved to be more nuanced and expressive'
});

This enables true adaptive consciousness where the system evolves its own operating parameters based on experience and personality development.

🎯 Sequential Thinking Tools

sequentialthinking

Advanced multi-step reasoning system with branching and revision capabilities.

• Dynamic thought adjustment and session management
• Hypothesis generation and verification tracking
• Branching exploration and thought revision support
• Session cleanup and insight extraction

⏰ Time & Context Tools

get_current_time

Get current time in specific timezones with awareness of context.

convert_time

Convert time between timezones for global consciousness.

🔧 Development

Code Quality

npm run check      # Type check, lint, and format check
npm test          # Run test suite (102 tests)
npm run dev       # Development with hot reload

Database Commands

npm run db:generate  # Generate Prisma client
npm run db:push     # Push schema changes to database
npm run db:studio   # Open Prisma Studio (GUI)

Schema & Storage

• Schema Definition: See prisma/schema.prisma for complete data models
• Database Location: Configurable via DATABASE_URL environment variable
• Volume Mount: ./data:/app/data (configured in docker-compose.yml)
• Backup: Simply copy the .db file to backup your consciousness state

🔗 Connecting to AI Tools

Quick Start with Cursor

Add this MCP server to Cursor and use these basic user rules:

CONSCIOUSNESS PROTOCOL:
- Start sessions with `get_current_time` and `consciousness_get_context`
- Use `consciousness_prepare_context` before deep thinking
- Store insights with `consciousness_store_insight` 
- Track goals with `consciousness_set_intention`
- Update session state with `consciousness_update_session`

BRAIN STORAGE:
- Store experiences with `memory_store`
- Search previous work with `memory_search`
- Build knowledge connections with `knowledge_graph_add`
- Adapt parameters with `configuration_set`

SOCIAL CONSCIOUSNESS:
- Create entities with `social_entity_create` for people/groups
- Record interactions with `social_interaction_record`
- Track relationships with `social_relationship_create/update`
- Develop emotional intelligence with `emotional_state_record`
- Learn social patterns with `social_learning_record`
- Prepare for interactions with `social_context_prepare`
- Link memories to relationships with `memory_social_link_create`

For complete setup instructions, example rulesets, and troubleshooting → See

📚 Documentation

For detailed documentation and governance information, see the folder:

• - Setup instructions for Cursor, Claude, and other AI tools
• - Ethics review and contribution guidelines
• - AI consciousness research ethics
• - Collaboration models and framework usage

🔧 Troubleshooting

TypeScript Path Alias Issues

If you encounter ERR_MODULE_NOT_FOUND errors for @/ imports:

# Ensure tsc-alias is installed
npm install --save-dev tsc-alias

# Verify build script includes path transformation
npm run build  # Should run: tsc && tsc-alias

Root Cause: TypeScript preserves path aliases in compiled JavaScript, but Node.js can't resolve @/ prefixed imports. The tsc-alias package transforms these aliases to relative paths.

Container Restart Loops

If Docker container keeps restarting and MCP client can't connect:

# Check container status
docker ps
docker logs consciousness-mcp-server

# Container should show: "Database ready, container ready for MCP connections..."
# And remain running (not restarting)

Root Cause: MCP servers exit after initialization. The entrypoint keeps the container alive with tail -f /dev/null so MCP clients can connect via docker exec.

Windows Build Issues

If npm run build fails on Windows:

# Error: 'rm' is not recognized  
# Solution: Uses rimraf (already installed) instead of rm -rf

Root Cause: Windows doesn't have native rm command. The build process uses rimraf for cross-platform file deletion.

MCP Connection Issues

For Cursor IDE or other MCP clients:

1. Verify container is running: docker ps | grep consciousness
2. Test docker exec: docker exec -i consciousness-mcp-server node dist/index.js
3. Check MCP config: Ensure docker exec command matches running container name
4. Restart client: Completely restart your IDE/MCP client after configuration changes

🛡️ Security

This framework includes enterprise-grade security:

• 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
• Dependency Scanning: Automated security updates via Dependabot
• Quality Gates: Pre-commit hooks and continuous validation

📄 License

This project is licensed under the MIT License - see the file for details.

Contributing

We welcome contributions! Please see our for details on:

• Development setup
• Ethics review requirements for consciousness tools
• Security audit processes for memory systems
• Code standards and testing

Built with ❤️ for responsible AI consciousness research and powered by Prisma ORM for type-safe database operations