lore-memory 0.1.0

package/bin/lore.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+'use strict';
+
+const { Command } = require('commander');
+
+const program = new Command();
+
+program
+  .name('lore')
+  .description('Persistent project memory for developers')
+  .version('0.1.0')
+  .action(() => program.outputHelp());
+
+program
+  .command('init')
+  .description('Initialize Lore in the current project')
+  .action(require('../src/commands/init'));
+
+program
+  .command('log')
+  .description('Log a new decision, invariant, graveyard entry, or gotcha')
+  .option('--type <type>', 'Entry type (decision|invariant|graveyard|gotcha)')
+  .option('--title <title>', 'Entry title')
+  .option('--context <context>', 'Context/reason')
+  .option('--alternatives <alternatives>', 'Alternatives considered')
+  .option('--tradeoffs <tradeoffs>', 'Tradeoffs')
+  .option('--tags <tags>', 'Comma-separated tags')
+  .option('--files <files>', 'Comma-separated file paths')
+  .action(require('../src/commands/log'));
+
+program
+  .command('why <filepath>')
+  .description('Show all Lore entries linked to a file or directory')
+  .action(require('../src/commands/why'));
+
+program
+  .command('status')
+  .description('Show entry counts and stale warnings')
+  .action(require('../src/commands/status'));
+
+program
+  .command('stale')
+  .description('Show detailed stale entry report')
+  .action(require('../src/commands/stale'));
+
+program
+  .command('search <query>')
+  .description('Search all entries for a keyword')
+  .action(require('../src/commands/search'));
+
+program
+  .command('export')
+  .description('Export all entries to CLAUDE.md at project root')
+  .action(require('../src/commands/export'));
+
+program
+  .command('edit <id>')
+  .description('Open an entry JSON in VSCode')
+  .action(require('../src/commands/edit'));
+
+program
+  .command('serve')
+  .description('Start the Lore MCP server (stdio) for use with Claude Code')
+  .option('-q, --quiet', 'Suppress startup messages (use when piped into MCP client)')
+  .action(require('../src/commands/serve'));
+
+program
+  .command('embed')
+  .description('Build semantic search index using Ollama (requires ollama pull nomic-embed-text)')
+  .action(require('../src/commands/embed'));
+
+program
+  .command('onboard')
+  .description('Print a re-onboarding brief for this project')
+  .option('--days <n>', 'Only show if away for at least N days', '0')
+  .action(require('../src/commands/onboard'));
+
+program
+  .command('watch')
+  .description('Watch project for decisions and mine comments passively')
+  .option('-d, --daemon', 'Run as background daemon')
+  .option('--stop', 'Stop the running background daemon')
+  .option('--daemon-worker', { hidden: true })
+  .action(require('../src/commands/watch'));
+
+program
+  .command('mine [path]')
+  .description('Mine source files for lore-worthy comments and create drafts')
+  .action(require('../src/commands/mine'));
+
+program
+  .command('drafts')
+  .description('Review and approve auto-captured draft entries')
+  .option('--auto', 'Auto-accept drafts with confidence >= 0.8')
+  .action(require('../src/commands/drafts'));
+
+program
+  .command('score')
+  .description('Show the Lore Score — memory health metric for this project')
+  .action(require('../src/commands/score'));
+
+program
+  .command('graph [filepath]')
+  .description('Show or build the module dependency graph')
+  .option('--build', 'Rebuild the full graph from source')
+  .action(require('../src/commands/graph'));
+
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "lore-memory",
+  "version": "0.1.0",
+  "description": "Persistent project memory for developers. Captures decisions, invariants, gotchas, and graveyard entries — automatically and manually — and injects them into AI coding sessions.",
+  "main": "bin/lore.js",
+  "bin": {
+    "lore": "./bin/lore.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "lore",
+    "memory",
+    "decisions",
+    "architecture",
+    "ai",
+    "claude",
+    "mcp",
+    "context",
+    "knowledge-base",
+    "developer-tools",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/YOUR_USERNAME/lore-cli.git"
+  },
+  "homepage": "https://github.com/YOUR_USERNAME/lore-cli#readme",
+  "bugs": {
+    "url": "https://github.com/YOUR_USERNAME/lore-cli/issues"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.29.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "better-sqlite3": "^12.6.2",
+    "chalk": "^4",
+    "chokidar": "^3.6.0",
+    "commander": "^11",
+    "fs-extra": "^11",
+    "glob": "^10.5.0",
+    "inquirer": "^8",
+    "js-yaml": "^4",
+    "natural": "^6.12.0",
+    "ollama": "^0.6.3"
+  }
+}

