Atom Of Thoughts Rs
Atom of Thoughts (AoT) MCP is a server that decomposes complex problems into independent atomic units of thought, using the dependencies between these units to deliver more robust reasoning and validated insights.
Ask AI about Atom Of Thoughts Rs
Powered by Claude Β· Grounded in docs
I know everything about Atom Of Thoughts Rs. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Atom of Thoughts (AoT) MCP Server - Rust Implementation
π§ Overview
Atom of Thoughts (AoT) is a server that decomposes complex problems into independent atomic units of thought, using the dependencies between these units to deliver more robust reasoning and validated insights. This Rust implementation provides an MCP (Model Context Protocol) server that can be integrated with AI assistants for enhanced reasoning capabilities.
Unlike traditional sequential thinking, AoT enables more powerful problem solving by allowing atomic units of thought to form dependencies with each other, creating a graph of reasoning that can be verified, decomposed, and contracted.
β¨ Key Features
- Atomic Reasoning Units: Five distinct atom types for different reasoning stages
- Decomposition-Contraction Mechanism: Break down complex atoms into simpler sub-atoms and contract back after verification
- Dependency Tracking: Manage relationships between reasoning units
- Automatic Termination: Stop reasoning when maximum depth reached or high-confidence conclusion found
- Confidence Scoring: Each atom has a confidence level (0-1) with visual feedback
- MCP Integration: Full Model Context Protocol server implementation
- Two Server Modes: Full AoT (depth 5) and AoT-light (depth 3, faster processing)
- Command Interface: Control decomposition, check termination, get best conclusions
π Quick Start
Prerequisites
- Rust 1.70 or later
- Cargo (comes with Rust)
Installation
# Clone the repository
git clone https://github.com/yourusername/Atom_of_Thoughts_rs.git
cd Atom_of_Thoughts_rs
# Build the project
cargo build --release
# Run tests to verify everything works
cargo test
Running the MCP Server
# Run in debug mode
cargo run
# Run release build for better performance
cargo run --release
The server runs on stdio transport and is ready to accept MCP requests.
π Debugging and Logging
The AoT server uses the standard Rust log crate with env_logger for flexible logging control. Logging is configured via environment variables and supports multiple log levels.
Environment Variables
-
RUST_LOG: Controls log level and filtering (standardenv_loggervariable)- Example:
export RUST_LOG=debug - Levels:
error,warn,info,debug,trace - Can filter by crate:
export RUST_LOG=atom_of_thoughts_rs=debug,info
- Example:
-
AOT_DEBUG: Backward compatibility - maps toRUST_LOG=debugwhen set- Example:
export AOT_DEBUG=1 - Accepts:
1,true,on,yes - Only used if
RUST_LOGis not already set
- Example:
Log Output
Logs are written to standard error (stderr) with the following format:
[timestamp] LEVEL crate::module message
Example output:
[2026-03-01T17:22:32Z INFO atom_of_thoughts_rs::mcp] Starting MCP server
[2026-03-01T17:22:32Z DEBUG atom_of_thoughts_rs::mcp] ServerHandler::get_info called
[2026-03-01T17:22:33Z DEBUG atom_of_thoughts_rs] P1 | premise | Depth: 0 | Dependencies: none | Confidence: 90.00% | Verified: β
[2026-03-01T17:22:33Z INFO atom_of_thoughts_rs] SERVER EVENT: atom_created - premise: P1
Log Levels
error: Critical errors that prevent operationwarn: Warnings about potential issues (e.g., max depth reached)info: General server events, startup, verification, contractiondebug: Atom processing details, decomposition events, dependenciestrace: Verbose atom structure dumps and detailed internal state
Usage Examples
# Basic debug logging
export RUST_LOG=debug
cargo run
# Filter by crate for cleaner output
export RUST_LOG=atom_of_thoughts_rs=debug
cargo run
# Backward compatibility with AOT_DEBUG
export AOT_DEBUG=1
cargo run
# Different log levels
export RUST_LOG=error # Only errors
export RUST_LOG=info # Default informational messages
export RUST_LOG=debug # Debug information
export RUST_LOG=trace # Very verbose output
π§© Atom Types
AoT uses five distinct atom types, each with a specific role in the reasoning process:
| Atom Type | Symbol | Color | Purpose |
|---|---|---|---|
| Premise | π | Blue | Basic assumptions or given information for problem solving |
| Reasoning | π§ | Green | Logical reasoning process based on other atoms |
| Hypothesis | π‘ | Yellow | Proposed solutions or intermediate conclusions |
| Verification | β | Magenta | Process to evaluate validity of other atoms (especially hypotheses) |
| Conclusion | π | Red | Verified hypotheses or final problem solutions |
Each atom has:
- atomId: Unique identifier (e.g., "P1", "H2", "C3")
- content: Text description of the atom
- dependencies: List of atom IDs this atom depends on
- confidence: Confidence score between 0.0 and 1.0
- isVerified: Whether this atom has been verified
- depth: Depth level in the decomposition tree (0 = root)
π§ MCP Tools
The server exposes three MCP tools:
1. AoT Tool (Full Implementation)
Name: AoT
Description: Full Atom of Thoughts implementation for complex reasoning tasks.
When to use:
- Solving problems requiring complex reasoning
- Generating hypotheses that need verification from multiple perspectives
- Deriving high-confidence conclusions in critical tasks
- Decision-making requiring multiple verification steps
- Minimizing logical errors
Parameters:
atomId: Unique identifier for the atom (required)content: Actual content of the atom (required)atomType: Type of atom: "premise", "reasoning", "hypothesis", "verification", "conclusion" (required)dependencies: List of IDs of other atoms this atom depends on (required, can be empty array)confidence: Confidence level between 0-1 (required)isVerified: Whether this atom has been verified (optional, defaults to false)depth: Depth level in decomposition-contraction mechanism (optional, auto-calculated)
Max Depth: 5 levels
Important Notes:
- Conclusions must be verified (
isVerified: true) to appear inbest_conclusionresults - To verify a conclusion, either create it with
isVerified: trueor create a verification atom that depends on it - Verification atoms with
isVerified: trueautomatically verify atoms listed in theirdependencies - The
atomcommandstool works with atoms created using theAoTtool (notAoT-light)
2. AoT-light Tool (Fast Processing)
Name: AoT-light
Description: Lightweight version for faster processing and quicker results.
When to use:
- Quick brainstorming sessions
- Time-sensitive problem solving
- Simpler reasoning tasks
- Initial exploration before using full AoT
- Learning or demonstration purposes
Key differences:
- Lower maximum depth (3 instead of 5)
- Simplified verification process
- Immediate conclusion suggestion for high-confidence hypotheses
- Reduced computational overhead
- Optimized for speed rather than exhaustive analysis
Parameters: Same as full AoT tool
Important Notes:
- AoT-light uses a separate server instance from full AoT
- Atoms created with AoT-light are not visible to the
atomcommandstool - For decomposition features or
best_conclusionwith AoT-light atoms, use the full AoT tool instead - High-confidence hypotheses (confidence β₯ 0.8) trigger automatic conclusion suggestions
3. Atom Commands Tool (Advanced Control)
Name: atomcommands
Description: Command tool to control decomposition-contraction mechanism and automatic termination.
Commands:
decompose: Decompose a specified atom into smaller sub-atomscomplete_decomposition: Complete an ongoing decomposition processtermination_status: Check termination status of current AoT processbest_conclusion: Get the verified conclusion with highest confidenceset_max_depth: Change the maximum depth limit
Parameters:
command: Command to execute (required)atomId: Atom ID (required fordecomposecommand)decompositionId: ID of decomposition process (required forcomplete_decomposition)maxDepth: Maximum depth value (required forset_max_depth)
Important Notes:
best_conclusiononly returns verified conclusions (isVerified: true)atomcommandsworks with the full AoT server, not AoT-light server- To use
best_conclusionwith AoT-light atoms, recreate them using the full AoT tool - Conclusions must be verified to appear in results (set
isVerified: trueor use verification atoms)
π Decomposition-Contraction Mechanism
Decomposition Process
- Start Decomposition: Break down a complex atom (usually a hypothesis) into simpler sub-atoms
- Add Sub-atoms: Automatically or manually add atoms to the decomposition
- Calculate Depth: Sub-atoms get depth = parent depth + 1
- Complete Decomposition: Mark decomposition as ready for contraction
Contraction Process
- Verification: When verification atoms verify hypotheses
- Check Conditions: All sub-atoms must be verified and decomposition completed
- Calculate Confidence: Average confidence of sub-atoms
- Update Original: Original atom gets updated confidence and marked as verified
- Suggest Conclusion: If verified hypothesis has confidence β₯ 0.8, suggest a conclusion
Automatic Features
- Auto-add to decomposition: New atoms automatically added to current decomposition
- Auto-termination: Terminates when max depth reached or strong conclusion found (confidence β₯ 0.9)
- Auto-conclusion: Suggests conclusions for verified hypotheses with confidence β₯ 0.8
- Auto-verification: Verification atoms automatically verify their dependencies
π Usage Examples
Example 1: Basic Reasoning Chain
{
"atomId": "P1",
"content": "The user wants to find restaurants near them",
"atomType": "premise",
"dependencies": [],
"confidence": 0.9
}
{
"atomId": "R1",
"content": "We need to get the user's location first",
"atomType": "reasoning",
"dependencies": ["P1"],
"confidence": 0.8
}
{
"atomId": "H1",
"content": "Ask the user for their location or use IP geolocation",
"atomType": "hypothesis",
"dependencies": ["R1"],
"confidence": 0.7
}
Example 2: Verification and Conclusion
{
"atomId": "V1",
"content": "IP geolocation is less accurate but faster; asking is more accurate but requires interaction",
"atomType": "verification",
"dependencies": ["H1"],
"confidence": 0.85,
"isVerified": true
}
{
"atomId": "C1",
"content": "Use IP geolocation for quick results, then ask for precise location if needed",
"atomType": "conclusion",
"dependencies": ["H1"],
"confidence": 0.77
}
Example 3: Decomposition Command
{
"command": "decompose",
"atomId": "H1"
}
Example 4: Get Termination Status
{
"command": "termination_status"
}
π§ͺ Testing
The project includes comprehensive unit tests:
# Run all tests
cargo test
# Run tests with output visible
cargo test -- --nocapture
# Run specific test
cargo test test_decomposition_flow
# Run all tests and show output
cargo test -- --show-output
Test coverage includes:
- Atom type functionality
- Server initialization
- Atom processing and validation
- Decomposition flow
- Verification and contraction
- Termination logic
- Best conclusion retrieval
- Light server functionality
ποΈ Project Structure
Atom_of_Thoughts_rs/
βββ Cargo.toml # Rust dependencies and metadata
βββ Cargo.lock # Dependency lock file
βββ README.md # This file
βββ AGENTS.md # Agent guidelines and conventions
βββ memory.ms # Project information and design notes
βββ refference.ts # TypeScript reference implementation
βββ src/
β βββ lib.rs # Core library implementation
β βββ main.rs # Binary entry point with logging setup
βββ target/ # Build artifacts (generated)
Key Components in lib.rs:
-
Data Structures:
AtomType: Enum with five atom typesAtomData: Core atom structure with all fieldsDecompositionState: Tracks decomposition progressTerminationStatus: Termination condition and reason
-
Core Servers:
AtomOfThoughtsServer: Full implementation with max depth 5AtomOfThoughtsLightServer: Lightweight version with max depth 3
-
Error Handling:
AtomError: Comprehensive error enum with descriptive messagesResult<T>: Type alias forResult<T, AtomError>
-
MCP Integration:
AtomOfThoughtsMcpHandler: MCP server handler with three toolsAtomRequest: Schema for atom creation requestsAtomCommandsRequest: Schema for command requests
-
Core Algorithms:
- Decomposition management
- Contraction triggering
- Confidence calculation
- Termination checking
- Dependency validation
-
Logging System:
- Standard
logcrate withenv_loggerintegration - Environment variable controlled log levels (
RUST_LOG) - Backward compatibility with
AOT_DEBUGvariable - Multiple log levels: error, warn, info, debug, trace
- Structured log output with timestamps and crate/module information
- Standard
π Development
Code Style
- Follows Rust 2024 edition
- Uses
cargo fmtfor consistent formatting cargo clippy -- -D warningsfor linting- Comprehensive documentation with doc comments
Building
# Debug build
cargo build
# Release build
cargo build --release
# Type checking without building
cargo check
# Generate documentation
cargo doc --open
Dependencies
- rmcp: Model Context Protocol implementation (v0.17)
- serde/serde_json: JSON serialization
- anyhow: Error handling
- thiserror: Custom error types
- tokio: Async runtime
- chrono: DateTime handling
- colored: Terminal output coloring
- log: Logging facade
- env_logger: Environment-based logging configuration
π Output Format
Atoms are displayed with colored, formatted output:
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β π‘ HYPOTHESIS:H1 [Depth: 0/5] (β Verified) β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Ask the user for their location or use IP geolocation β
β Confidence: [ββββββββββββββββββββ] 80% β
β Dependencies: R1 β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Features:
- Colored headers based on atom type
- Confidence bar visualization
- Depth information
- Verification status
- Dependency listing
π― When to Use AoT
Ideal Use Cases
- Complex Decision Making: Multiple factors, uncertain outcomes
- Problem Solving: Breaking down complex problems into manageable parts
- Hypothesis Testing: Generating and verifying multiple hypotheses
- Risk Assessment: Evaluating different scenarios with confidence scores
- Planning: Step-by-step reasoning with verification at each stage
Comparison: AoT vs AoT-light
| Aspect | AoT (Full) | AoT-light |
|---|---|---|
| Max Depth | 5 | 3 |
| Processing | Comprehensive | Fast |
| Verification | Multi-step | Immediate |
| Use Case | Critical decisions | Quick reasoning |
| Output Detail | Full analysis | Essential only |
| Auto-features | All enabled | Simplified |
π€ Contributing
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes
- Run tests:
cargo test - Format code:
cargo fmt - Check lints:
cargo clippy -- -D warnings - Commit changes:
git commit -m 'Add amazing feature' - Push to branch:
git push origin feature/amazing-feature - Open a Pull Request
Development Guidelines
- Follow existing code style and conventions
- Add tests for new functionality
- Update documentation as needed
- Keep commits focused and atomic
- Reference issues in commit messages
π License
This project is licensed under the MIT License - see the LICENSE file for details.
π Acknowledgments
- Based on the original Atom of Thoughts concept
- Uses the Model Context Protocol (MCP) for AI tool integration
- Inspired by decomposition-contraction mechanisms in cognitive architectures
π Resources
Built with β€οΈ using Rust
Decompose. Reason. Validate.
