local-agent-memory 1.0.9 → 1.0.11

package/README.md

@@ -31,6 +31,21 @@ Inicializa el entorno de memoria en el repositorio actual. Esto crea las bases d
 memory init --rules all --docs ./docs
 ```
 
+#### Actualización de Reglas en Proyectos Existentes
+Si ya tienes proyectos donde se inicializó la memoria y deseas migrar o incorporar el protocolo actualizado para tus agentes de IA sin perder tus reglas de `core.md` ni alterar el `project_id`:
+
+```bash
+# Para actualizar las reglas de Antigravity (IDE y CLI)
+memory init --rules=antigravity
+
+# O si utilizas múltiples herramientas (Cursor, Claude, Antigravity, etc.)
+memory init --rules=all
+```
+
+**¿Por qué es necesario?**
+- **Garantiza la adherencia del agente:** Inyecta en los archivos de instrucciones (`.agents/rules/memory.md`, `GEMINI.md`, `AGENTS.md`, `.cursorrules`, etc.) las directivas imperativas obligatorias (`memory_recall_context` al inicio y `memory_record_decision` al finalizar).
+- **Actualización no destructiva:** Preserva intactos el archivo `core.md`, las decisiones previas (`.memory/decisions/`) y la identidad del proyecto (`project_id`).
+
 ### 2. `sync`
 Sincroniza los archivos Markdown del proyecto en el índice de memoria local. Escanea los documentos y actualiza la base de datos para que los agentes cuenten con el contexto más reciente.
 
@@ -39,12 +54,21 @@ memory sync
 ```
 
 ### 3. `status`
-Comprueba el estado de sincronización del proyecto de memoria actual, mostrando detalles sobre archivos indexados y pendienetes.
+Comprueba el estado de sincronización del proyecto de memoria actual y presenta el nuevo panel de métricas y auditoría de actividad MCP.
 
 ```bash
+# Verificar que la BD se actualizó y ver el nuevo panel de métricas
 memory status
 ```
 
+**¿Por qué es necesario?**
+- **Verificación de la Base de Datos:** Valida que la base de datos local SQLite (`.memory/local.sqlite`) esté operando en modo WAL de alta concurrencia y que todos los documentos Markdown estén indexados.
+- **Panel de Métricas MCP:** Muestra la telemetría en tiempo real sobre la actividad del agente:
+  - Conteo acumulado de lecturas (`memory_recall_context`, `search_memory`, `get_memory_document`).
+  - Conteo acumulado de escrituras (`memory_record_decision`, `update_core_rules`, `end_session`).
+  - Marca temporal de la última actividad del agente.
+  - Registro de las decisiones y resúmenes de sesión más recientes.
+
 ### 4. `list` (o `projects`)
 Muestra de forma interactiva una lista de todos los proyectos registrados globalmente en tu máquina. Permite seleccionar un proyecto y ver detalles como el total de archivos indexados, los registros de decisiones (ADRs) y los resúmenes de sesión (Ledgers) para ese proyecto.
 
@@ -112,6 +136,17 @@ memory-mcp
 
 *(Si configuras MCP manualmente, deberás establecer que tu cliente ejecute `memory-mcp` sin argumentos extra)*
 
+### Herramientas MCP Expuestas al Agente
+
+| Herramienta (y Alias) | Tipo | Descripción |
+| :--- | :--- | :--- |
+| `memory_recall_context`<br>*(alias: `get_project_context`)* | Lectura | **Paso Obligatorio al Iniciar:** Recupera `core.md`, las decisiones más recientes y contexto relevante antes de modificar código. |
+| `memory_record_decision`<br>*(alias: `log_decision`)* | Escritura | **Paso Obligatorio al Finalizar:** Registra una decisión técnica o solución de bug en `.memory/decisions/`. |
+| `search_memory` | Lectura | Búsqueda híbrida (vectorial + FTS5) sin cortes arbitrarios. Soporta `full_content: true` para obtener documentos completos. |
+| `get_memory_document`<br>*(alias: `read_memory_document`)* | Lectura | Recupera el texto íntegro e intacto de cualquier documento en `.memory/`. |
+| `update_core_rules` | Escritura | Agrega permanentemente reglas o directivas a `core.md`. |
+| `end_session` | Escritura | Registra el resumen de cierre de sesión en `.memory/ledger/`. |
+
 ---
 
 ## Licencia

