@pcircle/memesh 2.11.0 → 3.0.1

package/scripts/hooks/pre-compact.js

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+
+import { createRequire } from 'module';
+import { homedir } from 'os';
+import { join, basename } from 'path';
+import { existsSync, mkdirSync, readFileSync } from 'fs';
+
+const require = createRequire(import.meta.url);
+
+const SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS entities (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT NOT NULL UNIQUE,
+  type TEXT NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  metadata JSON
+);
+
+CREATE TABLE IF NOT EXISTS observations (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  entity_id INTEGER NOT NULL,
+  content TEXT NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (entity_id) REFERENCES entities(id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS relations (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  from_entity_id INTEGER NOT NULL,
+  to_entity_id INTEGER NOT NULL,
+  relation_type TEXT NOT NULL,
+  metadata JSON,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (from_entity_id) REFERENCES entities(id) ON DELETE CASCADE,
+  FOREIGN KEY (to_entity_id) REFERENCES entities(id) ON DELETE CASCADE,
+  UNIQUE(from_entity_id, to_entity_id, relation_type)
+);
+
+CREATE TABLE IF NOT EXISTS tags (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  entity_id INTEGER NOT NULL,
+  tag TEXT NOT NULL,
+  FOREIGN KEY (entity_id) REFERENCES entities(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_tags_entity ON tags(entity_id);
+CREATE INDEX IF NOT EXISTS idx_tags_tag ON tags(tag);
+DELETE FROM tags
+WHERE id NOT IN (
+  SELECT MIN(id)
+  FROM tags
+  GROUP BY entity_id, tag
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_tags_entity_tag_unique ON tags(entity_id, tag);
+CREATE INDEX IF NOT EXISTS idx_observations_entity ON observations(entity_id);
+CREATE INDEX IF NOT EXISTS idx_relations_from ON relations(from_entity_id);
+CREATE INDEX IF NOT EXISTS idx_relations_to ON relations(to_entity_id);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS entities_fts USING fts5(
+  name, observations, content='',
+  tokenize='unicode61 remove_diacritics 1'
+);
+`;
+
+// Timeout guard: always exit within 10 seconds
+const TIMEOUT_MS = 10000;
+const timeoutHandle = setTimeout(() => {
+  try { process.stderr.write('[memesh pre-compact] Timed out after 10s\n'); } catch {}
+  process.exit(0);
+}, TIMEOUT_MS);
+timeoutHandle.unref();
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    // Opt-out check
+    if (process.env.MEMESH_AUTO_CAPTURE === 'false') {
+      return exit0();
+    }
+
+    const data = JSON.parse(input);
+    const sessionId = data.session_id || 'unknown';
+    const transcriptPath = data.transcript_path || '';
+    const cwd = data.cwd || process.cwd();
+    const reason = data.reason || 'auto';
+    const projectName = basename(cwd);
+
+    // Parse transcript to gather insights
+    let toolCallCount = 0;
+    const editedFiles = new Set();
+
+    if (transcriptPath && existsSync(transcriptPath)) {
+      try {
+        const lines = readFileSync(transcriptPath, 'utf8').split('\n');
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          try {
+            const entry = JSON.parse(line);
+            // Count tool uses from assistant message content blocks
+            if (entry.role === 'assistant' && Array.isArray(entry.content)) {
+              for (const block of entry.content) {
+                if (block.type === 'tool_use') {
+                  toolCallCount++;
+                  // Track file edits
+                  const name = block.name || '';
+                  if (name === 'Edit' || name === 'Write' || name === 'MultiEdit') {
+                    const filePath = block.input?.file_path || block.input?.path || '';
+                    if (filePath) editedFiles.add(basename(filePath));
+                  }
+                }
+              }
+            }
+          } catch {
+            // Skip malformed lines
+          }
+        }
+      } catch {
+        // Transcript read failed — proceed with zero counts
+      }
+    }
+
+    const insightCount = editedFiles.size + (toolCallCount > 0 ? 1 : 0);
+    const entityName = `pre-compact-${sessionId}`;
+
+    // Build observation content
+    const obsLines = [`Compaction reason: ${reason}`, `Tool calls: ${toolCallCount}`];
+    if (editedFiles.size > 0) {
+      obsLines.push(`Files edited: ${Array.from(editedFiles).join(', ')}`);
+    }
+
+    // Open (or create) database
+    const dbPath = process.env.MEMESH_DB_PATH || join(homedir(), '.memesh', 'knowledge-graph.db');
+    const dbDir = process.env.MEMESH_DB_PATH
+      ? join(process.env.MEMESH_DB_PATH, '..')
+      : join(homedir(), '.memesh');
+    if (!existsSync(dbDir)) mkdirSync(dbDir, { recursive: true });
+
+    const Database = require('better-sqlite3');
+    const db = new Database(dbPath);
+    try {
+      db.pragma('journal_mode = WAL');
+      db.pragma('foreign_keys = ON');
+      db.exec(SCHEMA_SQL);
+
+      // Upsert entity
+      const insertResult = db.prepare('INSERT OR IGNORE INTO entities (name, type) VALUES (?, ?)').run(entityName, 'session-summary');
+      const isNew = insertResult.changes > 0;
+      const entity = db.prepare('SELECT id FROM entities WHERE name = ?').get(entityName);
+
+      if (entity) {
+        // Capture existing observations for FTS delete
+        const prevObs = isNew
+          ? []
+          : db.prepare('SELECT content FROM observations WHERE entity_id = ?').all(entity.id);
+        const prevObsText = isNew ? undefined : prevObs.map(o => o.content).join(' ');
+
+        // Insert each observation line
+        for (const line of obsLines) {
+          db.prepare('INSERT INTO observations (entity_id, content) VALUES (?, ?)').run(entity.id, line);
+        }
+
+        // Add tags
+        const tags = ['source:auto-capture', 'urgency:pre-compact', `project:${projectName}`];
+        for (const tag of tags) {
+          db.prepare('INSERT OR IGNORE INTO tags (entity_id, tag) VALUES (?, ?)').run(entity.id, tag);
+        }
+
+        // Update FTS
+        if (prevObsText !== undefined) {
+          db.prepare("INSERT INTO entities_fts(entities_fts, rowid, name, observations) VALUES('delete', ?, ?, ?)").run(entity.id, entityName, prevObsText);
+        }
+        const allObs = db.prepare('SELECT content FROM observations WHERE entity_id = ?').all(entity.id);
+        const allObsText = allObs.map(o => o.content).join(' ');
+        db.prepare('INSERT INTO entities_fts(rowid, name, observations) VALUES(?, ?, ?)').run(entity.id, entityName, allObsText);
+      }
+    } finally {
+      db.close();
+    }
+
+    const hookOutput = {
+      hookSpecificOutput: {
+        hookEventName: 'PreCompact',
+        additionalContext: `Saved ${insightCount} insights to MeMesh before compaction`,
+      },
+    };
+    console.log(JSON.stringify(hookOutput));
+  } catch (err) {
+    // Hooks must never crash Claude Code — exit cleanly
+    try { process.stderr.write(`[memesh pre-compact] ${err?.message || err}\n`); } catch {}
+  }
+  exit0();
+});
+
+function exit0() {
+  process.exit(0);
+}

package/scripts/hooks/session-start.js

@@ -36,67 +36,115 @@ process.stdin.on('end', () => {
         return;
       }
 
-      // Query project-specific recent entities with their observations
+      // Inspect available columns for backward compat
+      const columns = db.prepare("PRAGMA table_info(entities)").all();
+      const colNames = new Set(columns.map(col => col.name));
+
+      const hasStatus = colNames.has('status');
+      const hasScoringCols = colNames.has('access_count') && colNames.has('last_accessed_at') && colNames.has('confidence');
+
+      const statusFilter = hasStatus ? "AND e.status = 'active'" : '';
+      const recentStatusFilter = hasStatus ? "WHERE status = 'active'" : '';
+
+      // Configurable limit: how many top-N entities to load per section
+      const sessionLimit = parseInt(process.env.MEMESH_SESSION_LIMIT || '10', 10);
+
+      // Build scoring ORDER BY clause (or fallback to insertion order)
+      const scoringOrderBy = hasScoringCols
+        ? `ORDER BY
+            CASE WHEN e.confidence IS NULL THEN 0.5 ELSE e.confidence END * 0.4
+            + CASE WHEN e.access_count IS NULL THEN 0
+                   ELSE MIN(CAST(e.access_count AS REAL) / 50.0, 1.0) END * 0.3
+            + CASE WHEN e.last_accessed_at IS NULL THEN 0.3
+                   ELSE MIN(1.0, 1.0 / (1.0 + (julianday('now') - julianday(e.last_accessed_at)) / 30.0)) END * 0.3
+            DESC`
+        : 'ORDER BY e.id DESC';
+
+      const recentScoringOrderBy = hasScoringCols
+        ? `ORDER BY
+            CASE WHEN confidence IS NULL THEN 0.5 ELSE confidence END * 0.4
+            + CASE WHEN access_count IS NULL THEN 0
+                   ELSE MIN(CAST(access_count AS REAL) / 50.0, 1.0) END * 0.3
+            + CASE WHEN last_accessed_at IS NULL THEN 0.3
+                   ELSE MIN(1.0, 1.0 / (1.0 + (julianday('now') - julianday(last_accessed_at)) / 30.0)) END * 0.3
+            DESC`
+        : 'ORDER BY id DESC';
+
+      // Query project-specific top-N entities by relevance score
       const projectTag = `project:${projectName}`;
       const projectEntities = db.prepare(`
         SELECT DISTINCT e.id, e.name, e.type, e.created_at
         FROM entities e
         JOIN tags t ON t.entity_id = e.id
         WHERE t.tag = ?
-        ORDER BY e.id DESC
-        LIMIT 10
-      `).all(projectTag);
+        ${statusFilter}
+        ${scoringOrderBy}
+        LIMIT ?
+      `).all(projectTag, sessionLimit);
 
-      // Fetch observations for each entity (up to 3 per entity)
-      const getObservations = db.prepare(
-        'SELECT content FROM observations WHERE entity_id = ? ORDER BY id DESC LIMIT 3'
+      // Fetch the first observation for each entity (for concise summary)
+      const getFirstObservation = db.prepare(
+        'SELECT content FROM observations WHERE entity_id = ? ORDER BY id ASC LIMIT 1'
       );
 
-      // Query global recent entities
+      // Query global recent/top entities (exclude project-tagged ones for this project)
       const recentEntities = db.prepare(`
         SELECT id, name, type, created_at
         FROM entities
-        ORDER BY id DESC
+        ${recentStatusFilter}
+        ${recentScoringOrderBy}
         LIMIT 5
       `).all();
 
+      // Format entity as concise bullet: "• name (type): first observation (truncated)"
+      function formatEntity(entity) {
+        const obs = getFirstObservation.get(entity.id);
+        const snippet = obs ? obs.content.slice(0, 100) : '';
+        return snippet
+          ? `• ${entity.name} (${entity.type}): ${snippet}`
+          : `• ${entity.name} (${entity.type})`;
+      }
+
       // Build recall message
       const lines = [];
       if (projectEntities.length > 0) {
-        lines.push(`Project "${projectName}" memories (${projectEntities.length}):`);
+        const label = hasScoringCols ? `top ${projectEntities.length} by relevance` : `${projectEntities.length}`;
+        lines.push(`Project "${projectName}" memories (${label}):`);
         for (const e of projectEntities) {
-          lines.push(`  - [${e.type}] ${e.name}`);
-          const obs = getObservations.all(e.id);
-          for (const o of obs) {
-            lines.push(`    ${o.content}`);
-          }
+          lines.push(formatEntity(e));
         }
       }
       if (recentEntities.length > 0) {
-        lines.push('');
+        if (lines.length > 0) lines.push('');
         lines.push('Recent memories:');
         for (const e of recentEntities) {
-          lines.push(`  - [${e.type}] ${e.name}`);
-          const obs = getObservations.all(e.id);
-          for (const o of obs) {
-            lines.push(`    ${o.content}`);
-          }
+          lines.push(formatEntity(e));
         }
       }
+
+      // No memories at all — output nothing (don't clutter session)
       if (lines.length === 0) {
-        lines.push('MeMesh: No memories found yet. Use remember tool to store knowledge.');
+        return;
       }
 
-      output(lines.join('\n'));
+      const memorySummary = lines.join('\n');
+      const hookOutput = {
+        suppressOutput: true,
+        hookSpecificOutput: {
+          hookEventName: 'SessionStart',
+          additionalContext: memorySummary,
+        },
+      };
+      console.log(JSON.stringify(hookOutput));
     } finally {
       db.close();
     }
   } catch (err) {
     // Hooks must never crash Claude Code — but report honestly
-    output(`MeMesh: Session start failed (${err?.message || 'unknown error'}). Memories not loaded.`);
+    console.log(JSON.stringify({ systemMessage: `MeMesh: Session start failed (${err?.message || 'unknown error'}). Memories not loaded.` }));
   }
 });
 
 function output(text) {
-  console.log(JSON.stringify({ result: text }));
+  console.log(JSON.stringify({ systemMessage: text }));
 }

package/scripts/hooks/session-summary.js

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+
+// Session Auto-Capture — Stop hook
+// Extracts knowledge from completed Claude Code sessions
+// and stores as session-insight entities in MeMesh.
+
+import { createRequire } from 'module';
+import { homedir } from 'os';
+import { join, basename } from 'path';
+import { existsSync, mkdirSync, readFileSync } from 'fs';
+
+const require = createRequire(import.meta.url);
+
+const SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS entities (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT NOT NULL UNIQUE,
+  type TEXT NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  metadata JSON
+);
+
+CREATE TABLE IF NOT EXISTS observations (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  entity_id INTEGER NOT NULL,
+  content TEXT NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (entity_id) REFERENCES entities(id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS relations (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  from_entity_id INTEGER NOT NULL,
+  to_entity_id INTEGER NOT NULL,
+  relation_type TEXT NOT NULL,
+  metadata JSON,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (from_entity_id) REFERENCES entities(id) ON DELETE CASCADE,
+  FOREIGN KEY (to_entity_id) REFERENCES entities(id) ON DELETE CASCADE,
+  UNIQUE(from_entity_id, to_entity_id, relation_type)
+);
+
+CREATE TABLE IF NOT EXISTS tags (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  entity_id INTEGER NOT NULL,
+  tag TEXT NOT NULL,
+  FOREIGN KEY (entity_id) REFERENCES entities(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_tags_entity ON tags(entity_id);
+CREATE INDEX IF NOT EXISTS idx_tags_tag ON tags(tag);
+DELETE FROM tags
+WHERE id NOT IN (
+  SELECT MIN(id)
+  FROM tags
+  GROUP BY entity_id, tag
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_tags_entity_tag_unique ON tags(entity_id, tag);
+CREATE INDEX IF NOT EXISTS idx_observations_entity ON observations(entity_id);
+CREATE INDEX IF NOT EXISTS idx_relations_from ON relations(from_entity_id);
+CREATE INDEX IF NOT EXISTS idx_relations_to ON relations(to_entity_id);
+`;
+
+// Parse a JSONL transcript file.
+// Mirrors logic in src/core/extractor.ts parseTranscript().
+// Defensive: never throws — malformed lines are silently skipped.
+function parseTranscript(transcriptPath) {
+  const filesEdited = new Set();
+  const bashCommands = [];
+  const errorsEncountered = [];
+  let toolCallCount = 0;
+
+  try {
+    const lines = readFileSync(transcriptPath, 'utf8').split('\n').filter(l => l.trim());
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+
+        // Count tool calls
+        if (entry.type === 'tool_use' || entry.tool_name) toolCallCount++;
+
+        // Track file edits (Write, Edit tools)
+        if (entry.tool_name === 'Write' || entry.tool_name === 'Edit') {
+          const inp = entry.tool_input ?? {};
+          const fp = (inp.file_path ?? inp.path);
+          if (fp && typeof fp === 'string') filesEdited.add(basename(fp));
+        }
+
+        // Track meaningful bash commands
+        if (entry.tool_name === 'Bash') {
+          const cmd = (entry.tool_input?.command) ?? '';
+          if (typeof cmd === 'string' && cmd.length > 10 && !cmd.startsWith('ls') && !cmd.startsWith('cd')) {
+            bashCommands.push(cmd.slice(0, 100));
+          }
+        }
+
+        // Track errors from tool results
+        if (entry.type === 'tool_result' && entry.content != null) {
+          const text = typeof entry.content === 'string'
+            ? entry.content
+            : JSON.stringify(entry.content);
+          if (text.includes('Error') || text.includes('FAIL') || text.includes('error:')) {
+            errorsEncountered.push(text.slice(0, 200));
+          }
+        }
+      } catch {
+        // Skip malformed JSONL lines
+      }
+    }
+  } catch {
+    // Transcript unreadable — return empty results
+  }
+
+  return { filesEdited: [...filesEdited], bashCommands, errorsEncountered, toolCallCount };
+}
+
+// Main: read stdin, extract insights, store in DB
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    if (!input.trim()) return exit0();
+
+    // Opt-out check
+    if (process.env.MEMESH_AUTO_CAPTURE === 'false') return exit0();
+
+    let inputData;
+    try {
+      inputData = JSON.parse(input);
+    } catch {
+      return exit0();
+    }
+
+    const sessionId = inputData.session_id || 'unknown';
+    const transcriptPath = inputData.transcript_path;
+    const cwd = inputData.cwd || process.cwd();
+    const stopReason = inputData.stop_reason || 'unknown';
+    const wasAgenticLoop = inputData.was_in_agentic_loop === true;
+
+    // Guards: skip low-signal sessions
+    if (stopReason === 'user_interrupt') return exit0();
+    if (!wasAgenticLoop) return exit0();
+    if (!transcriptPath || !existsSync(transcriptPath)) return exit0();
+
+    // Parse transcript
+    const { filesEdited, bashCommands, errorsEncountered, toolCallCount } = parseTranscript(transcriptPath);
+
+    // Skip sessions with too little activity
+    if (toolCallCount < 3) return exit0();
+
+    // Open DB
+    const dbPath = process.env.MEMESH_DB_PATH || join(homedir(), '.memesh', 'knowledge-graph.db');
+    const dbDir = process.env.MEMESH_DB_PATH
+      ? join(process.env.MEMESH_DB_PATH, '..')
+      : join(homedir(), '.memesh');
+    if (!existsSync(dbDir)) mkdirSync(dbDir, { recursive: true });
+
+    const Database = require('better-sqlite3');
+    const sqliteVec = require('sqlite-vec');
+
+    const db = new Database(dbPath);
+    try {
+      db.pragma('journal_mode = WAL');
+      db.pragma('foreign_keys = ON');
+
+      // Ensure schema exists (tables may already exist from MeMesh server)
+      db.exec(SCHEMA_SQL);
+
+      // Migrate: add status column if missing (v2.11 -> v2.12)
+      const cols = db.prepare("PRAGMA table_info(entities)").all();
+      if (!cols.some(c => c.name === 'status')) {
+        db.exec("ALTER TABLE entities ADD COLUMN status TEXT NOT NULL DEFAULT 'active'");
+        db.exec("CREATE INDEX IF NOT EXISTS idx_entities_status ON entities(status)");
+      }
+
+      // Load sqlite-vec extension
+      sqliteVec.load(db);
+
+      // Duplicate detection: if we already captured this session, bail
+      const shortId = sessionId.slice(0, 8);
+      const alreadyCaptured = db.prepare("SELECT id FROM entities WHERE name = ?").get(`session-${shortId}-files`);
+      if (alreadyCaptured) return exit0();
+
+      // Build and store session memories
+      const projectName = basename(cwd);
+      const baseTags = ['source:auto-capture', `session:${shortId}`, `project:${projectName}`];
+
+      const insertEntity = db.prepare('INSERT OR IGNORE INTO entities (name, type) VALUES (?, ?)');
+      const selectEntity = db.prepare('SELECT id FROM entities WHERE name = ?');
+      const insertObs = db.prepare('INSERT INTO observations (entity_id, content) VALUES (?, ?)');
+      const insertTag = db.prepare('INSERT OR IGNORE INTO tags (entity_id, tag) VALUES (?, ?)');
+
+      function storeMemory(name, type, observations, tags) {
+        insertEntity.run(name, type);
+        const row = selectEntity.get(name);
+        if (!row) return;
+        for (const obs of observations) insertObs.run(row.id, obs);
+        for (const tag of tags) insertTag.run(row.id, tag);
+      }
+
+      // Rule 1: File editing session summary
+      if (filesEdited.length > 0) {
+        storeMemory(
+          `session-${shortId}-files`,
+          'session-insight',
+          [
+            `Session edited ${filesEdited.length} file(s): ${filesEdited.join(', ')}`,
+            `Total tool calls: ${toolCallCount}`,
+          ],
+          baseTags
+        );
+      }
+
+      // Rule 2: Error -> Fix pattern detection
+      if (errorsEncountered.length > 0 && filesEdited.length > 0) {
+        storeMemory(
+          `session-${shortId}-fixes`,
+          'session-insight',
+          [
+            `Fixed ${errorsEncountered.length} error(s) by editing ${filesEdited.join(', ')}`,
+            ...errorsEncountered.slice(0, 3).map(e => `Error: ${e.slice(0, 100)}`),
+          ],
+          [...baseTags, 'type:bugfix']
+        );
+      }
+
+      // Rule 3: Heavy session summary (20+ tool calls = significant work)
+      if (toolCallCount >= 20) {
+        storeMemory(
+          `session-${shortId}-summary`,
+          'session-insight',
+          [
+            `Significant session: ${toolCallCount} tool calls, ${filesEdited.length} files edited`,
+            ...bashCommands.slice(0, 3).map(c => `Command: ${c}`),
+          ],
+          [...baseTags, 'type:heavy-session']
+        );
+      }
+    } finally {
+      db.close();
+    }
+  } catch (err) {
+    // Never crash Claude Code — leave a trace for debugging
+    try { process.stderr.write(`[memesh session-summary] ${err?.message || err}\n`); } catch {}
+  }
+
+  // Silent output — don't clutter Claude's response
+  console.log(JSON.stringify({ suppressOutput: true }));
+  exit0();
+});
+
+function exit0() {
+  process.exit(0);
+}

package/skills/memesh/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: memesh
+description: Use MeMesh to remember, recall, and manage AI knowledge across sessions. Triggers when the user asks to remember something, recall past decisions, forget outdated info, or manage their memory. Also triggers proactively when you make important decisions, fix bugs, or learn lessons worth preserving.
+user-invocable: true
+---
+
+# MeMesh — AI Memory Management
+
+You have access to MeMesh, a persistent memory layer with 6 tools. Use them to remember important knowledge across sessions.
+
+## When to Use (Proactive)
+
+**Remember automatically when:**
+- A design decision is made ("let's use OAuth" → remember it)
+- A bug is fixed (root cause + fix → remember as lesson)
+- A pattern is established ("we always use Zod for validation" → remember as pattern)
+- Architecture changes ("moved from monolith to microservices" → remember)
+- The user explicitly says "remember this" or "don't forget"
+
+**Recall automatically when:**
+- Starting work on a feature that might have prior decisions
+- The user asks "what did we decide about X?"
+- You need context about a project's conventions
+
+**Forget when:**
+- A decision is superseded by a new one (use `supersedes` relation)
+- The user says "forget about X" or "that's outdated"
+
+## Tools Reference
+
+### remember
+```json
+{
+  "name": "auth-decision",
+  "type": "decision",
+  "observations": ["Use OAuth 2.0 with PKCE for authentication"],
+  "tags": ["project:myapp", "topic:auth"],
+  "relations": [{"to": "old-auth", "type": "supersedes"}]
+}
+```
+Types: `decision`, `pattern`, `lesson`, `bug_fix`, `architecture`, `convention`
+
+### recall
+```json
+{"query": "authentication", "tag": "project:myapp", "limit": 10}
+```
+Omit query to list recent memories. Results are ranked by relevance, recency, and access frequency.
+
+### forget
+```json
+{"name": "outdated-design"}
+```
+Archives the entity (soft-delete). Add `"observation": "specific text"` to remove just one fact.
+
+### consolidate
+```json
+{"name": "auth-history", "min_observations": 5}
+```
+Compresses verbose memories using LLM. Requires Smart Mode configured.
+
+### export / import
+```json
+{"tag": "project:myapp"}
+```
+Export memories as JSON for sharing. Import with merge strategies: `skip`, `overwrite`, `append`.
+
+## Best Practices
+
+1. **Be specific** — "Use OAuth 2.0 with PKCE" not "auth stuff decided"
+2. **Tag by project** — Always include `project:<name>` tag
+3. **Use relations** — Link related decisions with `related-to`, replace old ones with `supersedes`
+4. **Type correctly** — Use the right type (decision/pattern/lesson) for better search
+5. **Don't over-remember** — Skip trivial things. Remember decisions that took > 5 minutes to make.