Skip to content

API.md

Latest commit

 

History

History
2411 lines (1970 loc) · 57.8 KB

API.md

File metadata and controls

2411 lines (1970 loc) · 57.8 KB

MCP Memory Keeper - API Reference

Table of Contents

Session Management

context_session_start

Start a new session or continue from a previous one.

Parameters:

{
  name?: string;           // Optional session name
  description?: string;    // Optional session description
  continueFrom?: string;   // Previous session ID to continue from
  projectDir?: string;     // Project directory for git tracking
  defaultChannel?: string; // Default channel for context items (auto-derived from git branch if not specified)
}

Returns:

{
  sessionId: string;       // Unique session identifier
  name: string;            // Session name
  description?: string;    // Session description if provided
  parentId?: string;       // Parent session ID if branched
  createdAt: string;       // ISO timestamp
}

Example:

// Start new session
await context_session_start({
  name: 'Feature Development',
  description: 'Implementing user authentication',
});

// Continue from previous
await context_session_start({
  name: 'Feature Dev Day 2',
  continueFrom: 'previous-session-id',
});

context_session_list

List recent sessions with optional filtering.

Parameters:

{
  limit?: number;          // Number of sessions to return (default: 10)
  beforeDate?: string;     // Filter sessions before this date
  afterDate?: string;      // Filter sessions after this date
}

Returns:

{
  sessions: Array<{
    id: string;
    name: string;
    description?: string;
    createdAt: string;
    updatedAt: string;
    itemCount: number;
    parentId?: string;
  }>;
  total: number;
}

Context Storage

context_save

Save context information with categories and priorities.

Parameters:

{
  key: string;             // Unique identifier for the context item
  value: string;           // Content to save
  category?: 'task' | 'decision' | 'progress' | 'note' | 'warning' | 'error';
  priority?: 'critical' | 'high' | 'normal' | 'low';
  metadata?: any;          // Additional JSON metadata
  private?: boolean;       // If true, item is only visible in current session (default: false - shared across all sessions)
  channel?: string;        // Channel to save to (default: session's defaultChannel or auto-derived from git branch)
}

Returns:

{
  id: string; // Unique item ID
  key: string; // The provided key
  sessionId: string; // Current session ID
  createdAt: string; // ISO timestamp
}

Example:

// Save public context (default - accessible from all sessions)
await context_save({
  key: 'auth_decision',
  value: 'Using JWT with 24h expiry and refresh tokens',
  category: 'decision',
  priority: 'high',
  metadata: { reviewedBy: 'team', approvedDate: '2024-01-15' },
});

// Save private context (only visible in current session)
await context_save({
  key: 'debug_notes',
  value: 'Local testing with mock API keys',
  category: 'note',
  private: true,
});

context_get

Retrieve context items with flexible filtering. By default, returns all accessible items (public items from all sessions + private items from current session).

Parameters:

{
  key?: string;            // Specific key to retrieve
  category?: string;       // Filter by category
  priority?: string;       // Filter by priority (deprecated - use priorities)
  priorities?: string[];   // Filter by multiple priorities (NEW v0.10.0)
  sessionId?: string;      // Specific session (default: current)
  limit?: number;          // Maximum items to return (default: 100, 0 = unlimited)
  offset?: number;         // Pagination offset (default: 0) (NEW v0.10.0)
  channel?: string;        // Filter by channel (NEW v0.10.0)
  includeMetadata?: boolean; // Include timestamps and size info (NEW v0.10.0)
  sort?: 'created_asc' | 'created_desc' | 'updated_asc' | 'updated_desc' | 'priority'; // Sort order (default: 'created_desc') (NEW v0.10.0)
  createdAfter?: string;   // ISO date - items created after this time (NEW v0.10.0)
  createdBefore?: string;  // ISO date - items created before this time (NEW v0.10.0)
  keyPattern?: string;     // Regex pattern to match keys (NEW v0.10.0)
}

Pagination Defaults:

  • limit: 100 (returns first 100 items by default)
  • offset: 0 (starts from the beginning)
  • sort: 'created_desc' (newest items first)
  • To retrieve all items, set limit to 0
  • Limits are clamped between 1-100 (except 0 for unlimited)

Returns:

{
  items: Array<{
    key: string;
    value: string;
    category?: string;
    priority?: string;
    channel?: string;
    metadata?: any;          // When includeMetadata: true
    size?: number;           // When includeMetadata: true
    created_at?: string;     // When includeMetadata: true
    updated_at?: string;     // When includeMetadata: true
  }>;
  pagination: {
    total: number;           // Total count of matching items
    returned: number;        // Number of items in this response
    offset: number;          // Current offset
    hasMore: boolean;        // Whether more items exist
    nextOffset?: number;     // Offset for next page (if hasMore is true)

    // Extended pagination metadata
    totalCount: number;      // Same as total
    page: number;            // Current page number (1-based)
    pageSize: number;        // Items per page (same as limit)
    totalPages: number;      // Total number of pages
    hasNextPage: boolean;    // Whether next page exists
    hasPreviousPage: boolean; // Whether previous page exists
    previousOffset?: number; // Offset for previous page

    // Additional metadata
    totalSize?: number;      // Combined size of all returned items (when includeMetadata: true)
    averageSize?: number;    // Average size per item (when includeMetadata: true)
    defaultsApplied?: {      // Which defaults were applied
      limit: boolean;
      sort: boolean;
    };
    warning?: string;        // Warning if approaching token limits
  };
}

Examples:

// Get items from specific channel
await context_get({
  channel: 'feature-auth',
});

// Get recent high-priority items with metadata
await context_get({
  priorities: ['high', 'critical'],
  createdAfter: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(),
  includeMetadata: true,
  sort: 'created_desc',
});

// Paginated results
await context_get({
  category: 'task',
  limit: 20,
  offset: 40, // Skip first 40 items
  sort: 'priority',
});

// Pattern matching
await context_get({
  keyPattern: 'auth_.*|login_.*',
  channel: 'feature-auth',
});

context_delete

Delete a specific context item.

Parameters:

{
  key: string;             // Key of item to delete
  sessionId?: string;      // Session ID (default: current)
}

Returns:

{
  success: boolean;
  deletedCount: number;
}

Channel Management

context_list_channels

List all channels across sessions with comprehensive statistics and insights.

Parameters:

{
  sessionId?: string;      // Filter by specific session (default: all sessions)
  includeEmpty?: boolean;  // Include channels with zero items (default: false)
  sort?: 'name' | 'item_count' | 'last_activity'; // Sort order (default: 'name')
  limit?: number;          // Maximum channels to return
  offset?: number;         // Pagination offset
}

