grimoire-framework 1.5.0 → 1.6.0

package/.grimoire/install-manifest.yaml

@@ -7,8 +7,8 @@
 # - SHA256 hashes for change detection
 # - File types for categorization
 #
-version: 1.5.0
-generated_at: "2026-02-22T17:38:38.314Z"
+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/memory.js

@@ -70,7 +70,7 @@ async function run(args) {
   }
 }
 
-// ── Auto-update context (silent) ────────────────────────────────────────────
+// ── Auto-update context + RAG index (silent) ─────────────────────────
 function silentContextUpdate(grimoireDir) {
   try {
     const { doUpdate } = require('./context');
@@ -78,6 +78,24 @@ function silentContextUpdate(grimoireDir) {
   } 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)
  */
@@ -167,6 +185,8 @@ async function saveMemory(args, memoryDir, grimoireDir) {
     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 {

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

@@ -154,6 +154,9 @@ async function main() {
     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.5.0",
+  "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",