gitmem-mcp 1.0.2 → 1.0.4

package/dist/tools/definitions.js

@@ -4,14 +4,14 @@
  * All tool registrations (names, descriptions, JSON schemas) for the GitMem MCP server.
  * Extracted from server.ts for maintainability.
  */
-import { hasBatchOperations, hasTranscripts, hasCacheManagement, hasSupabase, } from "../services/tier.js";
+import { hasBatchOperations, hasTranscripts, hasCacheManagement, hasSupabase, hasFullAliases, } from "../services/tier.js";
 /**
  * Tool definitions for MCP
  */
 export const TOOLS = [
     {
         name: "recall",
-        description: "Check institutional memory for relevant scars before taking action. Returns matching scars and their lessons. OD-525: Integrates variant assignment when issue_id provided.",
+        description: "Check institutional memory for relevant scars before taking action. Returns matching scars and their lessons. Integrates variant assignment when issue_id provided.",
         inputSchema: {
             type: "object",
             properties: {
@@ -21,7 +21,7 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
                 match_count: {
                     type: "number",
@@ -29,7 +29,11 @@ export const TOOLS = [
                 },
                 issue_id: {
                     type: "string",
-                    description: "Linear issue identifier for variant assignment (e.g., 'OD-525'). When provided, scars with variants will be randomly assigned and formatted accordingly.",
+                    description: "Linear issue identifier for variant assignment (e.g., 'PROJ-123'). When provided, scars with variants will be randomly assigned and formatted accordingly.",
+                },
+                similarity_threshold: {
+                    type: "number",
+                    description: "Minimum similarity score (0-1) to include results. Weak matches below threshold are suppressed. Default: 0.4 (free tier BM25), 0.35 (pro tier embeddings).",
                 },
             },
             required: ["plan"],
@@ -59,6 +63,11 @@ export const TOOLS = [
                                 type: "string",
                                 description: "Past-tense evidence (APPLYING), scenario comparison (N_A), or risk acknowledgment (REFUTED). Minimum 50 characters.",
                             },
+                            relevance: {
+                                type: "string",
+                                enum: ["high", "low", "noise"],
+                                description: "How relevant was this scar to your plan? high=directly applicable, low=tangentially related, noise=not relevant to this context. Helps improve future recall quality.",
+                            },
                         },
                         required: ["scar_id", "decision", "evidence"],
                     },
@@ -76,12 +85,12 @@ export const TOOLS = [
             properties: {
                 agent_identity: {
                     type: "string",
-                    enum: ["CLI", "DAC", "CODA-1", "Brain_Local", "Brain_Cloud"],
+                    enum: ["cli", "desktop", "autonomous", "local", "cloud"],
                     description: "Override agent identity (auto-detects if not provided)",
                 },
                 linear_issue: {
                     type: "string",
-                    description: "Current Linear issue identifier (e.g., OD-XXX)",
+                    description: "Current Linear issue identifier (e.g., PROJ-123)",
                 },
                 issue_title: {
                     type: "string",
@@ -98,11 +107,11 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
                 force: {
                     type: "boolean",
-                    description: "Force create new session even if one already exists (OD-558)",
+                    description: "Force create new session even if one already exists",
                 },
             },
         },
@@ -210,7 +219,7 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
             },
             required: ["learning_type", "title", "description"],
@@ -259,7 +268,7 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
             },
             required: ["title", "decision", "rationale"],
@@ -273,7 +282,7 @@ export const TOOLS = [
             properties: {
                 scar_id: {
                     type: "string",
-                    description: "UUID of the scar from orchestra_learnings",
+                    description: "UUID of the scar",
                 },
                 issue_id: {
                     type: "string",
@@ -281,7 +290,7 @@ export const TOOLS = [
                 },
                 issue_identifier: {
                     type: "string",
-                    description: "Linear issue identifier (e.g., OD-XXX)",
+                    description: "Linear issue identifier (e.g., PROJ-123)",
                 },
                 surfaced_at: {
                     type: "string",
@@ -310,7 +319,7 @@ export const TOOLS = [
                 },
                 agent: {
                     type: "string",
-                    description: "Agent identity (CLI, DAC, CODA-1, etc.)",
+                    description: "Agent identity (e.g., cli, desktop, autonomous)",
                 },
                 variant_id: {
                     type: "string",
@@ -341,7 +350,7 @@ export const TOOLS = [
                             },
                             issue_identifier: {
                                 type: "string",
-                                description: "Linear issue identifier (e.g., OD-XXX)",
+                                description: "Linear issue identifier (e.g., PROJ-123)",
                             },
                             surfaced_at: {
                                 type: "string",
@@ -370,7 +379,7 @@ export const TOOLS = [
                             },
                             agent: {
                                 type: "string",
-                                description: "Agent identity (CLI, DAC, CODA-1, etc.)",
+                                description: "Agent identity (e.g., cli, desktop, autonomous)",
                             },
                         },
                         required: ["scar_identifier", "surfaced_at", "reference_type", "reference_context"],
@@ -387,7 +396,7 @@ export const TOOLS = [
     },
     {
         name: "save_transcript",
-        description: "Save full session transcript to storage for training data and post-mortems (OD-467)",
+        description: "Save full session transcript to storage for training data and post-mortems",
         inputSchema: {
             type: "object",
             properties: {
@@ -406,7 +415,7 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
             },
             required: ["session_id", "transcript"],
@@ -414,7 +423,7 @@ export const TOOLS = [
     },
     {
         name: "get_transcript",
-        description: "Retrieve a session transcript from storage (OD-467)",
+        description: "Retrieve a session transcript from storage",
         inputSchema: {
             type: "object",
             properties: {
@@ -446,14 +455,14 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace to filter by (e.g., 'orchestra_dev')",
+                    description: "Project namespace to filter by (e.g., 'my-project')",
                 },
             },
             required: ["query"],
         },
     },
     // ============================================================================
-    // SEARCH & LOG TOOLS (OD-560, OD-561)
+    // SEARCH & LOG TOOLS
     // ============================================================================
     {
         name: "search",
@@ -471,7 +480,7 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
                 severity: {
                     type: "string",
@@ -499,7 +508,7 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
                 learning_type: {
                     type: "string",
@@ -519,7 +528,7 @@ export const TOOLS = [
         },
     },
     // ============================================================================
-    // PREPARE CONTEXT (GitMem v2 Phase 1 — OD-593)
+    // PREPARE CONTEXT
     // ============================================================================
     {
         name: "prepare_context",
@@ -546,7 +555,7 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
             },
             required: ["plan", "format"],
@@ -583,7 +592,7 @@ export const TOOLS = [
             required: ["observations"],
         },
     },
-    // --- Thread Lifecycle Tools (OD-thread-lifecycle) ---
+    // --- Thread Lifecycle Tools () ---
     {
         name: "list_threads",
         description: "List open threads across recent sessions. Shows unresolved work items that carry over between sessions, with IDs for resolution. Use resolve_thread to mark threads as done.",
@@ -601,7 +610,7 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
             },
         },
@@ -639,7 +648,7 @@ export const TOOLS = [
                 },
                 linear_issue: {
                     type: "string",
-                    description: "Associated Linear issue (e.g., OD-XXX)",
+                    description: "Associated Linear issue (e.g., PROJ-123)",
                 },
             },
             required: ["text"],
@@ -658,7 +667,7 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
             },
             required: ["suggestion_id"],
@@ -687,7 +696,7 @@ export const TOOLS = [
             properties: {
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
                 auto_archive: {
                     type: "boolean",
@@ -726,7 +735,7 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
                 match_count: {
                     type: "number",
@@ -767,12 +776,12 @@ export const TOOLS = [
             properties: {
                 agent_identity: {
                     type: "string",
-                    enum: ["CLI", "DAC", "CODA-1", "Brain_Local", "Brain_Cloud"],
+                    enum: ["cli", "desktop", "autonomous", "local", "cloud"],
                     description: "Override agent identity (auto-detects if not provided)",
                 },
                 linear_issue: {
                     type: "string",
-                    description: "Current Linear issue identifier (e.g., OD-XXX)",
+                    description: "Current Linear issue identifier (e.g., PROJ-123)",
                 },
                 issue_title: {
                     type: "string",
@@ -789,11 +798,11 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
                 force: {
                     type: "boolean",
-                    description: "Force create new session even if one already exists (OD-558)",
+                    description: "Force create new session even if one already exists",
                 },
             },
         },
@@ -901,7 +910,7 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
             },
             required: ["learning_type", "title", "description"],
@@ -950,7 +959,7 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
             },
             required: ["title", "decision", "rationale"],
@@ -964,7 +973,7 @@ export const TOOLS = [
             properties: {
                 scar_id: {
                     type: "string",
-                    description: "UUID of the scar from orchestra_learnings",
+                    description: "UUID of the scar",
                 },
                 issue_id: {
                     type: "string",
@@ -972,7 +981,7 @@ export const TOOLS = [
                 },
                 issue_identifier: {
                     type: "string",
-                    description: "Linear issue identifier (e.g., OD-XXX)",
+                    description: "Linear issue identifier (e.g., PROJ-123)",
                 },
                 surfaced_at: {
                     type: "string",
@@ -1001,7 +1010,7 @@ export const TOOLS = [
                 },
                 agent: {
                     type: "string",
-                    description: "Agent identity (CLI, DAC, CODA-1, etc.)",
+                    description: "Agent identity (e.g., cli, desktop, autonomous)",
                 },
                 variant_id: {
                     type: "string",
@@ -1032,7 +1041,7 @@ export const TOOLS = [
                             },
                             issue_identifier: {
                                 type: "string",
-                                description: "Linear issue identifier (e.g., OD-XXX)",
+                                description: "Linear issue identifier (e.g., PROJ-123)",
                             },
                             surfaced_at: {
                                 type: "string",
@@ -1061,7 +1070,7 @@ export const TOOLS = [
                             },
                             agent: {
                                 type: "string",
-                                description: "Agent identity (CLI, DAC, CODA-1, etc.)",
+                                description: "Agent identity (e.g., cli, desktop, autonomous)",
                             },
                         },
                         required: ["scar_identifier", "surfaced_at", "reference_type", "reference_context"],
@@ -1097,7 +1106,7 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
             },
             required: ["session_id", "transcript"],
@@ -1170,7 +1179,7 @@ export const TOOLS = [
             required: ["query"],
         },
     },
-    // gitmem-search (OD-560)
+    // gitmem-search
     {
         name: "gitmem-search",
         description: "gitmem-search (search) - Search institutional memory by query (exploration, no side effects)",
@@ -1187,7 +1196,7 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
                 severity: {
                     type: "string",
@@ -1203,7 +1212,7 @@ export const TOOLS = [
             required: ["query"],
         },
     },
-    // gitmem-log (OD-561)
+    // gitmem-log
     {
         name: "gitmem-log",
         description: "gitmem-log (log) - List recent learnings chronologically",
@@ -1216,7 +1225,7 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
                 learning_type: {
                     type: "string",
@@ -1235,7 +1244,7 @@ export const TOOLS = [
             },
         },
     },
-    // gitmem-pc (prepare_context) — OD-593
+    // gitmem-pc (prepare_context)
     {
         name: "gitmem-pc",
         description: "gitmem-pc (prepare_context) - Generate portable memory payload for sub-agent injection",
@@ -1261,7 +1270,7 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
             },
             required: ["plan", "format"],
@@ -1293,7 +1302,7 @@ export const TOOLS = [
             required: ["observations"],
         },
     },
-    // gitmem-lt (list_threads) — OD-thread-lifecycle
+    // gitmem-lt (list_threads) — 
     {
         name: "gitmem-lt",
         description: "gitmem-lt (list_threads) - List open threads across sessions",
@@ -1306,7 +1315,7 @@ export const TOOLS = [
             },
         },
     },
-    // gitmem-rt (resolve_thread) — OD-thread-lifecycle
+    // gitmem-rt (resolve_thread) — 
     {
         name: "gitmem-rt",
         description: "gitmem-rt (resolve_thread) - Mark a thread as resolved",
@@ -1391,12 +1400,12 @@ export const TOOLS = [
             properties: {
                 agent_identity: {
                     type: "string",
-                    enum: ["CLI", "DAC", "CODA-1", "Brain_Local", "Brain_Cloud"],
+                    enum: ["cli", "desktop", "autonomous", "local", "cloud"],
                     description: "Override agent identity (auto-detects if not provided)",
                 },
                 linear_issue: {
                     type: "string",
-                    description: "Current Linear issue identifier (e.g., OD-XXX)",
+                    description: "Current Linear issue identifier (e.g., PROJ-123)",
                 },
                 issue_title: {
                     type: "string",
@@ -1413,11 +1422,11 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
                 force: {
                     type: "boolean",
-                    description: "Force create new session even if one already exists (OD-558)",
+                    description: "Force create new session even if one already exists",
                 },
             },
         },
@@ -1548,13 +1557,13 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
             },
             required: ["learning_type", "title", "description"],
         },
     },
-    // gm-search (OD-560)
+    // gm-search
     {
         name: "gm-search",
         description: "gm-search (search) - Search institutional memory by query",
@@ -1571,7 +1580,7 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
                 severity: {
                     type: "string",
@@ -1587,7 +1596,7 @@ export const TOOLS = [
             required: ["query"],
         },
     },
-    // gm-log (OD-561)
+    // gm-log
     {
         name: "gm-log",
         description: "gm-log (log) - List recent learnings chronologically",
@@ -1600,7 +1609,7 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
                 learning_type: {
                     type: "string",
@@ -1619,7 +1628,7 @@ export const TOOLS = [
             },
         },
     },
-    // gm-pc (prepare_context) — OD-593
+    // gm-pc (prepare_context)
     {
         name: "gm-pc",
         description: "gm-pc (prepare_context) - Generate portable memory payload for sub-agents",
@@ -1645,7 +1654,7 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
             },
             required: ["plan", "format"],
@@ -1677,7 +1686,7 @@ export const TOOLS = [
             required: ["observations"],
         },
     },
-    // gm-threads (list_threads) — OD-thread-lifecycle
+    // gm-threads (list_threads) — 
     {
         name: "gm-threads",
         description: "gm-threads (list_threads) - List open threads",
@@ -1690,7 +1699,7 @@ export const TOOLS = [
             },
         },
     },
-    // gm-resolve (resolve_thread) — OD-thread-lifecycle
+    // gm-resolve (resolve_thread) — 
     {
         name: "gm-resolve",
         description: "gm-resolve (resolve_thread) - Resolve a thread",
@@ -1765,7 +1774,7 @@ export const TOOLS = [
         },
     },
     // ============================================================================
-    // ANALYTICS TOOLS (OD-567)
+    // ANALYTICS TOOLS
     // ============================================================================
     {
         name: "analyze",
@@ -1784,11 +1793,11 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
                 agent: {
                     type: "string",
-                    description: "Filter by agent identity (e.g., CLI, DAC, CODA-1)",
+                    description: "Filter by agent identity (e.g., cli, desktop, autonomous)",
                 },
                 format: {
                     type: "string",
@@ -1798,7 +1807,7 @@ export const TOOLS = [
             },
         },
     },
-    // gitmem-analyze alias (OD-567)
+    // gitmem-analyze alias
     {
         name: "gitmem-analyze",
         description: "gitmem-analyze (analyze) - Session analytics. Returns formatted markdown by default.",
@@ -1816,11 +1825,11 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
                 agent: {
                     type: "string",
-                    description: "Filter by agent identity (e.g., CLI, DAC, CODA-1)",
+                    description: "Filter by agent identity (e.g., cli, desktop, autonomous)",
                 },
                 format: {
                     type: "string",
@@ -1830,7 +1839,7 @@ export const TOOLS = [
             },
         },
     },
-    // gm-analyze ultra-short alias (OD-567)
+    // gm-analyze ultra-short alias
     {
         name: "gm-analyze",
         description: "gm-analyze (analyze) - Session analytics. Returns formatted markdown by default.",
@@ -1848,11 +1857,11 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
                 agent: {
                     type: "string",
-                    description: "Filter by agent identity (e.g., CLI, DAC, CODA-1)",
+                    description: "Filter by agent identity (e.g., cli, desktop, autonomous)",
                 },
                 format: {
                     type: "string",
@@ -1871,7 +1880,7 @@ export const TOOLS = [
         },
     },
     // ============================================================================
-    // CACHE MANAGEMENT TOOLS (OD-473)
+    // CACHE MANAGEMENT TOOLS
     // ============================================================================
     {
         name: "gitmem-cache-status",
@@ -1881,7 +1890,7 @@ export const TOOLS = [
             properties: {
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
             },
         },
@@ -1894,7 +1903,7 @@ export const TOOLS = [
             properties: {
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
             },
         },
@@ -1907,7 +1916,7 @@ export const TOOLS = [
             properties: {
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
             },
         },
@@ -1920,7 +1929,7 @@ export const TOOLS = [
             properties: {
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
             },
         },
@@ -1933,7 +1942,7 @@ export const TOOLS = [
             properties: {
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
             },
         },
@@ -1946,7 +1955,7 @@ export const TOOLS = [
             properties: {
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
             },
         },
@@ -1964,7 +1973,7 @@ export const TOOLS = [
                 },
                 reason: {
                     type: "string",
-                    description: "Optional reason for archiving (e.g., 'superseded by OD-XXX', 'no longer relevant')",
+                    description: "Optional reason for archiving (e.g., 'superseded by PROJ-123', 'no longer relevant')",
                 },
             },
             required: ["id"],
@@ -2009,7 +2018,7 @@ export const TOOLS = [
     // --- Knowledge Graph Traversal (Phase 3) ---
     {
         name: "graph_traverse",
-        description: "Traverse the knowledge graph over institutional memory triples. Answers: 'show me everything connected to OD-466', 'what did CLI produce', 'trace this decision back', 'which issues produced the most learnings'. Four lenses: connected_to, produced_by, provenance, stats.",
+        description: "Traverse the knowledge graph over institutional memory triples. Answers: 'show me everything connected to this issue', 'what did this agent produce', 'trace this decision back', 'which issues produced the most learnings'. Four lenses: connected_to, produced_by, provenance, stats.",
         inputSchema: {
             type: "object",
             properties: {
@@ -2020,7 +2029,7 @@ export const TOOLS = [
                 },
                 node: {
                     type: "string",
-                    description: "Starting node. Examples: 'OD-466', 'CLI', 'Elena', 'Scar: Done ≠ Deployed'. Required for all lenses except stats.",
+                    description: "Starting node. Examples: 'PROJ-123', 'cli', 'Scar: Done ≠ Deployed'. Required for all lenses except stats.",
                 },
                 predicate: {
                     type: "string",
@@ -2033,7 +2042,7 @@ export const TOOLS = [
                 },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
                 limit: {
                     type: "number",
@@ -2056,7 +2065,7 @@ export const TOOLS = [
                 },
                 node: {
                     type: "string",
-                    description: "Starting node (e.g., 'OD-466', 'CLI', 'Elena')",
+                    description: "Starting node (e.g., 'PROJ-123', 'cli')",
                 },
                 predicate: {
                     type: "string",
@@ -2066,7 +2075,7 @@ export const TOOLS = [
                 depth: { type: "number", description: "Max depth for provenance (default: 3)" },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
                 limit: { type: "number", description: "Max triples (default: 50)" },
             },
@@ -2093,7 +2102,7 @@ export const TOOLS = [
                 depth: { type: "number", description: "Max depth for provenance" },
                 project: {
                     type: "string",
-                    description: "Project namespace (e.g., 'my-project', 'orchestra_dev'). Scopes sessions and searches.",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
                 },
                 limit: { type: "number", description: "Max triples" },
             },
@@ -2101,6 +2110,30 @@ export const TOOLS = [
         },
     },
 ];
+/**
+ * Alias tool names — filtered out by default to reduce context window cost.
+ * Set GITMEM_FULL_ALIASES=1 to advertise all aliases.
+ * Aliases still route correctly in server.ts even when not advertised.
+ */
+export const ALIAS_TOOL_NAMES = new Set([
+    // gitmem-* aliases
+    "gitmem-r", "gitmem-cs", "gitmem-ss", "gitmem-sr", "gitmem-sc",
+    "gitmem-cl", "gitmem-cd", "gitmem-rs", "gitmem-rsb",
+    "gitmem-st", "gitmem-gt", "gitmem-stx",
+    "gitmem-search", "gitmem-log", "gitmem-analyze",
+    "gitmem-pc", "gitmem-ao",
+    "gitmem-lt", "gitmem-rt", "gitmem-ct", "gitmem-ps", "gitmem-ds",
+    "gitmem-cleanup", "gitmem-health", "gitmem-al", "gitmem-graph",
+    // gm-* aliases
+    "gm-open", "gm-confirm", "gm-refresh", "gm-close",
+    "gm-scar", "gm-search", "gm-log", "gm-analyze",
+    "gm-pc", "gm-absorb",
+    "gm-threads", "gm-resolve", "gm-thread-new", "gm-promote", "gm-dismiss",
+    "gm-cleanup", "gm-health", "gm-archive", "gm-graph",
+    "gm-stx",
+    // gm-cache-* aliases (canonical names are gitmem-cache-*, tier-gated separately)
+    "gm-cache-s", "gm-cache-h", "gm-cache-f",
+]);
 /**
  * Tier-gated tool names
  *
@@ -2136,7 +2169,12 @@ export const ARCHIVE_TOOL_NAMES = new Set([
  * Dev: + batch operations + transcripts
  */
 export function getRegisteredTools() {
+    const showAliases = hasFullAliases();
     return TOOLS.filter(tool => {
+        // Filter aliases unless GITMEM_FULL_ALIASES=1
+        if (!showAliases && ALIAS_TOOL_NAMES.has(tool.name)) {
+            return false;
+        }
         if (BATCH_TOOL_NAMES.has(tool.name)) {
             return hasBatchOperations();
         }
@@ -2152,7 +2190,9 @@ export function getRegisteredTools() {
         if (GRAPH_TOOL_NAMES.has(tool.name)) {
             return hasSupabase();
         }
-        if (ARCHIVE_TOOL_NAMES.has(tool.name)) {
+        // archive_learning works on both free (local JSON) and pro (Supabase) tiers
+        // Only gate the aliases
+        if (ARCHIVE_TOOL_NAMES.has(tool.name) && tool.name !== "archive_learning") {
             return hasSupabase();
         }
         return true;