Returns:

{
  channels: Array<{
    channel: string; // Channel name
    itemCount: number; // Total items in this channel
    sessions: number; // Number of sessions using this channel
    lastActivity: string; // ISO timestamp of most recent activity
    categories: Record<string, number>; // Item count by category
    priorities: Record<string, number>; // Item count by priority
  }>;
  totalChannels: number; // Total number of channels found
  stats: {
    totalItems: number; // Total items across all channels
    averageItemsPerChannel: number;
    mostActiveChannel: string;
    leastActiveChannel: string;
  }
}

Examples:

// List all active channels
await context_list_channels();

// List channels for current session only
await context_list_channels({
  sessionId: 'current',
});

// Get top 10 most active channels
await context_list_channels({
  sort: 'item_count',
  limit: 10,
});

// Include empty channels for cleanup
await context_list_channels({
  includeEmpty: true,
  sort: 'last_activity',
});

Use Cases:

  1. Channel Discovery: Find all channels being used across your project
  2. Activity Monitoring: Identify most/least active channels
  3. Organization Review: See how work is distributed across channels
  4. Cleanup: Find empty or abandoned channels
  5. Team Coordination: Understand channel usage patterns across sessions

context_channel_stats

Get detailed statistics and insights for a specific channel.

Parameters:

{
  channel: string;         // Channel name (required)
  sessionId?: string;      // Filter by specific session (default: all sessions)
  includeInsights?: boolean; // Generate AI-friendly insights (default: true)
  timeRange?: {           // Optional time range for analysis
    start?: string;       // ISO timestamp
    end?: string;         // ISO timestamp
  };
}

Returns:

{
  channel: string;         // Channel name
  stats: {
    totalItems: number;    // Total items in channel
    totalSessions: number; // Sessions using this channel
    privateItems: number;  // Number of private items
    publicItems: number;   // Number of public items

    byCategory: Record<string, number>;  // Item distribution by category
    byPriority: Record<string, number>;  // Item distribution by priority
    bySession: Array<{     // Per-session breakdown
      sessionId: string;
      sessionName: string;
      itemCount: number;
      lastActivity: string;
    }>;

    activity: {
      firstItem: string;   // ISO timestamp of first item
      lastItem: string;    // ISO timestamp of last item
      durationDays: number; // Days between first and last item
      averageItemsPerDay: number;
      activityTrend: 'increasing' | 'stable' | 'decreasing';
    };

    topKeys: Array<{       // Most common keys
      key: string;
      count: number;
    }>;

    sizeMetrics: {         // Storage metrics
      totalSize: number;   // Total size in bytes
      averageSize: number; // Average item size
      largestItem: {
        key: string;
        size: number;
      };
    };
  };

  insights?: {             // When includeInsights: true
    summary: string;       // Natural language summary
    patterns: string[];    // Identified patterns
    recommendations: string[]; // Suggested actions
    relatedChannels: string[]; // Channels with similar content
  };
}

Examples:

// Get comprehensive stats for a channel
await context_channel_stats({
  channel: 'feature-auth',
});

// Focus on recent activity
await context_channel_stats({
  channel: 'debugging',
  timeRange: {
    start: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(), // Last 7 days
  },
});

// Get stats without AI insights (faster)
await context_channel_stats({
  channel: 'feature-payments',
  includeInsights: false,
});

// Session-specific channel stats
await context_channel_stats({
  channel: 'main',
  sessionId: 'current',
});

Use Cases:

  1. Progress Tracking: Monitor activity and trends in feature channels
  2. Resource Planning: Identify channels consuming most storage
  3. Quality Analysis: Review priority and category distributions
  4. Team Insights: Understand how different sessions contribute to a channel
  5. Decision Making: Use AI insights to guide channel organization

Error Scenarios:

  • CHANNEL_NOT_FOUND: Specified channel does not exist
  • INVALID_PARAMS: Missing required channel parameter
  • DATABASE_ERROR: Database read error during analysis

Performance Considerations:

  • Channel stats are computed in real-time from the database
  • For large channels (>1000 items), consider using includeInsights: false for faster response
  • Results are not cached, so repeated calls will re-compute statistics
  • Time range filtering can significantly improve performance for historical channels

Best Practices:

  1. Regular Monitoring: Check channel stats periodically to maintain organization
  2. Channel Naming: Use consistent, descriptive channel names (e.g., "feature-{name}", "bugfix-{id}")
  3. Privacy Boundaries: Remember that private items are only visible in their creating session
  4. Cleanup Strategy: Use stats to identify channels ready for archival or deletion
  5. Team Coordination: Share channel stats to align team understanding

context_reassign_channel

Move context items between channels based on keys, patterns, or entire channels. This is useful for reorganizing work when branches are renamed, features are merged, or you need to consolidate related items.

Parameters:

{
  toChannel: string;         // Target channel to move items to (required)
  keys?: string[];           // Specific keys to reassign
  keyPattern?: string;       // Pattern to match keys (supports wildcards: *, ?)
  fromChannel?: string;      // Source channel to move all items from
  category?: 'task' | 'decision' | 'progress' | 'note' | 'error' | 'warning';
  priorities?: ('high' | 'normal' | 'low')[];
  sessionId?: string;        // Session ID (defaults to current)
  dryRun?: boolean;          // Preview changes without applying them (default: false)
}

Returns:

{
  success: boolean;
  movedCount: number; // Number of items moved
  items: Array<{
    // Details of moved items (or items that would be moved if dryRun)
    id: string;
    key: string;
    fromChannel: string;
    toChannel: string;
  }>;
}

Examples:

// Move specific items to a new channel
await context_reassign_channel({
  keys: ['auth_config', 'auth_tokens', 'auth_middleware'],
  toChannel: 'feature-authentication',
});

// Move all items matching a pattern
await context_reassign_channel({
  keyPattern: 'test_*',
  toChannel: 'testing',
});

// Move entire channel contents
await context_reassign_channel({
  fromChannel: 'feature-old-auth',
  toChannel: 'feature-new-auth',
});

// Move high-priority tasks only
await context_reassign_channel({
  fromChannel: 'backlog',
  toChannel: 'sprint-15',
  category: 'task',
  priorities: ['high'],
});

// Preview changes before applying
const preview = await context_reassign_channel({
  keyPattern: 'legacy_*',
  toChannel: 'archive',
  dryRun: true,
});
console.log(`Would move ${preview.movedCount} items`);

