engram-mcp-server 1.2.0

package/dist/scripts/install-hooks.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+// ============================================================================
+// Engram — Git Hook Installer
+//
+// Installs a post-commit hook that records git commits in Engram's memory,
+// so the agent always knows what changed between sessions even without
+// explicitly recording changes.
+// ============================================================================
+import * as fs from "fs";
+import * as path from "path";
+const HOOK_CONTENT = `#!/bin/bash
+# ─────────────────────────────────────────────────────────────
+# Engram Post-Commit Hook
+# Records commit info into .engram/git-changes.log
+# The Engram MCP server reads this on session start.
+# ─────────────────────────────────────────────────────────────
+
+ENGRAM_DIR=".engram"
+CHANGE_LOG="$ENGRAM_DIR/git-changes.log"
+
+# Ensure the directory exists
+mkdir -p "$ENGRAM_DIR"
+
+# Get commit info
+HASH=$(git rev-parse --short HEAD)
+MSG=$(git log -1 --pretty=format:"%s")
+AUTHOR=$(git log -1 --pretty=format:"%an")
+DATE=$(git log -1 --pretty=format:"%aI")
+FILES=$(git diff-tree --no-commit-id --name-status -r HEAD)
+
+# Append to change log
+{
+  echo "--- COMMIT $HASH ---"
+  echo "date: $DATE"
+  echo "author: $AUTHOR"
+  echo "message: $MSG"
+  echo "files:"
+  echo "$FILES"
+  echo "---"
+  echo ""
+} >> "$CHANGE_LOG"
+
+# Keep only last 200 entries to prevent unbounded growth
+if [ -f "$CHANGE_LOG" ]; then
+  LINES=$(wc -l < "$CHANGE_LOG")
+  if [ "$LINES" -gt 2000 ]; then
+    tail -1000 "$CHANGE_LOG" > "$CHANGE_LOG.tmp"
+    mv "$CHANGE_LOG.tmp" "$CHANGE_LOG"
+  fi
+fi
+`;
+function installHooks() {
+    // Find .git directory
+    let dir = process.cwd();
+    while (dir !== path.dirname(dir)) {
+        if (fs.existsSync(path.join(dir, ".git"))) {
+            break;
+        }
+        dir = path.dirname(dir);
+    }
+    const gitDir = path.join(dir, ".git");
+    if (!fs.existsSync(gitDir)) {
+        console.error("Error: Not a git repository. Navigate to a project with .git and try again.");
+        process.exit(1);
+    }
+    const hooksDir = path.join(gitDir, "hooks");
+    fs.mkdirSync(hooksDir, { recursive: true });
+    const hookPath = path.join(hooksDir, "post-commit");
+    // Check for existing hook
+    if (fs.existsSync(hookPath)) {
+        const existing = fs.readFileSync(hookPath, "utf-8");
+        if (existing.includes("Engram Post-Commit Hook")) {
+            console.log("Engram post-commit hook is already installed.");
+            return;
+        }
+        // Append to existing hook
+        fs.appendFileSync(hookPath, "\n\n" + HOOK_CONTENT);
+        console.log("Engram post-commit hook appended to existing hook.");
+    }
+    else {
+        fs.writeFileSync(hookPath, HOOK_CONTENT);
+        console.log("Engram post-commit hook installed.");
+    }
+    // Make executable
+    fs.chmodSync(hookPath, "755");
+    console.log(`Hook location: ${hookPath}`);
+}
+installHooks();
+//# sourceMappingURL=install-hooks.js.map

package/dist/tools/intelligence.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerIntelligenceTools(server: McpServer): void;
+//# sourceMappingURL=intelligence.d.ts.map

package/dist/tools/intelligence.js