package/dist/cli/commands/hook.js

@@ -28,8 +28,8 @@ async function installGitHook() {
 
 # Add a reminder to the commit message template
 echo "" >> "$1"
-echo "# 🧠 Remember to update the local-agent-memory ledger if you made architectural changes." >> "$1"
-echo "# You can run: memory record-session --summary \\"..."\\"" >> "$1"
+echo '# 🧠 Remember to update the local-agent-memory ledger if you made architectural changes.' >> "$1"
+echo '# You can run: memory record-session --summary "..."' >> "$1"
 `;
         // Write file
         await node_fs_1.default.promises.writeFile(hookPath, hookContent, { mode: 0o755 });
@@ -43,15 +43,21 @@ echo "# You can run: memory record-session --summary \\"..."\\"" >> "$1"
         const postHookPath = node_path_1.default.join(hooksDir, postHookName);
         const postHookContent = `#!/bin/sh
 # local-agent-memory post-commit hook
-# Automatically records a memory session for this commit.
+# Automatically records a memory session for this commit with changed files.
 
 COMMIT_MSG=$(git log -1 --pretty=%B)
+CHANGED_FILES=$(git diff-tree --no-commit-id --name-status -r HEAD)
+
+SUMMARY="Commit: $COMMIT_MSG
+
+Modified files:
+$CHANGED_FILES"
 
 # If memory CLI exists, run it
 if command -v memory >/dev/null 2>&1; then
-  memory record-session --summary "Commit: $COMMIT_MSG" > /dev/null 2>&1 &
+  memory record-session --summary "$SUMMARY" > /dev/null 2>&1 &
 elif npx --no-install memory --version >/dev/null 2>&1; then
-  npx --no-install memory record-session --summary "Commit: $COMMIT_MSG" > /dev/null 2>&1 &
+  npx --no-install memory record-session --summary "$SUMMARY" > /dev/null 2>&1 &
 fi
 `;
         await node_fs_1.default.promises.writeFile(postHookPath, postHookContent, { mode: 0o755 });

package/dist/cli/commands/init.js

@@ -22,18 +22,12 @@ async function initProject(options = {}) {
     const spinner = (0, ora_1.default)("Initializing project...").start();
     try {
         const configFile = node_path_1.default.join(memoryDir, "config.json");
-        if (node_fs_1.default.existsSync(memoryDir) && node_fs_1.default.existsSync(configFile)) {
-            if (!options.force) {
-                spinner.fail("Project already initialized. Use --force to overwrite.");
-                process.exit(1);
-            }
-            else {
-                // If force, we just continue (or we might want to clear it, but prompt says "a menos que se use --force", meaning we can overwrite or just proceed)
-            }
-        }
-        else {
-            await node_fs_1.default.promises.mkdir(memoryDir, { recursive: true });
+        const isAlreadyInitialized = node_fs_1.default.existsSync(memoryDir) && node_fs_1.default.existsSync(configFile);
+        if (isAlreadyInitialized && !options.force && !options.rules) {
+            spinner.fail("Project already initialized. Use --rules <targets> to update agent rules, or --force to overwrite.");
+            process.exit(1);
         }
+        await node_fs_1.default.promises.mkdir(memoryDir, { recursive: true });
         // Subdirectories
         await node_fs_1.default.promises.mkdir(node_path_1.default.join(memoryDir, "decisions"), {
             recursive: true,
@@ -41,22 +35,48 @@ async function initProject(options = {}) {
         await node_fs_1.default.promises.mkdir(node_path_1.default.join(memoryDir, "context"), {
             recursive: true,
         });
-        // UUID
-        const projectId = node_crypto_1.default.randomUUID();
+        let projectId = "";
+        if (isAlreadyInitialized && !options.force) {
+            try {
+                const rawConfig = await node_fs_1.default.promises.readFile(configFile, "utf8");
+                const parsed = JSON.parse(rawConfig);
+                projectId = parsed.project_id || node_crypto_1.default.randomUUID();
+            }
+            catch {
+                projectId = node_crypto_1.default.randomUUID();
+            }
+        }
+        else {
+            projectId = node_crypto_1.default.randomUUID();
+        }
         // Config file
-        const configData = {
+        let configData = {
             project_id: projectId,
             created_at: new Date().toISOString(),
             include_paths: [".memory"],
             log_usage: options.log !== false,
         };
-        if (options.docs) {
+        if (isAlreadyInitialized && !options.force) {
+            try {
+                const rawConfig = await node_fs_1.default.promises.readFile(configFile, "utf8");
+                configData = {
+                    ...JSON.parse(rawConfig),
+                    log_usage: options.log !== false,
+                };
+            }
+            catch { }
+        }
+        if (options.docs && !configData.include_paths?.includes(options.docs)) {
+            configData.include_paths = configData.include_paths || [".memory"];
             configData.include_paths.push(options.docs);
         }
-        await node_fs_1.default.promises.writeFile(node_path_1.default.join(memoryDir, "config.json"), JSON.stringify(configData, null, 2));
-        // Core markdown
-        const coreMd = `# Core Rules\n\nThis file contains the core behavior and rules for this project.\n`;
-        await node_fs_1.default.promises.writeFile(node_path_1.default.join(memoryDir, "core.md"), coreMd);
+        await node_fs_1.default.promises.writeFile(configFile, JSON.stringify(configData, null, 2));
+        // Core markdown: preserve existing core.md if project already initialized
+        const corePath = node_path_1.default.join(memoryDir, "core.md");
+        if (!node_fs_1.default.existsSync(corePath) || options.force) {
+            const coreMd = `# Core Rules\n\nThis file contains the core behavior and rules for this project.\n`;
+            await node_fs_1.default.promises.writeFile(corePath, coreMd);
+        }
         // Initialize local DB
         const localDbPath = (0, project_1.getLocalDbPath)(cwd);
         const localDb = (0, project_1.initLocalDb)(localDbPath);
@@ -80,34 +100,49 @@ async function initProject(options = {}) {
             });
         });
         await (0, registry_1.registerProject)(projectId, cwd);