Use Cases:

  1. Branch Renaming: When git branches are renamed, move all items to match
  2. Feature Consolidation: Merge items from multiple feature branches
  3. Sprint Planning: Move high-priority items to current sprint channel
  4. Cleanup: Move completed or obsolete items to archive channels
  5. Team Handoffs: Reassign work items between team channels

Best Practices:

  1. Always use dryRun: true first to preview large moves
  2. Create the target channel through normal saves if it doesn't exist
  3. Use specific filters (category, priority) to avoid moving unintended items
  4. Document channel moves in your team's workflow

Batch Operations

context_batch_save

Save multiple context items in a single atomic operation. This ensures all items are saved together or none are saved, maintaining data consistency.

Parameters:

{
  items: Array<{
    key: string;             // Unique key for the context item
    value: string;           // Context value to save
    category?: 'task' | 'decision' | 'progress' | 'note' | 'error' | 'warning';
    priority?: 'high' | 'normal' | 'low';
    channel?: string;        // Channel to organize this item
  }>;
  updateExisting?: boolean;  // Update existing items with same key (default: true)
}

Returns:

{
  success: boolean;
  savedCount: number; // Number of items saved
  updatedCount: number; // Number of existing items updated
  items: Array<{
    // Details of saved items
    id: string;
    key: string;
    isNew: boolean; // true if newly created, false if updated
  }>;
}

Examples:

// Save multiple related configuration items
await context_batch_save({
  items: [
    { key: 'db_host', value: 'localhost', category: 'note' },
    { key: 'db_port', value: '5432', category: 'note' },
    { key: 'db_name', value: 'myapp', category: 'note' },
    { key: 'db_pool_size', value: '10', category: 'note' },
  ],
});

// Import task list with priorities
const tasks = [
  { key: 'task_auth', value: 'Implement OAuth2', priority: 'high', category: 'task' },
  { key: 'task_tests', value: 'Add integration tests', priority: 'normal', category: 'task' },
  { key: 'task_docs', value: 'Update API docs', priority: 'low', category: 'task' },
];
await context_batch_save({ items: tasks });

// Save items to specific channel
await context_batch_save({
  items: [
    { key: 'sprint_15_goal', value: 'Complete user management', channel: 'sprint-15' },
    { key: 'sprint_15_capacity', value: '40 story points', channel: 'sprint-15' },
    { key: 'sprint_15_risks', value: 'Backend API delays', channel: 'sprint-15' },
  ],
});

Use Cases:

  1. Bulk Import: Import configuration, tasks, or notes from external sources
  2. Atomic Updates: Ensure related items are saved together
  3. Template Application: Apply predefined sets of context items
  4. Migration: Move data between systems while maintaining consistency

context_batch_delete

Delete multiple context items by keys or pattern in a single atomic operation.

Parameters:

{
  keys?: string[];           // Array of specific keys to delete
  keyPattern?: string;       // Pattern to match keys for deletion (supports wildcards: *, ?)
  sessionId?: string;        // Session ID (defaults to current)
  dryRun?: boolean;          // Preview items to be deleted without actually deleting (default: false)
}

Returns:

{
  success: boolean;
  deletedCount: number; // Number of items deleted
  items: Array<{
    // Details of deleted items (or items that would be deleted if dryRun)
    id: string;
    key: string;
    value: string; // Included in dryRun to help identify items
  }>;
}

Examples:

// Delete specific items
await context_batch_delete({
  keys: ['temp_file_1', 'temp_file_2', 'temp_cache'],
});

// Delete all items matching pattern
await context_batch_delete({
  keyPattern: 'test_*',
});

// Preview deletion
const preview = await context_batch_delete({
  keyPattern: 'old_*',
  dryRun: true,
});
console.log(`Would delete ${preview.deletedCount} items`);

// Clean up session-specific temporary items
await context_batch_delete({
  keyPattern: 'tmp_*',
  sessionId: 'specific-session-id',
});

Use Cases:

  1. Cleanup: Remove temporary or obsolete items
  2. Reset: Clear specific categories of data
  3. Testing: Clean up test data after test runs
  4. Maintenance: Remove old or unused context items

context_batch_update

Update multiple context items with partial updates in a single atomic operation. Only specified fields are updated; others remain unchanged.

Parameters:

{
  updates: Array<{
    key: string;             // Key of the item to update (required)
    value?: string;          // New value (optional)
    category?: 'task' | 'decision' | 'progress' | 'note' | 'error' | 'warning';
    priority?: 'high' | 'normal' | 'low';
    channel?: string;        // New channel (optional)
  }>;
  sessionId?: string;        // Session ID (defaults to current)
}

Returns:

{
  success: boolean;
  updatedCount: number; // Number of items updated
  failedCount: number; // Number of items that couldn't be updated
  results: Array<{
    // Details of update results
    key: string;
    success: boolean;
    error?: string; // Error message if update failed
    changes?: {
      // What was changed
      value?: boolean;
      category?: boolean;
      priority?: boolean;
      channel?: boolean;
    };
  }>;
}

Examples:

// Update priorities for multiple tasks
await context_batch_update({
  updates: [
    { key: 'task_auth', priority: 'high' },
    { key: 'task_ui', priority: 'high' },
    { key: 'task_docs', priority: 'low' },
  ],
});

// Move items to new channel and update category
await context_batch_update({
  updates: [
    { key: 'decision_1', channel: 'archived', category: 'note' },
    { key: 'decision_2', channel: 'archived', category: 'note' },
    { key: 'decision_3', channel: 'archived', category: 'note' },
  ],
});

// Update values while keeping other fields
await context_batch_update({
  updates: [
    { key: 'config_timeout', value: '30000' },
    { key: 'config_retries', value: '5' },
    { key: 'config_batch_size', value: '100' },
  ],
});

Use Cases:

  1. Bulk Status Updates: Update multiple task statuses or priorities
  2. Reorganization: Move groups of items to different channels
  3. Metadata Updates: Update categories or priorities in bulk
  4. Configuration Changes: Update multiple configuration values

Best Practices for Batch Operations:

  1. Use transactions to ensure atomicity - all operations succeed or all fail
  2. Always validate data before batch operations
  3. Use dryRun for delete operations to preview effects
  4. Consider performance impact for large batches (>1000 items)
  5. Log batch operations for audit trails

Context Relationships

context_link

Create a relationship between two context items. This enables building a graph of related items for better organization and discovery.

Parameters:

{
  sourceKey: string;         // Key of the source context item
  targetKey: string;         // Key of the target context item
  relationship: string;      // Type of relationship (see enum below)
  metadata?: object;         // Optional metadata for the relationship
}

