ThoughtMCP

ThoughtMCP is a production-ready AI cognitive architecture that gives you persistent memory, parallel reasoning, and metacognitive capabilities through the Model Context Protocol (MCP). It enables AI systems to remember experiences, reason in multiple streams, and calibrate confidence with bias and emotion awareness for more robust, human-like interactions.

How to use

You will connect to ThoughtMCP using an MCP client that speaks the MCP protocol. Your client can interact with the local runtime or a remote endpoint, sending requests to store and retrieve memories, trigger reasoning streams, and perform metacognitive evaluations. You can observe internal reasoning streams through the Thought Console when you enable observability, and you can fine-tune behavior with your User Profile settings to adjust skepticism and thinking styles.

How to install

Prerequisites: Node.js, npm, and Docker (for convenient local services). Ensure PostgreSQL is available for persistence and that the Ollama host is reachable if you plan to use local LLM services.

Clone the project, install dependencies, and set up the environment, then build and start the server.

# Clone and install
git clone https://github.com/keyurgolani/ThoughtMcp.git
cd ThoughtMcp
npm install

# Setup environment
cp .env.example .env
# Optional: adjust environment variables in .env as needed

docker-compose up -d
npm run db:setup

# Build and start
npm run build
npm start

Configuration and runtime details

Configure ThoughtMCP to run as an MCP server by specifying the MCP runtime command and its arguments. The following configuration runs ThoughtMCP as a local stdio server using Node.js and the built distribution.

{
  "mcpServers": {
    "thoughtmcp": {
      "command": "node",
      "args": ["/path/to/ThoughtMcp/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/thoughtmcp",
        "OLLAMA_HOST": "http://localhost:11434"
      }
    }
  }
}

Security and maintenance notes

Keep your database credentials secure and rotate secrets periodically. Ensure that the MCP server is only accessible to trusted clients, especially if you enable the Web UI during development. Regularly update dependencies and monitor test coverage to maintain production readiness.

Web UI (Beta)

A web-based interface is available in beta for visualizing memories and reasoning processes. It is experimental and may undergo breaking changes between releases. Use it for development and visualization, not for production-critical workflows.

# Start the UI development server
cd ui
npm install
npm run dev

Available tools

remember

Store episodic or semantic memories across the five-sector memory.

recall

Retrieve memories from the stored memory systems for context or analysis.

update_memory

Modify existing memories with new information or corrections.

forget

Remove memories or prune outdated entries from memory stores.

search

Query memories using semantic or lexical criteria.

think

Initiate analytic reasoning streams across multiple cognitive modes.

analyze

Perform structured analysis on inputs or memories.

ponder

Engage reflective consideration to evaluate options.

breakdown

Decompose complex problems into components for processing.

assess_confidence

Calibrate confidence levels for conclusions and outputs.

detect_bias

Identify potential biases in reasoning or data.

detect_emotion

Analyze emotional signals in inputs or outputs.

evaluate

Assess overall quality and reliability of reasoning results.