@exaudeus/memory-mcp 1.2.0 → 1.4.0

package/dist/lobe-resolution.d.ts

@@ -0,0 +1,34 @@
+/** Outcome of resolving which lobes to search when the agent didn't specify one. */
+export type LobeResolution = {
+    readonly kind: 'resolved';
+    readonly lobes: readonly string[];
+    readonly label: string;
+} | {
+    readonly kind: 'global-only';
+    readonly hint: string;
+};
+/** A root URI from the MCP client (e.g. "file:///Users/me/projects/zillow"). */
+export interface ClientRoot {
+    readonly uri: string;
+}
+/** Minimal lobe config needed for matching — just the repo root path. */
+export interface LobeRootConfig {
+    readonly name: string;
+    readonly repoRoot: string;
+}
+/** Match MCP client workspace root URIs against known lobe repo roots.
+ *  Returns matched lobe names, or empty array if none match.
+ *
+ *  Matching rules:
+ *  - file:// URIs are stripped to filesystem paths
+ *  - Both paths are normalized via path.resolve
+ *  - A match occurs when either path is equal to or nested inside the other,
+ *    checked at path-separator boundaries (no partial-name false positives) */
+export declare function matchRootsToLobeNames(clientRoots: readonly ClientRoot[], lobeConfigs: readonly LobeRootConfig[]): readonly string[];
+/** Build a LobeResolution from the available lobe names and matched lobes.
+ *  Encodes the degradation ladder as a pure function.
+ *
+ *  When isFirstMemoryToolCall is true (default), alwaysIncludeLobes are appended
+ *  to the resolved set (deduped). When false, they are excluded — the agent has
+ *  already loaded global knowledge in this conversation. */
+export declare function buildLobeResolution(allLobeNames: readonly string[], matchedLobes: readonly string[], alwaysIncludeLobes?: readonly string[], isFirstMemoryToolCall?: boolean): LobeResolution;

package/dist/lobe-resolution.js

@@ -0,0 +1,89 @@
+// Pure lobe resolution logic — extracted for testability.
+//
+// When the agent doesn't specify a lobe, we determine which lobe(s) to search
+// via a degradation ladder:
+//   1. Single lobe configured → use it (unambiguous)
+//   2. Multiple lobes → match client workspace roots against lobe repo roots
+//   3. Fallback → global-only with a hint to specify the lobe
+//
+// This prevents cross-lobe leakage (e.g. game design lore surfacing in an Android MR review).
+import path from 'path';
+/** Check if `child` is equal to or nested under `parent` with path-boundary awareness.
+ *  Prevents false matches like "/projects/zillow-tools" matching "/projects/zillow". */
+function isPathPrefixOf(parent, child) {
+    if (child === parent)
+        return true;
+    // Ensure the prefix ends at a path separator boundary
+    const withSep = parent.endsWith(path.sep) ? parent : parent + path.sep;
+    return child.startsWith(withSep);
+}
+/** Match MCP client workspace root URIs against known lobe repo roots.
+ *  Returns matched lobe names, or empty array if none match.
+ *
+ *  Matching rules:
+ *  - file:// URIs are stripped to filesystem paths
+ *  - Both paths are normalized via path.resolve
+ *  - A match occurs when either path is equal to or nested inside the other,
+ *    checked at path-separator boundaries (no partial-name false positives) */
+export function matchRootsToLobeNames(clientRoots, lobeConfigs) {
+    if (clientRoots.length === 0 || lobeConfigs.length === 0)
+        return [];
+    const matchedLobes = new Set();
+    for (const root of clientRoots) {
+        // MCP roots use file:// URIs — strip the scheme to get the filesystem path
+        const rootPath = root.uri.startsWith('file://') ? root.uri.slice(7) : root.uri;
+        const normalizedRoot = path.resolve(rootPath);
+        for (const lobe of lobeConfigs) {
+            const normalizedLobe = path.resolve(lobe.repoRoot);
+            // Match if one path is equal to or nested inside the other
+            if (isPathPrefixOf(normalizedLobe, normalizedRoot) || isPathPrefixOf(normalizedRoot, normalizedLobe)) {
+                matchedLobes.add(lobe.name);
+            }
+        }
+    }
+    return Array.from(matchedLobes);
+}
+/** Build a LobeResolution from the available lobe names and matched lobes.
+ *  Encodes the degradation ladder as a pure function.
+ *
+ *  When isFirstMemoryToolCall is true (default), alwaysIncludeLobes are appended
+ *  to the resolved set (deduped). When false, they are excluded — the agent has
+ *  already loaded global knowledge in this conversation. */
+export function buildLobeResolution(allLobeNames, matchedLobes, alwaysIncludeLobes = [], isFirstMemoryToolCall = true) {
+    // Single lobe — always resolved, regardless of root matching
+    if (allLobeNames.length === 1 && alwaysIncludeLobes.length === 0) {
+        return { kind: 'resolved', lobes: allLobeNames, label: allLobeNames[0] };
+    }
+    // Build the base resolved set
+    let baseLobes;
+    if (allLobeNames.length === 1) {
+        baseLobes = allLobeNames;
+    }
+    else if (matchedLobes.length > 0) {
+        baseLobes = matchedLobes;
+    }
+    else {
+        baseLobes = [];
+    }
+    // Append alwaysInclude lobes when isFirstMemoryToolCall is true (deduped)
+    const resolvedSet = new Set(baseLobes);
+    if (isFirstMemoryToolCall) {
+        for (const lobe of alwaysIncludeLobes) {
+            resolvedSet.add(lobe);
+        }
+    }
+    if (resolvedSet.size > 0) {
+        const lobes = Array.from(resolvedSet);
+        return {
+            kind: 'resolved',
+            lobes,
+            label: lobes.length === 1 ? lobes[0] : lobes.join('+'),
+        };
+    }
+    // Fallback — no lobes could be determined
+    return {
+        kind: 'global-only',
+        hint: `Multiple lobes available (${allLobeNames.join(', ')}) but none could be inferred from client workspace roots. ` +
+            `Specify lobe parameter for lobe-specific results.`,
+    };
+}

