kotadb 2.1.0 → 2.2.0-next.20260204160632

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kotadb",
-  "version": "2.1.0",
+  "version": "2.2.0-next.20260204160632",
   "description": "Local-only code intelligence tool for CLI agents. SQLite-backed repository indexing and code search via MCP.",
   "type": "module",
   "module": "src/index.ts",
@@ -54,8 +54,8 @@
     "@asteasolutions/zod-to-openapi": "^8.4.0",
     "@modelcontextprotocol/sdk": "^1.25.0",
     "@sentry/node": "^10.25.0",
-    "@typescript-eslint/parser": "^8.0.0",
-    "@typescript-eslint/types": "^8.54.0",
+    "@typescript-eslint/parser": "8.54.0",
+    "@typescript-eslint/types": "8.54.0",
     "bcryptjs": "^2.4.3",
     "chokidar": "^5.0.0",
     "cors": "^2.8.6",
@@ -75,5 +75,8 @@
     "lint-staged": "^16.2.4",
     "supertest": "^7.1.4",
     "typescript": "^5.9.3"
+  },
+  "overrides": {
+    "@typescript-eslint/types": "8.54.0"
   }
 }

package/src/cli/args.ts

@@ -0,0 +1,105 @@
+/**
+ * CLI argument parsing utilities
+ *
+ * Extracted for testability. Used by main CLI entry point.
+ *
+ * @module cli/args
+ */
+
+/**
+ * Valid toolset tiers for MCP tool selection
+ * - default: 8 tools (core + sync)
+ * - core: 6 tools
+ * - memory: 14 tools (core + sync + memory)
+ * - full: 20 tools (all)
+ */
+export type ToolsetTier = "default" | "core" | "memory" | "full";
+
+const VALID_TOOLSET_TIERS: ToolsetTier[] = ["default", "core", "memory", "full"];
+
+export interface CliOptions {
+	port: number;
+	help: boolean;
+	version: boolean;
+	stdio: boolean;
+	toolset: ToolsetTier;
+}
+
+/**
+ * Type guard for valid toolset tier
+ */
+export function isValidToolsetTier(value: string): value is ToolsetTier {
+	return VALID_TOOLSET_TIERS.includes(value as ToolsetTier);
+}
+
+/**
+ * Parse CLI arguments into options object
+ */
+export function parseArgs(args: string[]): CliOptions {
+	const options: CliOptions = {
+		port: Number(process.env.PORT ?? 3000),
+		help: false,
+		version: false,
+		stdio: false,
+		toolset: "default",
+	};
+
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === undefined) continue;
+
+		if (arg === "--help" || arg === "-h") {
+			options.help = true;
+		} else if (arg === "--version" || arg === "-v") {
+			options.version = true;
+		} else if (arg === "--stdio") {
+			options.stdio = true;
+		} else if (arg === "--port") {
+			const portStr = args[++i];
+			if (!portStr || Number.isNaN(Number(portStr))) {
+				process.stderr.write("Error: --port requires a valid number\n");
+				process.exit(1);
+			}
+			options.port = Number(portStr);
+		} else if (arg.startsWith("--port=")) {
+			const portStr = arg.split("=")[1];
+			if (portStr === undefined || Number.isNaN(Number(portStr))) {
+				process.stderr.write("Error: --port requires a valid number\n");
+				process.exit(1);
+			}
+			options.port = Number(portStr);
+		} else if (arg === "--toolset") {
+			const tierStr = args[++i];
+			if (!tierStr) {
+				process.stderr.write("Error: --toolset requires a tier value\n");
+				process.stderr.write("Valid tiers: default, core, memory, full\n");
+				process.exit(1);
+			}
+			if (!isValidToolsetTier(tierStr)) {
+				process.stderr.write(`Error: Invalid toolset tier '${tierStr}'\n`);
+				process.stderr.write("Valid tiers: default, core, memory, full\n");
+				process.exit(1);
+			}
+			options.toolset = tierStr;
+		} else if (arg.startsWith("--toolset=")) {
+			const tierStr = arg.split("=")[1];
+			if (tierStr === undefined || tierStr === "") {
+				process.stderr.write("Error: --toolset requires a tier value\n");
+				process.stderr.write("Valid tiers: default, core, memory, full\n");
+				process.exit(1);
+			}
+			if (!isValidToolsetTier(tierStr)) {
+				process.stderr.write(`Error: Invalid toolset tier '${tierStr}'\n`);
+				process.stderr.write("Valid tiers: default, core, memory, full\n");
+				process.exit(1);
+			}
+			options.toolset = tierStr;
+		} else if (arg.startsWith("-") && arg !== "-") {
+			process.stderr.write(`Unknown option: ${arg}\n`);
+			process.stderr.write("Use --help for usage information\n");
+			process.exit(1);
+		}
+	}
+
+	return options;
+}

package/src/cli.ts

@@ -9,6 +9,7 @@
  *   kotadb              Start the MCP server (default port 3000)
  *   kotadb --stdio      Start in stdio mode (for Claude Code integration)
  *   kotadb --port 4000  Start on custom port
+ *   kotadb --toolset full  Select tool tier (default, core, memory, full)
  *   kotadb --version    Show version
  *   kotadb --help       Show help
  *   kotadb deps         Query dependency information for a file
