lore-memory 0.1.0

package/src/lib/relevance.js

@@ -0,0 +1,81 @@
+'use strict';
+
+const path = require('path');
+const { getEmbedding, cosineSimilarity } = require('./embeddings');
+
+// Weights for relevance scoring
+const WEIGHTS = {
+  directFileMatch: 1.0,
+  parentDirMatch: 0.7,
+  semanticSimilarity: 0.5,
+  tagOverlap: 0.3,
+};
+
+/**
+ * Score an entry against a query context.
+ * @param {object} entry - The lore entry
+ * @param {object} context - { filepath, queryText, queryEmbedding, tags }
+ * @returns {number} score 0–1+
+ */
+function scoreEntry(entry, context) {
+  let score = 0;
+
+  // Direct file match
+  if (context.filepath && entry.files && entry.files.length > 0) {
+    const normalizedQuery = context.filepath.replace(/^\.\//, '');
+    for (const f of entry.files) {
+      const normalizedFile = f.replace(/^\.\//, '');
+      if (normalizedFile === normalizedQuery) {
+        score += WEIGHTS.directFileMatch;
+        break;
+      }
+    }
+  }
+
+  // Parent dir match
+  if (context.filepath && entry.files && entry.files.length > 0) {
+    const queryDir = path.dirname(context.filepath.replace(/^\.\//, ''));
+    for (const f of entry.files) {
+      const fileDir = path.dirname(f.replace(/^\.\//, ''));
+      if (fileDir === queryDir && queryDir !== '.') {
+        score += WEIGHTS.parentDirMatch;
+        break;
+      }
+    }
+  }
+
+  // Semantic similarity (if query embedding and entry embedding available)
+  if (context.queryEmbedding) {
+    const entryVec = getEmbedding(entry.id);
+    if (entryVec) {
+      const sim = cosineSimilarity(context.queryEmbedding, entryVec);
+      score += sim * WEIGHTS.semanticSimilarity;
+    }
+  }
+
+  // Tag overlap
+  if (context.tags && entry.tags && context.tags.length > 0 && entry.tags.length > 0) {
+    const queryTagSet = new Set(context.tags.map(t => t.toLowerCase()));
+    const matches = entry.tags.filter(t => queryTagSet.has(t.toLowerCase())).length;
+    const overlap = matches / Math.max(queryTagSet.size, entry.tags.length);
+    score += overlap * WEIGHTS.tagOverlap;
+  }
+
+  return score;
+}
+
+/**
+ * Rank entries by relevance to a context.
+ * @param {object[]} entries
+ * @param {object} context
+ * @returns {object[]} sorted entries with .score attached
+ */
+function rankEntries(entries, context) {
+  return entries
+    .map(entry => ({ entry, score: scoreEntry(entry, context) }))
+    .filter(({ score }) => score > 0)
+    .sort((a, b) => b.score - a.score)
+    .map(({ entry, score }) => Object.assign({}, entry, { _score: score }));
+}
+
+module.exports = { scoreEntry, rankEntries };

package/src/lib/scorer.js

@@ -0,0 +1,188 @@
+'use strict';
+
+const { execSync } = require('child_process');
+const fs = require('fs-extra');
+const path = require('path');
+const { LORE_DIR, readIndex } = require('./index');
+const { readEntry } = require('./entries');
+const { checkStaleness } = require('./stale');
+const { readConfig } = require('./config');
+
+const SCORE_PATH = () => path.join(LORE_DIR, 'score.json');
+
+/**
+ * Get directories that have >5 commits in the last 90 days.
+ * @returns {string[]} relative dir paths
+ */
+function getActiveModules() {
+  try {
+    const output = execSync(
+      'git log --since="90 days ago" --name-only --pretty=format:""',
+      { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+    );
+    const dirCounts = {};
+    for (const line of output.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('warning:')) continue;
+      const dir = path.dirname(trimmed);
+      if (dir === '.') continue;
+      dirCounts[dir] = (dirCounts[dir] || 0) + 1;
+    }
+    return Object.entries(dirCounts)
+      .filter(([, count]) => count > 5)
+      .map(([dir]) => dir);
+  } catch (e) {
+    return [];
+  }
+}
+
+/**
+ * Get all directories that have at least one Lore entry linked.
+ */
+function getModulesWithEntries(index) {
+  const dirs = new Set();
+  for (const entryPath of Object.values(index.entries)) {
+    const entry = readEntry(entryPath);
+    if (!entry) continue;
+    for (const file of (entry.files || [])) {
+      const dir = path.dirname(file.replace(/^\.\//, '').replace(/\/$/, ''));
+      if (dir && dir !== '.') dirs.add(dir);
+    }
+  }
+  return dirs;
+}
+
+function calcCoverage(activeModules, modulesWithEntries) {
+  if (activeModules.length === 0) return 100;
+  const covered = activeModules.filter(m => modulesWithEntries.has(m)).length;
+  return Math.round((covered / activeModules.length) * 100);
+}
+
+function calcFreshness(index) {
+  let deduction = 0;
+  const now = new Date();
+  for (const entryPath of Object.values(index.entries)) {
+    const entry = readEntry(entryPath);
+    if (!entry) continue;
+
+    // File-based staleness
+    const staleFiles = checkStaleness(entry);
+    for (const { daysAgo } of staleFiles) {
+      deduction += Math.min(40, daysAgo / 2);
+    }
+
+    // Age-based staleness for entries with no linked files (older than 60 days)
+    if ((!entry.files || entry.files.length === 0) && entry.date) {
+      const ageDays = (now - new Date(entry.date)) / (1000 * 60 * 60 * 24);
+      if (ageDays > 60) {
+        deduction += Math.min(10, (ageDays - 60) / 6);
+      }
+    }
+  }
+  return Math.max(0, Math.round(100 - deduction));
+}
+
+function calcDepth(index) {
+  const counts = { decision: 0, invariant: 0, graveyard: 0, gotcha: 0 };
+  for (const entryPath of Object.values(index.entries)) {
+    const entry = readEntry(entryPath);
+    if (!entry) continue;
+    if (counts[entry.type] !== undefined) counts[entry.type]++;
+  }
+  // invariants and gotchas worth 1.5x
+  const weighted =
+    counts.decision + counts.graveyard + (counts.invariant * 1.5) + (counts.gotcha * 1.5);
+  const maxReasonable = 20;
+  return Math.min(100, Math.round((weighted / maxReasonable) * 100));
+}
+
+/**
+ * Compute the full Lore Score result.
+ * @returns {object}
+ */
+function computeScore() {
+  const index = readIndex();
+  const config = readConfig();
+  const weights = config.scoringWeights || { coverage: 0.4, freshness: 0.35, depth: 0.25 };
+
+  const activeModules = getActiveModules();
+  const modulesWithEntries = getModulesWithEntries(index);
+
+  // Commit count per dir for ranking unlogged modules
+  const commitCounts = {};
+  try {
+    const output = execSync(
+      'git log --since="90 days ago" --name-only --pretty=format:""',
+      { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+    );
+    for (const line of output.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('warning:')) continue;
+      const dir = path.dirname(trimmed);
+      if (dir !== '.') commitCounts[dir] = (commitCounts[dir] || 0) + 1;
+    }
+  } catch (e) {}
+
+  const topUnlogged = activeModules
+    .filter(m => !modulesWithEntries.has(m))
+    .sort((a, b) => (commitCounts[b] || 0) - (commitCounts[a] || 0))
+    .slice(0, 3)
+    .map(m => ({ module: m, commits: commitCounts[m] || 0 }));
+
+  const coverage = calcCoverage(activeModules, modulesWithEntries);
+  const freshness = calcFreshness(index);
+  const depth = calcDepth(index);
+  const score = Math.round(
+    coverage * weights.coverage +
+    freshness * weights.freshness +
+    depth * weights.depth
+  );
+
+  return {
+    score,
+    coverage,
+    freshness,
+    depth,
+    activeModules: activeModules.length,
+    coveredModules: activeModules.filter(m => modulesWithEntries.has(m)).length,
+    topUnlogged,
+  };
+}
+
+/**
+ * Append today's score to history, save to .lore/score.json.
+ * @param {object} result
+ * @returns {object[]} full history
+ */
+function saveScore(result) {
+  const scorePath = SCORE_PATH();
+  let data = { history: [] };
+  if (fs.existsSync(scorePath)) {
+    try { data = fs.readJsonSync(scorePath); } catch (e) {}
+  }
+  const today = new Date().toISOString().split('T')[0];
+  data.history = (data.history || []).filter(h => h.date !== today);
+  data.history.push({
+    date: today,
+    score: result.score,
+    coverage: result.coverage,
+    freshness: result.freshness,
+    depth: result.depth,
+  });
+  data.history = data.history.slice(-90);
+  fs.ensureDirSync(LORE_DIR);
+  fs.writeJsonSync(scorePath, data, { spaces: 2 });
+  return data.history;
+}
+
+/**
+ * Load score history.
+ * @returns {object[]}
+ */
+function loadHistory() {
+  const scorePath = SCORE_PATH();
+  if (!fs.existsSync(scorePath)) return [];
+  try { return fs.readJsonSync(scorePath).history || []; } catch (e) { return []; }
+}
+
+module.exports = { computeScore, saveScore, loadHistory, getActiveModules };

package/src/lib/sessions.js

@@ -0,0 +1,51 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+const { LORE_DIR } = require('./index');
+
+function getSessionPath() {
+  return path.join(LORE_DIR, 'sessions', 'last.json');
+}
+
+function updateLastSession() {
+  const sessionPath = getSessionPath();
+  fs.ensureDirSync(path.dirname(sessionPath));
+  const data = { lastActive: new Date().toISOString() };
+  fs.writeJsonSync(sessionPath, data, { spaces: 2 });
+}
+
+function getDaysSinceLastSession() {
+  const sessionPath = getSessionPath();
+  if (!fs.existsSync(sessionPath)) return null;
+  try {
+    const data = fs.readJsonSync(sessionPath);
+    if (!data.lastActive) return null;
+    const last = new Date(data.lastActive);
+    const now = new Date();
+    const diffMs = now - last;
+    return Math.floor(diffMs / (1000 * 60 * 60 * 24));
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Watch for conversation activity in .lore/sessions/.
+ * Calls onNewSession callback when a new Claude Code session is detected.
+ * This is a simple file-watch-based implementation.
+ */
+function watchConversations(onNewSession) {
+  const sessionsDir = path.join(LORE_DIR, 'sessions');
+  fs.ensureDirSync(sessionsDir);
+
+  const watcher = fs.watch(sessionsDir, { persistent: false }, (event, filename) => {
+    if (filename && filename.endsWith('.json')) {
+      onNewSession(filename);
+    }
+  });
+
+  return watcher;
+}
+
+module.exports = { updateLastSession, getDaysSinceLastSession, watchConversations };

package/src/lib/stale.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const fs = require('fs-extra');
+
+function checkStaleness(entry) {
+  const results = [];
+  const entryDate = new Date(entry.date);
+
+  for (const filepath of entry.files) {
+    try {
+      if (!fs.existsSync(filepath)) continue;
+      const stat = fs.statSync(filepath);
+      const mtime = stat.mtime;
+
+      if (mtime > entryDate) {
+        const daysAgo = Math.floor((Date.now() - mtime.getTime()) / (1000 * 60 * 60 * 24));
+        results.push({ isStale: true, filepath, mtime, daysAgo });
+      }
+    } catch (e) {
+      // Skip files that can't be stat'd
+    }
+  }
+
+  return results;
+}
+
+module.exports = { checkStaleness };

package/src/mcp/server.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const { Server } = require('@modelcontextprotocol/sdk/server');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+} = require('@modelcontextprotocol/sdk/types.js');
+
+const why = require('./tools/why');
+const search = require('./tools/search');
+const log = require('./tools/log');
+const stale = require('./tools/stale');
+const overview = require('./tools/overview');
+const drafts = require('./tools/drafts');
+
+const TOOLS = [why, search, log, stale, overview, drafts];
+
+async function startServer() {
+  const server = new Server(
+    { name: 'lore', version: '0.3.0' },
+    { capabilities: { tools: {} } }
+  );
+
+  // List tools handler
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS.map(t => t.toolDefinition),
+  }));
+
+  // Call tool handler
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const tool = TOOLS.find(t => t.toolDefinition.name === name);
+
+    if (!tool) {
+      return {
+        content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+        isError: true,
+      };
+    }
+
+    return tool.handler(args || {});
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  // Keep process alive
+  process.stdin.resume();
+}
+
+module.exports = { startServer };

package/src/mcp/tools/drafts.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const { listDrafts, getDraftCount } = require('../../lib/drafts');
+
+const toolDefinition = {
+  name: 'lore_drafts',
+  description: 'Returns the count and summary of pending Lore drafts — automatically captured signals (file deletions, comment mining, commit messages, repeated edits) that have not yet been reviewed. Use this to surface the draft queue to the developer.',
+  inputSchema: {
+    type: 'object',
+    properties: {},
+    required: [],
+  },
+};
+
+async function handler() {
+  try {
+    const count = getDraftCount();
+
+    if (count === 0) {
+      return {
+        content: [{ type: 'text', text: 'No pending Lore drafts. Your knowledge base is up to date.' }],
+      };
+    }
+
+    const drafts = listDrafts();
+    const lines = [
+      `You have ${count} unreviewed Lore draft${count === 1 ? '' : 's'} — run \`lore drafts\` to review.\n`,
+    ];
+
+    for (const draft of drafts.slice(0, 10)) {
+      const confidence = Math.round((draft.confidence || 0) * 100);
+      const files = (draft.files || []).slice(0, 2).join(', ');
+      lines.push(`• [${(draft.suggestedType || 'decision').toUpperCase()}] ${draft.suggestedTitle || draft.draftId}`);
+      if (files) lines.push(`  Files: ${files}`);
+      lines.push(`  Confidence: ${confidence}%  |  Evidence: ${(draft.evidence || '').slice(0, 80)}`);
+      lines.push('');
+    }
+
+    if (drafts.length > 10) {
+      lines.push(`  … and ${drafts.length - 10} more. Run \`lore drafts\` to see all.`);
+    }
+
+    return {
+      content: [{ type: 'text', text: lines.join('\n') }],
+    };
+  } catch (e) {
+    return {
+      content: [{ type: 'text', text: `Error: ${e.message}` }],
+      isError: true,
+    };
+  }
+}
+
+module.exports = { toolDefinition, handler };

package/src/mcp/tools/log.js

@@ -0,0 +1,93 @@
+'use strict';
+
+const { readIndex, writeIndex, addEntryToIndex } = require('../../lib/index');
+const { generateId, writeEntry } = require('../../lib/entries');
+
+const toolDefinition = {
+  name: 'lore_log',
+  description: 'Create a new Lore entry to record an architectural decision, invariant, gotcha, or graveyard item. Use this when you make a significant technical decision that future developers (or AI) should know about.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      type: {
+        type: 'string',
+        enum: ['decision', 'invariant', 'gotcha', 'graveyard'],
+        description: 'Type of entry to create',
+      },
+      title: {
+        type: 'string',
+        description: 'Short, descriptive title for the decision or note',
+      },
+      context: {
+        type: 'string',
+        description: 'Full explanation: what was decided, why, what problem it solves',
+      },
+      files: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Files or directories this entry relates to (relative paths)',
+      },
+      tags: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Optional tags for categorization',
+      },
+      alternatives: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Alternative approaches that were considered',
+      },
+      tradeoffs: {
+        type: 'string',
+        description: 'Known tradeoffs or downsides of this decision',
+      },
+    },
+    required: ['type', 'title', 'context'],
+  },
+};
+
+async function handler(args) {
+  const { type, title, context, files = [], tags = [], alternatives = [], tradeoffs = '' } = args;
+
+  try {
+    const id = generateId(type, title);
+    const entry = {
+      id,
+      type,
+      title,
+      context,
+      files,
+      tags,
+      alternatives,
+      tradeoffs,
+      date: new Date().toISOString(),
+    };
+
+    writeEntry(entry);
+
+    const index = readIndex();
+    addEntryToIndex(index, entry);
+    writeIndex(index);
+
+    // Auto-embed if possible
+    try {
+      const { generateEmbedding, storeEmbedding } = require('../../lib/embeddings');
+      const text = [title, context, ...alternatives, tradeoffs, ...tags].join(' ');
+      const vector = await generateEmbedding(text);
+      storeEmbedding(id, vector);
+    } catch (e) {
+      // Ollama not available — skip embedding silently
+    }
+
+    return {
+      content: [{ type: 'text', text: `Created ${type}: ${title} (${id})` }],
+    };
+  } catch (e) {
+    return {
+      content: [{ type: 'text', text: `Error creating entry: ${e.message}` }],
+      isError: true,
+    };
+  }
+}
+
+module.exports = { toolDefinition, handler };

