grimoire-framework 1.4.1 → 1.6.0

package/.grimoire/install-manifest.yaml

@@ -7,8 +7,8 @@
 # - SHA256 hashes for change detection
 # - File types for categorization
 #
-version: 1.4.1
-generated_at: "2026-02-22T17:28:34.901Z"
+version: 1.6.0
+generated_at: "2026-02-22T17:57:17.499Z"
 generator: scripts/generate-install-manifest.js
 file_count: 1011
 files:

package/bin/commands/context.js

@@ -0,0 +1,319 @@
+/**
+ * grimoire context — Live Context Manager
+ *
+ * grimoire context update     Regenera CONTEXT.md a partir de todos os .jsonl
+ * grimoire context show       Exibe CONTEXT.md no terminal
+ * grimoire context clean       Remove arquivos context/ gerados
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+// ── Paths ─────────────────────────────────────────────────────────────────────
+function findGrimoireDir() {
+    const cwd = process.cwd();
+    const direct = path.join(cwd, '.grimoire');
+    const sub = path.join(cwd, 'grimoire', '.grimoire');
+    if (fs.existsSync(direct)) return direct;
+    if (fs.existsSync(sub)) return sub;
+    return null;
+}
+
+function getGlobalMemoryDir() {
+    const d = path.join(os.homedir(), '.grimoire', 'memory');
+    if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+    return d;
+}
+
+function getContextDir(grimoireDir) {
+    const d = path.join(grimoireDir, 'context');
+    if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+    return d;
+}
+
+// ── Load all memory entries ───────────────────────────────────────────────────
+function loadAllEntries(grimoireDir, includeGlobal = true) {
+    const entries = [];
+
+    // Local sessions
+    const sessionsDir = path.join(grimoireDir, 'memory', 'sessions');
+    if (fs.existsSync(sessionsDir)) {
+        for (const f of fs.readdirSync(sessionsDir).filter(f => f.endsWith('.jsonl')).sort()) {
+            const raw = fs.readFileSync(path.join(sessionsDir, f), 'utf8');
+            for (const line of raw.split('\n').filter(l => l.trim())) {
+                try { entries.push({ ...JSON.parse(line), date: f.slice(0, 10), source: 'local' }); } catch (_) { }
+            }
+        }
+    }
+
+    // Pinned (local)
+    const pinnedFile = path.join(grimoireDir, 'memory', 'pinned.jsonl');
+    if (fs.existsSync(pinnedFile)) {
+        const raw = fs.readFileSync(pinnedFile, 'utf8');
+        for (const line of raw.split('\n').filter(l => l.trim())) {
+            try { entries.push({ ...JSON.parse(line), source: 'pinned' }); } catch (_) { }
+        }
+    }
+
+    // Global
+    if (includeGlobal) {
+        const globalFile = path.join(getGlobalMemoryDir(), 'global.jsonl');
+        if (fs.existsSync(globalFile)) {
+            const raw = fs.readFileSync(globalFile, 'utf8');
+            for (const line of raw.split('\n').filter(l => l.trim())) {
+                try { entries.push({ ...JSON.parse(line), source: 'global' }); } catch (_) { }
+            }
+        }
+    }
+
+    return entries;
+}
+
+// ── Build Markdown files ──────────────────────────────────────────────────────
+function buildContextMd(entries) {
+    const now = new Date().toISOString().split('T')[0];
+    const pinned = entries.filter(e => e.source === 'pinned');
+    const recent = entries.filter(e => e.source !== 'pinned').slice(-20).reverse();
+    const globals = entries.filter(e => e.source === 'global').slice(-10).reverse();
+
+    const lines = [];
+    lines.push(`# 🧠 Contexto do Projeto\n`);
+    lines.push(`> Auto-gerado em ${now} via \`grimoire context update\`\n`);
+
+    if (pinned.length) {
+        lines.push(`## 📌 Fixadas\n`);
+        pinned.forEach(e => lines.push(`- ${e.content}`));
+        lines.push('');
+    }
+
+    const decisions = recent.filter(e => e.tag === 'decisão' || e.tag === 'decisao' || e.tag === 'decision');
+    if (decisions.length) {
+        lines.push(`## ✅ Últimas Decisões\n`);
+        decisions.slice(0, 8).forEach(e => lines.push(`- **${e.date || ''}** ${e.content}`));
+        lines.push('');
+    }
+
+    const patterns = recent.filter(e => e.tag === 'padrão' || e.tag === 'padrao' || e.tag === 'pattern');
+    if (patterns.length) {
+        lines.push(`## 🔧 Padrões Estabelecidos\n`);
+        patterns.slice(0, 8).forEach(e => lines.push(`- **${e.date || ''}** ${e.content}`));
+        lines.push('');
+    }
+
+    const other = recent.filter(e => !['decisão', 'decisao', 'decision', 'padrão', 'padrao', 'pattern'].includes(e.tag));
+    if (other.length) {
+        lines.push(`## 📝 Entradas Recentes\n`);
+        other.slice(0, 10).forEach(e => {
+            const tag = e.tag ? ` \`#${e.tag}\`` : '';
+            const src = e.source === 'global' ? ' 🌐' : '';
+            lines.push(`- **${e.date || ''}** ${e.content}${tag}${src}`);
+        });
+        lines.push('');
+    }
+
+    if (globals.length) {
+        lines.push(`## 🌐 Memória Global (cross-projeto)\n`);
+        globals.slice(0, 5).forEach(e => {
+            const tag = e.tag ? ` \`#${e.tag}\`` : '';
+            lines.push(`- ${e.content}${tag}`);
+        });
+        lines.push('');
+    }
+
+    return lines.join('\n');
+}
+
+function buildTagMd(entries, tag, title, emoji) {
+    const variants = [tag, tag.normalize('NFD').replace(/[\u0300-\u036f]/g, '')];
+    const filtered = entries.filter(e => variants.includes(e.tag)).slice(-30).reverse();
+    if (!filtered.length) return null;
+
+    const lines = [`# ${emoji} ${title}\n`, `> Auto-gerado pelo Grimoire\n`];
+    filtered.forEach(e => {
+        const src = e.source === 'global' ? ' 🌐' : '';
+        lines.push(`- **${e.date || ''}** ${e.content}${src}`);
+    });
+    return lines.join('\n');
+}
+
+// ── Inject into GEMINI.md ─────────────────────────────────────────────────────
+const MARKER_START = '<!-- grimoire-MANAGED-START: memory-context -->';
+const MARKER_END = '<!-- grimoire-MANAGED-END: memory-context -->';
+
+function buildGeminiBlock(entries) {
+    const now = new Date().toISOString().split('T')[0];
+    const pinned = entries.filter(e => e.source === 'pinned');
+    const recent = entries.filter(e => e.source !== 'pinned').slice(-15).reverse();
+    const decisions = recent.filter(e => ['decisão', 'decisao', 'decision'].includes(e.tag)).slice(0, 5);
+    const patterns = recent.filter(e => ['padrão', 'padrao', 'pattern'].includes(e.tag)).slice(0, 5);
+
+    const block = [];
+    block.push(MARKER_START);
+    block.push(`## 🧠 Contexto do Projeto (auto-gerado)\n`);
+
+    if (pinned.length) {
+        block.push(`### 📌 Fixadas\n`);
+        pinned.forEach(e => block.push(`- ${e.content}`));
+        block.push('');
+    }
+
+    if (decisions.length) {
+        block.push(`### ✅ Últimas decisões\n`);
+        decisions.forEach(e => block.push(`- ${e.date}: ${e.content}`));
+        block.push('');
+    }
+
+    if (patterns.length) {
+        block.push(`### 🔧 Padrões\n`);
+        patterns.forEach(e => block.push(`- ${e.date}: ${e.content}`));
+        block.push('');
+    }
+
+    // Any other recent entries without special tag
+    const others = recent.filter(e => !['decisão', 'decisao', 'decision', 'padrão', 'padrao', 'pattern'].includes(e.tag)).slice(0, 5);
+    if (others.length) {
+        block.push(`### 📝 Recentes\n`);
+        others.forEach(e => {
+            const tag = e.tag ? ` [#${e.tag}]` : '';
+            block.push(`- ${e.date}: ${e.content}${tag}`);
+        });
+        block.push('');
+    }
+
+    block.push(`> _Atualizado em ${now}. Use \`grimoire context update\` para regenerar._`);
+    block.push(MARKER_END);
+    return block.join('\n');
+}
+
+function injectIntoGeminiMd(grimoireDir, entries) {
+    // GEMINI.md can be at project root or parent
+    const cwd = process.cwd();
+    const candidates = [
+        path.join(cwd, 'GEMINI.md'),
+        path.join(path.dirname(grimoireDir), 'GEMINI.md'),
+    ];
+    const geminiPath = candidates.find(p => fs.existsSync(p));
+    if (!geminiPath) return false;
+
+    const original = fs.readFileSync(geminiPath, 'utf8');
+    const newBlock = buildGeminiBlock(entries);
+
+    let updated;
+    if (original.includes(MARKER_START)) {
+        // Replace existing block
+        const re = new RegExp(`${regEscape(MARKER_START)}[\\s\\S]*?${regEscape(MARKER_END)}`, 'g');
+        updated = original.replace(re, newBlock);
+    } else {
+        // Append before last ---
+        const lastHr = original.lastIndexOf('\n---');
+        if (lastHr !== -1) {
+            updated = original.slice(0, lastHr) + '\n\n' + newBlock + '\n' + original.slice(lastHr);
+        } else {
+            updated = original + '\n\n' + newBlock + '\n';
+        }
+    }
+
+    if (updated !== original) {
+        fs.writeFileSync(geminiPath, updated, 'utf8');
+        return true;
+    }
+    return false;
+}
+
+function regEscape(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// ── Core update logic ─────────────────────────────────────────────────────────
+function doUpdate(grimoireDir, silent = false) {
+    const contextDir = getContextDir(grimoireDir);
+    const entries = loadAllEntries(grimoireDir, true);
+
+    // CONTEXT.md
+    fs.writeFileSync(path.join(contextDir, 'CONTEXT.md'), buildContextMd(entries), 'utf8');
+
+    // decisions.md
+    const dec = buildTagMd(entries, 'decisão', 'Decisões', '✅') ||
+        buildTagMd(entries, 'decisao', 'Decisões', '✅') ||
+        buildTagMd(entries, 'decision', 'Decisões', '✅');
+    if (dec) fs.writeFileSync(path.join(contextDir, 'decisions.md'), dec, 'utf8');
+
+    // patterns.md
+    const pat = buildTagMd(entries, 'padrão', 'Padrões', '🔧') ||
+        buildTagMd(entries, 'padrao', 'Padrões', '🔧') ||
+        buildTagMd(entries, 'pattern', 'Padrões', '🔧');
+    if (pat) fs.writeFileSync(path.join(contextDir, 'patterns.md'), pat, 'utf8');
+
+    // pinned.md
+    const pinned = entries.filter(e => e.source === 'pinned');
+    if (pinned.length) {
+        const pinnedLines = ['# 📌 Memórias Fixadas\n', '> Estas entradas são sempre incluídas no contexto dos agentes.\n'];
+        pinned.forEach(e => pinnedLines.push(`- ${e.content}`));
+        fs.writeFileSync(path.join(contextDir, 'pinned.md'), pinnedLines.join('\n'), 'utf8');
+    }
+
+    // Inject GEMINI.md
+    const injected = injectIntoGeminiMd(grimoireDir, entries);
+
+    if (!silent) {
+        console.log('\n✅ Contexto atualizado!\n');
+        console.log(`   📄 .grimoire/context/CONTEXT.md`);
+        if (dec) console.log(`   ✅ .grimoire/context/decisions.md`);
+        if (pat) console.log(`   🔧 .grimoire/context/patterns.md`);
+        if (pinned.length) console.log(`   📌 .grimoire/context/pinned.md`);
+        if (injected) console.log(`   🔮 GEMINI.md atualizado com bloco memory-context`);
+        console.log(`\n   ${entries.length} entradas indexadas`);
+        console.log(`   grimoire context show  ← ver o resultado\n`);
+    }
+
+    return { entries, injected };
+}
+
+// ── run ───────────────────────────────────────────────────────────────────────
+function run(args) {
+    const sub = args[0] || 'update';
+
+    const grimoireDir = findGrimoireDir();
+    if (!grimoireDir) {
+        console.error('❌ .grimoire/ not found. Run: npx grimoire-framework install');
+        return;
+    }
+
+    switch (sub) {
+        case 'update':
+            doUpdate(grimoireDir);
+            break;
+
+        case 'show': {
+            const contextFile = path.join(grimoireDir, 'context', 'CONTEXT.md');
+            if (!fs.existsSync(contextFile)) {
+                console.log('\n⚠️  Contexto ainda não gerado. Rode: grimoire context update\n');
+                return;
+            }
+            console.log('\n' + fs.readFileSync(contextFile, 'utf8'));
+            break;
+        }
+
+        case 'clean': {
+            const contextDir = path.join(grimoireDir, 'context');
+            if (fs.existsSync(contextDir)) {
+                fs.readdirSync(contextDir).forEach(f => fs.unlinkSync(path.join(contextDir, f)));
+                console.log('\n✅ Arquivos de contexto removidos (.jsonl preservados)\n');
+            } else {
+                console.log('\nℹ️  Nada para limpar.\n');
+            }
+            break;
+        }
+
+        default:
+            console.log('\nUsage:\n');
+            console.log('  grimoire context update   Regenera CONTEXT.md + injeta GEMINI.md');
+            console.log('  grimoire context show     Exibe CONTEXT.md');
+            console.log('  grimoire context clean    Remove arquivos gerados\n');
+    }
+}
+
+module.exports = { run, doUpdate, loadAllEntries, getGlobalMemoryDir };

package/bin/commands/memory.js

@@ -23,7 +23,8 @@ async function run(args) {
     baseDir = path.join(baseDir, 'grimoire');
   }
 
-  const memoryDir = path.join(baseDir, '.grimoire', 'memory');
+  const grimoireDir = path.join(baseDir, '.grimoire');
+  const memoryDir = path.join(grimoireDir, 'memory');
 
   if (!existsSync(memoryDir)) {
     console.error('❌ Memory system not found. Run "grimoire install" first.');
@@ -33,7 +34,10 @@ async function run(args) {
   try {
     switch (subCommand) {
       case 'save':
-        await saveMemory(args.slice(1), memoryDir);
+        await saveMemory(args.slice(1), memoryDir, grimoireDir);
+        break;
+      case 'pin':
+        await pinMemory(args.slice(1), memoryDir, grimoireDir);
         break;
       case 'list-tags':
         await listTags(memoryDir);
@@ -66,10 +70,36 @@ async function run(args) {
   }
 }
 
+// ── Auto-update context + RAG index (silent) ─────────────────────────
+function silentContextUpdate(grimoireDir) {
+  try {
+    const { doUpdate } = require('./context');
+    doUpdate(grimoireDir, true); // silent = true
+  } catch (_) { } // never block memory save
+}
+
+async function silentRagIndex(entry, date, grimoireDir) {
+  try {
+    const fs2 = require('fs');
+    const cfgF = require('path').join(grimoireDir, 'config.yaml');
+    const cfg = {};
+    if (fs2.existsSync(cfgF)) {
+      fs2.readFileSync(cfgF, 'utf8').split('\n').forEach(l => {
+        const m = l.match(/^(\w[\w_]*)\s*:\s*(.+)$/);
+        if (m) cfg[m[1].trim()] = m[2].trim();
+      });
+    }
+    // Only index if a real embedding provider is configured
+    if (!cfg.embedding_provider || cfg.embedding_provider === 'tfidf') return;
+    const { indexEntry } = require('./rag');
+    await indexEntry(entry, date, grimoireDir, cfg);
+  } catch (_) { }
+}
+
 /**
  * Saves memory using JSONL append (O(1) complexity)
  */
