@exaudeus/memory-mcp 1.0.0 → 1.1.0

package/dist/formatters.d.ts

@@ -1,4 +1,6 @@
 import type { MemoryStats, StaleEntry, ConflictPair, BehaviorConfig } from './types.js';
+import { type FilterGroup } from './text-analyzer.js';
+import type { MarkdownMemoryStore } from './store.js';
 /** Format the stale entries section for briefing/context responses */
 export declare function formatStaleSection(staleDetails: readonly StaleEntry[]): string;
 /** Format the conflict detection warning for query/context responses */
@@ -8,3 +10,16 @@ export declare function formatStats(lobe: string, result: MemoryStats): string;
 /** Format the active behavior config section for diagnostics.
  *  Shows effective values and marks overrides vs defaults clearly. */
 export declare function formatBehaviorConfigSection(behavior?: BehaviorConfig): string;
+/** Merge tag frequencies from multiple stores — pure function over a collection */
+export declare function mergeTagFrequencies(stores: Iterable<MarkdownMemoryStore>): ReadonlyMap<string, number>;
+/** Build query footer — pure function, same inputs → same output.
+ *  Accepts parsed FilterGroup[] to avoid reparsing. */
+export declare function buildQueryFooter(opts: {
+    readonly filterGroups: readonly FilterGroup[];
+    readonly rawFilter: string | undefined;
+    readonly tagFreq: ReadonlyMap<string, number>;
+    readonly resultCount: number;
+    readonly scope: string;
+}): string;
+/** Build tag primer section for session briefing — pure function */
+export declare function buildTagPrimerSection(tagFreq: ReadonlyMap<string, number>): string;

package/dist/formatters.js

@@ -2,7 +2,8 @@
 //
 // Pure functions — no side effects, no state. Each takes structured data
 // and returns a formatted string for the tool response.
-import { DEFAULT_STALE_DAYS_STANDARD, DEFAULT_STALE_DAYS_PREFERENCES, DEFAULT_MAX_STALE_IN_BRIEFING, DEFAULT_MAX_DEDUP_SUGGESTIONS, DEFAULT_MAX_CONFLICT_PAIRS, } from './thresholds.js';
+import { DEFAULT_STALE_DAYS_STANDARD, DEFAULT_STALE_DAYS_PREFERENCES, DEFAULT_MAX_STALE_IN_BRIEFING, DEFAULT_MAX_DEDUP_SUGGESTIONS, DEFAULT_MAX_CONFLICT_PAIRS, MAX_FOOTER_TAGS, } from './thresholds.js';
+import { analyzeFilterGroups } from './text-analyzer.js';
 /** Format the stale entries section for briefing/context responses */
 export function formatStaleSection(staleDetails) {
     const lines = [
@@ -43,6 +44,12 @@ export function formatStats(lobe, result) {
     const trustLines = Object.entries(result.byTrust)
         .map(([trust, count]) => `  - ${trust}: ${count}`)
         .join('\n');
+    const tagLines = Object.entries(result.byTag).length > 0
+        ? Object.entries(result.byTag)
+            .sort((a, b) => b[1] - a[1])
+            .map(([tag, count]) => `  - ${tag}: ${count}`)
+            .join('\n')
+        : '  (none)';
     const corruptLine = result.corruptFiles > 0 ? `\n**Corrupt files:** ${result.corruptFiles}` : '';
     return [
         `## [${lobe}] Memory Stats`,
@@ -57,6 +64,9 @@ export function formatStats(lobe, result) {
         `### By Trust Level`,
         trustLines,
         ``,
+        `### By Tag`,
+        tagLines,
+        ``,
         `### Freshness`,
         `  - Fresh: ${result.byFreshness.fresh}`,
         `  - Stale: ${result.byFreshness.stale}`,
@@ -90,3 +100,82 @@ export function formatBehaviorConfigSection(behavior) {
     }
     return lines.join('\n');
 }
+/** Merge tag frequencies from multiple stores — pure function over a collection */
+export function mergeTagFrequencies(stores) {
+    const merged = new Map();
+    for (const store of stores) {
+        const freq = store.getTagFrequency();
+        for (const [tag, count] of freq) {
+            merged.set(tag, (merged.get(tag) ?? 0) + count);
+        }
+    }
+    return merged;
+}
+/** Build query footer — pure function, same inputs → same output.
+ *  Accepts parsed FilterGroup[] to avoid reparsing. */
+export function buildQueryFooter(opts) {
+    const { filterGroups, rawFilter, tagFreq, resultCount, scope } = opts;
+    const mode = analyzeFilterGroups(filterGroups);
+    const lines = [];
+    // 1. Query mode explanation
+    switch (mode.kind) {
+        case 'no-filter':
+            lines.push(`Showing all entries in scope "${scope}"`);
+            break;
+        case 'keyword-only':
+            lines.push(`Searched keywords: ${mode.terms.join(', ')} (stemmed)`);
+            break;
+        case 'tag-only':
+            lines.push(`Filtered by tags: ${mode.tags.map(t => `#${t}`).join(', ')} (exact match)`);
+            break;
+        case 'complex':
+            const features = [];
+            if (mode.hasTags)
+                features.push('#tags');
+            if (mode.hasExact)
+                features.push('=exact');
+            if (mode.hasNot)
+                features.push('-NOT');
+            if (mode.hasOr)
+                features.push('|OR');
+            lines.push(`Complex filter: ${features.join(', ')}`);
+            break;
+    }
+    // 2. Available tags (always shown, capped for readability)
+    if (tagFreq.size > 0) {
+        const topTags = [...tagFreq.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, MAX_FOOTER_TAGS)
+            .map(([tag, count]) => `${tag}(${count})`)
+            .join(', ');
+        const remainder = tagFreq.size > MAX_FOOTER_TAGS ? ` + ${tagFreq.size - MAX_FOOTER_TAGS} more` : '';
+        lines.push(`Available tags: ${topTags}${remainder}`);
+    }
+    // 3. Zero-results suggestion (adaptive) — only when using keywords and tags exist
+    if (resultCount === 0 && mode.kind === 'keyword-only' && tagFreq.size > 0) {
+        const topTag = [...tagFreq.entries()].sort((a, b) => b[1] - a[1])[0][0];
+        lines.push(`→ No keyword matches. Try: filter: "#${topTag}" for exact category.`);
+    }
+    // 4. Syntax reference — show on failure or complex queries (not on simple successful queries)
+    if (resultCount === 0 || mode.kind === 'complex') {
+        lines.push(`Syntax: #tag | =exact | -NOT | word (stemmed) | A B (AND) | A|B (OR)`);
+    }
+    return lines.join('\n');
+}
+/** Build tag primer section for session briefing — pure function */
+export function buildTagPrimerSection(tagFreq) {
+    if (tagFreq.size === 0)
+        return '';
+    const allTags = [...tagFreq.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .map(([tag, count]) => `${tag}(${count})`)
+        .join(', ');
+    return [
+        `### Tag Vocabulary (${tagFreq.size} tags)`,
+        allTags,
+        ``,
+        `Filter by tags: memory_query(filter: "#auth") — exact match`,
+        `Combine: memory_query(filter: "#auth middleware") — tag + keyword`,
+        `Multiple: memory_query(filter: "#auth|#security") — OR logic`,
+    ].join('\n');
+}