memory_stats

Instructions

Implementation Reference

• packages/server/src/tools/memory-stats.ts:4-69 (handler)

  The handler function `handleMemoryStats()` that executes the memory_stats tool logic. It queries the SQLite database for counts of memories, journal entries, archives, searches, and presents them grouped by category, project, most accessed, and recent searches.

  export async function handleMemoryStats(): Promise<string> {
    const db = getDb();
  
    const memCount = (db.prepare(`SELECT COUNT(*) as c FROM memories`).get() as { c: number }).c;
    const journalCount = (db.prepare(`SELECT COUNT(*) as c FROM journal_entries`).get() as { c: number }).c;
    const archivedCount = (db.prepare(`SELECT COUNT(*) as c FROM memories WHERE archived = 1`).get() as { c: number }).c;
    const searchCount = (db.prepare(`SELECT COUNT(*) as c FROM search_log`).get() as { c: number }).c;
  
    const byCategory = db
      .prepare(`SELECT category, COUNT(*) as c FROM memories WHERE archived = 0 GROUP BY category ORDER BY c DESC`)
      .all() as Array<{ category: string; c: number }>;
  
    const byProject = db
      .prepare(
        `SELECT COALESCE(project, '(no project)') as project, COUNT(*) as c FROM memories WHERE archived = 0 GROUP BY project ORDER BY c DESC LIMIT 10`,
      )
      .all() as Array<{ project: string; c: number }>;
  
    const topAccessed = db
      .prepare(`SELECT content, access_count, category FROM memories WHERE access_count > 0 ORDER BY access_count DESC LIMIT 5`)
      .all() as Array<{ content: string; access_count: number; category: string }>;
  
    const recentSearches = db
      .prepare(`SELECT query, results_count, created_at FROM search_log ORDER BY created_at DESC LIMIT 5`)
      .all() as Array<{ query: string; results_count: number; created_at: number }>;
  
    let output = `## Memory Stats\n\n`;
    output += `- **Memories**: ${memCount} active, ${archivedCount} archived\n`;
    output += `- **Journal entries**: ${journalCount}\n`;
    output += `- **Searches performed**: ${searchCount}\n`;
    output += `- **Search mode**: ${isUsingFallback() ? "keyword (Ollama not available)" : "semantic (Ollama)"}\n\n`;
  
    if (byCategory.length > 0) {
      output += `### By Category\n`;
      for (const { category, c } of byCategory) {
        output += `- ${category}: ${c}\n`;
      }
      output += "\n";
    }
  
    if (byProject.length > 0) {
      output += `### By Project\n`;
      for (const { project, c } of byProject) {
        output += `- ${project}: ${c}\n`;
      }
      output += "\n";
    }
  
    if (topAccessed.length > 0) {
      output += `### Most Accessed\n`;
      for (const { content, access_count, category } of topAccessed) {
        output += `- (${access_count}x, ${category}) ${content.slice(0, 80)}\n`;
      }
      output += "\n";
    }
  
    if (recentSearches.length > 0) {
      output += `### Recent Searches\n`;
      for (const { query, results_count, created_at } of recentSearches) {
        const date = new Date(created_at).toISOString().slice(0, 16).replace("T", " ");
        output += `- "${query}" → ${results_count} results (${date})\n`;
      }
    }
  
    return output;
  }

• packages/server/src/index.ts:311-326 (registration)

  Registration of the 'memory_stats' tool on the MCP server via `server.tool()` with an empty schema (no inputs) and a callback that calls handleMemoryStats().

  server.tool(
    "memory_stats",
    "Show memory system statistics — counts by category, project, most accessed, and recent searches.",
    {},
    async () => {
      try {
        const result = await handleMemoryStats();
        return { content: [{ type: "text", text: result }] };
      } catch (err) {
        return {
          content: [{ type: "text", text: `Error getting stats: ${err}` }],
          isError: true,
        };
      }
    },
  );

• packages/server/src/index.ts:314-314 (schema)

  The schema is an empty object '{}' — the memory_stats tool takes no input parameters.

  {},

• packages/server/src/memory/db.ts:21-82 (helper)

  Helper function `getDb()` that initializes and returns the SQLite database connection, used by the handler to run queries on the memories, journal_entries, and search_log tables.

  export function getDb(): any {
    if (_db) return _db;
    if (_unavailable || !Database) {
      _unavailable = true;
      throw new Error(
        "Memory database unavailable — better-sqlite3 failed to load. " +
        "This is usually a native compilation issue. Memory features are disabled but everything else works. " +
        "Try: npm rebuild better-sqlite3"
      );
    }
  
    try {
      fs.mkdirSync(DB_DIR, { recursive: true });
      _db = new Database(DB_PATH);
  
      _db.pragma("journal_mode = WAL");
  
      _db.exec(`
        CREATE TABLE IF NOT EXISTS memories (
          id TEXT PRIMARY KEY,
          content TEXT NOT NULL,
          category TEXT NOT NULL DEFAULT 'general',
          project TEXT,
          source_file TEXT,
          created_at INTEGER NOT NULL,
          updated_at INTEGER NOT NULL,
          accessed_at INTEGER NOT NULL,
          access_count INTEGER NOT NULL DEFAULT 0,
          archived INTEGER NOT NULL DEFAULT 0,
          embedding BLOB
        );
  
        CREATE TABLE IF NOT EXISTS journal_entries (
          id TEXT PRIMARY KEY,
          session_id TEXT,
          project TEXT,
          content TEXT NOT NULL,
          created_at INTEGER NOT NULL,
          embedding BLOB
        );
  
        CREATE TABLE IF NOT EXISTS search_log (
          id INTEGER PRIMARY KEY AUTOINCREMENT,
          query TEXT NOT NULL,
          results_count INTEGER NOT NULL,
          created_at INTEGER NOT NULL
        );
  
        CREATE INDEX IF NOT EXISTS idx_memories_category ON memories(category);
        CREATE INDEX IF NOT EXISTS idx_memories_project ON memories(project);
        CREATE INDEX IF NOT EXISTS idx_memories_created ON memories(created_at);
        CREATE INDEX IF NOT EXISTS idx_memories_archived ON memories(archived);
        CREATE INDEX IF NOT EXISTS idx_journal_created ON journal_entries(created_at);
        CREATE INDEX IF NOT EXISTS idx_journal_project ON journal_entries(project);
      `);
  
      return _db;
    } catch (err) {
      _unavailable = true;
      throw new Error(`Memory database failed to initialize: ${err}`);
    }
  }

• packages/server/src/memory/embeddings.ts:26-28 (helper)

  Helper function `isUsingFallback()` that returns whether Ollama is unavailable (fallback to keyword search), used in the handler output to indicate the search mode.

  export function isUsingFallback(): boolean {
    return _fallbackMode === true;
  }