# ThoughtMCP MCP Tools Reference
## Overview
This document provides comprehensive documentation for all MCP (Model Context Protocol) tools exposed by ThoughtMCP. These tools enable LLM clients to interact with the cognitive architecture for memory management, reasoning, and metacognitive operations.
## Table of Contents
- [Memory Tools](#memory-tools)
- [remember](#remember)
- [recall](#recall)
- [update_memory](#update_memory)
- [forget](#forget)
- [search](#search)
- [Memory Management Tools](#memory-management-tools)
- [memory_health](#memory_health)
- [prune_memories](#prune_memories)
- [consolidate_memories](#consolidate_memories)
- [export_memories](#export_memories)
- [Reasoning Tools](#reasoning-tools)
- [think](#think)
- [analyze](#analyze)
- [ponder](#ponder)
- [breakdown](#breakdown)
- [Metacognitive Tools](#metacognitive-tools)
- [assess_confidence](#assess_confidence)
- [detect_bias](#detect_bias)
- [detect_emotion](#detect_emotion)
- [evaluate](#evaluate)
- [Response Format](#response-format)
- [Error Codes](#error-codes)
- [Best Practices](#best-practices)
- [Recommended Memory Content Formatting](#recommended-memory-content-formatting)
---
## Memory Tools
### remember
Store a new memory with automatic embedding generation and waypoint graph connections.
**Description:**
Creates a new memory in the HMD (Hierarchical Memory Decomposition) system. Automatically generates five-sector embeddings (episodic, semantic, procedural, emotional, reflective) and creates 1-3 waypoint connections to similar existing memories.
**Input Schema:**
```json
{
"type": "object",
"properties": {
"content": {
"type": "string",
"description": "Memory content to store (required, non-empty)"
},
"userId": {
"type": "string",
"description": "User ID for memory isolation (required)"
},
"sessionId": {
"type": "string",
"description": "Session ID for context tracking (required)"
},
"primarySector": {
"type": "string",
"enum": ["episodic", "semantic", "procedural", "emotional", "reflective"],
"description": "Primary memory sector"
},
"metadata": {
"type": "object",
"description": "Optional metadata for classification and search",
"properties": {
"keywords": {
"type": "array",
"items": { "type": "string" },
"description": "Keywords for search (auto-extracted if not provided)"
},
"tags": {
"type": "array",
"items": { "type": "string" },
"description": "Tags for categorization"
},
"category": {
"type": "string",
"description": "Category for grouping"
},
"context": {
"type": "string",
"description": "Additional context information"
},
"importance": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Importance score (0-1, default 0.5)"
}
}
}
},
"required": ["content", "userId", "sessionId", "primarySector"]
}
```
**Example Request:**
```json
{
"content": "User prefers dark mode for all applications",
"userId": "user-123",
"sessionId": "session-456",
"primarySector": "semantic",
"metadata": {
"keywords": ["preference", "dark mode", "ui"],
"tags": ["settings", "user-preference"],
"category": "preferences",
"importance": 0.8
}
}
```
**Success Response:**
```json
{
"success": true,
"data": {
"memoryId": "mem-abc123",
"embeddingsGenerated": 5,
"linksCreated": 2,
"salience": 0.75,
"strength": 1.0
},
"metadata": {
"timestamp": "2025-12-07T10:30:00Z",
"processingTime": 245,
"componentsUsed": ["memoryRepository", "embeddingEngine", "graphBuilder"]
}
}
```
**Error Response:**
```json
{
"success": false,
"error": "Content cannot be empty",
"suggestion": "Check that all required fields are provided and content is non-empty. Ensure primarySector is one of: episodic, semantic, procedural, emotional, reflective"
}
```
---
### recall
Retrieve memories using composite scoring with vector similarity, metadata filtering, and pagination.
**Description:**
Retrieves memories using a composite scoring formula: `0.6×similarity + 0.2×salience + 0.1×recency + 0.1×linkWeight`. Supports filtering by sectors, strength, salience, date range, and metadata.
**Input Schema:**
```json
{
"type": "object",
"properties": {
"userId": {
"type": "string",
"description": "User ID for memory isolation (required)"
},
"text": {
"type": "string",
"description": "Search query text for vector similarity (optional)"
},
"sectors": {
"type": "array",
"items": {
"type": "string",
"enum": ["episodic", "semantic", "procedural", "emotional", "reflective"]
},
"description": "Memory sectors to search (default: all sectors)"
},
"primarySector": {
"type": "string",
"enum": ["episodic", "semantic", "procedural", "emotional", "reflective"],
"description": "Filter by primary sector"
},
"minStrength": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum memory strength (0-1)"
},
"minSalience": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum salience score (0-1)"
},
"dateRange": {
"type": "object",
"properties": {
"start": { "type": "string", "format": "date-time" },
"end": { "type": "string", "format": "date-time" }
},
"description": "Filter by creation date range (ISO 8601)"
},
"metadata": {
"type": "object",
"properties": {
"keywords": { "type": "array", "items": { "type": "string" } },
"tags": { "type": "array", "items": { "type": "string" } },
"category": { "type": "string" }
},
"description": "Metadata filters"
},
"limit": {
"type": "number",
"minimum": 1,
"maximum": 100,
"description": "Maximum results to return (default 10, max 100)"
},
"offset": {
"type": "number",
"minimum": 0,
"description": "Pagination offset (default 0)"
}
},
"required": ["userId"]
}
```
**Example Request:**
```json
{
"userId": "user-123",
"text": "dark mode preference",
"sectors": ["semantic", "episodic"],
"minStrength": 0.5,
"limit": 10
}
```
**Success Response:**
```json
{
"success": true,
"data": {
"memories": [
{
"id": "mem-abc123",
"content": "User prefers dark mode for all applications",
"createdAt": "2025-12-07T10:30:00Z",
"lastAccessed": "2025-12-07T12:00:00Z",
"strength": 0.95,
"salience": 0.75,
"primarySector": "semantic",
"metadata": {
"keywords": ["preference", "dark mode"],
"tags": ["settings"]
},
"score": 0.87
}
],
"totalCount": 1,
"scores": { "mem-abc123": 0.87 }
}
}
```
---
### update_memory
Update an existing memory with selective field updates.
**Description:**
Updates memory fields selectively. Content changes trigger automatic embedding regeneration and waypoint connection updates. Supports updating strength, salience, and metadata.
**Input Schema:**
```json
{
"type": "object",
"properties": {
"memoryId": {
"type": "string",
"description": "Memory ID to update (required)"
},
"userId": {
"type": "string",
"description": "User ID for ownership verification (required)"
},
"content": {
"type": "string",
"description": "New content (triggers embedding regeneration)"
},
"strength": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "New strength value (0-1)"
},
"salience": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "New salience value (0-1)"
},
"metadata": {
"type": "object",
"properties": {
"keywords": { "type": "array", "items": { "type": "string" } },
"tags": { "type": "array", "items": { "type": "string" } },
"category": { "type": "string" },
"context": { "type": "string" },
"importance": { "type": "number", "minimum": 0, "maximum": 1 }
},
"description": "Metadata updates"
}
},
"required": ["memoryId", "userId"]
}
```
**Example Request:**
```json
{
"memoryId": "mem-abc123",
"userId": "user-123",
"content": "User strongly prefers dark mode across all applications",
"strength": 0.95,
"metadata": {
"importance": 0.9
}
}
```
**Success Response:**
```json
{
"success": true,
"data": {
"memoryId": "mem-abc123",
"embeddingsRegenerated": true,
"connectionsUpdated": 2,
"strength": 0.95,
"salience": 0.75
}
}
```
---
### forget
Delete a memory with cascade deletion options.
**Description:**
Supports soft delete (sets strength to 0, preserves data) or hard delete (removes memory and cascades to embeddings, connections, and metadata).
**Input Schema:**
```json
{
"type": "object",
"properties": {
"memoryId": {
"type": "string",
"description": "Memory ID to delete (required)"
},
"userId": {
"type": "string",
"description": "User ID for ownership verification (required)"
},
"soft": {
"type": "boolean",
"description": "Soft delete (true) sets strength=0, hard delete (false) removes record (default: false)"
}
},
"required": ["memoryId", "userId"]
}
```
**Example Request:**
```json
{
"memoryId": "mem-abc123",
"userId": "user-123",
"soft": false
}
```
**Success Response:**
```json
{
"success": true,
"data": {
"memoryId": "mem-abc123",
"deletionType": "hard",
"message": "Memory and all related data removed"
}
}
```
---
### search
Advanced memory search combining full-text search, vector similarity, and metadata filtering.
**Description:**
Performs comprehensive search using PostgreSQL full-text search with boolean operators (AND, OR, NOT) and phrase matching. Returns ranked results with composite scores.
**Input Schema:**
```json
{
"type": "object",
"properties": {
"userId": {
"type": "string",
"description": "User ID for memory isolation (required)"
},
"text": {
"type": "string",
"description": "Full-text search query with boolean operators (AND, OR, NOT) and phrase matching"
},
"sectors": {
"type": "array",
"items": {
"type": "string",
"enum": ["episodic", "semantic", "procedural", "emotional", "reflective"]
},
"description": "Memory sectors to search (default: all sectors)"
},
"primarySector": {
"type": "string",
"enum": ["episodic", "semantic", "procedural", "emotional", "reflective"],
"description": "Filter by primary sector"
},
"minStrength": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum memory strength (0-1)"
},
"minSalience": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum salience score (0-1)"
},
"dateRange": {
"type": "object",
"properties": {
"start": { "type": "string", "format": "date-time" },
"end": { "type": "string", "format": "date-time" }
},
"description": "Filter by creation date range"
},
"metadata": {
"type": "object",
"properties": {
"keywords": { "type": "array", "items": { "type": "string" } },
"tags": { "type": "array", "items": { "type": "string" } },
"category": { "type": "string" }
},
"description": "Metadata filters"
},
"limit": {
"type": "number",
"minimum": 1,
"maximum": 100,
"description": "Maximum results to return (default 10, max 100)"
},
"offset": {
"type": "number",
"minimum": 0,
"description": "Pagination offset (default 0)"
}
},
"required": ["userId"]
}
```
**Example Request (Full-Text Search):**
```json
{
"userId": "user-123",
"text": "dark mode AND preference",
"metadata": { "tags": ["settings"] },
"limit": 20
}
```
**Success Response (Full-Text):**
```json
{
"success": true,
"data": {
"memories": [
{
"id": "mem-abc123",
"content": "User prefers dark mode for all applications",
"createdAt": "2025-12-07T10:30:00Z",
"strength": 0.95,
"salience": 0.75,
"rank": 0.92,
"highlight": "User prefers <b>dark mode</b> for all applications",
"matchedTerms": ["dark", "mode", "preference"]
}
],
"totalCount": 1,
"searchType": "full-text"
}
}
```
---
## Memory Management Tools
### memory_health
Get comprehensive memory health metrics and recommendations for a user.
**Description:**
Returns storage usage, memory counts by sector and age, consolidation queue status, forgetting candidates breakdown, and actionable recommendations. When usage exceeds 80%, recommendations include storage optimization suggestions.
**Input Schema:**
```json
{
"type": "object",
"properties": {
"userId": {
"type": "string",
"description": "User ID for memory isolation (required)"
}
},
"required": ["userId"]
}
```
**Example Request:**
```json
{
"userId": "user-123"
}
```
**Success Response:**
```json
{
"success": true,
"data": {
"storage": {
"bytesUsed": 1048576,
"quotaBytes": 10485760,
"usagePercent": 10
},
"countsBySector": {
"episodic": 50,
"semantic": 30,
"procedural": 10,
"emotional": 5,
"reflective": 5
},
"countsByAge": {
"last24h": 5,
"lastWeek": 20,
"lastMonth": 40,
"older": 35
},
"consolidationQueue": {
"size": 15,
"estimatedTimeMs": 5000
},
"activeConsolidation": {
"isRunning": false,
"phase": null,
"clustersIdentified": 0,
"clustersConsolidated": 0,
"memoriesProcessed": 0,
"memoriesTotal": 0,
"percentComplete": 0,
"estimatedRemainingMs": 0,
"startedAt": null
},
"forgettingCandidates": {
"lowStrength": 10,
"oldAge": 5,
"lowAccess": 8,
"total": 23
},
"recommendations": [
{
"type": "consolidation",
"priority": "medium",
"message": "15 memories are candidates for consolidation",
"action": "Run consolidate_memories to combine related memories"
}
],
"timestamp": "2025-12-07T10:30:00Z"
}
}
```
---
### prune_memories
Identify and remove low-value memories to optimize storage and improve retrieval relevance.
**Description:**
Lists forgetting candidates based on configurable criteria (strength, age, access count), previews pruning effects, or executes pruning with graph cleanup. Supports dry-run mode to preview effects without deletion.
**Input Schema:**
```json
{
"type": "object",
"properties": {
"userId": {
"type": "string",
"description": "User ID for memory isolation (required)"
},
"action": {
"type": "string",
"enum": ["list", "preview", "prune"],
"description": "Action to perform: list candidates, preview effects, or execute pruning"
},
"criteria": {
"type": "object",
"description": "Pruning criteria (for list action)",
"properties": {
"minStrength": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Memories below this strength are candidates (default: 0.1)"
},
"maxAgeDays": {
"type": "number",
"minimum": 1,
"description": "Memories older than this are candidates (default: 180)"
},
"minAccessCount": {
"type": "number",
"minimum": 0,
"description": "Memories with fewer accesses are candidates (default: 0)"
}
}
},
"memoryIds": {
"type": "array",
"items": { "type": "string" },
"description": "Memory IDs to prune (for preview/prune actions)"
}
},
"required": ["userId", "action"]
}
```
**Example Request (List Candidates):**
```json
{
"userId": "user-123",
"action": "list",
"criteria": {
"minStrength": 0.1,
"maxAgeDays": 90,
"minAccessCount": 0
}
}
```
**Success Response (List):**
```json
{
"success": true,
"data": {
"candidates": [
{
"memoryId": "mem-abc123",
"content": "Old meeting notes from Q1",
"strength": 0.05,
"createdAt": "2025-03-15T10:00:00Z",
"lastAccessed": "2025-03-20T14:00:00Z",
"accessCount": 1,
"reason": "low_strength"
}
],
"count": 1,
"criteria": {
"minStrength": 0.1,
"maxAgeDays": 90,
"minAccessCount": 0
}
}
}
```
**Example Request (Prune):**
```json
{
"userId": "user-123",
"action": "prune",
"memoryIds": ["mem-abc123", "mem-def456"]
}
```
**Success Response (Prune):**
```json
{
"success": true,
"data": {
"deletedCount": 2,
"freedBytes": 4096,
"orphanedLinksRemoved": 3,
"timestamp": "2025-12-07T10:30:00Z"
}
}
```
---
### consolidate_memories
Trigger memory consolidation to combine related episodic memories into semantic summaries.
**Description:**
Identifies clusters of related episodic memories based on semantic similarity and consolidates them into higher-level semantic summaries. Creates graph links from summaries to originals and reduces original memory strength.
**Input Schema:**
```json
{
"type": "object",
"properties": {
"userId": {
"type": "string",
"description": "User ID for memory isolation (required)"
},
"similarityThreshold": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Minimum similarity for clustering (default: 0.75)"
},
"minClusterSize": {
"type": "number",
"minimum": 2,
"description": "Minimum cluster size to consolidate (default: 5)"
},
"batchSize": {
"type": "number",
"minimum": 1,
"maximum": 1000,
"description": "Maximum memories per consolidation run (default: 100)"
},
"strengthReductionFactor": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Factor to reduce original memory strength (default: 0.5)"
}
},
"required": ["userId"]
}
```
**Example Request:**
```json
{
"userId": "user-123",
"similarityThreshold": 0.8,
"minClusterSize": 5
}
```
**Success Response:**
```json
{
"success": true,
"data": {
"results": [
{
"summaryId": "mem-summary-001",
"consolidatedIds": ["mem-001", "mem-002", "mem-003", "mem-004", "mem-005"],
"summaryContent": "Multiple meetings about Q4 planning discussed roadmap priorities, resource allocation, and timeline adjustments.",
"consolidatedAt": "2025-12-07T10:30:00Z"
}
],
"totalConsolidated": 5,
"clustersProcessed": 1,
"timestamp": "2025-12-07T10:30:00Z"
}
}
```
---
### export_memories
Export memories to JSON format with all metadata and embeddings.
**Description:**
Exports memories to a portable JSON format including content, metadata, embeddings, tags, and graph links. Supports filtering by date range, sector, tags, and minimum strength.
**Input Schema:**
```json
{
"type": "object",
"properties": {
"userId": {
"type": "string",
"description": "User ID for memory isolation (required)"
},
"filter": {
"type": "object",
"description": "Export filters (optional)",
"properties": {
"startDate": {
"type": "string",
"format": "date-time",
"description": "Start date for date range filter"
},
"endDate": {
"type": "string",
"format": "date-time",
"description": "End date for date range filter"
},
"sectors": {
"type": "array",
"items": {
"type": "string",
"enum": ["episodic", "semantic", "procedural", "emotional", "reflective"]
},
"description": "Filter by memory sectors"
},
"tags": {
"type": "array",
"items": { "type": "string" },
"description": "Filter by tags"
},
"minStrength": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Filter by minimum strength"
}
}
}
},
"required": ["userId"]
}
```
**Example Request:**
```json
{
"userId": "user-123",
"filter": {
"sectors": ["semantic", "procedural"],
"minStrength": 0.5
}
}
```
**Success Response:**
```json
{
"success": true,
"data": {
"memories": [
{
"id": "mem-abc123",
"content": "PostgreSQL connection pooling best practices",
"primarySector": "procedural",
"metadata": {
"keywords": ["database", "postgresql", "performance"],
"tags": ["technical", "best-practices"],
"importance": 0.8
},
"embeddings": { "procedural": [0.1, 0.2, ...] },
"tags": ["technical"],
"createdAt": "2025-12-01T10:00:00Z",
"lastAccessed": "2025-12-07T09:00:00Z",
"strength": 0.85,
"salience": 0.7,
"accessCount": 5,
"links": [{ "targetId": "mem-def456", "weight": 0.8, "linkType": "waypoint" }]
}
],
"exportedAt": "2025-12-07T10:30:00Z",
"version": "1.0.0",
"userId": "user-123",
"filter": {
"sectors": ["semantic", "procedural"],
"minStrength": 0.5
},
"count": 1
}
}
```
---
## Reasoning Tools
### think
Perform reasoning with specified mode (analytical, creative, critical, synthetic, parallel).
**Description:**
Integrates all reasoning components including parallel streams, confidence assessment, and bias detection. Supports single-stream or parallel multi-stream reasoning.
**Input Schema:**
```json
{
"type": "object",
"properties": {
"problem": {
"type": "string",
"description": "Problem or question to reason about (required)"
},
"mode": {
"type": "string",
"enum": ["analytical", "creative", "critical", "synthetic", "parallel"],
"description": "Reasoning mode: analytical (logical), creative (innovative), critical (skeptical), synthetic (holistic), parallel (all modes simultaneously)"
},
"context": {
"type": "object",
"description": "Additional context for reasoning (optional)",
"properties": {
"background": { "type": "string", "description": "Background information" },
"constraints": {
"type": "array",
"items": { "type": "string" },
"description": "Constraints to consider"
},
"goals": {
"type": "array",
"items": { "type": "string" },
"description": "Goals to achieve"
}
}
}
},
"required": ["problem", "mode"]
}
```
**Example Request (Single Stream):**
```json
{
"problem": "How to optimize database query performance?",
"mode": "analytical",
"context": {
"background": "PostgreSQL database with 1M records",
"constraints": ["No schema changes", "Minimal downtime"],
"goals": ["Reduce p95 latency to <100ms"]
}
}
```
**Success Response (Single Stream):**
```json
{
"success": true,
"data": {
"conclusion": "Implement query caching and add composite indexes",
"reasoning": ["Analyzed query patterns", "Identified bottlenecks", "Evaluated solutions"],
"insights": [
"80% of queries hit same tables",
"Missing indexes on frequently filtered columns"
],
"confidence": 0.85,
"processingTime": 2500,
"status": "completed"
}
}
```
**Example Request (Parallel):**
```json
{
"problem": "Should we migrate to microservices architecture?",
"mode": "parallel",
"context": {
"background": "Monolithic application with scaling issues",
"constraints": ["Limited team size", "6-month timeline"]
}
}
```
**Success Response (Parallel):**
```json
{
"success": true,
"data": {
"conclusion": "Gradual migration recommended with careful planning",
"insights": [
{
"content": "Scalability benefits significant",
"sources": ["analytical"],
"importance": 0.9
},
{ "content": "Consider strangler fig pattern", "sources": ["creative"], "importance": 0.85 }
],
"recommendations": [
{ "description": "Start with bounded contexts", "priority": 1, "confidence": 0.88 }
],
"conflicts": [
{ "type": "approach", "description": "Timeline vs scope disagreement", "severity": 0.6 }
],
"confidence": 0.82,
"quality": 0.87
}
}
```
---
### analyze
Analyze problem using systematic thinking framework with dynamic framework selection.
**Description:**
Automatically selects optimal framework (Scientific Method, Design Thinking, Systems Thinking, etc.) based on problem characteristics. Supports preferred framework override.
**Available Frameworks:**
| Framework ID | Name | Best For |
| -------------------------- | ------------------------ | -------------------------------------- |
| `scientific-method` | Scientific Method | Hypothesis testing, empirical problems |
| `design-thinking` | Design Thinking | User-centered problems, innovation |
| `systems-thinking` | Systems Thinking | Complex interconnected systems |
| `critical-thinking` | Critical Thinking | Evaluation, argument analysis |
| `creative-problem-solving` | Creative Problem Solving | Novel solutions, brainstorming |
| `root-cause-analysis` | Root Cause Analysis | Debugging, failure analysis |
| `first-principles` | First Principles | Fundamental understanding |
| `scenario-planning` | Scenario Planning | Future planning, uncertainty |
**Input Schema:**
```json
{
"type": "object",
"properties": {
"problem": {
"type": "string",
"description": "Problem to analyze systematically (required)"
},
"preferredFramework": {
"type": "string",
"enum": [
"scientific-method",
"design-thinking",
"systems-thinking",
"critical-thinking",
"creative-problem-solving",
"root-cause-analysis",
"first-principles",
"scenario-planning"
],
"description": "Preferred framework (optional, overrides automatic selection)"
},
"context": {
"type": "object",
"properties": {
"background": { "type": "string" },
"constraints": { "type": "array", "items": { "type": "string" } },
"goals": { "type": "array", "items": { "type": "string" } }
}
}
},
"required": ["problem"]
}
```
**Example Request:**
```json
{
"problem": "Why is the system experiencing intermittent failures?",
"context": {
"background": "Production system with 99.9% SLA",
"constraints": ["Cannot take system offline"]
}
}
```
**Success Response:**
```json
{
"success": true,
"data": {
"framework": {
"id": "root-cause-analysis",
"name": "Root Cause Analysis",
"description": "Systematic approach to identify underlying causes"
},
"selection": {
"confidence": 0.92,
"reason": "Problem characteristics match debugging/failure analysis pattern",
"isHybrid": false
},
"result": {
"conclusion": "Memory leak in connection pool causing resource exhaustion",
"steps": ["Define problem", "Collect data", "Identify causes", "Verify root cause"],
"insights": ["Connection pool not releasing connections", "Memory grows linearly over time"],
"confidence": 0.88,
"processingTime": 3200
},
"alternatives": [
{
"framework": { "id": "systems-thinking", "name": "Systems Thinking" },
"reason": "Could reveal systemic issues"
}
]
}
}
```
---
### ponder
Execute parallel reasoning streams with coordination and synthesis.
**Description:**
Runs all four reasoning streams (analytical, creative, critical, synthetic) concurrently with synchronization at 25%, 50%, 75% completion. Results are synthesized with conflict preservation and insight attribution.
**Input Schema:**
```json
{
"type": "object",
"properties": {
"problem": {
"type": "string",
"description": "Problem to analyze with parallel reasoning (required)"
},
"timeout": {
"type": "number",
"minimum": 1000,
"maximum": 60000,
"description": "Total timeout in milliseconds (default: 30000ms, max: 60000ms)"
},
"context": {
"type": "object",
"properties": {
"background": { "type": "string" },
"constraints": { "type": "array", "items": { "type": "string" } },
"goals": { "type": "array", "items": { "type": "string" } }
}
}
},
"required": ["problem"]
}
```
**Example Request:**
```json
{
"problem": "How should we approach the product roadmap for Q1?",
"timeout": 30000,
"context": {
"background": "SaaS product with growing user base",
"goals": ["Increase retention", "Launch mobile app"]
}
}
```
**Success Response:**
```json
{
"success": true,
"data": {
"conclusion": "Prioritize retention features while preparing mobile foundation",
"insights": [
{
"content": "Retention has 3x ROI vs acquisition",
"sources": ["analytical"],
"importance": 0.95,
"confidence": 0.9
},
{
"content": "Mobile-first approach for new features",
"sources": ["creative"],
"importance": 0.85,
"confidence": 0.82
},
{
"content": "Risk of scope creep with parallel tracks",
"sources": ["critical"],
"importance": 0.8,
"confidence": 0.88
}
],
"recommendations": [
{
"description": "Focus 70% on retention, 30% on mobile prep",
"sources": ["synthetic"],
"priority": 1,
"confidence": 0.87,
"rationale": "Balances immediate needs with strategic goals"
}
],
"conflicts": [
{
"id": "conflict-1",
"type": "priority",
"description": "Analytical favors retention-only, Creative wants mobile-first",
"severity": 0.5,
"sourceStreams": ["analytical", "creative"]
}
],
"confidence": 0.85,
"quality": 0.88
}
}
```
---
### breakdown
Decompose problem into hierarchical sub-problems with dependency mapping.
**Description:**
Breaks complex problems into manageable components and identifies execution order using topological sorting. Supports configurable decomposition depth.
**Input Schema:**
```json
{
"type": "object",
"properties": {
"problem": {
"type": "string",
"description": "Problem to decompose (required)"
},
"maxDepth": {
"type": "number",
"minimum": 1,
"maximum": 5,
"description": "Maximum decomposition depth (default: 3, max: 5)"
},
"context": {
"type": "object",
"properties": {
"background": { "type": "string" },
"constraints": { "type": "array", "items": { "type": "string" } }
}
}
},
"required": ["problem"]
}
```
**Example Request:**
```json
{
"problem": "Build a scalable web application",
"maxDepth": 3
}
```
**Success Response:**
```json
{
"success": true,
"data": {
"problem": "Build a scalable web application",
"subProblems": [
{ "id": "problem-1-0", "description": "Build a scalable web application", "depth": 1 },
{
"id": "problem-1-0-0",
"description": "Design system architecture",
"depth": 2,
"parent": "problem-1-0"
},
{
"id": "problem-1-0-1",
"description": "Implement core features",
"depth": 2,
"parent": "problem-1-0"
},
{
"id": "problem-1-0-2",
"description": "Set up infrastructure",
"depth": 2,
"parent": "problem-1-0"
}
],
"dependencies": [
{ "from": "problem-1-0", "to": "problem-1-0-0", "type": "hierarchical" },
{ "from": "problem-1-0", "to": "problem-1-0-1", "type": "hierarchical" }
],
"executionOrder": ["problem-1-0", "problem-1-0-0", "problem-1-0-1", "problem-1-0-2"],
"totalSubProblems": 4,
"maxDepth": 3
}
}
```
---
## Metacognitive Tools
### assess_confidence
Assess confidence in reasoning with multi-dimensional analysis.
**Description:**
Evaluates evidence quality, reasoning coherence, completeness, uncertainty level, and bias freedom. Provides interpretation, warnings, and actionable recommendations.
**Input Schema:**
```json
{
"type": "object",
"properties": {
"reasoning": {
"type": "string",
"description": "Reasoning to assess (required)"
},
"evidence": {
"type": "array",
"items": { "type": "string" },
"description": "Supporting evidence (optional)"
},
"context": {
"type": "string",
"description": "Context for assessment (optional)"
}
},
"required": ["reasoning"]
}
```
**Example Request:**
```json
{
"reasoning": "Based on benchmark results, the optimization will improve throughput by 40%",
"evidence": ["Benchmark results showing 40% improvement", "Load test data", "Production metrics"],
"context": "Production deployment decision"
}
```
**Success Response:**
```json
{
"success": true,
"data": {
"overallConfidence": 0.82,
"dimensions": {
"evidenceQuality": 0.85,
"reasoningCoherence": 0.88,
"completeness": 0.75,
"uncertaintyLevel": 0.2,
"biasFreedom": 0.82
},
"interpretation": "High confidence - reasoning is well-supported",
"warnings": ["Consider edge cases not covered by benchmarks"],
"recommendations": ["Run A/B test in production", "Monitor for regression"]
},
"metadata": {
"timestamp": "2025-12-07T10:30:00Z",
"processingTime": 85,
"componentsUsed": ["confidenceAssessor"]
}
}
```
---
### detect_bias
Detect cognitive biases in reasoning with real-time monitoring.
**Description:**
Identifies 8 bias types: confirmation, anchoring, availability, recency, representativeness, framing, sunk cost, attribution. Provides severity assessment and correction strategies.
**Supported Bias Types:**
| Bias Type | Description |
| -------------------- | --------------------------------------------------- |
| `confirmation` | Favoring information that confirms existing beliefs |
| `anchoring` | Over-relying on first piece of information |
| `availability` | Overweighting easily recalled information |
| `recency` | Giving more weight to recent events |
| `representativeness` | Judging probability by similarity to stereotypes |
| `framing` | Being influenced by how information is presented |
| `sunk_cost` | Continuing due to past investment |
| `attribution` | Attributing behavior to character vs situation |
**Input Schema:**
```json
{
"type": "object",
"properties": {
"reasoning": {
"type": "string",
"description": "Reasoning to analyze for biases (required)"
},
"context": {
"type": "string",
"description": "Context for bias detection (optional)"
},
"monitorContinuously": {
"type": "boolean",
"description": "Enable continuous monitoring (default: false)"
}
},
"required": ["reasoning"]
}
```
**Example Request:**
```json
{
"reasoning": "All the data I've seen supports my hypothesis that users prefer feature A",
"context": "Product research analysis"
}
```
**Success Response:**
```json
{
"success": true,
"data": {
"biases": [
{
"type": "confirmation",
"severity": 0.75,
"evidence": ["Selective data consideration", "Dismissal of contradicting evidence"],
"correction": "Actively seek disconfirming evidence",
"confidence": 0.85
}
],
"detectionTime": 0.8,
"monitoringActive": false
},
"metadata": {
"timestamp": "2025-12-07T10:30:00Z",
"processingTime": 120,
"componentsUsed": ["biasDetector"]
}
}
```
---
### detect_emotion
Detect emotions using Circumplex model and discrete classification.
**Description:**
Analyzes text using the Circumplex model (valence, arousal, dominance) and classifies 11 discrete emotions: joy, sadness, anger, fear, disgust, surprise, pride, shame, guilt, gratitude, awe.
**Circumplex Dimensions:**
| Dimension | Range | Description |
| --------- | -------- | ----------------------------------- |
| Valence | -1 to +1 | Negative to positive emotional tone |
| Arousal | 0 to 1 | Low to high activation/energy |
| Dominance | -1 to +1 | Submissive to dominant feeling |
**Input Schema:**
```json
{
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "Text to analyze for emotions (required)"
},
"includeDiscrete": {
"type": "boolean",
"description": "Include discrete emotion classification (default: true)"
},
"context": {
"type": "string",
"description": "Context for emotion detection (optional)"
}
},
"required": ["text"]
}
```
**Example Request:**
```json
{
"text": "I'm really excited about this new project! It's going to be amazing!",
"includeDiscrete": true,
"context": "Work communication"
}
```
**Success Response:**
```json
{
"success": true,
"data": {
"circumplex": {
"valence": 0.85,
"arousal": 0.78,
"dominance": 0.65,
"confidence": 0.88
},
"discrete": {
"primary": "joy",
"emotions": [
{ "emotion": "joy", "score": 0.88, "intensity": "high" },
{ "emotion": "pride", "score": 0.45, "intensity": "moderate" },
{ "emotion": "awe", "score": 0.32, "intensity": "low" }
],
"confidence": 0.85
},
"detectionTime": 45
},
"metadata": {
"timestamp": "2025-12-07T10:30:00Z",
"processingTime": 45,
"componentsUsed": ["emotionAnalyzer", "discreteEmotionClassifier"]
}
}
```
---
### evaluate
Analyze reasoning quality with comprehensive assessment.
**Description:**
Evaluates coherence, completeness, logical validity, and evidence support. Identifies strengths, weaknesses, and provides improvement recommendations. Optionally includes confidence assessment, bias detection, and emotion analysis.
**Input Schema:**
```json
{
"type": "object",
"properties": {
"reasoning": {
"type": "string",
"description": "Reasoning to analyze (required)"
},
"context": {
"type": "string",
"description": "Context for analysis (optional)"
},
"includeConfidence": {
"type": "boolean",
"description": "Include confidence assessment (default: true)"
},
"includeBias": {
"type": "boolean",
"description": "Include bias detection (default: true)"
},
"includeEmotion": {
"type": "boolean",
"description": "Include emotion analysis (default: false)"
}
},
"required": ["reasoning"]
}
```
**Example Request:**
```json
{
"reasoning": "Based on our analysis, the proposed solution is optimal because it addresses all requirements while minimizing costs",
"context": "Technical decision review",
"includeConfidence": true,
"includeBias": true,
"includeEmotion": false
}
```
**Success Response:**
```json
{
"success": true,
"data": {
"quality": {
"coherence": 0.85,
"completeness": 0.8,
"logicalValidity": 0.9,
"evidenceSupport": 0.75
},
"strengths": ["Clear logical structure", "Well-supported claims"],
"weaknesses": ["Missing alternative perspectives", "Limited evidence"],
"recommendations": ["Consider counterarguments", "Gather more data"],
"confidence": {
"overallConfidence": 0.78,
"dimensions": { "evidenceQuality": 0.75, "reasoningCoherence": 0.85 }
},
"biases": []
},
"metadata": {
"timestamp": "2025-12-07T10:30:00Z",
"processingTime": 180,
"componentsUsed": ["confidenceAssessor", "biasDetector"]
}
}
```
---
## Response Format
All MCP tools return responses in a standardized format:
```typescript
interface MCPResponse {
success: boolean; // Whether the operation succeeded
data?: any; // Response data (if successful)
error?: string; // Error message (if failed)
suggestion?: string; // Suggestion for fixing error
metadata?: {
timestamp: string; // ISO 8601 timestamp
processingTime: number; // Processing time in milliseconds
componentsUsed: string[]; // Cognitive components used
confidence?: number; // Confidence level (0-1)
};
}
```
---
## Error Codes
Common error scenarios and their solutions:
| Error | Cause | Solution |
| ----------------------------------- | --------------------------- | ---------------------------------------------------------- |
| `Server not initialized` | Server startup incomplete | Wait for initialization to complete |
| `Memory repository not initialized` | Database connection failed | Check database configuration |
| `Tool not found` | Invalid tool name | Use one of the documented tool names |
| `Missing required parameter` | Required field not provided | Check input schema for required fields |
| `Memory not found` | Invalid memoryId | Verify memoryId exists and belongs to user |
| `Content cannot be empty` | Empty content string | Provide non-empty content |
| `Invalid sector` | Unknown memory sector | Use: episodic, semantic, procedural, emotional, reflective |
| `Timeout exceeded` | Processing took too long | Reduce complexity or increase timeout |
---
## Best Practices
### Memory Management
1. **Use appropriate sectors**: Choose the primary sector that best matches the memory type
- `episodic`: Events, experiences, temporal information
- `semantic`: Facts, concepts, general knowledge
- `procedural`: How-to, processes, skills
- `emotional`: Feelings, emotional experiences
- `reflective`: Insights, meta-observations
2. **Add meaningful metadata**: Keywords and tags improve search accuracy
3. **Set appropriate importance**: Higher importance (0.8-1.0) for critical information
4. **Use soft delete for recovery**: Soft delete preserves data for potential recovery
### Memory Health & Maintenance
1. **Monitor health regularly**: Use `memory_health` to track storage usage and get recommendations
2. **Prune proactively**: Regularly review and prune low-value memories to optimize storage
- Use `prune_memories` with `action: "list"` to identify candidates
- Preview effects with `action: "preview"` before actual deletion
- Execute with `action: "prune"` when ready
3. **Consolidate related memories**: Use `consolidate_memories` to combine related episodic memories
- Reduces memory bloat while preserving insights
- Creates semantic summaries linked to originals
- Run periodically or when consolidation queue grows
4. **Export for backup**: Use `export_memories` to create backups before major operations
- Filter by sector, tags, or date range for targeted exports
- Store exports securely for disaster recovery
5. **Archive old memories**: Move infrequently accessed memories to archive
- Maintains searchability while optimizing active storage
- Auto-restores when accessed
### Reasoning
1. **Choose the right mode**:
- `analytical`: For logical, data-driven problems
- `creative`: For innovation and brainstorming
- `critical`: For evaluation and risk assessment
- `synthetic`: For integration and holistic views
- `parallel`: For complex decisions requiring multiple perspectives
2. **Provide context**: Background, constraints, and goals improve reasoning quality
3. **Use systematic analysis**: For complex problems, use `analyze_systematically` with framework selection
### Metacognitive Tools
1. **Assess confidence before decisions**: Use `assess_confidence` for important decisions
2. **Check for biases**: Run `detect_bias` on reasoning before finalizing conclusions
3. **Consider emotional context**: Use `detect_emotion` when emotional factors are relevant
---
## Recommended Memory Content Formatting
For optimal organization, retrieval, and readability, memory content should be stored in **markdown format**. Markdown provides structure that enhances both human readability and semantic search accuracy.
### Why Markdown?
1. **Structured Content**: Headers, lists, and sections make memories easier to parse and understand
2. **Better Retrieval**: Well-structured content improves embedding quality and search relevance
3. **Consistent Organization**: Standard formatting across memories enables predictable patterns
4. **Rich Formatting**: Code blocks, links, and emphasis preserve important details
### Formatting Guidelines
- Use **headers** (`#`, `##`, `###`) to structure sections
- Use **lists** (`-` or `1.`) for enumerated items or key points
- Use **code blocks** (`` ` `` or ` ``` `) for code snippets, commands, or technical content
- Use **bold** (`**text**`) and _italic_ (`*text*`) for emphasis
- Use **links** (`[text](url)`) for references
- Keep content focused and concise within each memory
### Markdown Examples by Memory Sector
#### Episodic Memories (Events and Experiences)
Episodic memories capture temporal events, experiences, and contextual information.
```markdown
# Meeting: Q1 Planning Session
## Date
2025-01-15, 2:00 PM - 4:00 PM
## Participants
- Sarah (Product Lead)
- Mike (Engineering Manager)
- Lisa (Design Lead)
## Key Decisions
1. Prioritize mobile app development for Q1
2. Delay analytics dashboard to Q2
3. Hire two additional frontend developers
## Action Items
- [ ] Sarah: Draft mobile app requirements by Jan 20
- [ ] Mike: Create hiring plan by Jan 18
- [ ] Lisa: Prepare mobile UI mockups by Jan 25
## Context
This was a follow-up to the December strategy review. Team expressed concerns about timeline but agreed on priorities.
```
#### Semantic Memories (Facts and Knowledge)
Semantic memories store factual information, concepts, and general knowledge.
````markdown
# PostgreSQL Connection Pooling
## Overview
Connection pooling maintains a cache of database connections for reuse, reducing connection overhead.
## Key Concepts
- **Pool Size**: Maximum concurrent connections (recommended: 20-50)
- **Idle Timeout**: Time before unused connections are closed
- **Connection Lifetime**: Maximum age of a connection before recycling
## Best Practices
1. Set pool size based on expected concurrent users
2. Use connection timeouts to prevent resource exhaustion
3. Monitor pool metrics for optimization
## Configuration Example
```typescript
const pool = new Pool({
max: 20,
idleTimeoutMillis: 30000,
connectionTimeoutMillis: 2000,
});
```
````
## Related Topics
- Database performance optimization
- Query caching strategies
- Load balancing
````
#### Procedural Memories (How-To and Processes)
Procedural memories capture step-by-step processes, skills, and methodologies.
```markdown
# How to Deploy to Production
## Prerequisites
- Access to production AWS account
- Approved PR merged to main branch
- All tests passing in CI
## Steps
### 1. Prepare Release
```bash
git checkout main
git pull origin main
npm run build
npm run test:qa
````
### 2. Create Release Tag
```bash
git tag -a v1.2.3 -m "Release v1.2.3"
git push origin v1.2.3
```
### 3. Deploy to Staging
1. Navigate to GitHub Actions
2. Run "Deploy to Staging" workflow
3. Verify staging environment at staging.example.com
### 4. Production Deployment
1. Run smoke tests on staging
2. Get approval from on-call engineer
3. Run "Deploy to Production" workflow
4. Monitor dashboards for 30 minutes
## Rollback Procedure
If issues occur:
```bash
./scripts/rollback.sh v1.2.2
```
## Contacts
- On-call: #ops-oncall Slack channel
- Escalation: ops-lead@example.com
````
#### Emotional Memories (Feelings and Experiences)
Emotional memories capture affective experiences, sentiments, and emotional context.
```markdown
# User Feedback: Frustration with Onboarding
## Emotional Context
**Primary Emotion**: Frustration
**Intensity**: High
**Trigger**: Complex setup process
## User Quotes
> "I spent 2 hours just trying to connect my account. This is ridiculous."
> "Why do I need to configure 5 different settings before I can even start?"
## Observed Patterns
- Users abandon onboarding at step 3 (API configuration)
- Support tickets spike on Mondays (new user signups)
- Negative sentiment correlates with setup time > 15 minutes
## Emotional Impact
- **User Trust**: Decreased confidence in product
- **Brand Perception**: "Complicated" and "developer-only"
- **Churn Risk**: High for users who struggle with setup
## Recommended Response
1. Simplify onboarding to 3 steps maximum
2. Add progress indicator with time estimates
3. Provide "quick start" option with sensible defaults
````
#### Reflective Memories (Insights and Meta-Observations)
Reflective memories capture insights, lessons learned, and meta-level observations.
```markdown
# Insight: Why Our Estimates Are Always Wrong
## Observation
Sprint velocity has been 30-40% below estimates for 6 consecutive sprints.
## Root Causes Identified
1. **Optimism Bias**: We estimate for best-case scenarios
2. **Hidden Dependencies**: Integration work consistently underestimated
3. **Context Switching**: Meetings and interruptions not factored in
4. **Technical Debt**: Legacy code complexity surprises us
## Pattern Recognition
- Backend tasks: Estimates accurate within 20%
- Frontend tasks: Estimates off by 50%+
- Integration tasks: Estimates off by 100%+
## Lessons Learned
1. Add 50% buffer to frontend estimates
2. Double integration task estimates
3. Include "discovery time" for unfamiliar codebases
4. Break tasks into smaller units (< 4 hours)
## Applied Changes
- Introduced planning poker with historical reference
- Created estimation checklist for common pitfalls
- Added "uncertainty factor" field to task tracking
## Results After Changes
Sprint velocity improved to within 15% of estimates after implementing these changes.
```
### Tips for Effective Memory Content
1. **Be Specific**: Include concrete details, dates, names, and numbers
2. **Add Context**: Explain why information matters, not just what it is
3. **Use Consistent Structure**: Similar memories should follow similar formats
4. **Include Relationships**: Reference related memories, topics, or concepts
5. **Update Over Time**: Revise memories as understanding evolves
6. **Tag Appropriately**: Use metadata keywords and tags for discoverability
### Example: Well-Structured vs. Poorly-Structured Memory
**❌ Poorly Structured:**
```
talked to john about the api thing. he said we should use rest not graphql. something about caching. need to follow up.
```
**✅ Well Structured:**
```markdown
# Technical Decision: REST vs GraphQL for Public API
## Decision
Use REST API instead of GraphQL for the public API.
## Rationale
- **Caching**: REST enables HTTP-level caching (CDN, browser)
- **Simplicity**: Most integrators familiar with REST patterns
- **Tooling**: Better OpenAPI/Swagger documentation support
## Decision Maker
John Smith (API Architect) - discussed 2025-01-10
## Follow-up Required
- [ ] Draft REST API specification
- [ ] Review with frontend team
- [ ] Update API documentation
## Related
- See also: Internal API design (uses GraphQL)
- Reference: API Design Guidelines document
```
---
## See Also
- **[API Reference](api.md)** - Internal API documentation
- **[Architecture Guide](architecture.md)** - System architecture
- **[User Guide](user-guide.md)** - Getting started guide
- **[Examples](examples.md)** - Usage examples
---
**Last Updated**: December 2025
**Version**: 0.5.0