@@ -0,0 +1,427 @@
+// ============================================================================
+// Engram MCP Server — Project Intelligence Tools
+// ============================================================================
+import { z } from "zod";
+import { getDb, now, getProjectRoot } from "../database.js";
+import { TOOL_PREFIX, SNAPSHOT_TTL_MINUTES, MAX_SEARCH_RESULTS } from "../constants.js";
+import { scanFileTree, detectLayer, isGitRepo, getGitBranch, getGitHead, getGitLogSince, getGitFilesChanged, minutesSince, safeJsonParse } from "../utils.js";
+// ─── FTS5 Helpers ────────────────────────────────────────────────────
+/**
+ * Check if FTS5 tables exist (migration v2 applied).
+ */
+function hasFts(db) {
+    try {
+        const row = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='fts_sessions'").get();
+        return !!row;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Escape a user query for FTS5 MATCH syntax.
+ * Wraps each word in quotes to avoid syntax errors from special chars.
+ */
+function ftsEscape(query) {
+    return query
+        .split(/\s+/)
+        .filter(Boolean)
+        .map(word => `"${word.replace(/"/g, '""')}"`)
+        .join(" ");
+}
+export function registerIntelligenceTools(server) {
+    // ─── SCAN PROJECT ───────────────────────────────────────────────────
+    server.registerTool(`${TOOL_PREFIX}_scan_project`, {
+        title: "Scan Project",
+        description: `Scan the project filesystem and build a cached snapshot of the structure. Includes file tree, auto-detected architectural layers, existing file notes, active decisions, and conventions. The snapshot is cached and reused — no need to rescan unless files changed significantly.
+
+Args:
+  - force_refresh (boolean, optional): Force rescan even if cache is fresh (default: false)
+  - max_depth (number, optional): Max directory depth to scan (default: 5)
+
+Returns:
+  ProjectSnapshot with file tree, layer distribution, and all stored intelligence.`,
+        inputSchema: {
+            force_refresh: z.boolean().default(false).describe("Force rescan even if cache is fresh"),
+            max_depth: z.number().int().min(1).max(10).default(5).describe("Max directory depth"),
+        },
+        annotations: {
+            readOnlyHint: false, // It writes to cache
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ force_refresh, max_depth }) => {
+        const db = getDb();
+        const projectRoot = getProjectRoot();
+        // Check cache freshness
+        if (!force_refresh) {
+            const cached = db.prepare("SELECT * FROM snapshot_cache WHERE key = 'project_structure'").get();
+            if (cached) {
+                const age = minutesSince(cached.updated_at);
+                if (age < SNAPSHOT_TTL_MINUTES) {
+                    const snapshot = safeJsonParse(cached.value, null);
+                    if (snapshot) {
+                        return {
+                            content: [{
+                                    type: "text",
+                                    text: JSON.stringify({
+                                        ...snapshot,
+                                        _cache_status: `fresh (${age}min old, TTL: ${SNAPSHOT_TTL_MINUTES}min)`,
+                                    }, null, 2),
+                                }],
+                        };
+                    }
+                }
+            }
+        }
+        // Perform full scan
+        const fileTree = scanFileTree(projectRoot, max_depth);
+        // Auto-detect layers for each file
+        const layerDist = {};
+        for (const f of fileTree) {
+            if (f.endsWith("/"))
+                continue; // Skip directories
+            const layer = detectLayer(f);
+            layerDist[layer] = (layerDist[layer] || 0) + 1;
+        }
+        // Fetch stored intelligence
+        const fileNotes = db.prepare("SELECT * FROM file_notes ORDER BY file_path").all();
+        const activeDecisions = db.prepare("SELECT * FROM decisions WHERE status = 'active' ORDER BY timestamp DESC LIMIT 20").all();
+        const activeConventions = db.prepare("SELECT * FROM conventions WHERE enforced = 1 ORDER BY category").all();
+        // Git info
+        let gitInfo = null;
+        if (isGitRepo(projectRoot)) {
+            const branch = getGitBranch(projectRoot);
+            const head = getGitHead(projectRoot);
+            gitInfo = { branch, head, is_clean: true }; // Simplified
+        }
+        const snapshot = {
+            project_root: projectRoot,
+            file_tree: fileTree,
+            total_files: fileTree.filter(f => !f.endsWith("/")).length,
+            file_notes: fileNotes,
+            recent_decisions: activeDecisions,
+            active_conventions: activeConventions,
+            layer_distribution: layerDist,
+            generated_at: now(),
+            git: gitInfo,
+        };
+        // Cache the snapshot
+        db.prepare("INSERT OR REPLACE INTO snapshot_cache (key, value, updated_at, ttl_minutes) VALUES ('project_structure', ?, ?, ?)").run(JSON.stringify(snapshot), now(), SNAPSHOT_TTL_MINUTES);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        ...snapshot,
+                        _cache_status: "freshly scanned",
+                    }, null, 2),
+                }],
+        };
+    });
+    // ─── SEARCH MEMORY (FTS5-powered) ──────────────────────────────────
+    server.registerTool(`${TOOL_PREFIX}_search`, {
+        title: "Search Memory",
+        description: `Full-text search across ALL memory: sessions, changes, decisions, file notes, conventions, and tasks. Uses FTS5 for high-performance ranked results when available, falls back to LIKE for compatibility.
+
+Args:
+  - query (string): Search term(s)
+  - scope (string, optional): Limit search to a specific table — "sessions", "changes", "decisions", "file_notes", "conventions", "tasks", or "all" (default: "all")
+  - limit (number, optional): Max total results (default: 20)
+
+Returns:
+  Grouped search results with relevance context.`,
+        inputSchema: {
+            query: z.string().min(1).describe("Search term(s)"),
+            scope: z.enum(["all", "sessions", "changes", "decisions", "file_notes", "conventions", "tasks"]).default("all"),
+            limit: z.number().int().min(1).max(MAX_SEARCH_RESULTS).default(20),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ query, scope, limit }) => {
+        const db = getDb();
+        const useFts = hasFts(db);
+        const results = {};
+        let totalFound = 0;
+        const perTable = Math.ceil(limit / 6);
+        if (useFts) {
+            // ─── FTS5 Path (fast, ranked) ────────────────────────────
+            const ftsQuery = ftsEscape(query);
+            if (scope === "all" || scope === "sessions") {
+                try {
+                    const rows = db.prepare(`SELECT s.*, rank FROM fts_sessions f
+               JOIN sessions s ON s.id = f.rowid
+               WHERE fts_sessions MATCH ?
+               ORDER BY rank LIMIT ?`).all(ftsQuery, perTable);
+                    if (rows.length) {
+                        results.sessions = rows;
+                        totalFound += rows.length;
+                    }
+                }
+                catch { /* FTS match failed, skip */ }
+            }
+            if (scope === "all" || scope === "changes") {
+                try {
+                    const rows = db.prepare(`SELECT c.*, rank FROM fts_changes f
+               JOIN changes c ON c.id = f.rowid
+               WHERE fts_changes MATCH ?
+               ORDER BY rank LIMIT ?`).all(ftsQuery, perTable);
+                    if (rows.length) {
+                        results.changes = rows;
+                        totalFound += rows.length;
+                    }
+                }
+                catch { /* FTS match failed, skip */ }
+            }
+            if (scope === "all" || scope === "decisions") {
+                try {
+                    const rows = db.prepare(`SELECT d.*, rank FROM fts_decisions f
+               JOIN decisions d ON d.id = f.rowid
+               WHERE fts_decisions MATCH ?
+               ORDER BY rank LIMIT ?`).all(ftsQuery, perTable);
+                    if (rows.length) {
+                        results.decisions = rows;
+                        totalFound += rows.length;
+                    }
+                }
+                catch { /* FTS match failed, skip */ }
+            }
+            if (scope === "all" || scope === "file_notes") {
+                try {
+                    const rows = db.prepare(`SELECT * FROM file_notes WHERE file_path IN (
+                 SELECT file_path FROM fts_file_notes WHERE fts_file_notes MATCH ?
+               ) LIMIT ?`).all(ftsQuery, perTable);
+                    if (rows.length) {
+                        results.file_notes = rows;
+                        totalFound += rows.length;
+                    }
+                }
+                catch { /* FTS match failed, skip */ }
+            }
+            if (scope === "all" || scope === "conventions") {
+                try {
+                    const rows = db.prepare(`SELECT c.*, rank FROM fts_conventions f
+               JOIN conventions c ON c.id = f.rowid
+               WHERE fts_conventions MATCH ?
+               ORDER BY rank LIMIT ?`).all(ftsQuery, perTable);
+                    if (rows.length) {
+                        results.conventions = rows;
+                        totalFound += rows.length;
+                    }
+                }
+                catch { /* FTS match failed, skip */ }
+            }
+            if (scope === "all" || scope === "tasks") {
+                try {
+                    const rows = db.prepare(`SELECT t.*, rank FROM fts_tasks f
+               JOIN tasks t ON t.id = f.rowid
+               WHERE fts_tasks MATCH ?
+               ORDER BY rank LIMIT ?`).all(ftsQuery, perTable);
+                    if (rows.length) {
+                        results.tasks = rows;
+                        totalFound += rows.length;
+                    }
+                }
+                catch { /* FTS match failed, skip */ }
+            }
+        }
+        else {
+            // ─── LIKE Fallback (slow but compatible) ─────────────────
+            const term = `%${query}%`;
+            if (scope === "all" || scope === "sessions") {
+                const rows = db.prepare("SELECT * FROM sessions WHERE summary LIKE ? OR tags LIKE ? ORDER BY id DESC LIMIT ?").all(term, term, perTable);
+                if (rows.length) {
+                    results.sessions = rows;
+                    totalFound += rows.length;
+                }
+            }
+            if (scope === "all" || scope === "changes") {
+                const rows = db.prepare("SELECT * FROM changes WHERE description LIKE ? OR file_path LIKE ? OR diff_summary LIKE ? ORDER BY timestamp DESC LIMIT ?").all(term, term, term, perTable);
+                if (rows.length) {
+                    results.changes = rows;
+                    totalFound += rows.length;
+                }
+            }
+            if (scope === "all" || scope === "decisions") {
+                const rows = db.prepare("SELECT * FROM decisions WHERE decision LIKE ? OR rationale LIKE ? OR tags LIKE ? ORDER BY timestamp DESC LIMIT ?").all(term, term, term, perTable);
+                if (rows.length) {
+                    results.decisions = rows;
+                    totalFound += rows.length;
+                }
+            }
+            if (scope === "all" || scope === "file_notes") {
+                const rows = db.prepare("SELECT * FROM file_notes WHERE file_path LIKE ? OR purpose LIKE ? OR notes LIKE ? LIMIT ?").all(term, term, term, perTable);
+                if (rows.length) {
+                    results.file_notes = rows;
+                    totalFound += rows.length;
+                }
+            }
+            if (scope === "all" || scope === "conventions") {
+                const rows = db.prepare("SELECT * FROM conventions WHERE rule LIKE ? OR examples LIKE ? LIMIT ?").all(term, term, perTable);
+                if (rows.length) {
+                    results.conventions = rows;
+                    totalFound += rows.length;
+                }
+            }
+            if (scope === "all" || scope === "tasks") {
+                const rows = db.prepare("SELECT * FROM tasks WHERE title LIKE ? OR description LIKE ? OR tags LIKE ? ORDER BY updated_at DESC LIMIT ?").all(term, term, term, perTable);
+                if (rows.length) {
+                    results.tasks = rows;
+                    totalFound += rows.length;
+                }
+            }
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        query,
+                        scope,
+                        search_engine: useFts ? "fts5" : "like",
+                        total_results: totalFound,
+                        results,
+                    }, null, 2),
+                }],
+        };
+    });
+    // ─── WHAT CHANGED ───────────────────────────────────────────────────
+    server.registerTool(`${TOOL_PREFIX}_what_changed`, {
+        title: "What Changed",
+        description: `Comprehensive diff report: what changed since a given time. Combines agent-recorded changes with git history. Use to quickly catch up after being away.
+
+Args:
+  - since (string, optional): ISO timestamp or relative like "1h", "24h", "7d" (default: last session end)
+  - include_git (boolean, optional): Include git log (default: true)
+
+Returns:
+  Combined change report from both agent memory and git.`,
+        inputSchema: {
+            since: z.string().optional().describe('ISO timestamp or relative: "1h", "24h", "7d"'),
+            include_git: z.boolean().default(true),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ since, include_git }) => {
+        const db = getDb();
+        const projectRoot = getProjectRoot();
+        // Resolve "since" to an ISO timestamp
+        let sinceTimestamp;
+        if (!since) {
+            // Default to last session end
+            const last = db.prepare("SELECT ended_at FROM sessions WHERE ended_at IS NOT NULL ORDER BY id DESC LIMIT 1").get();
+            sinceTimestamp = last?.ended_at || new Date(Date.now() - 86400000).toISOString();
+        }
+        else if (/^\d+[hdm]$/.test(since)) {
+            // Relative time
+            const match = since.match(/^(\d+)([hdm])$/);
+            if (match) {
+                const amount = parseInt(match[1]);
+                const unit = match[2];
+                const ms = unit === "h" ? amount * 3600000 : unit === "d" ? amount * 86400000 : amount * 60000;
+                sinceTimestamp = new Date(Date.now() - ms).toISOString();
+            }
+            else {
+                sinceTimestamp = since;
+            }
+        }
+        else {
+            sinceTimestamp = since;
+        }
+        // Agent-recorded changes
+        const agentChanges = db.prepare("SELECT * FROM changes WHERE timestamp > ? ORDER BY timestamp DESC").all(sinceTimestamp);
+        // Decisions made since
+        const newDecisions = db.prepare("SELECT * FROM decisions WHERE timestamp > ? ORDER BY timestamp DESC").all(sinceTimestamp);
+        // Git changes
+        let gitLog = "";
+        let gitFilesChanged = [];
+        if (include_git && isGitRepo(projectRoot)) {
+            gitLog = getGitLogSince(projectRoot, sinceTimestamp);
+            gitFilesChanged = getGitFilesChanged(projectRoot, sinceTimestamp);
+        }
+        // Files only in git (not recorded by agent)
+        const recordedFiles = new Set(agentChanges.map(c => c.file_path));
+        const unrecordedGitChanges = gitFilesChanged.filter(f => !recordedFiles.has(f));
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        since: sinceTimestamp,
+                        agent_recorded: {
+                            count: agentChanges.length,
+                            changes: agentChanges,
+                        },
+                        new_decisions: newDecisions,
+                        git: include_git ? {
+                            log: gitLog,
+                            files_changed: gitFilesChanged.length,
+                            unrecorded_changes: unrecordedGitChanges,
+                        } : null,
+                        summary: `${agentChanges.length} recorded changes, ${newDecisions.length} new decisions, ${gitFilesChanged.length} git file changes (${unrecordedGitChanges.length} unrecorded) since ${sinceTimestamp}.`,
+                    }, null, 2),
+                }],
+        };
+    });
+    // ─── GET DEPENDENCY MAP ─────────────────────────────────────────────
+    server.registerTool(`${TOOL_PREFIX}_get_dependency_map`, {
+        title: "Get Dependency Map",
+        description: `Get the dependency graph for a file: what it depends on and what depends on it. Built from stored file notes.
+
+Args:
+  - file_path (string): File to query
+  - depth (number, optional): How many levels deep to traverse (default: 1)
+
+Returns:
+  Dependency tree with upstream and downstream files.`,
+        inputSchema: {
+            file_path: z.string().describe("File to query"),
+            depth: z.number().int().min(1).max(5).default(1).describe("Traversal depth"),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ file_path, depth }) => {
+        const db = getDb();
+        function getDeps(fp, dir, currentDepth) {
+            if (currentDepth > depth)
+                return {};
+            const note = db.prepare("SELECT * FROM file_notes WHERE file_path = ?").get(fp);
+            if (!note)
+                return {};
+            const field = dir === "up" ? "dependencies" : "dependents";
+            const deps = safeJsonParse(note[field], []);
+            const result = {};
+            for (const dep of deps) {
+                result[dep] = getDeps(dep, dir, currentDepth + 1);
+            }
+            return result;
+        }
+        const upstream = getDeps(file_path, "up", 1);
+        const downstream = getDeps(file_path, "down", 1);
+        const note = db.prepare("SELECT * FROM file_notes WHERE file_path = ?").get(file_path);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        file_path,
+                        purpose: note?.purpose || "(no notes recorded)",
+                        layer: note?.layer || detectLayer(file_path),
+                        complexity: note?.complexity || "unknown",
+                        depends_on: upstream,
+                        depended_by: downstream,
+                    }, null, 2),
+                }],
+        };
+    });
+}
+//# sourceMappingURL=intelligence.js.map

package/dist/tools/maintenance.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerMaintenanceTools(server: McpServer): void;
+//# sourceMappingURL=maintenance.d.ts.map