memtap 2.1.0 → 3.1.0

package/README.md

@@ -3,7 +3,7 @@
 [![npm](https://img.shields.io/npm/v/memtap)](https://www.npmjs.com/package/memtap)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
-**MemTap** gives your OpenClaw agent a persistent, graph-based long-term memory powered by ArangoDB.
+**MemTap** gives your OpenClaw agent a persistent, graph-based long-term memory.
 
 Instead of simple vector recall, MemTap builds a **knowledge graph** — memories are connected through entities, relationships, and temporal context. Your agent remembers facts, tracks decisions, discovers connections through multi-hop graph traversal, and consolidates knowledge over time.
 
@@ -104,6 +104,7 @@ Sign up at [memtap.ai](https://memtap.ai) to get your API key.
 ## Why MemTap?
 
 - **Graph-based**: Full knowledge graph, not just vector similarity
+- **Cloud-native**: Managed service — no database setup needed
 - **GraphRAG**: Multi-hop traversal discovers connections vector search misses
 - **Decision tracking**: Unique decision management for AI agents
 - **Auto-capture**: Learns from conversations without explicit commands
@@ -114,8 +115,8 @@ Sign up at [memtap.ai](https://memtap.ai) to get your API key.
 
 - **Website**: [memtap.ai](https://memtap.ai)
 - **API Docs**: [api.memtap.ai](https://api.memtap.ai)
-- **GitHub**: [github.com/memtap/openclaw-plugin](https://github.com/memtap/openclaw-plugin)
-- **Support**: [github.com/memtap/openclaw-plugin/issues](https://github.com/memtap/openclaw-plugin/issues)
+- **GitHub**: [github.com/psifactory/memtap](https://github.com/psifactory/memtap)
+- **Support**: [github.com/psifactory/memtap/issues](https://github.com/psifactory/memtap/issues)
 
 ## License
 

package/index.ts

@@ -1,23 +1,31 @@
 /**
  * MemTap — Graph-based Long-Term Memory Plugin for OpenClaw
- * v2.1.0 "The Neuron" — Neuromimetic Memory System with Human-like Cognition
+ * v3.1.0 "The Oracle" — Proactive Surfacing, Learning Loop & Inference Engine
  *
  * Tools:
- *  - memtap_recall       — semantic graph recall
- *  - memtap_remember     — store a memory in the graph
- *  - memtap_memory       — get, update, delete individual memories
- *  - memtap_bulletin     — context bulletin with graph expansion
- *  - memtap_graph        — graph analysis (overview, gaps, clusters, connections, traverse)
- *  - memtap_decide       — decision tracking (list, create, resolve, defer)
- *  - memtap_graphrag     — vector/BM25 + graph traversal search
- *  - memtap_maintenance  — memory maintenance (decay-report, contradictions, dedup-scan, run-all)
- *  - memtap_entities     — entity management (list, memories, merge)
- *  - memtap_edges        — create edges between memories
- *  - memtap_health       — server health check and statistics
+ *  - memtap_recall        — semantic graph recall
+ *  - memtap_remember      — store a memory in the graph (supports immutable flag)
+ *  - memtap_memory        — get, update, delete individual memories
+ *  - memtap_bulletin      — context bulletin with graph expansion
+ *  - memtap_graph         — graph analysis (overview, gaps, clusters, connections, traverse)
+ *  - memtap_decide        — decision tracking (list, create, resolve, defer)
+ *  - memtap_graphrag      — vector/BM25 + graph traversal search
+ *  - memtap_maintenance   — memory maintenance (decay-report, contradictions, dedup-scan, resolve-contradictions, run-all)
+ *  - memtap_entities      — entity management (list, memories, merge)
+ *  - memtap_edges         — create edges between memories
+ *  - memtap_consolidate   — consolidate related memories into synthesized summaries
+ *  - memtap_profile       — view/refresh agent memory profile
+ *  - memtap_export        — export memory graph (json, graphml, markdown)
+ *  - memtap_health        — server health check and statistics
+ *  - memtap_outcome       — record decision outcomes for learning loop
+ *  - memtap_infer         — inference engine: discover implicit knowledge via graph traversal + LLM reasoning
  *
  * Hooks:
- *  - preMessage         — neuromimetic tiered recall with working memory simulation
- *  - message_completed  — attention-gated encoding with emotional weighting
+ *  - preMessage         — neuromimetic tiered recall with working memory simulation + adaptive decay reinforcement
+ *                         + proactive surfacing of thematically related memories
+ *                         + decision outcome context injection (learning loop)
+ *  - message_completed  — attention-gated encoding with emotional weighting + auto-category assignment
+ *                         + proactive memory usage tracking with importance reinforcement
  *  - agent:bootstrap    — inject memory bulletin at session start
  *  - periodic           — dream-mode consolidation and neural maintenance
  *  - session_end        — performance monitoring and neural analytics
@@ -38,6 +46,10 @@ interface MemTapConfig {
   embeddingModel?: string;
   embeddingApiKey?: string;
   decayRate?: number;
+  instructions?: {
+    include?: string[];
+    exclude?: string[];
+  };
 }
 
 function getConfig(api: any): MemTapConfig {
@@ -88,7 +100,9 @@ function storeImportance(userValue: number): number {
 
 // ── Memory types ─────────────────────────────────────────────────────────────
 
-const MEMORY_TYPES = ['fact', 'preference', 'decision', 'identity', 'event', 'observation', 'goal', 'task'] as const;
+const MEMORY_TYPES = ['fact', 'preference', 'decision', 'identity', 'event', 'observation', 'goal', 'task', 'consolidated', 'outcome', 'inferred'] as const;
+
+const MEMORY_CATEGORIES = ['personal', 'professional', 'technical', 'project', 'health', 'preferences'] as const;
 
 // ── Neuromimetic Memory System (v2.1 "The Neuron") ──────────────────────────
 
@@ -178,6 +192,9 @@ const memoryCache = new Map<string, { data: any[]; timestamp: number; query: str
 // Attention tracking for encoding decisions
 let attentionHistory: Array<{ timestamp: number; agent: string; level: string; trigger: string }> = [];
 
+// Proactive surfacing tracking (which proactive memories were injected per agent)
+const proactiveSurfacedMemories = new Map<string, { memoryIds: string[]; timestamp: number }>();
+
 // ── Neuromimetic Functions ──────────────────────────────────────────────────
 
 function updateWorkingMemory(agentId: string, topics: string[], memories: any[] = []): WorkingMemory {
@@ -571,7 +588,8 @@ Antwort als JSON-Array (NUR das Array, kein Markdown):
     "content": "Kurze, prägnante Beschreibung des Fakts",
     "type": "fact|preference|decision|identity|event|observation|goal|task",
     "importance": 1-10,
-    "tags": ["tag1", "tag2"]
+    "tags": ["tag1", "tag2"],
+    "category": "personal|professional|technical|project|health|preferences"
   }
 ]
 
@@ -680,19 +698,21 @@ export default function register(api: any) {
         type: { type: 'string', enum: MEMORY_TYPES, description: 'Memory type (default: fact)' },
         importance: { type: 'number', description: 'Importance 1-10 (default: 5)' },
         tags: { type: 'array', items: { type: 'string' }, description: 'Optional tags for categorization' },
+        immutable: { type: 'boolean', description: 'Mark memory as immutable (cannot be auto-decayed or auto-archived)' },
       },
       required: ['content'],
     },
-    async execute(_id: string, params: { content: string; type?: string; importance?: number; tags?: string[] }) {
+    async execute(_id: string, params: { content: string; type?: string; importance?: number; tags?: string[]; immutable?: boolean }) {
       const cfg = getConfig(api);
       const importance = params.importance ?? 5;
-      const body = {
+      const body: Record<string, any> = {
         content: params.content,
         type: params.type || 'fact',
         agent: agentId(cfg, api),
         importance: storeImportance(importance),
         tags: params.tags || [],
       };
+      if (params.immutable) body.immutable = true;
 
       try {
         const data = await bbFetch(cfg, `${baseUrl(cfg)}/memories`, {
@@ -857,13 +877,14 @@ export default function register(api: any) {
       '- decay-report: find memories that have decayed below importance threshold\n' +
       '- contradictions: find contradicting memory pairs\n' +
       '- dedup-scan: find potential duplicate memories\n' +
+      '- resolve-contradictions: use LLM to resolve contradicting memories\n' +
       '- run-all: combined report of all checks',
     parameters: {
       type: 'object',
       properties: {
         action: {
           type: 'string',
-          enum: ['decay-report', 'contradictions', 'dedup-scan', 'run-all'],
+          enum: ['decay-report', 'contradictions', 'dedup-scan', 'resolve-contradictions', 'run-all'],
           description: 'Maintenance action to run',
         },
       },
@@ -925,6 +946,63 @@ export default function register(api: any) {
             return { content: [{ type: 'text', text: output }] };
           }
 
+          case 'resolve-contradictions': {
+            // Fetch contradictions
+            data = await bbFetch(cfg, `${base}/maintenance/contradictions`);
+            const contradictions = data.results || data.contradictions || [];
+            if (contradictions.length === 0) {
+              return { content: [{ type: 'text', text: 'No contradictions found to resolve.' }] };
+            }
+
+            let resolved = 0;
+            const resolutions: string[] = [];
+
+            for (const c of contradictions.slice(0, 10)) {
+              const m1 = c.memory1 || c;
+              const m2 = c.memory2 || c;
+              const m1Summary = m1.summary || m1.content || m1.from || '';
+              const m2Summary = m2.summary || m2.content || m2.to || '';
+
+              try {
+                const llmUrl = cfg.llmUrl || 'http://127.0.0.1:18789/v1/chat/completions';
+                const model = cfg.llmModel || 'anthropic/claude-sonnet-4-20250514';
+                const llmRes = await fetch(llmUrl, {
+                  method: 'POST',
+                  headers: { 'Content-Type': 'application/json' },
+                  body: JSON.stringify({
+                    model,
+                    max_tokens: 500,
+                    messages: [
+                      { role: 'system', content: 'You resolve contradictions between two memories. Decide which is more current/accurate. Respond with JSON: {"keep": 1 or 2, "reason": "short reason"}' },
+                      { role: 'user', content: `Memory 1 (created: ${m1.created || '?'}): ${m1Summary}\nMemory 2 (created: ${m2.created || '?'}): ${m2Summary}` },
+                    ],
+                  }),
+                });
+                if (!llmRes.ok) continue;
+                const llmData = await llmRes.json();
+                const text = llmData.choices?.[0]?.message?.content?.trim() || '';
+                const cleaned = text.replace(/^```json?\n?/m, '').replace(/\n?```$/m, '').trim();
+                const verdict = JSON.parse(cleaned);
+
+                const keepId = verdict.keep === 1 ? (m1.id || m1._key) : (m2.id || m2._key);
+                const archiveId = verdict.keep === 1 ? (m2.id || m2._key) : (m1.id || m1._key);
+
+                if (keepId && archiveId) {
+                  await bbFetch(cfg, `${base}/maintenance/resolve-contradiction`, {
+                    method: 'POST',
+                    body: JSON.stringify({ keep: keepId, archive: archiveId, reason: verdict.reason }),
+                  });
+                  resolved++;
+                  resolutions.push(`Kept [${keepId}], archived [${archiveId}]: ${verdict.reason}`);
+                }
+              } catch { /* skip individual resolution failures */ }
+            }
+
+            let output = `Contradiction Resolution: ${resolved}/${contradictions.length} resolved\n\n`;
+            output += resolutions.map((r, i) => `  ${i + 1}. ${r}`).join('\n');
+            return { content: [{ type: 'text', text: output }] };
+          }
+
           case 'run-all': {
             data = await bbFetch(cfg, `${base}/maintenance/run-all`, { method: 'POST', body: '{}' });
             const decay = data.decay || data.decayReport || {};
@@ -1342,13 +1420,208 @@ export default function register(api: any) {
     },
   });
 
+  // ── Tool: memtap_consolidate ──────────────────────────────────────────────
+
+  api.registerTool({
+    name: 'memtap_consolidate',
+    description:
+      'Consolidate related memories into a synthesized summary. ' +
+      'Searches memories by entity or topic, uses LLM to create a synthesis, ' +
+      'and stores the result as a consolidated memory linked to the originals.',
+    parameters: {
+      type: 'object',
+      properties: {
+        entity: { type: 'string', description: 'Entity name to consolidate memories around' },
+        topic: { type: 'string', description: 'Topic to consolidate memories about' },
+      },
+    },
+    async execute(_id: string, params: { entity?: string; topic?: string }) {
+      if (!params.entity && !params.topic) {
+        return { content: [{ type: 'text', text: 'Provide at least "entity" or "topic" to consolidate.' }], isError: true };
+      }
+
+      const cfg = getConfig(api);
+      const base = baseUrl(cfg);
+      const agent = agentId(cfg, api);
+      const query = params.entity || params.topic || '';
+
+      try {
+        // 1. Recall related memories
+        const recallUrl = new URL('/recall', base);
+        recallUrl.searchParams.set('q', query);
+        recallUrl.searchParams.set('agent', agent);
+        recallUrl.searchParams.set('limit', '20');
+        const recallData = await bbFetch(cfg, recallUrl.toString());
+        const memories = recallData.results || recallData.memories || [];
+
+        if (memories.length < 2) {
+          return { content: [{ type: 'text', text: `Only ${memories.length} memory found for "${query}" — need at least 2 to consolidate.` }] };
+        }
+
+        // 2. LLM synthesis
+        const memoryTexts = memories.map((m: any, i: number) =>
+          `${i + 1}. [${m.type}] ${m.content} (importance: ${displayImportance(m.importance)}/10, created: ${m.created || '?'})`
+        ).join('\n');
+
+        const llmUrl = cfg.llmUrl || 'http://127.0.0.1:18789/v1/chat/completions';
+        const model = cfg.llmModel || 'anthropic/claude-sonnet-4-20250514';
+
+        const synthRes = await fetch(llmUrl, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            model,
+            max_tokens: 1500,
+            messages: [
+              { role: 'system', content: 'Du erstellst eine prägnante Synthese aus mehreren Erinnerungen. Fasse Kernaussagen zusammen, entferne Redundanzen, hebe Widersprüche hervor. Antwort als JSON: {"synthesis": "...", "keyInsights": ["..."], "importance": 1-10}' },
+              { role: 'user', content: `Konsolidiere diese ${memories.length} Erinnerungen zum Thema "${query}":\n\n${memoryTexts}` },
+            ],
+          }),
+        });
+
+        if (!synthRes.ok) throw new Error(`LLM synthesis failed: ${synthRes.status}`);
+        const synthData = await synthRes.json();
+        const synthText = synthData.choices?.[0]?.message?.content?.trim() || '';
+        const cleanedSynth = synthText.replace(/^```json?\n?/m, '').replace(/\n?```$/m, '').trim();
+        const synthesis = JSON.parse(cleanedSynth);
+
+        // 3. Store consolidated memory
+        const storeRes = await bbFetch(cfg, `${base}/memories`, {
+          method: 'POST',
+          body: JSON.stringify({
+            content: synthesis.synthesis,
+            type: 'consolidated',
+            agent,
+            importance: storeImportance(synthesis.importance || 7),
+            tags: ['consolidated', `topic:${query}`, ...(synthesis.keyInsights || []).slice(0, 3)],
+            source: 'plugin:consolidation',
+          }),
+        });
+
+        const consolidatedId = storeRes.id || storeRes._key;
+
+        // 4. Create PART_OF edges from originals to consolidated
+        let edgesCreated = 0;
+        for (const mem of memories) {
+          const memId = mem.id || mem._key;
+          if (memId && consolidatedId) {
+            try {
+              await bbFetch(cfg, `${base}/relate`, {
+                method: 'POST',
+                body: JSON.stringify({ from: memId, to: consolidatedId, type: 'PART_OF', weight: 0.8 }),
+              });
+              edgesCreated++;
+            } catch { /* skip individual edge failures */ }
+          }
+        }
+
+        let response = `Consolidated ${memories.length} memories into [${consolidatedId}]\n`;
+        response += `Synthesis: ${synthesis.synthesis.substring(0, 200)}...\n`;
+        if (synthesis.keyInsights?.length) {
+          response += `Key insights: ${synthesis.keyInsights.join(', ')}\n`;
+        }
+        response += `Edges created: ${edgesCreated} PART_OF links`;
+
+        return { content: [{ type: 'text', text: response }] };
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `MemTap consolidation error: ${err.message}` }], isError: true };
+      }
+    },
+  });
+
+  // ── Tool: memtap_profile ──────────────────────────────────────────────────
+
+  api.registerTool({
+    name: 'memtap_profile',
+    description:
+      'View or refresh the agent memory profile. ' +
+      'Shows a summary of stored knowledge, topic distribution, and memory health.',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['view', 'refresh'],
+          description: 'View the current profile or refresh it from the knowledge graph',
+        },
+      },
+      required: ['action'],
+    },
+    async execute(_id: string, params: { action: 'view' | 'refresh' }) {
+      const cfg = getConfig(api);
+      const base = baseUrl(cfg);
+      const agent = agentId(cfg, api);
+
+      try {
+        if (params.action === 'view') {
+          const data = await bbFetch(cfg, `${base}/profiles?agent=${encodeURIComponent(agent)}`);
+          return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        } else {
+          const data = await bbFetch(cfg, `${base}/profiles`, {
+            method: 'POST',
+            body: JSON.stringify({ agent }),
+          });
+          return { content: [{ type: 'text', text: `Profile refreshed.\n${JSON.stringify(data, null, 2)}` }] };
+        }
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `MemTap profile error: ${err.message}` }], isError: true };
+      }
+    },
+  });
+
+  // ── Tool: memtap_export ───────────────────────────────────────────────────
+
+  api.registerTool({
+    name: 'memtap_export',
+    description:
+      'Export the memory graph in various formats. ' +
+      'Supports JSON (full data), GraphML (for graph visualization tools), and Markdown (human-readable).',
+    parameters: {
+      type: 'object',
+      properties: {
+        format: {
+          type: 'string',
+          enum: ['json', 'graphml', 'markdown'],
+          description: 'Export format',
+        },
+      },
+      required: ['format'],
+    },
+    async execute(_id: string, params: { format: 'json' | 'graphml' | 'markdown' }) {
+      const cfg = getConfig(api);
+      const base = baseUrl(cfg);
+      const agent = agentId(cfg, api);
+
+      try {
+        const url = new URL('/export', base);
+        url.searchParams.set('format', params.format);
+        url.searchParams.set('agent', agent);
+
+        const data = await bbFetch(cfg, url.toString());
+
+        if (params.format === 'json') {
+          const summary = data.memories?.length ?? data.count ?? '?';
+          return { content: [{ type: 'text', text: `Exported ${summary} memories as JSON.\n\n${JSON.stringify(data, null, 2).substring(0, 5000)}` }] };
+        } else if (params.format === 'graphml') {
+          const graphml = typeof data === 'string' ? data : data.graphml || JSON.stringify(data);
+          return { content: [{ type: 'text', text: `GraphML export:\n\n${String(graphml).substring(0, 5000)}` }] };
+        } else {
+          const md = typeof data === 'string' ? data : data.markdown || JSON.stringify(data, null, 2);
+          return { content: [{ type: 'text', text: String(md).substring(0, 5000) }] };
+        }
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `MemTap export error: ${err.message}` }], isError: true };
+      }
+    },
+  });
+
   // ── Tool: memtap_health (Enhanced Neural Monitoring) ────────────────────────
 
   api.registerTool({
     name: 'memtap_health',
     description:
       'Check MemTap server health and get neural system statistics. Actions:\n' +
-      '- health: server health check (ArangoDB version, counts)\n' +
+      '- health: server health check (version, counts)\n' +
       '- stats: detailed statistics (by type, by agent, entity/edge counts)\n' +
       '- neural: neuromimetic system status (working memory, attention, consolidation)\n' +
       '- performance: system performance metrics (cache hits, response times, memory usage)\n' +
@@ -1377,7 +1650,7 @@ export default function register(api: any) {
           case 'health':
             data = await bbFetch(cfg, `${base}/health`);
             const counts = data.counts || {};
-            return { content: [{ type: 'text', text: `MemTap: ${data.status}\nArangoDB: ${data.arango || 'unknown'}\nMemories: ${counts.memories ?? '?'} | Entities: ${counts.entities ?? '?'} | Edges: ${counts.edges ?? '?'}` }] };
+            return { content: [{ type: 'text', text: `MemTap: ${data.status}\nServer: ${data.arango || data.version || 'unknown'}\nMemories: ${counts.memories ?? '?'} | Entities: ${counts.entities ?? '?'} | Edges: ${counts.edges ?? '?'}` }] };
 
           case 'stats':
             data = await bbFetch(cfg, `${base}/stats`);
@@ -1558,26 +1831,54 @@ export default function register(api: any) {
             }
           }
           
+          // Apply instructions filtering (include/exclude patterns)
+          if (cfg.instructions) {
+            if (cfg.instructions.exclude?.length) {
+              memories = memories.filter((m: any) => {
+                const text = (m.content || '').toLowerCase();
+                return !cfg.instructions!.exclude!.some(pat => text.includes(pat.toLowerCase()));
+              });
+            }
+            if (cfg.instructions.include?.length) {
+              // Boost memories matching include patterns
+              memories.forEach((m: any) => {
+                const text = (m.content || '').toLowerCase();
+                if (cfg.instructions!.include!.some(pat => text.includes(pat.toLowerCase()))) {
+                  m.importance = Math.min(1, (m.importance || 0.5) + 0.1);
+                }
+              });
+            }
+          }
+
           if (memories.length > 0) {
-            // Retrieval Practice Strengthening - memories get stronger when accessed
+            // Adaptive Decay: Track access_count and send reinforcement signal
             memories.forEach(async (m: any) => {
               try {
                 if (!useCache && m.id) {
-                  // Update retrieval count and strengthen memory
-                  const strengthBoost = FORGETTING_CURVE.retrievalStrengthening * 
-                                       (context?.attentionLevel === 'focused' ? 1.2 : 1.0);
-                  
-                  // Background update to boost importance (fire and forget) 
+                  const accessCount = (m.accessCount || m.retrievalCount || 0) + 1;
+
+                  // Adaptive reinforcement: frequently accessed memories decay slower
+                  const accessBonus = Math.min(0.3, accessCount * 0.02);
+                  const attentionMultiplier = conversationCtx.attentionLevel === 'flow' ? 1.5 :
+                                             conversationCtx.attentionLevel === 'focused' ? 1.2 : 1.0;
+                  const strengthBoost = (FORGETTING_CURVE.retrievalStrengthening + accessBonus) * attentionMultiplier;
+
+                  // Send reinforcement signal to API (fire and forget)
                   bbFetch(cfg, `${baseUrl(cfg)}/memories/${encodeURIComponent(m.id)}/access`, {
                     method: 'POST',
-                    body: JSON.stringify({ 
+                    body: JSON.stringify({
                       boost: strengthBoost,
-                      retrievalCount: (m.retrievalCount || 0) + 1,
+                      retrievalCount: accessCount,
                       lastAccess: Date.now(),
-                      attentionLevel: context?.attentionLevel || 'unknown'
+                      attentionLevel: conversationCtx.attentionLevel || 'unknown',
+                      reinforcement: {
+                        accessCount,
+                        adaptiveDecayRate: Math.max(0.001, (cfg.decayRate || FORGETTING_CURVE.baseDecayRate) - accessBonus),
+                        emotionalProtection: FORGETTING_CURVE.emotionalProtection * attentionMultiplier
+                      }
                     })
                   }).catch(() => {}); // Silent fail
-                  
+
                   // Update local cache retrieval count
                   if (memoryCache.has(cacheKey)) {
                     const cached = memoryCache.get(cacheKey)!;
@@ -1632,6 +1933,67 @@ ${memoryContext}
             
             injection += instructions;
 
+            // ── Proactive Surfacing ──────────────────────────────────────
+            // Search for thematically related memories NOT already in the recall set
+            try {
+              const existingIds = new Set(memories.map((m: any) => m.id || m._key).filter(Boolean));
+              const proactiveTopics = predictiveTopicBoost(conversationCtx, recallLevel.topics)
+                .filter(t => !recallLevel.topics.includes(t));
+
+              if (proactiveTopics.length > 0) {
+                const proactiveQuery = proactiveTopics.join(' ');
+                const proactiveData = await bbFetch(cfg, `${baseUrl(cfg)}/recall?q=${encodeURIComponent(proactiveQuery)}&limit=5&agent=${currentAgent}`)
+                  .catch(() => ({ results: [] }));
+                const proactiveResults = (proactiveData.results || proactiveData.memories || [])
+                  .filter((m: any) => !existingIds.has(m.id || m._key))
+                  .slice(0, 3);
+
+                if (proactiveResults.length > 0) {
+                  const proactiveContext = proactiveResults.map((m: any, i: number) =>
+                    `${i + 1}. [${m.type}] ${m.content}\n   └─ Importance: ${displayImportance(m.importance)}/10`
+                  ).join('\n\n');
+
+                  injection += `\n\n## 💡 You might also want to know:\n${proactiveContext}\n`;
+
+                  // Track which memories were proactively surfaced for feedback loop
+                  const surfacedIds = proactiveResults.map((m: any) => m.id || m._key).filter(Boolean);
+                  proactiveSurfacedMemories.set(currentAgent, {
+                    memoryIds: surfacedIds,
+                    timestamp: Date.now()
+                  });
+                }
+              }
+            } catch { /* proactive surfacing failed, not critical */ }
+
+            // ── Decision Outcome Context (Learning Loop) ─────────────────
+            // If the message is decision-relevant, load past decision outcomes
+            try {
+              if (/\b(entscheidung|decision|decide|option|alternative|choose|wahl)\b/i.test(message)) {
+                const outcomeData = await bbFetch(cfg, `${baseUrl(cfg)}/recall?q=${encodeURIComponent('decision outcome result')}&limit=10&agent=${currentAgent}&types=outcome,decision`)
+                  .catch(() => ({ results: [] }));
+                const outcomes = (outcomeData.results || outcomeData.memories || [])
+                  .filter((m: any) => m.type === 'outcome' || (m.type === 'decision' && m.tags?.includes('has-outcome')));
+
+                if (outcomes.length > 0) {
+                  // Summarize past decision outcomes
+                  const successCount = outcomes.filter((m: any) => m.tags?.includes('outcome:success')).length;
+                  const failCount = outcomes.filter((m: any) => m.tags?.includes('outcome:failure')).length;
+
+                  let outcomeContext = '\n\n## 📊 Based on past decisions:\n';
+                  if (successCount + failCount > 0) {
+                    outcomeContext += `Track record: ${successCount} successful, ${failCount} unsuccessful outcomes recorded.\n\n`;
+                  }
+                  outcomeContext += outcomes.slice(0, 4).map((m: any, i: number) => {
+                    const success = m.tags?.includes('outcome:success') ? '✅' : m.tags?.includes('outcome:failure') ? '❌' : '📝';
+                    return `${i + 1}. ${success} ${m.content}\n   └─ Importance: ${displayImportance(m.importance)}/10`;
+                  }).join('\n\n');
+
+                  outcomeContext += '\n\n*Consider these past outcomes when advising on the current decision.*\n';
+                  injection += outcomeContext;
+                }
+              }
+            } catch { /* decision outcome loading failed, not critical */ }
+
             // Append to existing system prompt
             event.context.systemPrompt = (event.context.systemPrompt || '') + injection;
             
@@ -1706,22 +2068,31 @@ ${memoryContext}
               
               const finalImportance = (mem.importance ?? 5) * emotionalWeight * contextualWeight;
               
+              // Determine category (from LLM extraction or fallback)
+              const memCategory = MEMORY_CATEGORIES.includes(mem.category as any)
+                ? mem.category
+                : (memoryType === 'preference' ? 'preferences' :
+                   memoryType === 'decision' || memoryType === 'goal' || memoryType === 'task' ? 'project' :
+                   'technical');
+
               // Enhanced memory with neuromimetic features
-              const enhancedMem = {
+              const enhancedMem: Record<string, any> = {
                 content: mem.content,
                 type: memoryType,
                 agent: currentAgent,
                 importance: storeImportance(Math.min(10, finalImportance)),
+                category: memCategory,
                 tags: [
-                  ...(mem.tags || []), 
+                  ...(mem.tags || []),
                   'auto-captured',
                   'neuromimetic',
+                  `category:${memCategory}`,
                   ...(context?.dominantTopic ? [`topic:${context.dominantTopic}`] : []),
                   `engagement:${context?.userEngagement || 'unknown'}`,
                   `attention:${context?.attentionLevel || 'unknown'}`,
                   `emotion:${context?.emotionalContext || 'neutral'}`
                 ],
-                source: 'plugin:neuromimetic-capture-v2.1',
+                source: 'plugin:neuromimetic-capture-v3.0',
                 conversationContext: {
                   dominantTopic: context?.dominantTopic,
                   engagement: context?.userEngagement,
@@ -1778,11 +2149,70 @@ ${memoryContext}
             const profile = getUserProfile(currentAgent);
             profile.successfulRecalls += stored; // Treat captures as successes
             userProfiles.set(currentAgent, profile);
-            
+
             logger.info?.(`[memtap] Auto-captured ${stored} enhanced memories with context`) ??
               console.log(`[memtap] Auto-captured ${stored} enhanced memories with context`);
           }
-          
+
+          // ── Proactive Surfacing Feedback Loop ──────────────────────
+          // Check if the agent's response referenced any proactively surfaced memories
+          try {
+            const surfaced = proactiveSurfacedMemories.get(currentAgent);
+            if (surfaced && (Date.now() - surfaced.timestamp) < 600000) { // within 10min
+              const contentLower = content.toLowerCase();
+              const usedIds: string[] = [];
+
+              for (const memId of surfaced.memoryIds) {
+                // Check if the memory ID or content from proactive surfacing appears in the response
+                if (contentLower.includes(memId.toLowerCase())) {
+                  usedIds.push(memId);
+                }
+              }
+
+              // Also do a fuzzy check: recall proactive memories and see if their content appears
+              if (usedIds.length === 0 && surfaced.memoryIds.length > 0) {
+                for (const memId of surfaced.memoryIds) {
+                  try {
+                    const memData = await bbFetch(cfg, `${baseUrl(cfg)}/memories/${encodeURIComponent(memId)}`);
+                    const memContent = (memData.content || '').toLowerCase();
+                    // Check if key phrases from the memory appear in the response
+                    const keyPhrases = memContent.split(/\s+/).filter((w: string) => w.length > 5).slice(0, 5);
+                    const matchCount = keyPhrases.filter((phrase: string) => contentLower.includes(phrase)).length;
+                    if (matchCount >= 2) {
+                      usedIds.push(memId);
+                    }
+                  } catch { /* skip */ }
+                }
+              }
+
+              // Importance reinforcement for used proactive memories
+              if (usedIds.length > 0) {
+                for (const memId of usedIds) {
+                  try {
+                    await bbFetch(cfg, `${baseUrl(cfg)}/memories/${encodeURIComponent(memId)}/access`, {
+                      method: 'POST',
+                      body: JSON.stringify({
+                        boost: FORGETTING_CURVE.retrievalStrengthening * 1.5, // Extra boost for proactive hit
+                        lastAccess: Date.now(),
+                        attentionLevel: 'proactive-hit',
+                        reinforcement: {
+                          proactiveHit: true,
+                          adaptiveDecayRate: Math.max(0.001, (cfg.decayRate || FORGETTING_CURVE.baseDecayRate) * 0.5)
+                        }
+                      })
+                    });
+                  } catch { /* reinforcement failed, not critical */ }
+                }
+
+                logger.info?.(`[memtap] Proactive surfacing feedback: ${usedIds.length}/${surfaced.memoryIds.length} memories used by agent`) ??
+                  console.log(`[memtap] Proactive surfacing feedback: ${usedIds.length}/${surfaced.memoryIds.length} memories used by agent`);
+              }
+
+              // Clear after processing
+              proactiveSurfacedMemories.delete(currentAgent);
+            }
+          } catch { /* proactive feedback loop failed, not critical */ }
+
         } catch (err: any) {
           logger.warn?.(`[memtap] Auto-capture failed: ${err.message}`) ??
             console.warn(`[memtap] Auto-capture failed: ${err.message}`);
@@ -2811,6 +3241,321 @@ async function neuralMaintenance() {
     },
   });
 
-  logger.info?.('[memtap] Plugin v2.1.0 "The Neuron" registered: 13 tools + 5 neuromimetic hooks') ??
-    console.log('[memtap] Plugin v2.1.0 "The Neuron" registered: 13 tools + 5 neuromimetic hooks');
+  // ── Tool: memtap_outcome (Agent Learning Loop) ──────────────────────────────
+
+  api.registerTool({
+    name: 'memtap_outcome',
+    description:
+      'Record the outcome of a past decision for the learning loop. ' +
+      'Links the outcome to the original decision via a CAUSED_BY edge. ' +
+      'Future decision contexts will automatically surface past outcomes to improve advice quality.',
+    parameters: {
+      type: 'object',
+      properties: {
+        decisionId: { type: 'string', description: 'The ID of the decision this outcome relates to' },
+        outcome: { type: 'string', description: 'Description of what happened as a result of the decision' },
+        success: { type: 'boolean', description: 'Whether the decision led to a successful outcome' },
+        learnings: { type: 'string', description: 'Optional lessons learned from this outcome' },
+      },
+      required: ['decisionId', 'outcome', 'success'],
+    },
+    async execute(_id: string, params: { decisionId: string; outcome: string; success: boolean; learnings?: string }) {
+      const cfg = getConfig(api);
+      const base = baseUrl(cfg);
+      const agent = agentId(cfg, api);
+
+      try {
+        // 1. Verify the decision exists
+        let decisionContent = '';
+        try {
+          const decisionData = await bbFetch(cfg, `${base}/memories/${encodeURIComponent(params.decisionId)}`);
+          decisionContent = decisionData.content || '';
+        } catch {
+          return { content: [{ type: 'text', text: `Decision [${params.decisionId}] not found.` }], isError: true };
+        }
+
+        // 2. Build outcome memory content
+        const outcomeContent = params.learnings
+          ? `Outcome: ${params.outcome} | Learnings: ${params.learnings}`
+          : `Outcome: ${params.outcome}`;
+
+        // 3. Store outcome memory
+        const outcomeImportance = params.success ? 0.6 : 0.8; // Failures are more important to remember
+        const outcomeMem = await bbFetch(cfg, `${base}/memories`, {
+          method: 'POST',
+          body: JSON.stringify({
+            content: outcomeContent,
+            type: 'outcome',
+            agent,
+            importance: outcomeImportance,
+            tags: [
+              'outcome',
+              `outcome:${params.success ? 'success' : 'failure'}`,
+              `decision:${params.decisionId}`,
+              ...(params.learnings ? ['has-learnings'] : []),
+            ],
+            source: 'plugin:learning-loop',
+          }),
+        });
+
+        const outcomeId = outcomeMem.id || outcomeMem._key;
+
+        // 4. Create CAUSED_BY edge from outcome to decision
+        await bbFetch(cfg, `${base}/relate`, {
+          method: 'POST',
+          body: JSON.stringify({
+            from: outcomeId,
+            to: params.decisionId,
+            type: 'CAUSED_BY',
+            weight: 0.9,
+          }),
+        });
+
+        // 5. Tag the original decision as having an outcome
+        try {
+          await bbFetch(cfg, `${base}/memories/${encodeURIComponent(params.decisionId)}/update`, {
+            method: 'POST',
+            body: JSON.stringify({
+              tags: ['has-outcome', `outcome:${params.success ? 'success' : 'failure'}`],
+            }),
+          });
+        } catch { /* tagging failed, not critical */ }
+
+        const icon = params.success ? '✅' : '❌';
+        let response = `${icon} Outcome recorded [${outcomeId}] for decision [${params.decisionId}]\n`;
+        response += `  Result: ${params.success ? 'Success' : 'Failure'}\n`;
+        response += `  Edge: [${outcomeId}] -[CAUSED_BY]-> [${params.decisionId}]`;
+        if (params.learnings) response += `\n  Learnings: ${params.learnings}`;
+
+        return { content: [{ type: 'text', text: response }] };
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `MemTap outcome error: ${err.message}` }], isError: true };
+      }
+    },
+  });
+
+  // ── Tool: memtap_infer (Inference Engine) ─────────────────────────────────
+
+  api.registerTool({
+    name: 'memtap_infer',
+    description:
+      'Inference engine: traverses the knowledge graph (2-3 hops) to discover implicit relationships ' +
+      'and hidden knowledge not explicitly stored. Uses LLM reasoning to draw conclusions from connected facts. ' +
+      'Stores inferences as new memories with confidence decay (inferred memories decay 2x faster).',
+    parameters: {
+      type: 'object',
+      properties: {
+        depth: { type: 'number', description: 'Graph traversal depth in hops (default 2, max 3)' },
+        limit: { type: 'number', description: 'Max number of inferences to generate (default 3)' },
+      },
+    },
+    async execute(_id: string, params: { depth?: number; limit?: number }) {
+      const cfg = getConfig(api);
+      const base = baseUrl(cfg);
+      const agent = agentId(cfg, api);
+      const depth = Math.min(3, params.depth ?? 2);
+      const limit = Math.min(5, params.limit ?? 3);
+
+      try {
+        // 1. Get graph overview to find highly connected nodes as starting points
+        const overviewData = await bbFetch(cfg, `${base}/graph/overview`).catch(() => ({}));
+        const topNodes = (overviewData.topConnected || overviewData.hubs || []).slice(0, 5);
+
+        // 2. If no top nodes from overview, use recent important memories as seeds
+        let seedIds: string[] = topNodes.map((n: any) => n.id || n._key).filter(Boolean);
+        if (seedIds.length === 0) {
+          const recallData = await bbFetch(cfg, `${base}/recall?q=important&limit=5&agent=${agent}`);
+          seedIds = (recallData.results || recallData.memories || [])
+            .map((m: any) => m.id || m._key).filter(Boolean);
+        }
+
+        if (seedIds.length === 0) {
+          return { content: [{ type: 'text', text: 'Not enough memories in the graph to run inference. Store more memories first.' }] };
+        }
+
+        // 3. Traverse graph from each seed to collect connected memories
+        const allTraversals: any[] = [];
+        const visitedMemories = new Map<string, any>();
+
+        for (const seedId of seedIds.slice(0, 3)) {
+          try {
+            const traverseUrl = new URL('/graph/traverse', base);
+            traverseUrl.searchParams.set('start', seedId);
+            traverseUrl.searchParams.set('depth', String(depth));
+            const traverseData = await bbFetch(cfg, traverseUrl.toString());
+
+            const nodes = traverseData.nodes || traverseData.results || [];
+            for (const node of nodes) {
+              const nodeId = node.id || node._key;
+              if (nodeId && !visitedMemories.has(nodeId)) {
+                visitedMemories.set(nodeId, node);
+              }
+            }
+
+            allTraversals.push({
+              seed: seedId,
+              nodes: nodes.length,
+              edges: (traverseData.edges || []).length,
+            });
+          } catch { /* skip individual traversal failures */ }
+        }
+
+        if (visitedMemories.size < 3) {
+          return { content: [{ type: 'text', text: `Only ${visitedMemories.size} connected memories found. Need at least 3 for meaningful inference.` }] };
+        }
+
+        // 4. Build context for LLM inference
+        const memoryTexts = Array.from(visitedMemories.values())
+          .slice(0, 20)
+          .map((m: any, i: number) => {
+            const mType = m.type || 'unknown';
+            const mContent = m.content || m.summary || '';
+            return `${i + 1}. [${mType}] ${mContent}`;
+          }).join('\n');
+
+        // 5. Use LLM to find implicit connections and draw inferences
+        const llmUrl = cfg.llmUrl || 'http://127.0.0.1:18789/v1/chat/completions';
+        const model = cfg.llmModel || 'anthropic/claude-sonnet-4-20250514';
+
+        const inferRes = await fetch(llmUrl, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            model,
+            max_tokens: 2000,
+            messages: [
+              {
+                role: 'system',
+                content: `Du bist ein Inference-Engine für einen Wissensgraphen. Analysiere die folgenden verbundenen Fakten und finde IMPLIZITE Schlussfolgerungen die nicht direkt gespeichert sind.
+
+Regeln:
+- Nur nicht-triviale, wertvolle Schlüsse
+- Jeder Schluss muss auf mindestens 2 konkreten Fakten basieren
+- Gib die IDs der Quell-Memories an (Nummern aus der Liste)
+- Confidence 0-1: wie sicher ist der Schluss?
+
+Antwort als JSON-Array (NUR das Array):
+[
+  {
+    "inference": "Der Schluss in einem Satz",
+    "basedOn": [1, 3, 7],
+    "confidence": 0.7,
+    "category": "pattern|prediction|connection|risk"
+  }
+]
+
+Wenn keine sinnvollen Schlüsse möglich: []`
+              },
+              {
+                role: 'user',
+                content: `Welche impliziten Schlüsse kann man aus diesen ${visitedMemories.size} verbundenen Fakten ziehen?\n\n${memoryTexts}`
+              },
+            ],
+          }),
+        });
+
+        if (!inferRes.ok) throw new Error(`LLM inference failed: ${inferRes.status}`);
+        const inferData = await inferRes.json();
+        const inferText = inferData.choices?.[0]?.message?.content?.trim() || '[]';
+        const cleanedInfer = inferText.replace(/^```json?\n?/m, '').replace(/\n?```$/m, '').trim();
+
+        let inferences: any[];
+        try {
+          inferences = JSON.parse(cleanedInfer);
+          if (!Array.isArray(inferences)) inferences = [];
+        } catch {
+          inferences = [];
+        }
+
+        if (inferences.length === 0) {
+          return { content: [{ type: 'text', text: `Traversed ${visitedMemories.size} memories across ${allTraversals.length} paths but no meaningful inferences could be drawn.` }] };
+        }
+
+        // 6. Store inferences as memories with lower importance and 2x decay
+        const storedInferences: string[] = [];
+        const memoryArray = Array.from(visitedMemories.values());
+
+        for (const inf of inferences.slice(0, limit)) {
+          try {
+            // Calculate importance based on confidence (lower than explicit memories)
+            const inferImportance = Math.max(0.2, Math.min(0.6, (inf.confidence || 0.5) * 0.7));
+
+            const inferMem = await bbFetch(cfg, `${base}/memories`, {
+              method: 'POST',
+              body: JSON.stringify({
+                content: inf.inference,
+                type: 'inferred',
+                agent,
+                importance: inferImportance,
+                tags: [
+                  'inferred',
+                  `inference:${inf.category || 'connection'}`,
+                  `confidence:${Math.round((inf.confidence || 0.5) * 100)}`,
+                  'fast-decay', // Signal to server that this decays 2x faster
+                ],
+                source: 'plugin:inference-engine',
+                metadata: {
+                  confidence: inf.confidence || 0.5,
+                  decayMultiplier: 2.0, // Inferred memories decay 2x faster
+                  basedOnCount: (inf.basedOn || []).length,
+                  inferenceCategory: inf.category || 'connection',
+                },
+              }),
+            });
+
+            const inferenceId = inferMem.id || inferMem._key;
+
+            // 7. Create PART_OF edges (inference chain) from source memories to inference
+            const basedOnIndices = (inf.basedOn || []).map((n: number) => n - 1);
+            let edgesCreated = 0;
+
+            for (const idx of basedOnIndices) {
+              if (idx >= 0 && idx < memoryArray.length) {
+                const sourceId = memoryArray[idx].id || memoryArray[idx]._key;
+                if (sourceId && inferenceId) {
+                  try {
+                    await bbFetch(cfg, `${base}/relate`, {
+                      method: 'POST',
+                      body: JSON.stringify({
+                        from: sourceId,
+                        to: inferenceId,
+                        type: 'PART_OF',
+                        weight: inf.confidence || 0.5,
+                      }),
+                    });
+                    edgesCreated++;
+                  } catch { /* skip edge failures */ }
+                }
+              }
+            }
+
+            storedInferences.push(
+              `[${inferenceId}] ${inf.inference}\n   ` +
+              `Confidence: ${Math.round((inf.confidence || 0.5) * 100)}% | ` +
+              `Category: ${inf.category || 'connection'} | ` +
+              `Based on: ${(inf.basedOn || []).length} memories | ` +
+              `Edges: ${edgesCreated} PART_OF links`
+            );
+          } catch { /* skip individual inference storage failures */ }
+        }
+
+        let output = `Inference Engine Results\n`;
+        output += `Traversed: ${visitedMemories.size} memories, ${allTraversals.length} paths, depth ${depth}\n\n`;
+
+        if (storedInferences.length > 0) {
+          output += `Inferences discovered and stored (decay: 2x faster):\n\n`;
+          output += storedInferences.map((s, i) => `${i + 1}. ${s}`).join('\n\n');
+        } else {
+          output += 'Inferences were generated but could not be stored.';
+        }
+
+        return { content: [{ type: 'text', text: output }] };
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `MemTap inference error: ${err.message}` }], isError: true };
+      }
+    },
+  });
+
+  logger.info?.('[memtap] Plugin v3.1.0 "The Oracle" registered: 18 tools + 5 neuromimetic hooks') ??
+    console.log('[memtap] Plugin v3.1.0 "The Oracle" registered: 18 tools + 5 neuromimetic hooks');
 }

