@exaudeus/memory-mcp 1.0.1 → 1.2.0

package/dist/ephemeral.js

@@ -228,11 +228,66 @@ const SIGNALS = [
                 /\b(doesn'?t|don'?t) (handle|support|implement).*\byet\b/,
                 /\bis (underway|not finished|not complete)\b/,
                 /\bblocked on\b/,
+                // Work-remaining section markers (colon required to avoid matching prose)
+                /\bremaining\s*:/, /\bopen items?\s*:/, /\bstill to do\s*:/,
+                /\bpending (tasks?|items?|work)\s*:/,
             ];
             const m = firstMatch(content, patterns);
             return m ? `contains "${m[0]}" — task tracking doesn't belong in long-term memory` : undefined;
         },
     },
+    // ── Completed task / work summary ──────────────────────────────────────
+    // Catches session work summaries stored as permanent knowledge.
+    // "Documentation updates complete", "Completed the migration", "All X validated".
+    {
+        id: 'completed-task',
+        label: 'Completed task announcement',
+        confidence: 'high',
+        test: (title, content) => {
+            const titlePatterns = [
+                // "Documentation updates complete", "migration done", "task finished"
+                /\b(update|migration|refactor|implementation|task|feature|docs?|documentation|sync|work|changes?|setup)\s+(complete[d]?|done|finished?)\b/,
+                // "Complete: X" or "Done - X" as a status prefix in the title
+                /^(complete[d]?|done|finished?)\s*[-–—:]/,
+            ];
+            const contentPatterns = [
+                // Content that opens with a completion verb — strongest signal
+                /^completed?\s+\w/,
+                // "Successfully completed/deployed/merged/migrated..."
+                /\bsuccessfully\s+(completed?|deployed?|merged?|migrated?|updated?|implemented?|refactored?)\b/,
+                // "All cross-references validated", "All tests done"
+                // [\w-] (no \s) restricts to single-word or hyphenated nouns, preventing
+                // "Every code fix is validated" (a durable policy) from matching
+                /\b(all|every)\s+\S[\w-]{0,25}\s+(validated?|complete[d]?|verified?|done)\b/,
+                // "has been completed/finished/merged/deployed"
+                /\b(has|have)\s+been\s+(completed?|finished?|merged?|deployed?)\b/,
+            ];
+            const tm = firstMatch(title, titlePatterns);
+            if (tm)
+                return `title contains "${tm[0]}" — task completion announcements aren't durable knowledge`;
+            const cm = firstMatch(content, contentPatterns);
+            return cm ? `contains "${cm[0]}" — task completion announcements aren't durable knowledge` : undefined;
+        },
+    },
+    // ── Diff stats / work metrics ──────────────────────────────────────────
+    // Quantitative work summaries ("14 docs modified", "508 additions, 173 deletions")
+    // never appear in durable knowledge — they're always session activity reports.
+    {
+        id: 'diff-stats',
+        label: 'Diff stats or work metrics',
+        confidence: 'high',
+        test: (_title, _content, raw) => {
+            const content = raw.content.toLowerCase();
+            const patterns = [
+                // Git-style: "(508 additions, 173 deletions)" or "508 additions, 173 deletions"
+                /\b\d+\s+additions?,\s*\d+\s+deletions?\b/,
+                // Work quantity: "14 docs modified", "5 files changed"
+                /\b\d+\s+(docs?|files?|tests?|endpoints?|functions?|modules?|classes?|pages?)\s+(modified|changed|updated|added|created|deleted)\b/,
+            ];
+            const m = firstMatch(content, patterns);
+            return m ? `"${m[0]}" — quantitative work metrics are session activity, not lasting knowledge` : undefined;
+        },
+    },
     // ── Stack traces / debug logs ──────────────────────────────────────────
     {
         id: 'stack-trace',
@@ -386,6 +441,27 @@ const SIGNALS = [
             return m ? `"${m[0]}" — store the decision or fact, not the meeting reference` : undefined;
         },
     },
+    // ── Shipped / released / merged ────────────────────────────────────────
+    // Positive deployment/release language not already caught by temporal.
+    // ("just deployed" is caught by temporal; this catches statements without "just".)
+    {
+        id: 'shipped',
+        label: 'Deployed, released, or merged',
+        confidence: 'medium',
+        test: (_title, content) => {
+            const patterns = [
+                // "was/got/has been deployed to production/staging/main" — past-tense anchor prevents
+                // firing on policy conventions like "is deployed to production before release"
+                /\b(?:was|were|got|has been)\s+deployed?\s+(?:to|into)\s+(production|prod|staging|main|master)\b/,
+                // "was/got/has been merged into main/master/develop/trunk"
+                /\b(?:was|were|got|has been)\s+merged?\s+(?:to|into)\s+(main|master|develop|trunk)\b/,
+                // "released to production" or "released as v1.2" or "released as version 1.2"
+                /\breleased?\s+(?:to\s+(?:production|prod)|(?:as\s+)?(?:version\s+)?v?\d+\.\d+)\b/,
+            ];
+            const m = firstMatch(content, patterns);
+            return m ? `"${m[0]}" — deployment/release events are ephemeral; store the resulting behavior instead` : undefined;
+        },
+    },
     // ── Pending decision / under evaluation ─────────────────────────────────
     {
         id: 'pending-decision',
@@ -435,6 +511,30 @@ const SIGNALS = [
             return m ? `"${m[0]}" — metric changes are often transient observations` : undefined;
         },
     },
+    // ── Bundling conjunctions ──────────────────────────────────────────────
+    // Catches agents that put multiple unrelated facts in a single entry using
+    // explicit linking language. Only fires on sentence-boundary connectors
+    // (comma or start of new sentence) to avoid false positives on prose like
+    // "X and Y work together" or "also useful for Z".
+    {
+        id: 'bundling-conjunction',
+        label: 'Multiple facts bundled',
+        confidence: 'low',
+        test: (_title, content) => {
+            const patterns = [
+                /[,;]\s+also\b/i, // "X works this way, also Y does Z"
+                /[.!?]\s+additionally,/i, // ". Additionally, ..."
+                /[.!?]\s+furthermore,/i, // ". Furthermore, ..."
+                /\bunrelated:/i, // "Unrelated: ..."
+                /\bseparately:/i, // "Separately: ..."
+                /[.!?]\s+on a (separate|different|unrelated) note[,:]?/i,
+            ];
+            const m = firstMatch(content, patterns);
+            return m
+                ? `"${m[0]}" — consider splitting into separate entries (one insight per entry)`
+                : undefined;
+        },
+    },
     // ── Very short content ─────────────────────────────────────────────────
     {
         id: 'too-short',
@@ -502,15 +602,17 @@ export function formatEphemeralWarning(signals) {
         '',
     ];
     // Scale the guidance with confidence — high-confidence gets direct advice,
-    // low-confidence gets a softer suggestion to let the agent decide
+    // low-confidence gets a softer suggestion to let the agent decide.
+    // Always include the positive redirect: store state, not events.
     if (highCount >= 2) {
         lines.push('This is almost certainly session-specific. Consider deleting after your session.');
+        lines.push('If there is a lasting insight here, rephrase it as a present-tense fact: what is now true about the codebase?');
     }
     else if (highCount === 1) {
-        lines.push('If this is a lasting insight, keep it. If session-specific, consider deleting after your session.');
+        lines.push('If this is a lasting insight, rephrase it as a present-tense fact (what is now true) rather than an action report (what you did). If session-specific, consider deleting after your session.');
     }
     else {
-        lines.push('This might still be valid long-term knowledge — use your judgment.');
+        lines.push('If this is durable knowledge, rephrase as a present-tense fact: what is now true? If it describes what you did rather than what is, consider deleting after your session.');
     }
     return lines.join('\n');
 }

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');
+}

