memtap 2.1.0

package/index.ts

@@ -0,0 +1,2816 @@
+/**
+ * MemTap — Graph-based Long-Term Memory Plugin for OpenClaw
+ * v2.1.0 "The Neuron" — Neuromimetic Memory System with Human-like Cognition
+ *
+ * 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
+ *
+ * Hooks:
+ *  - preMessage         — neuromimetic tiered recall with working memory simulation
+ *  - message_completed  — attention-gated encoding with emotional weighting
+ *  - agent:bootstrap    — inject memory bulletin at session start
+ *  - periodic           — dream-mode consolidation and neural maintenance
+ *  - session_end        — performance monitoring and neural analytics
+ */
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+interface MemTapConfig {
+  serverUrl?: string;
+  apiKey?: string;
+  agentId?: string;
+  autoCapture?: boolean;
+  bulletinOnBoot?: boolean;
+  bulletinTopics?: string[];
+  llmUrl?: string;
+  llmModel?: string;
+  embeddingUrl?: string;
+  embeddingModel?: string;
+  embeddingApiKey?: string;
+  decayRate?: number;
+}
+
+function getConfig(api: any): MemTapConfig {
+  const entries = api.config?.plugins?.entries ?? {};
+  return entries.memtap?.config ?? {};
+}
+
+function baseUrl(cfg: MemTapConfig): string {
+  return (cfg.serverUrl || 'https://api.memtap.ai').replace(/\/$/, '');
+}
+
+function agentId(cfg: MemTapConfig, api: any): string {
+  return cfg.agentId || api.config?.agents?.defaults?.id || 'main';
+}
+
+async function bbFetch(cfg: MemTapConfig, url: string, opts: RequestInit = {}): Promise<any> {
+  const headers: any = { 'Content-Type': 'application/json', ...(opts.headers || {}) };
+  
+  // Add API key authentication if available
+  if (cfg.apiKey) {
+    headers['Authorization'] = `Bearer ${cfg.apiKey}`;
+  }
+  
+  const res = await fetch(url, {
+    ...opts,
+    headers,
+  });
+  
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    if (res.status === 401) {
+      throw new Error('MemTap authentication failed. Please check your API key.');
+    }
+    throw new Error(`MemTap API ${res.status}: ${text}`);
+  }
+  return res.json();
+}
+
+/** Server stores importance as 0-1, we display 1-10 to users */
+function displayImportance(serverValue: number): number {
+  return Math.round(serverValue * 10) || 1;
+}
+
+/** Users provide importance as 1-10, we store as 0-1 */
+function storeImportance(userValue: number): number {
+  return Math.min(1, Math.max(0, userValue / 10));
+}
+
+// ── Memory types ─────────────────────────────────────────────────────────────
+
+const MEMORY_TYPES = ['fact', 'preference', 'decision', 'identity', 'event', 'observation', 'goal', 'task'] as const;
+
+// ── Neuromimetic Memory System (v2.1 "The Neuron") ──────────────────────────
+
+interface RecallLevel {
+  intensity: number; // 0 = no recall, 1 = light, 2 = standard, 3 = deep
+  topics: string[];
+  confidence: number; // 0-1, how sure we are about this classification
+  reasoning: string;
+}
+
+interface ConversationContext {
+  recentTopics: string[];
+  memoryQueryCount: number;
+  lastMemoryAccess?: number;
+  dominantTopic?: string;
+  userEngagement: 'low' | 'medium' | 'high';
+  attentionLevel: 'focused' | 'distracted' | 'flow'; // Determines encoding strength
+  emotionalContext: 'positive' | 'neutral' | 'negative' | 'excited';
+}
+
+interface UserProfile {
+  recallSensitivity: 'low' | 'medium' | 'high';
+  preferredMemoryTypes: string[];
+  averageQueryComplexity: number;
+  lastActive: number;
+  totalQueries: number;
+  successfulRecalls: number;
+  sleepCycles: number; // For consolidation tracking
+  attentionPatterns: Array<{ timestamp: number; level: string }>;
+}
+
+interface WorkingMemory {
+  currentFocus: string[];           // 5-7 most important current topics
+  activeMemories: any[];            // Pre-loaded memories for instant access
+  attentionSpotlight: string;       // Primary focus topic
+  cognitiveLoad: number;            // 0-1, affects new memory encoding
+  lastUpdate: number;
+}
+
+interface EpisodicMemory {
+  event: string;
+  timestamp: number;
+  location: 'telegram' | 'discord' | 'local' | 'unknown';
+  participants: string[];
+  emotionalIntensity: number;       // 0-1, affects retention
+  contextualCues: string[];         // For context-dependent retrieval
+  consolidationScore: number;       // How well consolidated this memory is
+}
+
+interface MemoryChunk {
+  id: string;
+  relatedMemories: string[];
+  abstractConcept: string;
+  strength: number;                 // How often accessed together
+  lastActivation: number;
+}
+
+// Emotional weighting for different memory types
+const EMOTIONAL_WEIGHTS = {
+  'decision': 1.5,     // Decisions are crucial
+  'problem': 1.3,      // Problems stick in memory  
+  'success': 1.2,      // We remember wins
+  'failure': 1.4,      // We really remember losses
+  'event': 1.1,        // Events have mild boost
+  'fact': 1.0,         // Baseline
+  'preference': 0.9,   // Less emotionally salient
+  'observation': 0.8,  // Often forgotten
+  'routine': 0.7       // Quickly forgotten
+};
+
+// Forgetting curve parameters (Ebbinghaus + emotional modulation)
+const FORGETTING_CURVE = {
+  baseDecayRate: 0.01,     // Base daily decay
+  emotionalProtection: 0.3, // How much emotion protects from decay
+  retrievalStrengthening: 0.15, // Boost from each retrieval
+  consolidationBonus: 0.1   // Bonus from sleep/consolidation
+};
+
+// Global state for neuromimetic features
+const conversationState = new Map<string, ConversationContext>();
+const userProfiles = new Map<string, UserProfile>();
+const workingMemoryState = new Map<string, WorkingMemory>();
+const episodicMemories = new Map<string, EpisodicMemory[]>();
+const memoryChunks = new Map<string, MemoryChunk[]>();
+const memoryCache = new Map<string, { data: any[]; timestamp: number; query: string; retrievalCount: number }>();
+
+// Attention tracking for encoding decisions
+let attentionHistory: Array<{ timestamp: number; agent: string; level: string; trigger: string }> = [];
+
+// ── Neuromimetic Functions ──────────────────────────────────────────────────
+
+function updateWorkingMemory(agentId: string, topics: string[], memories: any[] = []): WorkingMemory {
+  const existing = workingMemoryState.get(agentId) || {
+    currentFocus: [],
+    activeMemories: [],
+    attentionSpotlight: '',
+    cognitiveLoad: 0,
+    lastUpdate: 0
+  };
+
+  // Update focus (maintain 5-7 items max, like human working memory)
+  existing.currentFocus = [...existing.currentFocus, ...topics]
+    .slice(-7) // Keep only recent 7 items
+    .filter((item, index, arr) => arr.indexOf(item) === index); // dedupe
+
+  // Update active memories (pre-loaded for instant access)
+  existing.activeMemories = memories.slice(0, 5); // Max 5 active
+
+  // Determine attention spotlight (most frequent recent topic)
+  const topicCounts = existing.currentFocus.reduce((acc, topic) => {
+    acc[topic] = (acc[topic] || 0) + 1;
+    return acc;
+  }, {} as Record<string, number>);
+  
+  existing.attentionSpotlight = Object.entries(topicCounts)
+    .sort(([,a], [,b]) => b - a)[0]?.[0] || '';
+
+  // Calculate cognitive load (affects new encoding)
+  existing.cognitiveLoad = Math.min(1, existing.currentFocus.length / 7);
+  existing.lastUpdate = Date.now();
+
+  workingMemoryState.set(agentId, existing);
+  return existing;
+}
+
+function analyzeAttentionLevel(message: string, context?: ConversationContext): string {
+  const msg = message.toLowerCase();
+  
+  // High attention triggers
+  if (/\b(wichtig|urgent|critical|problem|fehler|error|entscheidung|decision)\b/i.test(msg)) {
+    return 'focused';
+  }
+  
+  // Flow state indicators (long, detailed messages)
+  if (message.length > 200 && /\b(projekt|entwicklung|implementierung|strategie)\b/i.test(msg)) {
+    return 'flow';
+  }
+  
+  // Distracted indicators
+  if (message.length < 20 || /\b(btw|übrigens|kurz|quick|mal eben)\b/i.test(msg)) {
+    return 'distracted';
+  }
+  
+  return 'focused'; // Default to focused
+}
+
+function calculateEmotionalContext(message: string): string {
+  const msg = message.toLowerCase();
+  
+  // Positive indicators
+  if (/\b(super|great|toll|perfekt|excellent|love|awesome|gut gelöst)\b/i.test(msg)) {
+    return 'positive';
+  }
+  
+  // Excited indicators  
+  if (/[!]{2,}|🚀|🎉|💯|genial|krass|unglaublich/i.test(message)) {
+    return 'excited';
+  }
+  
+  // Negative indicators
+  if (/\b(problem|fehler|bug|broken|schlecht|terrible|failed|shit)\b/i.test(msg)) {
+    return 'negative';
+  }
+  
+  return 'neutral';
+}
+
+function shouldEncodeMemory(content: string, attentionLevel: string, emotionalContext: string, cognitiveLoad: number): boolean {
+  // Attention-gated encoding - like real brain filtering
+  
+  let encodeProbability = 0.5; // Base probability
+  
+  // Attention modulation
+  if (attentionLevel === 'focused') encodeProbability += 0.3;
+  else if (attentionLevel === 'flow') encodeProbability += 0.4;
+  else if (attentionLevel === 'distracted') encodeProbability -= 0.3;
+  
+  // Emotional modulation (emotional events are better encoded)
+  if (emotionalContext === 'excited') encodeProbability += 0.3;
+  else if (emotionalContext === 'positive') encodeProbability += 0.1;
+  else if (emotionalContext === 'negative') encodeProbability += 0.2; // We remember bad things
+  
+  // Cognitive load (harder to encode when overloaded)
+  encodeProbability -= cognitiveLoad * 0.2;
+  
+  // Content length and importance
+  if (content.length > 100) encodeProbability += 0.1;
+  if (/\b(entscheidung|decision|wichtig|important)\b/i.test(content)) encodeProbability += 0.2;
+  
+  return Math.random() < Math.min(1, Math.max(0, encodeProbability));
+}
+
+function createEpisodicMemory(agentId: string, content: string, context: ConversationContext): EpisodicMemory {
+  // Extract contextual information for episodic encoding
+  const episodic: EpisodicMemory = {
+    event: content,
+    timestamp: Date.now(),
+    location: 'telegram', // Could be extracted from context
+    participants: [agentId], // Could include other participants
+    emotionalIntensity: context.emotionalContext === 'excited' ? 0.8 :
+                       context.emotionalContext === 'positive' ? 0.6 :
+                       context.emotionalContext === 'negative' ? 0.7 : 0.4,
+    contextualCues: context.recentTopics.slice(-3), // Last 3 topics as retrieval cues
+    consolidationScore: 0.1 // Start low, increases with sleep cycles
+  };
+  
+  return episodic;
+}
+
+function updateMemoryChunks(agentId: string, relatedMemories: any[]) {
+  if (relatedMemories.length < 2) return; // Need at least 2 memories to chunk
+  
+  const chunks = memoryChunks.get(agentId) || [];
+  const memoryIds = relatedMemories.map(m => m.id || m._key).filter(Boolean);
+  
+  if (memoryIds.length < 2) return;
+  
+  // Find existing chunk or create new one
+  let chunk = chunks.find(c => 
+    c.relatedMemories.some(id => memoryIds.includes(id))
+  );
+  
+  if (chunk) {
+    // Strengthen existing chunk
+    chunk.relatedMemories = [...new Set([...chunk.relatedMemories, ...memoryIds])];
+    chunk.strength += 0.1;
+    chunk.lastActivation = Date.now();
+  } else {
+    // Create new chunk
+    const abstractConcept = extractAbstractConcept(relatedMemories);
+    chunk = {
+      id: `chunk_${Date.now()}`,
+      relatedMemories: memoryIds,
+      abstractConcept,
+      strength: 1.0,
+      lastActivation: Date.now()
+    };
+    chunks.push(chunk);
+  }
+  
+  memoryChunks.set(agentId, chunks);
+}
+
+function extractAbstractConcept(memories: any[]): string {
+  // Simple concept extraction based on common words
+  const allContent = memories.map(m => m.content || '').join(' ').toLowerCase();
+  
+  if (/memtap.*development|plugin.*code/i.test(allContent)) return 'MemTap Development';
+  if (/business.*model|pricing.*strategy/i.test(allContent)) return 'Business Strategy';
+  if (/server.*deploy|infrastructure/i.test(allContent)) return 'Infrastructure';
+  if (/problem.*solution|debug|fix/i.test(allContent)) return 'Problem Solving';
+  
+  return 'General Knowledge';
+}
+
+function analyzeConversationContext(agentId: string, message: string): ConversationContext {
+  const existing = conversationState.get(agentId) || {
+    recentTopics: [],
+    memoryQueryCount: 0,
+    userEngagement: 'medium',
+    attentionLevel: 'focused',
+    emotionalContext: 'neutral'
+  };
+
+  // Extract topics from current message
+  const topics: string[] = [];
+  const msg = message.toLowerCase();
+  
+  if (/memtap/i.test(msg)) topics.push('memtap');
+  if (/business|pricing|model/i.test(msg)) topics.push('business');
+  if (/server|deployment|vps|infrastructure/i.test(msg)) topics.push('infrastructure');
+  if (/plugin|entwicklung|development|code/i.test(msg)) topics.push('development');
+  if (/entscheidung|decision/i.test(msg)) topics.push('decisions');
+  if (/problem|issue|fehler|bug|error/i.test(msg)) topics.push('problems');
+  
+  // Update recent topics (sliding window of 5)
+  existing.recentTopics = [...existing.recentTopics, ...topics].slice(-5);
+  
+  // Analyze attention and emotional state
+  existing.attentionLevel = analyzeAttentionLevel(message, existing) as any;
+  existing.emotionalContext = calculateEmotionalContext(message) as any;
+  
+  // Track attention patterns for user profile
+  attentionHistory.push({
+    timestamp: Date.now(),
+    agent: agentId,
+    level: existing.attentionLevel,
+    trigger: message.substring(0, 50)
+  });
+  
+  // Limit attention history size
+  if (attentionHistory.length > 1000) {
+    attentionHistory = attentionHistory.slice(-500);
+  }
+  
+  // Count memory-related queries
+  if (isMemoryQuery(message)) {
+    existing.memoryQueryCount++;
+    existing.lastMemoryAccess = Date.now();
+  }
+  
+  // Determine dominant topic
+  const topicCounts = existing.recentTopics.reduce((acc, topic) => {
+    acc[topic] = (acc[topic] || 0) + 1;
+    return acc;
+  }, {} as Record<string, number>);
+  
+  existing.dominantTopic = Object.entries(topicCounts)
+    .sort(([,a], [,b]) => b - a)[0]?.[0];
+  
+  // Calculate engagement based on frequency, complexity, and attention
+  const queryFreq = existing.memoryQueryCount;
+  const attentionBoost = existing.attentionLevel === 'flow' ? 1 : 
+                        existing.attentionLevel === 'focused' ? 0.5 : 0;
+  const adjustedFreq = queryFreq + attentionBoost;
+  
+  existing.userEngagement = adjustedFreq > 3 ? 'high' : adjustedFreq > 1 ? 'medium' : 'low';
+  
+  conversationState.set(agentId, existing);
+  return existing;
+}
+
+function isMemoryQuery(message: string): boolean {
+  const memoryKeywords = [
+    /\b(erinnerst|remember|recall|was war|what was|früher|previously)\b/i,
+    /\b(entscheidung|decision|status|projekt|project)\b/i,
+    /\b(wie haben wir|how did we|wo stehen|where are)\b/i
+  ];
+  return memoryKeywords.some(kw => kw.test(message));
+}
+
+function getUserProfile(agentId: string): UserProfile {
+  return userProfiles.get(agentId) || {
+    recallSensitivity: 'medium',
+    preferredMemoryTypes: ['fact', 'decision', 'event'],
+    averageQueryComplexity: 2,
+    lastActive: Date.now(),
+    totalQueries: 0,
+    successfulRecalls: 0
+  };
+}
+
+function updateUserProfile(agentId: string, queryComplexity: number, successful: boolean) {
+  const profile = getUserProfile(agentId);
+  profile.totalQueries++;
+  profile.lastActive = Date.now();
+  profile.averageQueryComplexity = (profile.averageQueryComplexity + queryComplexity) / 2;
+  if (successful) profile.successfulRecalls++;
+  userProfiles.set(agentId, profile);
+}
+
+function predictiveTopicBoost(context: ConversationContext, baseTopics: string[]): string[] {
+  const enhanced = [...baseTopics];
+  
+  // If we're in a topic-focused conversation, boost related topics
+  if (context.dominantTopic === 'memtap' && context.recentTopics.length > 2) {
+    enhanced.push('development', 'business', 'infrastructure');
+  }
+  
+  if (context.dominantTopic === 'problems' && context.recentTopics.includes('memtap')) {
+    enhanced.push('debugging', 'server issues', 'deployment');
+  }
+  
+  return [...new Set(enhanced)]; // dedupe
+}
+
+function analyzeRecallLevel(message: string, agentId: string): RecallLevel {
+  const msg = message.toLowerCase();
+  const context = analyzeConversationContext(agentId, message);
+  const userProfile = getUserProfile(agentId);
+  
+  // Base keyword analysis
+  let intensity = 0;
+  let confidence = 0.5;
+  let reasoning = '';
+  
+  // Deep recall triggers (level 3)
+  const deepTriggers = [
+    /\b(project status|projektstand|wo stehen wir|complete overview)\b/i,
+    /\b(alle entscheidungen|all decisions|full context|comprehensive)\b/i,
+    /\b(memtap.*status|memtap.*fortschritt|memtap.*stand)\b/i,
+    /\b(business.*model|geschäfts.*modell|pricing.*strategy)\b/i
+  ];
+  
+  // Standard recall triggers (level 2)
+  const standardTriggers = [
+    /\b(erinnerst du|remember|recall)\b/i,
+    /\b(entscheidung|decision|beschlossen|agreed)\b/i,
+    /\b(was war|what was|wie haben wir|how did we)\b/i,
+    /\b(letzte mal|last time|früher|previously)\b/i,
+    /\b(wer ist|who is|wer war|who was)\b/i
+  ];
+  
+  // Light recall triggers (level 1)
+  const lightTriggers = [
+    /\b(status|update|aktuell|current)\b/i,
+    /\b(problem|issue|fehler|bug)\b/i,
+    /\b(wie geht|how.*going|weiter|next)\b/i,
+    /\b(info|information|details|erklärung)\b/i
+  ];
+  
+  // Base classification
+  if (deepTriggers.some(t => t.test(msg))) {
+    intensity = 3;
+    confidence = 0.9;
+    reasoning = 'Deep trigger detected';
+  } else if (standardTriggers.some(t => t.test(msg))) {
+    intensity = 2;
+    confidence = 0.8;
+    reasoning = 'Standard memory query';
+  } else if (lightTriggers.some(t => t.test(msg))) {
+    intensity = 1;
+    confidence = 0.6;
+    reasoning = 'Light context hint';
+  }
+  
+  // Conversation context adjustments
+  if (context.dominantTopic === 'memtap' && context.recentTopics.length > 2) {
+    intensity = Math.min(3, intensity + 1);
+    confidence += 0.2;
+    reasoning += ' + MemTap conversation context';
+  }
+  
+  if (context.memoryQueryCount > 2 && intensity > 0) {
+    intensity = Math.min(3, intensity + 1);
+    confidence += 0.1;
+    reasoning += ' + frequent memory queries';
+  }
+  
+  // User profile adjustments
+  if (userProfile.recallSensitivity === 'high' && intensity > 0) {
+    intensity = Math.min(3, intensity + 1);
+    reasoning += ' + high user sensitivity';
+  } else if (userProfile.recallSensitivity === 'low' && intensity > 0) {
+    intensity = Math.max(1, intensity - 1);
+    reasoning += ' + low user sensitivity';
+  }
+  
+  // Recent successful recalls boost confidence
+  if (userProfile.successfulRecalls > userProfile.totalQueries * 0.7) {
+    confidence += 0.1;
+  }
+  
+  // Topic extraction with predictive enhancement
+  const baseTopics: string[] = [];
+  if (/memtap/i.test(msg)) baseTopics.push('MemTap');
+  if (/business|pricing|model/i.test(msg)) baseTopics.push('business model');
+  if (/server|deployment|vps/i.test(msg)) baseTopics.push('infrastructure');
+  if (/plugin|entwicklung|development/i.test(msg)) baseTopics.push('development');
+  if (/entscheidung|decision/i.test(msg)) baseTopics.push('decisions');
+  
+  const topics = predictiveTopicBoost(context, baseTopics);
+  
+  // Clamp confidence
+  confidence = Math.min(1, Math.max(0, confidence));
+  
+  return { 
+    intensity, 
+    topics: topics.length ? topics : ['recent activity'], 
+    confidence,
+    reasoning: reasoning || 'no specific triggers'
+  };
+}
+
+// ── LLM Memory Extraction ────────────────────────────────────────────────────
+
+const EXTRACTION_PROMPT = `Du bist ein Memory-Extractor. Analysiere die folgende Assistenten-Nachricht und extrahiere Informationen die langfristig wissenswert sind.
+
+Regeln:
+- Nur NEUE Fakten, Entscheidungen, Präferenzen, Events extrahieren
+- Keine trivialen Dinge ("ich hab gesucht", "hier ist das Ergebnis")
+- Keine Wiederholungen von bereits bekanntem Wissen
+- Technische Konfigurationen, Entscheidungen, Personen-Info = wichtig
+- Smalltalk, Statusmeldungen, Zwischenschritte = unwichtig
+- Wenn NICHTS wissenswert ist: leeres Array zurückgeben
+
+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"]
+  }
+]
+
+Wenn nichts extrahiert werden soll: []`;
+
+async function llmExtract(cfg: MemTapConfig, content: string): Promise<any[]> {
+  const llmUrl = cfg.llmUrl || 'http://127.0.0.1:18789/v1/chat/completions';
+  const model = cfg.llmModel || 'anthropic/claude-sonnet-4-20250514';
+
+  const res = await fetch(llmUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      model,
+      max_tokens: 1000,
+      messages: [
+        { role: 'system', content: EXTRACTION_PROMPT },
+        { role: 'user', content: `Assistenten-Nachricht:\n\n${content}` },
+      ],
+    }),
+  });
+
+  if (!res.ok) throw new Error(`LLM ${res.status}`);
+  const data = await res.json();
+  const text = data.choices?.[0]?.message?.content?.trim() || '[]';
+
+  const cleaned = text.replace(/^```json?\n?/m, '').replace(/\n?```$/m, '').trim();
+
+  try {
+    const parsed = JSON.parse(cleaned);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+// ── Plugin Entry ─────────────────────────────────────────────────────────────
+
+export default function register(api: any) {
+  const logger = api.logger ?? console;
+
+  // ── Tool: memtap_recall ──────────────────────────────────────────────────
+
+  api.registerTool({
+    name: 'memtap_recall',
+    description:
+      'Search the MemTap knowledge graph for relevant memories. ' +
+      'Returns semantically matched memories with entities and relationships. ' +
+      'Use this before answering questions about prior decisions, people, projects, or preferences.',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Natural language search query' },
+        types: {
+          type: 'array',
+          items: { type: 'string', enum: MEMORY_TYPES },
+          description: 'Filter by memory types (optional)',
+        },
+        limit: { type: 'number', description: 'Max results (default 10)' },
+      },
+      required: ['query'],
+    },
+    async execute(_id: string, params: { query: string; types?: string[]; limit?: number }) {
+      const cfg = getConfig(api);
+      const url = new URL('/recall', baseUrl(cfg));
+      url.searchParams.set('q', params.query);
+      url.searchParams.set('agent', agentId(cfg, api));
+      if (params.limit) url.searchParams.set('limit', String(params.limit));
+      if (params.types?.length) url.searchParams.set('types', params.types.join(','));
+
+      try {
+        const data = await bbFetch(cfg, url.toString());
+        const memories = data.results || data.memories || [];
+
+        if (memories.length === 0) {
+          return { content: [{ type: 'text', text: 'No matching memories found in MemTap.' }] };
+        }
+
+        const formatted = memories.map((m: any, i: number) => {
+          const entities = (m.entities || []).map((e: any) => e.name).join(', ');
+          const meta = [`Type: ${m.type}`, `Importance: ${displayImportance(m.importance)}/10`];
+          if (entities) meta.push(`Entities: ${entities}`);
+          if (m.created) meta.push(`Created: ${m.created.split('T')[0]}`);
+          return `${i + 1}. [${m.id || m._key}] ${m.content}\n   ${meta.join(' | ')}`;
+        }).join('\n\n');
+
+        return { content: [{ type: 'text', text: `Found ${memories.length} memories:\n\n${formatted}` }] };
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `MemTap recall error: ${err.message}` }], isError: true };
+      }
+    },
+  });
+
+  // ── Tool: memtap_remember ────────────────────────────────────────────────
+
+  api.registerTool({
+    name: 'memtap_remember',
+    description:
+      'Store a memory in the MemTap knowledge graph. ' +
+      'Use for important facts, decisions, preferences, events, goals, or observations worth remembering long-term. ' +
+      'Entities mentioned are automatically extracted and linked.',
+    parameters: {
+      type: 'object',
+      properties: {
+        content: { type: 'string', description: 'The memory content to store' },
+        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' },
+      },
+      required: ['content'],
+    },
+    async execute(_id: string, params: { content: string; type?: string; importance?: number; tags?: string[] }) {
+      const cfg = getConfig(api);
+      const importance = params.importance ?? 5;
+      const body = {
+        content: params.content,
+        type: params.type || 'fact',
+        agent: agentId(cfg, api),
+        importance: storeImportance(importance),
+        tags: params.tags || [],
+      };
+
+      try {
+        const data = await bbFetch(cfg, `${baseUrl(cfg)}/memories`, {
+          method: 'POST',
+          body: JSON.stringify(body),
+        });
+
+        const entities = (data.entities || []).map((e: any) => e.name).join(', ');
+        let response = `Memory stored [${data.id || data._key}] (type: ${body.type}, importance: ${importance}/10)`;
+        if (entities) response += `\n  Linked entities: ${entities}`;
+
+        return { content: [{ type: 'text', text: response }] };
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `MemTap store error: ${err.message}` }], isError: true };
+      }
+    },
+  });
+
+  // ── Tool: memtap_bulletin (enhanced with graph expansion) ────────────────
+
+  api.registerTool({
+    name: 'memtap_bulletin',
+    description:
+      'Get a contextual memory bulletin from MemTap with graph expansion. ' +
+      'Returns relevant memories for given topics PLUS related memories discovered via graph traversal. ' +
+      'Agents suddenly "know" things they didn\'t explicitly search for.',
+    parameters: {
+      type: 'object',
+      properties: {
+        topics: { type: 'array', items: { type: 'string' }, description: 'Topics to get context for' },
+        limit: { type: 'number', description: 'Max seed memories per topic (default 3)' },
+      },
+      required: ['topics'],
+    },
+    async execute(_id: string, params: { topics: string[]; limit?: number }) {
+      const cfg = getConfig(api);
+
+      try {
+        const data = await bbFetch(cfg, `${baseUrl(cfg)}/bulletin`, {
+          method: 'POST',
+          body: JSON.stringify({
+            topics: params.topics,
+            agent: agentId(cfg, api),
+            limit: params.limit || 3,
+          }),
+        });
+
+        const sections = (data.sections || []).map((s: any) => {
+          // Direct search hits
+          const items = (s.memories || []).map((m: any) =>
+            `  - [${m.type}] ${m.summary} (importance: ${m.importance}/10)`
+          ).join('\n');
+
+          // Graph-expanded context
+          const graphItems = (s.graphContext || []).map((m: any) =>
+            `  - [${m.type}] ${m.summary} (importance: ${Math.round(m.importance)}/10)\n    Found via: ${m.foundVia}`
+          ).join('\n');
+
+          // Notable connections
+          const connItems = (s.connections || []).slice(0, 5).map((c: any) =>
+            `  - ${c.fromSummary} \u2192 ${c.edgeType} \u2192 ${c.toSummary}`
+          ).join('\n');
+
+          let section = `**${s.topic}** (${s.memories?.length || 0} direct + ${s.graphContext?.length || 0} via graph)`;
+          section += `\n${items || '  (no direct matches)'}`;
+          if (graphItems) section += `\n\nRelated (via graph):\n${graphItems}`;
+          if (connItems) section += `\n\nConnections:\n${connItems}`;
+          return section;
+        }).join('\n\n---\n\n');
+
+        return { content: [{ type: 'text', text: sections || 'No relevant memories found.' }] };
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `MemTap bulletin error: ${err.message}` }], isError: true };
+      }
+    },
+  });
+
+  // ── Tool: memtap_graphrag ────────────────────────────────────────────────
+
+  api.registerTool({
+    name: 'memtap_graphrag',
+    description:
+      'Advanced GraphRAG search: combines vector/BM25 search with multi-hop graph traversal. ' +
+      'Returns memories found through the knowledge graph with full path explanations. ' +
+      'Falls back to BM25 if embeddings are not configured.',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Natural language search query' },
+        depth: { type: 'number', description: 'Graph traversal depth (default 2, max 4)' },
+        topK: { type: 'number', description: 'Number of seed results (default 5)' },
+      },
+      required: ['query'],
+    },
+    async execute(_id: string, params: { query: string; depth?: number; topK?: number }) {
+      const cfg = getConfig(api);
+
+      try {
+        const data = await bbFetch(cfg, `${baseUrl(cfg)}/graphrag/query`, {
+          method: 'POST',
+          body: JSON.stringify({
+            query: params.query,
+            agent: agentId(cfg, api),
+            graphDepth: params.depth ?? 2,
+            embeddingTopK: params.topK ?? 5,
+          }),
+        });
+
+        const method = data.method || 'unknown';
+        const seeds = data.seeds || [];
+        const graphResults = data.results || data.graphResults || [];
+
+        if (seeds.length === 0 && graphResults.length === 0) {
+          return { content: [{ type: 'text', text: 'No results found via GraphRAG.' }] };
+        }
+
+        let output = `GraphRAG results (method: ${method}, ${seeds.length} seeds, ${graphResults.length} graph results):\n\n`;
+
+        // Show seeds
+        if (seeds.length > 0) {
+          output += 'Direct matches:\n';
+          output += seeds.map((s: any, i: number) =>
+            `  ${i + 1}. [${s.type}] ${s.summary || s.content} (importance: ${Math.round(s.importance)}/10)`
+          ).join('\n');
+          output += '\n\n';
+        }
+
+        // Show graph results with traversal paths
+        if (graphResults.length > 0) {
+          output += 'Discovered via graph traversal:\n';
+          output += graphResults.map((r: any, i: number) => {
+            const imp = Math.round(r.importance);
+            let line = `  ${i + 1}. [${r.type}] ${r.summary || r.content} (importance: ${imp}/10, ${r.hopDistance ?? r.depth ?? '?'}-hop)`;
+            // Show path explanation
+            if (r.path && r.path.length > 0) {
+              const pathStr = r.path.map((p: any) => `${p.id} \u2192 ${p.edgeType}`).join(' \u2192 ');
+              line += `\n     Path: ${pathStr} \u2192 ${r.id}`;
+            } else if (r.foundVia) {
+              line += `\n     Found via: ${r.foundVia}`;
+            }
+            return line;
+          }).join('\n');
+        }
+
+        return { content: [{ type: 'text', text: output }] };
+      } catch (err: any) {
+        // Graceful fallback if GraphRAG endpoint not available
+        if (err.message.includes('404') || err.message.includes('ECONNREFUSED')) {
+          return { content: [{ type: 'text', text: 'GraphRAG not available (embeddings may not be configured). Use memtap_recall for BM25 search.' }] };
+        }
+        return { content: [{ type: 'text', text: `MemTap GraphRAG error: ${err.message}` }], isError: true };
+      }
+    },
+  });
+
+  // ── Tool: memtap_maintenance ─────────────────────────────────────────────
+
+  api.registerTool({
+    name: 'memtap_maintenance',
+    description:
+      'Run memory maintenance checks on the MemTap knowledge graph. Actions:\n' +
+      '- decay-report: find memories that have decayed below importance threshold\n' +
+      '- contradictions: find contradicting memory pairs\n' +
+      '- dedup-scan: find potential duplicate memories\n' +
+      '- run-all: combined report of all checks',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['decay-report', 'contradictions', 'dedup-scan', 'run-all'],
+          description: 'Maintenance action to run',
+        },
+      },
+      required: ['action'],
+    },
+    async execute(_id: string, params: { action: string }) {
+      const cfg = getConfig(api);
+      const base = baseUrl(cfg);
+
+      try {
+        let data: any;
+
+        switch (params.action) {
+          case 'decay-report': {
+            data = await bbFetch(cfg, `${base}/maintenance/decay-report`);
+            const results = data.results || data.memories || [];
+            if (results.length === 0) {
+              return { content: [{ type: 'text', text: 'All memories are above the decay threshold. No action needed.' }] };
+            }
+            let output = `Decay Report: ${results.length} memories have decayed significantly\n\n`;
+            output += results.slice(0, 20).map((m: any, i: number) => {
+              const eff = m.effectiveImportance ?? m.effImportance ?? '?';
+              const days = m.daysSinceAccess ?? '?';
+              return `  ${i + 1}. [${m.id}] ${m.summary} (effective: ${eff}/10, ${days} days since access)`;
+            }).join('\n');
+            output += `\n\nRecommendation: These memories have decayed below 20% importance. Consider reviewing or archiving them.`;
+            return { content: [{ type: 'text', text: output }] };
+          }
+
+          case 'contradictions': {
+            data = await bbFetch(cfg, `${base}/maintenance/contradictions`);
+            const results = data.results || data.contradictions || [];
+            if (results.length === 0) {
+              return { content: [{ type: 'text', text: 'No contradictions found in the knowledge graph.' }] };
+            }
+            let output = `Contradictions: ${results.length} contradicting pair(s) found\n\n`;
+            output += results.map((c: any, i: number) => {
+              const m1 = c.memory1 || c;
+              const m2 = c.memory2 || c;
+              return `  ${i + 1}. "${m1.summary || m1.from}" CONTRADICTS "${m2.summary || m2.to}"`;
+            }).join('\n');
+            output += `\n\nRecommendation: Resolve by archiving the outdated memory or updating the relationship.`;
+            return { content: [{ type: 'text', text: output }] };
+          }
+
+          case 'dedup-scan': {
+            data = await bbFetch(cfg, `${base}/maintenance/dedup-scan`, { method: 'POST', body: '{}' });
+            const dupes = data.duplicates || [];
+            if (dupes.length === 0) {
+              return { content: [{ type: 'text', text: 'No obvious duplicates detected.' }] };
+            }
+            let output = `Dedup Scan: ${dupes.length} potential duplicate(s) found\n\n`;
+            output += dupes.slice(0, 20).map((d: any, i: number) => {
+              const m1 = d.memory1 || d;
+              const m2 = d.memory2 || d;
+              const kind = d.type === 'update_chain' ? 'Update chain' : 'Similar content';
+              return `  ${i + 1}. [${kind}] "${m1.summary || m1.older}" vs "${m2.summary || m2.newer}"\n     ${d.recommendation || 'Consider merging or archiving the older version.'}`;
+            }).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 || {};
+            const contras = data.contradictions || {};
+            const dedup = data.duplicates || data.dedupScan || {};
+
+            let output = 'MemTap Maintenance Report\n\n';
+
+            // Decay
+            const decayCount = decay.count ?? (decay.results || decay.memories || []).length;
+            output += `Decay: ${decayCount} memories below threshold\n`;
+            if (decayCount > 0) {
+              const decayItems = decay.results || decay.memories || [];
+              output += decayItems.slice(0, 5).map((m: any) =>
+                `  - [${m.id}] ${m.summary} (effective: ${m.effectiveImportance ?? '?'}/10)`
+              ).join('\n');
+              output += `\n  Action: Review or archive these ${decayCount} decayed memories\n`;
+            }
+
+            // Contradictions
+            const contraCount = contras.count ?? (contras.results || contras.pairs || []).length;
+            output += `\nContradictions: ${contraCount} pair(s)\n`;
+            if (contraCount > 0) {
+              const contraItems = contras.results || contras.pairs || [];
+              output += contraItems.slice(0, 5).map((c: any) =>
+                `  - "${c.from || c.memory1?.summary}" vs "${c.to || c.memory2?.summary}"`
+              ).join('\n');
+              output += `\n  Action: Resolve by archiving outdated versions\n`;
+            }
+
+            // Dedup
+            const dedupCount = dedup.count ?? (dedup.results || dedup.pairs || []).length;
+            output += `\nDuplicates: ${dedupCount} potential duplicate(s)\n`;
+            if (dedupCount > 0) {
+              const dedupItems = dedup.results || dedup.pairs || [];
+              output += dedupItems.slice(0, 5).map((d: any) =>
+                `  - "${d.older || d.memory1?.summary}" vs "${d.newer || d.memory2?.summary}"`
+              ).join('\n');
+              output += `\n  Action: Merge or archive older versions\n`;
+            }
+
+            return { content: [{ type: 'text', text: output }] };
+          }
+
+          default:
+            return { content: [{ type: 'text', text: `Unknown maintenance action: ${params.action}` }], isError: true };
+        }
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `MemTap maintenance error: ${err.message}` }], isError: true };
+      }
+    },
+  });
+
+  // ── Tool: memtap_graph ───────────────────────────────────────────────────
+
+  api.registerTool({
+    name: 'memtap_graph',
+    description:
+      'Analyze the MemTap knowledge graph structure. Actions:\n' +
+      '- overview: global graph stats (most connected nodes, edge distribution)\n' +
+      '- gaps: find orphan memories and weakly-connected nodes\n' +
+      '- clusters: discover topic clusters via connected components\n' +
+      '- connections: find paths between two memories (requires from, to)\n' +
+      '- traverse: BFS traversal from a start node (requires start, optional depth)',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['overview', 'gaps', 'clusters', 'connections', 'traverse'],
+          description: 'Graph analysis action',
+        },
+        from: { type: 'string', description: 'Source memory ID (for connections)' },
+        to: { type: 'string', description: 'Target memory ID (for connections)' },
+        start: { type: 'string', description: 'Start node ID (for traverse)' },
+        depth: { type: 'number', description: 'Traversal depth (for traverse, default server-side)' },
+      },
+      required: ['action'],
+    },
+    async execute(_id: string, params: { action: string; from?: string; to?: string; start?: string; depth?: number }) {
+      const cfg = getConfig(api);
+      const base = baseUrl(cfg);
+
+      try {
+        let data: any;
+
+        switch (params.action) {
+          case 'overview':
+            data = await bbFetch(cfg, `${base}/graph/overview`);
+            break;
+          case 'gaps':
+            data = await bbFetch(cfg, `${base}/graph/gaps`);
+            break;
+          case 'clusters':
+            data = await bbFetch(cfg, `${base}/graph/clusters`);
+            break;
+          case 'connections': {
+            if (!params.from || !params.to) {
+              return { content: [{ type: 'text', text: 'connections requires both "from" and "to" parameters.' }], isError: true };
+            }
+            const url = new URL('/graph/connections', base);
+            url.searchParams.set('from', params.from);
+            url.searchParams.set('to', params.to);
+            data = await bbFetch(cfg, url.toString());
+            break;
+          }
+          case 'traverse': {
+            if (!params.start) {
+              return { content: [{ type: 'text', text: 'traverse requires a "start" parameter.' }], isError: true };
+            }
+            const url = new URL('/graph/traverse', base);
+            url.searchParams.set('start', params.start);
+            if (params.depth != null) url.searchParams.set('depth', String(params.depth));
+            data = await bbFetch(cfg, url.toString());
+            break;
+          }
+          default:
+            return { content: [{ type: 'text', text: `Unknown graph action: ${params.action}` }], isError: true };
+        }
+
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `MemTap graph error: ${err.message}` }], isError: true };
+      }
+    },
+  });
+
+  // ── Tool: memtap_decide ──────────────────────────────────────────────────
+
+  api.registerTool({
+    name: 'memtap_decide',
+    description:
+      'Track decisions in MemTap. Actions:\n' +
+      '- list: show open/overdue/resolved decisions\n' +
+      '- create: create a new decision (requires content, optional options, deadline, context)\n' +
+      '- resolve: resolve a decision (requires id, resolution)\n' +
+      '- defer: defer a decision (requires id, reason)',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['list', 'create', 'resolve', 'defer'],
+          description: 'Decision action',
+        },
+        id: { type: 'string', description: 'Decision ID (for resolve/defer)' },
+        content: { type: 'string', description: 'Decision description (for create)' },
+        options: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Decision options (for create, optional)',
+        },
+        deadline: { type: 'string', description: 'Deadline ISO8601 (for create, optional)' },
+        context: { type: 'string', description: 'Additional context (for create, optional)' },
+        resolution: { type: 'string', description: 'Resolution text (for resolve)' },
+        reason: { type: 'string', description: 'Reason for deferral (for defer)' },
+      },
+      required: ['action'],
+    },
+    async execute(_id: string, params: {
+      action: string; id?: string; content?: string; options?: string[];
+      deadline?: string; context?: string; resolution?: string; reason?: string;
+    }) {
+      const cfg = getConfig(api);
+      const base = baseUrl(cfg);
+
+      try {
+        let data: any;
+
+        switch (params.action) {
+          case 'list':
+            data = await bbFetch(cfg, `${base}/decisions`);
+            break;
+          case 'create': {
+            if (!params.content) {
+              return { content: [{ type: 'text', text: 'create requires a "content" parameter.' }], isError: true };
+            }
+            const body: any = { content: params.content, agent: agentId(cfg, api) };
+            if (params.options?.length) body.options = params.options;
+            if (params.deadline) body.deadline = params.deadline;
+            if (params.context) body.context = params.context;
+            data = await bbFetch(cfg, `${base}/decisions`, {
+              method: 'POST',
+              body: JSON.stringify(body),
+            });
+            break;
+          }
+          case 'resolve': {
+            if (!params.id || !params.resolution) {
+              return { content: [{ type: 'text', text: 'resolve requires "id" and "resolution" parameters.' }], isError: true };
+            }
+            data = await bbFetch(cfg, `${base}/decisions/${encodeURIComponent(params.id)}/resolve`, {
+              method: 'POST',
+              body: JSON.stringify({ resolution: params.resolution }),
+            });
+            break;
+          }
+          case 'defer': {
+            if (!params.id || !params.reason) {
+              return { content: [{ type: 'text', text: 'defer requires "id" and "reason" parameters.' }], isError: true };
+            }
+            data = await bbFetch(cfg, `${base}/decisions/${encodeURIComponent(params.id)}/defer`, {
+              method: 'POST',
+              body: JSON.stringify({ reason: params.reason }),
+            });
+            break;
+          }
+          default:
+            return { content: [{ type: 'text', text: `Unknown decide action: ${params.action}` }], isError: true };
+        }
+
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `MemTap decide error: ${err.message}` }], isError: true };
+      }
+    },
+  });
+
+  // ── Tool: memtap_memory ──────────────────────────────────────────────────
+
+  api.registerTool({
+    name: 'memtap_memory',
+    description:
+      'Manage individual memories in MemTap. Actions:\n' +
+      '- get: retrieve a memory by ID\n' +
+      '- update: update a memory (content, summary, importance, tags, archived)\n' +
+      '- delete: archive a memory (soft delete) or hard-delete with hard=true',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['get', 'update', 'delete'],
+          description: 'Memory action',
+        },
+        id: { type: 'string', description: 'Memory ID' },
+        content: { type: 'string', description: 'Updated content (for update)' },
+        summary: { type: 'string', description: 'Updated summary (for update)' },
+        importance: { type: 'number', description: 'Updated importance 1-10 (for update)' },
+        tags: { type: 'array', items: { type: 'string' }, description: 'Updated tags (for update)' },
+        archived: { type: 'boolean', description: 'Archive status (for update)' },
+        hard: { type: 'boolean', description: 'Hard delete instead of archive (for delete, default false)' },
+      },
+      required: ['action', 'id'],
+    },
+    async execute(_id: string, params: {
+      action: string; id: string; content?: string; summary?: string;
+      importance?: number; tags?: string[]; archived?: boolean; hard?: boolean;
+    }) {
+      const cfg = getConfig(api);
+      const base = baseUrl(cfg);
+
+      try {
+        let data: any;
+
+        switch (params.action) {
+          case 'get':
+            data = await bbFetch(cfg, `${base}/memories/${encodeURIComponent(params.id)}`);
+            return { content: [{ type: 'text', text: `Memory [${data._key || params.id}]:\n  Content: ${data.content}\n  Type: ${data.type} | Importance: ${data.importance}/10 | Tags: ${(data.tags || []).join(', ')}\n  Created: ${data.created} | Accessed: ${data.accessCount || 0} times` }] };
+
+          case 'update': {
+            const body: Record<string, any> = {};
+            if (params.content !== undefined) body.content = params.content;
+            if (params.summary !== undefined) body.summary = params.summary;
+            if (params.importance !== undefined) body.importance = storeImportance(params.importance);
+            if (params.tags !== undefined) body.tags = params.tags;
+            if (params.archived !== undefined) body.archived = params.archived;
+            data = await bbFetch(cfg, `${base}/memories/${encodeURIComponent(params.id)}/update`, {
+              method: 'POST',
+              body: JSON.stringify(body),
+            });
+            return { content: [{ type: 'text', text: `Memory [${params.id}] updated.` }] };
+          }
+
+          case 'delete': {
+            const url = new URL(`/memories/${encodeURIComponent(params.id)}`, base);
+            if (params.hard) url.searchParams.set('hard', 'true');
+            data = await bbFetch(cfg, url.toString(), { method: 'DELETE' });
+            const action = data.deleted ? 'permanently deleted' : 'archived';
+            return { content: [{ type: 'text', text: `Memory [${params.id}] ${action}.` }] };
+          }
+
+          default:
+            return { content: [{ type: 'text', text: `Unknown memory action: ${params.action}` }], isError: true };
+        }
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `MemTap memory error: ${err.message}` }], isError: true };
+      }
+    },
+  });
+
+  // ── Tool: memtap_entities ─────────────────────────────────────────────────
+
+  api.registerTool({
+    name: 'memtap_entities',
+    description:
+      'Manage entities in the MemTap knowledge graph. Actions:\n' +
+      '- list: list all entities (optional type filter)\n' +
+      '- memories: get memories linked to an entity (requires key)\n' +
+      '- merge: merge duplicate entities (requires key, mergeFrom)',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['list', 'memories', 'merge'],
+          description: 'Entity action',
+        },
+        key: { type: 'string', description: 'Entity key (for memories/merge)' },
+        type: { type: 'string', description: 'Filter by entity type (for list)' },
+        mergeFrom: { type: 'string', description: 'Entity key to merge from (for merge)' },
+        limit: { type: 'number', description: 'Max results (default 50)' },
+      },
+      required: ['action'],
+    },
+    async execute(_id: string, params: { action: string; key?: string; type?: string; mergeFrom?: string; limit?: number }) {
+      const cfg = getConfig(api);
+      const base = baseUrl(cfg);
+
+      try {
+        let data: any;
+
+        switch (params.action) {
+          case 'list': {
+            const url = new URL('/entities', base);
+            if (params.type) url.searchParams.set('type', params.type);
+            if (params.limit) url.searchParams.set('limit', String(params.limit));
+            data = await bbFetch(cfg, url.toString());
+            const entities = Array.isArray(data) ? data : [];
+            if (entities.length === 0) {
+              return { content: [{ type: 'text', text: 'No entities found.' }] };
+            }
+            const formatted = entities.map((e: any) =>
+              `- [${e._key}] ${e.name} (type: ${e.type || 'unknown'}${e.aliases?.length ? `, aliases: ${e.aliases.join(', ')}` : ''})`
+            ).join('\n');
+            return { content: [{ type: 'text', text: `${entities.length} entities:\n${formatted}` }] };
+          }
+
+          case 'memories': {
+            if (!params.key) {
+              return { content: [{ type: 'text', text: 'memories requires a "key" parameter.' }], isError: true };
+            }
+            const url = new URL(`/entities/${encodeURIComponent(params.key)}/memories`, base);
+            if (params.limit) url.searchParams.set('limit', String(params.limit));
+            data = await bbFetch(cfg, url.toString());
+            const mems = Array.isArray(data) ? data : [];
+            if (mems.length === 0) {
+              return { content: [{ type: 'text', text: `No memories linked to entity "${params.key}".` }] };
+            }
+            const formatted = mems.map((m: any, i: number) =>
+              `${i + 1}. [${m._key}] ${m.content?.substring(0, 120)} (type: ${m.type}, importance: ${m.importance}/10)`
+            ).join('\n');
+            return { content: [{ type: 'text', text: `${mems.length} memories for entity "${params.key}":\n${formatted}` }] };
+          }
+
+          case 'merge': {
+            if (!params.key || !params.mergeFrom) {
+              return { content: [{ type: 'text', text: 'merge requires "key" (target) and "mergeFrom" (source) parameters.' }], isError: true };
+            }
+            data = await bbFetch(cfg, `${base}/entities/${encodeURIComponent(params.key)}/merge`, {
+              method: 'POST',
+              body: JSON.stringify({ mergeFrom: params.mergeFrom }),
+            });
+            return { content: [{ type: 'text', text: `Entity "${params.mergeFrom}" merged into "${params.key}". Aliases: ${(data.aliases || []).join(', ')}` }] };
+          }
+
+          default:
+            return { content: [{ type: 'text', text: `Unknown entity action: ${params.action}` }], isError: true };
+        }
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `MemTap entities error: ${err.message}` }], isError: true };
+      }
+    },
+  });
+
+  // ── Tool: memtap_edges ────────────────────────────────────────────────────
+
+  api.registerTool({
+    name: 'memtap_edges',
+    description:
+      'Create edges (relationships) between memories in the knowledge graph. ' +
+      'Edge types: RELATED_TO, UPDATES, CONTRADICTS, CAUSED_BY, PART_OF, DEPENDS_ON, MENTIONS.',
+    parameters: {
+      type: 'object',
+      properties: {
+        from: { type: 'string', description: 'Source memory ID' },
+        to: { type: 'string', description: 'Target memory ID' },
+        type: {
+          type: 'string',
+          enum: ['RELATED_TO', 'UPDATES', 'CONTRADICTS', 'CAUSED_BY', 'PART_OF', 'DEPENDS_ON', 'MENTIONS'],
+          description: 'Edge type',
+        },
+        weight: { type: 'number', description: 'Edge weight 0-1 (default 0.5)' },
+      },
+      required: ['from', 'to', 'type'],
+    },
+    async execute(_id: string, params: { from: string; to: string; type: string; weight?: number }) {
+      const cfg = getConfig(api);
+
+      try {
+        const data = await bbFetch(cfg, `${baseUrl(cfg)}/relate`, {
+          method: 'POST',
+          body: JSON.stringify({
+            from: params.from,
+            to: params.to,
+            type: params.type,
+            weight: params.weight ?? 0.5,
+          }),
+        });
+
+        return { content: [{ type: 'text', text: `Edge created: ${params.from} -[${params.type}]-> ${params.to} (weight: ${params.weight ?? 0.5})` }] };
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `MemTap edge 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' +
+      '- 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' +
+      '- analytics: user behavior analytics (engagement, success rates, patterns)',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['health', 'stats', 'neural', 'performance', 'analytics'],
+          description: 'Which check to run (default: health)',
+        },
+        agent: { type: 'string', description: 'Specific agent for neural/performance analysis (optional)' },
+        timeRange: { type: 'string', description: 'Time range for analytics (1h, 24h, 7d) default: 24h' }
+      },
+    },
+    async execute(_id: string, params: { action?: string; agent?: string; timeRange?: string }) {
+      const cfg = getConfig(api);
+      const base = baseUrl(cfg);
+      const action = params.action || 'health';
+
+      try {
+        let data: any;
+
+        switch (action) {
+          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 ?? '?'}` }] };
+
+          case 'stats':
+            data = await bbFetch(cfg, `${base}/stats`);
+            const byType = (data.byType || []).map((t: any) => `  ${t.type}: ${t.count}`).join('\n');
+            const byAgent = (data.byAgent || []).map((a: any) => `  ${a.agent}: ${a.count}`).join('\n');
+            return { content: [{ type: 'text', text: `MemTap Stats:\nTotal: ${data.total ?? '?'} memories | ${data.entityCount ?? '?'} entities | ${data.edgeCount ?? '?'} edges\n\nBy type:\n${byType || '  (none)'}\n\nBy agent:\n${byAgent || '  (none)'}` }] };
+
+          case 'neural':
+            return { content: [{ type: 'text', text: generateNeuralReport(params.agent) }] };
+
+          case 'performance':
+            return { content: [{ type: 'text', text: generatePerformanceReport(params.agent) }] };
+
+          case 'analytics':
+            return { content: [{ type: 'text', text: generateAnalyticsReport(params.agent, params.timeRange || '24h') }] };
+
+          default:
+            return { content: [{ type: 'text', text: `Unknown health action: ${action}` }], isError: true };
+        }
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `MemTap health error: ${err.message}` }], isError: true };
+      }
+    },
+  });
+
+  // ── Tool: memtap_monitor (Real-time Neural Activity) ─────────────────────
+
+  api.registerTool({
+    name: 'memtap_monitor',
+    description:
+      'Real-time monitoring of neural memory activity. Shows live working memory, attention patterns, ' +
+      'and memory operations as they happen. Use for debugging and optimization.',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['live', 'working-memory', 'attention', 'cache', 'consolidation'],
+          description: 'Type of monitoring to display'
+        },
+        agent: { type: 'string', description: 'Specific agent to monitor (optional)' },
+        duration: { type: 'number', description: 'Monitoring duration in seconds (default: 30)' }
+      },
+      required: ['action']
+    },
+    async execute(_id: string, params: { action: string; agent?: string; duration?: number }) {
+      const duration = params.duration || 30;
+      
+      try {
+        switch (params.action) {
+          case 'live':
+            return { content: [{ type: 'text', text: generateLiveMonitoring(params.agent, duration) }] };
+          
+          case 'working-memory':
+            return { content: [{ type: 'text', text: generateWorkingMemoryReport(params.agent) }] };
+          
+          case 'attention':
+            return { content: [{ type: 'text', text: generateAttentionReport(params.agent) }] };
+          
+          case 'cache':
+            return { content: [{ type: 'text', text: generateCacheReport(params.agent) }] };
+          
+          case 'consolidation':
+            return { content: [{ type: 'text', text: generateConsolidationReport(params.agent) }] };
+          
+          default:
+            return { content: [{ type: 'text', text: `Unknown monitor action: ${params.action}` }], isError: true };
+        }
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `MemTap monitor error: ${err.message}` }], isError: true };
+      }
+    },
+  });
+
+  // ── Hook: Smart Memory Recall (preMessage) ──────────────────────────────
+
+  api.registerHook(
+    'preMessage',
+    async (event: any) => {
+      const cfg = getConfig(api);
+      
+      const message = event.context?.message || event.message || '';
+      if (!message || message.length < 10) return;
+
+      // Neuromimetic Tiered Memory Recall with Working Memory Integration
+      const currentAgent = agentId(cfg, api);
+      const conversationCtx = analyzeConversationContext(currentAgent, message);
+      const recallLevel = analyzeRecallLevel(message, currentAgent);
+      
+      // Update Working Memory with current focus
+      const topics = recallLevel.topics;
+      updateWorkingMemory(currentAgent, topics);
+      
+      // Check cache first for performance (with neuromimetic enhancements)
+      const cacheKey = `${currentAgent}:${message.substring(0, 100)}`;
+      const cached = memoryCache.get(cacheKey);
+      const cacheValid = cached && (Date.now() - cached.timestamp) < 300000; // 5min cache
+      
+      if (recallLevel.intensity > 0) {
+        try {
+          let memories: any[] = [];
+          let contextTitle = '';
+          let bulletinContext = '';
+          let useCache = false;
+          
+          // Use cache if available and confidence is low
+          if (cacheValid && recallLevel.confidence < 0.7) {
+            memories = cached!.data;
+            contextTitle = `Cached Context (${recallLevel.reasoning})`;
+            useCache = true;
+          } else {
+            
+            // Dynamic limits based on user profile
+            const profile = getUserProfile(currentAgent);
+            const baseLimit = profile.recallSensitivity === 'high' ? 1.5 : 
+                             profile.recallSensitivity === 'low' ? 0.7 : 1.0;
+            
+            if (recallLevel.intensity === 1) {
+              // Light: Quick context
+              const limit = Math.ceil(2 * baseLimit);
+              const data = await bbFetch(cfg, `${baseUrl(cfg)}/recall?q=${encodeURIComponent(message)}&limit=${limit}&agent=${currentAgent}`);
+              memories = data.results || data.memories || [];
+              contextTitle = `Quick Context (confidence: ${Math.round(recallLevel.confidence * 100)}%)`;
+            } 
+            else if (recallLevel.intensity === 2) {
+              // Standard: Normal recall
+              const limit = Math.ceil(4 * baseLimit);
+              const data = await bbFetch(cfg, `${baseUrl(cfg)}/recall?q=${encodeURIComponent(message)}&limit=${limit}&agent=${currentAgent}`);
+              memories = data.results || data.memories || [];
+              contextTitle = `Relevant Memories (confidence: ${Math.round(recallLevel.confidence * 100)}%)`;
+            }
+            else if (recallLevel.intensity === 3) {
+              // Deep: Full context with bulletin
+              const limit = Math.ceil(6 * baseLimit);
+              
+              const [recallData, bulletinData] = await Promise.all([
+                bbFetch(cfg, `${baseUrl(cfg)}/recall?q=${encodeURIComponent(message)}&limit=${limit}&agent=${currentAgent}`),
+                bbFetch(cfg, `${baseUrl(cfg)}/bulletin`, {
+                  method: 'POST',
+                  body: JSON.stringify({
+                    topics: recallLevel.topics,
+                    agent: currentAgent,
+                    limit: Math.ceil(2 * baseLimit)
+                  })
+                }).catch(() => ({ sections: [] }))
+              ]);
+              
+              memories = recallData.results || recallData.memories || [];
+              const sections = bulletinData.sections || [];
+              contextTitle = `Deep Memory Context (confidence: ${Math.round(recallLevel.confidence * 100)}%)`;
+              
+              if (sections.length > 0) {
+                bulletinContext = sections.map((s: any) => {
+                  const items = (s.memories || []).slice(0, 2).map((m: any) => 
+                    `- [${m.type}] ${m.summary} (${Math.round(m.importance)}/10)`
+                  ).join('\n');
+                  const graphItems = (s.graphContext || []).slice(0, 1).map((m: any) =>
+                    `- [via graph] ${m.summary}`
+                  ).join('\n');
+                  return `**${s.topic}:**\n${items}${graphItems ? '\n' + graphItems : ''}`;
+                }).join('\n\n');
+              }
+            }
+            
+            // Cache results for performance
+            if (memories.length > 0) {
+              memoryCache.set(cacheKey, {
+                data: memories,
+                timestamp: Date.now(),
+                query: message
+              });
+              
+              // Limit cache size
+              if (memoryCache.size > 100) {
+                const oldestKey = Array.from(memoryCache.keys())[0];
+                memoryCache.delete(oldestKey);
+              }
+            }
+          }
+          
+          if (memories.length > 0) {
+            // Retrieval Practice Strengthening - memories get stronger when accessed
+            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) 
+                  bbFetch(cfg, `${baseUrl(cfg)}/memories/${encodeURIComponent(m.id)}/access`, {
+                    method: 'POST',
+                    body: JSON.stringify({ 
+                      boost: strengthBoost,
+                      retrievalCount: (m.retrievalCount || 0) + 1,
+                      lastAccess: Date.now(),
+                      attentionLevel: context?.attentionLevel || 'unknown'
+                    })
+                  }).catch(() => {}); // Silent fail
+                  
+                  // Update local cache retrieval count
+                  if (memoryCache.has(cacheKey)) {
+                    const cached = memoryCache.get(cacheKey)!;
+                    cached.retrievalCount = (cached.retrievalCount || 0) + 1;
+                  }
+                }
+              } catch { /* ignore update failures */ }
+            });
+            
+            // Sort by relevance + importance + recency
+            memories.sort((a, b) => {
+              const scoreA = (a.importance || 0.5) * 0.6 + (a.relevanceScore || 0.5) * 0.3 + (a.recency || 0) * 0.1;
+              const scoreB = (b.importance || 0.5) * 0.6 + (b.relevanceScore || 0.5) * 0.3 + (b.recency || 0) * 0.1;
+              return scoreB - scoreA;
+            });
+            
+            // Format memories with enhanced context
+            const memoryContext = memories.map((m: any, i: number) => {
+              const entities = (m.entities || []).map((e: any) => e.name).join(', ');
+              const age = m.created ? Math.floor((Date.now() - Date.parse(m.created)) / (1000 * 60 * 60 * 24)) : '?';
+              const hotness = m.accessCount > 5 ? ' 🔥' : m.accessCount > 2 ? ' ⚡' : '';
+              
+              return `${i + 1}. [${m.type}] ${m.content}${hotness}\n   └─ Importance: ${displayImportance(m.importance)}/10${entities ? ` | Entities: ${entities}` : ''} | Age: ${age}d`;
+            }).join('\n\n');
+
+            let injection = `
+## ${contextTitle}:
+${memoryContext}
+`;
+
+            // Add bulletin context if available
+            if (bulletinContext) {
+              injection += `\n## Topic Context:\n${bulletinContext}`;
+            }
+            
+            // Add conversation context hints
+            const context = conversationState.get(currentAgent);
+            if (context?.dominantTopic) {
+              injection += `\n## Conversation Context:\nDominant topic: ${context.dominantTopic} | Engagement: ${context.userEngagement}`;
+            }
+
+            // Enhanced instructions based on context
+            let instructions = '\n\n**Memory Instructions:**\n';
+            instructions += `- Use this context when relevant (confidence: ${Math.round(recallLevel.confidence * 100)}%)\n`;
+            instructions += `- Reasoning: ${recallLevel.reasoning}\n`;
+            if (recallLevel.confidence < 0.7) {
+              instructions += '- Consider using memtap_recall() for more specific information\n';
+            }
+            if (useCache) {
+              instructions += '- This is cached data - use memtap_recall() for fresh results if needed\n';
+            }
+            
+            injection += instructions;
+
+            // Append to existing system prompt
+            event.context.systemPrompt = (event.context.systemPrompt || '') + injection;
+            
+            // Update metrics
+            updateUserProfile(currentAgent, recallLevel.intensity, true);
+            
+            const logMsg = useCache ? 
+              `[memtap] ${contextTitle} injected: ${memories.length} cached memories` :
+              `[memtap] ${contextTitle} injected: ${memories.length} memories (level ${recallLevel.intensity}, conf: ${Math.round(recallLevel.confidence * 100)}%)`;
+            
+            logger.info?.(logMsg) ?? console.log(logMsg);
+          } else {
+            // No memories found - update metrics
+            updateUserProfile(currentAgent, recallLevel.intensity, false);
+          }
+        } catch (err: any) {
+          logger.warn?.(`[memtap] preMessage recall failed: ${err.message}`) ??
+            console.warn(`[memtap] preMessage recall failed: ${err.message}`);
+        }
+      }
+    },
+    {
+      name: 'memtap.smart-recall',
+      description: 'Smart automatic memory recall based on message content analysis',
+    }
+  );
+
+  // ── Hook: Enhanced Auto-Capture with Learning (message_completed) ─────────
+
+  api.registerHook(
+    'message_completed',
+    async (event: any) => {
+      const cfg = getConfig(api);
+      if (!cfg.autoCapture) return;
+
+      const content = event.context?.content;
+      if (!content || content === 'NO_REPLY' || content === 'HEARTBEAT_OK') return;
+      if (content.length < 80) return;
+
+      const currentAgent = agentId(cfg, api);
+      
+      (async () => {
+        try {
+          const context = conversationState.get(currentAgent);
+          const workingMemory = workingMemoryState.get(currentAgent);
+          
+          // Attention-gated encoding - only encode if attention allows
+          if (context && !shouldEncodeMemory(
+            content, 
+            context.attentionLevel, 
+            context.emotionalContext,
+            workingMemory?.cognitiveLoad || 0
+          )) {
+            return; // Skip encoding due to low attention/high cognitive load
+          }
+          
+          const memories = await llmExtract(cfg, content);
+          if (!memories.length) return;
+
+          let stored = 0;
+
+          for (const mem of memories) {
+            if (!mem.content || mem.content.length < 10) continue;
+            
+            try {
+              // Calculate emotional weighting
+              const memoryType = mem.type || 'fact';
+              const emotionalWeight = EMOTIONAL_WEIGHTS[memoryType] || 1.0;
+              const contextualWeight = context?.emotionalContext === 'excited' ? 1.2 :
+                                     context?.emotionalContext === 'positive' ? 1.1 :
+                                     context?.emotionalContext === 'negative' ? 1.15 : 1.0;
+              
+              const finalImportance = (mem.importance ?? 5) * emotionalWeight * contextualWeight;
+              
+              // Enhanced memory with neuromimetic features
+              const enhancedMem = {
+                content: mem.content,
+                type: memoryType,
+                agent: currentAgent,
+                importance: storeImportance(Math.min(10, finalImportance)),
+                tags: [
+                  ...(mem.tags || []), 
+                  'auto-captured',
+                  'neuromimetic',
+                  ...(context?.dominantTopic ? [`topic:${context.dominantTopic}`] : []),
+                  `engagement:${context?.userEngagement || 'unknown'}`,
+                  `attention:${context?.attentionLevel || 'unknown'}`,
+                  `emotion:${context?.emotionalContext || 'neutral'}`
+                ],
+                source: 'plugin:neuromimetic-capture-v2.1',
+                conversationContext: {
+                  dominantTopic: context?.dominantTopic,
+                  engagement: context?.userEngagement,
+                  queryCount: context?.memoryQueryCount || 0,
+                  attentionLevel: context?.attentionLevel,
+                  emotionalContext: context?.emotionalContext
+                },
+                neuromimeticData: {
+                  emotionalIntensity: contextualWeight,
+                  attentionStrength: context?.attentionLevel === 'flow' ? 1.0 :
+                                   context?.attentionLevel === 'focused' ? 0.8 : 0.5,
+                  consolidationScore: 0.1, // Will increase with dream cycles
+                  retrievalCount: 0,
+                  lastAccess: Date.now()
+                }
+              };
+              
+              // Create episodic memory entry
+              if (context && memoryType === 'event') {
+                const episodic = createEpisodicMemory(currentAgent, mem.content, context);
+                const episodics = episodicMemories.get(currentAgent) || [];
+                episodics.push(episodic);
+                episodicMemories.set(currentAgent, episodics.slice(-100)); // Keep last 100
+              }
+              
+              await bbFetch(cfg, `${baseUrl(cfg)}/memories`, {
+                method: 'POST',
+                body: JSON.stringify(enhancedMem),
+              });
+              stored++;
+              
+              // Cross-session memory sharing for MemTap agents
+              if (currentAgent.includes('memtap') && mem.type === 'decision') {
+                try {
+                  // Share important decisions across MemTap agent ecosystem
+                  const crossSessionMem = {
+                    ...enhancedMem,
+                    agent: 'memtap-shared',
+                    tags: [...enhancedMem.tags, 'cross-session', `from:${currentAgent}`]
+                  };
+                  
+                  await bbFetch(cfg, `${baseUrl(cfg)}/memories`, {
+                    method: 'POST',
+                    body: JSON.stringify(crossSessionMem)
+                  });
+                } catch { /* cross-session sharing failed, not critical */ }
+              }
+              
+            } catch { /* skip individual failures */ }
+          }
+
+          if (stored > 0) {
+            // Update user profile with successful capture
+            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`);
+          }
+          
+        } catch (err: any) {
+          logger.warn?.(`[memtap] Auto-capture failed: ${err.message}`) ??
+            console.warn(`[memtap] Auto-capture failed: ${err.message}`);
+        }
+      })();
+    },
+    {
+      name: 'memtap.auto-capture-enhanced',
+      description: 'Enhanced LLM-based memory extraction with context awareness and cross-session sharing',
+    }
+  );
+
+  // ── Hook: Bulletin on Bootstrap (agent:bootstrap) ──────────────────────────
+
+  api.registerHook(
+    'agent:bootstrap',
+    async (event: any) => {
+      const cfg = getConfig(api);
+      if (!cfg.bulletinOnBoot) return;
+
+      const topics = cfg.bulletinTopics || ['active projects', 'recent decisions', 'pending tasks'];
+
+      try {
+        const data = await bbFetch(cfg, `${baseUrl(cfg)}/bulletin`, {
+          method: 'POST',
+          body: JSON.stringify({
+            topics,
+            agent: agentId(cfg, api),
+            limit: 3,
+          }),
+        });
+
+        const sections = (data.sections || []).map((s: any) => {
+          const items = (s.memories || []).map((m: any) =>
+            `- [${m.type}] ${m.summary}`
+          ).join('\n');
+          const graphItems = (s.graphContext || []).slice(0, 3).map((m: any) =>
+            `- [via graph] [${m.type}] ${m.summary}`
+          ).join('\n');
+          return `### ${s.topic}\n${items || '(keine Erinnerungen)'}${graphItems ? '\n' + graphItems : ''}`;
+        }).join('\n\n');
+
+        if (sections) {
+          const bootstrapFiles = event.context?.bootstrapFiles || [];
+          const fileEntry = {
+            name: 'MEMTAP_BULLETIN.md',
+            path: 'MEMTAP_BULLETIN.md',
+            filePath: 'MEMTAP_BULLETIN.md',
+            content: `# MemTap Memory Bulletin\n\n${sections}\n`,
+            missing: false,
+            source: 'memtap-plugin',
+          };
+          bootstrapFiles.push(fileEntry);
+        }
+      } catch (err: any) {
+        logger.warn?.(`[memtap] Bulletin injection failed: ${err.message}`) ??
+          console.warn(`[memtap] Bulletin injection failed: ${err.message}`);
+      }
+    },
+    {
+      name: 'memtap.bulletin-inject',
+      description: 'Inject a memory bulletin into agent bootstrap context',
+    }
+  );
+
+  // ── Hook: Dream-Mode Consolidation & Neural Maintenance (periodic) ────────
+
+  api.registerHook(
+    'periodic',
+    async (event: any) => {
+      const cfg = getConfig(api);
+      
+      // Dream-mode consolidation (every ~10 calls, representing sleep cycles)
+      if (Math.random() < 0.1) {
+        await dreamModeConsolidation(cfg);
+      }
+      
+      // Neural maintenance and cleanup
+      if (Math.random() < 0.05) {
+        await neuralMaintenance();
+      }
+    },
+    {
+      name: 'memtap.dream-consolidation',
+      description: 'Neuromimetic dream-mode consolidation and neural maintenance',
+    }
+  );
+
+// ── Neural Monitoring & Analytics Functions ──────────────────────────────────
+
+function generateNeuralReport(agentFilter?: string): string {
+  const now = Date.now();
+  let report = `# 🧠 MemTap Neural System Report\n\n`;
+
+  // Working Memory Analysis
+  report += `## Working Memory States:\n`;
+  let wmCount = 0;
+  for (const [agentId, wm] of workingMemoryState.entries()) {
+    if (agentFilter && agentId !== agentFilter) continue;
+    wmCount++;
+    
+    const age = Math.round((now - wm.lastUpdate) / (1000 * 60));
+    const loadStatus = wm.cognitiveLoad > 0.8 ? '🔴 HIGH' : 
+                      wm.cognitiveLoad > 0.5 ? '🟡 MEDIUM' : '🟢 LOW';
+    
+    report += `  **${agentId}:**\n`;
+    report += `    Focus: [${wm.currentFocus.join(', ')}]\n`;
+    report += `    Spotlight: "${wm.attentionSpotlight}"\n`;
+    report += `    Load: ${Math.round(wm.cognitiveLoad * 100)}% ${loadStatus}\n`;
+    report += `    Active Memories: ${wm.activeMemories.length}\n`;
+    report += `    Last Update: ${age}min ago\n\n`;
+  }
+  if (wmCount === 0) report += `  No active working memory states\n\n`;
+
+  // Conversation Context Analysis
+  report += `## Conversation Contexts:\n`;
+  let ctxCount = 0;
+  for (const [agentId, ctx] of conversationState.entries()) {
+    if (agentFilter && agentId !== agentFilter) continue;
+    ctxCount++;
+    
+    const lastAccess = ctx.lastMemoryAccess ? 
+      Math.round((now - ctx.lastMemoryAccess) / (1000 * 60)) + 'min ago' : 
+      'never';
+    
+    report += `  **${agentId}:**\n`;
+    report += `    Topics: [${ctx.recentTopics.join(', ')}]\n`;
+    report += `    Dominant: "${ctx.dominantTopic || 'none'}"\n`;
+    report += `    Attention: ${ctx.attentionLevel} | Emotion: ${ctx.emotionalContext}\n`;
+    report += `    Engagement: ${ctx.userEngagement} | Queries: ${ctx.memoryQueryCount}\n`;
+    report += `    Last Memory Access: ${lastAccess}\n\n`;
+  }
+  if (ctxCount === 0) report += `  No active conversation contexts\n\n`;
+
+  // Episodic Memory Summary
+  report += `## Episodic Memories:\n`;
+  let episodicCount = 0;
+  for (const [agentId, episodes] of episodicMemories.entries()) {
+    if (agentFilter && agentId !== agentFilter) continue;
+    episodicCount += episodes.length;
+    
+    const avgEmotion = episodes.length > 0 ? 
+      episodes.reduce((sum, e) => sum + e.emotionalIntensity, 0) / episodes.length : 0;
+    const avgConsolidation = episodes.length > 0 ? 
+      episodes.reduce((sum, e) => sum + e.consolidationScore, 0) / episodes.length : 0;
+    
+    report += `  **${agentId}:** ${episodes.length} episodes\n`;
+    report += `    Avg Emotional Intensity: ${Math.round(avgEmotion * 100)}%\n`;
+    report += `    Avg Consolidation: ${Math.round(avgConsolidation * 100)}%\n`;
+  }
+  report += `  Total Episodic Memories: ${episodicCount}\n\n`;
+
+  // Memory Chunks Analysis
+  report += `## Memory Chunks:\n`;
+  let chunkCount = 0;
+  for (const [agentId, chunks] of memoryChunks.entries()) {
+    if (agentFilter && agentId !== agentFilter) continue;
+    chunkCount += chunks.length;
+    
+    const strongChunks = chunks.filter(c => c.strength > 0.8).length;
+    const concepts = chunks.map(c => c.abstractConcept).slice(0, 3).join(', ');
+    
+    report += `  **${agentId}:** ${chunks.length} chunks (${strongChunks} strong)\n`;
+    report += `    Top Concepts: ${concepts}\n`;
+  }
+  report += `  Total Memory Chunks: ${chunkCount}\n\n`;
+
+  return report;
+}
+
+function generatePerformanceReport(agentFilter?: string): string {
+  let report = `# ⚡ MemTap Performance Report\n\n`;
+
+  // Cache Performance
+  report += `## Cache Performance:\n`;
+  let totalCacheEntries = 0;
+  let totalRetrievals = 0;
+  let hitRate = 0;
+
+  for (const [key, cached] of memoryCache.entries()) {
+    if (agentFilter && !key.startsWith(agentFilter + ':')) continue;
+    totalCacheEntries++;
+    totalRetrievals += cached.retrievalCount || 0;
+  }
+
+  if (totalCacheEntries > 0) {
+    hitRate = totalRetrievals / totalCacheEntries;
+  }
+
+  report += `  Cache Entries: ${totalCacheEntries}\n`;
+  report += `  Total Retrievals: ${totalRetrievals}\n`;
+  report += `  Avg Hit Rate: ${Math.round(hitRate * 100)}%\n`;
+  report += `  Cache Efficiency: ${hitRate > 1.5 ? '🟢 EXCELLENT' : hitRate > 0.8 ? '🟡 GOOD' : '🔴 POOR'}\n\n`;
+
+  // User Profile Performance
+  report += `## User Profiles:\n`;
+  let totalProfiles = 0;
+  let totalQueries = 0;
+  let totalSuccessful = 0;
+
+  for (const [agentId, profile] of userProfiles.entries()) {
+    if (agentFilter && agentId !== agentFilter) continue;
+    totalProfiles++;
+    totalQueries += profile.totalQueries;
+    totalSuccessful += profile.successfulRecalls;
+
+    if (!agentFilter) {
+      const successRate = profile.totalQueries > 0 ? 
+        Math.round((profile.successfulRecalls / profile.totalQueries) * 100) : 0;
+      
+      report += `  **${agentId}:**\n`;
+      report += `    Queries: ${profile.totalQueries} | Success: ${successRate}%\n`;
+      report += `    Sensitivity: ${profile.recallSensitivity} | Complexity: ${profile.averageQueryComplexity.toFixed(1)}\n`;
+      report += `    Sleep Cycles: ${profile.sleepCycles} | Last Active: ${new Date(profile.lastActive).toLocaleString()}\n\n`;
+    }
+  }
+
+  const overallSuccessRate = totalQueries > 0 ? 
+    Math.round((totalSuccessful / totalQueries) * 100) : 0;
+
+  report += `## Overall Performance:\n`;
+  report += `  Active Profiles: ${totalProfiles}\n`;
+  report += `  Total Queries: ${totalQueries}\n`;
+  report += `  Success Rate: ${overallSuccessRate}%\n`;
+  report += `  System Health: ${overallSuccessRate > 80 ? '🟢 EXCELLENT' : overallSuccessRate > 60 ? '🟡 GOOD' : '🔴 NEEDS ATTENTION'}\n\n`;
+
+  return report;
+}
+
+function generateAnalyticsReport(agentFilter?: string, timeRange: string = '24h'): string {
+  const now = Date.now();
+  const ranges = {
+    '1h': 60 * 60 * 1000,
+    '24h': 24 * 60 * 60 * 1000,
+    '7d': 7 * 24 * 60 * 60 * 1000
+  };
+  const cutoff = now - (ranges[timeRange as keyof typeof ranges] || ranges['24h']);
+
+  let report = `# 📊 MemTap Analytics Report (${timeRange})\n\n`;
+
+  // Attention Patterns Analysis
+  const recentAttention = attentionHistory.filter(a => 
+    a.timestamp > cutoff && (!agentFilter || a.agent === agentFilter)
+  );
+
+  if (recentAttention.length > 0) {
+    const attentionCounts = recentAttention.reduce((acc, a) => {
+      acc[a.level] = (acc[a.level] || 0) + 1;
+      return acc;
+    }, {} as Record<string, number>);
+
+    report += `## Attention Patterns (${recentAttention.length} events):\n`;
+    for (const [level, count] of Object.entries(attentionCounts)) {
+      const pct = Math.round((count / recentAttention.length) * 100);
+      report += `  ${level}: ${count} events (${pct}%)\n`;
+    }
+    report += '\n';
+  }
+
+  // Engagement Analysis
+  report += `## User Engagement:\n`;
+  for (const [agentId, ctx] of conversationState.entries()) {
+    if (agentFilter && agentId !== agentFilter) continue;
+    
+    const profile = userProfiles.get(agentId);
+    if (!profile || profile.lastActive < cutoff) continue;
+
+    report += `  **${agentId}:**\n`;
+    report += `    Current Engagement: ${ctx.userEngagement}\n`;
+    report += `    Memory Queries: ${ctx.memoryQueryCount} in session\n`;
+    report += `    Dominant Topic: ${ctx.dominantTopic || 'none'}\n`;
+    report += `    Emotional Context: ${ctx.emotionalContext}\n\n`;
+  }
+
+  // Memory Operation Trends
+  const recentCacheOps = Array.from(memoryCache.entries()).filter(([key, cached]) => 
+    cached.timestamp > cutoff && (!agentFilter || key.startsWith(agentFilter + ':'))
+  );
+
+  report += `## Memory Operations:\n`;
+  report += `  Cache Operations: ${recentCacheOps.length}\n`;
+  
+  if (recentCacheOps.length > 0) {
+    const avgRetrievals = recentCacheOps.reduce((sum, [, cached]) => 
+      sum + (cached.retrievalCount || 0), 0) / recentCacheOps.length;
+    report += `  Avg Retrievals per Entry: ${avgRetrievals.toFixed(1)}\n`;
+  }
+
+  // Query Complexity Distribution
+  const complexities = Array.from(userProfiles.values())
+    .filter(p => !agentFilter || agentFilter === 'all' || p.lastActive > cutoff)
+    .map(p => p.averageQueryComplexity);
+
+  if (complexities.length > 0) {
+    const avgComplexity = complexities.reduce((sum, c) => sum + c, 0) / complexities.length;
+    report += `  Avg Query Complexity: ${avgComplexity.toFixed(2)}\n`;
+  }
+
+  return report;
+}
+
+function generateLiveMonitoring(agentFilter?: string, duration: number = 30): string {
+  let report = `# 🔴 LIVE Neural Monitoring (${duration}s)\n\n`;
+  
+  report += `## Current System State:\n`;
+  report += `- Working Memory States: ${workingMemoryState.size}\n`;
+  report += `- Active Conversations: ${conversationState.size}\n`;
+  report += `- Cache Entries: ${memoryCache.size}\n`;
+  report += `- User Profiles: ${userProfiles.size}\n`;
+  report += `- Memory Chunks: ${Array.from(memoryChunks.values()).reduce((sum, chunks) => sum + chunks.length, 0)}\n`;
+  report += `- Episodic Memories: ${Array.from(episodicMemories.values()).reduce((sum, eps) => sum + eps.length, 0)}\n\n`;
+
+  if (agentFilter) {
+    const wm = workingMemoryState.get(agentFilter);
+    const ctx = conversationState.get(agentFilter);
+    
+    if (wm) {
+      report += `## Live Working Memory (${agentFilter}):\n`;
+      report += `- Focus: [${wm.currentFocus.join(', ')}]\n`;
+      report += `- Cognitive Load: ${Math.round(wm.cognitiveLoad * 100)}%\n`;
+      report += `- Active Memories: ${wm.activeMemories.length}\n\n`;
+    }
+    
+    if (ctx) {
+      report += `## Live Context (${agentFilter}):\n`;
+      report += `- Attention: ${ctx.attentionLevel}\n`;
+      report += `- Emotion: ${ctx.emotionalContext}\n`;
+      report += `- Engagement: ${ctx.userEngagement}\n`;
+      report += `- Recent Topics: [${ctx.recentTopics.join(', ')}]\n\n`;
+    }
+  }
+
+  report += `*Monitoring started. Use memtap_monitor again to refresh.*\n`;
+  
+  return report;
+}
+
+function generateWorkingMemoryReport(agentFilter?: string): string {
+  let report = `# 🧠 Working Memory Analysis\n\n`;
+  
+  for (const [agentId, wm] of workingMemoryState.entries()) {
+    if (agentFilter && agentId !== agentFilter) continue;
+    
+    const age = Math.round((Date.now() - wm.lastUpdate) / 1000);
+    
+    report += `## Agent: ${agentId}\n`;
+    report += `**Current Focus:** [${wm.currentFocus.join(', ')}]\n`;
+    report += `**Attention Spotlight:** "${wm.attentionSpotlight}"\n`;
+    report += `**Cognitive Load:** ${Math.round(wm.cognitiveLoad * 100)}% ${'▓'.repeat(Math.round(wm.cognitiveLoad * 10))}${'░'.repeat(10 - Math.round(wm.cognitiveLoad * 10))}\n`;
+    report += `**Active Memories:** ${wm.activeMemories.length}\n`;
+    report += `**Last Update:** ${age}s ago\n\n`;
+    
+    if (wm.activeMemories.length > 0) {
+      report += `**Preloaded Memories:**\n`;
+      wm.activeMemories.slice(0, 3).forEach((mem, i) => {
+        report += `  ${i + 1}. [${mem.type}] ${mem.content?.substring(0, 60)}...\n`;
+      });
+      report += '\n';
+    }
+  }
+  
+  if (workingMemoryState.size === 0) {
+    report += `No active working memory states found.\n`;
+  }
+  
+  return report;
+}
+
+function generateAttentionReport(agentFilter?: string): string {
+  const recentAttention = attentionHistory
+    .filter(a => (!agentFilter || a.agent === agentFilter))
+    .slice(-20);
+  
+  let report = `# 👁️ Attention Pattern Analysis\n\n`;
+  
+  if (recentAttention.length === 0) {
+    return report + `No attention data available.\n`;
+  }
+  
+  // Attention distribution
+  const attentionCounts = recentAttention.reduce((acc, a) => {
+    acc[a.level] = (acc[a.level] || 0) + 1;
+    return acc;
+  }, {} as Record<string, number>);
+  
+  report += `## Recent Attention Distribution (${recentAttention.length} events):\n`;
+  for (const [level, count] of Object.entries(attentionCounts)) {
+    const pct = Math.round((count / recentAttention.length) * 100);
+    const bar = '█'.repeat(Math.round(pct / 5));
+    report += `**${level}:** ${count} (${pct}%) ${bar}\n`;
+  }
+  report += '\n';
+  
+  // Recent events
+  report += `## Recent Attention Events:\n`;
+  recentAttention.slice(-10).reverse().forEach((event, i) => {
+    const timeAgo = Math.round((Date.now() - event.timestamp) / 1000);
+    report += `${i + 1}. **${event.level}** - "${event.trigger}" (${timeAgo}s ago)\n`;
+  });
+  
+  return report;
+}
+
+function generateCacheReport(agentFilter?: string): string {
+  let report = `# 💾 Memory Cache Analysis\n\n`;
+  
+  const relevantCache = Array.from(memoryCache.entries()).filter(([key]) => 
+    !agentFilter || key.startsWith(agentFilter + ':')
+  );
+  
+  if (relevantCache.length === 0) {
+    return report + `No cache entries found.\n`;
+  }
+  
+  // Cache statistics
+  const totalRetrievals = relevantCache.reduce((sum, [, cached]) => sum + (cached.retrievalCount || 0), 0);
+  const avgAge = relevantCache.reduce((sum, [, cached]) => sum + (Date.now() - cached.timestamp), 0) / relevantCache.length / 1000;
+  const avgRetrievals = totalRetrievals / relevantCache.length;
+  
+  report += `## Cache Statistics:\n`;
+  report += `**Total Entries:** ${relevantCache.length}\n`;
+  report += `**Total Retrievals:** ${totalRetrievals}\n`;
+  report += `**Avg Retrievals/Entry:** ${avgRetrievals.toFixed(2)}\n`;
+  report += `**Avg Age:** ${Math.round(avgAge)}s\n`;
+  report += `**Hit Rate:** ${avgRetrievals > 1 ? '🟢 Good' : '🟡 Low'}\n\n`;
+  
+  // Top cached queries
+  const topCached = relevantCache
+    .sort(([, a], [, b]) => (b.retrievalCount || 0) - (a.retrievalCount || 0))
+    .slice(0, 5);
+  
+  report += `## Most Accessed Cache Entries:\n`;
+  topCached.forEach(([key, cached], i) => {
+    const query = cached.query.substring(0, 50);
+    const age = Math.round((Date.now() - cached.timestamp) / 1000);
+    report += `${i + 1}. "${query}..." (${cached.retrievalCount || 0} hits, ${age}s old)\n`;
+  });
+  
+  return report;
+}
+
+function generateConsolidationReport(agentFilter?: string): string {
+  let report = `# 🌙 Dream-Mode Consolidation Report\n\n`;
+  
+  // Memory chunks analysis
+  const relevantChunks = Array.from(memoryChunks.entries()).filter(([agentId]) => 
+    !agentFilter || agentId === agentFilter
+  );
+  
+  if (relevantChunks.length === 0) {
+    return report + `No consolidation data available.\n`;
+  }
+  
+  const allChunks = relevantChunks.flatMap(([, chunks]) => chunks);
+  const strongChunks = allChunks.filter(c => c.strength > 0.8);
+  const avgStrength = allChunks.reduce((sum, c) => sum + c.strength, 0) / allChunks.length;
+  
+  report += `## Consolidation Statistics:\n`;
+  report += `**Total Chunks:** ${allChunks.length}\n`;
+  report += `**Strong Chunks:** ${strongChunks.length} (${Math.round(strongChunks.length / allChunks.length * 100)}%)\n`;
+  report += `**Avg Strength:** ${avgStrength.toFixed(2)}\n`;
+  report += `**Consolidation Health:** ${avgStrength > 0.7 ? '🟢 Excellent' : avgStrength > 0.5 ? '🟡 Good' : '🔴 Poor'}\n\n`;
+  
+  // Top consolidated concepts
+  report += `## Top Consolidated Concepts:\n`;
+  strongChunks.slice(0, 5).forEach((chunk, i) => {
+    const age = Math.round((Date.now() - chunk.lastActivation) / (1000 * 60));
+    report += `${i + 1}. **${chunk.abstractConcept}** (strength: ${chunk.strength.toFixed(2)}, ${chunk.relatedMemories.length} memories, ${age}min ago)\n`;
+  });
+  
+  // Episodic consolidation
+  const episodicData = Array.from(episodicMemories.entries()).filter(([agentId]) => 
+    !agentFilter || agentId === agentFilter
+  );
+  
+  if (episodicData.length > 0) {
+    const allEpisodics = episodicData.flatMap(([, eps]) => eps);
+    const avgConsolidation = allEpisodics.reduce((sum, e) => sum + e.consolidationScore, 0) / allEpisodics.length;
+    
+    report += `\n## Episodic Memory Consolidation:\n`;
+    report += `**Total Episodes:** ${allEpisodics.length}\n`;
+    report += `**Avg Consolidation Score:** ${Math.round(avgConsolidation * 100)}%\n`;
+  }
+  
+  return report;
+}
+
+// ── Alert System & Dashboard Functions ───────────────────────────────────────
+
+interface Alert {
+  id: string;
+  severity: 'info' | 'warning' | 'critical';
+  message: string;
+  timestamp: number;
+  agent?: string;
+  metric?: string;
+  value?: number;
+  threshold?: number;
+}
+
+const activeAlerts: Alert[] = [];
+
+function performAnomalyDetection(minSeverity: string = 'warning'): string {
+  const now = Date.now();
+  let report = `# 🚨 Neural Anomaly Detection\n\n`;
+  let alertCount = 0;
+
+  // Check working memory overload
+  for (const [agentId, wm] of workingMemoryState.entries()) {
+    if (wm.cognitiveLoad > 0.9) {
+      const alert: Alert = {
+        id: `cognitive_overload_${agentId}`,
+        severity: 'warning',
+        message: `High cognitive load detected for ${agentId}`,
+        timestamp: now,
+        agent: agentId,
+        metric: 'cognitive_load',
+        value: wm.cognitiveLoad,
+        threshold: 0.9
+      };
+      addAlert(alert);
+      alertCount++;
+    }
+  }
+
+  // Check for memory cache bloat
+  if (memoryCache.size > 80) {
+    const alert: Alert = {
+      id: 'cache_bloat',
+      severity: 'warning',
+      message: 'Memory cache size approaching limit',
+      timestamp: now,
+      metric: 'cache_size',
+      value: memoryCache.size,
+      threshold: 80
+    };
+    addAlert(alert);
+    alertCount++;
+  }
+
+  // Check for inactive working memory states (memory leak detection)
+  const oneHourAgo = now - 60 * 60 * 1000;
+  for (const [agentId, wm] of workingMemoryState.entries()) {
+    if (wm.lastUpdate < oneHourAgo) {
+      const alert: Alert = {
+        id: `stale_wm_${agentId}`,
+        severity: 'info',
+        message: `Stale working memory state for ${agentId}`,
+        timestamp: now,
+        agent: agentId,
+        metric: 'last_update',
+        value: (now - wm.lastUpdate) / (1000 * 60), // minutes
+        threshold: 60
+      };
+      addAlert(alert);
+      alertCount++;
+    }
+  }
+
+  // Check attention pattern anomalies
+  const recentAttention = attentionHistory.filter(a => a.timestamp > now - 24 * 60 * 60 * 1000);
+  if (recentAttention.length > 0) {
+    const distractedCount = recentAttention.filter(a => a.level === 'distracted').length;
+    const distractedRatio = distractedCount / recentAttention.length;
+    
+    if (distractedRatio > 0.7) {
+      const alert: Alert = {
+        id: 'attention_degradation',
+        severity: 'warning',
+        message: 'High distraction rate detected across system',
+        timestamp: now,
+        metric: 'distracted_ratio',
+        value: distractedRatio,
+        threshold: 0.7
+      };
+      addAlert(alert);
+      alertCount++;
+    }
+  }
+
+  // Check user profile health
+  for (const [agentId, profile] of userProfiles.entries()) {
+    if (profile.totalQueries > 10) {
+      const successRate = profile.successfulRecalls / profile.totalQueries;
+      if (successRate < 0.6) {
+        const alert: Alert = {
+          id: `low_success_rate_${agentId}`,
+          severity: 'warning',
+          message: `Low memory recall success rate for ${agentId}`,
+          timestamp: now,
+          agent: agentId,
+          metric: 'success_rate',
+          value: successRate,
+          threshold: 0.6
+        };
+        addAlert(alert);
+        alertCount++;
+      }
+    }
+  }
+
+  // Filter alerts by severity
+  const filteredAlerts = activeAlerts.filter(a => {
+    const levels = { info: 0, warning: 1, critical: 2 };
+    return levels[a.severity] >= levels[minSeverity as keyof typeof levels];
+  });
+
+  report += `**Anomaly Detection Complete**\n`;
+  report += `- Total Checks: 5\n`;
+  report += `- New Alerts: ${alertCount}\n`;
+  report += `- Active Alerts (${minSeverity}+): ${filteredAlerts.length}\n\n`;
+
+  if (filteredAlerts.length > 0) {
+    report += `## Active Alerts:\n`;
+    filteredAlerts.slice(-10).forEach((alert, i) => {
+      const age = Math.round((now - alert.timestamp) / (1000 * 60));
+      const icon = alert.severity === 'critical' ? '🔴' : 
+                   alert.severity === 'warning' ? '🟡' : '🔵';
+      
+      report += `${i + 1}. ${icon} **${alert.severity.toUpperCase()}**: ${alert.message}\n`;
+      if (alert.value && alert.threshold) {
+        report += `   Value: ${alert.value.toFixed(2)} | Threshold: ${alert.threshold} | ${age}min ago\n`;
+      }
+      report += '\n';
+    });
+  } else {
+    report += `✅ **System Status: HEALTHY**\nNo anomalies detected at ${minSeverity} level or above.\n`;
+  }
+
+  return report;
+}
+
+function addAlert(alert: Alert) {
+  // Remove existing alert with same ID
+  const existingIndex = activeAlerts.findIndex(a => a.id === alert.id);
+  if (existingIndex >= 0) {
+    activeAlerts[existingIndex] = alert;
+  } else {
+    activeAlerts.push(alert);
+  }
+  
+  // Limit alert history
+  if (activeAlerts.length > 100) {
+    activeAlerts.splice(0, 50); // Keep most recent 50
+  }
+}
+
+function listActiveAlerts(minSeverity: string = 'warning'): string {
+  const levels = { info: 0, warning: 1, critical: 2 };
+  const filtered = activeAlerts.filter(a => 
+    levels[a.severity] >= levels[minSeverity as keyof typeof levels]
+  );
+
+  if (filtered.length === 0) {
+    return `No active alerts at ${minSeverity} level or above.`;
+  }
+
+  let report = `# 🚨 Active Alerts (${filtered.length})\n\n`;
+  
+  const now = Date.now();
+  filtered.slice(-20).reverse().forEach((alert, i) => {
+    const age = Math.round((now - alert.timestamp) / (1000 * 60));
+    const icon = alert.severity === 'critical' ? '🔴' : 
+                 alert.severity === 'warning' ? '🟡' : '🔵';
+    
+    report += `## ${i + 1}. ${icon} ${alert.severity.toUpperCase()}\n`;
+    report += `**Message:** ${alert.message}\n`;
+    report += `**Time:** ${age} minutes ago\n`;
+    if (alert.agent) report += `**Agent:** ${alert.agent}\n`;
+    if (alert.value && alert.threshold) {
+      report += `**Value:** ${alert.value.toFixed(2)} (threshold: ${alert.threshold})\n`;
+    }
+    report += '\n';
+  });
+
+  return report;
+}
+
+function clearAlerts() {
+  activeAlerts.length = 0;
+}
+
+function generateDashboard(view: string = 'overview', agentFilter?: string): string {
+  const now = Date.now();
+  let dashboard = `# 🧠 MemTap Neural System Dashboard\n`;
+  dashboard += `*Updated: ${new Date().toLocaleString()}*\n\n`;
+
+  // System Health Overview
+  const totalProfiles = userProfiles.size;
+  const activeWM = workingMemoryState.size;
+  const activeConversations = conversationState.size;
+  const cacheSize = memoryCache.size;
+  const totalAlerts = activeAlerts.filter(a => a.severity !== 'info').length;
+
+  dashboard += `## 🚦 System Health\n`;
+  dashboard += `| Metric | Value | Status |\n`;
+  dashboard += `|--------|-------|--------|\n`;
+  dashboard += `| Active Users | ${totalProfiles} | ${totalProfiles > 0 ? '🟢' : '🟡'} |\n`;
+  dashboard += `| Working Memory | ${activeWM} | ${activeWM > 0 ? '🟢' : '🟡'} |\n`;
+  dashboard += `| Conversations | ${activeConversations} | ${activeConversations > 0 ? '🟢' : '🟡'} |\n`;
+  dashboard += `| Cache Size | ${cacheSize}/100 | ${cacheSize < 80 ? '🟢' : cacheSize < 95 ? '🟡' : '🔴'} |\n`;
+  dashboard += `| Alerts | ${totalAlerts} | ${totalAlerts === 0 ? '🟢' : totalAlerts < 5 ? '🟡' : '🔴'} |\n\n`;
+
+  // Performance Metrics
+  if (view !== 'compact') {
+    const totalQueries = Array.from(userProfiles.values()).reduce((sum, p) => sum + p.totalQueries, 0);
+    const successfulRecalls = Array.from(userProfiles.values()).reduce((sum, p) => sum + p.successfulRecalls, 0);
+    const overallSuccessRate = totalQueries > 0 ? (successfulRecalls / totalQueries) * 100 : 0;
+
+    dashboard += `## 📊 Performance Metrics\n`;
+    dashboard += `- **Total Queries:** ${totalQueries}\n`;
+    dashboard += `- **Success Rate:** ${overallSuccessRate.toFixed(1)}%\n`;
+    dashboard += `- **Cache Hit Rate:** ${cacheSize > 0 ? 'Available' : 'N/A'}\n`;
+    dashboard += `- **Memory Efficiency:** ${overallSuccessRate > 80 ? '🟢 Excellent' : overallSuccessRate > 60 ? '🟡 Good' : '🔴 Poor'}\n\n`;
+  }
+
+  // Neural Activity Summary
+  if (view === 'detailed') {
+    dashboard += `## 🧠 Neural Activity\n`;
+    
+    // Working Memory Summary
+    if (workingMemoryState.size > 0) {
+      const avgCognitiveLoad = Array.from(workingMemoryState.values())
+        .reduce((sum, wm) => sum + wm.cognitiveLoad, 0) / workingMemoryState.size;
+      
+      dashboard += `### Working Memory\n`;
+      dashboard += `- **Active States:** ${workingMemoryState.size}\n`;
+      dashboard += `- **Avg Cognitive Load:** ${Math.round(avgCognitiveLoad * 100)}%\n`;
+      
+      // Show individual agents if filtered
+      if (agentFilter) {
+        const wm = workingMemoryState.get(agentFilter);
+        if (wm) {
+          dashboard += `- **Focus (${agentFilter}):** [${wm.currentFocus.join(', ')}]\n`;
+          dashboard += `- **Spotlight:** "${wm.attentionSpotlight}"\n`;
+        }
+      }
+      dashboard += '\n';
+    }
+
+    // Attention Patterns
+    const recentAttention = attentionHistory.filter(a => 
+      a.timestamp > now - 60 * 60 * 1000 && (!agentFilter || a.agent === agentFilter)
+    );
+    
+    if (recentAttention.length > 0) {
+      const attentionCounts = recentAttention.reduce((acc, a) => {
+        acc[a.level] = (acc[a.level] || 0) + 1;
+        return acc;
+      }, {} as Record<string, number>);
+
+      dashboard += `### Attention Patterns (Last Hour)\n`;
+      for (const [level, count] of Object.entries(attentionCounts)) {
+        const pct = Math.round((count / recentAttention.length) * 100);
+        dashboard += `- **${level}:** ${count} (${pct}%)\n`;
+      }
+      dashboard += '\n';
+    }
+
+    // Memory Consolidation
+    const totalChunks = Array.from(memoryChunks.values()).reduce((sum, chunks) => sum + chunks.length, 0);
+    const totalEpisodics = Array.from(episodicMemories.values()).reduce((sum, eps) => sum + eps.length, 0);
+
+    dashboard += `### Memory Consolidation\n`;
+    dashboard += `- **Memory Chunks:** ${totalChunks}\n`;
+    dashboard += `- **Episodic Memories:** ${totalEpisodics}\n`;
+    dashboard += `- **Consolidation Status:** ${totalChunks > 0 ? '🟢 Active' : '🟡 Minimal'}\n\n`;
+  }
+
+  // Recent Alerts
+  const recentAlerts = activeAlerts.filter(a => a.timestamp > now - 60 * 60 * 1000);
+  if (recentAlerts.length > 0) {
+    dashboard += `## 🚨 Recent Alerts (${recentAlerts.length})\n`;
+    recentAlerts.slice(-3).forEach((alert, i) => {
+      const age = Math.round((now - alert.timestamp) / (1000 * 60));
+      const icon = alert.severity === 'critical' ? '🔴' : alert.severity === 'warning' ? '🟡' : '🔵';
+      dashboard += `${i + 1}. ${icon} ${alert.message} (${age}min ago)\n`;
+    });
+    dashboard += '\n';
+  }
+
+  // Quick Actions
+  dashboard += `## ⚡ Quick Actions\n`;
+  dashboard += `- \`memtap_monitor live\` - Real-time neural monitoring\n`;
+  dashboard += `- \`memtap_alerts check\` - Run anomaly detection\n`;
+  dashboard += `- \`memtap_health neural\` - Detailed neural system report\n`;
+  dashboard += `- \`memtap_maintenance run-all\` - Full system maintenance\n`;
+
+  return dashboard;
+}
+
+// ── Dream-Mode Consolidation Function ────────────────────────────────────────
+
+async function dreamModeConsolidation(cfg: MemTapConfig) {
+  try {
+    // Simulate sleep consolidation - strengthen important memories, weaken unused ones
+    for (const [agentId, chunks] of memoryChunks.entries()) {
+      
+      // Strengthen frequently accessed chunks
+      for (const chunk of chunks) {
+        if (chunk.lastActivation > Date.now() - 86400000) { // Active in last 24h
+          chunk.strength += FORGETTING_CURVE.consolidationBonus;
+        } else {
+          chunk.strength *= 0.98; // Slight decay for unused chunks
+        }
+      }
+      
+      // Remove very weak chunks (forgotten)
+      const activeChunks = chunks.filter(c => c.strength > 0.1);
+      memoryChunks.set(agentId, activeChunks);
+      
+      // Update consolidation scores for episodic memories
+      const episodics = episodicMemories.get(agentId) || [];
+      for (const episodic of episodics) {
+        episodic.consolidationScore = Math.min(1.0, 
+          episodic.consolidationScore + 
+          (episodic.emotionalIntensity * FORGETTING_CURVE.consolidationBonus)
+        );
+      }
+    }
+    
+    // Pattern recognition and abstraction (simplified)
+    await backgroundPatternRecognition(cfg);
+    
+    console.log('[memtap] Dream-mode consolidation completed');
+    
+  } catch (err: any) {
+    console.warn(`[memtap] Dream-mode consolidation failed: ${err.message}`);
+  }
+}
+
+async function backgroundPatternRecognition(cfg: MemTapConfig) {
+  // Analyze patterns in memory access and create abstract connections
+  try {
+    // Find frequently co-accessed memories
+    const cachePatterns = new Map<string, string[]>();
+    
+    for (const [key, cached] of memoryCache.entries()) {
+      if (cached.retrievalCount > 3) { // Frequently accessed
+        const agent = key.split(':')[0];
+        const patterns = cachePatterns.get(agent) || [];
+        patterns.push(cached.query);
+        cachePatterns.set(agent, patterns);
+      }
+    }
+    
+    // Create abstract pattern memories (very simplified)
+    for (const [agent, patterns] of cachePatterns.entries()) {
+      if (patterns.length > 5) {
+        const abstractPattern = `Pattern detected: Frequent queries about ${extractCommonThemes(patterns)}`;
+        
+        // Store as a meta-memory
+        await bbFetch(cfg, `${baseUrl(cfg)}/memories`, {
+          method: 'POST',
+          body: JSON.stringify({
+            content: abstractPattern,
+            type: 'pattern',
+            agent: agent,
+            importance: 0.6,
+            tags: ['dream-extracted', 'pattern', 'meta-memory'],
+            source: 'plugin:dream-mode-pattern-recognition'
+          })
+        }).catch(() => {}); // Silent fail
+      }
+    }
+    
+  } catch { /* Pattern recognition failed - not critical */ }
+}
+
+function extractCommonThemes(queries: string[]): string {
+  const allText = queries.join(' ').toLowerCase();
+  
+  if (/memtap.*development/i.test(allText)) return 'MemTap development patterns';
+  if (/business.*strategy/i.test(allText)) return 'business strategy concerns';
+  if (/infrastructure.*server/i.test(allText)) return 'infrastructure management';
+  
+  return 'general usage patterns';
+}
+
+async function neuralMaintenance() {
+  try {
+    const now = Date.now();
+    const oneDayAgo = now - 24 * 60 * 60 * 1000;
+    const oneWeekAgo = now - 7 * 24 * 60 * 60 * 1000;
+    
+    // Clean up old conversation state (older than 1 day)
+    for (const [agentId, context] of conversationState.entries()) {
+      if ((context.lastMemoryAccess || 0) < oneDayAgo) {
+        conversationState.delete(agentId);
+      }
+    }
+    
+    // Clean up old cache entries and update retrieval counts
+    for (const [key, cached] of memoryCache.entries()) {
+      if (cached.timestamp < oneDayAgo) {
+        memoryCache.delete(key);
+      }
+    }
+    
+    // Clean up old working memory states
+    for (const [agentId, wm] of workingMemoryState.entries()) {
+      if (wm.lastUpdate < oneDayAgo) {
+        workingMemoryState.delete(agentId);
+      }
+    }
+    
+    // Clean up old episodic memories (keep only last 30 days)
+    for (const [agentId, episodics] of episodicMemories.entries()) {
+      const recentEpisodics = episodics.filter(e => e.timestamp > oneWeekAgo);
+      episodicMemories.set(agentId, recentEpisodics);
+    }
+    
+    // Update user profiles sleep cycles (for consolidation tracking)
+    for (const [agentId, profile] of userProfiles.entries()) {
+      if (profile.lastActive < oneDayAgo) {
+        profile.sleepCycles++;
+      }
+    }
+    
+    // Clean up attention history
+    attentionHistory = attentionHistory.filter(a => a.timestamp > oneWeekAgo);
+    
+    console.log('[memtap] Neural maintenance completed');
+    
+  } catch (err: any) {
+    console.warn(`[memtap] Neural maintenance failed: ${err.message}`);
+  }
+}
+
+  // ── Performance Monitoring Hook ──────────────────────────────────────────
+
+  api.registerHook(
+    'session_end',
+    async (event: any) => {
+      const currentAgent = agentId(getConfig(api), api);
+      const profile = userProfiles.get(currentAgent);
+      const context = conversationState.get(currentAgent);
+      
+      if (profile && profile.totalQueries > 0) {
+        const successRate = profile.successfulRecalls / profile.totalQueries;
+        const avgComplexity = profile.averageQueryComplexity;
+        
+        logger.info?.(`[memtap] Session stats for ${currentAgent}: ${profile.totalQueries} queries, ${Math.round(successRate * 100)}% success rate, avg complexity ${avgComplexity.toFixed(1)}`) ??
+          console.log(`[memtap] Session stats for ${currentAgent}: ${profile.totalQueries} queries, ${Math.round(successRate * 100)}% success rate, avg complexity ${avgComplexity.toFixed(1)}`);
+      }
+    },
+    {
+      name: 'memtap.performance-monitor',
+      description: 'Monitor and log memory system performance metrics',
+    }
+  );
+
+  // ── Tool: memtap_alerts (Anomaly Detection & Alerting) ──────────────────────
+
+  api.registerTool({
+    name: 'memtap_alerts',
+    description:
+      'Neural system anomaly detection and alerting. Monitors for performance issues, ' +
+      'memory leaks, attention anomalies, and system health problems.',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['check', 'list', 'clear'],
+          description: 'Alert action to perform'
+        },
+        severity: {
+          type: 'string',
+          enum: ['info', 'warning', 'critical'],
+          description: 'Minimum severity level to show (default: warning)'
+        }
+      },
+      required: ['action']
+    },
+    async execute(_id: string, params: { action: string; severity?: string }) {
+      const minSeverity = params.severity || 'warning';
+      
+      try {
+        switch (params.action) {
+          case 'check':
+            return { content: [{ type: 'text', text: performAnomalyDetection(minSeverity) }] };
+          
+          case 'list':
+            return { content: [{ type: 'text', text: listActiveAlerts(minSeverity) }] };
+          
+          case 'clear':
+            clearAlerts();
+            return { content: [{ type: 'text', text: 'All alerts cleared.' }] };
+          
+          default:
+            return { content: [{ type: 'text', text: `Unknown alert action: ${params.action}` }], isError: true };
+        }
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `MemTap alerts error: ${err.message}` }], isError: true };
+      }
+    },
+  });
+
+  // ── Tool: memtap_dashboard (Comprehensive System Overview) ─────────────────
+
+  api.registerTool({
+    name: 'memtap_dashboard',
+    description:
+      'Comprehensive MemTap neural system dashboard. Shows all key metrics, system health, ' +
+      'performance indicators, and neural activity in a single overview.',
+    parameters: {
+      type: 'object',
+      properties: {
+        view: {
+          type: 'string',
+          enum: ['overview', 'detailed', 'compact'],
+          description: 'Dashboard view mode (default: overview)'
+        },
+        agent: { type: 'string', description: 'Focus on specific agent (optional)' }
+      }
+    },
+    async execute(_id: string, params: { view?: string; agent?: string }) {
+      const view = params.view || 'overview';
+      
+      try {
+        return { content: [{ type: 'text', text: generateDashboard(view, params.agent) }] };
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `MemTap dashboard error: ${err.message}` }], isError: true };
+      }
+    },
+  });
+
+  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');
+}