package/src/commands/drafts.js

@@ -0,0 +1,144 @@
+'use strict';
+
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+const path = require('path');
+const fs = require('fs-extra');
+const { listDrafts, acceptDraft, deleteDraft } = require('../lib/drafts');
+const { LORE_DIR } = require('../lib/index');
+const { requireInit } = require('../lib/guard');
+
+async function drafts(options) {
+  requireInit();
+
+  const pending = listDrafts();
+
+  if (pending.length === 0) {
+    console.log(chalk.green('✓ No pending drafts'));
+    return;
+  }
+
+  // Auto mode: accept high-confidence, leave rest
+  if (options.auto) {
+    let accepted = 0;
+    for (const draft of pending) {
+      if ((draft.confidence || 0) >= 0.8) {
+        acceptDraft(draft.draftId);
+        console.log(chalk.green(`  ✓ ${draft.suggestedTitle}`));
+        accepted++;
+      }
+    }
+    const remaining = pending.length - accepted;
+    console.log(chalk.green(`\n📖 Auto-accepted ${accepted} draft${accepted === 1 ? '' : 's'}`));
+    if (remaining > 0) {
+      console.log(chalk.cyan(`   ${remaining} remaining — run: lore drafts`));
+    }
+    return;
+  }
+
+  console.log(chalk.cyan(`\n📖 ${pending.length} pending draft${pending.length === 1 ? '' : 's'}\n`));
+
+  for (let i = 0; i < pending.length; i++) {
+    const draft = pending[i];
+    const conf = Math.round((draft.confidence || 0) * 100);
+    const typeColor = {
+      decision: chalk.blue,
+      invariant: chalk.red,
+      gotcha: chalk.yellow,
+      graveyard: chalk.dim,
+    }[draft.suggestedType] || chalk.white;
+
+    console.log(chalk.cyan(`[${i + 1}/${pending.length}] SUGGESTED: ${typeColor(draft.suggestedType.toUpperCase())}  (confidence: ${conf}%)`));
+    console.log(`  ${chalk.bold('Title:')}    ${draft.suggestedTitle}`);
+    console.log(`  ${chalk.bold('Evidence:')} ${draft.evidence}`);
+    if (draft.files && draft.files.length > 0) {
+      console.log(`  ${chalk.bold('Files:')}    ${draft.files.join(', ')}`);
+    }
+    console.log();
+
+    let done = false;
+    while (!done) {
+      let action;
+      try {
+        const ans = await inquirer.prompt([{
+          type: 'list',
+          name: 'action',
+          message: 'Action:',
+          choices: [
+            { name: '[a] Accept', value: 'accept' },
+            { name: '[e] Edit then save', value: 'edit' },
+            { name: '[s] Skip', value: 'skip' },
+            { name: '[d] Delete', value: 'delete' },
+            { name: '[q] Quit', value: 'quit' },
+          ],
+        }]);
+        action = ans.action;
+      } catch (e) {
+        console.log(chalk.yellow('\nAborted.'));
+        return;
+      }
+
+      if (action === 'accept') {
+        const entry = acceptDraft(draft.draftId);
+        console.log(chalk.green(`  ✓ Saved as ${entry.id}`));
+        done = true;
+      } else if (action === 'edit') {
+        let edited;
+        try {
+          edited = await inquirer.prompt([
+            {
+              type: 'list',
+              name: 'type',
+              message: 'Type:',
+              choices: ['decision', 'invariant', 'gotcha', 'graveyard'],
+              default: draft.suggestedType,
+            },
+            {
+              type: 'input',
+              name: 'title',
+              message: 'Title:',
+              default: draft.suggestedTitle,
+            },
+            {
+              type: 'input',
+              name: 'context',
+              message: 'Context:',
+              default: draft.evidence,
+            },
+          ]);
+        } catch (e) {
+          console.log(chalk.yellow('\nAborted.'));
+          return;
+        }
+
+        // Update draft on disk, then accept
+        const draftPath = path.join(LORE_DIR, 'drafts', `${draft.draftId}.json`);
+        fs.writeJsonSync(draftPath, {
+          ...draft,
+          suggestedType: edited.type,
+          suggestedTitle: edited.title,
+          evidence: edited.context,
+        }, { spaces: 2 });
+
+        const entry = acceptDraft(draft.draftId);
+        console.log(chalk.green(`  ✓ Saved as ${entry.id}`));
+        done = true;
+      } else if (action === 'skip') {
+        console.log(chalk.dim('  Skipped'));
+        done = true;
+      } else if (action === 'delete') {
+        deleteDraft(draft.draftId);
+        console.log(chalk.dim('  Deleted'));
+        done = true;
+      } else if (action === 'quit') {
+        console.log(chalk.cyan('\n  Remaining drafts saved. Run: lore drafts'));
+        return;
+      }
+    }
+    console.log();
+  }
+
+  console.log(chalk.green('✓ All drafts reviewed'));
+}
+
+module.exports = drafts;

