MCP Tools Reference

Detailed documentation for all 8 MCP tools exposed by th0th. Each tool includes parameter schemas, usage examples, and response formats.

th0th_index

Index a project directory for semantic search with embeddings.

Indexing runs asynchronously in the background. Use th0th_index_status to check progress.

Parameters

projectPath

string

required

Absolute path to the project directory to index

projectId

string

Unique identifier for the project (defaults to directory name)

forceReindex

boolean

default:false

Force reindex even if project already exists

warmCache

boolean

default:false

Pre-cache common queries after indexing for faster initial searches

warmupQueries

array

Custom queries to pre-cache (uses defaults if not provided)

Response

jobId

string

Job ID for tracking indexing progress

projectId

string

Project identifier

projectPath

string

Path to the indexed project

status

string

Current status: started, running, completed, or failed

message

string

Status message with instructions

Example usage

await th0th_index({
  projectPath: "/home/user/my-project",
  projectId: "my-project",
  forceReindex: false,
  warmCache: true
});

// Response:
// {
//   "jobId": "job_abc123",
//   "projectId": "my-project",
//   "projectPath": "/home/user/my-project",
//   "status": "started",
//   "message": "Indexing started in background. Use th0th_index_status(jobId) to check progress."
// }

th0th_index_status

Get the status and progress of a background indexing job. Use this after calling th0th_index to check if indexing has completed.

Parameters

jobId

string

required

Job ID returned from th0th_index

Response

jobId

string

Job ID being tracked

status

string

Current job status: running, completed, or failed

progress

object

Progress information (files processed, completion percentage)

projectId

string

Project identifier

error

string

Error message if status is failed

Example usage

// After indexing starts
const indexResult = await th0th_index({
  projectPath: "/home/user/my-project"
});

// Check status
const status = await th0th_index_status({
  jobId: indexResult.jobId
});

// Response:
// {
//   "jobId": "job_abc123",
//   "status": "completed",
//   "progress": {
//     "filesProcessed": 1543,
//     "totalFiles": 1543,
//     "percentComplete": 100
//   },
//   "projectId": "my-project"
// }

th0th_search

Search for code using semantic and keyword search with RRF (Reciprocal Rank Fusion) ranking.

Parameters

query

string

required

Search query (natural language or keywords)

projectId

string

required

Project ID to search in

projectPath

string

Project path (required for autoReindex)

maxResults

number

default:10

Maximum number of results to return

minScore

number

Minimum relevance score (0-1)

responseMode

string

default:"summary"

Response format: summary (preview only, saves 70% tokens) or full (includes content)

autoReindex

boolean

default:false

Automatically reindex if project index is stale (can increase latency)

include

array

Glob patterns to include (e.g., ['src/components/**/*.tsx', 'src/utils/**'])

exclude

array

Glob patterns to exclude (e.g., ['**/*.test.*', '**/*.spec.*'])

explainScores

boolean

default:false

Include detailed score breakdown (vector, keyword, RRF components)

Response

results

array

Array of search results with file paths, content, and scores

query

string

Original search query

total

number

Total number of results found

cacheHit

boolean

Whether results were served from cache

Example usage

await th0th_search({
  query: "authentication middleware",
  projectId: "my-project",
  maxResults: 5,
  responseMode: "summary",
  include: ["src/**/*.ts"],
  exclude: ["**/*.test.ts"]
});

// Returns:
// - Top 5 results matching "authentication middleware"
// - Summary mode (no full content, saves 70% tokens)
// - Only TypeScript files in src/
// - Excludes test files

th0th_remember

Store information in the hierarchical memory system backed by SQLite.

Parameters

content

string

required

Content to store

type

string

required

Type of memory: preference, conversation, code, decision, or pattern

userId

string

User ID for filtering memories

projectId

string

Project ID for project-specific memories

sessionId

string

Session ID for session-specific memories

agentId

string

Agent ID (e.g., orchestrator, implementer, architect, optimizer)

Response

string

Unique memory ID

content

string

Stored content

type

string

Memory type

createdAt

string

Timestamp when memory was created

Example usage