Relationship Types:

  • contains - Source contains target (e.g., epic contains task)
  • depends_on - Source depends on target
  • references - Source references target
  • implements - Source implements target
  • extends - Source extends target
  • related_to - General relationship
  • blocks - Source blocks target
  • blocked_by - Source is blocked by target
  • parent_of - Source is parent of target
  • child_of - Source is child of target
  • has_task - Source has associated task
  • documented_in - Source is documented in target
  • serves - Source serves target
  • leads_to - Source leads to target

Returns:

{
  success: boolean;
  relationshipId: string; // Unique ID for the relationship
  source: {
    key: string;
    exists: boolean; // Whether source item exists
  }
  target: {
    key: string;
    exists: boolean; // Whether target item exists
  }
}

Examples:

// Link epic to its tasks
await context_link({
  sourceKey: 'epic_user_management',
  targetKey: 'task_create_user_api',
  relationship: 'contains',
});

// Document dependencies
await context_link({
  sourceKey: 'service_auth',
  targetKey: 'service_database',
  relationship: 'depends_on',
  metadata: { critical: true, version: '1.0' },
});

// Track blocking relationships
await context_link({
  sourceKey: 'task_frontend_integration',
  targetKey: 'task_api_completion',
  relationship: 'blocked_by',
});

// Reference documentation
await context_link({
  sourceKey: 'feature_oauth',
  targetKey: 'doc_oauth_setup',
  relationship: 'documented_in',
});

context_get_related

Get items related to a given context item, with support for multi-level traversal and filtering.

Parameters:

{
  key: string;               // Key of the context item to find relationships for
  relationship?: string;     // Filter by specific relationship type
  depth?: number;            // Traversal depth for multi-level relationships (default: 1)
  direction?: 'outgoing' | 'incoming' | 'both'; // Direction of relationships (default: 'both')
}

Returns:

{
  items: Array<{
    key: string;
    value: string;
    category?: string;
    priority: string;
    relationship: string; // How this item is related
    direction: 'outgoing' | 'incoming';
    distance: number; // How many hops from source (1 = direct)
    path: string[]; // Path of keys from source to this item
    metadata?: object; // Relationship metadata
  }>;
  totalCount: number;
  graph: {
    // Summary of the relationship graph
    nodes: number; // Total unique items in graph
    edges: number; // Total relationships
    maxDepth: number; // Deepest connection found
  }
}

Examples:

// Get all directly related items
const related = await context_get_related({
  key: 'epic_user_management',
});

// Get only dependencies
const deps = await context_get_related({
  key: 'service_api',
  relationship: 'depends_on',
  direction: 'outgoing',
});

// Find what blocks a task (incoming "blocks" = outgoing "blocked_by")
const blockers = await context_get_related({
  key: 'task_deploy',
  relationship: 'blocked_by',
  direction: 'outgoing',
});

// Traverse multiple levels to find all connected items
const fullGraph = await context_get_related({
  key: 'feature_auth',
  depth: 3,
  direction: 'both',
});

Use Cases:

  1. Dependency Analysis: Understand what a component depends on
  2. Impact Assessment: Find all items affected by a change
  3. Task Management: Track blockers and dependencies
  4. Documentation Discovery: Find related docs and examples
  5. Feature Mapping: Understand all components of a feature

Best Practices:

  1. Use specific relationship types for clearer organization
  2. Limit depth for large graphs to avoid performance issues
  3. Add metadata to relationships for richer context
  4. Regularly review and update relationships
  5. Use bidirectional relationships thoughtfully (blocks/blocked_by)

File Management

context_cache_file

Cache file content for change detection.

Parameters:

{
  filePath: string;        // Absolute or relative file path
  content: string;         // File content
  metadata?: any;          // Additional metadata
}

Returns:

{
  id: string; // Cache entry ID
  filePath: string; // Normalized file path
  hash: string; // SHA-256 hash of content
  size: number; // Content size in bytes
}

context_file_changed

Check if a file has changed since last cache.

Parameters:

{
  filePath: string;        // File path to check
  currentContent?: string; // Current content (optional, will read if not provided)
}

Returns:

{
  changed: boolean;        // True if file changed
  previousHash?: string;   // Previous content hash
  currentHash: string;     // Current content hash
  lastCached?: string;     // When file was last cached
}

Checkpoints

context_checkpoint

Create a complete snapshot of current context.

Parameters:

{
  name: string;            // Checkpoint name
  description?: string;    // Optional description
  includeFiles?: boolean;  // Include cached files (default: false)
  includeGitStatus?: boolean; // Include git status (default: false)
}

Returns:

{
  checkpointId: string;    // Unique checkpoint ID
  name: string;            // Checkpoint name
  itemCount: number;       // Number of context items
  fileCount: number;       // Number of files included
  gitBranch?: string;      // Current git branch
  gitStatus?: string;      // Git status output
  createdAt: string;       // ISO timestamp
}

context_restore_checkpoint

Restore context from a checkpoint by creating a new session with the checkpoint data.

Important: This operation creates a NEW session to preserve data safety. Your current session and all its data remain accessible.

Parameters:

{
  name?: string;           // Checkpoint name (latest if not specified)
  checkpointId?: string;   // Specific checkpoint ID
  restoreFiles?: boolean;  // Restore file cache (default: true)
}

Returns: Enhanced user-friendly message explaining:

  • New session creation for data safety
  • How to access your previous work
  • Session switching guidance
  • Data recovery instructions

Behavior:

  1. Creates a new session named "Restored from: {checkpoint-name}"
  2. Copies all checkpoint data to the new session
  3. Switches you to the new session
  4. Preserves your original session completely
  5. Provides clear guidance for session management

Example Response:

✅ Successfully restored from checkpoint: My Checkpoint

🔄 Data Safety: A new session was created to preserve your current work
📋 New Session: 1a2b3c4d ("Restored from: My Checkpoint")
🔙 Original Session: Working Session remains accessible

📊 Restored Data:
- Context items: 15
- Files: 3
- Git branch: main
- Checkpoint created: 2024-01-15T10:30:00Z

💡 Next Steps:
- You are now working in the restored session
- Your previous work is safely preserved in session 2
- Use context_session_list to see all sessions
- Switch sessions anytime without losing data

🆘 Need your previous work? Use context_search_all to find items across sessions

Real-time Monitoring

context_watch

Create, manage, and poll real-time watchers for context changes. This powerful feature enables real-time monitoring of context items based on flexible filters.

Actions

create

