project-thoth

Thoth is a local-first, extensible research assistant that exposes an MCP-based API for tool integration and dynamic configuration. The server orchestrates a set of services including an LLM router, a discovery engine, a knowledge base, and Letta-based memory, all accessible through natural-language commands via the MCP tools. You interact with Thoth primarily through the thoth CLI and the nearby Obsidian plugin; the agent can read and modify prompts, templates, schemas, and queries to tailor your workflow. Typical use includes starting the services, querying for papers, updating discovery rules, and refining your research questions via natural language, which the agent translates into MCP tool calls and memory edits. The included setup wizard and the 4-core tool baseline let you begin typing commands to add new sources, adjust extraction schemas, or switch document analysis backends without manually editing configuration files.

Prerequisites:

• Python 3.12+ installed on your system
• Obsidian installed (for vault access)
• Optional Docker if you prefer containerized setup

Install steps:

1. Clone the repository: git clone https://github.com/acertainKnight/project-thoth.git cd project-thoth

2. Create a Python virtual environment and install dependencies: python -m venv venv source venv/bin/activate # on macOS/Linux venv\Scripts\activate # on Windows pip install -r requirements.txt

3. Configure environment variables (example): export OBSIDIAN_VAULT_PATH="/path/to/your/obsidian/vault" export DB_CONNECTION_STRING="postgresql://user:password@localhost:5432/thoth" export THOTH_API_PORT="8082" export LETTA_API_URL="http://localhost:8283"

4. Run the MCP server: python -m project_thoth.mcp_server

Alternatively, using Docker:

1. Build or pull the container image (if provided by the project): docker pull acertainknight/project-thoth

2. Run the container with proper environment mappings: docker run -it --rm
   -p 8082:8082
   -e OBSIDIAN_VAULT_PATH="/path/to/your/obsidian/vault"
   -e DB_CONNECTION_STRING="postgresql://user:password@localhost:5432/thoth"
   -e LETTA_API_URL="http://localhost:8283"
   acertainknight/project-thoth

3. Access the API and CLI tools as described in the project docs.

Tips and notes:

• The agent is designed to be controlled via natural language through MCP tools; you can ask it to add or modify sources, adjust extraction schemas, or redirect document analysis to a different LLM provider.
• Memory is persistent via Letta; memory blocks are updated through tool calls and survive restarts.
• If you encounter port conflicts, adjust THOTH_API_PORT and corresponding client configurations.
• The Obsidian plugin and CLI work in tandem; use thoth start/stop/status to manage services. If using Docker, ensure Docker is running before starting the wizard or services.
• For troubleshooting, check logs for MCPServer and Letta integration endpoints; verify that the Letta REST API is reachable at the configured URL.
• You can customize prompts, templates, and schemas via natural language using the MCP tools, or edit files manually for advanced users.