mcvay-mind 1.0.0

package/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: mcvay-mind
+description: Typed memory system with YAML schemas, full-text search, wiki-link extraction, and proactive context surfacing for OpenClaw agents
+---
+
+# McVay Mind - Typed Memory System
+
+A typed memory system for OpenClaw agents with YAML schemas, full-text search, wiki-link extraction, and proactive context surfacing.
+
+## Quick Start
+
+```bash
+# Add a memory
+node ~/.openclaw/skills/mcvay-mind/index.js add --type preference --title "User prefers concise" --content "User wants responses under 3 sentences"
+
+# Query memories
+node ~/.openclaw/skills/mcvay-mind/index.js query --type preference --days 7
+
+# Search all memories
+node ~/.openclaw/skills/mcvay-mind/index.js search "user preference"
+
+# Rebuild indexes
+node ~/.openclaw/skills/mcvay-mind/index.js rebuild-indexes
+
+# Validate schema
+node ~/.openclaw/skills/mcvay-mind/index.js validate
+```
+
+## Memory Types
+
+| Type | Directory | Purpose |
+|------|-----------|---------|
+| `decision` | `memory/typed/decisions/` | Choices made, rationale |
+| `preference` | `memory/typed/preferences/` | Likes, dislikes, wants |
+| `relationship` | `memory/typed/relationships/` | People, roles, connections |
+| `commitment` | `memory/typed/commitments/` | Promises, follow-ups, todos |
+| `lesson` | `memory/typed/lessons/` | Learnings, mistakes, insights |
+| `task` | `memory/typed/tasks/` | Work items, action items |
+| `project` | `memory/typed/projects/` | Projects, initiatives |
+
+## Schema Templates
+
+Located in `~/.openclaw/skills/mcvay-mind/schema/`:
+
+- `base.yaml` — Base schema all types extend
+- `decision.yaml`, `preference.yaml`, `relationship.yaml`, `commitment.yaml`, `lesson.yaml`, `task.yaml`
+
+## Core Modules (in this skill)
+
+```javascript
+const store = require('~/.openclaw/skills/mcvay-mind/lib/store');
+const search = require('~/.openclaw/skills/mcvay-mind/lib/search');
+const entityLinker = require('~/.openclaw/skills/mcvay-mind/lib/entity-linker');
+```
+
+## Unified Commands
+
+All memory operations are now in this skill:
+
+```bash
+# Add memory
+node ~/.openclaw/skills/mcvay-mind/index.js add --type preference --title "Title" --content "Content"
+
+# Query by type
+node ~/.openclaw/skills/mcvay-mind/index.js query --type preference --days 7
+
+# Search (unified)
+node ~/.openclaw/skills/mcvay-mind/index.js search "query terms"
+
+# Active recall (context surfacing)
+node ~/.openclaw/skills/mcvay-mind/index.js recall "topic"
+
+# Entity linking
+node ~/.openclaw/skills/mcvay-mind/index.js link
+```
+
+// Add memory
+await store.addMemory({
+  type: 'preference',
+  title: 'No football emojis',
+  content: 'User prefers no football emojis in responses',
+  tags: ['preference', 'communication'],
+  confidence: 90
+});
+
+// Query by type
+const prefs = await store.queryMemories({ type: 'preference', days: 7 });
+
+// Full-text search
+const results = await search.searchMemories({
+  query: 'user preference concise',
+  types: ['preference', 'lesson'],
+  limit: 5
+});
+
+// Active recall - context surfacing
+const memories = await activeRecall('conversation topic');
+
+// Proactive search - search before responding
+const context = await searchMemories({ query: userQuestion });
+```
+
+## Proactive Search (MANDATORY)
+
+Before ANY response, agents MUST search for relevant context:
+
+```bash
+# CLI
+npx tsx skills/proactive-memory/search.ts --query "user question"
+```
+
+```typescript
+// Programmatic
+import { searchMemories } from './skills/proactive-memory/search';
+const context = await searchMemories({ query: userMessage });
+```
+
+### When to Search
+
+1. **Responding to questions** - Find relevant context first
+2. **Troubleshooting errors** - Look for similar past issues
+3. **Facing problems** - Search for solutions
+4. **Making decisions** - Check past decisions
+5. **User corrections** - Find related lessons
+
+## Entity Linking
+
+The system automatically extracts wiki-links `[[type/slug]]` from memories and builds a knowledge graph.
+
+```bash
+# Extract links and rebuild graph
+node ~/.openclaw/skills/mcvay-mind/index.js link
+```
+
+## Memory Format
+
+```yaml
+---
+title: "Memory Title"
+type: preference
+created: 2026-02-16T12:00:00.000Z
+updated: 2026-02-16T12:00:00.000Z
+tags: [tag1, tag2]
+links: [decision/choice-1, preference/user-pref]
+confidence: 90
+source: agent
+---
+
+# Memory Title
+## Content
+
+Your memory content here.
+```
+
+## Configuration
+
+Set custom workspace:
+```bash
+export MCVAY_MIND_CWD=/path/to/workspace
+```
+
+## Integrations
+
+### AGENTS.md Integration
+
+Add to startup:
+```markdown
+## Before ANY Response (MANDATORY)
+
+Run proactive memory search:
+npx tsx skills/proactive-memory/search.ts --query "<user question>"
+
+Include relevant memories in your response.
+```
+
+### Active Recall Triggers
+
+Keywords that should trigger recall:
+- "remember", "recall", "what do you know about"
+- Project names
+- People names
+
+## Files
+
+```
+~/.openclaw/skills/mcvay-mind/
+├── index.js           # CLI entry point
+├── lib/
+│   ├── store.js       # Memory CRUD operations
+│   ├── search.js      # Full-text search
+│   └── entity-linker.js # Wiki-link extraction & knowledge graph
+└── schema/            # YAML schemas
+    ├── base.yaml
+    ├── decision.yaml
+    ├── preference.yaml
+    ├── relationship.yaml
+    ├── commitment.yaml
+    ├── lesson.yaml
+    └── task.yaml
+```

package/index.js

@@ -0,0 +1,344 @@
+#!/usr/bin/env node
+
+/**
+ * McVay Mind Memory System
+ * 
+ * A typed memory system for OpenClaw agents
+ * 
+ * Usage:
+ *   node index.js add --type <type> --title "<title>" --content "<content>" [options]
+ *   node index.js query --type <type> [--search "query"] [--days 7]
+ *   node index.js search "<query>" [--types preference,lesson]
+ *   node index.js recall "topic"
+ *   node index.js link
+ *   node index.js validate
+ *   node index.js rebuild-indexes
+ */
+
+const path = require('path');
+const store = require('./lib/store');
+const search = require('./lib/search');
+const entityLinker = require('./lib/entity-linker');
+const activeRecall = require('./lib/active-recall');
+
+// ============================================================================
+// CLI Handler
+// ============================================================================
+
+const args = process.argv.slice(2);
+const cwd = process.env.MCVAY_MIND_CWD || process.cwd();
+
+function main() {
+  if (args.length === 0) {
+    printUsage();
+    return;
+  }
+
+  const command = args[0];
+
+  switch (command) {
+    case 'add':
+      handleAdd();
+      break;
+    case 'query':
+    case 'search':
+      handleQuery();
+      break;
+    case 'recall':
+    case 'active-recall':
+      handleActiveRecall();
+      break;
+    case 'link':
+    case 'entity-link':
+      handleEntityLink();
+      break;
+    case 'backlinks':
+      handleBacklinks();
+      break;
+    case 'validate':
+      handleValidate();
+      break;
+    case 'rebuild-indexes':
+      handleRebuildIndexes();
+      break;
+    case 'help':
+      printUsage();
+      break;
+    default:
+      // Try to treat as a search query
+      handleQuery([command, ...args.slice(1)]);
+  }
+}
+
+function printUsage() {
+  console.log(`
+McVay Mind Memory System
+=======================
+
+Usage:
+  node index.js add --type <type> --title "<title>" --content "<content>" [options]
+  node index.js query --type <type> [--days 7]
+  node index.js search "<query>" [--types type1,type2]
+  node index.js recall "topic"
+  node index.js link
+  node index.js validate
+  node index.js rebuild-indexes
+
+Types: decision, preference, relationship, commitment, lesson, task, project
+
+Options:
+  --type <type>         Memory type
+  --title "<title>"    Memory title
+  --content "<text>"   Memory content
+  --tags <tag1,tag2>  Comma-separated tags
+  --confidence <n>    Confidence level (0-100)
+  --days <n>          Limit to last N days
+  --limit <n>         Max results to return
+
+Examples:
+  node index.js add --type preference --title "Example: concise responses" --content "This user prefers short responses" --tags preference,communication
+  node index.js search "user preference" --types preference,lesson
+  node index.js recall "codex coding"
+`);
+}
+
+// ============================================================================
+// Argument Parsing
+// ============================================================================
+
+function parseArgs(argList = args.slice(1)) {
+  const options = {};
+  let i = 0;
+  while (i < argList.length) {
+    const arg = argList[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const value = argList[i + 1];
+      if (value && !value.startsWith('--')) {
+        options[key] = value;
+        i += 2;
+      } else {
+        options[key] = 'true';
+        i++;
+      }
+    } else if (!arg.startsWith('-')) {
+      // Positional arg
+      if (!options._) options._ = [];
+      options._.push(arg);
+      i++;
+    } else {
+      i++;
+    }
+  }
+  return options;
+}
+
+// ============================================================================
+// Command Handlers
+// ============================================================================
+
+function handleAdd() {
+  const options = parseArgs(args.slice(1));
+  const { type, title, content, tags, confidence, source, ...extra } = options;
+  
+  if (!type || !title || !content) {
+    console.error('Error: --type, --title, and --content are required');
+    process.exit(1);
+  }
+  
+  const tagList = tags ? tags.split(',').map(t => t.trim()) : [];
+  const conf = confidence ? parseInt(confidence, 10) : 80;
+  
+  const extraFields = {};
+  for (const [key, value] of Object.entries(extra)) {
+    if (key !== '_') {
+      extraFields[key] = value;
+    }
+  }
+  
+  const result = store.ingest({
+    type,
+    title,
+    content,
+    tags: tagList,
+    confidence: conf,
+    source: source || 'agent',
+    ...extraFields
+  }, cwd);
+  
+  if (result.success) {
+    console.log(`✓ Memory ingested: ${result.slug}`);
+  } else {
+    console.error('✗ Error ingesting memory:');
+    for (const err of result.errors || []) {
+      console.error(`  - ${err.field}: ${err.message}`);
+    }
+    process.exit(1);
+  }
+}
+
+async function handleQuery(argList = null) {
+  const options = parseArgs(argList || args.slice(1));
+  const { type, search: searchTerm, types, days, limit, 'min-confidence': minConf, _ } = options;
+  
+  const queryText = searchTerm || (_ && _.length > 0 ? _.join(' ') : null);
+  
+  if (queryText) {
+    const typeList = types ? types.split(',') : (type ? [type] : undefined);
+    const results = await search.searchMemories({
+      query: queryText,
+      types: typeList,
+      days: days ? parseInt(days, 10) : undefined,
+      limit: limit ? parseInt(limit, 10) : 10,
+      minConfidence: minConf ? parseInt(minConf, 10) : undefined
+    }, cwd);
+    
+    console.log(search.formatResults(results));
+  } else if (type || types) {
+    const typeList = (types || type).split(',');
+    const results = store.queryMemories({
+      type: typeList[0],
+      days: days ? parseInt(days, 10) : undefined,
+      limit: limit ? parseInt(limit, 10) : 50,
+      minConfidence: minConf ? parseInt(minConf, 10) : undefined
+    }, cwd);
+    
+    if (results.length === 0) {
+      console.log('No memories found.');
+      return;
+    }
+    
+    console.log(`Found ${results.length} memory(ies):\n`);
+    
+    const icon = {
+      decision: '📝', preference: '⚙️', lesson: '📚',
+      commitment: '✅', relationship: '👤', task: '🎯', project: '📁'
+    };
+    
+    for (const r of results) {
+      const fm = r.frontmatter;
+      const date = fm.created ? new Date(fm.created).toISOString().split('T')[0] : 'unknown';
+      console.log(`${icon[r.type] || '📌'} [${r.type}] ${fm.title} (confidence: ${fm.confidence || 'N/A'})`);
+      console.log(`  ${date} | ${r.slug}`);
+      if (fm.tags && fm.tags.length > 0) {
+        console.log(`  Tags: ${fm.tags.join(', ')}`);
+      }
+      console.log('');
+    }
+  } else {
+    console.error('Error: --search or --type is required');
+    process.exit(1);
+  }
+}
+
+function handleActiveRecall() {
+  const options = parseArgs(args.slice(1));
+  const { query, _ } = options;
+  
+  const queryText = query || (_ && _.length > 0 ? _.join(' ') : null);
+  
+  if (!queryText) {
+    console.log('Usage: node index.js recall "topic"');
+    console.log('   or: node index.js recall --query "topic"');
+    process.exit(1);
+  }
+  
+  activeRecall.activeRecall(queryText).then(data => {
+    console.log(activeRecall.formatResults(data));
+  }).catch(err => {
+    console.error('Error:', err.message);
+    process.exit(1);
+  });
+}
+
+function handleEntityLink() {
+  entityLinker.runEntityLinker(cwd);
+}
+
+function handleBacklinks() {
+  const options = parseArgs(args.slice(1));
+  const slug = options._ && options._[0] ? options._[0] : options.backlinks;
+  
+  if (!slug) {
+    console.error('Usage: node index.js backlinks <slug>');
+    process.exit(1);
+  }
+  
+  const backlinks = store.getBacklinks(slug, cwd);
+  const forwardLinks = store.getForwardLinks(slug, cwd);
+  
+  console.log(`Links for: ${slug}\n`);
+  console.log(`Backlinks (${backlinks.length}):`);
+  for (const l of backlinks) {
+    console.log(`  ← ${l}`);
+  }
+  console.log(`\nForward Links (${forwardLinks.length}):`);
+  for (const l of forwardLinks) {
+    console.log(`  → ${l}`);
+  }
+}
+
+function handleValidate() {
+  const errors = store.validateAll(cwd);
+  
+  if (errors.length === 0) {
+    console.log('✓ All memories are valid.');
+  } else {
+    console.error(`✗ Found ${errors.length} validation error(s):`);
+    for (const err of errors) {
+      console.error(`  - ${err.file}: ${err.error}`);
+    }
+    process.exit(1);
+  }
+}
+
+function handleRebuildIndexes() {
+  console.log('Rebuilding indexes...');
+  store.rebuildIndexes(cwd);
+  console.log('✓ Indexes rebuilt.');
+}
+
+// ============================================================================
+// Export for programmatic use
+// ============================================================================
+
+module.exports = {
+  store,
+  search: {
+    searchMemories: search.searchMemories,
+    searchForUserQuestion: search.searchForUserQuestion,
+    searchForError: search.searchForError,
+    searchRecentPreferences: search.searchRecentPreferences,
+    searchRecentLessons: search.searchRecentLessons,
+    searchRecentCommitments: search.searchRecentCommitments,
+    formatResults: search.formatResults,
+  },
+  entityLinker: {
+    runEntityLinker: entityLinker.runEntityLinker,
+  },
+  activeRecall: {
+    recall: activeRecall.activeRecall,
+    extractKeywords: activeRecall.extractKeywords,
+  },
+  onUserCorrection: (correction, original, context) => store.ingest({
+    type: 'lesson',
+    title: `User correction: ${correction.substring(0, 50)}`,
+    content: `Original: ${original}\nCorrection: ${correction}\n\nContext: ${context || 'N/A'}`,
+    tags: ['correction', 'lesson'],
+    source: 'agent',
+    lesson_type: 'correction'
+  }, cwd),
+  onError: (error, context) => store.ingest({
+    type: 'lesson',
+    title: `Error: ${error.substring(0, 50)}`,
+    content: error,
+    tags: ['error', 'tool-failure'],
+    source: 'agent',
+    lesson_type: 'error'
+  }, cwd),
+  VALID_TYPES: store.VALID_TYPES,
+  TYPE_DIRS: store.TYPE_DIRS,
+};
+
+// Run if called directly
+main();

package/lib/active-recall.js

@@ -0,0 +1,168 @@
+/**
+ * Active Recall - Context Surfacing
+ * Proactively surfaces relevant memories during conversations
+ */
+
+const store = require('./store');
+
+// Stop words for keyword extraction
+const STOP_WORDS = new Set([
+  'the', 'a', 'an', 'is', 'are', 'was', 'were', 'do', 'does', 'did', 
+  'what', 'how', 'why', 'when', 'where', 'who', 'can', 'could', 
+  'would', 'should', 'to', 'of', 'in', 'on', 'at', 'for', 'with', 'about'
+]);
+
+/**
+ * Extract keywords from query
+ */
+function extractKeywords(query) {
+  return query.toLowerCase()
+    .replace(/[^\w\s]/g, ' ')
+    .split(/\s+/)
+    .filter(w => w.length > 2 && !STOP_WORDS.has(w));
+}
+
+/**
+ * Score memory relevance
+ */
+function scoreMemory(memory, keywords) {
+  let score = parseInt(memory.frontmatter?.confidence || '50', 10);
+  
+  // Boost for keyword matches in title
+  const title = (memory.frontmatter?.title || '').toLowerCase();
+  for (const kw of keywords) {
+    if (title.includes(kw)) score += 20;
+  }
+  
+  // Boost for recency (newer = better)
+  if (memory.frontmatter?.created) {
+    const daysOld = (Date.now() - new Date(memory.frontmatter.created).getTime()) / (1000 * 60 * 60 * 24);
+    if (daysOld < 1) score += 10;
+    else if (daysOld < 7) score += 5;
+  }
+  
+  return Math.min(score, 100);
+}
+
+/**
+ * Query memory for related memories
+ */
+function queryMemoryGraph(keywords) {
+  const results = [];
+  
+  for (const kw of keywords) {
+    const matches = store.queryMemories({ search: kw, limit: 50 });
+    results.push(...matches);
+  }
+  
+  // Deduplicate by slug
+  const seen = new Set();
+  const unique = [];
+  for (const r of results) {
+    if (!seen.has(r.slug)) {
+      seen.add(r.slug);
+      unique.push(r);
+    }
+  }
+  
+  return unique;
+}
+
+/**
+ * Main active recall function
+ */
+async function activeRecall(query) {
+  if (!query) {
+    return { error: 'No query provided' };
+  }
+  
+  const keywords = extractKeywords(query);
+  
+  // Query memory
+  const graphResults = queryMemoryGraph(keywords);
+  
+  // Score and sort
+  const scored = graphResults.map(m => ({
+    ...m,
+    score: scoreMemory(m, keywords),
+    forwardLinks: store.getForwardLinks(m.slug).length,
+    backlinks: store.getBacklinks(m.slug).length
+  })).filter(m => m.score > 30);
+  
+  scored.sort((a, b) => b.score - a.score);
+  
+  // Format results
+  const icons = {
+    decision: '📝',
+    preference: '⚙️',
+    lesson: '📚',
+    commitment: '✅',
+    relationship: '👤',
+    task: '🎯',
+    project: '📁'
+  };
+  
+  const results = scored.slice(0, 10).map(m => ({
+    icon: icons[m.type] || '📌',
+    type: m.type,
+    title: m.frontmatter?.title,
+    confidence: m.frontmatter?.confidence || '50',
+    related: m.forwardLinks + m.backlinks,
+    summary: m.content?.substring(0, 200) || '',
+    source: `memory/typed/${m.type}s/${m.slug}.md`
+  }));
+  
+  return {
+    query,
+    keywords,
+    count: results.length,
+    results
+  };
+}
+
+/**
+ * Format for CLI output
+ */
+function formatResults(data) {
+  if (data.error) {
+    return `Error: ${data.error}`;
+  }
+  
+  if (data.count === 0) {
+    return `No relevant memories found for "${data.query}"`;
+  }
+  
+  let output = `\n🎯 Active Recall: "${data.query}"\n`;
+  output += `Found ${data.count} relevant memories:\n\n`;
+  
+  for (const r of data.results) {
+    output += `${r.icon} [${r.type}] ${r.title}\n`;
+    output += `   Confidence: ${r.confidence}% | Related: ${r.related} connections\n`;
+    output += `   ${r.summary.substring(0, 100)}...\n`;
+    output += `   Source: ${r.source}\n\n`;
+  }
+  
+  return output;
+}
+
+// CLI handler - only run if called directly
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const queryArg = args.findIndex(a => a === '--query' || a === '-q');
+  const query = queryArg >= 0 ? args[queryArg + 1] : args.join(' ');
+
+  if (!query) {
+    console.log('Usage: node lib/active-recall.js --query "topic"');
+    console.log('   or: node lib/active-recall.js "topic phrase"');
+    process.exit(1);
+  }
+
+  activeRecall(query).then(data => {
+    console.log(formatResults(data));
+  }).catch(err => {
+    console.error('Error:', err.message);
+    process.exit(1);
+  });
+}
+
+module.exports = { activeRecall, extractKeywords, scoreMemory, formatResults };