@exaudeus/memory-mcp 1.4.0 → 1.5.0

package/README.md

@@ -8,7 +8,7 @@ A Model Context Protocol (MCP) server that gives AI coding agents persistent, ev
 |------|-------------|
 | `memory_context` | Session start AND pre-task lookup. Call with no args for user + preferences + stale nudges; call with `context` for task-specific knowledge |
 | `memory_query` | Structured search with brief/standard/full detail levels and AND/OR/NOT filter syntax. Scope defaults to `"*"` (all topics) |
-| `memory_store` | Store a knowledge entry with dedup detection, preference surfacing, and lobe auto-detection from file paths |
+| `memory_store` | Store a knowledge entry with dedup detection, preference surfacing, lobe auto-detection, and a review-required gate for likely-ephemeral content |
 | `memory_correct` | Correct, update, or delete an existing entry (suggests storing as preference) |
 | `memory_bootstrap` | First-use scan to seed knowledge from repo structure, README, and build files |
 
@@ -33,6 +33,7 @@ A Model Context Protocol (MCP) server that gives AI coding agents persistent, ev
 
 - **Dedup detection**: When you store an entry, the response shows similar existing entries in the same topic (>35% keyword overlap) with consolidation instructions
 - **Preference surfacing**: Storing a non-preference entry shows relevant preferences that might conflict
+- **Ephemeral review gate**: Likely-ephemeral content is blocked before persistence by default. Re-run `memory_store(..., durabilityDecision: "store-anyway")` only when you intentionally want to keep it.
 - **Piggyback hints**: `memory_correct` suggests storing corrections as reusable preferences
 - **`memory_context`**: Describe your task in natural language and get ranked results across all topics with topic-based boosting (preferences 1.8x, gotchas 1.5x)
 
@@ -108,10 +109,12 @@ If no `memory-config.json` is found, the server falls back to environment variab
 1. **Edit `memory-config.json`** (create if it doesn't exist)
 2. **Add lobe entry:**
    ```json
+   {
    "my-project": {
      "root": "$HOME/git/my-project",
      "budgetMB": 2
    }
+   }
    ```
 3. **Restart the memory MCP server**
 4. **Verify:** Use `memory_list_lobes` to confirm it loaded

package/dist/index.js

@@ -215,7 +215,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 // 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 stored in the alwaysInclude lobe (shared across projects). One insight per object; use multiple objects instead of bundling.',
+                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 stored in the alwaysInclude lobe (shared across projects). One insight per object; use multiple objects instead of bundling. If content looks likely-ephemeral, the tool returns a review-required response; re-run with durabilityDecision: "store-anyway" only when deliberate.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -272,6 +272,12 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             description: 'Category labels for exact-match retrieval (lowercase slugs). Query with filter: "#tag". Example: ["auth", "critical-path", "mite-combat"]',
                             default: [],
                         },
+                        durabilityDecision: {
+                            type: 'string',
+                            enum: ['default', 'store-anyway'],
+                            description: 'Write intent for content that may require review. Use "default" normally. Use "store-anyway" only when intentionally persisting content after a review-required response.',
+                            default: 'default',
+                        },
                     },
                     required: ['topic', 'entries'],
                 },