-        // Inject agent instructions
+        // Inject agent instructions with mandatory protocol
         const memoryInstructions = `
-<!-- local-agent-memory rules -->
-- Consulta la herramienta MCP \`search_memory\` antes de proponer cambios de arquitectura, interfaces o decisiones de diseño.
-- Utiliza \`log_decision\` cada vez que se adopte una convención de código, biblioteca o patrón técnico nuevo.
-- Utiliza la herramienta de sesión para resumir acuerdos antes de dar por terminada una tarea.
+<!-- START LOCAL-AGENT-MEMORY PROTOCOL -->
+# Protocolo Obligatorio de Memoria Local (\`local-agent-memory\`)
+
+Este proyecto cuenta con un sistema de memoria persistente conectado vía MCP. Su uso NO es opcional.
+
+1. **Al iniciar cualquier tarea (Lectura):**
+   - Antes de proponer código, modificar archivos o responder dudas sobre el proyecto, **DEBES** ejecutar la herramienta MCP \`memory_recall_context\` (o \`get_project_context\`) pasando el \`projectPath\` actual.
+2. **Al finalizar cualquier cambio (Escritura):**
+   - Antes de dar por concluida tu respuesta tras haber editado código, resuelto un bug o definido arquitectura, **DEBES** ejecutar la herramienta MCP \`memory_record_decision\` (o \`log_decision\`) documentando el cambio y su justificación técnica.
+3. **Para dudas sobre reglas o patrones existentes:**
+   - Utiliza la herramienta MCP \`search_memory\` para consultar el histórico y las decisiones previas (pasa \`full_content: true\` para obtener documentos enteros en vez de fragmentos).
+4. **Para leer un documento de memoria completo:**
+   - Utiliza la herramienta MCP \`get_memory_document\` (o \`read_memory_document\`) especificando la ruta o nombre del archivo (ej. \`decisions/2026-10-14-xxx.md\` o \`core.md\`).
+<!-- END LOCAL-AGENT-MEMORY PROTOCOL -->
 `;
         spinner.stop();
