s1lv4/th0th-memory

th0th-memory Skill

Mandatory rules for using th0th tools. Prioritize semantic search, compression, memory, and symbol graph tools over native tools (Glob, Grep, Read) to explore and understand code.

When to Apply

Reference these guidelines when:

• Searching for code patterns or implementations
• Navigating to symbol definitions or finding all usages of a symbol
• Understanding codebase architecture
• Storing important decisions or patterns
• Compressing large code contexts
• Retrieving memories from previous sessions
• Listing or checking the status of indexed projects
• Analyzing usage and performance metrics

Available Tools

| Priority | Tool | Use | |----------|------|-----| | 1 | th0th_index | Index project before searching (returns jobId for background jobs) | | 2 | th0th_index_status | Poll background indexing job status by jobId | | 3 | th0th_search | Semantic + keyword search with filters | | 4 | th0th_optimized_context | Search + compress in one call (max token efficiency) | | 5 | th0th_search_definitions | Find symbol definitions (functions, classes, types) | | 6 | th0th_get_references | Find all usages of a symbol across the project | | 7 | th0th_go_to_definition | Jump to a symbol's definition with context | | 8 | th0th_list_projects | List all indexed projects and their status | | 9 | th0th_reset_project | Delete all indexed data for a project (vectors, symbols, memories) | | 10 | th0th_remember | Store important information in persistent memory | | 11 | th0th_recall | Retrieve memories from previous sessions | | 12 | th0th_compress | Reduce context size (70-98%) | | 13 | th0th_analytics | Usage patterns and metrics | | 14 | th0th_read_file | Read file/line-range with symbol metadata (prefer over Read when you have lineStart/lineEnd) | | 15 | th0th_project_map | One-shot project overview: PageRank backbone, symbol counts, language distribution | | 16 | th0th_synapse_session | Create/resume Synapse cognitive session (task alignment, agent affinity, working memory) | | 17 | th0th_synapse_prime | Seed Synapse buffer with recalled memories before searching | | 18 | th0th_synapse_access | Record file access for affinity scoring (call after reading/editing a file) | | 19 | th0th_symbol_snippet | Get raw code snippet by file + line range | | 20 | th0th_memory_list | Browse memories by type/importance without a query (audit mode) | | 21 | th0th_reindex | Force full reindex (when autoReindex/50-file limit is insufficient) | | 22 | Glob/Grep/Read | Only when th0th doesn't find what you need |

Tool Reference

1. th0th_index

Index a project directory for semantic search. Returns immediately with a jobId; polling is optional (use th0th_index_status).

th0th_index({
  projectPath: "/home/user/my-project",
  projectId: "my-project",
  forceReindex: false,
  warmCache: true,
  warmupQueries: ["authentication", "database schema"]
})

2. th0th_index_status

Poll a background indexing job by the jobId returned from th0th_index.

th0th_index_status({
  jobId: "job_abc123"
})

CRITICAL — polling discipline (mandatory):

Never call th0th_index_status in a tight loop. Choose one strategy:

Strategy A — single Bash sleep loop (preferred for normal tasks):

# TH0TH_API_URL is set by the MCP server environment; falls back to localhost:3333
TH0TH_API_URL="${TH0TH_API_URL:-http://localhost:3333}"

for i in $(seq 1 40); do
  result=$(curl -s "$TH0TH_API_URL/api/v1/project/index/status/JOB_ID")
  status=$(echo "$result" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['data']['status'])")
  progress=$(echo "$result" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['data'].get('progress',0))")
  echo "[$i] status=$status progress=$progress%"
  [ "$status" = "completed" ] || [ "$status" = "failed" ] && break
  sleep 15
done

Strategy B — ScheduleWakeup (only inside /loop mode):

ScheduleWakeup({ delaySeconds: 30, reason: "waiting for th0th indexing job JOB_ID", prompt: "<<autonomous-loop-dynamic>>" })

Then on the next wake-up call th0th_index_status once and repeat or finish.

Never do this:

# BAD: calling th0th_index_status repeatedly in successive turns without sleeping
th0th_index_status(...)  # turn 1
th0th_index_status(...)  # turn 2 — WRONG, wastes context and burns turns
th0th_index_status(...)  # turn 3 — WRONG

