@pcircle/memesh 4.6.0 → 4.6.1

package/dist/transports/cli/cli.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 import { randomBytes } from 'crypto';
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { openDatabase, closeDatabase, getDatabase, reindexFts, allowVectorIndexRebuild } from '../../db.js';
+import { openDatabase, closeDatabase, getDatabase, reindexFts, readVectorGeneration, generationRowIds, discardVectorGeneration, } from '../../db.js';
 import { remember, recallWithConflicts, forget, exportMemories, importMemories, learn, reindex, setPinned } from '../../core/operations.js';
 import { readConfig, writeConfig, maskApiKey, detectCapabilities } from '../../core/config.js';
 import { MAX_LANGUAGE_LENGTH, languageValueError } from '../../core/output-language.js';
-import { getDbPath, homeDir, redactSecrets, redactUserPaths } from '../../core/paths.js';
+import { getDbPath, getProjectName, homeDir, redactSecrets, redactUserPaths } from '../../core/paths.js';
 import { flushPendingEmbeddings, canRefillVectorIndex } from '../../core/embedder.js';
 import { NAMESPACES } from '../../core/types.js';
 import { assembleBriefing } from '../../core/briefing.js';
@@ -159,7 +159,7 @@ program
     .action(async (query, opts) => {
     requireOneOf(opts.namespace, NAMESPACES, '--namespace');
     await withDatabase(async () => {
-        const { entities, conflicts } = await recallWithConflicts({
+        const { entities, conflicts, retrieval } = await recallWithConflicts({
             query: query || undefined,
             tag: opts.tag,
             limit: parseInt(opts.limit),
@@ -168,12 +168,7 @@ program
             cross_project: opts.crossProject,
         });
         if (opts.json) {
-            if (conflicts.length > 0) {
-                console.log(JSON.stringify({ entities, conflicts }));
-            }
-            else {
-                console.log(JSON.stringify(entities));
-            }
+            console.log(JSON.stringify(conflicts.length > 0 ? { entities, retrieval, conflicts } : { entities, retrieval }));
         }
         else if (entities.length === 0) {
             console.log('No results found.');
@@ -203,7 +198,11 @@ program
                     console.log(`    ... +${e.observations.length - 3} more`);
                 }
             }
-            console.log(`\n${entities.length} result(s)`);
+            const truncatedNote = retrieval.truncated ? ' (limit reached — more may exist)' : '';
+            console.log(`\n${entities.length} result(s)${truncatedNote}`);
+            if (retrieval.degraded) {
+                console.log('Warning: semantic search unavailable right now — keyword-only results (degraded). Run `memesh doctor` to see why.');
+            }
             if (conflicts.length > 0) {
                 console.log('\nWarning: Conflicts detected:');
                 for (const c of conflicts) {
@@ -450,6 +449,83 @@ program
         console.log(result.text);
     });
 });
+const WHY_ABSTENTION_TEXT = {
+    git_unavailable: 'git is not installed or not on PATH — commit attribution unavailable.',
+    not_a_git_repo: 'Not inside a git repository — commit attribution unavailable.',
+    file_not_tracked: 'File is not tracked by git — commit attribution unavailable.',
+    history_unreadable: "git could not read this file's history (too much output, too slow, or the repository has no commits yet) — nothing is listed because the question went unanswered, not because no commit touched the file.",
+    no_commits_supplied: 'No commit hashes were supplied — only the file-tag half of this answer ran.',
+    line_out_of_range: 'That line does not exist in the tracked file.',
+    line_uncommitted: 'That line is not committed yet — nothing to attribute.',
+    no_commit_entity: 'memesh has no memory of this commit (it predates capture, or was made without hooks / on another machine).',
+    no_session_link: 'This commit was captured before commits recorded their session — the session link does not exist.',
+};
+program
+    .command('why')
+    .description('Explain a file: commits memesh remembers touching it, their sessions, and related memories')
+    .argument('<file>', 'File path (relative to the current directory or absolute)')
+    .option('--line <n>', 'Attribute one line via git blame instead of file history')
+    .option('--limit <n>', 'Max commits to inspect', '10')
+    .option('--json', 'Output as JSON')
+    .action(async (file, opts) => {
+    await withDatabase(async () => {
+        const { resolveFileCommits, explainCommits } = await import('../../core/why.js');
+        const cwd = process.cwd();
+        const limit = parseInt(opts.limit, 10);
+        const line = opts.line !== undefined ? parseInt(opts.line, 10) : undefined;
+        for (const [flag, value] of [['--limit', limit], ['--line', line]]) {
+            if (value !== undefined && (!Number.isInteger(value) || value < 1)) {
+                console.error(`Error: ${flag} needs a whole number of 1 or more.`);
+                process.exit(1);
+            }
+        }
+        const resolved = resolveFileCommits(cwd, file, { line, limit });
+        const result = explainCommits(getDatabase(), {
+            file,
+            commits: resolved.commits,
+            project: getProjectName(cwd),
+            limit,
+            abstentions: resolved.abstention ? [resolved.abstention] : [],
+        });
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`why ${result.file}  (project: ${result.project ?? 'all'})`);
+        for (const code of result.abstentions) {
+            console.log(`  ! ${WHY_ABSTENTION_TEXT[code] ?? code}`);
+        }
+        if (result.commits.length === 0 && result.abstentions.length === 0) {
+            console.log('  No commits touch this file.');
+        }
+        for (const c of result.commits) {
+            const head = [c.commit.hash.slice(0, 10), c.commit.date, c.commit.subject].filter(Boolean).join('  ');
+            console.log(`\n  ${head}`);
+            if (c.entity) {
+                console.log(`    memory: ${c.entity.name} [mem:${c.entity.id}]`);
+                for (const obs of c.entity.observations.slice(0, 3))
+                    console.log(`      - ${obs}`);
+            }
+            if (c.session) {
+                console.log(`    session: ${c.session.session_id}`);
+                for (const s of c.session.entities)
+                    console.log(`      - ${s.name} (${s.type})`);
+                if (c.session.truncated) {
+                    console.log(`      … first ${c.session.entities.length} of a larger session — more exist`);
+                }
+            }
+            for (const code of c.abstentions) {
+                console.log(`    ! ${WHY_ABSTENTION_TEXT[code] ?? code}`);
+            }
+        }
+        const fm = result.file_memories.entities;
+        if (fm.length > 0) {
+            console.log(`\n  Related by file tag (file:${result.basename} — associated, not commit-derived):`);
+            for (const e of fm)
+                console.log(`    - ${e.name} (${e.type})${e.title ? `: ${e.title}` : ''}`);
+        }
+    });
+});
 program
     .command('setup')
     .description('Detect Claude Code / Codex / Gemini on this machine, wire memesh into each, and verify')
@@ -615,7 +691,6 @@ const ALLOWED_KEYS = new Set([
     'llm.apiKey',
     'llm.model',
     'embedder.provider',
-    'embedder.model',
     'autoUpdate',
     'sessionLimit',
     'autoCapture',
@@ -1005,7 +1080,8 @@ kgCmd
     .option('--session-cooccurrence', 'Rule 3: link high-signal orphans co-created in the same session')
     .option('--name-tokens', 'Rule 4: link orphans sharing ≥3 name content tokens (or Jaccard ≥ 0.50)')
     .option('--min-jaccard <n>', 'Jaccard threshold for name similarity (default 0.50)', parseFloat)
-    .option('--all-rules', 'Enable all heuristic rules (Rules 1–4)')
+    .option('--all-rules', 'Enable all heuristic rules (Rules 1–5)')
+    .option('--no-evidence-links', 'Disable Rule 5: evidence → work-item links via shared session id (on by default — these edges feed the graph\'s evidence badges)')
     .option('--reset-idempotency', 'Clear the persistent "already-attempted" orphan cache before running (use after schema changes or to reconsider every orphan)')
     .option('--json', 'Output as JSON')
     .action(async (opts) => {
@@ -1020,6 +1096,7 @@ kgCmd
             dryRun: !!opts.dryRun,
             includeSessionCooccurrence: allRules || !!opts.sessionCooccurrence,
             includeNameTokenSimilarity: allRules || !!opts.nameTokens,
+            includeEvidenceLinks: opts.evidenceLinks !== false,
             minNameJaccard: opts.minJaccard,
             resetIdempotency: !!opts.resetIdempotency,
         };
@@ -1059,6 +1136,7 @@ kgCmd
         console.log(`  project clustering: ${result.byRule.projectClustering}`);
         console.log(`  session co-occurrence: ${result.byRule.sessionCooccurrence}`);
         console.log(`  name token similarity: ${result.byRule.nameTokenSimilarity}`);
+        console.log(`  evidence links: ${result.byRule.evidenceLinks}`);
         if (result.candidatesProposed > result.edgesWritten) {
             console.log(`  (${result.candidatesProposed - result.edgesWritten} candidates were already-existing edges; INSERT OR IGNORE skipped them.)`);
         }
@@ -1759,17 +1837,60 @@ program
     .description('Regenerate vector embeddings for all entities (--fts rebuilds the keyword index instead)')
     .option('--namespace <namespace>', 'Reindex only entities in this namespace')
     .option('--fts', 'Rebuild the full-text keyword index instead of the vector index')
-    .option('--vectors', 'Also rebuild the vector index at the configured dimension. DESTRUCTIVE: drops every ' +
-    'stored embedding first. Needed only when switching embedding providers.')
+    .option('--discard-generation', 'Throw away a half-built vector index left by an interrupted rebuild, without rebuilding')
     .option('--json', 'Output as JSON')
+    .addOption(new Option('--vectors').hideHelp())
     .action(async (opts) => {
+    if (opts.vectors) {
+        if (opts.json) {
+            console.log(JSON.stringify({
+                refused: true,
+                reason: 'the --vectors flag is retired',
+                fix: 'run plain memesh reindex; to change provider first: memesh config set embedder.provider ollama|openai',
+                indexTouched: false,
+            }));
+            process.exit(1);
+        }
+        console.error('`memesh reindex --vectors` has been retired.');
+        console.error('');
+        console.error('It existed to consent to dropping every stored embedding before a refill.');
+        console.error('A rebuild now happens beside the live index and replaces it only when');
+        console.error('complete, so there is nothing left to consent to.');
+        console.error('');
+        console.error('Run plain `memesh reindex`. To change embedding provider first:');
+        console.error('  memesh config set embedder.provider ollama   (or openai)');
+        process.exit(1);
+    }
     requireOneOf(opts.namespace, NAMESPACES, '--namespace');
+    if (opts.discardGeneration) {
+        await withDatabase(async () => {
+            const read = readVectorGeneration();
+            const staged = generationRowIds().size;
+            if (read.state === 'none' && staged === 0) {
+                if (opts.json)
+                    console.log(JSON.stringify({ discarded: false, staged: 0 }));
+                else
+                    console.log('Nothing to discard: there is no half-built vector index.');
+                return;
+            }
+            const describe = read.state === 'open'
+                ? `${read.info.dimension}-dim, provider ${read.info.provider}, started ${read.info.startedAt}`
+                : read.state === 'unreadable'
+                    ? `marker unreadable (${read.detail})`
+                    : 'no marker';
+            discardVectorGeneration();
+            if (opts.json) {
+                console.log(JSON.stringify({ discarded: true, staged, generation: read, liveIndexTouched: false }));
+            }
+            else {
+                console.log(`Discarded a half-built vector index: ${staged} staged vectors (${describe}).\n` +
+                    '   Your live index was not touched. Run `memesh reindex` to build a new one.');
+            }
+        });
+        return;
+    }
     try {
         if (opts.fts) {
-            if (opts.vectors) {
-                console.error('❌ --fts and --vectors rebuild different indexes. Run them separately.');
-                process.exit(1);
-            }
             await withDatabase(async () => {
                 const { entities } = reindexFts();
                 if (opts.json) {
@@ -1781,68 +1902,84 @@ program
             });
             return;
         }
-        if (opts.vectors) {
-            if (opts.namespace) {
-                console.error('❌ --vectors rebuilds the whole vector index, which is shared by every\n' +
-                    '   namespace, so it cannot be limited to one. Combining it with\n' +
-                    '   --namespace would delete the other namespaces\' embeddings and never\n' +
-                    '   regenerate them. Run `memesh reindex --vectors` on its own, or drop\n' +
-                    '   --vectors to reindex just this namespace at the current dimension.');
-                process.exit(1);
+        if (!opts.namespace && !(await canRefillVectorIndex())) {
+            const embedder = detectCapabilities().embeddings;
+            const written = readConfig().embedder?.provider;
+            const known = embedder === 'openai' || embedder === 'ollama';
+            const invalid = written !== undefined && !known;
+            const unconfigured = written === undefined && !known;
+            const reason = invalid
+                ? `embedder.provider is set to '${written}', which is not a provider MeMesh knows`
+                : unconfigured
+                    ? 'no embedding provider is configured, so there is nothing to build vectors with'
+                    : 'could not produce a test embedding at the configured vector width';
+            const fix = invalid || unconfigured
+                ? (invalid ? 'Set it to one MeMesh knows: ' : 'Pick one first: ') +
+                    '`memesh config set embedder.provider ollama` (local, needs `ollama serve`) ' +
+                    'or `memesh config set embedder.provider openai` (needs OPENAI_API_KEY). Until then, recall ' +
+                    'runs on keyword search, which needs no rebuild.'
+                : 'Check that Ollama is running (or that your OpenAI API key is valid), then run this again. ' +
+                    '`memesh doctor` reports which provider is configured.';
+            if (opts.json) {
+                console.log(JSON.stringify({ refused: true, reason, fix, indexTouched: false }));
             }
-            if (!(await allowVectorIndexRebuild(getDbPath(), canRefillVectorIndex))) {
-                console.error('❌ Could not produce a test embedding at this database\'s vector width, so\n' +
-                    '   the index was left untouched. Rebuilding it deletes every stored\n' +
-                    '   embedding, and nothing here could regenerate them.\n' +
-                    '   Check that Ollama is running (or that your OpenAI API key is valid) —\n' +
-                    '   then run this again. `memesh doctor` reports which provider is configured.');
-                process.exit(1);
+            else {
+                console.error(`❌ Nothing was rebuilt: ${reason}.\n` +
+                    '   Your existing index is untouched and still answering queries.\n' +
+                    `   ${fix}`);
             }
+            process.exit(1);
         }
         await withDatabase(async () => {
             const result = await reindex({ namespace: opts.namespace });
-            const incomplete = result.missingVectors > 0 || result.failed > 0;
+            const incomplete = result.missingVectors > 0
+                || result.failed > 0
+                || result.generationSwapped === false
+                || result.abortedAfter !== null;
             if (opts.json) {
                 console.log(JSON.stringify(result));
             }
-            else if (incomplete) {
-                console.log(`⚠️  Reindex incomplete:`);
+            else {
+                console.log(incomplete ? `⚠️  Reindex incomplete:` : `✅ Reindex complete:`);
                 console.log(`   Processed: ${result.processed}`);
                 console.log(`   Embedded:  ${result.embedded}`);
                 console.log(`   Skipped:   ${result.skipped}`);
-                if (result.missingVectors > 0) {
-                    console.log(`   Still without a vector: ${result.missingVectors}`);
-                }
-                if (result.failed > 0 && result.missingVectors === 0) {
-                    console.log(`   Could not be regenerated: ${result.failed} ` +
-                        `(these still hold their previous embedding)`);
+                if (incomplete) {
+                    if (result.abortedAfter !== null) {
+                        console.log(`   Stopped early after ${result.abortedAfter} entities: the provider failed ` +
+                            `repeatedly. Everything embedded so far is kept — run this again to continue.`);
+                    }
+                    if (result.generationSwapped === false) {
+                        console.log(`   The new index was NOT switched in, so your existing index is untouched ` +
+                            `and still answering queries.`);
+                    }
+                    if (result.missingVectors > 0) {
+                        console.log(`   Still without a vector: ${result.missingVectors}`);
+                    }
+                    if (result.failed > 0 && result.missingVectors === 0) {
+                        console.log(`   Could not be regenerated: ${result.failed} ` +
+                            `(these still hold their previous embedding)`);
+                    }
+                    for (const [outcome, count] of Object.entries(result.outcomes)) {
+                        if (outcome !== 'stored' && count > 0)
+                            console.log(`     ${outcome}: ${count}`);
+                    }
                 }
-                for (const [outcome, count] of Object.entries(result.outcomes)) {
-                    if (outcome !== 'stored' && count > 0)
-                        console.log(`     ${outcome}: ${count}`);
+                else if (!result.pendingReindexCleared) {
+                    console.log(`   Note: ${result.missingVectorsDatabaseWide} memories in other namespaces still ` +
+                        `have no vector, so the reindex-needed flag stays set.`);
                 }
             }
-            else if (!result.pendingReindexCleared) {
-                console.log(`✅ Reindex complete:`);
-                console.log(`   Processed: ${result.processed}`);
-                console.log(`   Embedded:  ${result.embedded}`);
-                console.log(`   Skipped:   ${result.skipped}`);
-                console.log(`   Note: ${result.missingVectorsDatabaseWide} memories in other namespaces still ` +
-                    `have no vector, so the reindex-needed flag stays set.`);
-            }
-            else {
-                console.log(`✅ Reindex complete:`);
-                console.log(`   Processed: ${result.processed}`);
-                console.log(`   Embedded:  ${result.embedded}`);
-                console.log(`   Skipped:   ${result.skipped}`);
-            }
             if (incomplete)
                 process.exitCode = 1;
         });
     }
     catch (err) {
         if (err instanceof Error) {
-            console.error(`❌ Reindex failed: ${err.message}`);
+            if (opts.json)
+                console.log(JSON.stringify({ refused: true, reason: err.message, indexTouched: false }));
+            else
+                console.error(`❌ Reindex failed: ${err.message}`);
             process.exit(1);
         }
         throw err;