package/src/commands/edit.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const { execSync } = require('child_process');
+const chalk = require('chalk');
+const { readIndex } = require('../lib/index');
+const { requireInit } = require('../lib/guard');
+
+function edit(id) {
+  requireInit();
+  try {
+    const index = readIndex();
+    const entryPath = index.entries[id];
+
+    if (!entryPath) {
+      console.error(chalk.red(`Entry not found: ${id}`));
+      process.exit(1);
+    }
+
+    try {
+      execSync(`code "${entryPath}"`, { stdio: 'inherit' });
+    } catch (e) {
+      console.log(chalk.yellow(`Could not open VSCode. File path: ${entryPath}`));
+    }
+  } catch (e) {
+    console.error(chalk.red(`Failed to edit: ${e.message}`));
+    process.exit(1);
+  }
+}
+
+module.exports = edit;

package/src/commands/embed.js

@@ -0,0 +1,63 @@
+'use strict';
+
+const chalk = require('chalk');
+const { readIndex } = require('../lib/index');
+const { readEntry } = require('../lib/entries');
+const { generateEmbedding, storeEmbedding } = require('../lib/embeddings');
+const { requireInit } = require('../lib/guard');
+
+async function embed() {
+  requireInit();
+  try {
+    const index = readIndex();
+    const ids = Object.keys(index.entries);
+
+    if (ids.length === 0) {
+      console.log(chalk.yellow('No entries to embed. Run lore log first.'));
+      return;
+    }
+
+    console.log(chalk.cyan(`📖 Embedding ${ids.length} entries using Ollama...`));
+    let success = 0;
+    let failed = 0;
+
+    for (const id of ids) {
+      const entryPath = index.entries[id];
+      const entry = readEntry(entryPath);
+      if (!entry) continue;
+
+      const text = [
+        entry.title,
+        entry.context,
+        ...(entry.alternatives || []),
+        entry.tradeoffs || '',
+        ...(entry.tags || []),
+      ].join(' ');
+
+      try {
+        const vector = await generateEmbedding(text);
+        storeEmbedding(id, vector);
+        process.stdout.write(chalk.green('.'));
+        success++;
+      } catch (e) {
+        process.stdout.write(chalk.red('x'));
+        failed++;
+      }
+    }
+
+    console.log('');
+    console.log(chalk.green(`✓ Embedded ${success}/${ids.length} entries`));
+    if (failed > 0) {
+      console.log(chalk.yellow(`⚠ ${failed} failed (is Ollama running? Run: ollama pull nomic-embed-text)`));
+    }
+  } catch (e) {
+    if (e.message && e.message.includes('Ollama')) {
+      console.error(chalk.red('Ollama not available. Start Ollama and run: ollama pull nomic-embed-text'));
+    } else {
+      console.error(chalk.red(`Failed to embed: ${e.message}`));
+    }
+    process.exit(1);
+  }
+}
+
+module.exports = embed;

