lore-memory 0.1.0

package/src/lib/budget.js

@@ -0,0 +1,57 @@
+'use strict';
+
+// Rough token estimate: 4 chars per token
+function estimateTokens(text) {
+  return Math.ceil((text || '').length / 4);
+}
+
+/**
+ * Format a single entry for MCP context injection.
+ * @param {object} entry
+ * @returns {string}
+ */
+function formatEntry(entry) {
+  const lines = [];
+  lines.push(`## [${entry.type.toUpperCase()}] ${entry.title}`);
+  lines.push(`ID: ${entry.id}`);
+  if (entry.files && entry.files.length > 0) {
+    lines.push(`Files: ${entry.files.join(', ')}`);
+  }
+  if (entry.tags && entry.tags.length > 0) {
+    lines.push(`Tags: ${entry.tags.join(', ')}`);
+  }
+  lines.push('');
+  if (entry.context) lines.push(entry.context);
+  if (entry.alternatives && entry.alternatives.length > 0) {
+    lines.push('');
+    lines.push(`Alternatives considered: ${entry.alternatives.join(', ')}`);
+  }
+  if (entry.tradeoffs) {
+    lines.push('');
+    lines.push(`Tradeoffs: ${entry.tradeoffs}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Select the highest-scoring entries that fit within a token budget.
+ * @param {object[]} rankedEntries - Entries sorted by score descending (from rankEntries)
+ * @param {number} budget - Max tokens
+ * @returns {string} Formatted context block
+ */
+function enforceBudget(rankedEntries, budget) {
+  const sections = [];
+  let used = 0;
+
+  for (const entry of rankedEntries) {
+    const text = formatEntry(entry);
+    const tokens = estimateTokens(text);
+    if (used + tokens > budget) break;
+    sections.push(text);
+    used += tokens;
+  }
+
+  return sections.join('\n\n---\n\n');
+}
+
+module.exports = { estimateTokens, formatEntry, enforceBudget };

package/src/lib/config.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const fs = require('fs-extra');
+const yaml = require('js-yaml');
+const path = require('path');
+const { LORE_DIR } = require('./index');
+
+const DEFAULTS = {
+  version: '1.0',
+  staleAfterDays: 30,
+  embed: {
+    model: 'nomic-embed-text',
+    autoEmbed: true,
+  },
+  mcp: {
+    tokenBudget: 4000,
+  },
+};
+
+function readConfig() {
+  const configPath = path.join(LORE_DIR, 'config.yaml');
+  let fileConfig = {};
+  try {
+    if (fs.existsSync(configPath)) {
+      fileConfig = yaml.load(fs.readFileSync(configPath, 'utf8')) || {};
+    }
+  } catch (e) {
+    // Fall back to defaults on parse error
+  }
+  return deepMerge(DEFAULTS, fileConfig);
+}
+
+function deepMerge(base, override) {
+  const result = Object.assign({}, base);
+  for (const key of Object.keys(override)) {
+    if (
+      override[key] !== null &&
+      typeof override[key] === 'object' &&
+      !Array.isArray(override[key]) &&
+      base[key] !== null &&
+      typeof base[key] === 'object' &&
+      !Array.isArray(base[key])
+    ) {
+      result[key] = deepMerge(base[key], override[key]);
+    } else {
+      result[key] = override[key];
+    }
+  }
+  return result;
+}
+
+module.exports = { readConfig };

package/src/lib/drafts.js

@@ -0,0 +1,104 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+const { LORE_DIR, readIndex, writeIndex, addEntryToIndex } = require('./index');
+const { generateId, writeEntry } = require('./entries');
+
+const DRAFTS_DIR = () => path.join(LORE_DIR, 'drafts');
+
+function ensureDraftsDir() {
+  fs.ensureDirSync(DRAFTS_DIR());
+}
+
+/**
+ * Save a draft to .lore/drafts/.
+ * @param {object} draft
+ * @returns {string} draftId
+ */
+function saveDraft(draft) {
+  ensureDraftsDir();
+  const draftId = draft.draftId || `draft-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+  const draftPath = path.join(DRAFTS_DIR(), `${draftId}.json`);
+  fs.writeJsonSync(draftPath, { ...draft, draftId, status: 'pending' }, { spaces: 2 });
+  return draftId;
+}
+
+/**
+ * List all pending drafts, sorted by confidence descending.
+ * @returns {object[]}
+ */
+function listDrafts() {
+  const dir = DRAFTS_DIR();
+  if (!fs.existsSync(dir)) return [];
+
+  const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
+  const drafts = [];
+  for (const file of files) {
+    try {
+      const draft = fs.readJsonSync(path.join(dir, file));
+      if (draft.status === 'pending') drafts.push(draft);
+    } catch (e) {}
+  }
+  return drafts.sort((a, b) => (b.confidence || 0) - (a.confidence || 0));
+}
+
+/**
+ * Promote a draft to a real Lore entry.
+ * @param {string} draftId
+ * @returns {object} the created entry
+ */
+function acceptDraft(draftId) {
+  const draftPath = path.join(DRAFTS_DIR(), `${draftId}.json`);
+  const draft = fs.readJsonSync(draftPath);
+
+  const type = draft.suggestedType || 'decision';
+  const title = draft.suggestedTitle || 'Untitled';
+  const id = generateId(type, title);
+
+  const entry = {
+    id,
+    type,
+    title,
+    context: draft.evidence || '',
+    files: draft.files || [],
+    tags: draft.tags || [],
+    alternatives: [],
+    tradeoffs: '',
+    date: new Date().toISOString(),
+  };
+
+  writeEntry(entry);
+  const index = readIndex();
+  addEntryToIndex(index, entry);
+  writeIndex(index);
+
+  // Auto-embed if Ollama available
+  try {
+    const { generateEmbedding, storeEmbedding } = require('./embeddings');
+    const text = [title, entry.context, ...entry.tags].join(' ');
+    generateEmbedding(text).then(vec => storeEmbedding(id, vec)).catch(() => {});
+  } catch (e) {}
+
+  fs.removeSync(draftPath);
+  return entry;
+}
+
+/**
+ * Delete a draft permanently.
+ * @param {string} draftId
+ */
+function deleteDraft(draftId) {
+  const draftPath = path.join(DRAFTS_DIR(), `${draftId}.json`);
+  fs.removeSync(draftPath);
+}
+
+/**
+ * Count pending drafts.
+ * @returns {number}
+ */
+function getDraftCount() {
+  return listDrafts().length;
+}
+
+module.exports = { saveDraft, listDrafts, acceptDraft, deleteDraft, getDraftCount };

package/src/lib/embeddings.js

@@ -0,0 +1,97 @@
+'use strict';
+
+const path = require('path');
+const { LORE_DIR } = require('./index');
+const { readConfig } = require('./config');
+
+let _db = null;
+
+function getDbPath() {
+  return path.join(LORE_DIR, 'embeddings.db');
+}
+
+function openDb() {
+  if (_db) return _db;
+  const Database = require('better-sqlite3');
+  _db = new Database(getDbPath());
+  _db.exec(`
+    CREATE TABLE IF NOT EXISTS embeddings (
+      id TEXT PRIMARY KEY,
+      vector TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    )
+  `);
+  return _db;
+}
+
+async function generateEmbedding(text) {
+  const { Ollama } = require('ollama');
+  const config = readConfig();
+  const model = config.embed && config.embed.model ? config.embed.model : 'nomic-embed-text';
+  const ollama = new Ollama();
+  const response = await ollama.embeddings({ model, prompt: text });
+  return response.embedding;
+}
+
+function storeEmbedding(id, vector) {
+  const db = openDb();
+  const stmt = db.prepare(`
+    INSERT OR REPLACE INTO embeddings (id, vector, updated_at)
+    VALUES (?, ?, ?)
+  `);
+  stmt.run(id, JSON.stringify(vector), new Date().toISOString());
+}
+
+function getEmbedding(id) {
+  const db = openDb();
+  const row = db.prepare('SELECT vector FROM embeddings WHERE id = ?').get(id);
+  if (!row) return null;
+  return JSON.parse(row.vector);
+}
+
+function cosineSimilarity(a, b) {
+  if (!a || !b || a.length !== b.length) return 0;
+  let dot = 0, magA = 0, magB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    magA += a[i] * a[i];
+    magB += b[i] * b[i];
+  }
+  const mag = Math.sqrt(magA) * Math.sqrt(magB);
+  if (mag === 0) return 0;
+  return dot / mag;
+}
+
+async function findSimilar(queryText, ids, topN = 5) {
+  const queryVec = await generateEmbedding(queryText);
+  const db = openDb();
+  const results = [];
+
+  for (const id of ids) {
+    const row = db.prepare('SELECT vector FROM embeddings WHERE id = ?').get(id);
+    if (!row) continue;
+    const vec = JSON.parse(row.vector);
+    const score = cosineSimilarity(queryVec, vec);
+    results.push({ id, score });
+  }
+
+  results.sort((a, b) => b.score - a.score);
+  return results.slice(0, topN);
+}
+
+function closeDb() {
+  if (_db) {
+    _db.close();
+    _db = null;
+  }
+}
+
+module.exports = {
+  openDb,
+  generateEmbedding,
+  storeEmbedding,
+  getEmbedding,
+  cosineSimilarity,
+  findSimilar,
+  closeDb,
+};

package/src/lib/entries.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const { LORE_DIR, getTypeDir } = require('./index');
+
+function getEntryPath(type, id) {
+  return path.join(LORE_DIR, getTypeDir(type), `${id}.json`);
+}
+
+function readEntry(entryPath) {
+  try {
+    return fs.readJsonSync(entryPath);
+  } catch (e) {
+    console.error(chalk.red(`Failed to read entry at ${entryPath}: ${e.message}`));
+    return null;
+  }
+}
+
+function writeEntry(entry) {
+  const entryPath = getEntryPath(entry.type, entry.id);
+  try {
+    fs.writeJsonSync(entryPath, entry, { spaces: 2 });
+    return entryPath;
+  } catch (e) {
+    console.error(chalk.red(`Failed to write entry: ${e.message}`));
+    process.exit(1);
+  }
+}
+
+function generateId(type, title) {
+  const words = title
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, '')
+    .split(/\s+/)
+    .filter(Boolean)
+    .slice(0, 3)
+    .join('-');
+  const ts = Math.floor(Date.now() / 1000);
+  return `${type}-${words}-${ts}`;
+}
+
+function readAllEntries(index) {
+  const entries = [];
+  for (const entryPath of Object.values(index.entries)) {
+    const entry = readEntry(entryPath);
+    if (entry) entries.push(entry);
+  }
+  return entries;
+}
+
+module.exports = {
+  getEntryPath,
+  readEntry,
+  writeEntry,
+  generateId,
+  readAllEntries,
+};

