mcp-memory-gateway

Instructions

Implementation Reference

• scripts/contextfs.js:639-778 (handler)

  The core implementation of `constructContextPack` which constructs a context pack by querying, ranking, and structuring documents from the context filesystem.

  function constructContextPack({ query = '', maxItems = 8, maxChars = 6000, namespaces = [] } = {}) {
    const normalizedNamespaces = normalizeNamespaces(namespaces);
    const tokens = tokenizeQuery(query);
    const sourceHash = getSourceHash(normalizedNamespaces);
  
    const cacheHit = findSemanticCacheHit({
      query,
      namespaces: normalizedNamespaces,
      maxItems,
      maxChars,
    });
  
    if (cacheHit) {
      const packId = `pack_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
      const cachedPack = cacheHit.entry.pack;
      const pack = {
        ...cachedPack,
        packId,
        query,
        createdAt: nowIso(),
        cache: {
          hit: true,
          similarity: Number(cacheHit.score.toFixed(4)),
          matchedQuery: cacheHit.entry.query,
          sourcePackId: cachedPack.packId,
        },
      };
  
      appendJsonl(path.join(CONTEXTFS_ROOT, NAMESPACES.provenance, 'packs.jsonl'), pack);
      recordProvenance({
        type: 'context_pack_cache_hit',
        packId,
        sourcePackId: cachedPack.packId,
        query,
        similarity: Number(cacheHit.score.toFixed(4)),
        itemCount: Array.isArray(pack.items) ? pack.items.length : 0,
      });
  
      return pack;
    }
  
    const candidates = loadCandidates(normalizedNamespaces)
      .map((doc) => ({ doc, score: scoreDocument(doc, tokens) }))
      .sort((a, b) => b.score - a.score);
  
    const selected = [];
    let usedChars = 0;
    let skippedByMaxChars = 0;
  
    for (const item of candidates) {
      if (selected.length >= maxItems) break;
  
      const snippet = `${item.doc.title}\n${item.doc.content || ''}`;
      if (usedChars + snippet.length > maxChars) {
        skippedByMaxChars += 1;
        continue;
      }
  
      // Context Structuralizer (EvoSkill Hardening)
      // Parse unstructured text back into a high-density State Document
      const structuredContext = {
        rawContent: item.doc.content || '',
        reasoning: null,
        whatWentWrong: null,
        whatToChange: null,
        rubricFailure: null
      };
  
      const lines = (item.doc.content || '').split('\n');
      for (const line of lines) {
        if (line.startsWith('Reasoning:')) structuredContext.reasoning = line.replace('Reasoning:', '').trim();
        else if (line.startsWith('What went wrong:')) structuredContext.whatWentWrong = line.replace('What went wrong:', '').trim();
        else if (line.startsWith('How to avoid:')) structuredContext.whatToChange = line.replace('How to avoid:', '').trim();
        else if (line.startsWith('Rubric failing criteria:')) structuredContext.rubricFailure = line.replace('Rubric failing criteria:', '').trim();
      }
  
      selected.push({
        id: item.doc.id,
        namespace: item.doc.namespace,
        title: item.doc.title,
        structuredContext,
        tags: item.doc.tags || [],
        score: item.score,
      });
      usedChars += snippet.length;
    }
  
    const visibility = {
      itemCount: selected.length,
      sourceCandidateCount: candidates.length,
      hiddenCount: Math.max(candidates.length - selected.length, 0),
      maxItemsHit: candidates.length > maxItems && selected.length >= maxItems,
      maxCharsHit: skippedByMaxChars > 0,
      skippedByMaxChars,
      remainingCharBudget: Math.max(maxChars - usedChars, 0),
      visibleTitles: selected.slice(0, 5).map((item) => item.title),
    };
  
    const packId = `pack_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
    const pack = {
      packId,
      query,
      maxItems,
      maxChars,
      usedChars,
      namespaces: normalizedNamespaces,
      createdAt: nowIso(),
      items: selected,
      visibility,
      cache: {
        hit: false,
      },
      sourceHash,
    };
  
    appendJsonl(path.join(CONTEXTFS_ROOT, NAMESPACES.provenance, 'packs.jsonl'), pack);
    appendSemanticCacheEntry({
      id: `cache_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
      timestamp: nowIso(),
      key: buildSemanticCacheKey({
        namespaces: normalizedNamespaces,
        maxItems,
        maxChars,
      }),
      query,
      tokens,
      sourceHash,
      pack,
    });
    recordProvenance({
      type: 'context_pack_constructed',
      packId,
      query,
      itemCount: selected.length,
      usedChars,
      sourceHash,
    });
  
    return pack;
  }