Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/S1LV4/th0th/llms.txt

Use this file to discover all available pages before exploring further.

​
What is th0th?

th0th is an infrastructure tool that brings semantic code search and intelligent context compression to AI assistants. Named after the ancient Egyptian god of knowledge, th0th helps AI systems understand and navigate codebases with unprecedented efficiency.
th0th achieves 98% token reduction through semantic compression while preserving code structure and meaning.

​
Why th0th?

Modern AI assistants face a critical challenge: context window limitations. When working with large codebases, you need to provide relevant context without overwhelming the AI with excessive tokens. th0th solves this through:

Semantic Search

Hybrid vector + keyword search with RRF ranking finds the exact code you need

Smart Compression

Rule-based compression keeps code structure while removing unnecessary details

Persistent Memory

SQLite-based storage remembers important context across sessions

Zero Cost

100% offline operation with Ollama - no API costs

​
Key Features

​
Hybrid Search Engine

th0th combines semantic understanding with traditional keyword search:
  • Vector embeddings for semantic similarity
  • Keyword search for exact matches
  • RRF (Reciprocal Rank Fusion) ranking for optimal results
  • Multi-level caching for instant responses
// From: packages/core/src/data/vector/hybrid-search.ts
// Combines vector and keyword search with RRF ranking
const results = await hybridSearch({
  query: "authentication middleware",
  projectId: "my-app",
  maxResults: 10,
  minScore: 0.3
});

​
Context Compression

Reduce tokens by 70-98% without losing critical information:
  • Code structure extraction - preserves signatures, removes implementation
  • Semantic deduplication - removes redundant content
  • Hierarchical compression - keeps important details, summarizes the rest
# From: README.md
curl -X POST http://localhost:3333/api/v1/context/compress \
  -H "Content-Type: application/json" \
  -d '{"content": "...", "strategy": "code_structure"}'

​
Persistent Memory System

Store and recall information across AI sessions:
  • Hierarchical organization by user, project, session, and agent
  • Semantic search through memories
  • Importance scoring for prioritization
  • Type-based filtering (preferences, decisions, patterns, code)
# From: README.md
curl -X POST http://localhost:3333/api/v1/memory/store \
  -H "Content-Type: application/json" \
  -d '{"content": "Important decision...", "type": "decision"}'

​
Architecture Overview

th0th is built as a monorepo with three main components: 
th0th/
├── apps/
│   ├── mcp-client/           # MCP Server (stdio)
│   ├── tools-api/            # REST API (port 3333)
│   └── opencode-plugin/      # OpenCode plugin
├── packages/
│   ├── core/                 # Business logic
│   └── shared/               # Shared utilities
└── scripts/

​
Component Breakdown

1

Semantic Search

Hybrid vector + keyword search with RRF ranking for precise code discovery
2

Embeddings

Flexible provider system supporting Ollama (local), Mistral, and OpenAI
3

Compression

Rule-based code structure extraction achieving 70-98% token reduction
4

Memory

Persistent SQLite storage for cross-session context preservation
5

Cache

Multi-level L1/L2 caching with TTL for optimal performance

​
How It Works

1

Index Your Project

th0th scans your codebase, generates embeddings, and builds search indices
curl -X POST http://localhost:3333/api/v1/project/index \
  -H "Content-Type: application/json" \
  -d '{"projectPath": "/home/user/my-project", "projectId": "my-project"}'
2

Search Semantically

Ask questions in natural language or use keywords to find relevant code
curl -X POST http://localhost:3333/api/v1/search/project \
  -H "Content-Type: application/json" \
  -d '{"query": "authentication", "projectId": "my-project"}'
3

Compress Context

Reduce token usage while preserving essential structure and meaning
curl -X POST http://localhost:3333/api/v1/context/compress \
  -H "Content-Type: application/json" \
  -d '{"content": "...", "strategy": "code_structure"}'
4

Remember Important Info

Store decisions, patterns, and context for future sessions
curl -X POST http://localhost:3333/api/v1/memory/store \
  -H "Content-Type: application/json" \
  -d '{"content": "User prefers TypeScript", "type": "preference"}'

​
Use Cases

​
Code Discovery

Find relevant code across large codebases using natural language:
  • “Where is authentication handled?”
  • “Show me database migration logic”
  • “Find API route handlers”

​
Context Optimization

Provide AI assistants with precise context while minimizing tokens:
  • Compress large files to their essential structure
  • Filter search results to specific patterns
  • Combine search + compression in one call

​
Session Continuity

Maintain context across multiple AI sessions:
  • Remember user preferences and coding style
  • Recall architectural decisions
  • Track important patterns and conventions

​
Embedding Providers

th0th supports multiple embedding providers to fit your needs:
ProviderModelCostQuality
Ollama (default)nomic-embed-text, bge-m3FreeGood
Mistralmistral-embed, codestral-embed$$Great
OpenAItext-embedding-3-small$$Great
The default Ollama setup is 100% offline with zero API costs.

​
Available Tools

th0th exposes 8 core tools through the MCP interface:
ToolDescription
th0th_indexIndex a project directory for semantic search
th0th_index_statusCheck background indexing job progress
th0th_searchSemantic + keyword search with filters
th0th_rememberStore important information in persistent memory
th0th_recallSearch stored memories from previous sessions
th0th_compressCompress context (keeps structure, removes details)
th0th_optimized_contextSearch + compress in one call (max efficiency)
th0th_analyticsUsage patterns, cache performance, metrics
All tools are available via both REST API and MCP protocol.

​
Next Steps

Quickstart

Get th0th running in under 5 minutes

Installation

Detailed installation instructions for all platforms

OpenCode Integration

Connect th0th to your AI assistant

REST API

Explore the HTTP API endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us