await th0th_remember({
  content: "User prefers TypeScript over JavaScript for new components",
  type: "preference",
  userId: "user_123",
  projectId: "my-project",
  importance: 0.8,
  tags: ["typescript", "preferences"],
  format: "toon"
});

// Stores preference in SQLite
// Returns memory ID and metadata in TOON format

th0th_recall

Search stored memories across sessions using semantic search.

Parameters

query

string

required

Search query (what to remember)

userId

string

Filter by user ID

projectId

string

Filter by project ID

sessionId

string

Filter by session ID

agentId

string

Filter by agent ID (orchestrator, implementer, architect, optimizer)

types

array

Filter by memory types: ['preference', 'conversation', 'code', 'decision', 'pattern']

limit

number

default:10

Maximum results to return

minImportance

number

Minimum importance (0-1)

includePersistent

boolean

default:true

Include persistent memories from other sessions

format

string

default:"toon"

Output format: json or toon

Response

memories

array

Array of matching memories with content, type, score, and metadata

query

string

Original search query

total

number

Total number of memories found

Example usage

await th0th_recall({
  query: "typescript preferences",
  userId: "user_123",
  projectId: "my-project",
  types: ["preference", "decision"],
  limit: 5,
  format: "toon"
});

// Returns:
// - Top 5 memories matching "typescript preferences"
// - Filtered to preference and decision types
// - TOON format (70% smaller than JSON)

th0th_compress

Compress context using semantic compression strategies.

Compression is rule-based and deterministic. It keeps structure while removing details, achieving 70-98% token reduction.

Parameters

content

string

required

Content to compress

strategy

string

default:"code_structure"

Compression strategy: code_structure, conversation_summary, semantic_dedup, or hierarchical

targetRatio

number

Target compression ratio (0-1, e.g., 0.7 = 70% reduction)

language

string

Programming language (for code compression)

Response

compressed

string

Compressed content

originalLength

number

Original content length in characters

compressedLength

number

Compressed content length in characters

originalTokens

number

Original token count

compressedTokens

number

Compressed token count

tokensSaved

number

Number of tokens saved

compressionRatio

number

Actual compression ratio achieved

Example usage

Code Structure
Conversation Summary
Semantic Dedup

await th0th_compress({
  content: `
    function processUser(user) {
      if (!user.id) throw new Error('Invalid user');
      const profile = user.profile || {};
      return {
        id: user.id,
        name: profile.name,
        email: profile.email
      };
    }
  `,
  strategy: "code_structure",
  language: "javascript"
});

// Returns structure without implementation details:
// function processUser(user) { ... }

await th0th_compress({
  content: "Long conversation thread with multiple messages...",
  strategy: "conversation_summary",
  targetRatio: 0.8
});

// Summarizes conversation, 80% reduction

await th0th_compress({
  content: "Text with repeated information...",
  strategy: "semantic_dedup"
});

// Removes semantically duplicate content

th0th_optimized_context

Retrieve and compress context with maximum token efficiency. Combines search + compression in one call.

This is the most powerful tool for AI context management. It searches, compresses, and optimizes token usage automatically.

Parameters

query

string

required

Search query to find relevant context

projectId

string

required

Project ID for code context

projectPath

string

Project path (for auto-reindex)

maxTokens

number

default:4000

Maximum tokens in returned context

maxResults

number

default:5

Maximum search results to include

Response

context

string

Optimized context (compressed and formatted)

sources

array

Array of source files included

resultsCount

number

Number of search results included

memoriesCount

number

Number of memories included

tokensSaved

number

Tokens saved by compression

compressionRatio

number

Compression ratio achieved

Example usage

await th0th_optimized_context({
  query: "authentication implementation",
  projectId: "my-project",
  maxTokens: 4000,
  maxResults: 5
});

// Returns:
// - Top 5 relevant files about authentication
// - Compressed to fit within 4000 tokens
// - Ready to use as AI context
// - Metadata: sources, token savings, compression ratio

Workflow

Search: Semantic + keyword search for relevant code
Compress: Apply code_structure compression
Optimize: Fit results within maxTokens budget
Return: Formatted context with metadata

th0th_analytics

