Documentation
ThinkableSpace builds a private knowledge base from your files and resources. Connect it to your AI assistant via MCP and search your documents without sending them to the cloud.
Quickstart
- 1
Download ThinkableSpace
Choose your platform from our downloads page
- 2
Install and complete first-time setup
Install the app and let it download the local AI model it needs to index documents
- 3
Add your files
Import files, drag them in, or place them in your sync folder (location varies by OS — see the Add Files section)
- 4
Connect your AI assistant
Copy the MCP configuration from Settings → MCP Server and paste it into your AI assistant
Video Tutorials
Step-by-step video guides covering installation, setup, and connecting ThinkableSpace to your AI tools.
Watch the full playlist on YouTube to get up and running quickly.
What ThinkableSpace Does
ThinkableSpace builds a private knowledge base from files and resources you choose. After a file is indexed, an AI assistant connected through MCP can search it and use relevant passages in its answers.
Supported File Types
| Type | Extensions |
|---|---|
| Documents | .pdf .docx .odt .rtf .epub |
| Text and notes | .txt .md |
| Tables | .csv |
| Code & config | .go .js .ts .py .java .rs .json .yaml .sql .html .css and more |
| Audio & video | .mp3 .wav .m4a .mp4 .webm License required |
Web pages, YouTube videos, and pasted text are also supported with an active license.
Installation
Follow the platform-specific instructions below to install ThinkableSpace on your system.
macOS
- Download the
.dmgfrom the downloads page - Open the downloaded DMG file
- Drag ThinkableSpace.app to Applications
- Open ThinkableSpace from Applications, Launchpad, or Spotlight
If macOS blocks the first launch, right-click ThinkableSpace.app, choose Open, then confirm.
Windows
- Download the Windows installer from the downloads page
- Run the installer and follow the setup wizard
- If Windows Defender SmartScreen appears, click More info then Run anyway
- On first launch, the app will download the local model — allow this to complete
- If Windows Firewall prompts you, click Allow access to enable local search
- Launch ThinkableSpace from the Start Menu or desktop shortcut
Linux
Download the .deb package from the downloads page.
- Double-click the .deb file to open in Ubuntu Software, then click Install
- Or install via terminal:
sudo dpkg -i ThinkableSpace-*.deb - Launch ThinkableSpace from your application menu
App data is stored under .config/thinkablespace in your user profile.
First-Time Setup
On first launch, ThinkableSpace downloads the local AI model it needs to index documents. This model is stored on your computer and is used for search.
When setup finishes, click Get Started.
If the download fails
- Check your internet connection
- Make sure you have enough free disk space
- Click Retry
- Reopen ThinkableSpace if the wizard does not continue
You can reinstall the model later from Settings → AI Models Add-On → Embedding Model → Reinstall Model.
Add Files
You can add files in three ways.
Import File
Click Import File in the toolbar and choose one or more supported files. ThinkableSpace copies the selected files into your sync folder, then indexes them.
Drag and Drop
Drag supported files onto the Sync Files table. ThinkableSpace copies them into your sync folder and indexes them.
Sync Folder
Move or copy files into your ThinkableSpace sync folder. If Auto-sync is enabled, ThinkableSpace finds new and changed files automatically.
Default sync folder location:
~/Documents/ThinkableSpace%USERPROFILE%\Documents\ThinkableSpace~/Documents/ThinkableSpaceYou can change the folder at any time from Settings → Sync Folder → Choose Folder.
Add Resources
With an active license, click Add Resource to add web pages, YouTube videos, and notes.
| Tab | Use it for |
|---|---|
| Web URL | A web page you want indexed |
| YouTube | A public YouTube video (transcribed locally) |
| Plain Text | Text you paste or type directly into ThinkableSpace |
YouTube resources and audio/video files are transcribed locally. If the transcription model is missing, ThinkableSpace will prompt you to download it. Manage it from Settings → AI Models Add-On → Audio Transcription.
Without an active license, Add Resource shows an Activate License prompt.
Manage Your Files
The Home page shows the Sync Files table with the file name, size, status, last modified time, and a count of indexed text pieces. Use Search files... to filter the list.
Row Actions
| Action | What it does |
|---|---|
| View File | Opens the file or saved resource |
| Re-Sync | Indexes the file again |
| Delete | Removes the file from ThinkableSpace and deletes the copied file |
Use Delete carefully. Imported and synced files are copied into the sync folder, and deleting from the table removes that copied file along with its index data.
To remove only the index data while keeping files, use Settings → Data Management → Clear Index, then re-enable Auto-sync or click Sync Now.
Sync Folder
Open Settings → Sync Folder to manage the folder ThinkableSpace watches.
- Click Choose Folder to use a different folder
- Turn Auto-sync on or off
- Click Sync Now to scan the folder immediately
- Use Reset to return sync settings to their defaults
When Auto-sync is on, ThinkableSpace indexes new and changed files. If files are deleted from the sync folder, they are removed from the knowledge base.
Connect an AI Assistant
ThinkableSpace uses MCP (Model Context Protocol) — the standard way AI assistants search your local knowledge base.
General Setup (Claude Desktop and other MCP clients)
- Keep ThinkableSpace running
- Open Settings → MCP Server
- Copy the MCP configuration block
- Paste it into your AI assistant's MCP settings
- Restart or reload the AI assistant if prompted
Default local MCP address:
http://127.0.0.1:8443/mcpThinkableSpace creates an access token automatically. If you generate a new token, update any AI assistant that uses the old one.
Claude Code
- Launch ThinkableSpace
- Open Claude Code Settings
- Find the MCP servers section
- Add the ThinkableSpace MCP URL
- Restart Claude Code
OpenAI
- Launch ThinkableSpace
- Open your OpenAI-compatible client
- Configure MCP with the server details
- Test the connection
Gemini
- Launch ThinkableSpace
- Access Google AI Studio or Gemini client
- Add the MCP server URL
- Authorize the connection
Cloudflare Tunnel
Cloudflare Tunnel is optional. It creates a public HTTPS address for ThinkableSpace so remote AI assistants can connect.
Use a tunnel only for AI assistants you trust. Your files stay on your computer, but the remote assistant can send search queries and receive matching text snippets.
Auto-Generated Tunnel
- Open Settings → Cloudflare Tunnel
- Choose Auto-generated by Cloudflare
- Click Connect Cloudflare
- Copy the public MCP configuration when the tunnel is running
Auto-generated tunnels are temporary and stop when the app closes.
Custom Domain Tunnel
- Open Settings → Cloudflare Tunnel
- Choose Custom domain
- Click Connect Cloudflare and sign in through the browser
- Enter the tunnel name and hostname
- Click Create Tunnel
- Use Start Tunnel and Stop Tunnel as needed
Custom domain tunnels require a domain in your Cloudflare account and may require an active license.
Remote Approvals
When a remote AI assistant connects through a tunnel, ThinkableSpace can show an approval prompt. Approved assistants appear in Settings → Connected Clients, where you can revoke access.
License & Limits
Activate a License
- Open Settings → License
- Enter the email address and license key from your purchase
- Click Activate License
To remove the license from this computer, open Settings → License and click Deactivate.
Free vs Licensed
| Feature | Free | Licensed |
|---|---|---|
| File indexing | Up to 3 files | Unlimited |
| Local MCP server | ||
| Web & YouTube resources | ||
| Audio & video transcription | ||
| Custom domain tunnel | Restricted |
What Happens After Expiry?
App versions released before your expiry date continue to work. Newer versions may require renewal. To renew, visit our pricing page.
Settings Reference
MCP Server
Shows the local MCP address, port, access token, and copyable configuration for AI assistants. You can restart the server, change the port, reset to default, or generate a new token.
Cloudflare Tunnel
Creates and manages a public tunnel for remote AI assistants.
Connected Clients
Shows remote AI assistants approved through a Cloudflare tunnel. Use Revoke to remove access.
AI Models Add-On
Manages local model downloads: Embedding Model (required for indexing and search) and Audio Transcription (required for audio, video, and YouTube transcription).
Sync Folder
Controls the watched folder, Auto-sync setting, and manual scans.
Data Management
Shows storage usage and includes Clear Index. Clearing the index removes ThinkableSpace's searchable records but does not delete files from the sync folder.
License
Shows license status and provides activation, refresh, and deactivation controls.
Help Improve ThinkableSpace
Controls anonymous error reporting when your license state allows it. File contents, search queries, and personal data are not sent.
About
Shows version information and includes Check for Updates.
Tray, Startup & Updates
Closing the main window hides ThinkableSpace and keeps it running in the system tray or menu bar. Indexing, MCP, and active tunnels continue in the background. Use Quit from the tray/menu bar menu to exit completely.
The tray/menu bar menu can open the app, Home, the sync folder, Settings, Help, notifications, feedback, and Quit.
If Start on Login is enabled, ThinkableSpace starts automatically after you sign in to your computer.
Updates
ThinkableSpace checks for updates periodically. You can also check manually from Settings → About → Check for Updates. Some updates install in the app; others may redirect to the website for a manual download. Updates do not remove your settings, models, index, or sync folder files.
Troubleshooting
Setup Keeps Appearing
The required indexing model is not installed yet.
- Check your internet connection
- Make sure you have enough free disk space
- Click Retry
- Reopen ThinkableSpace if needed
Files Do Not Appear
- Confirm the files are a supported type
- Check that the files are in the current sync folder
- Confirm Auto-sync is enabled
- Click Sync Now
- Use Import File to manually import a file
Files Are Stuck Processing
- Large files can take time
- Audio, video, and YouTube transcription can take longer than documents
- Confirm the Embedding Model is installed
- For audio/video/YouTube, confirm Audio Transcription is installed and your license is active
- Restart ThinkableSpace — pending work is queued again on launch
A File Shows Failed
Open the file menu and choose Re-Sync. If it fails again, confirm the file opens normally outside ThinkableSpace and is not password-protected or corrupted.
AI Assistant Cannot Connect
- Confirm ThinkableSpace is running
- Open Settings → MCP Server and check the server status
- Use the current MCP configuration from the app
- If you changed the token, update the AI assistant
- If the port is in use, change the port, click Save Changes, then Restart Server
Cloudflare Tunnel Does Not Connect
- Make sure the MCP server is running first
- Stop and reconnect the tunnel
- For custom domains, confirm the domain is in your Cloudflare account
- Check whether a firewall or VPN is blocking Cloudflare Tunnel
High CPU Usage
Indexing and transcription can use a lot of CPU or GPU. Usage should drop after processing finishes.
Local App Data Was Deleted
ThinkableSpace stores important app data under .config/thinkablespace. If files in that folder are deleted manually, your searchable index may not be recoverable. Include this folder in your normal system backups if the indexed data is important to you.