@@ -25,11 +26,23 @@ import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+/**
+ * Valid toolset tiers for MCP tool selection
+ * - default: 8 tools (core + sync)
+ * - core: 6 tools
+ * - memory: 14 tools (core + sync + memory)
+ * - full: 20 tools (all)
+ */
+export type ToolsetTier = "default" | "core" | "memory" | "full";
+
+const VALID_TOOLSET_TIERS: ToolsetTier[] = ["default", "core", "memory", "full"];
+
 interface CliOptions {
   port: number;
   help: boolean;
   version: boolean;
   stdio: boolean;
+  toolset: ToolsetTier;
 }
 
 function getVersion(): string {
@@ -70,6 +83,12 @@ COMMANDS:
 OPTIONS:
   --stdio           Use stdio transport (for Claude Code integration)
   --port <number>   Port to listen on (default: 3000, env: PORT)
+  --toolset <tier>  Select tool tier (default: default)
+                    Tiers:
+                      default  8 tools (core + sync)
+                      core     6 tools (search, index, deps, impact)
+                      memory   14 tools (core + sync + memory layer)
+                      full     20 tools (all available tools)
   --version, -v     Show version number
   --help, -h        Show this help message
 
@@ -81,6 +100,8 @@ ENVIRONMENT VARIABLES:
 
 EXAMPLES:
   kotadb --stdio                              Start in stdio mode (for Claude Code)
+  kotadb --stdio --toolset full               Start with all tools enabled
+  kotadb --stdio --toolset core               Start with minimal core tools
   kotadb                                      Start HTTP server on port 3000
   kotadb --port 4000                          Start HTTP server on port 4000
   kotadb deps --file src/db/client.ts         Query deps for a file (text)
@@ -99,6 +120,17 @@ MCP CONFIGURATION (stdio mode - RECOMMENDED):
     }
   }
 
+  With toolset selection:
+
+  {
+    "mcpServers": {
+      "kotadb": {
+        "command": "bunx",
+        "args": ["kotadb@next", "--stdio", "--toolset", "full"]
+      }
+    }
+  }
+
 MCP CONFIGURATION (HTTP mode - legacy):
   Add to your .mcp.json or Claude Code settings:
 
@@ -126,12 +158,17 @@ function printVersion(): void {
   process.stdout.write(`kotadb v${version}\n`);
 }
 