package/dist/store.d.ts

@@ -18,6 +18,9 @@ export declare class MarkdownMemoryStore {
     query(scope: string, detail?: DetailLevel, filter?: string, branchFilter?: string): Promise<QueryResult>;
     /** Generate a session-start briefing */
     briefing(maxTokens?: number): Promise<BriefingResult>;
+    /** Check if an entry exists by ID — read-only, no side effects beyond disk reload.
+     *  Use this to probe for entry ownership before calling correct(). */
+    hasEntry(id: string): Promise<boolean>;
     /** Correct an existing entry */
     correct(id: string, correction: string, action: 'append' | 'replace' | 'delete'): Promise<CorrectResult>;
     /** Get memory health statistics */

package/dist/store.js

@@ -10,7 +10,7 @@ import { DEFAULT_CONFIDENCE, realClock, parseTopicScope, parseTrustLevel, parseT
 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';
+import { detectEphemeralSignals, formatEphemeralWarning, getEphemeralSeverity } from './ephemeral.js';
 // Used only by bootstrap() for git log — not part of the GitService boundary
 // because bootstrap is a one-shot utility, not a recurring operation
 const execFileAsync = promisify(execFile);
@@ -89,9 +89,12 @@ export class MarkdownMemoryStore {
         const ephemeralSignals = topic !== 'recent-work'
             ? detectEphemeralSignals(title, content, topic)
             : [];
-        const ephemeralWarning = formatEphemeralWarning(ephemeralSignals);
+        // getEphemeralSeverity is the single source of threshold logic shared with formatEphemeralWarning.
+        const ephemeralSeverity = getEphemeralSeverity(ephemeralSignals);
+        const ephemeralWarning = formatEphemeralWarning(ephemeralSignals, id);
         return {
             stored: true, id, topic, file, confidence, warning, ephemeralWarning,
+            ephemeralSeverity: ephemeralSeverity ?? undefined,
             relatedEntries: relatedEntries.length > 0 ? relatedEntries : undefined,
             relevantPreferences: relevantPreferences && relevantPreferences.length > 0 ? relevantPreferences : undefined,
         };
@@ -253,6 +256,12 @@ export class MarkdownMemoryStore {
             suggestion,
         };
     }
+    /** Check if an entry exists by ID — read-only, no side effects beyond disk reload.
+     *  Use this to probe for entry ownership before calling correct(). */
+    async hasEntry(id) {
+        await this.reloadFromDisk();
+        return this.entries.has(id);
+    }
     /** Correct an existing entry */
     async correct(id, correction, action) {
         // Reload to ensure we have the latest

package/dist/thresholds.d.ts

@@ -16,14 +16,6 @@ export declare const CONFLICT_MIN_CONTENT_CHARS = 50;
 export declare const OPPOSITION_PAIRS: ReadonlyArray<readonly [string, string]>;
 /** Score multiplier when a reference path basename matches the context keywords. */
 export declare const REFERENCE_BOOST_MULTIPLIER = 1.3;
-/** Score multiplier applied to weak cross-lobe results in multi-lobe context search.
- *  Prevents generic software terms (e.g. "codebase", "structure") from surfacing
- *  entries from unrelated repos with high confidence/topic-boost scores. */
-export declare const CROSS_LOBE_WEAK_SCORE_PENALTY = 0.5;
-/** Fraction of context keywords an entry must match to avoid the cross-lobe penalty.
- *  E.g. 0.40 means an entry must match at least 40% of the context keywords (minimum 2)
- *  to be treated as a strong cross-lobe match. */
-export declare const CROSS_LOBE_MIN_MATCH_RATIO = 0.4;
 /** Per-topic scoring boost factors for contextSearch().
  *  Higher = more likely to surface for any given context. */
 export declare const TOPIC_BOOST: Record<string, number>;
@@ -51,3 +43,6 @@ export declare const TAG_MATCH_BOOST = 1.5;
 export declare const VOCABULARY_ECHO_LIMIT = 8;
 /** Maximum tags shown in query/context footer. */
 export declare const MAX_FOOTER_TAGS = 12;
+/** Visual separator for warning blocks in tool responses.
+ *  Width chosen to stand out as a block boundary in any terminal or chat rendering. */
+export declare const WARN_SEPARATOR: string;

package/dist/thresholds.js

@@ -42,14 +42,6 @@ export const OPPOSITION_PAIRS = [
 ];
 /** Score multiplier when a reference path basename matches the context keywords. */
 export const REFERENCE_BOOST_MULTIPLIER = 1.30;
-/** Score multiplier applied to weak cross-lobe results in multi-lobe context search.
- *  Prevents generic software terms (e.g. "codebase", "structure") from surfacing
- *  entries from unrelated repos with high confidence/topic-boost scores. */
-export const CROSS_LOBE_WEAK_SCORE_PENALTY = 0.50;
-/** Fraction of context keywords an entry must match to avoid the cross-lobe penalty.
- *  E.g. 0.40 means an entry must match at least 40% of the context keywords (minimum 2)
- *  to be treated as a strong cross-lobe match. */
-export const CROSS_LOBE_MIN_MATCH_RATIO = 0.40;
 /** Per-topic scoring boost factors for contextSearch().
  *  Higher = more likely to surface for any given context. */
 export const TOPIC_BOOST = {
@@ -87,3 +79,7 @@ export const TAG_MATCH_BOOST = 1.5;
 export const VOCABULARY_ECHO_LIMIT = 8;
 /** Maximum tags shown in query/context footer. */
 export const MAX_FOOTER_TAGS = 12;
+// ─── Display formatting constants ───────────────────────────────────────────
+/** Visual separator for warning blocks in tool responses.
+ *  Width chosen to stand out as a block boundary in any terminal or chat rendering. */
+export const WARN_SEPARATOR = '='.repeat(52);

package/dist/types.d.ts

@@ -1,5 +1,8 @@
 /** Trust levels for knowledge sources, ordered by reliability */
 export type TrustLevel = 'user' | 'agent-confirmed' | 'agent-inferred';
+/** Ephemeral detection severity — three distinct levels so consumers can branch exhaustively.
+ *  Separated from EphemeralSignal.confidence to represent the aggregate outcome of all signals. */
+export type EphemeralSeverity = 'high' | 'medium' | 'low';
 /** Parse a raw string into a TrustLevel, returning null for invalid input */
 export declare function parseTrustLevel(raw: string): TrustLevel | null;
 /** Predefined topic scopes for organizing knowledge */
@@ -96,6 +99,8 @@ export type StoreResult = {
     readonly warning?: string;
     /** Soft warning when content looks ephemeral — informational, never blocking */
     readonly ephemeralWarning?: string;
+    /** Aggregate severity of all ephemeral signals that fired — absent when none fired */
+    readonly ephemeralSeverity?: EphemeralSeverity;
     readonly relatedEntries?: readonly RelatedEntry[];
     readonly relevantPreferences?: readonly RelatedEntry[];
 } | {
@@ -190,6 +195,7 @@ export interface MemoryConfig {
     readonly repoRoot: string;
     readonly memoryPath: string;
     readonly storageBudgetBytes: number;
+    readonly alwaysInclude: boolean;
     readonly behavior?: BehaviorConfig;
     readonly clock?: Clock;
     readonly git?: GitService;

package/package.json

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