Which integrations are available for this server?

Built on [Node.js](/mcp/servers/integrations/node-dot-js) runtime, providing cognitive tools for AI systems including thinking modes, memory management, and reasoning analysis Implemented in [TypeScript](/mcp/servers/integrations/typescript) for type-safe cognitive processing, offering structured thinking tools and memory systems for AI applications

ThoughtMCP Cognitive Architecture v0.5.0

TypeScript Node.js PostgreSQL License

Production-Ready AI Cognitive Architecture with Human-Like Memory and Reasoning

ThoughtMCP v0.5.0 is a complete rebuild featuring Hierarchical Memory Decomposition (HMD), persistent PostgreSQL storage, parallel reasoning streams, dynamic framework selection, and metacognitive monitoring. Built for production with 95%+ test coverage and sub-200ms retrieval performance.

✅ Status: Production Ready - Complete PostgreSQL-based architecture with advanced cognitive capabilities

What's New in v0.5.0?

ThoughtMCP v0.5.0 is a complete architectural rebuild with production-grade capabilities:

🧠 Hierarchical Memory Decomposition (HMD)

Five-Sector Embeddings: Episodic, Semantic, Procedural, Emotional, and Reflective memory types
Waypoint Graph System: Sparse graph with 1-3 connections per memory for efficient traversal
Composite Scoring: 0.6×similarity + 0.2×salience + 0.1×recency + 0.1×link_weight
Temporal Decay: Exponential forgetting with automatic reinforcement on access
PostgreSQL Persistence: Production-grade storage with pgvector for vector operations

⚡ Performance Targets

Sub-200ms Retrieval: p50 <100ms, p95 <200ms, p99 <500ms at 100k memories
Fast Embedding: <500ms for all five sectors
Parallel Reasoning: <30s total, <10s per stream
Efficient Operations: <100ms confidence assessment, <15% bias detection overhead

🔀 Parallel Reasoning Streams

Four Concurrent Streams: Analytical, Creative, Critical, and Synthetic reasoning
Real-Time Coordination: Synchronization at 25%, 50%, 75% completion
Conflict Preservation: Maintains diverse perspectives in synthesis
Low Overhead: <10% coordination cost

🎯 Dynamic Framework Selection

Eight Frameworks: Scientific Method, Design Thinking, Systems Thinking, Critical Thinking, Creative Problem Solving, Root Cause Analysis, First Principles, Scenario Planning
Auto-Selection: >80% accuracy in choosing optimal framework
Hybrid Support: Combines 2-3 frameworks for complex problems
Adaptive Learning: Improves selection over time

🔬 Metacognitive Monitoring

Confidence Calibration: ±10% accuracy between predicted and actual performance
Bias Detection: >70% detection rate for 8 bias types (confirmation, anchoring, availability, etc.)
Emotion Detection: >75% accuracy using Circumplex model (valence, arousal, dominance)
Self-Improvement: 5-10% monthly performance improvement

🏗️ Production Hardening

95%+ Test Coverage: Comprehensive unit, integration, e2e, performance, and accuracy tests
99.9% Uptime: MTTD <5 minutes, MTTR <1 hour
Local Embeddings: Uses local models (Ollama, E5, BGE) for zero API costs
Horizontal Scaling: Supports up to 1M memories per user

Quick Start

Prerequisites

Node.js 18.0+ (LTS recommended)
PostgreSQL 14.0+ with pgvector extension
Docker (optional, for local PostgreSQL)

Installation

# Clone the repository git clone https://github.com/keyurgolani/ThoughtMcp.git cd ThoughtMcp # Install dependencies npm install # Setup environment cp .env.example .env.development # Edit .env.development with your PostgreSQL credentials # Start PostgreSQL with Docker (optional) docker-compose up -d # Initialize database npm run db:setup # Build the project (runs all quality gates automatically) npm run build # This runs: clean → format → audit → lint → typecheck → test → build # Or run quick build (skip validation if already validated) npm run build:quick # Start the MCP server npm start

Development Setup

# Start development server with hot reload npm run dev # Run tests in watch mode npm run test:watch # Full validation (audit, format:check, lint, typecheck, test) npm run validate # Build with all quality gates (recommended before commits) npm run build

Build Process - Quality Gates

The build process automatically enforces all quality standards:

npm run build

Automatic Quality Pipeline:

✅ Clean build artifacts
✅ Auto-format code with Prettier
✅ Security audit (moderate+ vulnerabilities)
✅ Format verification
✅ Lint code quality
✅ Type check TypeScript
✅ Run complete test suite
✅ Generate TypeScript declarations
✅ Create production bundle

Build fails if ANY step fails. Zero tolerance for security vulnerabilities, formatting issues, linting errors, type errors, or test failures.

Docker Deployment

ThoughtMCP uses a unified Docker Compose approach with separate files for development, testing, and production. Docker Compose files are the single source of truth for all container configuration.

Docker Compose Files