Create a new watcher with filters for real-time monitoring.

Parameters:

{
  action: 'create';
  filters?: {
    keys?: string[];         // Specific keys to watch (supports wildcards: "user_*", "*_config")
    categories?: ('task' | 'decision' | 'progress' | 'note' | 'warning' | 'error')[];
    channels?: string[];     // Specific channels to monitor
    priorities?: ('critical' | 'high' | 'normal' | 'low')[];
    sessionIds?: string[];   // Specific sessions (default: current session only)
  };
  includeExisting?: boolean; // Include existing items in first poll (default: false)
  expiresIn?: number;        // Expiration time in seconds (default: 3600)
}

Returns:

{
  watcherId: string;         // Unique watcher identifier
  filters: {                 // Applied filters
    keys?: string[];
    categories?: string[];
    channels?: string[];
    priorities?: string[];
    sessionIds?: string[];
  };
  createdAt: string;         // ISO timestamp
  expiresAt: string;         // ISO timestamp when watcher expires
  lastSequence: number;      // Starting sequence number
}
poll

Poll for changes since last check. Returns only new or updated items.

Parameters:

{
  action: 'poll';
  watcherId: string;         // Watcher ID from create action
  timeout?: number;          // Long-polling timeout in seconds (default: 0 - immediate return)
}

Returns:

{
  items: Array<{
    id: string;
    key: string;
    value: string;
    category?: string;
    priority: string;
    channel: string;
    sessionId: string;
    createdAt: string;
    updatedAt?: string;
    changeType: 'added' | 'updated'; // Type of change
  }>;
  lastSequence: number; // Updated sequence number
  hasMore: boolean; // If more changes are available
  metadata: {
    pollTime: string; // ISO timestamp of poll
    itemCount: number; // Number of items returned
    expired: boolean; // If watcher has expired
  }
}
stop

Stop and remove a watcher.

Parameters:

{
  action: 'stop';
  watcherId: string; // Watcher ID to stop
}

Returns:

{
  success: boolean;
  watcherId: string;
  itemsDelivered: number; // Total items delivered by this watcher
  duration: number; // How long watcher was active (seconds)
}
list

List all active watchers for the current session.

Parameters:

{
  action: 'list';
  includeExpired?: boolean;  // Include expired watchers (default: false)
}

Returns:

{
  watchers: Array<{
    watcherId: string;
    filters: {
      keys?: string[];
      categories?: string[];
      channels?: string[];
      priorities?: string[];
      sessionIds?: string[];
    };
    createdAt: string;
    expiresAt: string;
    lastPoll?: string; // Last poll timestamp
    lastSequence: number;
    itemsDelivered: number; // Total items delivered
    active: boolean; // If watcher is still active
  }>;
  total: number;
}

Examples

Basic Monitoring:

// Watch for high-priority tasks
const watcher = await context_watch({
  action: 'create',
  filters: {
    categories: ['task'],
    priorities: ['high', 'critical'],
  },
});

// Poll for changes
const changes = await context_watch({
  action: 'poll',
  watcherId: watcher.watcherId,
});

if (changes.items.length > 0) {
  console.log(`${changes.items.length} new high-priority tasks`);
}

Wildcard Key Monitoring:

// Watch for all user-related and config changes
const watcher = await context_watch({
  action: 'create',
  filters: {
    keys: ['user_*', '*_config', 'auth_*'],
  },
  includeExisting: true, // Get current state first
});

Channel-specific Monitoring:

// Monitor specific feature channels
const watcher = await context_watch({
  action: 'create',
  filters: {
    channels: ['feature-auth', 'feature-payments'],
    categories: ['error', 'warning'],
  },
  expiresIn: 7200, // 2-hour expiration
});

Long Polling:

// Wait up to 30 seconds for changes
const changes = await context_watch({
  action: 'poll',
  watcherId: watcher.watcherId,
  timeout: 30, // Wait up to 30 seconds
});

Multi-session Monitoring:

// Watch across multiple sessions
const watcher = await context_watch({
  action: 'create',
  filters: {
    sessionIds: ['session-1', 'session-2', 'current'],
    categories: ['decision'],
  },
});

Continuous Monitoring Loop:

// Create watcher
const watcher = await context_watch({
  action: 'create',
  filters: { categories: ['error', 'warning'] },
});

// Monitoring loop
let running = true;
while (running) {
  try {
    const changes = await context_watch({
      action: 'poll',
      watcherId: watcher.watcherId,
      timeout: 30, // Long poll
    });

    for (const item of changes.items) {
      console.log(`[${item.changeType}] ${item.category}: ${item.key}`);
      // Process changes...
    }

    if (changes.metadata.expired) {
      console.log('Watcher expired');
      running = false;
    }
  } catch (error) {
    console.error('Poll error:', error);
    await new Promise(r => setTimeout(r, 5000)); // Wait 5s on error
  }
}

// Cleanup
await context_watch({
  action: 'stop',
  watcherId: watcher.watcherId,
});

Managing Multiple Watchers:

// List all active watchers
const { watchers } = await context_watch({ action: 'list' });

console.log(`Active watchers: ${watchers.length}`);
for (const w of watchers) {
  console.log(`- ${w.watcherId}: ${w.itemsDelivered} items delivered`);
  if (w.filters.categories) {
    console.log(`  Categories: ${w.filters.categories.join(', ')}`);
  }
}

// Stop all watchers
for (const w of watchers) {
  await context_watch({
    action: 'stop',
    watcherId: w.watcherId,
  });
}

Use Cases

  1. Error Monitoring: Watch for errors and warnings in real-time
  2. Task Tracking: Monitor new high-priority tasks across team sessions
  3. Configuration Changes: Track when configuration items are modified
  4. Progress Updates: Follow progress on specific features or tasks
  5. Decision Tracking: Monitor important decisions as they're made
  6. Multi-Agent Coordination: Watch for updates from other AI agents
  7. Debugging: Monitor specific keys during debugging sessions
  8. Audit Trail: Track all changes in critical channels

Best Practices

  1. Filter Specificity: Use specific filters to reduce unnecessary polling overhead
  2. Expiration Management: Set appropriate expiration times based on use case
  3. Error Handling: Always handle expired watchers and network errors
  4. Cleanup: Stop watchers when no longer needed to free resources
  5. Polling Strategy: Use long-polling for real-time needs, short intervals for batch processing
  6. Wildcard Usage: Use wildcards thoughtfully to balance coverage and performance
  7. Session Scope: Remember watchers are session-specific by default