package/src/mcp/tools/overview.js

@@ -0,0 +1,141 @@
+'use strict';
+
+const { readIndex } = require('../../lib/index');
+const { readEntry } = require('../../lib/entries');
+const { checkStaleness } = require('../../lib/stale');
+const { readConfig } = require('../../lib/config');
+const { getDaysSinceLastSession, updateLastSession } = require('../../lib/sessions');
+const { getDraftCount } = require('../../lib/drafts');
+const { loadHistory } = require('../../lib/scorer');
+
+const toolDefinition = {
+  name: 'lore_overview',
+  description: "Get a high-level summary of this project's Lore knowledge base. Returns key decisions, invariants, gotchas, stale entries, Lore Score, and pending drafts. Call this at the start of a session.",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      include_stale: {
+        type: 'boolean',
+        description: 'Include stale entry warnings (default: true)',
+      },
+    },
+    required: [],
+  },
+};
+
+async function handler(args) {
+  const includeStale = args.include_stale !== false;
+
+  try {
+    const config = readConfig();
+    const index = readIndex();
+    const daysSince = getDaysSinceLastSession();
+    updateLastSession();
+
+    const byType = { decision: [], invariant: [], gotcha: [], graveyard: [] };
+    const staleItems = [];
+
+    for (const entryPath of Object.values(index.entries)) {
+      const entry = readEntry(entryPath);
+      if (!entry) continue;
+      if (byType[entry.type]) byType[entry.type].push(entry);
+      if (includeStale) {
+        const staleFiles = checkStaleness(entry);
+        if (staleFiles.length > 0) staleItems.push({ entry, staleFiles });
+      }
+    }
+
+    const lines = [];
+    const projectName = config.project || 'this project';
+
+    if (daysSince !== null && daysSince >= 3) {
+      lines.push(`# Welcome back to ${projectName}`);
+      lines.push(`_(You've been away for ${daysSince} day${daysSince === 1 ? '' : 's'})_`);
+      lines.push('');
+    } else {
+      lines.push(`# Lore Overview — ${projectName}`);
+      lines.push('');
+    }
+
+    // Lore Score one-liner
+    const history = loadHistory();
+    if (history.length > 0) {
+      const latest = history[history.length - 1];
+      lines.push(`**Memory health: ${latest.score}/100**`);
+      lines.push('');
+    }
+
+    // Pending drafts
+    const draftCount = getDraftCount();
+    if (draftCount > 0) {
+      lines.push(`**${draftCount} unreviewed draft${draftCount === 1 ? '' : 's'} — run \`lore drafts\` to review**`);
+      lines.push('');
+    }
+
+    // Decisions
+    if (byType.decision.length > 0) {
+      lines.push(`## Architectural Decisions (${byType.decision.length})`);
+      for (const e of byType.decision.slice(0, 5)) {
+        lines.push(`• **${e.title}**`);
+        if (e.context) {
+          const summary = e.context.split('\n')[0].slice(0, 100);
+          lines.push(`  ${summary}${e.context.length > 100 ? '…' : ''}`);
+        }
+      }
+      if (byType.decision.length > 5) {
+        lines.push(`  _(and ${byType.decision.length - 5} more — use lore_search to explore)_`);
+      }
+      lines.push('');
+    }
+
+    // Invariants
+    if (byType.invariant.length > 0) {
+      lines.push(`## Invariants — Never Break These (${byType.invariant.length})`);
+      for (const e of byType.invariant) {
+        lines.push(`• **${e.title}**`);
+        if (e.context) {
+          lines.push(`  ${e.context.split('\n')[0].slice(0, 100)}`);
+        }
+      }
+      lines.push('');
+    }
+
+    // Gotchas
+    if (byType.gotcha.length > 0) {
+      lines.push(`## Gotchas (${byType.gotcha.length})`);
+      for (const e of byType.gotcha.slice(0, 3)) {
+        lines.push(`• **${e.title}**`);
+      }
+      if (byType.gotcha.length > 3) {
+        lines.push(`  _(and ${byType.gotcha.length - 3} more)_`);
+      }
+      lines.push('');
+    }
+
+    // Stale
+    if (includeStale && staleItems.length > 0) {
+      lines.push(`## ⚠️ Stale Entries (${staleItems.length})`);
+      for (const { entry, staleFiles } of staleItems.slice(0, 5)) {
+        lines.push(`• **${entry.title}** (${entry.id})`);
+        for (const s of staleFiles) {
+          const daysText = s.daysAgo === 0 ? 'today' : `${s.daysAgo}d ago`;
+          lines.push(`  ${s.filepath} changed ${daysText}`);
+        }
+      }
+      lines.push('');
+    }
+
+    const total = Object.values(byType).reduce((sum, arr) => sum + arr.length, 0);
+    lines.push('---');
+    lines.push(`_Total: ${total} entries | Use lore_why <filepath> for file-specific context_`);
+
+    return { content: [{ type: 'text', text: lines.join('\n') }] };
+  } catch (e) {
+    return {
+      content: [{ type: 'text', text: `Error: ${e.message}` }],
+      isError: true,
+    };
+  }
+}
+
+module.exports = { toolDefinition, handler };