s1lv4/th0th/th0th-memory

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

th0th_index_status({
  jobId: "job_abc123"
})

# 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

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

# 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

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.*"]
})

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

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
})

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

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

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

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
})

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"
})

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

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

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

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)

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

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