Performance Considerations

  • Watchers use sequence-based tracking for efficient change detection
  • Each poll only returns changes since the last sequence number
  • Long-polling reduces request overhead for real-time monitoring
  • Expired watchers are automatically cleaned up
  • Maximum 100 watchers per session (configurable)
  • Wildcard matching is performed server-side for efficiency

Error Scenarios

  • WATCHER_NOT_FOUND: Invalid or expired watcher ID
  • INVALID_ACTION: Unknown action specified
  • INVALID_FILTERS: Invalid filter parameters
  • MAX_WATCHERS_EXCEEDED: Too many active watchers
  • SESSION_NOT_FOUND: Invalid session ID in filters
  • INVALID_TIMEOUT: Timeout value out of acceptable range

Privacy and Security

  • Watchers respect privacy boundaries: private items only visible in their creating session
  • Cross-session monitoring requires explicit session IDs in filters
  • Watchers automatically expire to prevent resource leaks
  • Each watcher has a unique, unguessable ID
  • Polling from expired watchers returns empty results

Search & Analysis

context_search

Full-text search across context items with advanced filtering and sorting.

Parameters:

{
  query: string;           // Search query (required)
  searchIn?: ('key' | 'value')[];  // Fields to search (default: ['key', 'value'])
  sessionId?: string;      // Session to search (default: current)

  // Filtering options
  category?: string;       // Filter by category
  channel?: string;        // Filter by single channel
  channels?: string[];     // Filter by multiple channels
  priorities?: ('high' | 'normal' | 'low')[];  // Filter by priorities
  keyPattern?: string;     // GLOB pattern for key matching (e.g., "user_*")

  // Time filtering
  createdAfter?: string;   // ISO date string
  createdBefore?: string;  // ISO date string
  relativeTime?: string;   // Natural language time (e.g., "2 hours ago", "yesterday")

  // Sorting and pagination
  sort?: 'created_desc' | 'created_asc' | 'updated_desc' | 'key_asc' | 'key_desc';
  limit?: number;          // Maximum results
  offset?: number;         // Pagination offset
  includeMetadata?: boolean;  // Include detailed metadata
}

Returns (without metadata):

{
  results: Array<{
    key: string;
    value: string;
    category?: string;
    priority: string;
  }>;
}

Returns (with metadata):

{
  items: Array<{
    id: string;
    key: string;
    value: string;
    category?: string;
    priority: string;
    channel: string;
    created_at: string;
    updated_at: string;
    size: number;
    metadata?: any;
  }>;
  totalCount: number;
  page: number;
  pageSize: number;
}

Examples:

// Simple search
await context_search({ query: 'api key' });

// Search with time filtering
await context_search({
  query: 'error',
  relativeTime: '2 hours ago',
  channel: 'debugging',
});

// Advanced filtering with pagination
await context_search({
  query: 'config',
  keyPattern: 'app_*',
  priorities: ['high'],
  sort: 'created_desc',
  limit: 20,
  offset: 0,
  includeMetadata: true,
});

context_diff

Track changes to context items since a specific point in time. Useful for understanding what has been added, modified, or deleted.

Parameters:

{
  since: string;           // Required: ISO timestamp, checkpoint name/ID, or relative time (e.g., "2 hours ago")
  sessionId?: string;      // Session to analyze (default: current)
  category?: string;       // Filter by category
  channel?: string;        // Filter by single channel
  channels?: string[];     // Filter by multiple channels
  includeValues?: boolean; // Include full item values (default: true)
  limit?: number;          // Maximum items per category
  offset?: number;         // Pagination offset
}

Returns:

{
  added: Array<{
    key: string;
    value?: string;        // if includeValues is true
    category?: string;
    priority: string;
    channel: string;
    created_at: string;
  }>;
  modified: Array<{
    key: string;
    value?: string;        // if includeValues is true
    category?: string;
    priority: string;
    channel: string;
    updated_at: string;
  }>;
  deleted: string[];       // Array of deleted keys (only available with checkpoint comparison)
  summary: string;         // e.g., "5 added, 3 modified, 2 deleted"
  period: {
    from: string;          // ISO timestamp
    to: string;            // ISO timestamp (current time)
  };
}

Examples:

// Compare with checkpoint
await context_diff({ since: 'my-checkpoint' });

// Compare with timestamp
await context_diff({ since: '2024-01-01T00:00:00Z' });

// Compare with relative time
await context_diff({
  since: '2 hours ago',
  channel: 'feature-branch',
});

// Get summary without values
await context_diff({
  since: 'yesterday',
  includeValues: false,
  category: 'task',
});

context_summarize

Generate AI-friendly summary of context.

Parameters:

{
  categories?: string[];   // Categories to include
  sessionId?: string;      // Specific session (default: current)
  maxLength?: number;      // Maximum summary length
  format?: 'markdown' | 'json' | 'text';
}

Returns:

{
  summary: string; // Formatted summary
  stats: {
    totalItems: number;
    byCategory: Record<string, number>;
    byPriority: Record<string, number>;
  }
  sessionInfo: {
    id: string;
    name: string;
    duration: string;
  }
}

context_analyze

Analyze context to extract entities and relationships.

Parameters:

{
  categories?: string[];   // Categories to analyze
  sessionId?: string;      // Session to analyze
  maxDepth?: number;       // Relationship depth (default: 2)
}

Returns:

{
  entities: Array<{
    id: string;
    type: string;
    name: string;
    count: number;
    attributes?: any;
  }>;
  relations: Array<{
    subject: string;
    predicate: string;
    object: string;
    confidence: number;
  }>;
  stats: {
    totalEntities: number;
    totalRelations: number;
    types: Record<string, number>;
  }
}

Export/Import

context_export

Export context data to a JSON file with enhanced validation and statistics.

Parameters:

{
  sessionId?: string;      // Session to export (default: current)
  sessionIds?: string[];   // Multiple sessions to export
  format?: 'json' | 'csv'; // Export format (default: json)
  outputPath?: string;     // Custom output path
  includeMetadata?: boolean; // Include system metadata
  confirmEmpty?: boolean;  // Bypass empty export warning (default: false) [NEW v0.11.0]
  includeStats?: boolean;  // Include detailed statistics (default: false) [NEW v0.11.0]
}

Returns (Standard):

{
  filePath: string; // Output file path
  stats: {
    sessions: number;
    items: number;
    files: number;
    checkpoints: number;
    size: number; // File size in bytes
  }
}

Returns (With includeStats=true):