package/dist/index.js

@@ -16,9 +16,9 @@ import { getLobeConfigs } from './config.js';
 import { ConfigManager } from './config-manager.js';
 import { normalizeArgs } from './normalize.js';
 import { buildCrashReport, writeCrashReport, writeCrashReportSync, readLatestCrash, readCrashHistory, clearLatestCrash, formatCrashReport, formatCrashSummary, markServerStarted, } from './crash-journal.js';
-import { formatStaleSection, formatConflictWarning, formatStats, formatBehaviorConfigSection } from './formatters.js';
-import { extractKeywords } from './text-analyzer.js';
-import { CROSS_LOBE_WEAK_SCORE_PENALTY, CROSS_LOBE_MIN_MATCH_RATIO } from './thresholds.js';
+import { formatStaleSection, formatConflictWarning, formatStats, formatBehaviorConfigSection, mergeTagFrequencies, buildQueryFooter, buildTagPrimerSection } from './formatters.js';
+import { extractKeywords, parseFilter } from './text-analyzer.js';
+import { CROSS_LOBE_WEAK_SCORE_PENALTY, CROSS_LOBE_MIN_MATCH_RATIO, VOCABULARY_ECHO_LIMIT } from './thresholds.js';
 let serverMode = { kind: 'running' };
 const lobeHealth = new Map();
 const serverStartTime = Date.now();
@@ -183,7 +183,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             // and memory_stats. The handler still works if called directly.
             {
                 name: 'memory_store',
-                description: 'Store knowledge. "user" and "preferences" are global (no lobe needed). Example: memory_store(topic: "gotchas", title: "Build cache", content: "Must clean build after Tuist changes")',
+                // Example comes first — agents form their call shape from the first concrete pattern they see.
+                // "entries" (not "content") signals a collection; fighting the "content = string" prior
+                // is an architectural fix rather than patching the description after the fact.
+                description: 'memory_store(topic: "gotchas", entries: [{title: "Build cache", fact: "Must clean build after Tuist changes"}, {title: "Tuist version", fact: "Project requires Tuist 4.x"}], tags: ["build"]). Stores enduring knowledge — (1) Codebase facts (architecture, conventions, gotchas, modules): what IS true now, not past actions. Wrong: "Completed migration to StateFlow." Right: "All ViewModels use StateFlow." (2) User knowledge (user, preferences): who the person is, how they work. "user" and "preferences" are global. One insight per object; use multiple objects instead of bundling.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -196,13 +199,25 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             description: 'Predefined: user | preferences | architecture | conventions | gotchas | recent-work. Custom namespace: modules/<name> (e.g. modules/brainstorm, modules/game-design, modules/api-notes). Use modules/<name> for any domain that doesn\'t fit the built-in topics.',
                             enum: ['user', 'preferences', 'architecture', 'conventions', 'gotchas', 'recent-work'],
                         },
-                        title: {
-                            type: 'string',
-                            description: 'Short title for this entry',
-                        },
-                        content: {
-                            type: 'string',
-                            description: 'The knowledge to store',
+                        entries: {
+                            type: 'array',
+                            // Type annotation first — agents trained on code read type signatures before prose.
+                            description: 'Array<{title: string, fact: string}> — not a string. One object per insight. title: short label (2-5 words). fact: codebase topics → present-tense state ("X uses Y", not "Completed X"); user/preferences → what the person expressed. Wrong: one object bundling two facts. Right: two objects.',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    title: {
+                                        type: 'string',
+                                        description: 'Short label for this insight (2-5 words)',
+                                    },
+                                    fact: {
+                                        type: 'string',
+                                        description: 'The insight itself — one focused fact or observation',
+                                    },
+                                },
+                                required: ['title', 'fact'],
+                            },
+                            minItems: 1,
                         },
                         sources: {
                             type: 'array',
@@ -222,13 +237,19 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             description: 'user (from human) > agent-confirmed > agent-inferred',
                             default: 'agent-inferred',
                         },
+                        tags: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'Category labels for exact-match retrieval (lowercase slugs). Query with filter: "#tag". Example: ["auth", "critical-path", "mite-combat"]',
+                            default: [],
+                        },
                     },