3. th0th_search

Semantic + keyword search with RRF (Reciprocal Rank Fusion).

th0th_search({
  query: "JWT authentication middleware",
  projectId: "my-project",
  maxResults: 10,
  minScore: 0.3,
  responseMode: "summary",   // "summary" saves ~70% tokens vs "full"
  autoReindex: false,        // set true to auto-refresh stale index
  explainScores: false,      // set true for vector/keyword/RRF breakdown
  include: ["src/**/*.ts"],
  exclude: ["**/*.test.*"]
})

responseMode:

• "summary" (default) — returns preview only; saves ~70% tokens.
• "full" — includes full file content; use when you need to read code.
• "enriched" — full content + fileImports + parentSymbol in every result; best for deep dives without extra tool calls. Use chunkIndex/totalChunks to navigate adjacent chunks.

4. th0th_optimized_context

Search + compress in one call. Maximum token efficiency.

Always pass sessionId to activate the session file cache. On repeated calls within the same conversation, unchanged file chunks are replaced with a compact reference token (~8 tokens) instead of full content, saving 50-70% of input tokens in long sessions.

th0th_optimized_context({
  query: "how does authentication work?",
  projectId: "my-project",
  sessionId: "<stable identifier for the current conversation>",
  maxTokens: 4000,
  maxResults: 5
})

The response includes metadata.tokensSavedBySessionCache and data.sessionCacheHits so you can observe the savings.

5. th0th_search_definitions

Find symbol definitions (functions, classes, variables, types, interfaces, exports) in an indexed project.

th0th_search_definitions({
  projectId: "my-project",
  query: "UserService",       // substring match, case-insensitive
  kind: "class,function",    // comma-separated: function,class,variable,type,interface,export
  file: "src/services/user.ts",
  exportedOnly: false,
  limit: 20
})

6. th0th_get_references

Find all usages of a symbol across the project. Returns file paths, line numbers, reference kinds (call, import, type_ref, extend, implement), and code context.

th0th_get_references({
  projectId: "my-project",
  symbolName: "UserService",
  fqn: "services/user.ts#UserService",  // disambiguates when name is shared
  limit: 50
})

7. th0th_go_to_definition

Jump to a symbol's definition. Disambiguates using calling file context.

th0th_go_to_definition({
  projectId: "my-project",
  symbolName: "getPrismaClient",
  fromFile: "src/controllers/search-controller.ts"
})

8. th0th_list_projects

List all indexed projects and their current status.

th0th_list_projects({
  status: "all"   // pending | indexing | indexed | error | all
})

9. th0th_reset_project

Delete all indexed data for a project. Each scope is independent and defaults to true.

th0th_reset_project({
  projectId: "my-project",
  clearVectors: true,    // remove vector embeddings (semantic search index)
  clearSymbols: true,    // remove symbol graph (definitions, references, imports, centrality)
  clearMemories: true    // remove stored memories for this project
})

When to use:

• Before a full reindex to ensure a clean slate (th0th_reset_project → th0th_index)
• To free space from a project that is no longer needed
• To clear stale data after a major refactor

Response includes: vectorsDeleted, symbolsCleared, memoriesDeleted counts.

10. th0th_remember

Store important information in persistent memory.

th0th_remember({
  content: "Using PostgreSQL for user data",
  type: "decision",
  importance: 0.8,
  tags: ["database", "architecture"],
  projectId: "my-project",
  sessionId: "session-123",
  agentId: "architect",
  format: "toon"   // "json" or "toon"
})

11. th0th_recall

Search stored memories from previous sessions.

th0th_recall({
  query: "database decisions",
  types: ["decision"],
  limit: 10,
  minImportance: 0.3,
  projectId: "my-project",
  agentId: "architect",
  includePersistent: true,
  format: "toon"
})

12. th0th_compress

Compress context (keeps structure, removes details).

th0th_compress({
  content: "...large code...",
  strategy: "code_structure",
  targetRatio: 0.7,
  language: "typescript"
})

13. th0th_analytics