{
  filePath: string; // Output file path
  stats: {
    sessions: number;
    items: number;
    files: number;
    checkpoints: number;
    size: number; // File size in bytes
  }
  detailedStats: {
    // Additional statistics [NEW v0.11.0]
    byCategory: Record<string, number>; // Item count by category
    byPriority: Record<string, number>; // Item count by priority
    byChannel: Record<string, number>; // Item count by channel
    dateRange: {
      earliest: string; // ISO timestamp of earliest item
      latest: string; // ISO timestamp of latest item
    }
    averageItemSize: number; // Average item size in bytes
    totalValueSize: number; // Total size of all item values
  }
}

Error Scenarios:

  • EMPTY_EXPORT: Attempted to export with no data (unless confirmEmpty=true)
  • NO_SESSION: No active session and no sessionId provided
  • SESSION_NOT_FOUND: Specified session does not exist
  • INVALID_FORMAT: Unsupported export format
  • FILE_WRITE_ERROR: Failed to write export file
  • DATABASE_ERROR: Database read error during export

Examples:

// Basic export of current session
await context_export();

// Export with detailed statistics
await context_export({
  includeStats: true,
});

// Export multiple sessions
await context_export({
  sessionIds: ['session-1', 'session-2'],
  outputPath: './exports/multi-session-backup.json',
  includeStats: true,
});

// Force export even if empty
await context_export({
  confirmEmpty: true, // No warning for empty exports
});

// Handle empty export scenario
try {
  await context_export();
} catch (error) {
  if (error.code === 'EMPTY_EXPORT') {
    console.log('No data to export. Use confirmEmpty:true to bypass.');
    // Either add some data or confirm empty export
    await context_export({ confirmEmpty: true });
  }
}

Best Practices:

  1. Regular Backups: Export important sessions regularly
  2. Include Statistics: Use includeStats:true for export verification
  3. Check Empty Exports: Handle EMPTY_EXPORT errors appropriately
  4. Archive Old Sessions: Export and compress old sessions to save space
  5. Version Control: Consider adding exports to version control for team sharing

Backward Compatibility:

  • The confirmEmpty and includeStats parameters are optional
  • Existing code will continue to work without changes
  • Empty exports will show a warning but can be bypassed with confirmEmpty:true

context_import

Import context from file.

Parameters:

{
  filePath: string;        // Path to import file
  merge?: boolean;         // Merge with existing (default: false)
  mergeStrategy?: 'skip' | 'overwrite' | 'rename';
  sessionName?: string;    // Override session name
}

Returns:

{
  imported: {
    sessions: number;
    items: number;
    files: number;
    checkpoints: number;
  };
  skipped: number;
  errors: string[];
  sessionIds: string[];    // Imported session IDs
}

Knowledge Graph

context_find_related

Find entities related to a key.

Parameters:

{
  key: string;             // Entity key to search from
  maxDepth?: number;       // Relationship depth (default: 2)
  relationTypes?: string[]; // Filter by relation types
  limit?: number;          // Maximum results
}

Returns:

{
  entities: Array<{
    id: string;
    name: string;
    type: string;
    distance: number; // Relationship distance
    path: string[]; // Relationship path
  }>;
  relations: Array<{
    subject: string;
    predicate: string;
    object: string;
  }>;
}

context_visualize

Generate visualization data for context.

Parameters:

{
  type: 'graph' | 'timeline' | 'heatmap';
  sessionId?: string;      // Session to visualize
  startDate?: string;      // For timeline view
  endDate?: string;        // For timeline view
  groupBy?: 'hour' | 'day' | 'week'; // Timeline grouping
}

Returns:

// For graph type:
{
  nodes: Array<{
    id: string;
    label: string;
    type: string;
    size: number;
    color?: string;
  }>;
  edges: Array<{
    source: string;
    target: string;
    label: string;
    weight: number;
  }>;
}

// For timeline type:
{
  periods: Array<{
    period: string;
    count: number;
    categories: Record<string, number>;
    events: Array<{
      time: string;
      type: string;
      description: string;
    }>;
  }>;
}

Semantic Search

context_semantic_search

Search using natural language queries.

Parameters:

{
  query: string;           // Natural language query
  topK?: number;           // Number of results (default: 10)
  minSimilarity?: number;  // Minimum similarity score (0-1)
  sessionId?: string;      // Specific session or 'all'
  categories?: string[];   // Filter by categories
}

Returns:

{
  results: Array<{
    id: string;
    key: string;
    value: string;
    similarity: number;    // Similarity score (0-1)
    category?: string;
    priority?: string;
    sessionId: string;
  }>;
  queryEmbedding: number[]; // Query vector for debugging
}

Multi-Agent System

context_delegate

Delegate analysis tasks to specialized agents.

Parameters:

{
  taskType: 'analyze' | 'synthesize' | string[];  // Task or chain
  input: any | any[];      // Task-specific input
  chain?: boolean;         // Chain multiple tasks
  context?: any;           // Additional context
}

Analysis Input Types:

// Pattern Analysis
{
  analysisType: 'patterns';
  categories?: string[];
  timeframe?: string;
}

// Relationship Analysis
{
  analysisType: 'relationships';
  maxDepth?: number;
  entityTypes?: string[];
}

// Trend Analysis
{
  analysisType: 'trends';
  timeframe?: string;
  metrics?: string[];
}

// Comprehensive Analysis
{
  analysisType: 'comprehensive';
  includeAll?: boolean;
}

Synthesis Input Types:

// Summary Generation
{
  synthesisType: 'summary';
  maxLength?: number;
  categories?: string[];
}

// Recommendations
{
  synthesisType: 'recommendations';
  analysisResults?: any;
  priorities?: string[];
}

// Narrative Report
{
  synthesisType: 'narrative';
  includeMetrics?: boolean;
  includeLearnings?: boolean;
}

Returns:

{
  result: any;             // Task-specific results
  confidence: number;      // Agent confidence (0-1)
  reasoning?: string;      // Agent reasoning
  metadata?: {
    duration: number;      // Processing time (ms)
    agentType: string;     // Agent that processed
    taskId: string;        // Unique task ID
  };
}

Advanced Features

context_branch_session

Create a branch from current session.

Parameters:

{
  branchName: string;      // Name for the branch
  copyDepth?: 'shallow' | 'deep'; // What to copy
  description?: string;    // Branch description
}

Returns:

{
  branchId: string; // New session ID
  parentId: string; // Parent session ID
  copiedItems: number; // Items copied
  copiedFiles: number; // Files copied
}

context_merge_sessions

Merge another session into current.

Parameters:

{
  sourceSessionId: string; // Session to merge from
  conflictResolution: 'keep_current' | 'keep_source' | 'keep_newest';
  categories?: string[];   // Specific categories to merge
}