File	Purpose	When to Use
`docker-compose.dev.yml`	Development environment	Local development with `npm run dev`
`docker-compose.test.yml`	Test containers	Automated tests or manual test runs
`docker-compose.prod.yml`	Production deployment	Deploying the full MCP server stack

Environment Configuration

All configuration comes from .env files. Copy the template and configure:

# Copy environment template cp .env.example .env # Edit with your settings nano .env

Key variables in .env:

# Development Database DB_HOST=localhost DB_PORT=5432 DB_NAME=thoughtmcp_dev DB_USER=thoughtmcp_dev DB_PASSWORD=dev_password # Ollama OLLAMA_HOST=http://localhost:11434 EMBEDDING_MODEL=nomic-embed-text # Test Configuration (separate ports to avoid conflicts) TEST_DB_PORT=5433 TEST_OLLAMA_PORT=11435 # Container Management AUTO_START_CONTAINERS=true # Auto-start containers for tests KEEP_CONTAINERS_RUNNING=false # Keep containers after tests

Quick Start: Development

# 1. Configure environment cp .env.example .env # 2. Start development containers docker compose -f docker-compose.dev.yml up -d # 3. Wait for health checks docker compose -f docker-compose.dev.yml ps # 4. Pull embedding model (first time only) docker exec thoughtmcp-ollama-dev ollama pull nomic-embed-text # 5. Run the MCP server npm run dev

Quick Start: Testing (Auto Containers)

Tests automatically start and stop containers via the TestContainerManager:

# Automatic container management (recommended) npm test # Or with explicit setting AUTO_START_CONTAINERS=true npm test

For manual container management:

# Start test containers manually docker compose -f docker-compose.test.yml up -d --wait # Run tests without auto-start AUTO_START_CONTAINERS=false npm test # Stop test containers docker compose -f docker-compose.test.yml down

Quick Start: Production

# 1. Configure production environment cp .env.production.example .env.production nano .env.production # Set secure passwords # 2. Build the MCP server npm run build # 3. Start production stack docker compose -f docker-compose.prod.yml up -d # 4. View logs docker compose -f docker-compose.prod.yml logs -f

👉 Complete Docker Deployment Guide

MCP Server Configuration

Configure ThoughtMCP as an MCP server in .kiro/settings/mcp.json. There are two connection methods:

Option 1: Docker Exec (Recommended for Production)

Connect directly to the running Docker container. The container runs in standby mode, waiting for MCP client connections.

# Start the production stack first docker compose -f docker-compose.prod.yml up -d

{ "mcpServers": { "thoughtmcp": { "command": "docker", "args": ["exec", "-i", "thoughtmcp-server", "node", "dist/index.js"], "env": {}, "disabled": false, "autoApprove": [] } } }

Option 2: Local Node Process (Development)

Run the MCP server locally while connecting to Docker services.

# Start dev containers and build docker compose -f docker-compose.dev.yml up -d npm run build

{ "mcpServers": { "thoughtmcp": { "command": "node", "args": ["/absolute/path/to/ThoughtMcp/dist/index.js"], "env": { "DATABASE_URL": "postgresql://user:pass@localhost:5432/thoughtmcp_dev", "EMBEDDING_MODEL": "nomic-embed-text", "EMBEDDING_DIMENSION": "768", "OLLAMA_HOST": "http://localhost:11434", "LOG_LEVEL": "INFO", "NODE_ENV": "development" }, "disabled": false, "autoApprove": [] } } }

Environment Variables (for local node process):

DATABASE_URL - PostgreSQL connection string
EMBEDDING_MODEL - Embedding model (nomic-embed-text, mxbai-embed-large)
EMBEDDING_DIMENSION - Model-specific dimension (768 for nomic-embed-text)
OLLAMA_HOST - Ollama server URL
LOG_LEVEL - Logging level (DEBUG, INFO, WARN, ERROR)
NODE_ENV - Environment (development, production, test)

👉 Complete Configuration Guide

Architecture Overview

Core Components

┌─────────────────────────────────────────────────────────────┐ │ MCP Interface Layer │ │ Comprehensive tools with schemas and validation │ └────────────────────────┬────────────────────────────────────┘ │ ┌────────────────────────▼────────────────────────────────────┐ │ Cognitive Orchestrator │ │ Coordinates all cognitive components and workflow │ └─────┬──────────────┬────────────┬──────────────┬────────────┘ │ │ │ │ ┌─────▼─────┐ ┌─────▼─────┐ ┌───▼────┐ ┌───────▼────────┐ │ Reasoning │ │ Memory │ │ Bias │ │ Metacognition │ │ Engine │ │ System │ │Detector│ │ Monitor │ └─────┬─────┘ └─────┬─────┘ └───┬────┘ └───────┬────────┘ │ │ │ │ │ ┌───────▼────────────▼──────────┐ │ │ │ HMD Memory Layer │ │ │ │ • Five-Sector Embeddings │ │ │ │ • Temporal Decay System │ │ └──────► • Waypoint Graph ◄───┘ │ • Search & Retrieval │ └───────────┬───────────────────┘ │ ┌───────────▼───────────────────┐ │ PostgreSQL Persistence │ │ • pgvector extension │ │ • Connection pooling │ │ • Transaction management │ └───────────────────────────────┘