-                    required: ['topic', 'title', 'content'],
+                    required: ['topic', 'entries'],
                 },
             },
             {
                 name: 'memory_query',
-                description: 'Search stored knowledge. Searches all lobes when lobe is omitted. Example: memory_query(scope: "*", filter: "reducer sealed", detail: "full"). Use scope "*" to search everything. Use detail "full" for complete content.',
+                description: 'Search stored knowledge. Searches all lobes when lobe is omitted. Filter supports: keywords (stemmed), #tag (exact tag match), =term (exact keyword, no stemming), -term (NOT). Example: memory_query(scope: "*", filter: "#auth reducer", detail: "full")',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -245,7 +266,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         },
                         filter: {
                             type: 'string',
-                            description: 'Search terms. "A B" = AND, "A|B" = OR, "-A" = NOT. Example: "reducer sealed -deprecated"',
+                            description: 'Search terms. "A B" = AND, "A|B" = OR, "-A" = NOT, "#tag" = exact tag, "=term" = exact keyword (no stemming). Example: "#auth reducer -deprecated"',
                         },
                         branch: {
                             type: 'string',
@@ -387,14 +408,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 };
             }
             case 'memory_store': {
-                const { lobe: rawLobe, topic: rawTopic, title, content, sources, references, trust: rawTrust } = z.object({
+                const { lobe: rawLobe, topic: rawTopic, entries: rawEntries, sources, references, trust: rawTrust, tags: rawTags } = z.object({
                     lobe: z.string().optional(),
                     topic: z.string(),
-                    title: z.string().min(1),
-                    content: z.string().min(1),
+                    // Accept a bare {title, fact} object in addition to the canonical array form.
+                    // Only objects are auto-wrapped — strings and other primitives still fail with
+                    // a type error, preserving the "validate at boundaries" invariant.
+                    entries: z.preprocess((val) => (val !== null && !Array.isArray(val) && typeof val === 'object' ? [val] : val), z.array(z.object({
+                        title: z.string().min(1),
+                        fact: z.string().min(1),
+                    })).min(1)),
                     sources: z.array(z.string()).default([]),
                     references: z.array(z.string()).default([]),
                     trust: z.enum(['user', 'agent-confirmed', 'agent-inferred']).default('agent-inferred'),
+                    tags: z.array(z.string()).default([]),
                 }).parse(args);
                 // Validate topic at boundary
                 const topic = parseTopicScope(rawTopic);
@@ -417,52 +444,83 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const ctx = resolveToolContext(effectiveLobe, { isGlobal });
                 if (!ctx.ok)
                     return contextError(ctx);
-                const result = await ctx.store.store(topic, title, content, sources, 
-                // User/preferences default to 'user' trust unless explicitly set otherwise
-                isGlobal && trust === 'agent-inferred' ? 'user' : trust, references);
-                if (!result.stored) {
-                    return {
-                        content: [{ type: 'text', text: `[${ctx.label}] Failed to store: ${result.warning}` }],
-                        isError: true,
-                    };
+                const effectiveTrust = isGlobal && trust === 'agent-inferred' ? 'user' : trust;
+                const storedResults = [];
+                for (const { title, fact } of rawEntries) {
+                    const result = await ctx.store.store(topic, title, fact, sources, effectiveTrust, references, rawTags);
+                    if (!result.stored) {
+                        return {
+                            content: [{ type: 'text', text: `[${ctx.label}] Failed to store "${title}": ${result.warning}` }],
+                            isError: true,
+                        };
+                    }
+                    storedResults.push({ title, result });
+                }
+                // Build response header
+                const lines = [];
+                if (storedResults.length === 1) {
+                    const { result } = storedResults[0];
+                    lines.push(`[${ctx.label}] Stored entry ${result.id} in ${result.topic} (confidence: ${result.confidence})`);
+                    if (result.warning)
+                        lines.push(`Note: ${result.warning}`);
+                }
+                else {
+                    const { result: first } = storedResults[0];
+                    lines.push(`[${ctx.label}] Stored ${storedResults.length} entries in ${first.topic} (confidence: ${first.confidence}):`);
+                    for (const { title, result } of storedResults) {
+                        lines.push(`  - ${result.id}: "${title}"`);
+                    }
                 }
-                const lines = [
-                    `[${ctx.label}] Stored entry ${result.id} in ${result.topic} (confidence: ${result.confidence})`,
-                ];
-                if (result.warning)
-                    lines.push(`Note: ${result.warning}`);
                 // Limit to at most 2 hint sections per response to prevent hint fatigue.
                 // Priority: dedup > ephemeral > preferences (dedup is actionable and high-signal,
                 // ephemeral warnings affect entry quality, preferences are informational).
+                // For multi-entry batches, hints reference the first triggering entry.
                 let hintCount = 0;
-                // Dedup: surface related entries in the same topic
-                if (result.relatedEntries && result.relatedEntries.length > 0 && hintCount < 2) {
-                    hintCount++;
-                    lines.push('');
-                    lines.push('⚠ Similar entries found in the same topic:');
-                    for (const r of result.relatedEntries) {
-                        lines.push(`  - ${r.id}: "${r.title}" (confidence: ${r.confidence})`);
-                        lines.push(`    Content: ${r.content.length > 120 ? r.content.substring(0, 120) + '...' : r.content}`);
+                for (const { title, result } of storedResults) {
+                    const entryPrefix = storedResults.length > 1 ? `"${title}": ` : '';
+                    // Dedup: surface related entries in the same topic
+                    if (result.relatedEntries && result.relatedEntries.length > 0 && hintCount < 2) {
+                        hintCount++;
+                        lines.push('');
+                        lines.push(`⚠ ${entryPrefix}Similar entries found in the same topic:`);
+                        for (const r of result.relatedEntries) {
+                            lines.push(`  - ${r.id}: "${r.title}" (confidence: ${r.confidence})`);
+                            lines.push(`    Content: ${r.content.length > 120 ? r.content.substring(0, 120) + '...' : r.content}`);
+                        }
+                        lines.push('');
+                        lines.push('To consolidate: memory_correct(id: "<old-id>", action: "replace", correction: "<merged content>") then memory_correct(id: "<new-id>", action: "delete")');
+                    }
+                    // Ephemeral content warning — soft nudge, never blocking
+                    if (result.ephemeralWarning && hintCount < 2) {
+                        hintCount++;
+                        lines.push('');
+                        lines.push(`⏳ ${entryPrefix}${result.ephemeralWarning}`);
+                    }
+                    // Preference surfacing: show relevant preferences for non-preference entries
+                    if (result.relevantPreferences && result.relevantPreferences.length > 0 && hintCount < 2) {
+                        hintCount++;
+                        lines.push('');
+                        lines.push(`📌 ${entryPrefix}Relevant preferences:`);
+                        for (const p of result.relevantPreferences) {
+                            lines.push(`  - [pref] ${p.title}: ${p.content.length > 120 ? p.content.substring(0, 120) + '...' : p.content}`);
+                        }
+                        lines.push('');
+                        lines.push('Review the stored entry against these preferences for potential conflicts.');
                     }
-                    lines.push('');
-                    lines.push('To consolidate: memory_correct(id: "<old-id>", action: "replace", correction: "<merged content>") then memory_correct(id: "<new-id>", action: "delete")');
-                }
-                // Ephemeral content warning — soft nudge, never blocking
-                if (result.ephemeralWarning && hintCount < 2) {
-                    hintCount++;
-                    lines.push('');
-                    lines.push(`⏳ ${result.ephemeralWarning}`);
                 }
-                // Preference surfacing: show relevant preferences for non-preference entries
-                if (result.relevantPreferences && result.relevantPreferences.length > 0 && hintCount < 2) {
-                    hintCount++;
-                    lines.push('');
-                    lines.push('📌 Relevant preferences:');
-                    for (const p of result.relevantPreferences) {
-                        lines.push(`  - [pref] ${p.title}: ${p.content.length > 120 ? p.content.substring(0, 120) + '...' : p.content}`);
+                // Vocabulary echo: show existing tags to drive convergence (once per response)
+                if (hintCount < 2) {
+                    const tagFreq = ctx.store.getTagFrequency();
+                    if (tagFreq.size > 0) {
+                        hintCount++;
+                        const topTags = [...tagFreq.entries()]
+                            .sort((a, b) => b[1] - a[1])
+                            .slice(0, VOCABULARY_ECHO_LIMIT)
+                            .map(([tag, count]) => `${tag}(${count})`).join(', ');
+                        const truncated = tagFreq.size > VOCABULARY_ECHO_LIMIT ? ` (top ${VOCABULARY_ECHO_LIMIT} shown)` : '';
+                        lines.push('');
+                        lines.push(`Existing tags: ${topTags}${truncated}. Reuse for consistency. Query with filter: "#tag".`);
                     }
-                    lines.push('');
-                    lines.push('Review the stored entry against these preferences for potential conflicts.');
                 }
                 return { content: [{ type: 'text', text: lines.join('\n') }] };
             }
@@ -537,14 +595,35 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     return true;
                 })
                     .sort((a, b) => b.relevanceScore - a.relevanceScore);
+                // Build stores collection for tag frequency aggregation
+                const searchedStores = [];
+                if (isGlobalQuery) {
+                    searchedStores.push(globalStore);
+                }
+                else if (rawLobe) {
+                    const store = configManager.getStore(rawLobe);
+                    if (store)
+                        searchedStores.push(store);
+                }
+                else {
+                    // All lobes + global when doing wildcard search
+                    for (const lobeName of configManager.getLobeNames()) {
+                        const store = configManager.getStore(lobeName);
+                        if (store)
+                            searchedStores.push(store);
+                    }
+                    if (scope === '*')
+                        searchedStores.push(globalStore);
+                }
+                const tagFreq = mergeTagFrequencies(searchedStores);
+                // Parse filter once for both filtering (already done) and footer display
+                const filterGroups = filter ? parseFilter(filter) : [];
                 if (allEntries.length === 0) {
-                    const scopeHint = scope !== '*'
-                        ? ` Try scope: "*" to search all topics, or use filter: "${filter ?? scope}" to search by keyword.`
-                        : '';
+                    const footer = buildQueryFooter({ filterGroups, rawFilter: filter, tagFreq, resultCount: 0, scope });
                     return {
                         content: [{
                                 type: 'text',
-                                text: `[${label}] No entries found for scope "${scope}"${filter ? ` with filter "${filter}"` : ''}.${scopeHint}`,
+                                text: `[${label}] No entries found for scope "${scope}"${filter ? ` with filter "${filter}"` : ''}.\n\n---\n${footer}`,
                             }],
                     };
                 }
@@ -563,14 +642,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             `Fresh: ${e.fresh}`,
                             e.sources?.length ? `Sources: ${e.sources.join(', ')}` : null,
                             e.references?.length ? `References: ${e.references.join(', ')}` : null,
+                            e.tags?.length ? `Tags: ${e.tags.join(', ')}` : null,
                             `Created: ${e.created}`,
                             `Last accessed: ${e.lastAccessed}`,
                             e.gitSha ? `Git SHA: ${e.gitSha}` : null,
                         ].filter(Boolean).join('\n');
                         return `### ${e.title}\n${meta}\n\n${e.content}`;
                     }
-                    if (detail === 'standard' && e.references?.length) {
-                        return `### ${e.title}\n*${e.id}${lobeTag} | confidence: ${e.confidence}${freshIndicator}*\nReferences: ${e.references.join(', ')}\n\n${e.summary}`;
+                    if (detail === 'standard') {
+                        const metaParts = [];
+                        if (e.references?.length)
+                            metaParts.push(`References: ${e.references.join(', ')}`);
+                        if (e.tags?.length)
+                            metaParts.push(`Tags: ${e.tags.join(', ')}`);
+                        const metaLine = metaParts.length > 0 ? `\n${metaParts.join('\n')}\n` : '\n';
+                        return `### ${e.title}\n*${e.id}${lobeTag} | confidence: ${e.confidence}${freshIndicator}*${metaLine}\n${e.summary}`;
                     }
                     return `### ${e.title}\n*${e.id}${lobeTag} | confidence: ${e.confidence}${freshIndicator}*\n\n${e.summary}`;
                 });
@@ -584,25 +670,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         text += '\n\n' + formatConflictWarning(conflicts);
                     }
                 }
