@deepsql/mcp 0.23.0 → 0.26.0

package/CLAUDE.md

@@ -33,8 +33,10 @@ server, and the statement you ran.** Don't be sloppy.
 
 ## The tools you have
 
-The MCP server exposes **41 tools** as of 0.19.0 — the original 16 +
-0.18.x's 5 slow-query tools + 0.19.0's 20 CLI-parity additions. Most
+The MCP server exposes **44 tools** as of 0.26.0 — the original 16 +
+0.18.x's 5 slow-query tools + 0.19.0's 20 CLI-parity additions + 0.26.0's
+3 brain-notes tools (`list_brain_recommendations`, `save_brain_note`,
+`list_brain_notes`). Most
 take a `connectionId` (UUID returned by `list_connections`); a few
 take server-resolved row ids (`apply_index_recommendation` →
 `recommendationId`, `dismiss_index_recommendation` →
@@ -65,6 +67,9 @@ in this version; ask before mid-session admin work.
 | `list_business_rules` | Active business rules and SQL guardrails. Honor these — they encode domain semantics. |
 | `get_relationships` | Inferred + validated foreign keys with confidence scores. Many real DBs lack declared FKs; this fills the gap. |
 | `get_anti_patterns` | Schema-level (`kind=table`) or query-level (`kind=query`) anti-patterns. |
+| `list_brain_recommendations` | The brain's AI-proposed notes to review for a connection (priority, reason, indicators, suggested prompt). The company-context review queue. |
+| `save_brain_note` | **Accept/save a fact into the shared brain** — grounds every future answer for the connection. TABLE- or COLUMN-scoped. Admin (manage-content), audited. Personal preferences belong in a DeepSQL skill, not here. |
+| `list_brain_notes` | Knowledge already saved to the brain (filter by table/column; can be thousands). |
 | `analyze_slow_queries` | Recent slow queries with fingerprints, durations, examples. Read-only; doesn't trigger new work. |
 | `get_slow_query_timeline` | Day-by-day timeline for one query from the 30-day analytics store — call count, mean/max time, regression factor per day. Identify the query by its fingerprint (the `queryId` from `analyze_slow_queries`). Answers "is this query getting slower". |
 | `get_query_regressions` | Slow queries that regressed (got slower) on the latest daily analysis run, ranked by slowdown factor. Read-only. |

package/README.md

@@ -88,7 +88,7 @@ Restart the editor for the entry to load.
 
 ## What the MCP server exposes
 
-**41 tools** as of 0.19.0. Read-only at the schema/retrieval/diagnostics
+**44 tools** as of 0.26.0. Read-only at the schema/retrieval/diagnostics
 layer; policy-gated at the SQL layer (only `execute_sql`,
 `analyze_query_plan` with `useAnalyze=true`, and
 `apply_index_recommendation` can write — the rest are reads or low-stakes
@@ -112,7 +112,7 @@ per-user admin ops (`users`/`access`/`permissions`).
 | `test_connection` | Run the privilege report (+ SSH check); reuses saved creds — no plaintext crosses the wire |
 | `reinit_connection_brain` | Trigger a fresh schema scan + brain re-embed |
 
-### Schema + retrieval brain (5)
+### Schema + retrieval brain (8)
 
 | Tool | Purpose |
 |---|---|
@@ -121,6 +121,9 @@ per-user admin ops (`users`/`access`/`permissions`).
 | `get_brain_context` | Retrieval brain: tables/columns/FKs/training docs/rules for a question |
 | `list_business_rules` | Active business rules and SQL guardrails for a connection |
 | `get_relationships` | Inferred + validated foreign keys with confidence scores |
+| `list_brain_recommendations` | The brain's AI-proposed notes to review (company-context queue) |
+| `save_brain_note` | Accept/save a fact into the shared brain (admin; grounds future answers) |
+| `list_brain_notes` | Knowledge already saved to the brain (filterable) |
 
 ### Anti-patterns + daily digest (4)
 

package/deepsql-phase1-lib.js

@@ -143,6 +143,51 @@ const TOOL_DEFINITIONS = [
       additionalProperties: false,
     },
   },
+  {
+    name: "list_brain_recommendations",
+    description:
+      "List the brain's AI-proposed recommendations for a connection — high-value tables/columns DeepSQL suggests documenting, each with a priority (P0/P1…), the reason, supporting indicators, and a suggested prompt to explore. This is the company-context review queue: an admin reviews these and accepts the good ones with save_brain_note. Returns { suggestions, totalCount } (totalCount reflects the requested limit, not an absolute total).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        limit: { type: "integer", minimum: 1, maximum: 100, description: "Max recommendations to return (default 10)." },
+      },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "save_brain_note",
+    description:
+      "Accept/save a fact into the connection's BRAIN — shared, company-level context that grounds EVERY future answer for this connection (not a per-user preference). Use this to accept a recommendation from list_brain_recommendations, or to record any durable fact about a table/column. Scope is TABLE (tableName only) or COLUMN (tableName + columnName). Requires manage-content permission on the connection (admin) — the backend enforces and audits it. NOTE: an individual's personal preference (how *they* like answers formatted, a private shortcut) belongs in a DeepSQL skill on their own profile, NOT here — this writes to the shared brain everyone sees.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        tableName: { type: "string", description: "Table the note is about (required)." },
+        columnName: { type: "string", description: "Column the note is about; omit for a table-scoped note." },
+        noteText: { type: "string", description: "The fact/guidance to remember." },
+      },
+      required: ["connectionId", "tableName", "noteText"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "list_brain_notes",
+    description:
+      "List knowledge already saved to the connection's brain (the notes that ground answers). Optionally filter by tableName and/or columnName — a trained connection can hold thousands of notes, so filtering is recommended. Use this to check whether a fact is already remembered before saving a new one with save_brain_note.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        tableName: { type: "string", description: "Filter to one table." },
+        columnName: { type: "string", description: "Filter to one column (use with tableName)." },
+      },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
   {
     name: "apply_index_recommendation",
     description:
@@ -1149,6 +1194,25 @@ function summarizeRelationships(payload) {
   return `${list.length} relationship(s) (${high} high-confidence).`;
 }
 
+function summarizeBrainRecommendations(payload) {
+  const list = (payload && payload.suggestions) || [];
+  if (!list.length) return "No brain recommendations pending review for this connection.";
+  const top = list
+    .slice(0, 5)
+    .map((s) => `${s.priority || ""} ${s.columnName ? `${s.tableName}.${s.columnName}` : s.tableName}`.trim());
+  return `${payload.totalCount ?? list.length} recommendation(s) to review. Top: ${top.join("; ")}. Accept the good ones with save_brain_note.`;
+}
+
+function summarizeBrainNoteSaved(payload) {
+  const target = payload && (payload.columnName ? `${payload.tableName}.${payload.columnName}` : payload.tableName);
+  return `Saved to brain${target ? ` — ${target}` : ""}. It now grounds future answers for this connection (shared, company-level).`;
+}
+
+function summarizeBrainNotes(payload) {
+  const list = Array.isArray(payload) ? payload : (payload && payload.notes) || [];
+  return `${list.length} brain note(s) for the requested scope.`;
+}
+
 function summarizeAntiPatterns(payload, kind) {
   if (kind === "table") {
     const tables = payload && typeof payload === "object" ? Object.keys(payload).length : 0;
@@ -1548,6 +1612,15 @@ function buildToolResult(name, payload, extra = {}) {
     case "get_growth_anomalies":
       summary = summarizeGrowthAnomalies(payload);
       break;
+    case "list_brain_recommendations":
+      summary = summarizeBrainRecommendations(payload);
+      break;
+    case "save_brain_note":
+      summary = summarizeBrainNoteSaved(payload);
+      break;
+    case "list_brain_notes":
+      summary = summarizeBrainNotes(payload);
+      break;
     case "get_index_recommendations":
       summary = summarizeIndexRecommendations(payload);
       break;
@@ -1596,10 +1669,28 @@ function buildToolError(message, extra = {}) {
   };
 }
 
+// Short-TTL in-memory cache for the connections list. The MCP server is a
+// long-lived process and `list_connections` is the "call this first" tool, so an
+// agent hits it repeatedly in a session — caching makes those calls instant. The
+// list changes rarely; a 30s TTL keeps it fresh enough.
+const CONNECTIONS_CACHE_TTL_MS = 30000;
+let _connectionsCache = null; // { key, ts, payload }
+
+async function fetchConnectionsCached(config) {
+  const key = `${(config && config.baseUrl) || ""}|${(config && config.authToken) || ""}`;
+  if (_connectionsCache && _connectionsCache.key === key
+      && Date.now() - _connectionsCache.ts < CONNECTIONS_CACHE_TTL_MS) {
+    return _connectionsCache.payload;
+  }
+  const payload = await callDeepSqlApi(config, "/connections");
+  _connectionsCache = { key, ts: Date.now(), payload };
+  return payload;
+}
+
 async function handleToolCall(config, name, args = {}) {
   switch (name) {
     case "list_connections": {
-      const payload = await callDeepSqlApi(config, "/connections");
+      const payload = await fetchConnectionsCached(config);
       return buildToolResult(name, payload);
     }
 
@@ -1684,6 +1775,52 @@ async function handleToolCall(config, name, args = {}) {
       return buildToolResult(name, payload, { kind });
     }
 
+    case "list_brain_recommendations": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const limit = clampInteger(args.limit, 1, 100, 10);
+      const payload = await callDeepSqlApi(
+        config,
+        `/brain/notes/suggestions/${encodeURIComponent(connectionId)}?limit=${limit}`,
+      );
+      return buildToolResult(name, payload);
+    }
+
+    case "save_brain_note": {
+      const connectionId = String(args.connectionId || "").trim();
+      const tableName = String(args.tableName || "").trim();
+      const noteText = String(args.noteText || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      if (!tableName) return buildToolError("tableName is required.");
+      if (!noteText) return buildToolError("noteText is required.");
+      const columnName = args.columnName ? String(args.columnName).trim() : null;
+      // Backend enforces manage-content permission (admin) + audits the write.
+      const payload = await callDeepSqlApi(config, "/brain/notes", {
+        method: "POST",
+        json: {
+          connectionId,
+          scopeType: columnName ? "COLUMN" : "TABLE",
+          tableName,
+          columnName,
+          noteText,
+        },
+      });
+      return buildToolResult(name, payload);
+    }
+
+    case "list_brain_notes": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const qs = [];
+      if (args.tableName) qs.push(`tableName=${encodeURIComponent(String(args.tableName))}`);
+      if (args.columnName) qs.push(`columnName=${encodeURIComponent(String(args.columnName))}`);
+      const payload = await callDeepSqlApi(
+        config,
+        `/brain/notes/${encodeURIComponent(connectionId)}${qs.length ? `?${qs.join("&")}` : ""}`,
+      );
+      return buildToolResult(name, payload);
+    }
+
     case "get_index_recommendations": {
       const connectionId = String(args.connectionId || "").trim();
       if (!connectionId) return buildToolError("connectionId is required.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepsql/mcp",
-  "version": "0.23.0",
+  "version": "0.26.0",
   "description": "DeepSQL CLI, DBA Agent (thin client), and stdio MCP server for self-hosted deployments",
   "bin": {
     "deepsql": "bin/deepsql.js",

package/skills/SKILL_BODY.md

@@ -2,7 +2,7 @@
 
 You have two DeepSQL surfaces available:
 
-1. **MCP tools** — JSON-RPC tools loaded into your session (41 of them
+1. **MCP tools** — JSON-RPC tools loaded into your session (44 of them
    as of 0.19.0). The MCP surface mirrors the CLI for almost every
    read/diagnostic operation, plus the two execute tools and the index-
    apply tool.
@@ -91,6 +91,9 @@ usually doesn't know about either; that's exactly why DeepSQL exists.
 | `list_business_rules(connectionId, question?)` | Rules the SQL must respect. |
 | `get_relationships(connectionId)` | Foreign keys (declared + inferred-with-confidence). |
 | `get_anti_patterns(connectionId, kind="table"\|"query")` | Patterns to avoid in this DB. |
+| `list_brain_recommendations(connectionId, limit?)` | The brain's AI-proposed things to document (the review queue). Admin accepts good ones with `save_brain_note`. |
+| `save_brain_note(connectionId, tableName, noteText, columnName?)` | **Accept/save a fact to the SHARED company brain** — grounds every future answer for this connection. Admin (manage-content). NOT for personal prefs — those go in a DeepSQL skill. |
+| `list_brain_notes(connectionId, tableName?, columnName?)` | Knowledge already in the brain; filter before saving a duplicate. |
 | `analyze_slow_queries(connectionId, thresholdMs?, limit?)` | Snapshot of slow queries from live stats. |
 | `get_slow_query_timeline(connectionId, fingerprint)` | Day-by-day timeline for one fingerprint: call count, mean/max time, regression factor per day. Answers "is this query getting slower". |
 | `get_query_regressions(connectionId, minFactor?)` | Slow queries that got slower on the latest daily analysis run, ranked by slowdown factor. |
@@ -138,7 +141,7 @@ called by claude-code via deepsql CLI").
 deepsql query "SELECT 1" --connection prod-pg --caller-agent claude-code --json
 ```
 
-### Command catalog (20 top-level commands)
+### Command catalog (21 top-level commands)
 
 | Command | What it does | MCP equivalent? |
 |---|---|---|
@@ -154,6 +157,7 @@ deepsql query "SELECT 1" --connection prod-pg --caller-agent claude-code --json
 | `deepsql analyze "<sql>" --connection <c>` | AI plan analysis (`--analyze` for EXPLAIN ANALYZE) | `analyze_query_plan` |
 | `deepsql schema [tables\|objects] --connection <c>` | Dump full schema as JSON | `get_schema` / `get_database_objects` |
 | `deepsql brain-context "<question>" --connection <c>` | Same retrieval as the MCP tool | `get_brain_context` |
+| `deepsql brain recommendations\|notes\|remember` | Review what DeepSQL has learned (AI-proposed notes), list saved notes, and `remember "<note>" --table <t> [--column <c>]` to teach it (admin) | none — CLI/web surface for the brain-notes loop |
 | `deepsql business-rules --connection <c>` | List active business rules | `list_business_rules` |
 | `deepsql relationships --connection <c>` | Inferred + validated FKs | `get_relationships` |
 | `deepsql anti-patterns --connection <c> [--kind table\|query]` | Anti-patterns | `get_anti_patterns` |

package/src/cli.js

@@ -28,6 +28,7 @@ const COMMANDS = {
   // Brain tools — give a coding agent the same retrieval context the chat
   // pipeline uses, then let the agent generate SQL/answers itself.
   "brain-context": () => require("./commands/brain-context"),
+  brain: () => require("./commands/brain"),
   "business-rules": () => require("./commands/business-rules"),
   relationships: () => require("./commands/relationships"),
   "anti-patterns": () => require("./commands/anti-patterns"),
@@ -60,6 +61,7 @@ const COMMAND_LIST = [
   ["digest",         true,  "Show DeepSQL daily digests"],
   ["growth",         true,  "Table growth analytics — trends, history, anomalies, alert config"],
   ["brain-context",  false, "Retrieve embedding-ranked context for a question"],
+  ["brain",          true,  "Review brain recommendations and remember facts (admin)"],
   ["business-rules", false, "List active business rules and SQL guardrails"],
   ["relationships",  false, "List inferred and validated FK relationships"],
   ["anti-patterns",  false, "List schema- or query-level anti-patterns"],
@@ -161,7 +163,7 @@ const COMMAND_HELP = {
     description: "Manage database connections — list, pin, full CRUD.",
     usage: "deepsql connections <subcommand> [options]",
     subcommands: [
-      ["list [--json]",                              "List database connections (active default marked with *)"],
+      ["list [--json] [--refresh]",                  "List database connections (cached ~60s; --refresh forces live)"],
       ["use <name>",                                 "Pin <name> as the active default for this profile"],
       ["current",                                    "Print the active default (exit 1 if none)"],
       ["unset",                                      "Clear the active default for this profile"],
@@ -174,6 +176,7 @@ const COMMAND_HELP = {
       ["init <name> [--force] [--wait]",             "Trigger brain re-initialization"],
     ],
     options: [
+      ["--refresh",                  "Bypass the connections cache and fetch live (list)"],
       ["--from-file <p>",            "Read connection JSON from file"],
       ["--from-stdin",               "Read connection JSON from stdin"],
       ["--upsert",                   "PUT instead of POST on add if name collision"],
@@ -261,6 +264,24 @@ const COMMAND_HELP = {
     notes: "`capture` and `config set` are the only mutations; both are admin-level but neither writes user data. Trends + anomalies are the agent-facing subcommands and are also exposed via the MCP tools `get_table_growth` and `get_growth_anomalies`.",
   },
 
+  brain: {
+    description: "Review what DeepSQL has learned about a connection and teach it more (admin).",
+    usage: "deepsql brain <subcommand> [options]",
+    subcommands: [
+      ["recommendations [--connection <name>] [--limit <n>]",   "AI-proposed things to document/investigate (alias: recs)"],
+      ["notes [--connection <name>] [--table <t>] [--column <c>]", "Knowledge already saved to the brain (filterable)"],
+      ['remember "<note>" --table <t> [--column <c>]',          "Save a fact to the brain (alias: save)"],
+    ],
+    options: [
+      ["--connection <name>", "Connection to act on (default: active connection)"],
+      ["--table <t>",         "Scope notes/remember to a table"],
+      ["--column <c>",        "Scope to a column (with --table)"],
+      ["--limit <n>",         "Cap results"],
+      ["--json",              "Raw JSON output"],
+    ],
+    notes: "`recommendations` reads /brain/notes/suggestions; `remember` writes a brain note (requires manage-content permission on the connection). The same recommendations surface backs the web UI.",
+  },
+
   "brain-context": {
     description: "Retrieve embedding-ranked tables/columns/FKs, training docs, and business rules for a question.",
     usage: 'deepsql brain-context "<question>" --connection <name> [options]',
@@ -581,6 +602,9 @@ function buildOpts(parsed) {
     label: f.label || null,
     // Connection / users / chat
     connection: f.connection || f.c || null,
+    // Brain notes scoping
+    table: f.table || null,
+    column: f.column || null,
     chat: f.chat || null,
     user: f.user || null,
     project: f.project || null,

package/src/cli.test.js

@@ -75,7 +75,7 @@ test("every command in the catalog has a COMMAND_HELP entry", () => {
   const expected = [
     "agent",
     "login","logout","whoami","config","mcp","connections","query","analyze","schema",
-    "digest","brain-context","business-rules","relationships","anti-patterns","indexes",
+    "digest","brain-context","brain","business-rules","relationships","anti-patterns","indexes",
     "users","access","permissions","slow-queries","setup",
   ];
   for (const name of expected) {
@@ -137,6 +137,7 @@ test("--no-color suppresses ANSI escapes in help output", async () => {
 // a `SUBCOMMANDS` object whose keys are the dispatchable subcommand names.
 const HELP_DRIFT_TARGETS = [
   { command: "slow-queries", modulePath: "./commands/slow-queries" },
+  { command: "brain", modulePath: "./commands/brain" },
 ];
 
 for (const { command, modulePath } of HELP_DRIFT_TARGETS) {

package/src/commands/_agent_intro.js

@@ -35,6 +35,7 @@ const LOGO = [
 const PURPLE_LIGHT = 141; // #af87ff
 const PURPLE = 99; //        #875fff
 const PURPLE_DEEP = 98; //   #875fd7
+const AMBER = 178; //        #d7af00 — "needs attention" marker, readable on light & dark
 const LOGO_ROWS = [PURPLE_LIGHT, PURPLE_LIGHT, PURPLE, PURPLE, PURPLE_DEEP];
 
 function c(n, s, on) {
@@ -75,7 +76,17 @@ function promptLabel(useColor) {
   return "\n" + c(PURPLE, "deepsql ›", useColor) + " ";
 }
 
-function renderIntro(stdout, { useColor = true, connectionLabel = null, versionLine = null } = {}) {
+function renderIntro(
+  stdout,
+  {
+    useColor = true,
+    connectionLabel = null,
+    versionLine = null,
+    connections = [],
+    suggestions = [],
+    recommendationCount = 0,
+  } = {}
+) {
   const out = [""];
   LOGO.forEach((row, i) => out.push("  " + c(LOGO_ROWS[i], row, useColor)));
   out.push("");
@@ -88,6 +99,44 @@ function renderIntro(stdout, { useColor = true, connectionLabel = null, versionL
     const label = `${cat} prompt`;
     out.push("    " + c(PURPLE_LIGHT, label.padEnd(16), useColor) + `"${pick(PROMPTS[cat])}"`);
   }
+
+  // Connections the token can see (frictionless onboarding: guide to add one if none).
+  out.push("");
+  if (connections.length === 0) {
+    out.push("  " + c(PURPLE, "No databases connected yet", useColor));
+    out.push("    " + dim("→ ", useColor) + "deepsql connections add");
+  } else {
+    out.push("  " + c(PURPLE, `Connections (${connections.length})`, useColor));
+    const width = Math.min(24, Math.max(...connections.map((x) => x.name.length)));
+    for (const conn of connections.slice(0, 8)) {
+      out.push("    " + conn.name.padEnd(width + 2) + dim(conn.dbType, useColor));
+    }
+    if (connections.length > 8) out.push("    " + dim(`… +${connections.length - 8} more`, useColor));
+  }
+
+  // Admin "needs attention" — config suggestions for connections the user manages.
+  if (suggestions.length) {
+    out.push("");
+    out.push("  " + c(AMBER, "Needs attention", useColor));
+    for (const s of suggestions.slice(0, 6)) {
+      out.push(
+        "    " + c(AMBER, "⚠ ", useColor) + s.conn + dim(" · ", useColor) + s.text
+      );
+      if (s.fix) out.push("        " + dim("→ ", useColor) + dim(s.fix, useColor));
+    }
+    if (suggestions.length > 6) out.push("    " + dim(`… +${suggestions.length - 6} more`, useColor));
+  }
+
+  // Brain learning loop: prompt admins to review what DeepSQL wants to remember.
+  if (recommendationCount > 0) {
+    out.push("");
+    out.push(
+      "  " +
+        c(PURPLE, `${recommendationCount} brain recommendation${recommendationCount === 1 ? "" : "s"} to review`, useColor) +
+        dim("  → deepsql brain recs", useColor)
+    );
+  }
+
   out.push("");
   if (connectionLabel) {
     out.push("  " + dim("Grounded on ", useColor) + connectionLabel);

package/src/commands/_agent_status.js

@@ -0,0 +1,93 @@
+"use strict";
+
+// Best-effort onboarding data for the agent intro: the connections this token
+// can see, plus per-connection "needs attention" suggestions for connections the
+// user can configure (admin-level). Uses EXISTING backend endpoints only:
+//   GET /connections                       (RBAC-scoped list, with canManageConfig)
+//   GET /connections/{id}/init-status       (brain readiness: currentStage)
+//   GET /slow-log-source/{id}               (slow-query log: enabled)
+//
+// Everything is wrapped in tight timeouts and swallows errors, so a slow or old
+// backend (missing an endpoint) degrades to "show whatever we have" and never
+// blocks the REPL.
+
+const { request } = require("../api/client");
+const { listConnections } = require("./_connections");
+
+function withTimeout(p, ms) {
+  return Promise.race([
+    Promise.resolve(p),
+    new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), ms)),
+  ]);
+}
+
+// Derive config suggestions + a brain-recommendation count for one connection
+// from its status endpoints. Returns { items: [...attention], recCount }.
+async function checkConnection(session, c) {
+  const out = [];
+  const [init, slow, recs] = await Promise.all([
+    request(session.baseUrl, `/connections/${encodeURIComponent(c.id)}/init-status`, {
+      token: session.token,
+    }).catch(() => null),
+    request(session.baseUrl, `/slow-log-source/${encodeURIComponent(c.id)}`, {
+      token: session.token,
+    }).catch(() => null),
+    // totalCount tracks the limit, so request enough to give an accurate-ish
+    // "N to review" nudge (the brain command shows the full list).
+    request(session.baseUrl, `/brain/notes/suggestions/${encodeURIComponent(c.id)}?limit=25`, {
+      token: session.token,
+    }).catch(() => null),
+  ]);
+
+  const stage = init && init.currentStage;
+  const pct = (init && init.progressPercent) || 0;
+  if (stage === "FAILED") {
+    out.push({ conn: c.name, text: "brain initialization failed", fix: `deepsql connections init ${c.name}` });
+  } else if (stage && stage !== "READY" && pct < 100) {
+    // Skip near-done (100% but not yet flipped to READY) — don't nag.
+    out.push({ conn: c.name, text: `brain still initializing (${pct}%)`, fix: `deepsql connections init ${c.name}` });
+  }
+  if (slow && slow.enabled !== true) {
+    out.push({
+      conn: c.name,
+      text: "slow-query log not connected",
+      fix: "set it up in the web UI → Slow Query Log",
+    });
+  }
+  // Brain recommendations to review (only meaningful once the brain is trained).
+  const recCount = stage !== "FAILED" && recs && typeof recs.totalCount === "number" ? recs.totalCount : 0;
+  return { items: out, recCount };
+}
+
+// Returns { connections: [{name,dbType,canManage}], suggestions: [{conn,text,fix}] }.
+async function loadIntroData(session, { timeoutMs = 2500 } = {}) {
+  const data = { connections: [], suggestions: [], recommendationCount: 0 };
+  try {
+    const list = await withTimeout(listConnections(session), timeoutMs);
+    data.connections = (list || []).map((c) => ({
+      id: c.id,
+      name: c.connectionName || c.name || c.id,
+      dbType: c.dbType || "",
+      canManage: !!c.canManageConfig,
+    }));
+    // Status/suggestions only for connections this user can configure
+    // (admin-level), capped so a workspace with many connections doesn't fan
+    // out at startup.
+    const manageable = data.connections.filter((c) => c.canManage).slice(0, 6);
+    if (manageable.length) {
+      const checks = await withTimeout(
+        Promise.all(
+          manageable.map((c) => checkConnection(session, c).catch(() => ({ items: [], recCount: 0 })))
+        ),
+        timeoutMs
+      );
+      data.suggestions = checks.flatMap((r) => r.items);
+      data.recommendationCount = checks.reduce((n, r) => n + (r.recCount || 0), 0);
+    }
+  } catch {
+    /* degrade gracefully — render whatever we have */
+  }
+  return data;
+}
+
+module.exports = { loadIntroData };

package/src/commands/_connections.js

@@ -17,16 +17,40 @@
  */
 
 const { request } = require("../api/client");
+const cache = require("../connections/cache");
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
-let cachedList = null;
+let inProcess = null; // L1: within a single command invocation
 
-async function listConnections(session) {
-  if (cachedList) return cachedList;
-  cachedList = await request(session.baseUrl, "/connections", { token: session.token });
-  if (!Array.isArray(cachedList)) cachedList = [];
-  return cachedList;
+// Connections list with two cache tiers: the in-process memo (L1) and a short-
+// TTL on-disk cache (L2) shared across `deepsql` invocations. Pass refresh:true
+// to bypass both and fetch live (then refresh the caches).
+async function listConnections(session, { refresh = false } = {}) {
+  if (!refresh) {
+    if (inProcess) return inProcess;
+    const disk = cache.read(session.baseUrl);
+    if (disk) {
+      inProcess = disk;
+      return disk;
+    }
+  }
+  const fetched = await request(session.baseUrl, "/connections", { token: session.token });
+  const list = Array.isArray(fetched) ? fetched : [];
+  inProcess = list;
+  cache.write(session.baseUrl, list);
+  return list;
+}
+
+function matchConnection(connections, trimmed) {
+  const exact = connections.filter((c) => (c.connectionName || c.name) === trimmed);
+  if (exact.length === 1) return { id: exact[0].id || exact[0].connectionId };
+  const ci = connections.filter(
+    (c) => String(c.connectionName || c.name || "").toLowerCase() === trimmed.toLowerCase(),
+  );
+  if (ci.length === 1) return { id: ci[0].id || ci[0].connectionId };
+  if (ci.length > 1) return { ambiguous: ci };
+  return null;
 }
 
 /**
@@ -59,17 +83,17 @@ async function resolveConnectionId(session, input) {
   const trimmed = raw.trim();
   if (UUID_RE.test(trimmed)) return trimmed;
 
-  const connections = await listConnections(session);
-  const exact = connections.filter((c) => (c.connectionName || c.name) === trimmed);
-  if (exact.length === 1) return exact[0].id || exact[0].connectionId;
-
-  const ciMatches = connections.filter(
-    (c) => String(c.connectionName || c.name || "").toLowerCase() === trimmed.toLowerCase(),
-  );
-  if (ciMatches.length === 1) return ciMatches[0].id || ciMatches[0].connectionId;
-
-  if (ciMatches.length > 1) {
-    const names = ciMatches.map((c) => `${c.connectionName} (${c.id})`).join(", ");
+  // Try the (possibly cached) list first; on a miss, refetch live once before
+  // failing — so a connection added since the cache was written still resolves.
+  let connections = await listConnections(session);
+  let m = matchConnection(connections, trimmed);
+  if (!m) {
+    connections = await listConnections(session, { refresh: true });
+    m = matchConnection(connections, trimmed);
+  }
+  if (m && m.id) return m.id;
+  if (m && m.ambiguous) {
+    const names = m.ambiguous.map((c) => `${c.connectionName} (${c.id})`).join(", ");
     throw new Error(
       `Multiple connections match "${trimmed}" by case-insensitive name: ${names}. Pass the exact name or the id.`,
     );

package/src/commands/agent.js

@@ -16,6 +16,7 @@ const { request } = require("../api/client");
 const { resolveSession } = require("./_session");
 const { resolveConnectionId } = require("./_connections");
 const { renderIntro, getVersionLine, promptLabel } = require("./_agent_intro");
+const { loadIntroData } = require("./_agent_status");
 
 // The brokered turn can run a full multi-tool agent loop server-side; allow well
 // past the backend's own per-turn ceiling so we don't abandon a valid answer.
@@ -113,8 +114,20 @@ async function run(opts, io = {}) {
     // Only surface a connection when one was explicitly named; a default/absent
     // connection shows nothing (the agent asks if a question needs one).
     const connectionLabel = opts.connection || null;
-    const versionLine = await getVersionLine(useColor); // best-effort, tight timeout
-    renderIntro(stdout, { useColor, connectionLabel, versionLine });
+    // Version check + connections/suggestions run in parallel (both best-effort,
+    // tight timeouts) so startup waits on the slower one, not the sum.
+    const [versionLine, introData] = await Promise.all([
+      getVersionLine(useColor),
+      loadIntroData(session),
+    ]);
+    renderIntro(stdout, {
+      useColor,
+      connectionLabel,
+      versionLine,
+      connections: introData.connections,
+      suggestions: introData.suggestions,
+      recommendationCount: introData.recommendationCount,
+    });
   }
   // conversationId stays null on the first turn so the server resumes your most
   // recent conversation for this connection (shared with the web Agent tab);

package/src/commands/brain.js

@@ -0,0 +1,144 @@
+"use strict";
+
+// `deepsql brain` — review what DeepSQL has learned about a connection and teach
+// it more. The "remember things as people use it" admin loop, on the CLI:
+//   recommendations  AI-proposed things to document/investigate (the inbox)
+//   notes            knowledge already saved to the brain (filterable)
+//   remember         save a fact to the brain (admin: needs manage-content)
+//
+// Backed by existing endpoints — no new backend:
+//   GET  /brain/notes/suggestions/{connectionId}?limit=N   → { suggestions, totalCount }
+//   GET  /brain/notes/{connectionId}[?tableName=&columnName=]
+//   POST /brain/notes   { connectionId, scopeType, tableName, columnName, noteText }
+
+const { ApiError, request } = require("../api/client");
+const { resolveSession } = require("./_session");
+const { resolveConnectionId } = require("./_connections");
+
+// Canonical subcommands (the drift guard compares these keys to the help rows).
+const SUBCOMMANDS = {
+  recommendations: cmdRecommendations,
+  notes: cmdNotes,
+  remember: cmdRemember,
+};
+// Convenience aliases resolved before dispatch (kept out of SUBCOMMANDS so the
+// help-drift test stays clean).
+const ALIASES = { recs: "recommendations", save: "remember" };
+
+async function run(opts, io = {}) {
+  const raw = opts.positional[0];
+  if (!raw) throw new Error("Usage: deepsql brain <recommendations|notes|remember> [options]");
+  const sub = ALIASES[raw] || raw;
+  const handler = SUBCOMMANDS[sub];
+  if (!handler) throw new Error(`Unknown brain subcommand: ${raw}.`);
+  return wrap(handler)({ ...opts, positional: opts.positional.slice(1) }, io);
+}
+
+function wrap(handler) {
+  return async (opts, io) => {
+    try {
+      return await handler(opts, io);
+    } catch (err) {
+      if (err instanceof ApiError && err.status === 403) {
+        throw new Error("Access denied — this brain operation requires manage-content permission on the connection.");
+      }
+      throw err;
+    }
+  };
+}
+
+// ─── recommendations ─────────────────────────────────────────────────────────
+async function cmdRecommendations(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const limit = parseInt(opts.limit, 10) || 10;
+  const res = await request(
+    session.baseUrl,
+    `/brain/notes/suggestions/${encodeURIComponent(connectionId)}?limit=${limit}`,
+    { token: session.token }
+  );
+  const suggestions = (res && res.suggestions) || [];
+  if (opts.json) {
+    stdout.write(JSON.stringify(suggestions, null, 2) + "\n");
+    return 0;
+  }
+  if (!suggestions.length) {
+    stdout.write("No recommendations — the brain has nothing pending to review for this connection.\n");
+    return 0;
+  }
+  stdout.write(`\nBrain recommendations (${res.totalCount ?? suggestions.length}):\n\n`);
+  for (const s of suggestions) {
+    const target = s.columnName ? `${s.tableName}.${s.columnName}` : s.tableName;
+    stdout.write(`  ${String(s.priority || "").padEnd(3)} ${target}\n`);
+    if (s.reason) stdout.write(`      ${s.reason}\n`);
+    if (Array.isArray(s.indicators) && s.indicators.length) {
+      stdout.write(`      ${s.indicators.join(" · ")}\n`);
+    }
+    if (s.suggestedPrompt) stdout.write(`      explore: deepsql agent "${s.suggestedPrompt}"\n`);
+    stdout.write("\n");
+  }
+  stdout.write('Save a fact with:  deepsql brain remember "<note>" --table <t> [--column <c>]\n');
+  return 0;
+}
+
+// ─── notes ───────────────────────────────────────────────────────────────────
+async function cmdNotes(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const qs = [];
+  if (opts.table) qs.push(`tableName=${encodeURIComponent(opts.table)}`);
+  if (opts.column) qs.push(`columnName=${encodeURIComponent(opts.column)}`);
+  const notes = await request(
+    session.baseUrl,
+    `/brain/notes/${encodeURIComponent(connectionId)}${qs.length ? `?${qs.join("&")}` : ""}`,
+    { token: session.token }
+  );
+  const list = Array.isArray(notes) ? notes : [];
+  if (opts.json) {
+    stdout.write(JSON.stringify(list, null, 2) + "\n");
+    return 0;
+  }
+  if (!list.length) {
+    stdout.write("No saved notes for that scope.\n");
+    return 0;
+  }
+  const limit = parseInt(opts.limit, 10) || 20;
+  stdout.write(`\nBrain notes (${list.length}${list.length > limit ? `, showing ${limit}` : ""}):\n\n`);
+  for (const n of list.slice(0, limit)) {
+    const target = n.columnName ? `${n.tableName}.${n.columnName}` : n.tableName;
+    const tags = `${n.source ? `  [${n.source}]` : ""}${n.stale ? "  (stale)" : ""}`;
+    stdout.write(`  ${target}${tags}\n      ${n.noteText}\n\n`);
+  }
+  if (list.length > limit) {
+    stdout.write(`… +${list.length - limit} more — narrow with --table <t> [--column <c>], or --limit N\n`);
+  }
+  return 0;
+}
+
+// ─── remember ────────────────────────────────────────────────────────────────
+async function cmdRemember(opts, { stdout = process.stdout, stderr = process.stderr } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const noteText = (opts.positional || []).join(" ").trim();
+  if (!noteText) {
+    stderr.write('Usage: deepsql brain remember "<note text>" --table <t> [--column <c>]\n');
+    return 2;
+  }
+  if (!opts.table) {
+    stderr.write("A --table is required (add --column for a column-scoped note).\n");
+    return 2;
+  }
+  const body = {
+    connectionId,
+    scopeType: opts.column ? "COLUMN" : "TABLE",
+    tableName: opts.table,
+    columnName: opts.column || null,
+    noteText,
+  };
+  await request(session.baseUrl, "/brain/notes", { method: "POST", token: session.token, json: body });
+  const target = body.columnName ? `${body.tableName}.${body.columnName}` : body.tableName;
+  stdout.write(`✓ Saved to brain — ${target}: ${noteText}\n`);
+  return 0;
+}
+
+module.exports = { run, SUBCOMMANDS };

package/src/commands/connections.js

@@ -27,9 +27,10 @@ const fs = require("node:fs");
 const { ApiError, request } = require("../api/client");
 const store = require("../auth/store");
 const { resolveSession } = require("./_session");
-const { resolveConnectionId } = require("./_connections");
+const { resolveConnectionId, listConnections } = require("./_connections");
 const { resolveSecrets, maskSecrets, SECRET_FIELDS } = require("../connections/secrets");
 const { SCHEMA, validate } = require("../connections/schema");
+const cache = require("../connections/cache");
 const ui = require("../ui/prompts");
 const { promptPassword } = require("../auth/prompt");
 
@@ -59,7 +60,8 @@ async function run(opts, io = {}) {
 
 async function runList(opts, { stdout = process.stdout } = {}) {
   const session = resolveSession(opts);
-  const data = await request(session.baseUrl, "/connections", { token: session.token });
+  // Cached for speed; --refresh (or --no-cache) forces a live fetch.
+  const data = await listConnections(session, { refresh: !!(opts.refresh || opts.noCache) });
   if (opts.json) {
     stdout.write(`${JSON.stringify(data, null, 2)}\n`);
     return;
@@ -228,6 +230,7 @@ async function runAdd(opts, { stdout = process.stdout, stderr = process.stderr }
     throw new Error(saved.message || "Connection save failed.");
   }
   const id = saved?.connectionId || saved?.id;
+  cache.invalidate(session.baseUrl);
   if (saved?.privileges) printPrivilegeReport(stderr, saved);
   stdout.write(`Saved "${cfg.connectionName}" (id ${id || "?"}).\n`);
 
@@ -277,6 +280,7 @@ async function runUpdate(opts, { stdout = process.stdout, stderr = process.stder
   if (saved?.success === false) {
     throw new Error(saved.message || "Connection update failed.");
   }
+  cache.invalidate(session.baseUrl);
   if (saved?.privileges) printPrivilegeReport(stderr, saved);
   stdout.write(`Updated "${target}".\n`);
 }
@@ -303,6 +307,7 @@ async function runRemove(opts, { stdout = process.stdout, stderr = process.stder
     method: "DELETE",
     token: session.token,
   });
+  cache.invalidate(session.baseUrl);
   if (session.defaultConnection === target) {
     store.setDefaultConnection(session.baseUrl, null);
     stderr.write(`[deepsql] Cleared the active-connection pin (was "${target}").\n`);
@@ -391,6 +396,7 @@ async function runInit(opts, { stdout = process.stdout, stderr = process.stderr
     token: session.token,
     json: { force: !!opts.force },
   });
+  cache.invalidate(session.baseUrl);
   stdout.write(`Brain reinit triggered for "${target}".\n`);
   if (opts.wait) await pollInitStatus(session, connectionId, stderr);
 }

package/src/connections/cache.js

@@ -0,0 +1,52 @@
+"use strict";
+
+// Small on-disk cache for the connections list, keyed per DeepSQL instance.
+// Each `deepsql` invocation is a fresh process, so without this every command
+// re-fetches (and re-decrypts, server-side) the whole list just to resolve
+// `--connection`. The list changes rarely, so a short TTL makes the common path
+// (resolve a connection name → id) effectively free while staying fresh.
+//
+// Holds only the same non-secret connection summary the user already sees
+// (name/host/port/etc.; secrets are masked server-side). File is 0600.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+const { configDir } = require("../auth/store");
+
+const DEFAULT_TTL_MS = 60000; // 60s
+
+function cacheFile(baseUrl) {
+  const key = crypto.createHash("sha1").update(String(baseUrl || "")).digest("hex").slice(0, 16);
+  return path.join(configDir(), "cache", `connections-${key}.json`);
+}
+
+function read(baseUrl, ttlMs = DEFAULT_TTL_MS) {
+  try {
+    const obj = JSON.parse(fs.readFileSync(cacheFile(baseUrl), "utf8"));
+    if (!obj || !Array.isArray(obj.data)) return null;
+    if (Date.now() - (obj.ts || 0) > ttlMs) return null;
+    return obj.data;
+  } catch {
+    return null;
+  }
+}
+
+function write(baseUrl, data) {
+  if (!Array.isArray(data)) return;
+  try {
+    const dir = path.join(configDir(), "cache");
+    fs.mkdirSync(dir, { recursive: true });
+    const file = cacheFile(baseUrl);
+    fs.writeFileSync(file, JSON.stringify({ ts: Date.now(), data }), { mode: 0o600 });
+    try { fs.chmodSync(file, 0o600); } catch { /* best-effort */ }
+  } catch {
+    /* cache is best-effort — never fail a command over it */
+  }
+}
+
+function invalidate(baseUrl) {
+  try { fs.rmSync(cacheFile(baseUrl), { force: true }); } catch { /* ignore */ }
+}
+
+module.exports = { read, write, invalidate, DEFAULT_TTL_MS };