Returns:

{
  merged: number; // Items merged
  conflicts: number; // Conflicts resolved
  skipped: number; // Items skipped
  stats: {
    byCategory: Record<string, number>;
    byResolution: Record<string, number>;
  }
}

context_journal_entry

Add a journal entry with tags and mood.

Parameters:

{
  entry: string;           // Journal entry text
  tags?: string[];         // Tags for categorization
  mood?: 'excited' | 'happy' | 'neutral' | 'frustrated' | 'stressed';
}

Returns:

{
  id: string; // Entry ID
  createdAt: string; // Timestamp
  wordCount: number; // Entry word count
}

context_timeline

Generate timeline view of activity.

Parameters:

{
  startDate?: string;      // Start date (ISO)
  endDate?: string;        // End date (ISO)
  groupBy?: 'hour' | 'day' | 'week';
  includeJournals?: boolean;
  sessionId?: string;
  includeItems?: boolean;  // Include actual items, not just counts (NEW v0.10.0)
  categories?: string[];   // Filter by specific categories (NEW v0.10.0)
  relativeTime?: boolean;  // Show "2 hours ago" format (NEW v0.10.0)
  itemsPerPeriod?: number; // Max items to show per period (NEW v0.10.0)
}

Returns:

{
  periods: Array<{
    period: string; // Period label
    startTime: string; // Period start
    endTime: string; // Period end
    relativeTime?: string; // When relativeTime: true (NEW v0.10.0)
    items: {
      total: number;
      byCategory: Record<string, number>;
      details?: Array<{
        // When includeItems: true (NEW v0.10.0)
        id: string;
        key: string;
        value: string;
        category?: string;
        priority?: string;
        channel?: string;
        createdAt: string;
      }>;
    };
    journals: Array<{
      id: string;
      entry: string;
      mood?: string;
      tags?: string[];
    }>;
    activity: number; // Activity score
  }>;
  summary: {
    totalPeriods: number;
    totalItems: number;
    totalJournals: number;
    mostActiveperiod: string;
  }
}

Examples:

// Basic timeline for today
await context_timeline({
  groupBy: 'hour',
});

// Detailed timeline with items
await context_timeline({
  startDate: '2025-01-20T00:00:00Z',
  endDate: '2025-01-26T23:59:59Z',
  groupBy: 'day',
  includeItems: true,
  categories: ['task', 'progress'],
  itemsPerPeriod: 10,
});

// Timeline with relative times
await context_timeline({
  groupBy: 'hour',
  relativeTime: true,
  includeItems: true,
});

context_compress

Compress old context to save space.

Parameters:

{
  olderThan: string;       // ISO date cutoff
  preserveCategories?: string[]; // Categories to keep
  targetSize?: number;     // Target KB (optional)
  sessionId?: string;      // Specific session
}

Returns:

{
  compressed: {
    items: number; // Items compressed
    originalSize: number; // Original KB
    compressedSize: number; // Compressed KB
    ratio: number; // Compression ratio
  }
  preserved: number; // Items preserved
  deleted: number; // Items deleted
  summary: {
    byCategory: Record<string, number>;
    dateRange: {
      start: string;
      end: string;
    }
  }
}

context_integrate_tool

Record events from other MCP tools.

Parameters:

{
  toolName: string;        // Tool identifier
  eventType: string;       // Event type
  data: any;               // Event data
  important?: boolean;     // Create context item
}

Returns:

{
  eventId: string;         // Event ID
  createdAt: string;       // Timestamp
  contextItemId?: string;  // If important=true
}

Error Handling

All tools follow consistent error handling:

Error Response:

{
  error: {
    code: string;          // Error code
    message: string;       // Human-readable message
    details?: any;         // Additional details
  }
}

Common Error Codes:

  • INVALID_PARAMS: Invalid or missing parameters
  • SESSION_NOT_FOUND: Session does not exist
  • ITEM_NOT_FOUND: Context item not found
  • FILE_NOT_FOUND: File does not exist
  • DATABASE_ERROR: Database operation failed
  • PARSE_ERROR: Failed to parse data
  • PERMISSION_ERROR: Insufficient permissions
  • STORAGE_FULL: Database storage limit reached

Example Error Handling:

try {
  const result = await context_save({
    key: 'example',
    value: 'test',
  });
} catch (error) {
  if (error.code === 'STORAGE_FULL') {
    // Compress old data
    await context_compress({
      olderThan: '30 days ago',
    });
    // Retry
  }
}

Best Practices

  1. Session Management: Start a new session for each major task or feature
  2. Categories: Use consistent categories for better organization
  3. Priorities: Reserve 'critical' for truly important items
  4. Keys: Use descriptive, searchable keys
  5. Metadata: Store structured data in metadata field
  6. Checkpoints: Create checkpoints before major changes
  7. Compression: Regularly compress old data to maintain performance
  8. Search: Use semantic search for natural language queries

Performance Tips

  1. Batch Operations: Use single calls with multiple items when possible
  2. Selective Loading: Use filters to load only needed context
  3. Regular Cleanup: Compress or export old sessions
  4. Indexed Searches: Search by key is faster than full-text
  5. Limit Results: Always specify reasonable limits

Pre-built Query Library

Common queries optimized for performance:

Development Queries

// Recent high-priority tasks
{
  category: "task",
  priority: "high",
  limit: 10
}

// Today's decisions
{
  category: "decision",
  afterDate: new Date().toISOString().split('T')[0]
}

// Recent errors with context
{
  category: "error",
  limit: 20,
  includeMetadata: true
}

Analysis Queries

// Find related code changes
await context_semantic_search({
  query: 'authentication refactor',
  minSimilarity: 0.7,
  categories: ['task', 'decision'],
});

// Track feature progress
await context_search({
  query: 'feature:user-management status:*',
  searchIn: ['value'],
  categories: ['progress'],
});

Team Queries

// Blockers and impediments
{
  query: "blocked OR waiting OR impediment",
  categories: ["task", "warning"],
  priority: "high"
}

// Recent decisions by area
{
  category: "decision",
  query: "area:frontend OR area:backend",
  groupBy: "metadata.area"
}

Performance Queries

// Slow operations
{
  query: "duration:>1000ms",
  categories: ["progress"],
  sortBy: "metadata.duration",
  order: "desc"
}

// Memory usage patterns
{
  query: "memory usage",
  categories: ["progress", "warning"],
  timeRange: "-7d"
}

For more examples and patterns, see RECIPES.md