-                // Hints: teach the agent about capabilities it may not know about
-                const hints = [];
-                // Nudge: when searching all lobes, remind the agent to specify one for targeted results
-                const allQueryLobeNames = configManager.getLobeNames();
-                if (!rawLobe && !isGlobalQuery && allQueryLobeNames.length > 1) {
-                    hints.push(`Searched all lobes (${allQueryLobeNames.join(', ')}). Specify lobe: "<name>" for targeted results.`);
-                }
-                if (detail !== 'full') {
-                    hints.push('Use detail: "full" to see complete entry content.');
-                }
-                if (filter && !filter.includes(' ') && !filter.includes('|') && !filter.includes('-')) {
-                    hints.push('Tip: combine terms with spaces (AND), | (OR), -term (NOT). Example: "reducer sealed -deprecated"');
-                }
-                if (!filter) {
-                    hints.push('Tip: add filter: "keyword" to search within results.');
-                }
-                if (hints.length > 0) {
-                    text += `\n\n---\n*${hints.join(' ')}*`;
-                }
+                // Build footer with query mode, tag vocabulary, and syntax reference
+                const footer = buildQueryFooter({ filterGroups, rawFilter: filter, tagFreq, resultCount: allEntries.length, scope });
+                text += `\n\n---\n${footer}`;
                 return { content: [{ type: 'text', text }] };
             }
             case 'memory_correct': {
@@ -723,6 +793,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     if (sections.length === 0) {
                         sections.push('No knowledge stored yet. As you work, store observations with memory_store. Try memory_bootstrap to seed initial knowledge from the repo.');
                     }
+                    // Tag primer: show tag vocabulary if tags exist across any lobe
+                    const briefingStores = [globalStore];
+                    for (const lobeName of allBriefingLobeNames) {
+                        const store = configManager.getStore(lobeName);
+                        if (store)
+                            briefingStores.push(store);
+                    }
+                    const briefingTagFreq = mergeTagFrequencies(briefingStores);
+                    const tagPrimer = buildTagPrimerSection(briefingTagFreq);
+                    if (tagPrimer) {
+                        sections.push(tagPrimer);
+                    }
                     const briefingHints = [];
                     briefingHints.push(`${totalEntries} entries${totalStale > 0 ? ` (${totalStale} stale)` : ''} across ${allBriefingLobeNames.length} ${allBriefingLobeNames.length === 1 ? 'lobe' : 'lobes'}.`);
                     briefingHints.push('Use memory_context(context: "what you are about to do") for task-specific knowledge.');
@@ -797,11 +879,29 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     return true;
                 })
                     .slice(0, max);
+                // Build stores collection for tag frequency aggregation
+                const ctxSearchedStores = [globalStore];
+                if (rawLobe) {
+                    const store = configManager.getStore(rawLobe);
+                    if (store)
+                        ctxSearchedStores.push(store);
+                }
+                else {
+                    for (const lobeName of configManager.getLobeNames()) {
+                        const store = configManager.getStore(lobeName);
+                        if (store)
+                            ctxSearchedStores.push(store);
+                    }
+                }
+                const ctxTagFreq = mergeTagFrequencies(ctxSearchedStores);
+                // Parse filter for footer (context search has no filter, pass empty)
+                const ctxFilterGroups = [];
                 if (results.length === 0) {
+                    const ctxFooter = buildQueryFooter({ filterGroups: ctxFilterGroups, rawFilter: undefined, tagFreq: ctxTagFreq, resultCount: 0, scope: 'context search' });
                     return {
                         content: [{
                                 type: 'text',
-                                text: `[${label}] No relevant knowledge found for: "${context}"\n\nThis is fine — proceed without prior context. As you learn things worth remembering, store them with memory_store.\nTry memory_query(scope: "*") to browse all entries.`,
+                                text: `[${label}] No relevant knowledge found for: "${context}"\n\nThis is fine — proceed without prior context. As you learn things worth remembering, store them with memory_store.\n\n---\n${ctxFooter}`,
                             }],
                     };
                 }
@@ -831,7 +931,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         const marker = topic === 'gotchas' ? '[!] ' : topic === 'preferences' ? '[pref] ' : '';
                         const keywords = r.matchedKeywords.length > 0 ? ` (matched: ${r.matchedKeywords.join(', ')})` : '';
                         const lobeLabel = isCtxMultiLobe ? ` [${ctxEntryLobeMap.get(r.entry.id) ?? '?'}]` : '';
-                        sections.push(`- **${marker}${r.entry.title}**${lobeLabel}: ${r.entry.content}${keywords}`);
+                        const tagsSuffix = r.entry.tags?.length ? ` [tags: ${r.entry.tags.join(', ')}]` : '';
+                        sections.push(`- **${marker}${r.entry.title}**${lobeLabel}: ${r.entry.content}${keywords}${tagsSuffix}`);
                     }
                     sections.push('');
                 }
@@ -850,33 +951,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         allMatchedKeywords.add(kw);
                     matchedTopics.add(r.entry.topic);
                 }