-async function saveMemory(args, memoryDir) {
+async function saveMemory(args, memoryDir, grimoireDir) {
   // Extract --tag value if present
   const tagIdx = args.findIndex(a => a === '--tag' || a.startsWith('--tag='));
   let tag = null;
@@ -98,6 +128,10 @@ async function saveMemory(args, memoryDir) {
     }
   }
 
+  // Extract --global flag
+  const isGlobal = filteredArgs.includes('--global');
+  filteredArgs = filteredArgs.filter(a => a !== '--global');
+
   const content = filteredArgs.join(' ');
   if (!content) {
     console.error('❌ Please provide content to save.');
@@ -105,8 +139,6 @@ async function saveMemory(args, memoryDir) {
   }
 
   const today = new Date().toISOString().split('T')[0];
-  const sessionFile = path.join(memoryDir, 'sessions', `${today}.jsonl`);
-
   const entry = {
     timestamp: new Date().toISOString(),
     content: content,
@@ -114,6 +146,21 @@ async function saveMemory(args, memoryDir) {
     ...(storyId ? { story: storyId } : {}),
   };
 
+  if (isGlobal) {
+    // Save to global memory
+    const { getGlobalMemoryDir } = require('./context');
+    const globalDir = getGlobalMemoryDir();
+    const globalFile = require('path').join(globalDir, 'global.jsonl');
+    const fss = require('fs');
+    fss.appendFileSync(globalFile, JSON.stringify({ ...entry, source: 'global' }) + '\n', 'utf8');
+    const tagLabel = tag ? ` [#${tag}]` : '';
+    console.log(`✅ Memory saved globally 🌐${tagLabel}`);
+    silentContextUpdate(grimoireDir);
+    return;
+  }
+
+  const sessionFile = require('path').join(memoryDir, 'sessions', `${today}.jsonl`);
+
   // Ensure file exists for lockfile
   if (!existsSync(sessionFile)) {
     await fs.writeFile(sessionFile, '', 'utf8');
@@ -134,7 +181,12 @@ async function saveMemory(args, memoryDir) {
     // Append entry as a new line in JSONL format
     await fs.appendFile(sessionFile, JSON.stringify(entry) + '\n', 'utf8');
     const tagLabel = tag ? ` [#${tag}]` : '';
-    console.log(`✅ Memory appended to session ${today}${tagLabel}`);
+    const storyLabel = storyId ? ` [${storyId}]` : '';
+    console.log(`✅ Memory saved${tagLabel}${storyLabel}`);
+    // Auto-update .grimoire/context/ silently
+    silentContextUpdate(grimoireDir);
+    // Auto-index for RAG (fire-and-forget)
+    silentRagIndex(entry, today, grimoireDir);
   } catch (err) {
     console.error(`❌ Failed to acquire lock for memory file: ${err.message}`);
   } finally {
@@ -142,6 +194,22 @@ async function saveMemory(args, memoryDir) {
   }
 }
 
+/**
+ * Pins a memory entry permanently in pinned.jsonl
+ */
+async function pinMemory(args, memoryDir, grimoireDir) {
+  const content = args.filter(a => !a.startsWith('-')).join(' ');
+  if (!content) {
+    console.log('Usage: grimoire memory pin "texto"\n');
+    return;
+  }
+  const pinnedFile = require('path').join(memoryDir, 'pinned.jsonl');
+  const entry = { timestamp: new Date().toISOString(), content, source: 'pinned' };
+  require('fs').appendFileSync(pinnedFile, JSON.stringify(entry) + '\n', 'utf8');
+  console.log(`📌 Memoria fixada: "${content}"`);
+  silentContextUpdate(grimoireDir);
+}
+
 /**
  * Lists sessions scanning the directory
  */

package/bin/commands/rag.js

@@ -0,0 +1,297 @@
+/**
+ * grimoire rag.js — Embedding Engine (Layered Strategy)
+ *
+ * Layer 1: @xenova/transformers (local, no server needed)
+ * Layer 2: Ollama (http://localhost:11434) — if running
+ * Layer 3: TF-IDF (always available, zero deps)
+ *
+ * Vector store: .grimoire/memory/vectors/YYYY-MM-DD.json (plain JSON arrays)
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+// ── Config ────────────────────────────────────────────────────────────────────
+const DEFAULT_XENOVA_MODEL = 'Xenova/all-MiniLM-L6-v2'; // 23MB, fast
+const OLLAMA_URL = 'http://localhost:11434';
+const OLLAMA_MODEL = 'nomic-embed-text';
+const VECTORS_DIR_NAME = 'vectors';
+
+// ── Cosine similarity ─────────────────────────────────────────────────────────
+function cosineSimilarity(a, b) {
+    if (!a || !b || a.length !== b.length) return 0;
+    let dot = 0, normA = 0, normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    return denom === 0 ? 0 : dot / denom;
+}
+
+// ── TF-IDF fallback ───────────────────────────────────────────────────────────
+function tokenize(text) {
+    return text.toLowerCase().replace(/[^a-z0-9\u00c0-\u024f\s]/g, '').split(/\s+/).filter(Boolean);
+}
+
+const STOP_WORDS = new Set(['de', 'do', 'da', 'em', 'um', 'uma', 'e', 'a', 'o', 'os', 'as', 'para', 'com', 'que', 'não', 'por', 'se', 'mais', 'mas', 'ou', 'no', 'na', 'ao', 'isso', 'este', 'esta', 'é', 'foi', 'são', 'tem', 'como', 'sua', 'seu', 'usar', 'usar', 'ter', 'ser', 'was', 'the', 'and', 'for', 'are', 'with', 'this', 'that', 'from', 'not', 'has', 'have', 'will', 'can', 'also', 'use', 'used', 'via']);
+
+function buildTFIDF(allEntries, query) {
+    // Build corpus
+    const docs = allEntries.map(e => tokenize(e.content));
+    const queryTokens = tokenize(query);
+    const N = docs.length;
+
+    // Build vocabulary (union of query + docs)
+    const vocab = new Set([...queryTokens]);
+    docs.forEach(d => d.forEach(t => { if (!STOP_WORDS.has(t)) vocab.add(t); }));
+    const vocabArr = [...vocab];
+
+    // IDF
+    const idf = {};
+    vocabArr.forEach(term => {
+        const df = docs.filter(d => d.includes(term)).length;
+        idf[term] = df === 0 ? 0 : Math.log((N + 1) / (df + 1)) + 1;
+    });
+
+    // TF-IDF vector for a token list
+    function toVec(tokens) {
+        const tf = {};
+        tokens.forEach(t => { tf[t] = (tf[t] || 0) + 1; });
+        const maxTF = Math.max(...Object.values(tf), 1);
+        return vocabArr.map(term => ((tf[term] || 0) / maxTF) * (idf[term] || 0));
+    }
+
+    const queryVec = toVec(queryTokens);
+    return allEntries.map((entry, i) => ({
+        entry,
+        score: cosineSimilarity(queryVec, toVec(docs[i])),
+    }));
+}
+
+// ── Xenova embedding ──────────────────────────────────────────────────────────
+let _xenovaExtractor = null;
+
+async function getXenovaExtractor() {
+    if (_xenovaExtractor) return _xenovaExtractor;
+    try {
+        // Dynamic import for ESM compat
+        const { pipeline } = await import('@xenova/transformers');
+        _xenovaExtractor = await pipeline('feature-extraction', DEFAULT_XENOVA_MODEL, {
+            progress_callback: null, // silent
+        });
+        return _xenovaExtractor;
+    } catch (_) {
+        return null;
+    }
+}
+
+async function embedXenova(text) {
+    const extractor = await getXenovaExtractor();
+    if (!extractor) return null;
+    const output = await extractor(text, { pooling: 'mean', normalize: true });
+    return Array.from(output.data);
+}
+
+// ── Ollama embedding ──────────────────────────────────────────────────────────
+async function embedOllama(text) {
+    try {
+        const res = await fetch(`${OLLAMA_URL}/api/embeddings`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ model: OLLAMA_MODEL, prompt: text }),
+            signal: AbortSignal.timeout(5000),
+        });
+        const { embedding } = await res.json();
+        return Array.isArray(embedding) ? embedding : null;
+    } catch (_) {
+        return null;
+    }
+}
+
+// ── Auto-detect provider ──────────────────────────────────────────────────────
+async function detectProvider(config) {
+    const preferred = config?.embedding_provider || 'auto';
+
+    if (preferred === 'tfidf') return 'tfidf';
+    if (preferred === 'ollama') return 'ollama';
+
+    if (preferred === 'xenova' || preferred === 'auto') {
+        try {
+            await import('@xenova/transformers');
+            return 'xenova';
+        } catch (_) { }
+    }
+
+    if (preferred === 'auto') {
+        // Try Ollama ping
+        try {
+            const r = await fetch(`${OLLAMA_URL}/api/tags`, { signal: AbortSignal.timeout(1000) });
+            if (r.ok) return 'ollama';
+        } catch (_) { }
+    }
+
+    return 'tfidf';
+}
+
+// ── Public: embed a single text ───────────────────────────────────────────────
+async function embed(text, config) {
+    const provider = await detectProvider(config);
+
+    if (provider === 'xenova') {
+        const v = await embedXenova(text);
+        if (v) return { vector: v, provider: 'xenova' };
+    }
+
+    if (provider === 'ollama') {
+        const v = await embedOllama(text);
+        if (v) return { vector: v, provider: 'ollama' };
+    }
+
+    return { vector: null, provider: 'tfidf' }; // TF-IDF is computed at search time
+}
+
+// ── Vector store ──────────────────────────────────────────────────────────────
+function getVectorsDir(grimoireDir) {
+    const d = path.join(grimoireDir, 'memory', VECTORS_DIR_NAME);
+    if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+    return d;
+}
+
+function loadVectorFile(vectorsDir, date) {
+    const f = path.join(vectorsDir, `${date}.json`);
+    if (!fs.existsSync(f)) return [];
+    try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch (_) { return []; }
+}
+
+function saveVectorFile(vectorsDir, date, records) {
+    fs.writeFileSync(path.join(vectorsDir, `${date}.json`), JSON.stringify(records), 'utf8');
+}
+
+// Index a single entry (called after memory save)
+async function indexEntry(entry, date, grimoireDir, config) {
+    try {
+        const { vector, provider } = await embed(entry.content, config);
+        if (!vector) return; // TF-IDF: skip vector storage, computed at query time
+
+        const vectorsDir = getVectorsDir(grimoireDir);
+        const records = loadVectorFile(vectorsDir, date);
+
+        // Remove existing record with same timestamp to avoid duplicates
+        const filtered = records.filter(r => r.timestamp !== entry.timestamp);
+        filtered.push({
+            timestamp: entry.timestamp,
+            content: entry.content,
+            tag: entry.tag || null,
+            story: entry.story || null,
+            source: entry.source || 'local',
+            vector,
+            provider,
+        });
+        saveVectorFile(vectorsDir, date, filtered);
+    } catch (_) { } // never block memory save
+}
+
+// ── Public: semantic search ───────────────────────────────────────────────────
+async function search(query, grimoireDir, config, topK = 5) {
+    const provider = await detectProvider(config);
+
+    if (provider === 'xenova' || provider === 'ollama') {
+        return await vectorSearch(query, grimoireDir, config, topK, provider);
+    }
+
+    // TF-IDF fallback — load all entries from JSONL
+    return tfidfSearch(query, grimoireDir, topK);
+}
+
+async function vectorSearch(query, grimoireDir, config, topK, provider) {
+    const { vector: queryVec } = await embed(query, config);
+    if (!queryVec) return tfidfSearch(query, grimoireDir, topK);
+
+    const vectorsDir = getVectorsDir(grimoireDir);
+    if (!fs.existsSync(vectorsDir)) return [];
+
+    const results = [];
+    for (const f of fs.readdirSync(vectorsDir).filter(f => f.endsWith('.json'))) {
+        const records = loadVectorFile(vectorsDir, f.replace('.json', ''));
+        for (const rec of records) {
+            if (!rec.vector) continue;
+            const score = cosineSimilarity(queryVec, rec.vector);
+            results.push({ ...rec, score, searchMode: 'semantic' });
+        }
+    }
+
+    return results.sort((a, b) => b.score - a.score).slice(0, topK);
+}
+
+function tfidfSearch(query, grimoireDir, topK) {
+    // Load all JSONL entries
+    const allEntries = [];
+    const sessionsDir = path.join(grimoireDir, 'memory', 'sessions');
+    if (!fs.existsSync(sessionsDir)) return [];
+
+    for (const f of fs.readdirSync(sessionsDir).filter(f => f.endsWith('.jsonl')).sort()) {
+        const raw = fs.readFileSync(path.join(sessionsDir, f), 'utf8');
+        for (const line of raw.split('\n').filter(l => l.trim())) {
+            try { allEntries.push({ date: f.slice(0, 10), ...JSON.parse(line) }); } catch (_) { }
+        }
+    }
+
+    return buildTFIDF(allEntries, query)
+        .filter(r => r.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, topK)
+        .map(r => ({ ...r.entry, score: r.score, searchMode: 'tfidf' }));
+}
+
+// ── Re-index all existing entries ─────────────────────────────────────────────
+async function reindexAll(grimoireDir, config, onProgress) {
+    const sessionsDir = path.join(grimoireDir, 'memory', 'sessions');
+    if (!fs.existsSync(sessionsDir)) return 0;
+
+    let count = 0;
+    const files = fs.readdirSync(sessionsDir).filter(f => f.endsWith('.jsonl')).sort();
+
+    for (const f of files) {
+        const date = f.slice(0, 10);
+        const raw = fs.readFileSync(path.join(sessionsDir, f), 'utf8');
+        const lines = raw.split('\n').filter(l => l.trim());
+
+        for (const line of lines) {
+            try {
+                const entry = JSON.parse(line);
+                await indexEntry(entry, date, grimoireDir, config);
+                count++;
+                if (onProgress) onProgress(count);
+            } catch (_) { }
+        }
+    }
+    return count;
+}
+
+// ── Status check ──────────────────────────────────────────────────────────────
+async function ragStatus(config) {
+    const provider = await detectProvider(config);
+    const xenovaAvail = await (async () => {
+        try { await import('@xenova/transformers'); return true; } catch (_) { return false; }
+    })();
+    const ollamaAvail = await (async () => {
+        try {
+            const r = await fetch(`${OLLAMA_URL}/api/tags`, { signal: AbortSignal.timeout(1000) });
+            return r.ok;
+        } catch (_) { return false; }
+    })();
+
+    return {
+        activeProvider: provider,
+        xenova: { available: xenovaAvail, model: DEFAULT_XENOVA_MODEL },
+        ollama: { available: ollamaAvail, url: OLLAMA_URL, model: OLLAMA_MODEL },
+        tfidf: { available: true },
+    };
+}
+
+module.exports = { embed, indexEntry, search, reindexAll, ragStatus, cosineSimilarity };

package/bin/commands/search.js

@@ -1,10 +1,12 @@
 /**
- * grimoire search — Global Search
+ * grimoire search — Global Search (RAG-enhanced)
  *
- * grimoire search "termo"           Busca em memory + stories + agents
- * grimoire search "JWT" --memory    Só memória
+ * grimoire search "termo"           Busca semântica em memory + stories + agents
+ * grimoire search "JWT" --memory    Só memória (semântica se RAG ativo)
  * grimoire search "JWT" --stories   Só stories
  * grimoire search "JWT" --agents    Só agentes
+ * grimoire search "JWT" --semantic  Força busca semântica
+ * grimoire search "JWT" --exact     Força busca por substring
  */
 
 'use strict';
@@ -36,8 +38,38 @@ function hl(text, query) {
     return text.replace(re, m => `\x1b[33m${m}\x1b[0m`);
 }
 
-// ── Search memory sessions ────────────────────────────────────────────────────
-function searchMemory(grimoireDir, query) {
+function loadConfig(grimoireDir) {
+    const f = path.join(grimoireDir, 'config.yaml');
+    if (!fs.existsSync(f)) return {};
+    const cfg = {};
+    fs.readFileSync(f, 'utf8').split('\n').forEach(line => {
+        const m = line.match(/^(\w[\w_]*)\s*:\s*(.+)$/);
+        if (m) cfg[m[1].trim()] = m[2].trim();
+    });
+    return cfg;
+}
+
+// ── RAG memory search ─────────────────────────────────────────────────────────
+async function searchMemoryRAG(grimoireDir, query, topK = 15) {
+    try {
+        const { search } = require('./rag');
+        const config = loadConfig(grimoireDir);
+        const results = await search(query, grimoireDir, config, topK);
+        return results.map(r => ({
+            date: r.date || r.timestamp?.slice(0, 10) || '',
+            content: r.content,
+            tag: r.tag || null,
+            story: r.story || null,
+            score: r.score,
+            searchMode: r.searchMode || 'unknown',
+        }));
+    } catch (_) {
+        return searchMemoryExact(grimoireDir, query);
+    }
+}
+
+// ── Exact substring memory search (fallback) ─────────────────────────────────
+function searchMemoryExact(grimoireDir, query) {
     const sessionsDir = path.join(grimoireDir, 'memory', 'sessions');
     if (!fs.existsSync(sessionsDir)) return [];
     const lq = query.toLowerCase();
@@ -49,7 +81,7 @@ function searchMemory(grimoireDir, query) {
             try {
                 const e = JSON.parse(line);
                 if ((e.content || '').toLowerCase().includes(lq)) {
-                    results.push({ date: f.slice(0, 10), content: e.content, tag: e.tag || null, story: e.story || null });
+                    results.push({ date: f.slice(0, 10), content: e.content, tag: e.tag || null, story: e.story || null, score: 1, searchMode: 'exact' });
                 }
             } catch (_) { }
         }
@@ -80,7 +112,6 @@ function searchAgents(agentsDir, query) {
         const raw = fs.readFileSync(path.join(agentsDir, f), 'utf8').toLowerCase();
         if (raw.includes(lq)) {
             const id = f.replace('.md', '');
-            // Extract name from yaml block
             let name = id;
             const nameMatch = raw.match(/name:\s*([^\n]+)/);
             if (nameMatch) name = nameMatch[1].trim();
@@ -92,18 +123,33 @@ function searchAgents(agentsDir, query) {
     return results;
 }
 
+// ── Render score bar ──────────────────────────────────────────────────────────
+function scoreBar(score) {
+    if (score === null || score === undefined) return '';
+    const pct = Math.round(score * 10);
+    const bar = '█'.repeat(pct) + '░'.repeat(10 - pct);
+    const pctStr = `${Math.round(score * 100)}%`.padStart(4);
+    return ` \x1b[2m${bar} ${pctStr}\x1b[0m`;
+}
+
 // ── run ───────────────────────────────────────────────────────────────────────
-function run(args) {
+async function run(args) {
     const query = args.filter(a => !a.startsWith('-')).join(' ');
     if (!query) {
         console.log('Usage: grimoire search "termo"\n');
-        console.log('Busca em: memória · stories · agentes\n');
+        console.log('Busca semântica em: memória · stories · agentes\n');
+        console.log('Flags:');
+        console.log('  --memory    Só memória');
+        console.log('  --stories   Só stories');
+        console.log('  --agents    Só agentes');
+        console.log('  --exact     Força busca por substring (ignora RAG)\n');
         return;
     }
 
     const onlyMemory = args.includes('--memory');
     const onlyStories = args.includes('--stories');
     const onlyAgents = args.includes('--agents');
+    const forceExact = args.includes('--exact');
     const all = !onlyMemory && !onlyStories && !onlyAgents;
 
     const grimoireDir = findGrimoireDir();
@@ -111,43 +157,59 @@ function run(args) {
 
     let totalResults = 0;
 
-    console.log(`\n🔍 Grimoire Search — "${query}"\n${'─'.repeat(44)}`);
+    // Detect search mode label
+    let searchModeLabel = '(substring)';
+    if (!forceExact && grimoireDir) {
+        const config = loadConfig(grimoireDir);
+        const provider = config.embedding_provider || 'auto';
+        if (provider !== 'tfidf') {
+            searchModeLabel = provider === 'xenova' ? '🤖 semântica (xenova)' :
+                provider === 'ollama' ? '🦙 semântica (ollama)' :
+                    '📊 TF-IDF';
+        } else {
+            searchModeLabel = '📊 TF-IDF';
+        }
+    }
+
+    console.log(`\n🔍 Grimoire Search — "${query}"  ${searchModeLabel}\n${'─'.repeat(52)}`);
 
     // Memory
-    if (all || onlyMemory) {
-        if (grimoireDir) {
-            const memResults = searchMemory(grimoireDir, query);
-            if (memResults.length > 0) {
-                console.log('\n🧠 Memória:');
-                for (const r of memResults) {
-                    const tag = r.tag ? ` [#${r.tag}]` : '';
-                    const story = r.story ? ` [${r.story}]` : '';
-                    console.log(`  ${r.date}  ${hl(r.content, query)}${tag}${story}`);
-                }
-                totalResults += memResults.length;
+    if ((all || onlyMemory) && grimoireDir) {
+        const memResults = forceExact
+            ? searchMemoryExact(grimoireDir, query)
+            : await searchMemoryRAG(grimoireDir, query, 10);
+
+        if (memResults.length > 0) {
+            const modeIcon = memResults[0]?.searchMode === 'semantic' ? ' 🤖' :
+                memResults[0]?.searchMode === 'tfidf' ? ' 📊' : '';
+            console.log(`\n🧠 Memória${modeIcon}:`);
+            for (const r of memResults) {
+                const tag = r.tag ? ` \x1b[36m[#${r.tag}]\x1b[0m` : '';
+                const story = r.story ? ` \x1b[35m[${r.story}]\x1b[0m` : '';
+                const bar = r.searchMode !== 'exact' ? scoreBar(r.score) : '';
+                console.log(`  ${r.date}  ${hl(r.content, query)}${tag}${story}${bar}`);
             }
+            totalResults += memResults.length;
         }
     }
 
-    // Stories
-    if (all || onlyStories) {
-        if (grimoireDir) {
-            const storyResults = searchStories(grimoireDir, query);
-            if (storyResults.length > 0) {
-                console.log('\n📋 Stories:');
-                for (const s of storyResults) {
-                    const icon = s.status === 'done' ? '✅' : '🔄';
-                    console.log(`  ${icon} [${s.id}] ${hl(s.title, query)}`);
-                    for (const n of (s.notes || []).filter(n => n.toLowerCase().includes(query.toLowerCase()))) {
-                        console.log(`       📝 ${hl(n, query)}`);
-                    }
+    // Stories (always exact — small dataset)
+    if ((all || onlyStories) && grimoireDir) {
+        const storyResults = searchStories(grimoireDir, query);
+        if (storyResults.length > 0) {
+            console.log('\n📋 Stories:');
+            for (const s of storyResults) {
+                const icon = s.status === 'done' ? '✅' : '🔄';
+                console.log(`  ${icon} [${s.id}] ${hl(s.title, query)}`);
+                for (const n of (s.notes || []).filter(n => n.toLowerCase().includes(query.toLowerCase()))) {
+                    console.log(`       📝 ${hl(n, query)}`);
                 }
-                totalResults += storyResults.length;
             }
+            totalResults += storyResults.length;
         }
     }
 
-    // Agents
+    // Agents (always exact)
     if (all || onlyAgents) {
         const agentResults = searchAgents(agentsDir, query);
         if (agentResults.length > 0) {
@@ -161,9 +223,9 @@ function run(args) {
 
     if (totalResults === 0) {
         console.log('\n  (nenhum resultado encontrado)');
-        console.log(`  Dica: tente termos mais curtos ou use --memory / --stories / --agents\n`);
+        console.log(`  Dica: tente termos mais amplos ou "grimoire setup rag" para busca semântica\n`);
     } else {
-        console.log(`\n${'─'.repeat(44)}`);
+        console.log(`\n${'─'.repeat(52)}`);
         console.log(`  ${totalResults} resultado(s)\n`);
     }
 }

package/bin/commands/setup.js

@@ -0,0 +1,173 @@
+/**
+ * grimoire setup — Environment & RAG Setup
+ *
+ * grimoire setup rag          Configura RAG (detecta provider + baixa modelo)
+ * grimoire setup rag --reindex  Reindexar todas as entradas existentes
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const { execSync, spawn } = require('child_process');
+
+function findGrimoireDir() {
+    const cwd = process.cwd();
+    const d1 = path.join(cwd, '.grimoire');
+    const d2 = path.join(cwd, 'grimoire', '.grimoire');
+    if (fs.existsSync(d1)) return d1;
+    if (fs.existsSync(d2)) return d2;
+    return null;
+}
+
+function loadConfig(grimoireDir) {
+    const f = path.join(grimoireDir, 'config.yaml');
+    if (!fs.existsSync(f)) return {};
+    // Simple YAML key: value parser
+    const cfg = {};
+    fs.readFileSync(f, 'utf8').split('\n').forEach(line => {
+        const m = line.match(/^(\w[\w_]*)\s*:\s*(.+)$/);
+        if (m) cfg[m[1].trim()] = m[2].trim();
+    });
+    return cfg;
+}
+
+function saveConfig(grimoireDir, updates) {
+    const f = path.join(grimoireDir, 'config.yaml');
+    let content = fs.existsSync(f) ? fs.readFileSync(f, 'utf8') : '';
+
+    Object.entries(updates).forEach(([key, value]) => {
+        const re = new RegExp(`^${key}\\s*:.*$`, 'm');
+        if (re.test(content)) {
+            content = content.replace(re, `${key}: ${value}`);
+        } else {
+            content += `\n${key}: ${value}`;
+        }
+    });
+
+    fs.writeFileSync(f, content.trim() + '\n', 'utf8');
+}
+
+// ── Check if @xenova/transformers is installed ─────────────────────────────────
+function isXenovaInstalled() {
+    try { require.resolve('@xenova/transformers'); return true; } catch (_) { return false; }
+}
+
+// ── Check if Ollama is running ─────────────────────────────────────────────────
+async function isOllamaRunning() {
+    try {
+        const r = await fetch('http://localhost:11434/api/tags', { signal: AbortSignal.timeout(1500) });
+        return r.ok;
+    } catch (_) { return false; }
+}
+
+// ── Setup RAG ─────────────────────────────────────────────────────────────────
+async function setupRag(args) {
+    const reindex = args.includes('--reindex');
+    const sep = '─'.repeat(52);
+
+    console.log(`\n🔮 Grimoire RAG Setup\n${sep}\n`);
+
+    const { ragStatus } = require('./rag');
+    const grimoireDir = findGrimoireDir();
+
+    if (!grimoireDir) {
+        console.error('❌ .grimoire/ not found. Run: npx grimoire-framework install\n');
+        return;
+    }
+
+    const config = loadConfig(grimoireDir);
+
+    console.log('🔍 Detectando providers disponíveis...\n');
+
+    // ── Layer 1: @xenova/transformers ──────────────────────────────────────────
+    console.log('  [1/3] @xenova/transformers (local, offline)');
+
+    if (isXenovaInstalled()) {
+        console.log('        ✅ Já instalado');
+    } else {
+        console.log('        📦 Instalando @xenova/transformers...');
+        try {
+            execSync('npm install @xenova/transformers --save-optional --no-fund --no-audit', {
+                stdio: 'inherit',
+                cwd: path.dirname(require.main?.filename || process.cwd()),
+            });
+            console.log('        ✅ Instalado com sucesso');
+        } catch (e) {
+            console.log('        ⚠️  Falha ao instalar — tentando layer 2 (Ollama)');
+        }
+    }
+
+    // Download model on first use (xenova downloads automatically)
+    if (isXenovaInstalled()) {
+        console.log('        🤖 Carregando modelo Xenova/all-MiniLM-L6-v2...');
+        console.log('           (primeiro carregamento pode levar 30-60s ~23MB)');
+        try {
+            const { pipeline } = await import('@xenova/transformers');
+            await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', { progress_callback: null });
+            console.log('        ✅ Modelo pronto!\n');
+            saveConfig(grimoireDir, { embedding_provider: 'xenova', embedding_model: 'Xenova/all-MiniLM-L6-v2' });
+        } catch (e) {
+            console.log(`        ❌ Erro ao carregar modelo: ${e.message}\n`);
+        }
+    }
+
+    // ── Layer 2: Ollama ────────────────────────────────────────────────────────
+    console.log('  [2/3] Ollama (local server, melhor qualidade)');
+    const ollamaRunning = await isOllamaRunning();
+    if (ollamaRunning) {
+        console.log('        ✅ Ollama detectado em localhost:11434');
+        if (!isXenovaInstalled()) {
+            saveConfig(grimoireDir, { embedding_provider: 'ollama', embedding_model: 'nomic-embed-text' });
+        }
+    } else {
+        console.log('        ℹ️  Ollama não detectado (opcional)');
+        console.log('           Instale em: https://ollama.com');
+        console.log('           Depois: ollama pull nomic-embed-text\n');
+    }
+
+    // ── Layer 3: TF-IDF ────────────────────────────────────────────────────────
+    console.log('  [3/3] TF-IDF (fallback — sempre disponível)');
+    console.log('        ✅ Ativo\n');
+
+    // ── Final status ───────────────────────────────────────────────────────────
+    const status = await ragStatus(loadConfig(grimoireDir));
+    const activeIcon = { xenova: '🤖', ollama: '🦙', tfidf: '📊' };
+
+    console.log(`${sep}`);
+    console.log(`  Provider ativo:  ${activeIcon[status.activeProvider] || '📊'} ${status.activeProvider}`);
+    console.log(`  Xenova:          ${status.xenova.available ? '✅' : '❌'} ${status.xenova.model}`);
+    console.log(`  Ollama:          ${status.ollama.available ? '✅' : '❌'} ${status.ollama.url}`);
+    console.log(`  TF-IDF:          ✅ sempre disponível`);
+    console.log(`${sep}\n`);
+
+    // ── Reindex ────────────────────────────────────────────────────────────────
+    if (reindex || status.activeProvider !== 'tfidf') {
+        const { reindexAll } = require('./rag');
+        process.stdout.write('  🔄 Indexando entradas de memória existentes...');
+        let n = 0;
+        const count = await reindexAll(grimoireDir, loadConfig(grimoireDir), (i) => {
+            n = i;
+            if (i % 10 === 0) process.stdout.write('.');
+        });
+        console.log(`\n  ✅ ${count} entradas indexadas\n`);
+    }
+
+    console.log('🎯 RAG configurado! Agora o grimoire memory search é semântico.');
+    console.log('   grimoire memory search "autenticação"  ← busca por significado\n');
+}
+
+// ── run ────────────────────────────────────────────────────────────────────────
+async function run(args) {
+    const sub = args[0];
+    switch (sub) {
+        case 'rag': await setupRag(args.slice(1)); break;
+        default:
+            console.log('\nUsage:\n');
+            console.log('  grimoire setup rag            Configura RAG (xenova + modelos)');
+            console.log('  grimoire setup rag --reindex  Reindexar todas as entradas\n');
+    }
+}
+
+module.exports = { run };

package/bin/grimoire-cli.js

@@ -151,6 +151,12 @@ async function main() {
     case 'export':
       require('./commands/exportall').run(args.slice(1));
       break;
+    case 'context':
+      require('./commands/context').run(args.slice(1));
+      break;
+    case 'setup':
+      require('./commands/setup').run(args.slice(1));
+      break;
     case 'whoami':
       handleWhoami();
       break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grimoire-framework",
-  "version": "1.4.1",
+  "version": "1.6.0",
   "description": "Grimoire: AI-Orchestrated System for Full Stack Development - Core Framework",
   "publishConfig": {
     "access": "public"
@@ -82,6 +82,9 @@
     "prepublishOnly": "node scripts/pre-publish-check.js && npm run generate:manifest && npm run validate:manifest",
     "prepare": "husky"
   },
+  "optionalDependencies": {
+    "@xenova/transformers": "^2.17.2"
+  },
   "dependencies": {
     "@clack/prompts": "^0.11.0",
     "@kayvan/markdown-tree-parser": "^1.5.0",