-        let tools = [];
+        let selectedKeys = [];
         const availableRules = {
-            cursor: ".cursorrules",
-            windsurf: ".windsurfrules",
-            copilot: ".github/copilot-instructions.md",
-            claude: "CLAUDE.md",
-            "antigravity-ide": ".agents/rules/memory.md",
-            "antigravity-cli": ".agents/rules/memory.md",
+            cursor: [".cursorrules", ".cursor/rules/memory-protocol.mdc"],
+            windsurf: [".windsurfrules"],
+            copilot: [".github/copilot-instructions.md"],
+            claude: ["CLAUDE.md"],
+            "antigravity-ide": [".agents/rules/memory.md", "GEMINI.md"],
+            "antigravity-cli": ["AGENTS.md"],
+            antigravity: [".agents/rules/memory.md", "GEMINI.md", "AGENTS.md"],
+            ".cursorrules": [".cursorrules"],
+            ".windsurfrules": [".windsurfrules"],
+            ".github/copilot-instructions.md": [".github/copilot-instructions.md"],
+            "claude.md": ["CLAUDE.md"],
+            ".agents/rules/memory.md": [".agents/rules/memory.md"],
+            "gemini.md": ["GEMINI.md"],
+            "agents.md": ["AGENTS.md"],
         };
         if (options.rules) {
             if (options.rules.toLowerCase() === "all") {
-                tools = Array.from(new Set(Object.values(availableRules)));
+                selectedKeys = Object.keys(availableRules);
             }
             else {
-                const rulesList = options.rules
+                selectedKeys = options.rules
                     .split(",")
                     .map((r) => r.trim().toLowerCase());
-                tools = Array.from(new Set(rulesList
-                    .map((r) => availableRules[r])
-                    .filter((r) => Boolean(r))));
             }
         }
         else {
@@ -117,32 +152,62 @@ async function initProject(options = {}) {
                     name: "tools",
                     message: "Select the IDEs/CLIs to generate or inject memory rules into:",
                     choices: [
-                        { name: "Cursor (.cursorrules)", value: ".cursorrules" },
-                        { name: "Windsurf (.windsurfrules)", value: ".windsurfrules" },
+                        {
+                            name: "Cursor (.cursorrules, .cursor/rules/memory-protocol.mdc)",
+                            value: "cursor",
+                        },
+                        { name: "Windsurf (.windsurfrules)", value: "windsurf" },
                         {
                             name: "GitHub Copilot (.github/copilot-instructions.md)",
-                            value: ".github/copilot-instructions.md",
+                            value: "copilot",
+                        },
+                        { name: "Claude Code (CLAUDE.md)", value: "claude" },
+                        {
+                            name: "Antigravity IDE (.agents/rules/memory.md, GEMINI.md)",
+                            value: "antigravity-ide",
                         },
-                        { name: "Claude Code (CLAUDE.md)", value: "CLAUDE.md" },
                         {
-                            name: "Antigravity IDE / CLI (.agents/rules/memory.md)",
-                            value: ".agents/rules/memory.md",
+                            name: "Antigravity CLI (AGENTS.md)",
+                            value: "antigravity-cli",
                         },
                     ],
                 },
             ]);
-            tools = answers.tools;
+            selectedKeys = answers.tools;
         }
         spinner.start("Finishing initialization...");