package/src/commands/export.js

@@ -0,0 +1,76 @@
+'use strict';
+
+const fs = require('fs-extra');
+const chalk = require('chalk');
+const { readIndex } = require('../lib/index');
+const { readEntry } = require('../lib/entries');
+const { requireInit } = require('../lib/guard');
+
+function exportLore() {
+  requireInit();
+  try {
+    const index = readIndex();
+    const allEntries = [];
+
+    for (const entryPath of Object.values(index.entries)) {
+      const entry = readEntry(entryPath);
+      if (entry) allEntries.push(entry);
+    }
+
+    const byType = {
+      decision: allEntries.filter(e => e.type === 'decision'),
+      invariant: allEntries.filter(e => e.type === 'invariant'),
+      graveyard: allEntries.filter(e => e.type === 'graveyard'),
+      gotcha: allEntries.filter(e => e.type === 'gotcha'),
+    };
+
+    let md = '# Project Lore\n';
+    md += '> Auto-generated by lore export. Do not edit manually — run `lore export` to regenerate.\n\n';
+
+    if (byType.decision.length > 0) {
+      md += '## Architectural Decisions\n';
+      for (const e of byType.decision) {
+        md += `- **${e.title}** (\`${e.files.join(', ')}\`): ${e.context}\n`;
+        if (e.alternatives && e.alternatives.length > 0) {
+          md += `  - Alternatives considered: ${e.alternatives.join('; ')}\n`;
+        }
+        if (e.tradeoffs) {
+          md += `  - Tradeoffs: ${e.tradeoffs}\n`;
+        }
+      }
+      md += '\n';
+    }
+
+    if (byType.invariant.length > 0) {
+      md += '## Invariants\n';
+      for (const e of byType.invariant) {
+        md += `- **${e.title}** (\`${e.files.join(', ')}\`): ${e.context}\n`;
+      }
+      md += '\n';
+    }
+
+    if (byType.graveyard.length > 0) {
+      md += '## Graveyard (Abandoned Approaches)\n';
+      for (const e of byType.graveyard) {
+        md += `- **${e.title}** (\`${e.files.join(', ')}\`): ${e.context}\n`;
+      }
+      md += '\n';
+    }
+
+    if (byType.gotcha.length > 0) {
+      md += '## Gotchas\n';
+      for (const e of byType.gotcha) {
+        md += `- **${e.title}** (\`${e.files.join(', ')}\`): ${e.context}\n`;
+      }
+      md += '\n';
+    }
+
+    fs.writeFileSync('CLAUDE.md', md);
+    console.log(chalk.green('✓ CLAUDE.md written to project root — Claude Code will read this on next session start'));
+  } catch (e) {
+    console.error(chalk.red(`Failed to export: ${e.message}`));
+    process.exit(1);
+  }
+}
+
+module.exports = exportLore;

package/src/commands/graph.js