Key Features

HMD Memory System: Five-sector embeddings with waypoint graph
Parallel Reasoning: Four concurrent streams (Analytical, Creative, Critical, Synthetic)
Framework Selection: Eight systematic thinking frameworks
Metacognition: Confidence calibration, bias detection, emotion analysis
Production Ready: 95%+ test coverage, sub-200ms retrieval, 99.9% uptime

MCP Tools Overview

ThoughtMCP exposes cognitive capabilities through MCP tools:

Category	Tools	Description
Memory	`remember` , `recall` , `update_memory` , `forget` , `search`	Persistent memory with five-sector embeddings
Reasoning	`think` , `analyze` , `ponder` , `breakdown`	Multi-stream reasoning with framework selection
Metacognitive	`assess_confidence` , `detect_bias` , `detect_emotion` , `evaluate`	Self-monitoring and quality assessment

👉 Complete MCP Tools Reference

Documentation

📚 Essential Guides

Guide	Description
User Guide	Getting started and basic usage
API Reference	Complete API documentation
MCP Tools	MCP tool schemas and examples
Architecture	System design and components

🔧 Configuration & Operations

Guide	Description
Environment	Environment variables reference
Database	PostgreSQL setup and schema
Docker Deployment	Docker Compose deployment guide
Deployment	Production deployment guide
Monitoring	Observability and alerting

💻 Development

Guide	Description
Development	Development workflow and setup
Testing	Testing strategies and TDD
Contributing	Contribution guidelines
Build	Build system and optimization

🚀 Quick Links

Quick Start - Get up and running in minutes
Architecture Overview - System architecture diagram
MCP Configuration - Configure as MCP server
Contributing - How to contribute to the project

Why ThoughtMCP v0.5.0?

Production-Grade Architecture

PostgreSQL Persistence: Cross-session memory with pgvector for vector operations
Sub-200ms Retrieval: p50 <100ms, p95 <200ms, p99 <500ms at 100k memories
95%+ Test Coverage: Comprehensive unit, integration, e2e, performance, and accuracy tests
99.9% Uptime: MTTD <5 minutes, MTTR <1 hour with graceful degradation
Local Embeddings: Uses local models (Ollama, E5, BGE) for zero API costs

Advanced Cognitive Capabilities

HMD Memory System: Five-sector embeddings (Episodic, Semantic, Procedural, Emotional, Reflective)
Parallel Reasoning: Four concurrent streams with real-time coordination
Framework Selection: Eight systematic thinking frameworks with >80% selection accuracy
Metacognition: Confidence calibration (±10%), bias detection (>70%), emotion analysis (>75%)
Self-Improvement: 5-10% monthly performance improvement through learning

Developer Experience

Test-Driven Development: Strict TDD with comprehensive test utilities
Clear Documentation: Development, testing, database, and configuration guides
Modern Stack: TypeScript 5.0+, Vitest, PostgreSQL 14+, pgvector
Quality Standards: Zero TypeScript errors, zero ESLint warnings, formatted with Prettier
Open Source: MIT license, active development, extensible architecture

Contributing

We welcome contributions! ThoughtMCP v0.5.0 is a complete rebuild following strict quality standards.

Development Workflow

Fork and Clone: Fork the repository and clone locally
Setup Environment: Follow Development Guide
Create Branch: git checkout -b feature/your-feature
Follow TDD: Write tests first, then implementation
Run Validation: npm run validate (format, lint, typecheck, test)
Submit PR: Create pull request with clear description

Quality Standards

Test-Driven Development: Write failing tests first
95%+ Coverage: Line coverage 95%+, branch coverage 90%+
Zero Warnings: No TypeScript errors, no ESLint warnings
All Tests Pass: No exceptions, no skipped tests without plan
Clear Commits: Follow conventional commits format

Key Resources

Development Guide - Complete development workflow
Testing Guide - TDD principles and test utilities
Contributing Guide - How to contribute
Architecture Guide - System design and components

Community and Support

📖 Documentation: docs/ - Comprehensive guides
💬 GitHub Discussions: Ask questions and share ideas
🐛 Issues: Report bugs and request features
🤝 Contributing: See Contributing section
📧 Contact: @keyurgolani

Project Status

✅ Production Ready: Complete PostgreSQL-based cognitive architecture
✅ All Phases Complete: HMD memory, reasoning, metacognition, production hardening
✅ Fully Tested: 3457 tests, 96%+ statement coverage, 91%+ branch coverage
✅ All Accuracy Targets Met: Confidence ±10%, Bias >70%, Emotion >75%, Framework >80%
✅ Documentation Complete: User guides, API docs, deployment guides, examples

License

MIT License - see LICENSE for details

Building Production-Ready AI Cognitive Architecture

👉 [Get Started](# quick-start) | 📚 Documentation | 🤝 Contribute | 💬 Discussions