Usage patterns, cache performance, metrics.

th0th_analytics({
  type: "summary",   // summary | project | query | cache | recent
  projectId: "my-project",
  limit: 10
})

Compression Strategies

| Strategy | Use Case | Reduction | |----------|----------|-----------| | code_structure | Source code | 70-90% | | conversation_summary | Chat history | 80-95% | | semantic_dedup | Repetitive content | 50-70% | | hierarchical | Structured docs | 60-80% |

Memory Types

| Type | Use | |------|-----| | critical | Critical user-defined facts | | conversation | Important conversation points | | code | Code patterns discovered | | decision | Architecture decisions | | pattern | Recurring patterns |

Decision Flow

Need to find code?
  → th0th_search with responseMode:"summary" (first)
  → Glob/Grep/Read (fallback only)

Need to navigate symbols?
  → th0th_go_to_definition (jump to definition)
  → th0th_get_references (find all usages)
  → th0th_search_definitions (list matching symbols)

Need to understand architecture?
  → th0th_recall (check memories first)
  → th0th_search (explore code)
  → th0th_search_definitions (enumerate public API)

Found important pattern/decision?
  → th0th_remember (store for future sessions)

Context too large?
  → th0th_compress (reduce tokens)

Maximum efficiency needed?
  → th0th_optimized_context (search + compress + session cache)

Need to check indexed projects?
  → th0th_list_projects (see status, file counts, last indexed)

Indexing taking long?
  → th0th_index_status (poll jobId from th0th_index)
  → WAIT between polls: use a single Bash sleep loop (15s intervals) or ScheduleWakeup in /loop mode
  → NEVER call th0th_index_status in successive turns without sleeping first

Need a clean slate before reindexing?
  → th0th_reset_project (wipe vectors + symbols + memories)
  → th0th_index (reindex from scratch)

Installation

One-command (recommended)

curl -fsSL https://raw.githubusercontent.com/S1LV4/th0th/main/install.sh | bash

Supports three modes (select interactively or override with TH0TH_MODE):

| Mode | TH0TH_MODE | Requirements | Best for | |------|--------------|--------------|---------| | Docker | docker | Docker | Production, quick start | | Docker build | build | Docker + Git | Custom builds, local changes | | From source | source | Git + Bun | Development, contributors |

Non-interactive example:

TH0TH_MODE=docker TH0TH_API_PORT=4000 TH0TH_NO_START=1 \
  curl -fsSL https://raw.githubusercontent.com/S1LV4/th0th/main/install.sh | bash

Configuration

Config file: ~/.config/th0th/config.json (auto-created on first run)

Embedding Providers

| Provider | Default Model | Dimensions | Cost | |----------|---------------|------------|------| | Ollama (default) | bge-m3 | 1024 | Free | | Ollama alt | qwen3-embedding | 4096 | Free | | Mistral | mistral-embed | — | $$ | | OpenAI | text-embedding-3-small | — | $$ |

Quick Config Commands

npx @th0th-ai/mcp-client --config-show                          # print current config
npx @th0th-ai/mcp-client --config-path                          # show config file path
npx @th0th-ai/mcp-client --config-init                          # init with Ollama defaults
npx @th0th-ai/mcp-client --config-init --mistral YOUR_KEY       # init with Mistral
npx @th0th-ai/mcp-client --config-init --openai YOUR_KEY        # init with OpenAI
npx @th0th-ai/mcp-client --config-init --ollama-model bge-m3    # switch Ollama model
npx @th0th-ai/mcp-client --config-set embedding.dimensions 1024 # set specific value

Validate Stack

bun run diagnose   # checks Ollama, database, embeddings, migration status

Deployment Notes

• Docker mode: PostgreSQL + auto-migration via entrypoint script on container startup. Uses bge-m3 / 1024d by default.
• Source mode: SQLite via prisma-adapter-bun-sqlite. Run bun run diagnose after setup.
• WSL / Linux: Ollama connectivity via host.docker.internal:host-gateway in docker-compose.yml.
• PostgreSQL: Set DATABASE_URL=postgresql://... and POSTGRES_PASSWORD. Migrations run automatically on docker compose up.