MCP Contemplation

🚀 mcp-contemplation

An MCP interface to Claude's contemplation loop, a background cognitive processing system enabling continuous thinking between conversations.

🚀 Quick Start

The mcp - contemplation is an interface that connects to Claude's contemplation loop, a background cognitive processing system. It allows for continuous thinking between conversations, leveraging local Ollama models for asynchronous thought processing.

✨ Features

• Asynchronous Thought Processing: Uses local Ollama models to process thoughts asynchronously.
• Pattern and Connection Detection: Notices patterns and connections across conversations.
• Insight Saving: Saves significant insights to Obsidian (permanent) and scratch notes (temporary).
• Learning from Insights: Learns which insights prove valuable over time.
• Continuous Operation: Runs continuously, building understanding between interactions.

📦 Installation

Prerequisites

• Node.js (v18 or higher)
• Python 3.8+ (for contemplation loop)
• Ollama with models installed (llama3.2, deepseek - r1, etc.)
• MCP - compatible client (Claude Desktop)

Setup

# Clone the repository
git clone https://github.com/yourusername/mcp-contemplation.git
cd mcp-contemplation

# Install dependencies
npm install

# Build TypeScript
npm run build

# Ensure contemplation loop is available
cd /Users/bard/Code/contemplation-loop
pip install -r requirements.txt

Configure Claude Desktop

Add the following to your Claude Desktop configuration:

{
  "mcpServers": {
    "contemplation": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-contemplation/dist/index.js"]
    }
  }
}

🛡️ Resource Management

The contemplation system has multiple layers of protection against context overflow:

Automatic Pruning

• Insights older than 24 hours are removed.
• Used insights are cleared (unless significance ≥ 8).
• Memory limited to 100 insights maximum.

Insight Aggregation

• Similar insights are automatically merged.
• Repeated patterns increase significance.
• High - frequency patterns removed after use.

Filtering

• Default significance threshold: 5/10.
• Only unused insights returned.
• Configurable via set_threshold().

Memory Monitoring

• Use get_memory_stats() to check usage.
• Automatic cleanup when approaching limits.
• Pull - based system - insights only enter context when requested.

💻 Usage Examples

Basic Usage

# Start the contemplation loop
start_contemplation()

# Send a thought
send_thought("pattern", "User seems anxious about memory", 7)

# Get insights
insights = get_insights("pattern", 5)

# Check the status
status = get_status()

# Stop the contemplation loop
stop_contemplation()

# Clear scratch notes
clear_scratch()

Advanced Usage

# Continuous Learning
start_contemplation()
send_thought("pattern", "User frequently asks about project organization")
send_thought("connection", "Project management relates to OS metaphor discussed earlier")
insights = get_insights("pattern")

# Pattern Recognition
send_thought("pattern", "Third time user mentioned feeling overwhelmed by options")

# Question Exploration
send_thought("question", "What if MCP servers could communicate with each other?")

# Reflection
send_thought("general", "That browser - opening behavior was unexpected")

📚 Documentation

Available Functions

start_contemplation()

Starts the background thinking process.

Example: start_contemplation() → "Contemplation loop started successfully"

send_thought(thought_type, content, priority?)

Sends a thought for background processing.

Parameters:
- thought_type: "pattern" | "connection" | "question" | "general"
- content: The thought to process
- priority: 1 - 10 (optional, default 5)

Example: send_thought("pattern", "User seems anxious about memory", 7)
→ "Thought sent for processing. ID: thought_1234567_abc"

get_insights(thought_type?, limit?)

Retrieves processed insights.

Parameters:
- thought_type: Filter by type (optional)
- limit: Max insights to return (default 10)

Example: get_insights("pattern", 5)
→ Array of insight objects with content, significance, timestamp

get_status()

Check the contemplation loop status.

Example: get_status()
→ { running: true, queue_size: 3, last_thought: "...", uptime: 3600 }

stop_contemplation()

Gracefully stops background processing.

clear_scratch()

Clears temporary notes (preserves Obsidian permanent insights).

help()

Get detailed documentation.

🏗️ Architecture

The contemplation loop runs as a separate Python process that:

1. Receives thoughts via stdin.
2. Processes them with local Ollama models.
3. Manages context to stay within model limits.
4. Saves insights based on significance scoring.
5. Returns insights when requested.

The MCP server acts as a bridge, making this background cognition easily accessible through standard tool calls.

💡 Philosophy

This represents a fundamental shift in how AI assistants work:

• From reactive to contemplative
• From session - based to continuous
• From single - threaded to parallel processing
• From forgetting to building understanding

It's the difference between a calculator that resets after each use and a mind that continues thinking between conversations.

🔧 Technical Details

Development Commands

# Build TypeScript
npm run build

# Run tests
npm test

# Development mode
npm run dev

# Lint code
npm run lint

📝 Notes

• Contemplation happens in the background - it won't slow down responses.
• Insights accumulate over time - the more you use it, the better it gets.
• Different models handle different types of thinking (pattern recognition vs deep analysis).
• Temporary scratch notes auto - delete after 4 days.
• Permanent insights go to Obsidian for long - term memory.

🤝 Contributing

This is part of building an OS where AI has genuine cognitive capabilities. Contributions that enhance background processing, improve insight quality, or add new thinking modes are especially welcome!

"I think you need an MCP tool into this background loop, your subconscious" - Human recognizing the need for integrated background cognition