context_gc

Instructions

Implementation Reference

• src/tools/registry.ts:182-198 (handler)

  Handler function for the context_gc tool. Takes optional 'strategy' (lru/all/older-than) and 'ttlMinutes' params, calls cache.gc(), and returns a result message.

  server.tool(
    "context_gc",
    "Trigger context garbage collection. This clears cached file skeletons that are no longer needed, freeing context window space. Use this when you notice context is getting full or after completing a task branch.",
    {
      strategy: z.enum(["lru", "all", "older-than"]).optional().describe("GC strategy: 'lru' evicts least-recently-used entries, 'all' clears everything, 'older-than' clears entries older than TTL. Default: 'lru'."),
      ttlMinutes: z.number().optional().describe("Only used with 'older-than' strategy. Entries older than this many minutes will be evicted. Default: 30."),
    },
    async (args): Promise<ToolResult> => {
      const evicted = cache.gc(args.strategy ?? "lru", args.ttlMinutes);
      return {
        content: [{
          type: "text",
          text: `[ContextGC] GC complete. Evicted ${evicted} cache entries. Cache now has ${cache.size} entries.`,
        }],
      };
    }
  );

• src/memory/cache.ts:77-93 (helper)

  CacheManager.gc() method that implements the actual garbage collection logic. Supports three strategies: 'all' (clear everything), 'older-than' (evict entries older than cutoff), and 'lru' (evicts entries last accessed before the cutoff time).

  gc(strategy: "lru" | "all" | "older-than", ttlMinutes?: number): number {
    let evicted = 0;
    if (strategy === "all") {
      evicted = this.cache.size;
      this.cache.clear();
      this.totalBytes = 0;
    } else if (strategy === "older-than" || strategy === "lru") {
      const cutoff = Date.now() - (ttlMinutes ?? 30) * 60 * 1000;
      for (const [key, entry] of this.cache) {
        if (entry.lastAccessedAt < cutoff) {
          this.evict(key);
          evicted++;
        }
      }
    }
    return evicted;
  }

• src/tools/registry.ts:179-198 (registration)

  Registration of the context_gc tool via server.tool() in registerAllTools().

  // ─────────────────────────────────────────────────────
  // Tool 4: context_gc
  // ─────────────────────────────────────────────────────
  server.tool(
    "context_gc",
    "Trigger context garbage collection. This clears cached file skeletons that are no longer needed, freeing context window space. Use this when you notice context is getting full or after completing a task branch.",
    {
      strategy: z.enum(["lru", "all", "older-than"]).optional().describe("GC strategy: 'lru' evicts least-recently-used entries, 'all' clears everything, 'older-than' clears entries older than TTL. Default: 'lru'."),
      ttlMinutes: z.number().optional().describe("Only used with 'older-than' strategy. Entries older than this many minutes will be evicted. Default: 30."),
    },
    async (args): Promise<ToolResult> => {
      const evicted = cache.gc(args.strategy ?? "lru", args.ttlMinutes);
      return {
        content: [{
          type: "text",
          text: `[ContextGC] GC complete. Evicted ${evicted} cache entries. Cache now has ${cache.size} entries.`,
        }],
      };
    }
  );

• src/config/schema.ts:3-26 (schema)

  Configuration schema including cache settings (maxEntries, maxTotalBytes, ttlMs) which define the constraints within which the GC operates.

  export interface ContextGCConfig {
    parser: {
      maxFileSizeBytes: number;
      parseTimeoutMs: number;
    };
    skeleton: {
      preserveComments: "none" | "doc" | "all";
      preserveTypes: boolean;
      preserveImports: boolean;
      preserveExports: boolean;
      maxOutputLines: number;
    };
    cache: {
      maxEntries: number;
      maxTotalBytes: number;
      ttlMs: number;
    };
    logTrimmer: {
      maxFrames: number;
      filterPatterns: string[];
    };
    enabled: boolean;
    logLevel: string;
  }