cccmemory 1.8.0

package/dist/tools/ToolHandlers.d.ts

@@ -0,0 +1,791 @@
+/**
+ * MCP Tool Handlers - Implementation of all 22 tools for the cccmemory MCP server.
+ *
+ * This class provides the implementation for all MCP (Model Context Protocol) tools
+ * that allow Claude to interact with conversation history and memory.
+ *
+ * Tools are organized into categories:
+ * - Indexing: index_conversations
+ * - Search: search_conversations, searchDecisions, search_mistakes
+ * - File Context: check_before_modify, get_file_evolution
+ * - History: get_tool_history, link_commits_to_conversations
+ * - Discovery: find_similar_sessions, get_requirements
+ * - Recall: recall_and_apply
+ * - Documentation: generate_documentation
+ * - Migration: discover_old_conversations, migrate_project
+ *
+ * @example
+ * ```typescript
+ * const handlers = new ToolHandlers(memory, db, '/path/to/projects');
+ * const result = await handlers.indexConversations({
+ *   project_path: '/Users/me/my-project'
+ * });
+ * ```
+ */
+import { ConversationMemory } from "../ConversationMemory.js";
+import type { SQLiteManager } from "../storage/SQLiteManager.js";
+import type * as Types from "../types/ToolTypes.js";
+/**
+ * Pagination Patterns:
+ *
+ * This codebase uses two different pagination patterns based on data source:
+ *
+ * 1. SQL-based pagination (fetch+1):
+ *    - Fetch limit+1 records from database
+ *    - hasMore = results.length > limit
+ *    - Slice to limit if hasMore is true
+ *    - Use case: Single-database SQL queries (searchMistakes, linkCommitsToConversations)
+ *    - Advantage: Efficient, minimal data transfer
+ *
+ * 2. In-memory pagination (slice):
+ *    - Fetch all needed results (or limit+offset)
+ *    - Slice to get paginated subset: results.slice(offset, offset + limit)
+ *    - has_more = offset + limit < results.length
+ *    - Use case: Semantic search, cross-project aggregation
+ *    - Advantage: Allows sorting/filtering before pagination
+ *
+ * Both patterns are correct and optimized for their respective use cases.
+ */
+/**
+ * Tool handlers for the cccmemory MCP server.
+ *
+ * Provides methods for indexing, searching, and managing conversation history.
+ */
+export declare class ToolHandlers {
+    private memory;
+    private db;
+    private migration;
+    private lastAutoIndex;
+    private autoIndexPromise;
+    private readonly AUTO_INDEX_COOLDOWN;
+    /**
+     * Create a new ToolHandlers instance.
+     *
+     * @param memory - ConversationMemory instance for core operations
+     * @param db - SQLiteManager for database access
+     * @param projectsDir - Optional directory for storing project data
+     */
+    constructor(memory: ConversationMemory, db: SQLiteManager, projectsDir?: string);
+    private resolveProjectPath;
+    private resolveOptionalProjectPath;
+    private inferProjectPathFromMessages;
+    /**
+     * Automatically run incremental indexing if cooldown has expired.
+     * Uses a mutex (autoIndexPromise) to coalesce concurrent calls and prevent stampede.
+     * This ensures search results include recent conversations without
+     * requiring manual indexing.
+     */
+    private maybeAutoIndex;
+    /**
+     * Index conversation history for a project.
+     *
+     * Parses conversation files from Claude Code's conversation history, extracts
+     * decisions, mistakes, and requirements, links git commits, and generates
+     * semantic embeddings for search.
+     *
+     * @param args - Indexing arguments:
+     * - `project_path`: Path to the project (defaults to cwd)
+     * - `session_id`: Optional specific session to index
+     * - `include_thinking`: Include thinking blocks (default: false)
+     * - `enable_git`: Enable git integration (default: true)
+     * - `exclude_mcp_conversations`: Exclude MCP tool conversations (default: 'self-only')
+     * - `exclude_mcp_servers`: List of specific MCP servers to exclude
+     *
+     * @returns Result containing:
+     * - `success`: Whether indexing succeeded
+     * - `stats`: Counts of conversations, messages, decisions, etc.
+     * - `indexed_folders`: List of folders that were indexed
+     * - `database_path`: Path to the SQLite database
+     * - `embeddings_generated`: Whether embeddings were created
+     * - `embedding_error`: Error message if embeddings failed
+     * - `message`: Human-readable status message
+     *
+     * @example
+     * ```typescript
+     * const result = await handlers.indexConversations({
+     *   project_path: '/Users/me/my-project',
+     *   enable_git: true,
+     *   exclude_mcp_conversations: 'self-only'
+     * });
+     * console.error(result.message); // "Indexed 5 conversation(s) with 245 messages..."
+     * ```
+     */
+    indexConversations(args: Record<string, unknown>): Promise<Types.IndexConversationsResponse>;
+    /**
+     * Helper method to filter MCP conversations from parse results.
+     * Extracted to be usable in both the main indexConversations and project-specific indexing.
+     */
+    private filterMcpConversationsHelper;
+    /**
+     * Search conversation history using natural language queries.
+     *
+     * Uses semantic search with embeddings if available, otherwise falls back
+     * to full-text search. Returns relevant messages with context and similarity scores.
+     *
+     * @param args - Search arguments:
+     * - `query`: Natural language search query (required)
+     * - `limit`: Maximum number of results (default: 10)
+     * - `date_range`: Optional [start_timestamp, end_timestamp] filter
+     *
+     * @returns Search results containing:
+     * - `query`: The search query used
+     * - `results`: Array of matching messages with:
+     *   - `conversation_id`: Conversation containing the message
+     *   - `message_id`: Message identifier
+     *   - `timestamp`: When the message was created
+     *   - `similarity`: Relevance score (0-1)
+     *   - `snippet`: Text excerpt from the message
+     *   - `git_branch`: Git branch at the time
+     *   - `message_type`: Type of message
+     *   - `role`: Message role (user/assistant)
+     * - `total_found`: Number of results returned
+     *
+     * @example
+     * ```typescript
+     * const result = await handlers.searchConversations({
+     *   query: 'authentication bug fix',
+     *   limit: 5
+     * });
+     * result.results.forEach(r => {
+     *   console.error(`${r.similarity.toFixed(2)}: ${r.snippet}`);
+     * });
+     * ```
+     */
+    searchConversations(args: Record<string, unknown>): Promise<Types.SearchConversationsResponse>;
+    /**
+     * Find decisions made about a specific topic, file, or component.
+     *
+     * Searches through extracted decisions to find relevant architectural choices,
+     * technical decisions, and their rationale. Shows alternatives considered and
+     * rejected approaches.
+     *
+     * @param args - Decision search arguments:
+     * - `query`: Topic or keyword to search for (required)
+     * - `file_path`: Optional filter for decisions related to a specific file
+     * - `limit`: Maximum number of results (default: 10)
+     *
+     * @returns Decision search results containing:
+     * - `query`: The search query used
+     * - `file_path`: File filter if applied
+     * - `decisions`: Array of matching decisions with:
+     *   - `decision_id`: Decision identifier
+     *   - `decision_text`: The decision that was made
+     *   - `rationale`: Why this decision was made
+     *   - `alternatives_considered`: Other options that were considered
+     *   - `rejected_reasons`: Why alternatives were rejected
+     *   - `context`: Context in which the decision was made
+     *   - `related_files`: Files affected by this decision
+     *   - `related_commits`: Git commits implementing this decision
+     *   - `timestamp`: When the decision was made
+     *   - `similarity`: Relevance score
+     * - `total_found`: Number of decisions returned
+     *
+     * @example
+     * ```typescript
+     * const result = await handlers.getDecisions({
+     *   query: 'database',
+     *   file_path: 'src/storage/SQLiteManager.ts',
+     *   limit: 5
+     * });
+     * result.decisions.forEach(d => {
+     *   console.error(`Decision: ${d.decision_text}`);
+     *   console.error(`Rationale: ${d.rationale}`);
+     * });
+     * ```
+     */
+    getDecisions(args: Record<string, unknown>): Promise<Types.GetDecisionsResponse>;
+    /**
+     * Check important context before modifying a file.
+     *
+     * Shows recent changes, related decisions, commits, and past mistakes to avoid
+     * when working on a file. Use this before making significant changes to understand
+     * the file's history and context.
+     *
+     * @param args - Check arguments:
+     * - `file_path`: Path to the file you want to modify (required)
+     *
+     * @returns Context information containing:
+     * - `file_path`: The file being checked
+     * - `warning`: Warning message if important context found
+     * - `recent_changes`: Recent edits and commits to this file
+     *   - `edits`: Recent file edits with timestamps and conversation IDs
+     *   - `commits`: Recent git commits affecting this file
+     * - `related_decisions`: Decisions that affect this file
+     * - `mistakes_to_avoid`: Past mistakes related to this file
+     *
+     * @example
+     * ```typescript
+     * const context = await handlers.checkBeforeModify({
+     *   file_path: 'src/storage/SQLiteManager.ts'
+     * });
+     * console.error(context.warning);
+     * console.error(`${context.related_decisions.length} decisions affect this file`);
+     * console.error(`${context.mistakes_to_avoid.length} mistakes to avoid`);
+     * ```
+     */
+    checkBeforeModify(args: Record<string, unknown>): Promise<Types.CheckBeforeModifyResponse>;
+    /**
+     * Show complete timeline of changes to a file.
+     *
+     * Returns a chronological timeline of all edits, commits, and related decisions
+     * for a specific file across all conversations and git history.
+     *
+     * @param args - Evolution arguments:
+     * - `file_path`: Path to the file (required)
+     * - `include_decisions`: Include related decisions (default: true)
+     * - `include_commits`: Include git commits (default: true)
+     *
+     * @returns File evolution timeline containing:
+     * - `file_path`: The file being analyzed
+     * - `total_edits`: Total number of edits to this file
+     * - `timeline`: Chronological array of events (most recent first):
+     *   - `type`: Event type ('edit', 'commit', or 'decision')
+     *   - `timestamp`: When the event occurred
+     *   - `data`: Event-specific data (conversation_id, commit hash, decision text, etc.)
+     *
+     * @example
+     * ```typescript
+     * const evolution = await handlers.getFileEvolution({
+     *   file_path: 'src/index.ts',
+     *   include_decisions: true,
+     *   include_commits: true
+     * });
+     * console.error(`${evolution.total_edits} edits across ${evolution.timeline.length} events`);
+     * evolution.timeline.forEach(event => {
+     *   console.error(`${event.timestamp}: ${event.type}`);
+     * });
+     * ```
+     */
+    getFileEvolution(args: Record<string, unknown>): Promise<Types.GetFileEvolutionResponse>;
+    /**
+     * Link git commits to the conversations where they were made or discussed.
+     *
+     * Finds git commits that are associated with specific conversations, showing
+     * which code changes were made during which conversations. Helps answer "WHY
+     * was this code changed?"
+     *
+     * @param args - Link arguments:
+     * - `query`: Optional search query for commit messages
+     * - `conversation_id`: Optional filter for specific conversation
+     * - `limit`: Maximum number of commits (default: 20)
+     *
+     * @returns Commit links containing:
+     * - `query`: Search query if provided
+     * - `conversation_id`: Conversation filter if provided
+     * - `commits`: Array of linked commits with:
+     *   - `hash`: Short commit hash (7 chars)
+     *   - `full_hash`: Full commit hash
+     *   - `message`: Commit message
+     *   - `author`: Commit author
+     *   - `timestamp`: When commit was made
+     *   - `branch`: Git branch
+     *   - `files_changed`: List of files changed
+     *   - `conversation_id`: Conversation where this was discussed/made
+     * - `total_found`: Number of commits returned
+     *
+     * @example
+     * ```typescript
+     * const links = await handlers.linkCommitsToConversations({
+     *   query: 'fix authentication',
+     *   limit: 10
+     * });
+     * links.commits.forEach(c => {
+     *   console.error(`${c.hash}: ${c.message}`);
+     *   console.error(`  Conversation: ${c.conversation_id}`);
+     * });
+     * ```
+     */
+    linkCommitsToConversations(args: Record<string, unknown>): Promise<Types.LinkCommitsToConversationsResponse>;
+    /**
+     * Find past mistakes to avoid repeating them.
+     *
+     * Searches through extracted mistakes to find documented errors, bugs, and
+     * wrong approaches. Shows what went wrong and how it was corrected.
+     *
+     * @param args - Mistake search arguments:
+     * - `query`: Search query for mistakes (required)
+     * - `mistake_type`: Optional filter by type (logic_error, wrong_approach, misunderstanding, tool_error, syntax_error)
+     * - `limit`: Maximum number of results (default: 10)
+     *
+     * @returns Mistake search results containing:
+     * - `query`: Search query used
+     * - `mistake_type`: Type filter if applied
+     * - `mistakes`: Array of matching mistakes with:
+     *   - `mistake_id`: Mistake identifier
+     *   - `mistake_type`: Type of mistake
+     *   - `what_went_wrong`: Description of the mistake
+     *   - `correction`: How it was fixed
+     *   - `user_correction_message`: User's correction message if available
+     *   - `files_affected`: List of files involved
+     *   - `timestamp`: When the mistake occurred
+     * - `total_found`: Number of mistakes returned
+     *
+     * @example
+     * ```typescript
+     * const mistakes = await handlers.searchMistakes({
+     *   query: 'database transaction',
+     *   mistake_type: 'logic_error',
+     *   limit: 5
+     * });
+     * mistakes.mistakes.forEach(m => {
+     *   console.error(`${m.mistake_type}: ${m.what_went_wrong}`);
+     *   console.error(`Fix: ${m.correction}`);
+     * });
+     * ```
+     */
+    searchMistakes(args: Record<string, unknown>): Promise<Types.SearchMistakesResponse>;
+    /**
+     * Look up requirements and constraints for a component or feature.
+     *
+     * Finds documented requirements, dependencies, performance constraints, and
+     * compatibility requirements that affect a component or feature.
+     *
+     * @param args - Requirements search arguments:
+     * - `component`: Component or feature name (required)
+     * - `type`: Optional filter by requirement type (dependency, performance, compatibility, business)
+     *
+     * @returns Requirements results containing:
+     * - `component`: Component searched
+     * - `type`: Type filter if applied
+     * - `requirements`: Array of matching requirements with:
+     *   - `requirement_id`: Requirement identifier
+     *   - `type`: Requirement type
+     *   - `description`: Requirement description
+     *   - `rationale`: Why this requirement exists
+     *   - `affects_components`: List of affected components
+     *   - `timestamp`: When requirement was documented
+     * - `total_found`: Number of requirements returned
+     *
+     * @example
+     * ```typescript
+     * const reqs = await handlers.getRequirements({
+     *   component: 'authentication',
+     *   type: 'security'
+     * });
+     * reqs.requirements.forEach(r => {
+     *   console.error(`${r.type}: ${r.description}`);
+     *   console.error(`Rationale: ${r.rationale}`);
+     * });
+     * ```
+     */
+    getRequirements(args: Record<string, unknown>): Promise<Types.GetRequirementsResponse>;
+    /**
+     * Query history of tool uses (bash commands, file edits, reads, etc.) with pagination and filtering.
+     *
+     * Shows what tools were used during conversations and their results. Useful
+     * for understanding what commands were run, what files were edited, and
+     * whether operations succeeded or failed.
+     *
+     * @param args - Tool history arguments:
+     * - `tool_name`: Optional filter by tool name (Bash, Edit, Write, Read)
+     * - `file_path`: Optional filter by file path
+     * - `limit`: Maximum number of results (default: 20)
+     * - `offset`: Skip N results for pagination (default: 0)
+     * - `include_content`: Include tool content in response (default: false for security, set true to include)
+     * - `max_content_length`: Maximum characters per content field (default: 500)
+     * - `date_range`: Filter by timestamp range [start, end]
+     * - `conversation_id`: Filter by specific conversation
+     * - `errors_only`: Show only failed tool uses (default: false)
+     *
+     * @returns Tool history containing:
+     * - `tool_name`: Tool filter if applied
+     * - `file_path`: File filter if applied
+     * - `tool_uses`: Array of tool uses (may have truncated content)
+     * - `total_found`: Number of results returned in this page
+     * - `total_in_database`: Total matching records in database
+     * - `has_more`: Whether more results exist beyond current page
+     * - `offset`: Current offset position
+     *
+     * @example
+     * ```typescript
+     * // Get first page of Bash commands
+     * const page1 = await handlers.getToolHistory({
+     *   tool_name: 'Bash',
+     *   limit: 20,
+     *   offset: 0
+     * });
+     *
+     * // Get metadata only (no content)
+     * const metadata = await handlers.getToolHistory({
+     *   include_content: false,
+     *   limit: 50
+     * });
+     *
+     * // Get errors from last 24 hours
+     * const errors = await handlers.getToolHistory({
+     *   errors_only: true,
+     *   date_range: [Date.now() - 86400000, Date.now()]
+     * });
+     * ```
+     */
+    getToolHistory(args: Record<string, unknown>): Promise<Types.GetToolHistoryResponse>;
+    /**
+     * Find conversations that dealt with similar topics or problems.
+     *
+     * Searches across all conversations to find ones that discussed similar topics,
+     * allowing you to learn from past work on similar problems.
+     *
+     * @param args - Similarity search arguments:
+     * - `query`: Description of the topic or problem (required)
+     * - `limit`: Maximum number of sessions (default: 5)
+     *
+     * @returns Similar sessions containing:
+     * - `query`: Search query used
+     * - `sessions`: Array of similar conversation sessions with:
+     *   - `conversation_id`: Session identifier
+     *   - `project_path`: Project path for this session
+     *   - `first_message_at`: When the conversation started
+     *   - `message_count`: Number of messages in the conversation
+     *   - `git_branch`: Git branch at the time
+     *   - `relevance_score`: Similarity score to the query
+     *   - `relevant_messages`: Sample of relevant messages from this session
+     * - `total_found`: Number of sessions returned
+     *
+     * @example
+     * ```typescript
+     * const similar = await handlers.findSimilarSessions({
+     *   query: 'implementing user authentication with JWT',
+     *   limit: 3
+     * });
+     * similar.sessions.forEach(s => {
+     *   console.error(`Session ${s.conversation_id} (${s.message_count} messages)`);
+     *   console.error(`Relevance: ${s.relevance_score.toFixed(2)}`);
+     *   console.error(`Messages: ${s.relevant_messages.length} relevant`);
+     * });
+     * ```
+     */
+    findSimilarSessions(args: Record<string, unknown>): Promise<Types.FindSimilarSessionsResponse>;
+    /**
+     * Recall relevant context and format for application to current work.
+     *
+     * This is a comprehensive context retrieval tool that searches across multiple
+     * data sources (conversations, decisions, mistakes, file changes, commits) and
+     * returns actionable suggestions for applying historical context to current work.
+     *
+     * @param args - Recall arguments:
+     * - `query`: What you're working on or need context for (required)
+     * - `context_types`: Types to recall (default: all types)
+     *   - Options: "conversations", "decisions", "mistakes", "file_changes", "commits"
+     * - `file_path`: Optional filter for file-specific context
+     * - `date_range`: Optional [start_timestamp, end_timestamp] filter
+     * - `limit`: Maximum items per context type (default: 5)
+     *
+     * @returns Recalled context containing:
+     * - `query`: Search query used
+     * - `context_summary`: High-level summary of what was found
+     * - `recalled_context`: Structured context data:
+     *   - `conversations`: Relevant past conversations
+     *   - `decisions`: Related decisions with rationale
+     *   - `mistakes`: Past mistakes to avoid
+     *   - `file_changes`: File modification history
+     *   - `commits`: Related git commits
+     * - `application_suggestions`: Actionable suggestions for applying this context
+     * - `total_items_found`: Total number of context items found
+     *
+     * @example
+     * ```typescript
+     * const context = await handlers.recallAndApply({
+     *   query: 'refactoring database connection pooling',
+     *   context_types: ['decisions', 'mistakes', 'commits'],
+     *   file_path: 'src/database/pool.ts',
+     *   limit: 5
+     * });
+     * console.error(context.context_summary);
+     * context.application_suggestions.forEach(s => console.error(`- ${s}`));
+     * ```
+     */
+    recallAndApply(args: Record<string, unknown>): Promise<Types.RecallAndApplyResponse>;
+    /**
+     * Generate comprehensive project documentation by combining codebase analysis
+     * with conversation history.
+     *
+     * Creates documentation that shows WHAT exists in the code (via CODE-GRAPH-RAG-MCP)
+     * and WHY it was built that way (via conversation history). Requires CODE-GRAPH-RAG-MCP
+     * to be indexed first.
+     *
+     * @param args - Documentation generation arguments:
+     * - `project_path`: Path to the project (defaults to cwd)
+     * - `session_id`: Optional specific session to include
+     * - `scope`: Documentation scope (default: 'full')
+     *   - 'full': Everything (architecture, decisions, quality)
+     *   - 'architecture': Module structure and dependencies
+     *   - 'decisions': Decision log with rationale
+     *   - 'quality': Code quality insights
+     * - `module_filter`: Optional filter for specific module path (e.g., 'src/auth')
+     *
+     * @returns Documentation result containing:
+     * - `success`: Whether generation succeeded
+     * - `project_path`: Project that was documented
+     * - `scope`: Scope of documentation generated
+     * - `documentation`: Generated markdown documentation
+     * - `statistics`: Summary statistics:
+     *   - `modules`: Number of modules documented
+     *   - `decisions`: Number of decisions included
+     *   - `mistakes`: Number of mistakes documented
+     *   - `commits`: Number of commits referenced
+     *
+     * @example
+     * ```typescript
+     * const doc = await handlers.generateDocumentation({
+     *   project_path: '/Users/me/my-project',
+     *   scope: 'full',
+     *   module_filter: 'src/auth'
+     * });
+     * console.error(doc.documentation); // Markdown documentation
+     * console.error(`Documented ${doc.statistics.modules} modules`);
+     * ```
+     */
+    generateDocumentation(args: Record<string, unknown>): Promise<Types.GenerateDocumentationResponse>;
+    /**
+     * Discover old conversation folders that might contain conversation history
+     * for the current project.
+     *
+     * Searches through stored conversation folders to find potential matches for
+     * the current project path. Useful when project paths have changed (e.g., after
+     * moving or renaming a project directory).
+     *
+     * @param args - Discovery arguments:
+     * - `current_project_path`: Current project path (defaults to cwd)
+     *
+     * @returns Discovery results containing:
+     * - `success`: Whether discovery succeeded
+     * - `current_project_path`: Current project path searched for
+     * - `candidates`: Array of potential matches sorted by score:
+     *   - `folder_name`: Name of the conversation folder
+     *   - `folder_path`: Full path to the folder
+     *   - `stored_project_path`: Original project path stored in conversations
+     *   - `score`: Match score (higher is better match)
+     *   - `stats`: Folder statistics:
+     *     - `conversations`: Number of conversations in folder
+     *     - `messages`: Number of messages in folder
+     *     - `files`: Number of .jsonl files
+     *     - `last_activity`: Timestamp of last activity
+     * - `message`: Human-readable status message
+     *
+     * @example
+     * ```typescript
+     * const discovery = await handlers.discoverOldConversations({
+     *   current_project_path: '/Users/me/projects/my-app'
+     * });
+     * console.error(discovery.message);
+     * discovery.candidates.forEach(c => {
+     *   console.error(`Score ${c.score}: ${c.folder_name}`);
+     *   console.error(`  Original path: ${c.stored_project_path}`);
+     *   console.error(`  Stats: ${c.stats.conversations} conversations, ${c.stats.files} files`);
+     * });
+     * ```
+     */
+    discoverOldConversations(args: Record<string, unknown>): Promise<Types.DiscoverOldConversationsResponse>;
+    /**
+     * Migrate or merge conversation history from an old project path to a new one.
+     *
+     * Use this when a project has been moved or renamed to bring the conversation
+     * history along. Supports two modes: 'migrate' (move all files) or 'merge'
+     * (combine with existing files).
+     *
+     * @param args - Migration arguments:
+     * - `source_folder`: Source folder containing old conversations (required)
+     * - `old_project_path`: Original project path in the conversations (required)
+     * - `new_project_path`: New project path to update to (required)
+     * - `dry_run`: Preview changes without applying them (default: false)
+     * - `mode`: Migration mode (default: 'migrate')
+     *   - 'migrate': Move all files from source to target
+     *   - 'merge': Combine source files with existing target files
+     *
+     * @returns Migration result containing:
+     * - `success`: Whether migration succeeded
+     * - `source_folder`: Source folder path
+     * - `target_folder`: Target folder path (where files were copied)
+     * - `files_copied`: Number of files copied/migrated
+     * - `database_updated`: Whether database was updated with new paths
+     * - `backup_created`: Whether backup was created (always true for non-dry-run)
+     * - `message`: Human-readable status message
+     *
+     * @example
+     * ```typescript
+     * // First, preview with dry run
+     * const preview = await handlers.migrateProject({
+     *   source_folder: '/path/to/old/conversations',
+     *   old_project_path: '/old/path/to/project',
+     *   new_project_path: '/new/path/to/project',
+     *   dry_run: true
+     * });
+     * console.error(preview.message); // "Dry run: Would migrate X files..."
+     *
+     * // Then, execute the migration
+     * const result = await handlers.migrateProject({
+     *   source_folder: '/path/to/old/conversations',
+     *   old_project_path: '/old/path/to/project',
+     *   new_project_path: '/new/path/to/project',
+     *   dry_run: false,
+     *   mode: 'migrate'
+     * });
+     * console.error(`Migrated ${result.files_copied} files`);
+     * ```
+     */
+    migrateProject(args: Record<string, unknown>): Promise<Types.MigrateProjectResponse>;
+    /**
+     * Forget conversations by topic/keywords.
+     *
+     * Searches for conversations matching the provided keywords and optionally deletes them.
+     * Creates automatic backup before deletion.
+     *
+     * @param args - Arguments:
+     * - `keywords`: Array of keywords/topics to search for
+     * - `project_path`: Path to the project (defaults to cwd)
+     * - `confirm`: Must be true to actually delete (default: false for preview)
+     *
+     * @returns Result containing:
+     * - `success`: Whether operation succeeded
+     * - `preview_mode`: Whether this was a preview (confirm=false)
+     * - `conversations_found`: Number of conversations matching keywords
+     * - `conversations_deleted`: Number of conversations actually deleted
+     * - `messages_deleted`: Number of messages deleted
+     * - `decisions_deleted`: Number of decisions deleted
+     * - `mistakes_deleted`: Number of mistakes deleted
+     * - `backup_path`: Path to backup file (if deletion occurred)
+     * - `conversation_summaries`: List of conversations with basic info
+     * - `message`: Human-readable status message
+     *
+     * @example
+     * ```typescript
+     * // Preview what would be deleted
+     * const preview = await handlers.forgetByTopic({
+     *   keywords: ['authentication', 'redesign'],
+     *   confirm: false
+     * });
+     *
+     * // Actually delete after reviewing preview
+     * const result = await handlers.forgetByTopic({
+     *   keywords: ['authentication', 'redesign'],
+     *   confirm: true
+     * });
+     * ```
+     */
+    forgetByTopic(args: unknown): Promise<Types.ForgetByTopicResponse>;
+    /**
+     * Search for all context related to a specific file.
+     *
+     * Combines discussions, decisions, and mistakes related to a file
+     * in one convenient query.
+     *
+     * @param args - Search arguments with file_path
+     * @returns Combined file context from all sources
+     */
+    searchByFile(args: Record<string, unknown>): Promise<Types.SearchByFileResponse>;
+    /**
+     * List recent conversation sessions.
+     *
+     * Provides an overview of recent sessions with basic stats.
+     *
+     * @param args - Query arguments with limit/offset
+     * @returns List of recent sessions with summaries
+     */
+    listRecentSessions(args: Record<string, unknown>): Promise<Types.ListRecentSessionsResponse>;
+    /**
+     * Index all projects (Claude Code + Codex).
+     *
+     * Discovers and indexes all projects from both Claude Code and Codex,
+     * registering them in a global index for cross-project search.
+     *
+     * @param args - Indexing arguments
+     * @returns Summary of all indexed projects
+     */
+    indexAllProjects(args: Record<string, unknown>): Promise<Types.IndexAllProjectsResponse>;
+    /**
+     * Search across all indexed projects.
+     *
+     * @param args - Search arguments
+     * @returns Search results from all projects
+     */
+    searchAllConversations(args: Record<string, unknown>): Promise<Types.SearchAllConversationsResponse>;
+    /**
+     * Get decisions from all indexed projects.
+     *
+     * @param args - Query arguments
+     * @returns Decisions from all projects
+     */
+    getAllDecisions(args: Record<string, unknown>): Promise<Types.GetAllDecisionsResponse>;
+    /**
+     * Search mistakes across all indexed projects.
+     *
+     * @param args - Search arguments
+     * @returns Mistakes from all projects
+     */
+    searchAllMistakes(args: Record<string, unknown>): Promise<Types.SearchAllMistakesResponse>;
+    /**
+     * Store a fact, decision, or context in working memory.
+     *
+     * @param args - Remember arguments with key, value, context, tags, ttl
+     * @returns The stored memory item
+     */
+    remember(args: Record<string, unknown>): Promise<Types.RememberResponse>;
+    /**
+     * Recall a specific memory item by key.
+     *
+     * @param args - Recall arguments with key
+     * @returns The recalled memory item or null
+     */
+    recall(args: Record<string, unknown>): Promise<Types.RecallResponse>;
+    /**
+     * Search working memory semantically.
+     *
+     * @param args - Search arguments with query
+     * @returns Relevant memory items
+     */
+    recallRelevant(args: Record<string, unknown>): Promise<Types.RecallRelevantResponse>;
+    /**
+     * List all items in working memory.
+     *
+     * @param args - List arguments with optional tags filter
+     * @returns All memory items
+     */
+    listMemory(args: Record<string, unknown>): Promise<Types.ListMemoryResponse>;
+    /**
+     * Remove a memory item by key.
+     *
+     * @param args - Forget arguments with key
+     * @returns Success status
+     */
+    forget(args: Record<string, unknown>): Promise<Types.ForgetResponse>;
+    /**
+     * Prepare a handoff document from the current session.
+     * Captures decisions, active files, pending tasks, and working memory.
+     *
+     * @param args - Handoff preparation arguments
+     * @returns The prepared handoff document
+     */
+    prepareHandoff(args: Record<string, unknown>): Promise<Types.PrepareHandoffResponse>;
+    /**
+     * Resume from a handoff in a new session.
+     * Loads context from a previous session for continuity.
+     *
+     * @param args - Resume arguments
+     * @returns The resumed handoff context
+     */
+    resumeFromHandoff(args: Record<string, unknown>): Promise<Types.ResumeFromHandoffResponse>;
+    /**
+     * List available handoffs for a project.
+     *
+     * @param args - List arguments
+     * @returns List of available handoffs
+     */
+    listHandoffs(args: Record<string, unknown>): Promise<Types.ListHandoffsResponse>;
+    /**
+     * Get context to inject at the start of a new conversation.
+     * Combines handoffs, decisions, working memory, and file history.
+     *
+     * @param args - Context injection arguments
+     * @returns Structured context for injection
+     */
+    getStartupContext(args: Record<string, unknown>): Promise<Types.GetStartupContextResponse>;
+    /**
+     * Inject relevant context based on the first message in a new conversation.
+     * Returns formatted markdown context for direct use.
+     *
+     * @param args - Injection arguments
+     * @returns Formatted context string
+     */
+    injectRelevantContext(args: Record<string, unknown>): Promise<Types.InjectRelevantContextResponse>;
+}
+//# sourceMappingURL=ToolHandlers.d.ts.map