+function isValidToolsetTier(value: string): value is ToolsetTier {
+  return VALID_TOOLSET_TIERS.includes(value as ToolsetTier);
+}
+
 function parseArgs(args: string[]): CliOptions {
   const options: CliOptions = {
     port: Number(process.env.PORT ?? 3000),
     help: false,
     version: false,
     stdio: false,
+    toolset: "default",
   };
 
   for (let i = 0; i < args.length; i++) {
@@ -158,6 +195,32 @@ function parseArgs(args: string[]): CliOptions {
         process.exit(1);
       }
       options.port = Number(portStr);
+    } else if (arg === "--toolset") {
+      const tierStr = args[++i];
+      if (!tierStr) {
+        process.stderr.write("Error: --toolset requires a tier value\n");
+        process.stderr.write("Valid tiers: default, core, memory, full\n");
+        process.exit(1);
+      }
+      if (!isValidToolsetTier(tierStr)) {
+        process.stderr.write(`Error: Invalid toolset tier '${tierStr}'\n`);
+        process.stderr.write("Valid tiers: default, core, memory, full\n");
+        process.exit(1);
+      }
+      options.toolset = tierStr;
+    } else if (arg.startsWith("--toolset=")) {
+      const tierStr = arg.split("=")[1];
+      if (tierStr === undefined || tierStr === "") {
+        process.stderr.write("Error: --toolset requires a tier value\n");
+        process.stderr.write("Valid tiers: default, core, memory, full\n");
+        process.exit(1);
+      }
+      if (!isValidToolsetTier(tierStr)) {
+        process.stderr.write(`Error: Invalid toolset tier '${tierStr}'\n`);
+        process.stderr.write("Valid tiers: default, core, memory, full\n");
+        process.exit(1);
+      }
+      options.toolset = tierStr;
     } else if (arg.startsWith("-") && arg !== "-") {
       process.stderr.write(`Unknown option: ${arg}\n`);
       process.stderr.write("Use --help for usage information\n");
@@ -168,7 +231,7 @@ function parseArgs(args: string[]): CliOptions {
   return options;
 }
 
-async function runStdioMode(): Promise<void> {
+async function runStdioMode(toolset: ToolsetTier): Promise<void> {
   // Redirect logger to stderr in stdio mode
   // This is CRITICAL - stdout is reserved for JSON-RPC protocol
   const logger = createLogger({
@@ -178,11 +241,13 @@ async function runStdioMode(): Promise<void> {
 
   logger.info("KotaDB MCP server starting in stdio mode", {
     version: getVersion(),
+    toolset,
   });
 
-  // Create MCP server with local-only context
+  // Create MCP server with local-only context and toolset
   const context: McpServerContext = {
     userId: "local", // Local-only mode uses fixed user ID
+    toolset,
   };
   const server = createMcpServer(context);
 
@@ -192,7 +257,7 @@ async function runStdioMode(): Promise<void> {
   // Connect server to transport
   await server.connect(transport);
 
-  logger.info("KotaDB MCP server connected via stdio");
+  logger.info("KotaDB MCP server connected via stdio", { toolset });
 
   // Server lifecycle is managed by the transport
   // Process will stay alive until stdin closes (when Claude Code terminates it)
@@ -234,7 +299,7 @@ async function main(): Promise<void> {
 
   // Handle stdio mode
   if (options.stdio) {
-    await runStdioMode();
+    await runStdioMode(options.toolset);
     return; // runStdioMode() keeps process alive
   }
 
@@ -247,6 +312,7 @@ async function main(): Promise<void> {
     mode: envConfig.mode,
     port: options.port,
     localDbPath: envConfig.localDbPath,
+    toolset: options.toolset,
   });
 
   const app = createExpressApp();
@@ -256,6 +322,7 @@ async function main(): Promise<void> {
       port: options.port,
       mcp_endpoint: `http://localhost:${options.port}/mcp`,
       health_endpoint: `http://localhost:${options.port}/health`,
+      toolset: options.toolset,
     });
 
     // Print user-friendly startup message
@@ -265,6 +332,7 @@ async function main(): Promise<void> {
     process.stdout.write(`  MCP Endpoint:    http://localhost:${options.port}/mcp\n`);
     process.stdout.write(`  Health Check:    http://localhost:${options.port}/health\n`);
     process.stdout.write(`  Database:        ${envConfig.localDbPath}\n`);
+    process.stdout.write(`  Toolset:         ${options.toolset}\n`);
     process.stdout.write(`\n`);
     process.stdout.write(`Press Ctrl+C to stop\n`);
     process.stdout.write(`\n`);

package/src/indexer/ast-parser.ts

@@ -42,6 +42,24 @@ export interface ParseError {
 	column?: number;
 }
 
+/**
+ * Type guard to validate that an AST node is a valid Program.
+ * Provides runtime type validation to prevent version compatibility issues.
+ *
+ * @param ast - Unknown AST node to validate
+ * @returns true if ast is a valid Program node
+ */
+function isValidProgram(ast: unknown): ast is TSESTree.Program {
+	return (
+		ast !== null &&
+		typeof ast === "object" &&
+		"type" in ast &&
+		ast.type === "Program" &&
+		"body" in ast &&
+		Array.isArray(ast.body)
+	);
+}
+
 /**
  * Result of parsing a file, including partial AST recovery information.
  */
@@ -103,7 +121,7 @@ function createParseError(error: unknown): ParseError {
 
 /**
  * Parse a file with error-tolerant options enabled.
- * Uses allowInvalidAST to attempt partial recovery.
+ * Uses allowInvalidAST to attempt partial recovery and validates result.
  */
 function parseWithRecoveryOptions(filePath: string, content: string): TSESTree.Program | null {
 	try {
@@ -119,6 +137,18 @@ function parseWithRecoveryOptions(filePath: string, content: string): TSESTree.P
 			allowInvalidAST: true,
 			errorOnUnknownASTType: false,
 		});
+
+		// Validate the returned AST is actually a Program node
+		if (!isValidProgram(ast)) {
+			const astType = typeof ast === "object" && ast !== null && "type" in ast ? (ast as any).type : typeof ast;
+			logger.warn(`Parser returned invalid Program type for ${filePath}`, {
+				file_path: filePath,
+				ast_type: astType,
+				recovery: "failed_validation",
+			});
+			return null;
+		}
+
 		return ast;
 	} catch {
 		// Even with recovery options, parsing can still fail
@@ -159,6 +189,18 @@ export function parseFileWithRecovery(filePath: string, content: string): ParseR
 			tokens: true,
 			filePath,
 		});
+
+		// Validate the returned AST is actually a Program node
+		if (!isValidProgram(ast)) {
+			const astType = typeof ast === "object" && ast !== null && "type" in ast ? (ast as any).type : typeof ast;
+			logger.warn(`Parser returned invalid Program type for ${filePath}`, {
+				file_path: filePath,
+				ast_type: astType,
+				recovery: "failed_validation",
+			});
+			throw new Error(`Invalid AST type returned: expected Program, got ${astType}`);
+		}
+
 		return {
 			ast,
 			errors: [],

package/src/mcp/server.ts

@@ -18,17 +18,14 @@ import {
 	GENERATE_TASK_CONTEXT_TOOL,
 	INDEX_REPOSITORY_TOOL,
 	LIST_RECENT_FILES_TOOL,
-	SEARCH_CODE_TOOL,
+	SEARCH_TOOL,
 	SEARCH_DEPENDENCIES_TOOL,
 	SYNC_EXPORT_TOOL,
 	SYNC_IMPORT_TOOL,
 	VALIDATE_IMPLEMENTATION_SPEC_TOOL,
 	// Memory Layer tools
-	SEARCH_DECISIONS_TOOL,
 	RECORD_DECISION_TOOL,
-	SEARCH_FAILURES_TOOL,
 	RECORD_FAILURE_TOOL,
-	SEARCH_PATTERNS_TOOL,
 	RECORD_INSIGHT_TOOL,
 	// Dynamic Expertise tools
 	GET_DOMAIN_KEY_FILES_TOOL,
@@ -40,27 +37,35 @@ import {
 	executeGenerateTaskContext,
 	executeIndexRepository,
 	executeListRecentFiles,
-	executeSearchCode,
+	executeSearch,
 	executeSearchDependencies,
 	executeSyncExport,
 	executeSyncImport,
 	executeValidateImplementationSpec,
 	// Memory Layer execute functions
-	executeSearchDecisions,
 	executeRecordDecision,
-	executeSearchFailures,
 	executeRecordFailure,
-	executeSearchPatterns,
 	executeRecordInsight,
 	// Dynamic Expertise execute functions
 	executeGetDomainKeyFiles,
 	executeValidateExpertise,
 	executeSyncExpertise,
 	executeGetRecentPatterns,
+	// Tool filtering
+	filterToolsByTier,
 } from "./tools";
 
 const logger = createLogger({ module: "mcp-server" });
 
+/**
+ * Valid toolset tiers for MCP tool selection
+ * - default: 8 tools (core + sync)
+ * - core: 6 tools
+ * - memory: 14 tools (core + sync + memory)
+ * - full: 20 tools (all)
+ */
+export type ToolsetTier = "default" | "core" | "memory" | "full";
+
 /**
  * MCP Server context passed to tool handlers via closure
  *
@@ -68,6 +73,7 @@ const logger = createLogger({ module: "mcp-server" });
  */
 export interface McpServerContext {
 	userId: string;
+	toolset?: ToolsetTier;
 }
 
 /**
@@ -107,35 +113,20 @@ export function createMcpServer(context: McpServerContext): Server {
 		},
 	);
 
-	// Register tools/list handler - local-only tools
+	// Register tools/list handler - filter by toolset tier
 	server.setRequestHandler(ListToolsRequestSchema, async () => {
+		const tier = context.toolset || "default";
+		const filteredTools = filterToolsByTier(tier);
+		
+		logger.debug("Listing MCP tools", { 
+			tier, 
+			tool_count: filteredTools.length 
+		});
+		
 		return {
-			tools: [
-				SEARCH_CODE_TOOL,
-				INDEX_REPOSITORY_TOOL,
-				LIST_RECENT_FILES_TOOL,
-				SEARCH_DEPENDENCIES_TOOL,
-				ANALYZE_CHANGE_IMPACT_TOOL,
-				VALIDATE_IMPLEMENTATION_SPEC_TOOL,
-				SYNC_EXPORT_TOOL,
-				SYNC_IMPORT_TOOL,
-				GENERATE_TASK_CONTEXT_TOOL,
-				// Memory Layer tools
-				SEARCH_DECISIONS_TOOL,
-				RECORD_DECISION_TOOL,
-				SEARCH_FAILURES_TOOL,
-				RECORD_FAILURE_TOOL,
-				SEARCH_PATTERNS_TOOL,
-				RECORD_INSIGHT_TOOL,
-				// Dynamic Expertise tools
-				GET_DOMAIN_KEY_FILES_TOOL,
-				VALIDATE_EXPERTISE_TOOL,
-				SYNC_EXPERTISE_TOOL,
-				GET_RECENT_PATTERNS_TOOL,
-			],
+			tools: filteredTools,
 		};
 	});
-
 	// Register tools/call handler
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {
 		const { name, arguments: toolArgs } = request.params;
@@ -146,8 +137,8 @@ export function createMcpServer(context: McpServerContext): Server {
 
 		try {
 			switch (name) {
-				case "search_code":
-					result = await executeSearchCode(
+				case "search":
+					result = await executeSearch(
 						toolArgs,
 						"", // requestId not used
 						context.userId,
@@ -202,13 +193,6 @@ export function createMcpServer(context: McpServerContext): Server {
 					);
 					break;
 				// Memory Layer tools
-				case "search_decisions":
-					result = await executeSearchDecisions(
-						toolArgs,
-						"", // requestId not used
-						context.userId,
-					);
-					break;
 				case "record_decision":
 					result = await executeRecordDecision(
 						toolArgs,
@@ -216,13 +200,6 @@ export function createMcpServer(context: McpServerContext): Server {
 						context.userId,
 					);
 					break;
-				case "search_failures":
-					result = await executeSearchFailures(
-						toolArgs,
-						"", // requestId not used
-						context.userId,
-					);
-					break;
 				case "record_failure":
 					result = await executeRecordFailure(
 						toolArgs,
@@ -230,13 +207,6 @@ export function createMcpServer(context: McpServerContext): Server {
 						context.userId,
 					);
 					break;
-				case "search_patterns":
-					result = await executeSearchPatterns(
-						toolArgs,
-						"", // requestId not used
-						context.userId,
-					);
-					break;
 				case "record_insight":
 					result = await executeRecordInsight(
 						toolArgs,

package/src/mcp/tools.ts

@@ -34,8 +34,14 @@ const logger = createLogger({ module: "mcp-tools" });
 /**
  * MCP Tool Definition
  */
+/**
+ * Tool tier for categorizing tools by feature set
+ */
+export type ToolTier = "core" | "sync" | "memory" | "expertise";
+
 export interface ToolDefinition {
 	name: string;
+	tier: ToolTier;
 	description: string;
 	inputSchema: {
 		type: "object";
@@ -45,38 +51,165 @@ export interface ToolDefinition {
 }
 
 /**
+ * Toolset tier for CLI selection (maps to tool tiers)
+ */
+export type ToolsetTier = "default" | "core" | "memory" | "full";
+
+/**
+ * Filter tools by the requested toolset tier
+ *
+ * Tier mapping:
+ * - core: 6 tools (core tier only)
+ * - default: 8 tools (core + sync tiers)
+ * - memory: 14 tools (core + sync + memory tiers)
+ * - full: all tools
+ *
+ * @param tier - The toolset tier to filter by
+ * @param tools - Optional array of tools (defaults to all tool definitions)
+ */
+export function filterToolsByTier(tier: ToolsetTier, tools?: ToolDefinition[]): ToolDefinition[] {
+	const allTools = tools ?? getToolDefinitions();
+	switch (tier) {
+		case "core":
+			return allTools.filter((t) => t.tier === "core");
+		case "default":
+			return allTools.filter((t) => t.tier === "core" || t.tier === "sync");
+		case "memory":
+			return allTools.filter((t) => t.tier === "core" || t.tier === "sync" || t.tier === "memory");
+		case "full":
+			return allTools;
+		default:
+			// Default to "default" tier if unknown
+			return allTools.filter((t) => t.tier === "core" || t.tier === "sync");
+	}
+}
 
 /**
- * Tool: search_code
+ * Alias for filterToolsByTier - get tool definitions filtered by toolset
+ *
+ * @param toolset - The toolset tier to filter by
  */
-export const SEARCH_CODE_TOOL: ToolDefinition = {
-	name: "search_code",
+export function getToolsByTier(toolset: ToolsetTier): ToolDefinition[] {
+	return filterToolsByTier(toolset);
+}
+
+/**
+ * Validate if a string is a valid toolset tier
+ */
+export function isValidToolset(value: string): value is ToolsetTier {
+	return value === "default" || value === "core" || value === "memory" || value === "full";
+}
+
+// ============================================================================
+// UNIFIED SEARCH TOOL - Replaces search_code, search_symbols, search_decisions, search_patterns, search_failures  
+// Issue: #143
+// ============================================================================
+
+/**
+ * Tool: search (unified)
+ */
+export const SEARCH_TOOL: ToolDefinition = {
+	tier: "core",
+	name: "search",
 	description:
-		"Search indexed code files for a specific term. Returns matching files with context snippets.",
+		"Search indexed code, symbols, decisions, patterns, and failures. Supports multiple search scopes simultaneously with scope-specific filters and output formats.",
 	inputSchema: {
 		type: "object",
 		properties: {
-			term: {
+			query: {
 				type: "string",
-				description: "The search term to find in code files",
+				description: "Search query term or phrase",
 			},
-			repository: {
-				type: "string",
-				description: "Optional: Filter results to a specific repository ID",
+			scope: {
+				type: "array",
+				items: {
+					type: "string",
+					enum: ["code", "symbols", "decisions", "patterns", "failures"],
+				},
+				description: "Search scopes to query (default: ['code'])",
+			},
+			filters: {
+				type: "object",
+				description: "Scope-specific filters (invalid filters ignored)",
+				properties: {
+					// Code scope filters
+					glob: {
+						type: "string",
+						description: "File path glob pattern (code scope only)",
+					},
+					exclude: {
+						type: "array",
+						items: { type: "string" },
+						description: "Exclude patterns (code scope only)",
+					},
+					language: {
+						type: "string",
+						description: "Programming language filter (code scope only)",
+					},
+					// Symbol scope filters
+					symbol_kind: {
+						type: "array",
+						items: {
+							type: "string",
+							enum: [
+								"function",
+								"class",
+								"interface",
+								"type",
+								"variable",
+								"constant",
+								"method",
+								"property",
+								"module",
+								"namespace",
+								"enum",
+								"enum_member",
+							],
+						},
+						description: "Symbol kinds to include (symbols scope only)",
+					},
+					exported_only: {
+						type: "boolean",
+						description: "Only exported symbols (symbols scope only)",
+					},
+					// Decision scope filters
+					decision_scope: {
+						type: "string",
+						enum: ["architecture", "pattern", "convention", "workaround"],
+						description: "Decision category (decisions scope only)",
+					},
+					// Pattern scope filters
+					pattern_type: {
+						type: "string",
+						description: "Pattern type filter (patterns scope only)",
+					},
+					// Common filters
+					repository: {
+						type: "string",
+						description: "Repository ID or full_name filter (all scopes)",
+					},
+				},
 			},
 			limit: {
 				type: "number",
-				description: "Optional: Maximum number of results (default: 20, max: 100)",
+				description: "Max results per scope (default: 20, max: 100)",
+			},
+			output: {
+				type: "string",
+				enum: ["full", "paths", "compact"],
+				description: "Output format (default: 'full')",
 			},
 		},
-		required: ["term"],
+		required: ["query"],
 	},
 };
 
+
 /**
  * Tool: index_repository
  */
 export const INDEX_REPOSITORY_TOOL: ToolDefinition = {
+	tier: "core",
 	name: "index_repository",
 	description:
 		"Index a git repository by cloning/updating it and extracting code files. Performs synchronous indexing and returns immediately with status 'completed' and full indexing stats.",
@@ -104,6 +237,7 @@ export const INDEX_REPOSITORY_TOOL: ToolDefinition = {
  * Tool: list_recent_files
  */
 export const LIST_RECENT_FILES_TOOL: ToolDefinition = {
+	tier: "core",
 	name: "list_recent_files",
 	description:
 		"List recently indexed files, ordered by indexing timestamp. Useful for seeing what code is available.",
@@ -126,6 +260,7 @@ export const LIST_RECENT_FILES_TOOL: ToolDefinition = {
  * Tool: search_dependencies
  */
 export const SEARCH_DEPENDENCIES_TOOL: ToolDefinition = {
+	tier: "core",
 	name: "search_dependencies",
 	description:
 		"Search the dependency graph to find files that depend on (dependents) or are depended on by (dependencies) a target file. Useful for impact analysis before refactoring, test scope discovery, and circular dependency detection.",
@@ -174,6 +309,7 @@ export const SEARCH_DEPENDENCIES_TOOL: ToolDefinition = {
  * Tool: analyze_change_impact
  */
 export const ANALYZE_CHANGE_IMPACT_TOOL: ToolDefinition = {
+	tier: "core",
 	name: "analyze_change_impact",
 	description:
 		"Analyze the impact of proposed code changes by examining dependency graphs, test scope, and potential conflicts. Returns comprehensive analysis including affected files, test recommendations, architectural warnings, and risk assessment. Useful for planning implementations and avoiding breaking changes.",
@@ -221,6 +357,7 @@ export const ANALYZE_CHANGE_IMPACT_TOOL: ToolDefinition = {
  * Tool: validate_implementation_spec
  */
 export const VALIDATE_IMPLEMENTATION_SPEC_TOOL: ToolDefinition = {
+	tier: "expertise",
 	name: "validate_implementation_spec",
 	description:
 		"Validate an implementation specification against KotaDB conventions and repository state. Checks for file conflicts, naming conventions, path alias usage, test coverage, and dependency compatibility. Returns validation errors, warnings, and approval conditions checklist.",
@@ -303,6 +440,7 @@ export const VALIDATE_IMPLEMENTATION_SPEC_TOOL: ToolDefinition = {
  * Tool: kota_sync_export
  */
 export const SYNC_EXPORT_TOOL: ToolDefinition = {
+	tier: "sync",
 	name: "kota_sync_export",
 	description:
 		"Export local SQLite database to JSONL files for git sync. Uses hash-based change detection to skip unchanged tables. Exports to .kotadb/export/ by default.",
@@ -325,6 +463,7 @@ export const SYNC_EXPORT_TOOL: ToolDefinition = {
  * Tool: kota_sync_import
  */
 export const SYNC_IMPORT_TOOL: ToolDefinition = {
+	tier: "sync",
 	name: "kota_sync_import",
 	description:
 		"Import JSONL files into local SQLite database. Applies deletion manifest first, then imports all tables transactionally. Typically run after git pull to sync remote changes.",
@@ -347,6 +486,7 @@ export const SYNC_IMPORT_TOOL: ToolDefinition = {
  * Target: <100ms response time
  */
 export const GENERATE_TASK_CONTEXT_TOOL: ToolDefinition = {
+	tier: "core",
 	name: "generate_task_context",
 	description:
 		"Generate structured context for a set of files including dependency counts, impacted files, test files, and recent changes. Designed for hook-based context injection with <100ms performance target.",
@@ -383,42 +523,11 @@ export const GENERATE_TASK_CONTEXT_TOOL: ToolDefinition = {
 // Memory Layer Tool Definitions
 // ============================================================================
 
-/**
- * Tool: search_decisions
- */
-export const SEARCH_DECISIONS_TOOL: ToolDefinition = {
-	name: "search_decisions",
-	description:
-		"Search past architectural decisions using FTS5. Returns decisions with relevance scores.",
-	inputSchema: {
-		type: "object",
-		properties: {
-			query: {
-				type: "string",
-				description: "Search query for decisions",
-			},
-			scope: {
-				type: "string",
-				enum: ["architecture", "pattern", "convention", "workaround"],
-				description: "Optional: Filter by decision scope",
-			},
-			repository: {
-				type: "string",
-				description: "Optional: Filter to a specific repository ID or full_name",
-			},
-			limit: {
-				type: "number",
-				description: "Optional: Max results (default: 20)",
-			},
-		},
-		required: ["query"],
-	},
-};
-
 /**
  * Tool: record_decision
  */
 export const RECORD_DECISION_TOOL: ToolDefinition = {
+	tier: "memory",
 	name: "record_decision",
 	description:
 		"Record a new architectural decision for future reference. Decisions are searchable via search_decisions.",
@@ -465,37 +574,11 @@ export const RECORD_DECISION_TOOL: ToolDefinition = {
 	},
 };
 
-/**
- * Tool: search_failures
- */
-export const SEARCH_FAILURES_TOOL: ToolDefinition = {
-	name: "search_failures",
-	description:
-		"Search failed approaches to avoid repeating mistakes. Returns failures with relevance scores.",
-	inputSchema: {
-		type: "object",
-		properties: {
-			query: {
-				type: "string",
-				description: "Search query for failures",
-			},
-			repository: {
-				type: "string",
-				description: "Optional: Filter to a specific repository ID or full_name",
-			},
-			limit: {
-				type: "number",
-				description: "Optional: Max results (default: 20)",
-			},
-		},
-		required: ["query"],
-	},
-};
-
 /**
  * Tool: record_failure
  */
 export const RECORD_FAILURE_TOOL: ToolDefinition = {
+	tier: "memory",
 	name: "record_failure",
 	description:
 		"Record a failed approach for future reference. Helps agents avoid repeating mistakes.",
@@ -532,44 +615,11 @@ export const RECORD_FAILURE_TOOL: ToolDefinition = {
 	},
 };
 
-/**
- * Tool: search_patterns
- */
-export const SEARCH_PATTERNS_TOOL: ToolDefinition = {
-	name: "search_patterns",
-	description:
-		"Find codebase patterns by type or file. Returns discovered patterns for consistency.",
-	inputSchema: {
-		type: "object",
-		properties: {
-			query: {
-				type: "string",
-				description: "Optional: Search query for pattern name/description",
-			},
-			pattern_type: {
-				type: "string",
-				description: "Optional: Filter by pattern type (e.g., error-handling, api-call)",
-			},
-			file: {
-				type: "string",
-				description: "Optional: Filter by file path",
-			},
-			repository: {
-				type: "string",
-				description: "Optional: Filter to a specific repository ID or full_name",
-			},
-			limit: {
-				type: "number",
-				description: "Optional: Max results (default: 20)",
-			},
-		},
-	},
-};
-
 /**
  * Tool: record_insight
  */
 export const RECORD_INSIGHT_TOOL: ToolDefinition = {
+	tier: "memory",
 	name: "record_insight",
 	description:
 		"Store a session insight for future agents. Insights are discoveries, failures, or workarounds.",
@@ -611,6 +661,7 @@ export const RECORD_INSIGHT_TOOL: ToolDefinition = {
  * Tool: get_domain_key_files
  */
 export const GET_DOMAIN_KEY_FILES_TOOL: ToolDefinition = {
+	tier: "expertise",
 	name: "get_domain_key_files",
 	description:
 		"Get the most-depended-on files for a domain. Key files are core infrastructure that many other files depend on.",
@@ -638,6 +689,7 @@ export const GET_DOMAIN_KEY_FILES_TOOL: ToolDefinition = {
  * Tool: validate_expertise
  */
 export const VALIDATE_EXPERTISE_TOOL: ToolDefinition = {
+	tier: "expertise",
 	name: "validate_expertise",
 	description:
 		"Validate that key_files defined in expertise.yaml exist in the indexed codebase. Checks for stale or missing file references.",
@@ -657,6 +709,7 @@ export const VALIDATE_EXPERTISE_TOOL: ToolDefinition = {
  * Tool: sync_expertise
  */
 export const SYNC_EXPERTISE_TOOL: ToolDefinition = {
+	tier: "expertise",
 	name: "sync_expertise",
 	description:
 		"Sync patterns from expertise.yaml files to the patterns table. Extracts pattern definitions and stores them for future reference.",
@@ -679,6 +732,7 @@ export const SYNC_EXPERTISE_TOOL: ToolDefinition = {
  * Tool: get_recent_patterns
  */
 export const GET_RECENT_PATTERNS_TOOL: ToolDefinition = {
+	tier: "expertise",
 	name: "get_recent_patterns",
 	description:
 		"Get recently observed patterns from the patterns table. Useful for understanding codebase conventions.",
@@ -711,7 +765,7 @@ export const GET_RECENT_PATTERNS_TOOL: ToolDefinition = {
  */
 export function getToolDefinitions(): ToolDefinition[] {
 	return [
-		SEARCH_CODE_TOOL,
+		SEARCH_TOOL,
 		INDEX_REPOSITORY_TOOL,
 		LIST_RECENT_FILES_TOOL,
 		SEARCH_DEPENDENCIES_TOOL,
@@ -721,11 +775,8 @@ export function getToolDefinitions(): ToolDefinition[] {
 		SYNC_IMPORT_TOOL,
 		GENERATE_TASK_CONTEXT_TOOL,
 		// Memory Layer tools
-		SEARCH_DECISIONS_TOOL,
 		RECORD_DECISION_TOOL,
-		SEARCH_FAILURES_TOOL,
 		RECORD_FAILURE_TOOL,
-		SEARCH_PATTERNS_TOOL,
 		RECORD_INSIGHT_TOOL,
 		// Dynamic Expertise tools
 		GET_DOMAIN_KEY_FILES_TOOL,
@@ -734,7 +785,6 @@ export function getToolDefinitions(): ToolDefinition[] {
 		GET_RECENT_PATTERNS_TOOL,
 	];
 }
-
 /**
 
 /**
@@ -749,7 +799,361 @@ function isListRecentParams(params: unknown): params is { limit?: number; reposi
 	return true;
 }
 
+// ============================================================================
+// UNIFIED SEARCH - Helper Functions and Types
+// ============================================================================
+
+interface NormalizedFilters {
+	// Common
+	repositoryId?: string;
+	// Code
+	glob?: string;
+	exclude?: string[];
+	language?: string;
+	// Symbols
+	symbol_kind?: string[];
+	exported_only?: boolean;
+	// Decisions
+	decision_scope?: string;
+	// Patterns
+	pattern_type?: string;
+}
+
+function normalizeFilters(filters: unknown): NormalizedFilters {
+	if (!filters || typeof filters !== "object") {
+		return {};
+	}
+	
+	const f = filters as Record<string, unknown>;
+	const normalized: NormalizedFilters = {};
+	
+	// Resolve repository (UUID or full_name)
+	if (f.repository && typeof f.repository === "string") {
+		const resolved = resolveRepositoryIdentifierWithError(f.repository);
+		if (!("error" in resolved)) {
+			normalized.repositoryId = resolved.id;
+		}
+	}
+	
+	// Extract typed filters (silently ignore invalid)
+	if (f.glob && typeof f.glob === "string") {
+		normalized.glob = f.glob;
+	}
+	
+	if (Array.isArray(f.exclude)) {
+		normalized.exclude = f.exclude.filter(e => typeof e === "string");
+	}
+	
+	if (f.language && typeof f.language === "string") {
+		normalized.language = f.language;
+	}
+	
+	if (Array.isArray(f.symbol_kind)) {
+		normalized.symbol_kind = f.symbol_kind.filter(k => typeof k === "string");
+	}
+	
+	if (typeof f.exported_only === "boolean") {
+		normalized.exported_only = f.exported_only;
+	}
+	
+	if (f.decision_scope && typeof f.decision_scope === "string") {
+		normalized.decision_scope = f.decision_scope;
+	}
+	
+	if (f.pattern_type && typeof f.pattern_type === "string") {
+		normalized.pattern_type = f.pattern_type;
+	}
+	
+	return normalized;
+}
+
+interface SymbolResult {
+	id: string;
+	name: string;
+	kind: string;
+	signature: string | null;
+	documentation: string | null;
+	location: {
+		file: string;
+		line_start: number;
+		line_end: number;
+	};
+	repository_id: string;
+	is_exported: boolean;
+}
+
+async function searchSymbols(
+	query: string,
+	filters: NormalizedFilters,
+	limit: number
+): Promise<SymbolResult[]> {
+	const db = getGlobalDatabase();
+	
+	let sql = `
+		SELECT 
+			s.id,
+			s.name,
+			s.kind,
+			s.signature,
+			s.documentation,
+			s.line_start,
+			s.line_end,
+			s.metadata,
+			f.path as file_path,
+			s.repository_id
+		FROM indexed_symbols s
+		JOIN indexed_files f ON s.file_id = f.id
+		WHERE s.name LIKE ?
+	`;
+	
+	const params: (string | number)[] = [`%${query}%`];
+	
+	// Apply symbol_kind filter
+	if (filters.symbol_kind && filters.symbol_kind.length > 0) {
+		const placeholders = filters.symbol_kind.map(() => "?").join(", ");
+		sql += ` AND s.kind IN (${placeholders})`;
+		params.push(...filters.symbol_kind);
+	}
+	
+	// Apply exported_only filter
+	if (filters.exported_only) {
+		sql += ` AND json_extract(s.metadata, '$.is_exported') = 1`;
+	}
+	
+	// Apply repository filter
+	if (filters.repositoryId) {
+		sql += ` AND s.repository_id = ?`;
+		params.push(filters.repositoryId);
+	}
+	
+	sql += ` ORDER BY s.name LIMIT ?`;
+	params.push(limit);
+	
+	const rows = db.query<{
+		id: string;
+		name: string;
+		kind: string;
+		signature: string | null;
+		documentation: string | null;
+		line_start: number;
+		line_end: number;
+		metadata: string;
+		file_path: string;
+		repository_id: string;
+	}>(sql, params);
+	
+	return rows.map(row => ({
+		id: row.id,
+		name: row.name,
+		kind: row.kind,
+		signature: row.signature,
+		documentation: row.documentation,
+		location: {
+			file: row.file_path,
+			line_start: row.line_start,
+			line_end: row.line_end,
+		},
+		repository_id: row.repository_id,
+		is_exported: JSON.parse(row.metadata || '{}').is_exported || false,
+	}));
+}
+
+function formatSearchResults(
+	query: string,
+	scopes: string[],
+	scopeResults: Record<string, unknown[]>,
+	format: string
+): Record<string, unknown> {
+	const response: Record<string, unknown> = {
+		query,
+		scopes,
+		results: {} as Record<string, unknown>,
+		counts: { total: 0 } as Record<string, unknown>,
+	};
+
+	for (const scope of scopes) {
+		const items = scopeResults[scope] || [];
+		
+		if (format === "paths") {
+			// Extract file paths only
+			(response.results as Record<string, unknown>)[scope] = items.map((item: any) => {
+				if (item.path) return item.path;
+				if (item.file_path) return item.file_path;
+				if (item.location?.file) return item.location.file;
+				return "unknown";
+			});
+		} else if (format === "compact") {
+			// Summary info only
+			(response.results as Record<string, unknown>)[scope] = items.map((item: any) => {
+				if (scope === "code") {
+					return { path: item.path, match_count: 1 };
+				} else if (scope === "symbols") {
+					return { name: item.name, kind: item.kind, file: item.location.file };
+				} else if (scope === "decisions") {
+					return { title: item.title, scope: item.scope };
+				} else if (scope === "patterns") {
+					return { pattern_type: item.pattern_type, file_path: item.file_path };
+				} else if (scope === "failures") {
+					return { title: item.title, problem: item.problem };
+				}
+				return item;
+			});
+		} else {
+			// Full details
+			(response.results as Record<string, unknown>)[scope] = items;
+		}
+		
+		(response.counts as Record<string, unknown>)[scope] = items.length;
+		(response.counts as Record<string, unknown>).total = ((response.counts as Record<string, unknown>).total as number) + items.length;
+	}
+
+	return response;
+}
+
+// ============================================================================
+// UNIFIED SEARCH - Execute Function
+// ============================================================================
+
 /**
+ * Execute search tool (unified search across multiple scopes)
+ */
+export async function executeSearch(
+	params: unknown,
+	requestId: string | number,
+	userId: string,
+): Promise<unknown> {
+	// Validate params structure
+	if (typeof params !== "object" || params === null) {
+		throw new Error("Parameters must be an object");
+	}
+
+	const p = params as Record<string, unknown>;
+
+	// Check required parameter: query
+	if (p.query === undefined) {
+		throw new Error("Missing required parameter: query");
+	}
+	if (typeof p.query !== "string") {
+		throw new Error("Parameter 'query' must be a string");
+	}
+
+	// Validate optional parameters
+	let scopes: string[] = ["code"]; // Default scope
+	if (p.scope !== undefined) {
+		if (!Array.isArray(p.scope)) {
+			throw new Error("Parameter 'scope' must be an array");
+		}
+		const validScopes = ["code", "symbols", "decisions", "patterns", "failures"];
+		for (const s of p.scope) {
+			if (typeof s !== "string" || !validScopes.includes(s)) {
+				throw new Error(`Invalid scope: ${s}. Must be one of: ${validScopes.join(", ")}`);
+			}
+		}
+		scopes = p.scope as string[];
+	}
+
+	if (p.limit !== undefined && typeof p.limit !== "number") {
+		throw new Error("Parameter 'limit' must be a number");
+	}
+
+	if (p.output !== undefined) {
+		if (typeof p.output !== "string" || !["full", "paths", "compact"].includes(p.output)) {
+			throw new Error("Parameter 'output' must be one of: full, paths, compact");
+		}
+	}
+
+	const limit = Math.min(Math.max((p.limit as number) || 20, 1), 100);
+	const output = (p.output as string) || "full";
+	const filters = normalizeFilters(p.filters);
+
+	// Route to scope handlers in parallel
+	const results: Record<string, unknown[]> = {};
+	const searchPromises: Promise<void>[] = [];
+
+	if (scopes.includes("code")) {
+		searchPromises.push(
+			(async () => {
+				// Reuse existing searchFiles logic
+				const codeResults = searchFiles(p.query as string, {
+					repositoryId: filters.repositoryId,
+					limit,
+				});
+				results.code = codeResults;
+			})()
+		);
+	}
+
+	if (scopes.includes("symbols")) {
+		searchPromises.push(
+			(async () => {
+				const symbolResults = await searchSymbols(p.query as string, filters, limit);
+				results.symbols = symbolResults;
+			})()
+		);
+	}
+
+	if (scopes.includes("decisions")) {
+		searchPromises.push(
+			(async () => {
+				// Reuse existing executeSearchDecisions logic
+				const decisionParams = {
+					query: p.query,
+					scope: filters.decision_scope,
+					repository: filters.repositoryId,
+					limit,
+				};
+				const decisionResults = await executeSearchDecisions(decisionParams, requestId, userId);
+				results.decisions = (decisionResults as { results: unknown[] }).results;
+			})()
+		);
+	}
+
+	if (scopes.includes("patterns")) {
+		searchPromises.push(
+			(async () => {
+				// Reuse existing executeSearchPatterns logic
+				const patternParams = {
+					query: p.query,
+					pattern_type: filters.pattern_type,
+					repository: filters.repositoryId,
+					limit,
+				};
+				const patternResults = await executeSearchPatterns(patternParams, requestId, userId);
+				results.patterns = (patternResults as { results: unknown[] }).results;
+			})()
+		);
+	}
+
+	if (scopes.includes("failures")) {
+		searchPromises.push(
+			(async () => {
+				// Reuse existing executeSearchFailures logic
+				const failureParams = {
+					query: p.query,
+					repository: filters.repositoryId,
+					limit,
+				};
+				const failureResults = await executeSearchFailures(failureParams, requestId, userId);
+				results.failures = (failureResults as { results: unknown[] }).results;
+			})()
+		);
+	}
+
+	await Promise.all(searchPromises);
+
+	// Format output
+	const response = formatSearchResults(p.query as string, scopes, results, output);
+
+	logger.info("Unified search completed", {
+		query: p.query,
+		scopes,
+		total_results: (response.counts as Record<string, unknown>).total,
+		user_id: userId,
+	});
+
+	return response;
+}
+
 /**
  * Execute search_code tool
  *
@@ -943,8 +1347,18 @@ export async function executeListRecentFiles(
 			? (params.repository as string | undefined) 
 			: undefined;
 
+	// Resolve repository ID (supports UUID or full_name)
+	let repositoryId = repository;
+	if (repositoryId) {
+		const repoResult = resolveRepositoryIdentifierWithError(repositoryId);
+		if ("error" in repoResult) {
+			return { results: [], message: repoResult.error };
+		}
+		repositoryId = repoResult.id;
+	}
+
 	// Use SQLite via listRecentFiles with optional repository filter
-	const files = listRecentFiles(limit, repository);
+	const files = listRecentFiles(limit, repositoryId);
 
 	return {
 		results: files.map((file) => ({
@@ -956,8 +1370,6 @@ export async function executeListRecentFiles(
 	};
 }
 
-/**
-
 /**
  * Execute search_dependencies tool
  */
@@ -2558,8 +2970,8 @@ export async function handleToolCall(
 	userId: string,
 ): Promise<unknown> {
 	switch (toolName) {
-		case "search_code":
-			return await executeSearchCode(params, requestId, userId);
+		case "search":
+			return await executeSearch(params, requestId, userId);
 		case "index_repository":
 			return await executeIndexRepository(params, requestId, userId);
 		case "list_recent_files":
@@ -2577,16 +2989,10 @@ export async function handleToolCall(
 		case "generate_task_context":
 			return await executeGenerateTaskContext(params, requestId, userId);
 		// Memory Layer tools
-		case "search_decisions":
-			return await executeSearchDecisions(params, requestId, userId);
 		case "record_decision":
 			return await executeRecordDecision(params, requestId, userId);
-		case "search_failures":
-			return await executeSearchFailures(params, requestId, userId);
 		case "record_failure":
 			return await executeRecordFailure(params, requestId, userId);
-		case "search_patterns":
-			return await executeSearchPatterns(params, requestId, userId);
 		case "record_insight":
 			return await executeRecordInsight(params, requestId, userId);
 		// Expertise Layer tools