package/src/lib/format.js

@@ -0,0 +1,23 @@
+'use strict';
+
+const chalk = require('chalk');
+
+function printEntry(entry) {
+  const typeLabel = `[${entry.type.toUpperCase()}]`;
+  console.log(chalk.bold(`${typeLabel} ${entry.title}`) + chalk.gray(` (${entry.date})`));
+  console.log(`  → ${entry.context}`);
+
+  if (entry.alternatives && entry.alternatives.length > 0) {
+    for (const alt of entry.alternatives) {
+      console.log(chalk.yellow(`  → Rejected: ${alt}`));
+    }
+  }
+
+  if (entry.tradeoffs) {
+    console.log(chalk.gray(`  → Tradeoffs: ${entry.tradeoffs}`));
+  }
+
+  console.log();
+}
+
+module.exports = { printEntry };

package/src/lib/git.js

@@ -0,0 +1,18 @@
+'use strict';
+
+const { execSync } = require('child_process');
+
+function getRecentFiles(depth = 5) {
+  try {
+    const output = execSync(`git diff --name-only HEAD~${depth} HEAD`, {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return output.trim().split('\n').filter(Boolean);
+  } catch (e) {
+    // Not a git repo, no commits yet, or not enough history
+    return [];
+  }
+}
+
+module.exports = { getRecentFiles };

package/src/lib/graph.js

@@ -0,0 +1,51 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+const { LORE_DIR } = require('./index');
+
+const GRAPH_PATH = () => path.join(LORE_DIR, 'graph.json');
+
+function emptyGraph() {
+  return {
+    imports: {},    // filepath → [filepath]
+    importedBy: {}, // filepath → [filepath]
+    lastUpdated: new Date().toISOString(),
+  };
+}
+
+function loadGraph() {
+  const p = GRAPH_PATH();
+  if (!fs.existsSync(p)) return emptyGraph();
+  try { return fs.readJsonSync(p); } catch (e) { return emptyGraph(); }
+}
+
+function saveGraph(graph) {
+  graph.lastUpdated = new Date().toISOString();
+  fs.writeJsonSync(GRAPH_PATH(), graph, { spaces: 2 });
+}
+
+/**
+ * For a given filepath, return graph-context entry IDs weighted by relationship.
+ * @param {string} filepath  Normalized relative path
+ * @param {object} graph
+ * @param {object} index
+ * @returns {{ imports: Array<{file,entryIds}>, importedBy: Array<{file,entryIds}> }}
+ */
+function getGraphContext(filepath, graph, index) {
+  const normalized = filepath.replace(/^\.\//, '');
+  const result = { imports: [], importedBy: [] };
+
+  for (const dep of (graph.imports[normalized] || [])) {
+    const entryIds = index.files[dep] || [];
+    if (entryIds.length > 0) result.imports.push({ file: dep, entryIds });
+  }
+  for (const dep of (graph.importedBy[normalized] || [])) {
+    const entryIds = index.files[dep] || [];
+    if (entryIds.length > 0) result.importedBy.push({ file: dep, entryIds });
+  }
+
+  return result;
+}
+
+module.exports = { loadGraph, saveGraph, emptyGraph, getGraphContext };

package/src/lib/guard.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const chalk = require('chalk');
+const { loreExists } = require('./index');
+
+function requireInit() {
+  if (!loreExists()) {
+    console.error(chalk.red('📖 Run lore init first'));
+    process.exit(1);
+  }
+}
+
+module.exports = { requireInit };

package/src/lib/index.js

@@ -0,0 +1,84 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+const LORE_DIR = '.lore';
+const INDEX_PATH = path.join(LORE_DIR, 'index.json');
+
+function loreExists() {
+  return fs.existsSync(LORE_DIR);
+}
+
+function readIndex() {
+  try {
+    return fs.readJsonSync(INDEX_PATH);
+  } catch (e) {
+    if (e.code === 'ENOENT') {
+      console.error(chalk.red(`📖 index.json not found at ${INDEX_PATH}`));
+    } else {
+      console.error(chalk.red(`📖 Malformed index.json at ${INDEX_PATH}: ${e.message}`));
+    }
+    process.exit(1);
+  }
+}
+
+function writeIndex(index) {
+  try {
+    index.lastUpdated = new Date().toISOString();
+    fs.writeJsonSync(INDEX_PATH, index, { spaces: 2 });
+  } catch (e) {
+    console.error(chalk.red(`Failed to write index.json: ${e.message}`));
+    process.exit(1);
+  }
+}
+
+function emptyIndex() {
+  return {
+    files: {},
+    entries: {},
+    lastUpdated: new Date().toISOString(),
+  };
+}
+
+function getTypeDir(type) {
+  return type === 'graveyard' ? 'graveyard' : type + 's';
+}
+
+function addEntryToIndex(index, entry) {
+  const typeDir = getTypeDir(entry.type);
+  index.entries[entry.id] = `.lore/${typeDir}/${entry.id}.json`;
+
+  for (const filepath of entry.files) {
+    const normalized = filepath.replace(/^\.\//, '');
+
+    if (!index.files[normalized]) index.files[normalized] = [];
+    if (!index.files[normalized].includes(entry.id)) {
+      index.files[normalized].push(entry.id);
+    }
+
+    // Index immediate parent directory only (ancestor walking happens at lookup time)
+    const dir = path.dirname(normalized.replace(/\/$/, ''));
+    if (dir && dir !== '.') {
+      const dirKey = dir + '/';
+      if (!index.files[dirKey]) index.files[dirKey] = [];
+      if (!index.files[dirKey].includes(entry.id)) {
+        index.files[dirKey].push(entry.id);
+      }
+    }
+  }
+
+  index.lastUpdated = new Date().toISOString();
+}
+
+module.exports = {
+  LORE_DIR,
+  INDEX_PATH,
+  loreExists,
+  readIndex,
+  writeIndex,
+  emptyIndex,
+  getTypeDir,
+  addEntryToIndex,
+};

package/src/lib/nlp.js

@@ -0,0 +1,106 @@
+'use strict';
+
+const natural = require('natural');
+
+// Type detection patterns
+const TYPE_PATTERNS = [
+  { type: 'invariant', re: /\b(must|always|never|shall|required|mandatory|do not|don't)\b/i, confidence: 0.9 },
+  { type: 'graveyard', re: /\b(tried|abandoned|removed|replaced|deprecated|don'?t use|do not use|we used to)\b/i, confidence: 0.85 },
+  { type: 'gotcha', re: /\b(warning|careful|hack|workaround|footgun|beware|gotcha|pitfall|tricky|careful)\b/i, confidence: 0.8 },
+  { type: 'decision', re: /\b(because|reason|chose|decided|switched|opted|note:|important:|we chose|we use)\b/i, confidence: 0.7 },
+];
+
+// Trigger phrases for comment scoring
+const TRIGGER_PHRASES = [
+  "don't", "never", "always", "because", "warning", "hack",
+  "todo: explain", "note:", "important:", "must", "shall",
+  "tried", "abandoned", "careful", "workaround", "footgun",
+  "beware", "replaced", "deprecated", "we tried", "latency",
+];
+
+const STOP_WORDS = new Set([
+  'a', 'an', 'the', 'is', 'are', 'was', 'were', 'be', 'been',
+  'being', 'i', 'we', 'it', 'this', 'that', 'to', 'of', 'in',
+  'for', 'on', 'with', 'as', 'at', 'by', 'or', 'and', 'but',
+]);
+
+/**
+ * Detect the suggested entry type from a text snippet.
+ * @param {string} text
+ * @returns {{ type: string, confidence: number }}
+ */
+function detectType(text) {
+  for (const { type, re, confidence } of TYPE_PATTERNS) {
+    if (re.test(text)) return { type, confidence };
+  }
+  return { type: 'decision', confidence: 0.4 };
+}
+
+/**
+ * Extract a short title from comment text.
+ * @param {string} text
+ * @param {number} maxWords
+ * @returns {string}
+ */
+function extractTitle(text, maxWords = 8) {
+  // Strip comment markers
+  const stripped = text
+    .replace(/^[\s\/\*#\-]+/, '')
+    .replace(/\*\//g, '')
+    .trim();
+
+  const tokenizer = new natural.WordTokenizer();
+  const words = tokenizer.tokenize(stripped) || [];
+  const meaningful = words.filter(w => w.length > 2 && !STOP_WORDS.has(w.toLowerCase()));
+
+  const titleWords = meaningful.slice(0, maxWords);
+  if (titleWords.length === 0) return stripped.slice(0, 50);
+
+  // Title-case
+  return titleWords
+    .map((w, i) => i === 0 ? w.charAt(0).toUpperCase() + w.slice(1) : w)
+    .join(' ');
+}
+
+/**
+ * Slugify text for use in IDs.
+ * @param {string} text
+ * @returns {string}
+ */
+function slugify(text) {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+
+/**
+ * Score a comment 0–1 for lore-worthiness.
+ * @param {string} comment
+ * @returns {number}
+ */
+function scoreComment(comment) {
+  const lower = comment.toLowerCase();
+  let score = 0;
+
+  // Trigger phrase present
+  for (const phrase of TRIGGER_PHRASES) {
+    if (lower.includes(phrase)) {
+      score += 0.4;
+      break;
+    }
+  }
+
+  // Length bonus
+  if (comment.length > 20) score += 0.2;
+  if (comment.length > 60) score += 0.2;
+
+  // Penalty for generic TODO/FIXME without explanation
+  if (/\b(todo|fixme)\b/i.test(lower) && !lower.includes('todo: explain')) {
+    score -= 0.35;
+  }
+
+  // Bonus for numbers/metrics (performance constraints etc.)
+  if (/\d+(ms|mb|kb|s|%|x)/.test(lower)) score += 0.1;
+
+  return Math.max(0, Math.min(1, score));
+}
+
+module.exports = { detectType, extractTitle, slugify, scoreComment };