@@ -0,0 +1,80 @@
+'use strict';
+
+const chalk = require('chalk');
+const path = require('path');
+const { loadGraph, saveGraph } = require('../lib/graph');
+const { readIndex } = require('../lib/index');
+const { requireInit } = require('../lib/guard');
+
+function graph(filepath, options) {
+  requireInit();
+  const projectRoot = process.cwd();
+
+  try {
+    let g = loadGraph();
+
+    // Rebuild graph if requested or it's empty
+    if (options.build || (Object.keys(g.imports).length === 0 && filepath)) {
+      console.log(chalk.cyan('📖 Building dependency graph...'));
+      const { buildFullGraph } = require('../watcher/graph');
+      g = buildFullGraph(projectRoot);
+      saveGraph(g);
+      console.log(chalk.green(`✓ Graph built: ${Object.keys(g.imports).length} files indexed`));
+      if (!filepath) return;
+    }
+
+    if (!filepath) {
+      // Stats overview
+      const fileCount = Object.keys(g.imports).length;
+      const edgeCount = Object.values(g.imports).reduce((sum, arr) => sum + arr.length, 0);
+      console.log(chalk.cyan(`\n📖 Dependency Graph`));
+      console.log(`  Files indexed: ${fileCount}`);
+      console.log(`  Import edges:  ${edgeCount}`);
+      if (g.lastUpdated) console.log(chalk.dim(`  Last updated:  ${g.lastUpdated}`));
+      console.log(chalk.dim('\n  Run: lore graph <filepath>  for file details'));
+      console.log(chalk.dim('  Run: lore graph --build     to rebuild from scratch'));
+      return;
+    }
+
+    const index = readIndex();
+    const normalized = path.relative(projectRoot, path.resolve(filepath)).replace(/\\/g, '/');
+
+    const imports = g.imports[normalized] || [];
+    const importedBy = g.importedBy[normalized] || [];
+
+    if (imports.length === 0 && importedBy.length === 0) {
+      console.log(chalk.yellow(`No graph data for ${filepath}`));
+      console.log(chalk.dim('  Run: lore graph --build  to build the dependency graph'));
+      return;
+    }
+
+    const entryCount = (file) => (index.files[file] || []).length;
+
+    console.log(chalk.cyan(`\n📖 ${filepath}\n`));
+
+    if (imports.length > 0) {
+      console.log(chalk.bold('Imports:'));
+      for (const dep of imports) {
+        const n = entryCount(dep);
+        const badge = n > 0 ? chalk.green(` → ${n} Lore entr${n === 1 ? 'y' : 'ies'}`) : chalk.dim(` → 0 Lore entries`);
+        console.log(`  ${dep}${badge}`);
+      }
+      console.log();
+    }
+
+    if (importedBy.length > 0) {
+      console.log(chalk.bold('Imported by:'));
+      for (const dep of importedBy) {
+        const n = entryCount(dep);
+        const badge = n > 0 ? chalk.green(` → ${n} Lore entr${n === 1 ? 'y' : 'ies'}`) : chalk.dim(` → 0 Lore entries`);
+        console.log(`  ${dep}${badge}`);
+      }
+      console.log();
+    }
+  } catch (e) {
+    console.error(chalk.red(`Failed: ${e.message}`));
+    process.exit(1);
+  }
+}
+
+module.exports = graph;

package/src/commands/init.js