@@ -442,7 +448,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 };
             }
             case 'memory_store': {
-                const { lobe: rawLobe, topic: rawTopic, entries: rawEntries, sources, references, trust: rawTrust, tags: rawTags } = z.object({
+                const { lobe: rawLobe, topic: rawTopic, entries: rawEntries, sources, references, trust: rawTrust, tags: rawTags, durabilityDecision } = z.object({
                     lobe: z.string().optional(),
                     topic: z.string(),
                     // Accept a bare {title, fact} object in addition to the canonical array form.
@@ -456,6 +462,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     references: z.array(z.string()).default([]),
                     trust: z.enum(['user', 'agent-confirmed', 'agent-inferred']).default('agent-inferred'),
                     tags: z.array(z.string()).default([]),
+                    durabilityDecision: z.enum(['default', 'store-anyway']).default('default'),
                 }).parse(args);
                 // Validate topic at boundary
                 const topic = parseTopicScope(rawTopic);
@@ -494,8 +501,26 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     : 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) {
+                    const result = await ctx.store.store(topic, title, fact, sources, effectiveTrust, references, rawTags, durabilityDecision);
+                    if (result.kind === 'review-required') {
+                        const lines = [
+                            `[${ctx.label}] Review required before storing "${title}".`,
+                            '',
+                            `Severity: ${result.severity}`,
+                            'Signals:',
+                            ...result.signals.map(signal => `- ${signal.label}: ${signal.detail}`),
+                            '',
+                            result.warning,
+                            '',
+                            'If this knowledge is still worth persisting, re-run with:',
+                            `memory_store(topic: "${topic}", entries: [{title: "${title}", fact: "${fact.replace(/"/g, '\\"')}"}], trust: "${effectiveTrust}", durabilityDecision: "store-anyway"${rawTags.length > 0 ? `, tags: ${JSON.stringify(rawTags)}` : ''}${sources.length > 0 ? `, sources: ${JSON.stringify(sources)}` : ''}${references.length > 0 ? `, references: ${JSON.stringify(references)}` : ''})`,
+                        ];
+                        return {
+                            content: [{ type: 'text', text: lines.join('\n') }],
+                            isError: true,
+                        };
+                    }
+                    if (result.kind === 'rejected') {
                         return {
                             content: [{ type: 'text', text: `[${ctx.label}] Failed to store "${title}": ${result.warning}` }],
                             isError: true,
@@ -1092,8 +1117,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 if (!ctx.ok)
                     return contextError(ctx);
                 const results = await ctx.store.bootstrap();
-                const stored = results.filter(r => r.stored);
-                const failed = results.filter(r => !r.stored);
+                const stored = results.filter((r) => r.kind === 'stored');
+                const failed = results.filter((r) => r.kind !== 'stored');
                 let text = `## [${ctx.label}] Bootstrap Complete\n\nStored ${stored.length} entries:`;
                 for (const r of stored) {
                     text += `\n- ${r.id}: ${r.topic} (${r.file})`;

package/dist/store.d.ts

@@ -1,4 +1,4 @@
-import type { MemoryEntry, TopicScope, TrustLevel, DetailLevel, QueryResult, StoreResult, CorrectResult, MemoryStats, BriefingResult, ConflictPair, MemoryConfig } from './types.js';
+import type { MemoryEntry, TopicScope, TrustLevel, DetailLevel, DurabilityDecision, QueryResult, StoreResult, CorrectResult, MemoryStats, BriefingResult, ConflictPair, MemoryConfig } from './types.js';
 export declare class MarkdownMemoryStore {
     private readonly config;
     private readonly memoryPath;
@@ -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[], rawTags?: string[]): Promise<StoreResult>;
+    store(topic: TopicScope, title: string, content: string, sources?: string[], trust?: TrustLevel, references?: string[], rawTags?: string[], durabilityDecision?: DurabilityDecision): 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 */

package/dist/store.js

@@ -41,15 +41,35 @@ export class MarkdownMemoryStore {
         await this.reloadFromDisk();
     }
     /** Store a new knowledge entry */
-    async store(topic, title, content, sources = [], trust = 'agent-inferred', references = [], rawTags = []) {
+    async store(topic, title, content, sources = [], trust = 'agent-inferred', references = [], rawTags = [], durabilityDecision = 'default') {
         // Check storage budget — null means we can't measure, allow the write
         const currentSize = await this.getStorageSize();
         if (currentSize !== null && currentSize >= this.config.storageBudgetBytes) {
             return {
-                stored: false, topic,
+                kind: 'rejected', stored: false, topic,
                 warning: `Storage budget exceeded (${this.formatBytes(currentSize)} / ${this.formatBytes(this.config.storageBudgetBytes)}). Delete or correct existing entries to free space.`,
             };
         }
+        const ephemeralSignals = topic !== 'recent-work'
+            ? detectEphemeralSignals(title, content, topic)
+            : [];
+        const ephemeralSeverity = getEphemeralSeverity(ephemeralSignals);
+        const requiresReview = ephemeralSeverity === 'medium' || ephemeralSeverity === 'high';
+        if (durabilityDecision === 'default' && requiresReview) {
+            return {
+                kind: 'review-required',
+                stored: false,
+                topic,
+                severity: ephemeralSeverity,
+                warning: `Likely ephemeral content detected. Review the signals and re-run with durabilityDecision: "store-anyway" if this knowledge should still be persisted.`,
+                signals: ephemeralSignals.map(signal => ({
+                    id: signal.id,
+                    label: signal.label,
+                    detail: signal.detail,
+                    confidence: signal.confidence,
+                })),
+            };
+        }
         const id = this.generateId(topic);
         const now = this.clock.isoNow();
         const confidence = DEFAULT_CONFIDENCE[trust];
@@ -85,15 +105,9 @@ export class MarkdownMemoryStore {
         const relevantPreferences = (topic !== 'preferences' && topic !== 'user')
             ? this.findRelevantPreferences(entry)
             : undefined;
-        // Soft ephemeral detection — warn but never block
-        const ephemeralSignals = topic !== 'recent-work'
-            ? detectEphemeralSignals(title, content, topic)
-            : [];
-        // 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,
+            kind: 'stored', stored: true, id, topic, file, confidence, warning, ephemeralWarning,
             ephemeralSeverity: ephemeralSeverity ?? undefined,
             relatedEntries: relatedEntries.length > 0 ? relatedEntries : undefined,
             relevantPreferences: relevantPreferences && relevantPreferences.length > 0 ? relevantPreferences : undefined,
@@ -384,7 +398,7 @@ export class MarkdownMemoryStore {
         catch { /* not a git repo or git not available */ }
         // 5. Fallback: if nothing was detected, store a minimal overview so the lobe
         //    is never left completely empty after bootstrap (makes memory_context useful immediately).
-        const storedCount = results.filter(r => r.stored).length;
+        const storedCount = results.filter(r => r.kind === 'stored').length;
         if (storedCount === 0) {
             try {
                 const topLevel = await fs.readdir(repoRoot, { withFileTypes: true });

package/dist/types.d.ts

@@ -89,8 +89,21 @@ export interface RelatedEntry {
     readonly confidence: number;
     readonly trust: TrustLevel;
 }
+/** Caller intent for writes that may require a durability decision.
+ *  Explicit domain type avoids booleanly-typed override semantics. */
+export type DurabilityDecision = 'default' | 'store-anyway';
+/** Structured signal attached to a review-required store outcome.
+ *  Duplicated here (rather than importing from ephemeral.ts) to keep the store
+ *  result contract independent of a concrete detection implementation. */
+export interface ReviewSignal {
+    readonly id: string;
+    readonly label: string;
+    readonly detail: string;
+    readonly confidence: 'high' | 'medium' | 'low';
+}
 /** Result of a memory store operation — discriminated union eliminates impossible states */
 export type StoreResult = {
+    readonly kind: 'stored';
     readonly stored: true;
     readonly id: string;
     readonly topic: TopicScope;
@@ -104,6 +117,14 @@ export type StoreResult = {
     readonly relatedEntries?: readonly RelatedEntry[];
     readonly relevantPreferences?: readonly RelatedEntry[];
 } | {
+    readonly kind: 'review-required';
+    readonly stored: false;
+    readonly topic: TopicScope;
+    readonly severity: EphemeralSeverity;
+    readonly warning: string;
+    readonly signals: readonly ReviewSignal[];
+} | {
+    readonly kind: 'rejected';
     readonly stored: false;
     readonly topic: TopicScope;
     readonly warning: string;

package/package.json

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