-                // Hints
-                const ctxHints = [];
-                // Nudge: when searching all lobes, infer the most relevant lobe from context keywords
-                // matching lobe names (e.g. "minion-miner" in context → suggest lobe "minion-miner"),
-                // falling back to the first lobe when no name overlap is found.
-                const allCtxLobeNames = configManager.getLobeNames();
-                if (!rawLobe && allCtxLobeNames.length > 1) {
-                    const contextKws = extractKeywords(context);
-                    const inferredLobe = allCtxLobeNames.find(name => [...extractKeywords(name)].some(kw => contextKws.has(kw))) ?? allCtxLobeNames[0];
-                    ctxHints.push(`Searched all lobes. For faster, targeted results use lobe: "${inferredLobe}" (available: ${allCtxLobeNames.join(', ')}).`);
-                }
-                if (results.length >= max) {
-                    ctxHints.push(`Showing top ${max} results. Increase maxResults or raise minMatch to refine.`);
-                }
-                if (threshold <= 0.2 && results.length > 5) {
-                    ctxHints.push('Too many results? Use minMatch: 0.4 for stricter matching.');
-                }
-                // Session dedup hint — tell the agent not to re-call for these keywords
                 if (allMatchedKeywords.size > 0) {
                     const kwList = Array.from(allMatchedKeywords).sort().join(', ');
                     const topicList = Array.from(matchedTopics).sort().join(', ');
-                    ctxHints.push(`Context loaded for: ${kwList} (${topicList}). ` +
-                        `This knowledge is now in your conversation — no need to call memory_context again for these terms this session.`);
-                }
-                if (ctxHints.length > 0) {
-                    sections.push(`---\n*${ctxHints.join(' ')}*`);
+                    sections.push(`---\n*Context loaded for: ${kwList} (${topicList}). ` +
+                        `This knowledge is now in your conversation — no need to call memory_context again for these terms this session.*`);
                 }
+                // Build footer (context search has no filter — it's natural language keyword matching)
+                const ctxFooter = buildQueryFooter({ filterGroups: ctxFilterGroups, rawFilter: undefined, tagFreq: ctxTagFreq, resultCount: results.length, scope: 'context search' });
+                sections.push(`---\n${ctxFooter}`);
                 return { content: [{ type: 'text', text: sections.join('\n') }] };
             }
             case 'memory_stats': {
@@ -986,8 +1069,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const lobeNames = configManager.getLobeNames();
             hint = `\n\nHint: lobe is required. Use memory_list_lobes to see available lobes. Available: ${lobeNames.join(', ')}`;
         }