@@ -0,0 +1,110 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+const yaml = require('js-yaml');
+const chalk = require('chalk');
+const { LORE_DIR, emptyIndex } = require('../lib/index');
+
+const HOOK_CONTENT = `#!/bin/bash
+LINECOUNT=$(git diff HEAD~1 --shortstat 2>/dev/null | grep -o '[0-9]* insertion' | grep -o '[0-9]*' || echo 0)
+if [ "\${LINECOUNT:-0}" -gt 50 ]; then
+  echo "📖 Lore: Significant change detected. Log it? (y/n)"
+  read -r answer </dev/tty
+  if [ "$answer" = "y" ]; then
+    lore log </dev/tty
+  fi
+fi
+`;
+
+async function init() {
+  try {
+    const dirs = ['decisions', 'invariants', 'graveyard', 'gotchas', 'modules', 'sessions', 'drafts'];
+    for (const dir of dirs) {
+      await fs.ensureDir(path.join(LORE_DIR, dir));
+    }
+
+    const indexPath = path.join(LORE_DIR, 'index.json');
+    if (!fs.existsSync(indexPath)) {
+      await fs.writeJson(indexPath, emptyIndex(), { spaces: 2 });
+    }
+
+    const configPath = path.join(LORE_DIR, 'config.yaml');
+    if (!fs.existsSync(configPath)) {
+      const config = {
+        version: '1.0',
+        project: path.basename(process.cwd()),
+        staleAfterDays: 30,
+        embed: {
+          model: 'nomic-embed-text',
+          autoEmbed: true,
+        },
+        mcp: {
+          tokenBudget: 4000,
+        },
+        watchMode: false,
+        watchIgnore: ['node_modules', 'dist', '.git', 'coverage'],
+        commentPatterns: ["don't", 'never', 'always', 'because', 'warning', 'hack', 'note:', 'important:'],
+        signalThreshold: 30,
+        semanticStaleness: true,
+        scoringWeights: { coverage: 0.4, freshness: 0.35, depth: 0.25 },
+      };
+      await fs.writeFile(configPath, yaml.dump(config));
+    }
+
+    // Create a .lore/.gitignore so generated/ephemeral files are excluded
+    // but entry json files, config.yaml, and index.json are committed.
+    const loreGitignorePath = path.join(LORE_DIR, '.gitignore');
+    if (!fs.existsSync(loreGitignorePath)) {
+      await fs.writeFile(loreGitignorePath,
+        '# Auto-generated by lore init\nembeddings.db\nsessions/\nwatch-state.json\nwatcher.pid\nwatcher.log\nscore.json\n'
+      );
+    }
+
+    const hookDir = path.join('.git', 'hooks');
+    if (fs.existsSync(hookDir)) {
+      const hookPath = path.join(hookDir, 'post-commit');
+      await fs.writeFile(hookPath, HOOK_CONTENT);
+      await fs.chmod(hookPath, '755');
+      console.log(chalk.green('✓ Git post-commit hook installed'));
+    } else {
+      console.log(chalk.yellow('⚠ Not a git repo — hook not installed'));
+    }
+
+    console.log(chalk.green(`✓ Lore initialized at ${LORE_DIR}/`));
+    console.log(chalk.cyan('  Run: lore mine .       to scan codebase for lore-worthy comments'));
+    console.log(chalk.cyan('  Run: lore log          to create your first entry manually'));
+    console.log(chalk.cyan('  Run: lore watch        to start passive capture'));
+    console.log(chalk.cyan('  Run: lore serve        to start the MCP server'));
+
+    // Auto-mine the codebase on first init if source files exist
+    const index = require('../lib/index').readIndex();
+    const entryCount = Object.keys(index.entries).length;
+    if (entryCount === 0) {
+      const { globSync } = require('glob');
+      const hasSource = globSync('**/*.{js,ts,jsx,tsx}', {
+        cwd: process.cwd(),
+        ignore: ['node_modules/**', 'dist/**', '.lore/**'],
+        absolute: false,
+      }).length > 0;
+
+      if (hasSource) {
+        console.log(chalk.dim('\n  Scanning codebase for lore-worthy comments...'));
+        try {
+          const { mineDirectory } = require('../watcher/comments');
+          const count = mineDirectory(process.cwd(), process.cwd());
+          if (count > 0) {
+            console.log(chalk.cyan(`  Found ${count} draft entr${count === 1 ? 'y' : 'ies'} — run: lore drafts`));
+          }
+        } catch (e) {
+          // Non-fatal
+        }
+      }
+    }
+  } catch (e) {
+    console.error(chalk.red(`Failed to initialize Lore: ${e.message}`));
+    process.exit(1);
+  }
+}
+
+module.exports = init;