Get usage patterns, cache performance, and search metrics.

Parameters

type

string

required

Analytics type: summary, project, query, cache, or recent

projectId

string

Project ID (required for type='project' or type='cache')

query

string

Search query (required for type='query')

limit

number

default:10

Limit for results (default: 10 for most, 50 for recent)

Response

Response varies by analytics type:

Summary
Project
Cache
Recent

{
  "totalSearches": 1234,
  "totalProjects": 5,
  "cacheHitRate": 0.67,
  "avgSearchTime": 45,
  "topProjects": [...],
  "topQueries": [...]
}

{
  "projectId": "my-project",
  "totalSearches": 456,
  "filesIndexed": 1234,
  "lastIndexed": "2026-03-09T10:30:00Z",
  "topQueries": [...]
}

{
  "l1HitRate": 0.85,
  "l2HitRate": 0.12,
  "missRate": 0.03,
  "totalQueries": 1000,
  "avgHitTime": 2,
  "avgMissTime": 45
}

{
  "searches": [
    {
      "query": "authentication",
      "projectId": "my-project",
      "timestamp": "2026-03-09T10:30:00Z",
      "cacheHit": true,
      "duration": 3
    },
    ...
  ]
}

Example usage

// Get overall summary
await th0th_analytics({ type: "summary" });

// Get project-specific stats
await th0th_analytics({ 
  type: "project",
  projectId: "my-project",
  limit: 10
});

// Get cache performance
await th0th_analytics({ 
  type: "cache",
  projectId: "my-project"
});

// Get recent searches
await th0th_analytics({ 
  type: "recent",
  limit: 50
});

Response Formats

JSON format

Standard JSON response:

{
  "success": true,
  "data": { ... },
  "metadata": { ... }
}

TOON format

Tree Object Oriented Notation (70% smaller than JSON):

# Memory
  id: mem_abc123
  content: User prefers TypeScript
  type: preference
  importance: 0.8
  tags:
    - typescript
    - preferences
  createdAt: 2026-03-09T10:30:00Z

TOON format is more readable and uses significantly fewer tokens. Set format: "toon" in memory tools to enable it.

Error handling

All tools return a consistent error format:

{
  "success": false,
  "error": "Error message here"
}

Common errors:

Project not indexed: Run th0th_index first
Invalid projectId: Check that the project exists
Missing required parameter: Check tool schema
API not reachable: Ensure th0th API is running on port 3333

Performance tips

Use summary mode

Set responseMode: "summary" in th0th_search to save 70% tokens

Enable cache warmup

Set warmCache: true in th0th_index for faster initial searches

Leverage optimized context

Use th0th_optimized_context instead of separate search + compress calls

Filter with glob patterns

Use include and exclude patterns to narrow search scope

Next steps

MCP Overview

Learn about MCP integration and setup

REST API

Use th0th via HTTP instead of MCP

REST API

MCP Tools

CLI

Documentation Index

​th0th_index

​Parameters

​Response

​Example usage

​th0th_index_status

​Parameters

​Response

​Example usage

​th0th_search

​Parameters

​Response

​Example usage

​th0th_remember

​Parameters

​Response

​Example usage

​th0th_recall

​Parameters

​Response

​Example usage

​th0th_compress

​Parameters

​Response

​Example usage

​th0th_optimized_context

​Parameters

​Response

​Example usage

​Workflow

​th0th_analytics

​Parameters

​Response

​Example usage

​Response Formats

​JSON format

​TOON format

​Error handling

​Performance tips

Use summary mode

Enable cache warmup

Leverage optimized context

Filter with glob patterns

​Next steps

MCP Overview

REST API

th0th_index

Parameters

Response

Example usage

th0th_index_status

Parameters

Response

Example usage

th0th_search

Parameters

Response

Example usage

th0th_remember

Parameters

Response

Example usage

th0th_recall

Parameters

Response

Example usage

th0th_compress

Parameters

Response

Example usage

th0th_optimized_context

Parameters

Response

Example usage

Workflow

th0th_analytics

Parameters

Response

Example usage

Response Formats

JSON format

TOON format

Error handling

Performance tips

Next steps