@exaudeus/memory-mcp 1.0.1 → 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');
+}

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,7 @@ 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")',
+                description: 'Store knowledge. "user" and "preferences" are global (no lobe needed). Use tags for exact-match categorization. Add a shared tag (e.g., "test-entry") for bulk operations. Example: memory_store(topic: "gotchas", title: "Build cache", content: "Must clean build after Tuist changes", tags: ["build", "ios"])',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -222,13 +222,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'],
                 },
             },
             {
                 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 +251,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,7 +393,7 @@ 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, title, content, sources, references, trust: rawTrust, tags: rawTags } = z.object({
                     lobe: z.string().optional(),
                     topic: z.string(),
                     title: z.string().min(1),
@@ -395,6 +401,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     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);
@@ -419,7 +426,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     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);
+                isGlobal && trust === 'agent-inferred' ? 'user' : trust, references, rawTags);
                 if (!result.stored) {
                     return {
                         content: [{ type: 'text', text: `[${ctx.label}] Failed to store: ${result.warning}` }],
@@ -464,6 +471,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     lines.push('');
                     lines.push('Review the stored entry against these preferences for potential conflicts.');
                 }
+                // Vocabulary echo: show existing tags to drive convergence
+                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".`);
+                    }
+                }
                 return { content: [{ type: 'text', text: lines.join('\n') }] };
             }
             case 'memory_query': {
@@ -537,14 +558,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 +605,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 +633,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 +756,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 +842,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 +894,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 +914,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': {

package/dist/normalize.js

@@ -19,6 +19,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.1.0",
   "description": "Codebase memory MCP server - persistent, evolving knowledge for AI coding agents",
   "type": "module",
   "main": "dist/index.js",