-        else if (message.includes('"topic"') || message.includes('"title"') || message.includes('"content"')) {
-            hint = '\n\nHint: memory_store requires: topic (architecture|conventions|gotchas|recent-work|modules/<name>), title, content. Use modules/<name> for custom namespaces (e.g. modules/brainstorm, modules/game-design).';
+        else if (message.includes('"topic"') || message.includes('"entries"')) {
+            hint = '\n\nHint: memory_store requires: topic (architecture|conventions|gotchas|recent-work|modules/<name>) and entries (Array<{title, fact}>). Example: entries: [{title: "Build cache", fact: "Must clean build after Tuist changes"}]. Use modules/<name> for custom namespaces.';
         }
         else if (message.includes('"scope"')) {
             hint = '\n\nHint: memory_query requires: lobe, scope (architecture|conventions|gotchas|recent-work|modules/<name>|* for all)';

package/dist/normalize.js

@@ -6,11 +6,6 @@
 /** Canonical param name aliases — maps guessed names to their correct form */
 const PARAM_ALIASES = {
     // memory_store aliases
-    key: 'title',
-    name: 'title',
-    value: 'content',
-    body: 'content',
-    text: 'content',
     refs: 'references',
     // memory_query aliases
     query: 'filter',
@@ -19,6 +14,10 @@ const PARAM_ALIASES = {
     // memory_context aliases
     description: 'context',
     task: 'context',
+    // tag aliases
+    tag: 'tags',
+    labels: 'tags',
+    categories: 'tags',
     // lobe aliases
     workspace: 'lobe',
     repo: 'lobe',

package/dist/store.d.ts

@@ -13,7 +13,7 @@ export declare class MarkdownMemoryStore {
     /** Initialize the store: create memory dir and load existing entries */
     init(): Promise<void>;
     /** Store a new knowledge entry */
-    store(topic: TopicScope, title: string, content: string, sources?: string[], trust?: TrustLevel, references?: string[]): Promise<StoreResult>;
+    store(topic: TopicScope, title: string, content: string, sources?: string[], trust?: TrustLevel, references?: string[], rawTags?: string[]): Promise<StoreResult>;
     /** Query knowledge by scope and detail level */
     query(scope: string, detail?: DetailLevel, filter?: string, branchFilter?: string): Promise<QueryResult>;
     /** Generate a session-start briefing */
@@ -68,6 +68,9 @@ export declare class MarkdownMemoryStore {
     /** Find entries in the same topic with significant overlap (dedup detection).
      *  Uses hybrid jaccard+containment similarity. */
     private findRelatedEntries;
+    /** Tag frequency across all entries — for vocabulary echo in store responses.
+     *  Returns tags sorted by frequency (descending). O(N) over entries. */
+    getTagFrequency(): ReadonlyMap<string, number>;
     /** Fetch raw MemoryEntry objects by ID for conflict detection.
      *  Must be called after query() (which calls reloadFromDisk) to ensure entries are current. */
     getEntriesByIds(ids: readonly string[]): MemoryEntry[];

package/dist/store.js

@@ -6,8 +6,8 @@ import path from 'path';
 import crypto from 'crypto';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
-import { DEFAULT_CONFIDENCE, realClock, parseTopicScope, parseTrustLevel } from './types.js';
-import { DEDUP_SIMILARITY_THRESHOLD, CONFLICT_SIMILARITY_THRESHOLD_SAME_TOPIC, CONFLICT_SIMILARITY_THRESHOLD_CROSS_TOPIC, CONFLICT_MIN_CONTENT_CHARS, OPPOSITION_PAIRS, PREFERENCE_SURFACE_THRESHOLD, REFERENCE_BOOST_MULTIPLIER, TOPIC_BOOST, MODULE_TOPIC_BOOST, USER_ALWAYS_INCLUDE_SCORE_FRACTION, DEFAULT_STALE_DAYS_STANDARD, DEFAULT_STALE_DAYS_PREFERENCES, DEFAULT_MAX_STALE_IN_BRIEFING, DEFAULT_MAX_DEDUP_SUGGESTIONS, DEFAULT_MAX_CONFLICT_PAIRS, DEFAULT_MAX_PREFERENCE_SUGGESTIONS, } from './thresholds.js';
+import { DEFAULT_CONFIDENCE, realClock, parseTopicScope, parseTrustLevel, parseTags } from './types.js';
+import { DEDUP_SIMILARITY_THRESHOLD, CONFLICT_SIMILARITY_THRESHOLD_SAME_TOPIC, CONFLICT_SIMILARITY_THRESHOLD_CROSS_TOPIC, CONFLICT_MIN_CONTENT_CHARS, OPPOSITION_PAIRS, PREFERENCE_SURFACE_THRESHOLD, REFERENCE_BOOST_MULTIPLIER, TOPIC_BOOST, MODULE_TOPIC_BOOST, USER_ALWAYS_INCLUDE_SCORE_FRACTION, DEFAULT_STALE_DAYS_STANDARD, DEFAULT_STALE_DAYS_PREFERENCES, DEFAULT_MAX_STALE_IN_BRIEFING, DEFAULT_MAX_DEDUP_SUGGESTIONS, DEFAULT_MAX_CONFLICT_PAIRS, DEFAULT_MAX_PREFERENCE_SUGGESTIONS, TAG_MATCH_BOOST, } from './thresholds.js';
 import { realGitService } from './git-service.js';
 import { extractKeywords, stem, similarity, matchesFilter, computeRelevanceScore, } from './text-analyzer.js';
 import { detectEphemeralSignals, formatEphemeralWarning } from './ephemeral.js';
@@ -41,7 +41,7 @@ export class MarkdownMemoryStore {
         await this.reloadFromDisk();
     }
     /** Store a new knowledge entry */
-    async store(topic, title, content, sources = [], trust = 'agent-inferred', references = []) {
+    async store(topic, title, content, sources = [], trust = 'agent-inferred', references = [], rawTags = []) {
         // Check storage budget — null means we can't measure, allow the write
         const currentSize = await this.getStorageSize();
         if (currentSize !== null && currentSize >= this.config.storageBudgetBytes) {
@@ -56,10 +56,13 @@ export class MarkdownMemoryStore {
         const gitSha = await this.getGitSha(sources);
         // Auto-detect branch for recent-work entries
         const branch = topic === 'recent-work' ? await this.getCurrentBranch() : undefined;
+        // Validate tags at boundary — invalid ones silently dropped
+        const tags = parseTags(rawTags);
         const entry = {
             id, topic, title, content, confidence, trust,
             sources,
             references: references.length > 0 ? references : undefined,
+            tags: tags.length > 0 ? tags : undefined,
             created: now, lastAccessed: now, gitSha, branch,
         };
         // Check for existing entry with same title in same topic (and same branch for recent-work)
@@ -113,12 +116,12 @@ export class MarkdownMemoryStore {
                     return false;
                 }
             }
-            // Optional keyword filter with AND/OR/NOT syntax
+            // Optional keyword filter with AND/OR/NOT syntax + #tag and =exact support
             if (filter) {
                 const titleKeywords = extractKeywords(entry.title);
                 const contentKeywords = extractKeywords(entry.content);
                 const allKeywords = new Set([...titleKeywords, ...contentKeywords]);
-                return matchesFilter(allKeywords, filter);
+                return matchesFilter(allKeywords, filter, entry.tags);
             }
             return true;
         });
@@ -126,7 +129,7 @@ export class MarkdownMemoryStore {
         if (filter) {
             const scores = new Map();
             for (const entry of matching) {
-                scores.set(entry.id, computeRelevanceScore(extractKeywords(entry.title), extractKeywords(entry.content), entry.confidence, filter));
+                scores.set(entry.id, computeRelevanceScore(extractKeywords(entry.title), extractKeywords(entry.content), entry.confidence, filter, entry.tags));
             }
             matching.sort((a, b) => {
                 const scoreDiff = (scores.get(b.id) ?? 0) - (scores.get(a.id) ?? 0);
@@ -155,7 +158,7 @@ export class MarkdownMemoryStore {
         const entries = matching.map(entry => ({
             ...this.formatEntry(entry, detail),
             relevanceScore: filter
-                ? computeRelevanceScore(extractKeywords(entry.title), extractKeywords(entry.content), entry.confidence, filter)
+                ? computeRelevanceScore(extractKeywords(entry.title), extractKeywords(entry.content), entry.confidence, filter, entry.tags)
                 : entry.confidence,
         }));
         return { scope, detail, entries, totalEntries: matching.length };
@@ -288,6 +291,7 @@ export class MarkdownMemoryStore {
         const byTopic = {};
         const byTrust = { 'user': 0, 'agent-confirmed': 0, 'agent-inferred': 0 };
         const byFreshness = { fresh: 0, stale: 0, unknown: 0 };
+        const byTag = {};
         for (const entry of allEntries) {
             byTopic[entry.topic] = (byTopic[entry.topic] ?? 0) + 1;
             byTrust[entry.trust]++;
@@ -300,12 +304,18 @@ export class MarkdownMemoryStore {
             else {
                 byFreshness.stale++;
             }
+            // Aggregate tag frequencies
+            if (entry.tags) {
+                for (const tag of entry.tags) {
+                    byTag[tag] = (byTag[tag] ?? 0) + 1;
+                }
+            }
         }
         const dates = allEntries.map(e => e.created).sort();
         return {
             totalEntries: allEntries.length,
             corruptFiles: this.corruptFileCount,
-            byTopic, byTrust, byFreshness,
+            byTopic, byTrust, byFreshness, byTag,
             storageSize: this.formatBytes(storageSize ?? 0),
             storageBudgetBytes: this.config.storageBudgetBytes,
             memoryPath: this.memoryPath,
@@ -399,7 +409,9 @@ export class MarkdownMemoryStore {
             if (entry.topic === 'recent-work' && branchFilter !== '*' && entry.branch && entry.branch !== currentBranch) {
                 continue;
             }
-            const entryKeywords = extractKeywords(`${entry.title} ${entry.content}`);
+            // Include tag values as keywords so tagged entries surface in context search
+            const tagKeywordPart = entry.tags ? ` ${entry.tags.join(' ')}` : '';
+            const entryKeywords = extractKeywords(`${entry.title} ${entry.content}${tagKeywordPart}`);
             const matchedKeywords = [];
             for (const kw of contextKeywords) {
                 if (entryKeywords.has(kw))
@@ -421,7 +433,10 @@ export class MarkdownMemoryStore {
                 const basename = ref.split('/').pop()?.replace(/\.\w+$/, '') ?? ref;
                 return contextKeywords.has(stem(basename.toLowerCase()));
             }) ? REFERENCE_BOOST_MULTIPLIER : 1.0;
-            const score = matchRatio * entry.confidence * boost * freshnessMultiplier * referenceBoost;
+            // Tag boost: if any tag exactly matches a context keyword, boost the entry
+            const tagBoost = entry.tags?.some(tag => contextKeywords.has(tag))
+                ? TAG_MATCH_BOOST : 1.0;
+            const score = matchRatio * entry.confidence * boost * freshnessMultiplier * referenceBoost * tagBoost;
             results.push({ entry, score, matchedKeywords });
         }
         // Always include user entries even if no keyword match (they're always relevant)
@@ -485,6 +500,9 @@ export class MarkdownMemoryStore {
         if (entry.references && entry.references.length > 0) {
             meta.push(`- **references**: ${entry.references.join(', ')}`);
         }
+        if (entry.tags && entry.tags.length > 0) {
+            meta.push(`- **tags**: ${entry.tags.join(', ')}`);
+        }
         if (entry.gitSha) {
             meta.push(`- **gitSha**: ${entry.gitSha}`);
         }
@@ -603,6 +621,10 @@ export class MarkdownMemoryStore {
         const references = metadata['references']
             ? metadata['references'].split(',').map(s => s.trim()).filter(s => s.length > 0)
             : undefined;
+        // Parse tags at boundary — invalid tags silently dropped
+        const tags = metadata['tags']
+            ? parseTags(metadata['tags'].split(','))
+            : undefined;
         return {
             id: metadata['id'],
             topic,
@@ -612,6 +634,7 @@ export class MarkdownMemoryStore {
             trust,
             sources: metadata['source'] ? metadata['source'].split(',').map(s => s.trim()) : [],
             references: references && references.length > 0 ? references : undefined,
+            tags: tags && tags.length > 0 ? tags : undefined,
             created: metadata['created'] ?? now,
             lastAccessed: metadata['lastAccessed'] ?? now,
             gitSha: metadata['gitSha'],
@@ -634,8 +657,9 @@ export class MarkdownMemoryStore {
         if (detail === 'standard') {
             return {
                 ...base,
-                // Surface references in standard detail — compact but useful for navigation
+                // Surface references and tags in standard detail
                 references: entry.references,
+                tags: entry.tags,
             };
         }
         if (detail === 'full') {
@@ -645,6 +669,7 @@ export class MarkdownMemoryStore {
                 trust: entry.trust,
                 sources: entry.sources,
                 references: entry.references,
+                tags: entry.tags,
                 created: entry.created,
                 lastAccessed: entry.lastAccessed,
                 gitSha: entry.gitSha,
@@ -737,6 +762,19 @@ export class MarkdownMemoryStore {
             trust: r.entry.trust,
         }));
     }
+    /** Tag frequency across all entries — for vocabulary echo in store responses.
+     *  Returns tags sorted by frequency (descending). O(N) over entries. */
+    getTagFrequency() {
+        const freq = new Map();
+        for (const entry of this.entries.values()) {
+            if (!entry.tags)
+                continue;
+            for (const tag of entry.tags) {
+                freq.set(tag, (freq.get(tag) ?? 0) + 1);
+            }
+        }
+        return freq;
+    }
     /** Fetch raw MemoryEntry objects by ID for conflict detection.
      *  Must be called after query() (which calls reloadFromDisk) to ensure entries are current. */
     getEntriesByIds(ids) {

package/dist/text-analyzer.d.ts

@@ -1,8 +1,29 @@
-/** Parsed filter group: a set of required terms and excluded terms */
+/** Parsed filter group: required, excluded, exact-match, and tag terms */
 export interface FilterGroup {
     readonly must: Set<string>;
     readonly mustNot: Set<string>;
+    readonly mustExact: Set<string>;
+    readonly mustTags: Set<string>;
 }
+/** Query mode summary — describes what a parsed filter actually searches */
+export type QueryMode = {
+    readonly kind: 'no-filter';
+} | {
+    readonly kind: 'keyword-only';
+    readonly terms: readonly string[];
+} | {
+    readonly kind: 'tag-only';
+    readonly tags: readonly string[];
+} | {
+    readonly kind: 'complex';
+    readonly hasTags: boolean;
+    readonly hasExact: boolean;
+    readonly hasNot: boolean;
+    readonly hasOr: boolean;
+};
+/** Analyze parsed filter groups into QueryMode for display — pure function.
+ *  Accepts already-parsed FilterGroup[] to avoid reparsing. */
+export declare function analyzeFilterGroups(groups: readonly FilterGroup[]): QueryMode;
 /** Naive stem: strip common English suffixes to improve keyword matching.
  *  "reducers" -> "reducer", "sealed" stays, "implementations" -> "implement" */
 export declare function stem(word: string): string;
@@ -25,8 +46,10 @@ export declare function similarity(titleA: string, contentA: string, titleB: str
  *  ] */
 export declare function parseFilter(filter: string): FilterGroup[];
 /** Check if a set of keywords matches a filter string using stemmed AND/OR/NOT logic.
- *  Entry matches if ANY OR-group is satisfied (all must-terms present, no mustNot-terms present). */
-export declare function matchesFilter(allKeywords: Set<string>, filter: string): boolean;
+ *  Entry matches if ANY OR-group is satisfied (all must-terms present, no mustNot-terms present).
+ *  Supports =exact (no stemming) and #tag (exact match against entry tags). */
+export declare function matchesFilter(allKeywords: Set<string>, filter: string, tags?: readonly string[]): boolean;
 /** Compute relevance score for an entry against a filter.
- *  Title matches get 2x weight over content-only matches. */
-export declare function computeRelevanceScore(titleKeywords: Set<string>, contentKeywords: Set<string>, confidence: number, filter: string): number;
+ *  Title matches get 2x weight over content-only matches.
+ *  Tag and exact matches count as full-weight hits (same as title). */
+export declare function computeRelevanceScore(titleKeywords: Set<string>, contentKeywords: Set<string>, confidence: number, filter: string, tags?: readonly string[]): number;

package/dist/text-analyzer.js

@@ -20,6 +20,42 @@ const STOPWORDS = new Set([
     'he', 'him', 'his', 'she', 'her', 'they', 'them', 'their', 'about',
     'up', 'out', 'then', 'also', 'use', 'used', 'using',
 ]);
+/** Analyze parsed filter groups into QueryMode for display — pure function.
+ *  Accepts already-parsed FilterGroup[] to avoid reparsing. */
+export function analyzeFilterGroups(groups) {
+    if (groups.length === 0)
+        return { kind: 'no-filter' };
+    // Aggregate all filter features across OR groups
+    const allMust = new Set();
+    const allMustNot = new Set();
+    const allMustExact = new Set();
+    const allMustTags = new Set();
+    for (const g of groups) {
+        for (const t of g.must)
+            allMust.add(t);
+        for (const t of g.mustNot)
+            allMustNot.add(t);
+        for (const t of g.mustExact)
+            allMustExact.add(t);
+        for (const t of g.mustTags)
+            allMustTags.add(t);
+    }
+    const hasTags = allMustTags.size > 0;
+    const hasExact = allMustExact.size > 0;
+    const hasNot = allMustNot.size > 0;
+    const hasOr = groups.length > 1;
+    const hasKeywords = allMust.size > 0;
+    // Pure tag-only (no other features)
+    if (hasTags && !hasExact && !hasNot && !hasOr && !hasKeywords) {
+        return { kind: 'tag-only', tags: [...allMustTags] };
+    }
+    // Pure keyword-only (no other features)
+    if (hasKeywords && !hasTags && !hasExact && !hasNot && !hasOr) {
+        return { kind: 'keyword-only', terms: [...allMust] };
+    }
+    // Everything else is complex (mixed features)
+    return { kind: 'complex', hasTags, hasExact, hasNot, hasOr };
+}
 /** Naive stem: strip common English suffixes to improve keyword matching.
  *  "reducers" -> "reducer", "sealed" stays, "implementations" -> "implement" */
 export function stem(word) {
@@ -126,6 +162,8 @@ export function parseFilter(filter) {
         const terms = group.split(/\s+/).filter(t => t.length > 0);
         const must = new Set();
         const mustNot = new Set();
+        const mustExact = new Set();
+        const mustTags = new Set();
         for (const term of terms) {
             if (term.startsWith('-') && term.length > 1) {
                 // Negation: stem the compound as-is, WITHOUT hyphen expansion.
@@ -135,6 +173,14 @@ export function parseFilter(filter) {
                 if (raw.length > 2)
                     mustNot.add(stem(raw));
             }
+            else if (term.startsWith('#') && term.length > 1) {
+                // Tag filter: exact match against entry tags, no stemming
+                mustTags.add(term.slice(1).toLowerCase());
+            }
+            else if (term.startsWith('=') && term.length > 1) {
+                // Exact keyword match: bypasses stemming
+                mustExact.add(term.slice(1).toLowerCase());
+            }
             else {
                 // Positive terms: full expansion (hyphens split into parts)
                 for (const kw of extractKeywords(term)) {
@@ -142,16 +188,18 @@ export function parseFilter(filter) {
                 }
             }
         }
-        return { must, mustNot };
+        return { must, mustNot, mustExact, mustTags };
     });
 }
 /** Check if a set of keywords matches a filter string using stemmed AND/OR/NOT logic.
- *  Entry matches if ANY OR-group is satisfied (all must-terms present, no mustNot-terms present). */
-export function matchesFilter(allKeywords, filter) {
+ *  Entry matches if ANY OR-group is satisfied (all must-terms present, no mustNot-terms present).
+ *  Supports =exact (no stemming) and #tag (exact match against entry tags). */
+export function matchesFilter(allKeywords, filter, tags) {
     const groups = parseFilter(filter);
     if (groups.length === 0)
         return true;
-    return groups.some(({ must, mustNot }) => {
+    const entryTags = new Set(tags ?? []);
+    return groups.some(({ must, mustNot, mustExact, mustTags }) => {
         for (const term of must) {
             if (!allKeywords.has(term))
                 return false;
@@ -160,18 +208,29 @@ export function matchesFilter(allKeywords, filter) {
             if (allKeywords.has(term))
                 return false;
         }
-        return must.size > 0 || mustNot.size > 0;
+        for (const term of mustExact) {
+            if (!allKeywords.has(term))
+                return false;
+        }
+        for (const tag of mustTags) {
+            if (!entryTags.has(tag))
+                return false;
+        }
+        return must.size > 0 || mustNot.size > 0 || mustExact.size > 0 || mustTags.size > 0;
     });
 }
 /** Compute relevance score for an entry against a filter.
- *  Title matches get 2x weight over content-only matches. */
-export function computeRelevanceScore(titleKeywords, contentKeywords, confidence, filter) {
+ *  Title matches get 2x weight over content-only matches.
+ *  Tag and exact matches count as full-weight hits (same as title). */
+export function computeRelevanceScore(titleKeywords, contentKeywords, confidence, filter, tags) {
     const groups = parseFilter(filter);
     if (groups.length === 0)
         return 0;
+    const entryTags = new Set(tags ?? []);
     let bestScore = 0;
-    for (const { must } of groups) {
-        if (must.size === 0)
+    for (const { must, mustExact, mustTags } of groups) {
+        const totalTerms = must.size + mustExact.size + mustTags.size;
+        if (totalTerms === 0)
             continue;
         let score = 0;
         for (const term of must) {
@@ -182,7 +241,20 @@ export function computeRelevanceScore(titleKeywords, contentKeywords, confidence
                 score += 1.0; // content-only match
             }
         }
-        const normalized = score / must.size;
+        for (const term of mustExact) {
+            if (titleKeywords.has(term)) {
+                score += 2.0;
+            }
+            else if (contentKeywords.has(term)) {
+                score += 1.0;
+            }
+        }
+        // Tag matches count as high-value (same as title hits)
+        for (const tag of mustTags) {
+            if (entryTags.has(tag))
+                score += 2.0;
+        }
+        const normalized = score / totalTerms;
         if (normalized > bestScore)
             bestScore = normalized;
     }

package/dist/thresholds.d.ts

@@ -45,3 +45,9 @@ export declare const DEFAULT_MAX_DEDUP_SUGGESTIONS = 3;
 export declare const DEFAULT_MAX_CONFLICT_PAIRS = 2;
 /** Maximum related preferences surfaced when storing a non-preference entry. */
 export declare const DEFAULT_MAX_PREFERENCE_SUGGESTIONS = 3;
+/** Score multiplier when an entry's tags match context keywords in contextSearch(). */
+export declare const TAG_MATCH_BOOST = 1.5;
+/** Maximum tags shown in vocabulary echo after a store operation. */
+export declare const VOCABULARY_ECHO_LIMIT = 8;
+/** Maximum tags shown in query/context footer. */
+export declare const MAX_FOOTER_TAGS = 12;

package/dist/thresholds.js

@@ -81,3 +81,9 @@ export const DEFAULT_MAX_DEDUP_SUGGESTIONS = 3;
 export const DEFAULT_MAX_CONFLICT_PAIRS = 2;
 /** Maximum related preferences surfaced when storing a non-preference entry. */
 export const DEFAULT_MAX_PREFERENCE_SUGGESTIONS = 3;
+/** Score multiplier when an entry's tags match context keywords in contextSearch(). */
+export const TAG_MATCH_BOOST = 1.5;
+/** Maximum tags shown in vocabulary echo after a store operation. */
+export const VOCABULARY_ECHO_LIMIT = 8;
+/** Maximum tags shown in query/context footer. */
+export const MAX_FOOTER_TAGS = 12;

package/dist/types.d.ts

@@ -4,6 +4,17 @@ export type TrustLevel = 'user' | 'agent-confirmed' | 'agent-inferred';
 export declare function parseTrustLevel(raw: string): TrustLevel | null;
 /** Predefined topic scopes for organizing knowledge */
 export type TopicScope = 'user' | 'preferences' | 'architecture' | 'conventions' | 'gotchas' | 'recent-work' | `modules/${string}`;
+/** Validated tag: lowercase alphanumeric slug (letters, digits, hyphens).
+ *  Branded type prevents accidentally passing raw strings where validated tags are expected. */
+export type Tag = string & {
+    readonly __brand: 'Tag';
+};
+/** Parse a raw string into a Tag, returning null for invalid input.
+ *  Normalizes to lowercase. Rejects empty, too-long, or non-slug strings. */
+export declare function parseTag(raw: string): Tag | null;
+/** Parse an array of raw strings into Tags, silently dropping invalid/duplicate ones.
+ *  Caps at MAX_TAGS_PER_ENTRY to prevent sprawl. */
+export declare function parseTags(raw: readonly string[]): readonly Tag[];
 /** Parse a raw string into a TopicScope, returning null for invalid input */
 export declare function parseTopicScope(raw: string): TopicScope | null;
 /** Injectable clock for deterministic time in tests */
@@ -23,6 +34,7 @@ export interface MemoryEntry {
     readonly trust: TrustLevel;
     readonly sources: readonly string[];
     readonly references?: readonly string[];
+    readonly tags?: readonly Tag[];
     readonly created: string;
     readonly lastAccessed: string;
     readonly gitSha?: string;
@@ -57,6 +69,7 @@ export interface QueryEntry {
     readonly relevanceScore: number;
     readonly fresh: boolean;
     readonly references?: readonly string[];
+    readonly tags?: readonly Tag[];
     readonly content?: string;
     readonly trust?: TrustLevel;
     readonly sources?: readonly string[];
@@ -113,6 +126,7 @@ export interface MemoryStats {
         stale: number;
         unknown: number;
     };
+    readonly byTag: Record<string, number>;
     readonly storageSize: string;
     readonly storageBudgetBytes: number;
     readonly memoryPath: string;

package/dist/types.js

@@ -10,6 +10,38 @@ export function parseTrustLevel(raw) {
     return TRUST_LEVELS.includes(raw) ? raw : null;
 }
 const FIXED_TOPICS = ['user', 'preferences', 'architecture', 'conventions', 'gotchas', 'recent-work'];
+const TAG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+const MAX_TAG_LENGTH = 50;
+const MAX_TAGS_PER_ENTRY = 10;
+/** Parse a raw string into a Tag, returning null for invalid input.
+ *  Normalizes to lowercase. Rejects empty, too-long, or non-slug strings. */
+export function parseTag(raw) {
+    const normalized = raw.trim().toLowerCase()
+        .replace(/[^a-z0-9-]/g, '-') // non-slug chars → dash
+        .replace(/-+/g, '-') // collapse consecutive dashes
+        .replace(/^-|-$/g, ''); // trim leading/trailing dashes
+    if (normalized.length < 2 || normalized.length > MAX_TAG_LENGTH)
+        return null;
+    if (!TAG_PATTERN.test(normalized))
+        return null;
+    return normalized;
+}
+/** Parse an array of raw strings into Tags, silently dropping invalid/duplicate ones.
+ *  Caps at MAX_TAGS_PER_ENTRY to prevent sprawl. */
+export function parseTags(raw) {
+    const tags = [];
+    const seen = new Set();
+    for (const r of raw) {
+        const tag = parseTag(r);
+        if (tag && !seen.has(tag)) {
+            seen.add(tag);
+            tags.push(tag);
+        }
+        if (tags.length >= MAX_TAGS_PER_ENTRY)
+            break;
+    }
+    return tags;
+}
 /** Parse a raw string into a TopicScope, returning null for invalid input */
 export function parseTopicScope(raw) {
     if (FIXED_TOPICS.includes(raw))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/memory-mcp",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Codebase memory MCP server - persistent, evolving knowledge for AI coding agents",
   "type": "module",
   "main": "dist/index.js",