package/openclaw.plugin.json

@@ -2,8 +2,8 @@
   "id": "memtap",
   "name": "MemTap",
   "kind": "memory",
-  "version": "2.1.0",
-  "description": "Graph-based long-term memory for OpenClaw agents — semantic recall, GraphRAG, entity management, decision tracking, neural auto-capture, and anomaly detection. Powered by ArangoDB.",
+  "version": "3.1.0",
+  "description": "Graph-based long-term memory for OpenClaw agents — semantic recall, GraphRAG, entity management, decision tracking, neural auto-capture, anomaly detection, consolidation, profiles, and adaptive decay.",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -60,6 +60,22 @@
       "decayRate": {
         "type": "number",
         "description": "Memory importance decay rate per day (default: 0.005)"
+      },
+      "instructions": {
+        "type": "object",
+        "description": "Content filtering instructions for memory recall and capture",
+        "properties": {
+          "include": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Patterns to prioritize in recall (boost matching memories)"
+          },
+          "exclude": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Patterns to exclude from recall results"
+          }
+        }
       }
     }
   },
@@ -110,6 +126,10 @@
     "decayRate": {
       "label": "Memory Decay Rate",
       "placeholder": "0.005"
+    },
+    "instructions": {
+      "label": "Content Filter Instructions",
+      "helpText": "Include/exclude patterns for memory recall filtering"
     }
   }
 }

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "memtap",
-  "version": "2.1.0",
-  "description": "MemTap — Graph-based long-term memory plugin for OpenClaw agents. ArangoDB-backed knowledge graph with semantic recall, GraphRAG, entity management, decision tracking, and auto-capture.",
+  "version": "3.1.0",
+  "description": "MemTap — Graph-based long-term memory plugin for OpenClaw agents. Knowledge graph with semantic recall, GraphRAG, entity management, decision tracking, and auto-capture.",
   "keywords": [
     "openclaw",
     "openclaw-plugin",
     "plugin",
     "memory",
     "knowledge-graph",
-    "arangodb",
     "graphrag",
     "ai-agents",
     "long-term-memory",
@@ -19,10 +18,11 @@
   "homepage": "https://memtap.ai",
   "repository": {
     "type": "git",
-    "url": "https://github.com/memtap/openclaw-plugin.git"
+    "url": "https://github.com/psifactory/memtap.git",
+    "directory": "plugin"
   },
   "bugs": {
-    "url": "https://github.com/memtap/openclaw-plugin/issues"
+    "url": "https://github.com/psifactory/memtap/issues"
   },
   "openclaw": {
     "extensions": [