-        for (const file of tools) {
+        const filesToInject = new Set();
+        for (const key of selectedKeys) {
+            const paths = availableRules[key.toLowerCase()];
+            if (paths) {
+                for (const p of paths)
+                    filesToInject.add(p);
+            }
+            else if (key.endsWith(".md") ||
+                key.endsWith(".mdc") ||
+                key.startsWith(".")) {
+                filesToInject.add(key);
+            }
+        }
+        for (const file of Array.from(filesToInject)) {
             const filePath = node_path_1.default.join(cwd, file);
             const dir = node_path_1.default.dirname(filePath);
             if (!node_fs_1.default.existsSync(dir)) {
                 await node_fs_1.default.promises.mkdir(dir, { recursive: true });
             }
             if (node_fs_1.default.existsSync(filePath)) {
-                const content = await node_fs_1.default.promises.readFile(filePath, "utf8");
-                if (!content.includes("<!-- local-agent-memory rules -->")) {
+                let content = await node_fs_1.default.promises.readFile(filePath, "utf8");
+                const protocolRegex = /<!-- START LOCAL-AGENT-MEMORY PROTOCOL -->[\s\S]*?<!-- END LOCAL-AGENT-MEMORY PROTOCOL -->/;
+                const legacyRegex = /<!-- local-agent-memory rules -->[\s\S]*?(?=\n\n|$)/;
+                if (protocolRegex.test(content)) {
+                    content = content.replace(protocolRegex, memoryInstructions.trim());
+                    await node_fs_1.default.promises.writeFile(filePath, content);
+                }
+                else if (legacyRegex.test(content)) {
+                    content = content.replace(legacyRegex, memoryInstructions.trim());
+                    await node_fs_1.default.promises.writeFile(filePath, content);
+                }
+                else {
                     await node_fs_1.default.promises.appendFile(filePath, `\n${memoryInstructions}`);
                 }
             }

package/dist/cli/commands/status.js

@@ -57,6 +57,16 @@ async function projectStatus() {
             manifestMap.delete(relativePath);
         }
         delCount = manifestMap.size;
+        // Check MCP usage stats if DB exists
+        let mcpStats = null;
+        if (node_fs_1.default.existsSync(localDbPath)) {
+            try {
+                mcpStats = await (0, project_1.getMcpUsageStats)(localDbPath);
+            }
+            catch (_e) {
+                // Table may not exist yet in older databases
+            }
+        }
         spinner.stop();
         console.log(`\nProject ID: ${projectId || "Unknown (Not in global registry)"}`);
         console.log(`Total MD files tracking: ${currentFiles.length}`);
@@ -66,6 +76,20 @@ async function projectStatus() {
         console.log(`Modified (unsynced): ${modCount}`);
         console.log(`Deleted (orphaned in db): ${delCount}`);
         console.log(`\nRun \`memory sync\` to update index.`);
+        if (mcpStats) {
+            console.log(`\nAgent & MCP Activity:`);
+            console.log(`---------------------------------`);
+            console.log(`Total MCP tool invocations: ${mcpStats.totalCalls}`);
+            console.log(` - Context & search recalls: ${mcpStats.readCalls}`);
+            console.log(` - Decisions & rules recorded: ${mcpStats.writeCalls}`);
+            console.log(`Last agent activity: ${mcpStats.lastConnection || "No recorded activity yet"}`);
+            if (mcpStats.recentQueries && mcpStats.recentQueries.length > 0) {
+                console.log(`\nRecent agent actions:`);
+                for (const q of mcpStats.recentQueries) {
+                    console.log(` [${q.timestamp}] ${q.tool_name || q.event_type}: ${q.query_or_summary || "success"}`);
+                }
+            }
+        }
     }
     catch (err) {
         spinner.fail("Status check failed.");

package/dist/core/search.d.ts

@@ -10,6 +10,12 @@ export interface SearchResult extends Chunk {
  * or punctuation (like *, AND, OR, NEAR).
  */
 export declare function sanitizeFtsQuery(query: string): string;
+/**
+ * Calculates a time decay multiplier for search results:
+ * Final_Score = RRF_Score * (1 / (1 + lambda * delta_days))
+ * Core rules or pinned files have lambda = 0 (multiplier = 1.0).
+ */
+export declare function calculateTimeDecayMultiplier(filePath: string, nowMs?: number, mtimeMs?: number): number;
 /**
  * Performs a hybrid search combining FTS5 lexical search and sqlite-vec vector search.
  * Uses Reciprocal Rank Fusion (RRF) to combine results.

package/dist/core/search.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sanitizeFtsQuery = sanitizeFtsQuery;
+exports.calculateTimeDecayMultiplier = calculateTimeDecayMultiplier;
 exports.hybridSearch = hybridSearch;
 const embeddings_1 = require("./embeddings");
 const sync_1 = require("./sync");
@@ -17,6 +18,31 @@ function sanitizeFtsQuery(query) {
         return "";
     return terms.map((t) => `"${t.replace(/"/g, '""')}"`).join(" ");
 }
+/**
+ * Calculates a time decay multiplier for search results:
+ * Final_Score = RRF_Score * (1 / (1 + lambda * delta_days))
+ * Core rules or pinned files have lambda = 0 (multiplier = 1.0).
+ */
+function calculateTimeDecayMultiplier(filePath, nowMs = Date.now(), mtimeMs) {
+    if (filePath.endsWith("core.md") || filePath.includes("pinned")) {
+        return 1.0;
+    }
+    // Check if filename starts with YYYY-MM-DD (e.g. ADRs or ledger sessions)
+    const baseName = filePath.split(/[/\\]/).pop() || "";
+    const match = baseName.match(/^(\d{4})-(\d{2})-(\d{2})/);
+    let ageDays = 0;
+    if (match) {
+        const fileDate = new Date(`${match[1]}-${match[2]}-${match[3]}`).getTime();
+        if (!Number.isNaN(fileDate)) {
+            ageDays = Math.max(0, (nowMs - fileDate) / (1000 * 60 * 60 * 24));
+        }
+    }
+    else if (mtimeMs) {
+        ageDays = Math.max(0, (nowMs - mtimeMs) / (1000 * 60 * 60 * 24));
+    }
+    const LAMBDA = 0.005; // Gentle decay factor
+    return 1 / (1 + LAMBDA * ageDays);
+}
 /**
  * Performs a hybrid search combining FTS5 lexical search and sqlite-vec vector search.
  * Uses Reciprocal Rank Fusion (RRF) to combine results.
@@ -129,6 +155,7 @@ async function hybridSearch(query, limit, db, filter) {
             row = await asyncDb.get("SELECT * FROM chunks WHERE id = ?", [id]);
         }
         if (row) {
+            const decay = calculateTimeDecayMultiplier(row.path);
             finalResults.push({
                 id: row.id,
                 path: row.path,
@@ -136,9 +163,10 @@ async function hybridSearch(query, limit, db, filter) {
                 breadcrumbs: row.breadcrumbs,
                 startLine: row.startLine,
                 endLine: row.endLine,
-                score,
+                score: score * decay,
             });
         }
     }
+    finalResults.sort((a, b) => b.score - a.score);
     return finalResults;
 }

package/dist/db/project.d.ts

@@ -11,3 +11,28 @@ export declare function upsertFileManifest(dbOrPath: string | sqlite3.Database,
 export declare function getFileManifest(dbOrPath: string | sqlite3.Database, file_path: string): Promise<FileManifestRow | null>;
 export declare function getAllManifests(dbOrPath: string | sqlite3.Database): Promise<FileManifestRow[]>;
 export declare function removeFileManifest(dbOrPath: string | sqlite3.Database, file_path: string): Promise<void>;
+export interface McpUsageLogRow {
+    id?: number;
+    timestamp?: string;
+    project_path: string;
+    event_type: string;
+    tool_name?: string | null | undefined;
+    query_or_summary?: string | null | undefined;
+    execution_time_ms?: number | null | undefined;
+    success?: boolean | null | undefined;
+}
+export interface McpUsageStats {
+    totalCalls: number;
+    readCalls: number;
+    writeCalls: number;
+    lastConnection: string | null;
+    recentQueries: Array<{
+        timestamp: string;
+        event_type: string;
+        tool_name: string | null;
+        query_or_summary: string | null;
+        success: boolean;
+    }>;
+}
+export declare function insertMcpUsageLog(dbOrPath: string | sqlite3.Database, entry: Omit<McpUsageLogRow, "id" | "timestamp">): Promise<void>;
+export declare function getMcpUsageStats(dbOrPath: string | sqlite3.Database): Promise<McpUsageStats>;

package/dist/db/project.js

@@ -10,6 +10,8 @@ exports.upsertFileManifest = upsertFileManifest;
 exports.getFileManifest = getFileManifest;
 exports.getAllManifests = getAllManifests;
 exports.removeFileManifest = removeFileManifest;
+exports.insertMcpUsageLog = insertMcpUsageLog;
+exports.getMcpUsageStats = getMcpUsageStats;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -34,11 +36,26 @@ function getLocalDbPath(projectRoot) {
     return node_path_1.default.join(projectRoot, ".memory", "local.sqlite");
 }
 function initLocalDb(dbPath) {
-    const db = new sqlite3_1.default.Database(dbPath);
+    const db = new sqlite3_1.default.Database(dbPath, () => { });
+    db.on("error", () => { });
     db.configure("busyTimeout", 5000);
     db.serialize(() => {
         db.run("PRAGMA journal_mode = WAL;");
         db.run("PRAGMA busy_timeout = 5000;");
+        db.run("PRAGMA synchronous = NORMAL;");
+        db.run("PRAGMA foreign_keys = ON;");
+        db.run(`
+      CREATE TABLE IF NOT EXISTS mcp_usage_logs (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
+        project_path TEXT,
+        event_type TEXT NOT NULL,
+        tool_name TEXT,
+        query_or_summary TEXT,
+        execution_time_ms INTEGER,
+        success BOOLEAN
+      )
+    `);
         db.run(`
       CREATE TABLE IF NOT EXISTS file_manifest (
         file_path TEXT PRIMARY KEY,
@@ -161,3 +178,96 @@ async function removeFileManifest(dbOrPath, file_path) {
         });
     });
 }
+async function insertMcpUsageLog(dbOrPath, entry) {
+    return new Promise((resolve) => {
+        try {
+            const isDb = typeof dbOrPath !== "string";
+            const db = isDb ? dbOrPath : initLocalDb(dbOrPath);
+            db.run(`INSERT INTO mcp_usage_logs (project_path, event_type, tool_name, query_or_summary, execution_time_ms, success)
+         VALUES (?, ?, ?, ?, ?, ?)`, [
+                entry.project_path,
+                entry.event_type,
+                entry.tool_name ?? null,
+                entry.query_or_summary ?? null,
+                entry.execution_time_ms ?? null,
+                entry.success ?? true,
+            ], (_err) => {
+                if (!isDb) {
+                    try {
+                        db.close();
+                    }
+                    catch { }
+                }
+                resolve();
+            });
+        }
+        catch {
+            resolve();
+        }
+    });
+}
+async function getMcpUsageStats(dbOrPath) {
+    return new Promise((resolve) => {
+        const emptyStats = {
+            totalCalls: 0,
+            readCalls: 0,
+            writeCalls: 0,
+            lastConnection: null,
+            recentQueries: [],
+        };
+        try {
+            const isDb = typeof dbOrPath !== "string";
+            const db = isDb ? dbOrPath : initLocalDb(dbOrPath);
+            db.serialize(() => {
+                db.all(`SELECT
+             COUNT(*) as total_count,
+             SUM(CASE WHEN tool_name IN ('get_project_context', 'memory_recall_context', 'search_memory') THEN 1 ELSE 0 END) as read_count,
+             SUM(CASE WHEN tool_name IN ('log_decision', 'memory_record_decision', 'update_core_rules', 'end_session') THEN 1 ELSE 0 END) as write_count,
+             MAX(timestamp) as last_conn
+           FROM mcp_usage_logs`, [], (err, statsRows) => {
+                    if (err) {
+                        if (!isDb) {
+                            try {
+                                db.close();
+                            }
+                            catch { }
+                        }
+                        return resolve(emptyStats);
+                    }
+                    db.all(`SELECT timestamp, event_type, tool_name, query_or_summary, success
+               FROM mcp_usage_logs
+               WHERE event_type = 'tool_call'
+               ORDER BY id DESC
+               LIMIT 5`, [], (err2, recentRows) => {
+                        if (!isDb) {
+                            try {
+                                db.close();
+                            }
+                            catch { }
+                        }
+                        if (err2) {
+                            return resolve(emptyStats);
+                        }
+                        const row = statsRows?.[0] || {};
+                        resolve({
+                            totalCalls: row.total_count || 0,
+                            readCalls: row.read_count || 0,
+                            writeCalls: row.write_count || 0,
+                            lastConnection: row.last_conn || null,
+                            recentQueries: (recentRows || []).map((r) => ({
+                                timestamp: r.timestamp,
+                                event_type: r.event_type,
+                                tool_name: r.tool_name,
+                                query_or_summary: r.query_or_summary,
+                                success: Boolean(r.success),
+                            })),
+                        });
+                    });
+                });
+            });
+        }
+        catch {
+            resolve(emptyStats);
+        }
+    });
+}

package/dist/db/registry.js

@@ -34,6 +34,8 @@ function initRegistryDb(dbPath = getRegistryDbPath()) {
     db.serialize(() => {
         db.run("PRAGMA journal_mode = WAL;");
         db.run("PRAGMA busy_timeout = 5000;");
+        db.run("PRAGMA synchronous = NORMAL;");
+        db.run("PRAGMA foreign_keys = ON;");
         db.run(`
       CREATE TABLE IF NOT EXISTS projects (
         project_id TEXT PRIMARY KEY,

package/dist/mcp/logger.d.ts

@@ -1,3 +1,4 @@
+export declare const getLocalMemoryDir: () => string;
 export interface MemoryConfig {
     project_id?: string;
     created_at?: string;
@@ -8,3 +9,4 @@ export interface MemoryConfig {
 }
 export declare function getMemoryConfig(cwd: string): MemoryConfig | null;
 export declare function logUsage(cwd: string, action: string, details?: Record<string, unknown>): void;
+export declare function recordMcpEvent(cwd: string, eventType: string, toolName?: string, queryOrSummary?: string, executionTimeMs?: number, success?: boolean): Promise<void>;