memoryai-mcp 2.2.0 → 2.3.1

package/dist/index.js

@@ -8,13 +8,46 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-const API_URL = process.env.HM_ENDPOINT || "http://localhost:8420";
-const API_KEY = process.env.HM_API_KEY || "";
+const API_URL = process.env.MEMORYAI_ENDPOINT || process.env.HM_ENDPOINT || "http://localhost:8420";
+const API_KEY = process.env.MEMORYAI_API_KEY || process.env.HM_API_KEY || "";
 const REQUEST_TIMEOUT_MS = 30_000; // P2 #6: 30s default timeout for API requests
-// Context Guard — per-IDE settings via env vars
-const CG_CONTEXT_CAP = parseInt(process.env.HM_CONTEXT_CAP || "0", 10); // IDE's context window (0 = let server detect)
-const CG_COMPACT_PCT = parseInt(process.env.HM_COMPACT_AT || "0", 10); // % to warn (e.g. 30 = 30%)
-const CG_CRITICAL_PCT = parseInt(process.env.HM_CRITICAL_AT || "0", 10); // % to force compact (e.g. 50 = 50%)
+// Context Guard — per-IDE settings via env vars.
+// HM_COMPACT_AT and HM_CRITICAL_AT are now ABSOLUTE token counts (e.g. "100000",
+// "150000"). The legacy meaning ("30" = 30%) is detected automatically: any
+// value < 1000 is treated as a deprecated percentage and converted to absolute
+// using HM_CONTEXT_CAP if present, otherwise the value is sent as-is and the
+// server interprets it as a fraction (backward-compat path).
+//
+// HM_CONTEXT_CAP itself is no longer required — users set the two thresholds
+// directly. When present it is forwarded as max_tokens so the server can clamp.
+const CG_CONTEXT_CAP = parseInt(process.env.MEMORYAI_CONTEXT_CAP || process.env.HM_CONTEXT_CAP || "0", 10);
+const CG_COMPACT_RAW = parseInt(process.env.MEMORYAI_COMPACT_AT || process.env.HM_COMPACT_AT || "0", 10);
+const CG_CRITICAL_RAW = parseInt(process.env.MEMORYAI_CRITICAL_AT || process.env.HM_CRITICAL_AT || "0", 10);
+// Heuristic: small numbers are legacy percentages; large numbers are absolute tokens.
+// Threshold "<= 100" is generous enough to catch any sensible % (max 95%) and
+// well below any sensible absolute count (min would be ~10K tokens).
+function _isLegacyPct(v) { return v > 0 && v <= 100; }
+// Resolved absolute thresholds. 0 means "not configured — use server defaults".
+const CG_COMPACT_AT_TOKENS = (() => {
+    if (CG_COMPACT_RAW <= 0)
+        return 0;
+    if (_isLegacyPct(CG_COMPACT_RAW) && CG_CONTEXT_CAP > 0) {
+        return Math.round((CG_COMPACT_RAW / 100) * CG_CONTEXT_CAP);
+    }
+    return _isLegacyPct(CG_COMPACT_RAW) ? 0 : CG_COMPACT_RAW;
+})();
+const CG_CRITICAL_AT_TOKENS = (() => {
+    if (CG_CRITICAL_RAW <= 0)
+        return 0;
+    if (_isLegacyPct(CG_CRITICAL_RAW) && CG_CONTEXT_CAP > 0) {
+        return Math.round((CG_CRITICAL_RAW / 100) * CG_CONTEXT_CAP);
+    }
+    return _isLegacyPct(CG_CRITICAL_RAW) ? 0 : CG_CRITICAL_RAW;
+})();
+// Legacy decimal % path for the rare case where user keeps "30/50" without
+// HM_CONTEXT_CAP — server still accepts compact_pct/critical_pct as decimals.
+const CG_COMPACT_PCT = _isLegacyPct(CG_COMPACT_RAW) && CG_CONTEXT_CAP <= 0 ? CG_COMPACT_RAW : 0;
+const CG_CRITICAL_PCT = _isLegacyPct(CG_CRITICAL_RAW) && CG_CONTEXT_CAP <= 0 ? CG_CRITICAL_RAW : 0;
 // --- HTTP helper ---
 async function api(method, path, body) {
     const resp = await fetch(`${API_URL}${path}`, {
@@ -40,9 +73,9 @@ function err(e) {
     return { content: [{ type: "text", text: `Error: ${msg}` }], isError: true };
 }
 // --- MCP Server ---
-const server = new McpServer({ name: "memoryai", version: "1.0.0" }, { capabilities: { tools: {} } });
+const server = new McpServer({ name: "memoryai", version: "2.3.0" }, { capabilities: { tools: {} } });
 // 1. memory_store
-server.tool("memory_store", "Store information in persistent memory. Use when you learn something important — project context, user preferences, architectural decisions, patterns, bugs, pricing/cost discussions, business plans, financial calculations, credit/billing info, revenue models, partnership details, or ANY information the user might ask about later. When in doubt, STORE — MemoryAI handles dedup automatically, so storing too much is always better than forgetting.", {
+server.tool("memory_store", "[CORE] Store information in persistent memory. Use when you learn something important — project context, user preferences, architectural decisions, patterns, bugs, pricing/cost discussions, business plans, or ANY information the user might ask about later. When in doubt, STORE — dedup is automatic.", {
     content: z.string().describe("What to remember"),
     source: z.string().optional().describe("Source context (e.g. file path, conversation)"),
     tags: z.array(z.string()).optional().describe("Categories: preferences, architecture, bugs, patterns, decisions"),
@@ -87,7 +120,7 @@ server.tool("memory_store", "Store information in persistent memory. Use when yo
     }
 });
 // 2. memory_recall
-server.tool("memory_recall", "Search persistent memory for relevant context. Use before starting work to check what you already know about the project or task.", {
+server.tool("memory_recall", "[CORE] Search persistent memory for relevant context. Use BEFORE starting work to check what you already know about the project, user preferences, or past decisions.", {
     query: z.string().describe("What to search for"),
     depth: z.enum(["fast", "instant", "deep", "exhaustive"]).optional().describe("Search depth. 'instant'=vector only (~50ms), 'fast'=FTS only, 'deep'=full fusion (default), 'exhaustive'=deep+more results"),
     limit: z.number().optional().describe("Max results (default: 5)"),
@@ -129,7 +162,7 @@ server.tool("memory_recall", "Search persistent memory for relevant context. Use
     }
 });
 // 3. memory_stats
-server.tool("memory_stats", "Get memory usage statistics — chunk count, storage size, monthly usage.", {}, async () => {
+server.tool("memory_stats", "Advanced: Get memory usage statistics — chunk count, storage size, monthly usage.", {}, async () => {
     try {
         const r = (await api("GET", "/v1/stats"));
         return ok(`Memory Stats:\n` +
@@ -143,7 +176,7 @@ server.tool("memory_stats", "Get memory usage statistics — chunk count, storag
     }
 });
 // 4. memory_compact
-server.tool("memory_compact", "Compact long text into memory chunks for long-term storage. Use at end of session or when context is getting large.", {
+server.tool("memory_compact", "Advanced: Compact long text into memory chunks for long-term storage. Use at end of session or when context is getting large.", {
     content: z.string().describe("Text content to compact"),
     task_context: z.string().optional().describe("Brief description of the task/session"),
     content_type: z.enum(["conversation", "code"]).optional().describe("Content type"),
@@ -186,7 +219,7 @@ server.tool("memory_compact", "Compact long text into memory chunks for long-ter
     }
 });
 // 5. context_check
-server.tool("context_check", "Check current context token usage and urgency level.", {
+server.tool("context_check", "Advanced: Check current context token usage and urgency level.", {
     content_type: z.enum(["conversation", "code"]).optional().describe("Check conversation or code context"),
 }, async (args) => {
     try {
@@ -203,7 +236,7 @@ server.tool("context_check", "Check current context token usage and urgency leve
     }
 });
 // 6. context_restore
-server.tool("context_restore", "Restore context for a task by recalling the most relevant memory chunks.", {
+server.tool("context_restore", "Advanced: Restore context for a task by recalling the most relevant memory chunks.", {
     task_description: z.string().describe("Description of the task to restore context for"),
     limit: z.number().optional().describe("Max chunks to restore (default: 5)"),
 }, async (args) => {
@@ -224,7 +257,7 @@ server.tool("context_restore", "Restore context for a task by recalling the most
     }
 });
 // 7. project_index
-server.tool("project_index", "Index a code project's file tree and key files into memory. IDE use only.", {
+server.tool("project_index", "Advanced: Index a code project's file tree and key files into memory. IDE use only.", {
     file_tree: z.array(z.string()).describe("List of file paths in the project"),
     key_files: z.record(z.string(), z.string()).optional().describe("Map of file_path → file_content for important files"),
     git_info: z.record(z.string(), z.unknown()).optional().describe("Git metadata (branch, remote, last commit)"),
@@ -251,7 +284,7 @@ server.tool("project_index", "Index a code project's file tree and key files int
 // 8. collective_contribute
 server.tool(
   "collective_contribute",
-  "Contribute knowledge to the collective memory pool. Requires opt-in. Content is anonymized before storage. Use for sharing bug fixes, patterns, decisions that could help other developers.",
+  "Advanced: Contribute knowledge to the collective memory pool. Requires opt-in. Content is anonymized before storage. Use for sharing bug fixes, patterns, decisions that could help other developers.",
   {
     content: z.string().describe("Knowledge to contribute (will be anonymized)"),
     content_type: z.enum(["bug_fix", "pattern", "decision", "migration", "tip", "performance", "security"]).optional().describe("Type of knowledge (default: bug_fix)"),
@@ -281,7 +314,7 @@ server.tool(
 // 9. collective_recall
 server.tool(
   "collective_recall",
-  "Search the collective knowledge pool for solutions, patterns, and tips from the developer community. Free for all users.",
+  "Advanced: Search the collective knowledge pool for solutions, patterns, and tips from the developer community. Free for all users.",
   {
     query: z.string().describe("What to search for"),
     depth: z.enum(["fast", "deep"]).optional().describe("Search depth (default: deep)"),
@@ -314,7 +347,7 @@ server.tool(
 // 10. collective_confirm
 server.tool(
   "collective_confirm",
-  "Confirm whether a collective solution worked or not. Helps improve confidence scores.",
+  "Advanced: Confirm whether a collective solution worked or not. Helps improve confidence scores.",
   {
     collective_chunk_id: z.number().describe("ID of the collective chunk to confirm"),
     worked: z.boolean().describe("Did the solution work? true/false"),
@@ -337,7 +370,7 @@ server.tool(
 // 11. collective_stats
 server.tool(
   "collective_stats",
-  "Get statistics about the collective knowledge pool.",
+  "Advanced: Get statistics about the collective knowledge pool.",
   {},
   async () => {
     try {
@@ -357,7 +390,7 @@ server.tool(
 );
 */
 // 12. l2_store
-server.tool("reasoning_store", "Store content in a reasoning bank. Reasoning banks hold context for deep analysis. Requires Pro plan or higher.", {
+server.tool("reasoning_store", "Advanced: Store content in a reasoning bank. Reasoning banks hold context for deep analysis. Requires Pro plan or higher.", {
     bank_name: z.string().describe("Name of the L2 bank"),
     content: z.string().describe("Content to store in the bank"),
     token_count: z.number().optional().describe("Approximate token count of the content"),
@@ -375,7 +408,7 @@ server.tool("reasoning_store", "Store content in a reasoning bank. Reasoning ban
     }
 });
 // 13. l2_recall
-server.tool("reasoning_recall", "Recall from reasoning banks via deep analysis. Requires Pro plan or higher.", {
+server.tool("reasoning_recall", "Advanced: Recall from reasoning banks via deep analysis. Requires Pro plan or higher.", {
     query: z.string().describe("Question to answer using L2 bank context"),
     bank_names: z.array(z.string()).optional().describe("Specific banks to search (default: all)"),
 }, async (args) => {
@@ -393,7 +426,7 @@ server.tool("reasoning_recall", "Recall from reasoning banks via deep analysis.
     }
 });
 // 14. l2_compress
-server.tool("reasoning_compress", "Compress old reasoning bank entries into a digest. Reduces storage while preserving key information.", {
+server.tool("reasoning_compress", "Advanced: Compress old reasoning bank entries into a digest. Reduces storage while preserving key information.", {
     bank_name: z.string().describe("Name of the L2 bank to compress"),
 }, async (args) => {
     try {
@@ -409,7 +442,7 @@ server.tool("reasoning_compress", "Compress old reasoning bank entries into a di
     }
 });
 // 15. l2_stats
-server.tool("reasoning_stats", "Get reasoning layer statistics — bank sizes, usage, and plan limits.", {}, async () => {
+server.tool("reasoning_stats", "Advanced: Get reasoning layer statistics — bank sizes, usage, and plan limits.", {}, async () => {
     try {
         const r = (await api("GET", "/v1/l2/stats"));
         const bankList = (r.banks || [])
@@ -425,7 +458,7 @@ server.tool("reasoning_stats", "Get reasoning layer statistics — bank sizes, u
     }
 });
 // 16. entity_list
-server.tool("entity_list", "List tracked entities (files, URLs, people, packages, code symbols) extracted from stored memories.", {
+server.tool("entity_list", "Advanced: List tracked entities (files, URLs, people, packages, code symbols) extracted from stored memories.", {
     entity_type: z.string().optional().describe("Filter by type: file, url, person, package, code_symbol"),
     limit: z.number().optional().describe("Max results (default: 50)"),
 }, async (args) => {
@@ -449,7 +482,7 @@ server.tool("entity_list", "List tracked entities (files, URLs, people, packages
     }
 });
 // 17. entity_search
-server.tool("entity_search", "Find memory chunks linked to a specific entity by name.", {
+server.tool("entity_search", "Advanced: Find memory chunks linked to a specific entity by name.", {
     name: z.string().describe("Entity name to search for"),
     limit: z.number().optional().describe("Max chunk IDs to return (default: 20)"),
 }, async (args) => {
@@ -465,7 +498,7 @@ server.tool("entity_search", "Find memory chunks linked to a specific entity by
     }
 });
 // 18. learn
-server.tool("learn", "Store an action, its result, and lesson learned. Use after completing tasks, fixing bugs, or making decisions to build action memory.", {
+server.tool("learn", "Advanced: Store an action, its result, and lesson learned. Use after completing tasks, fixing bugs, or making decisions to build action memory.", {
     action: z.string().describe("What was done"),
     result: z.string().describe("What happened"),
     outcome: z.enum(["success", "failure", "partial"]).optional().describe("Outcome (default: success)"),
@@ -491,7 +524,7 @@ server.tool("learn", "Store an action, its result, and lesson learned. Use after
 // 12. collective_shards
 server.tool(
   "collective_shards",
-  "List all domain shards in the collective knowledge pool with chunk counts.",
+  "Advanced: List all domain shards in the collective knowledge pool with chunk counts.",
   {},
   async () => {
     try {
@@ -508,7 +541,7 @@ server.tool(
 // 13. collective_synthesize
 server.tool(
   "collective_synthesize",
-  "Trigger knowledge card synthesis from collective chunks. Groups similar chunks and creates merged knowledge cards. Admin operation.",
+  "Advanced: Trigger knowledge card synthesis from collective chunks. Groups similar chunks and creates merged knowledge cards. Admin operation.",
   {},
   async () => {
     try {
@@ -530,7 +563,7 @@ server.tool(
 // 14. pool_stats
 server.tool(
   "pool_stats",
-  "Get content pool dedup statistics — pool size, ref count, dedup ratio, and estimated savings.",
+  "Advanced: Get content pool dedup statistics — pool size, ref count, dedup ratio, and estimated savings.",
   {},
   async () => {
     try {
@@ -549,7 +582,7 @@ server.tool(
 */
 // --- Start ---
 // 16. memory_recover
-server.tool("memory_recover", "Recover session context from recent memory. Use when resuming work after a break to quickly understand what was happening — active files, pending tasks, timeline, and key references.", {
+server.tool("memory_recover", "Advanced: Recover session context from recent memory. Use when resuming work after a break to quickly understand what was happening — active files, pending tasks, timeline, and key references.", {
     task_context: z.string().optional().describe("Hint about what you were working on"),
     time_range_hours: z.number().optional().describe("Look back N hours (default: 24)"),
     max_tokens: z.number().optional().describe("Token budget for response (default: 8000)"),
@@ -579,7 +612,7 @@ server.tool("memory_recover", "Recover session context from recent memory. Use w
     }
 });
 // 17. memory_health
-server.tool("memory_health", "Check context window health — usage percentage, compaction recommendation, and memory freshness stats.", {
+server.tool("memory_health", "Advanced: Check context window health — usage percentage, compaction recommendation, and memory freshness stats.", {
     current_tokens: z.number().describe("Current token count in context window"),
     max_tokens: z.number().optional().describe("Max context window size (default: 200000)"),
 }, async (args) => {
@@ -604,7 +637,7 @@ server.tool("memory_health", "Check context window health — usage percentage,
     }
 });
 // 18. memory_health_detailed
-server.tool("memory_health_detailed", "Get detailed memory health — chunk distribution, stale chunk count, entity stats, and actionable recommendations.", {}, async () => {
+server.tool("memory_health_detailed", "Advanced: Get detailed memory health — chunk distribution, stale chunk count, entity stats, and actionable recommendations.", {}, async () => {
     try {
         const r = (await api("GET", "/v1/health/detailed"));
         const recs = (r.recommendations || []).map((rec) => `  ⚠ ${rec}`).join("\n");
@@ -622,7 +655,7 @@ server.tool("memory_health_detailed", "Get detailed memory health — chunk dist
     }
 });
 // 19. snapshot_create
-server.tool("snapshot_create", "Create a snapshot backup of all current memory chunks. Use before risky operations.", {}, async () => {
+server.tool("snapshot_create", "Advanced: Create a snapshot backup of all current memory chunks. Use before risky operations.", {}, async () => {
     try {
         const r = (await api("POST", "/v1/snapshots/create"));
         return ok(`Snapshot created (id=${r.snapshot_id}): ${r.chunks_count} chunks, ${r.size_bytes} bytes`);
@@ -632,7 +665,7 @@ server.tool("snapshot_create", "Create a snapshot backup of all current memory c
     }
 });
 // 19. snapshot_list
-server.tool("snapshot_list", "List all available memory snapshots.", {}, async () => {
+server.tool("snapshot_list", "Advanced: List all available memory snapshots.", {}, async () => {
     try {
         const r = (await api("GET", "/v1/snapshots"));
         if (!r.snapshots?.length)
@@ -647,7 +680,7 @@ server.tool("snapshot_list", "List all available memory snapshots.", {}, async (
     }
 });
 // 20. snapshot_restore
-server.tool("snapshot_restore", "Restore memory from a snapshot. Current chunks will be soft-deleted and replaced.", {
+server.tool("snapshot_restore", "Advanced: Restore memory from a snapshot. Current chunks will be soft-deleted and replaced.", {
     snapshot_id: z.string().describe("Snapshot ID to restore from"),
 }, async (args) => {
     try {
@@ -659,7 +692,7 @@ server.tool("snapshot_restore", "Restore memory from a snapshot. Current chunks
     }
 });
 // 21. memory_bootstrap
-server.tool("memory_bootstrap", "Get a ready-to-use context block at session start. Automatically assembles preferences, recent activity, project context, and key entities. Call this at the beginning of every session instead of manual recalls.", {
+server.tool("memory_bootstrap", "[CORE] Load context at session start — call this FIRST in every new session. Returns preferences, recent activity, project context, and key entities as a ready-to-use block.", {
     task_description: z.string().optional().describe("What you're about to work on"),
     project_name: z.string().optional().describe("Project name to focus on"),
     max_tokens: z.number().optional().describe("Token budget for context block (default: 4000)"),
@@ -685,7 +718,7 @@ server.tool("memory_bootstrap", "Get a ready-to-use context block at session sta
     }
 });
 // 22. memory_explore
-server.tool("memory_explore", "Explore memory connections — find chunks related to a specific memory. Reveals hidden connections and associations.", {
+server.tool("memory_explore", "Advanced: Explore memory connections — find chunks related to a specific memory. Reveals hidden connections and associations.", {
     chunk_id: z.number().describe("ID of the memory chunk to explore from"),
     limit: z.number().optional().describe("Max neighbors to return (default: 10)"),
 }, async (args) => {
@@ -707,7 +740,7 @@ server.tool("memory_explore", "Explore memory connections — find chunks relate
     }
 });
 // 23. memory_clusters
-server.tool("memory_clusters", "View memory topic clusters — groups of related memories organized by topic. Useful for understanding what topics are stored.", {
+server.tool("memory_clusters", "Advanced: View memory topic clusters — groups of related memories organized by topic. Useful for understanding what topics are stored.", {
     limit: z.number().optional().describe("Max clusters to return (default: 20)"),
 }, async (args) => {
     try {
@@ -724,7 +757,7 @@ server.tool("memory_clusters", "View memory topic clusters — groups of related
     }
 });
 // 24. session_handoff_start
-server.tool("session_handoff_start", "Start a session handoff — save old session conversation to MemoryAI server for new session to read. Use when context window is filling up and you need to switch sessions without losing context.", {
+server.tool("session_handoff_start", "Advanced: Start a session handoff — save old session conversation to MemoryAI server for new session to read. Use when context window is filling up and you need to switch sessions without losing context.", {
     conversation: z.array(z.object({
         role: z.string().describe("Message role: user, assistant, system"),
         content: z.string().describe("Message content"),
@@ -744,7 +777,7 @@ server.tool("session_handoff_start", "Start a session handoff — save old sessi
     }
 });
 // 25. session_handoff_restore
-server.tool("session_handoff_restore", "Restore old session conversation + related MemoryAI memories for a new session. Call this at the start of a new session to pick up where the old session left off — zero context loss.", {
+server.tool("session_handoff_restore", "Advanced: Restore old session conversation + related MemoryAI memories for a new session. Call this at the start of a new session to pick up where the old session left off — zero context loss.", {
     handoff_id: z.string().optional().describe("Specific handoff ID, or omit for latest"),
     include_memories: z.boolean().optional().describe("Also include related MemoryAI memories (default: true)"),
     memory_limit: z.number().optional().describe("Max related memories to include (default: 5)"),
@@ -775,7 +808,7 @@ server.tool("session_handoff_restore", "Restore old session conversation + relat
     }
 });
 // 26. session_handoff_complete
-server.tool("session_handoff_complete", "Complete a session handoff — archive old session conversation into long-term MemoryAI storage. Call this when the new session has enough context (e.g., after working for a while).", {
+server.tool("session_handoff_complete", "Advanced: Complete a session handoff — archive old session conversation into long-term MemoryAI storage. Call this when the new session has enough context (e.g., after working for a while).", {
     handoff_id: z.string().optional().describe("Specific handoff ID, or omit for latest"),
     archive_to_memory: z.boolean().optional().describe("Store old conversation as MemoryAI chunks (default: true)"),
 }, async (args) => {
@@ -795,7 +828,7 @@ server.tool("session_handoff_complete", "Complete a session handoff — archive
     }
 });
 // 27. session_handoff_status
-server.tool("session_handoff_status", "Check current session handoff status — whether there's a pending handoff and its state.", {}, async () => {
+server.tool("session_handoff_status", "Advanced: Check current session handoff status — whether there's a pending handoff and its state.", {}, async () => {
     try {
         const r = (await api("GET", "/v1/session/handoff/status"));
         if (!r.handoff_id)
@@ -816,7 +849,7 @@ server.tool("session_handoff_status", "Check current session handoff status —
 });
 // ─── Context Guard v6 Tools ─────────────────────────────────────────
 // context_guard_check — universal guard check with DNA count
-server.tool("context_guard_check", "Check context window health using Context Guard v6 — dynamic thresholds, DNA memory count, bootstrap readiness. Replaces memory_health with richer data.", {
+server.tool("context_guard_check", "[CORE] Check context pressure — returns recommendation (safe/compact_soon/compact_now). Call every ~15 messages to monitor context window health.", {
     estimated_tokens: z.number().describe("Current token count in context window"),
     max_tokens: z.number().optional().describe("Max context window size (uses HM_CONTEXT_CAP env if omitted)"),
     model: z.string().optional().describe("Model name for auto-detecting context window size (e.g. claude-sonnet-4-6)"),
@@ -829,21 +862,34 @@ server.tool("context_guard_check", "Check context window health using Context Gu
             max_tokens: maxTokens,
             model: args.model || null,
         };
-        // Send per-IDE threshold overrides if configured via env vars
+        // Per-IDE threshold overrides. Absolute (CG_*_AT_TOKENS) is preferred —
+        // server treats it as the authoritative trigger. Decimal % is the
+        // backward-compat path for users whose env still says "30/50".
+        if (CG_COMPACT_AT_TOKENS > 0)
+            payload.compact_at_tokens = CG_COMPACT_AT_TOKENS;
+        if (CG_CRITICAL_AT_TOKENS > 0)
+            payload.critical_at_tokens = CG_CRITICAL_AT_TOKENS;
         if (CG_COMPACT_PCT > 0)
             payload.compact_pct = CG_COMPACT_PCT / 100;
         if (CG_CRITICAL_PCT > 0)
             payload.critical_pct = CG_CRITICAL_PCT / 100;
         const r = (await api("POST", "/v1/context/guard/check", payload));
-        const pct = r.usage_percent;
+        // Render against the user's configured critical threshold so the bar is
+        // anchored to the absolute trigger point (HM_CRITICAL_AT), not a soft
+        // model-window percentage. When critical_at_tokens is missing, fall back
+        // to the legacy usage_percent rendering.
+        const tokens = args.estimated_tokens;
+        const critical = r.critical_at_tokens || (CG_CRITICAL_AT_TOKENS > 0 ? CG_CRITICAL_AT_TOKENS : 0);
+        const compact = r.compact_at_tokens || (CG_COMPACT_AT_TOKENS > 0 ? CG_COMPACT_AT_TOKENS : 0);
         const barLen = 20;
-        const filled = Math.round(pct / 100 * barLen);
+        const ratio = critical > 0 ? Math.min(1, tokens / critical) : (r.usage_percent / 100);
+        const filled = Math.max(0, Math.min(barLen, Math.round(ratio * barLen)));
         const bar = "\u2588".repeat(filled) + "\u2591".repeat(barLen - filled);
         return ok(`Context Guard v6:\n` +
-            `[${bar}] ${pct.toFixed(1)}%\n` +
-            `Recommendation: ${r.recommendation.toUpperCase()}${r.should_compact ? " — compact now" : ""}\n` +
+            `[${bar}] ${tokens.toLocaleString()} / ${critical ? critical.toLocaleString() + " tokens" : (r.usage_percent.toFixed(1) + "%")}\n` +
+            `Recommendation: ${r.recommendation.toUpperCase()}${r.should_compact ? " \u2014 compact now" : ""}\n` +
             `Urgency: ${r.urgency}\n` +
-            `Thresholds: compact=${r.compact_at_tokens.toLocaleString()}, critical=${r.critical_at_tokens.toLocaleString()}\n` +
+            `Thresholds: compact=${(compact || r.compact_at_tokens).toLocaleString()}, critical=${(critical || r.critical_at_tokens).toLocaleString()}\n` +
             `DNA memories: ${r.dna_memories} | Hot: ${r.hot_memories} | Stale: ${r.stale_memories}\n` +
             `Bootstrap ready: ${r.bootstrap_ready ? "yes" : "no"}\n` +
             (r.last_compact_minutes_ago != null ? `Last compact: ${r.last_compact_minutes_ago.toFixed(0)} min ago` : "No compacts yet"));
@@ -853,7 +899,7 @@ server.tool("context_guard_check", "Check context window health using Context Gu
     }
 });
 // context_guard_compact — compact with DNA protection
-server.tool("context_guard_compact", "Compact session context with DNA protection — DNA memories are never overwritten. IMPORTANT: Send a REAL summary of the conversation (>500 chars) including topics discussed, decisions made, key numbers/facts, and current status. Do NOT send just a status string like 'context guard - 132%'. If you send useless content, the server will use its internal buffer as fallback, but a good summary from you produces better memories.", {
+server.tool("context_guard_compact", "[CORE] Save context to long-term memory when context_guard_check says 'compact_now'. Send a REAL summary (>500 chars) of topics discussed, decisions made, key facts, and current status. DNA memories are never overwritten.", {
     content: z.string().describe("Conversation summary — include topics, decisions, key facts, numbers. Must be >500 chars of real content."),
     task_context: z.string().optional().describe("Task description for tagging"),
     blocking: z.boolean().optional().describe("Wait for result (true) or return task_id (false, default)"),
@@ -874,8 +920,58 @@ server.tool("context_guard_compact", "Compact session context with DNA protectio
         return err(e);
     }
 });
+// ide_turn_check — server-authoritative context guard (zero guessing)
+// The agent cannot read its host IDE's actual context window from inside an
+// MCP tool. Instead of asking it to estimate tokens, this tool only asks for
+// turn_count + max_tokens and the server does the math. Returns a ready-to-
+// follow action_prompt — agent reads it verbatim, no interpretation needed.
+server.tool("ide_turn_check", "[CORE] Server-authoritative context check for IDE hooks. Pass turn_count + max_tokens; server computes pressure and returns an action_prompt the agent should follow verbatim. Use this instead of context_guard_check from IDE auto-capture hooks.", {
+    turn_count: z.number().describe("Number of assistant turns in this conversation."),
+    max_tokens: z.number().optional().describe("Actual IDE context window in tokens — NOT the underlying model claim. Default 200000."),
+    avg_tokens_per_turn: z.number().optional().describe("Calibration knob, default 4000."),
+    skip_below_turns: z.number().optional().describe("Skip the check below this many turns (default 20)."),
+    model: z.string().optional().describe("Optional model hint when max_tokens not set."),
+}, async (args) => {
+    try {
+        const payload = {
+            turn_count: args.turn_count,
+            max_tokens: args.max_tokens ?? CG_CONTEXT_CAP ?? 200_000,
+            avg_tokens_per_turn: args.avg_tokens_per_turn ?? 8000,
+            skip_below_turns: args.skip_below_turns ?? 10,
+            model: args.model ?? null,
+        };
+        // Per-IDE threshold overrides. Absolute first (preferred), % fallback.
+        if (CG_COMPACT_AT_TOKENS > 0)
+            payload.compact_at_tokens = CG_COMPACT_AT_TOKENS;
+        if (CG_CRITICAL_AT_TOKENS > 0)
+            payload.critical_at_tokens = CG_CRITICAL_AT_TOKENS;
+        if (CG_COMPACT_PCT > 0)
+            payload.compact_pct = CG_COMPACT_PCT / 100;
+        if (CG_CRITICAL_PCT > 0)
+            payload.critical_pct = CG_CRITICAL_PCT / 100;
+        const r = (await api("POST", "/v1/ide/guard/turn-check", payload));
+        if (r.skipped) {
+            return ok(`Turn check skipped (turn ${args.turn_count} below threshold). Recommendation: SAFE.`);
+        }
+        const tokens = r.estimated_tokens;
+        const critical = r.critical_at_tokens || (CG_CRITICAL_AT_TOKENS > 0 ? CG_CRITICAL_AT_TOKENS : 0);
+        const barLen = 20;
+        const ratio = critical > 0 ? Math.min(1, tokens / critical) : (r.usage_percent / 100);
+        const filled = Math.max(0, Math.min(barLen, Math.round(ratio * barLen)));
+        const bar = "\u2588".repeat(filled) + "\u2591".repeat(barLen - filled);
+        return ok(`IDE Turn Check (server-authoritative):\n` +
+            `[${bar}] ${tokens.toLocaleString()} / ${critical ? critical.toLocaleString() + " tokens" : (r.usage_percent.toFixed(1) + "%")}\n` +
+            `Recommendation: ${r.recommendation.toUpperCase()}\n` +
+            `Urgency: ${r.urgency}\n` +
+            `Thresholds: compact=${r.compact_at_tokens.toLocaleString()}, critical=${r.critical_at_tokens.toLocaleString()}\n` +
+            (r.action_prompt ? `\nACTION FOR AGENT (follow verbatim):\n${r.action_prompt}` : "No action needed."));
+    }
+    catch (e) {
+        return err(e);
+    }
+});
 // context_guard_bootstrap — DNA-first session bootstrap (IDE)
-server.tool("context_guard_bootstrap", "Load context from previous sessions at session start. Returns preferences, recent activity, and task-relevant memories. Call once at the beginning of a session to restore context.", {
+server.tool("context_guard_bootstrap", "Advanced: Load context from previous sessions at session start. Returns preferences, recent activity, and task-relevant memories. Call once at the beginning of a session to restore context.", {
     task: z.string().describe("Task description for context relevance"),
     limit: z.number().optional().describe("Max memories to include (default: 10)"),
 }, async (args) => {
@@ -893,7 +989,7 @@ server.tool("context_guard_bootstrap", "Load context from previous sessions at s
     }
 });
 // bot_guard_bootstrap — 3-tier wake-up for bots (800 tokens)
-server.tool("bot_guard_bootstrap", "Bot-specific bootstrap — 3-tier wake-up (Identity→Context→Details) with 800 token budget. Use for chatbots, not IDEs.", {
+server.tool("bot_guard_bootstrap", "Advanced: Bot-specific bootstrap — 3-tier wake-up (Identity→Context→Details) with 800 token budget. Use for chatbots, not IDEs.", {
     task: z.string().describe("Task description for the new session"),
     limit: z.number().optional().describe("Max memories to include (default: 10)"),
     mode: z.enum(["default", "deep"]).optional().describe("'default' = 800 token 3-tier, 'deep' = full context with L2 chunks"),
@@ -916,7 +1012,7 @@ server.tool("bot_guard_bootstrap", "Bot-specific bootstrap — 3-tier wake-up (I
     }
 });
 // bot_session_message — Rolling 3-session tracking (60 msg raw context)
-server.tool("bot_session_message", "Track a message in the rolling session (rolling 3: keeps 60 messages raw in LLM context). Call on EVERY message (user + assistant). Returns rotate=true when session hits 20 messages. When should_compress=true, compress the oldest session via bot_session_compress.", {
+server.tool("bot_session_message", "Advanced: Track a message in the rolling session (rolling 3: keeps 60 messages raw in LLM context). Call on EVERY message (user + assistant). Returns rotate=true when session hits 20 messages. When should_compress=true, compress the oldest session via bot_session_compress.", {
     message: z.object({
         role: z.enum(["user", "assistant"]).describe("Message role"),
         content: z.string().describe("Message content"),
@@ -945,7 +1041,7 @@ server.tool("bot_session_message", "Track a message in the rolling session (roll
     }
 });
 // bot_guard_check — Bot-specific guard with spawn signal
-server.tool("bot_guard_check", "Bot context guard — checks context pressure AND returns spawn signal. When should_spawn_new_session=true, bot should spawn a new session and compress the old one later. Use this instead of context_guard_check for bot/chatbot clients.", {
+server.tool("bot_guard_check", "Advanced: Bot context guard — checks context pressure AND returns spawn signal. When should_spawn_new_session=true, bot should spawn a new session and compress the old one later. Use this instead of context_guard_check for bot/chatbot clients.", {
     estimated_tokens: z.number().describe("Current token count in context window"),
     max_tokens: z.number().optional().describe("Max context window size (default: 200000)"),
     model: z.string().optional().describe("Model name for auto-detecting context window size"),
@@ -982,7 +1078,7 @@ server.tool("bot_guard_check", "Bot context guard — checks context pressure AN
 });
 // ── Self-Thinking Tools ──────────────────────────────────────────────
 // brain_thoughts — Get current active thoughts
-server.tool("brain_thoughts", "Get the brain's current active thoughts — what it's thinking about autonomously.", {
+server.tool("brain_thoughts", "Advanced: Get the brain's current active thoughts — what it's thinking about autonomously.", {
     limit: z.number().optional().describe("Max thoughts to return (default: 10)"),
 }, async (args) => {
     try {
@@ -997,7 +1093,7 @@ server.tool("brain_thoughts", "Get the brain's current active thoughts — what
     }
 });
 // brain_think_about — Request brain to think about a topic
-server.tool("brain_think_about", "Request the brain to think about a specific topic. The brain will deliberate on it in its next thinking cycle.", {
+server.tool("brain_think_about", "Advanced: Request the brain to think about a specific topic. The brain will deliberate on it in its next thinking cycle.", {
     topic: z.string().describe("What should the brain think about?"),
 }, async (args) => {
     try {
@@ -1009,7 +1105,7 @@ server.tool("brain_think_about", "Request the brain to think about a specific to
     }
 });
 // brain_hypotheses — Get active hypotheses
-server.tool("brain_hypotheses", "Get hypotheses the brain is currently testing — predictions about user behavior patterns.", {
+server.tool("brain_hypotheses", "Advanced: Get hypotheses the brain is currently testing — predictions about user behavior patterns.", {
     limit: z.number().optional().describe("Max hypotheses to return (default: 10)"),
 }, async (args) => {
     try {
@@ -1024,7 +1120,7 @@ server.tool("brain_hypotheses", "Get hypotheses the brain is currently testing
     }
 });
 // brain_feedback — Rate a thought
-server.tool("brain_feedback", "Rate a thought as useful or not — helps the brain learn what's worth thinking about.", {
+server.tool("brain_feedback", "Advanced: Rate a thought as useful or not — helps the brain learn what's worth thinking about.", {
     thought_id: z.number().describe("ID of the thought to rate"),
     useful: z.boolean().describe("Was this thought useful?"),
 }, async (args) => {
@@ -1040,7 +1136,7 @@ server.tool("brain_feedback", "Rate a thought as useful or not — helps the bra
     }
 });
 // brain_thinking_stats — Budget and efficiency
-server.tool("brain_thinking_stats", "Get thinking system statistics — token budget, efficiency, queue size, and meta-cognition report.", {}, async () => {
+server.tool("brain_thinking_stats", "Advanced: Get thinking system statistics — token budget, efficiency, queue size, and meta-cognition report.", {}, async () => {
     try {
         const r = (await api("GET", "/v1/brain/thinking-stats"));
         return ok(`Budget: ${r.budget.remaining_tokens} tokens remaining (limit: ${r.budget.limit_per_hour}/hr)\n` +
@@ -1057,7 +1153,7 @@ server.tool("brain_thinking_stats", "Get thinking system statistics — token bu
 });
 // ── Session Settings Tools ──────────────────────────────────────────
 // memory_auto_extract — LLM-based fact extraction from conversation
-server.tool("memory_auto_extract", "CRITICAL: Call this at the END of every conversation session to extract and store important facts automatically. Uses LLM analysis to identify pricing, decisions, plans, technical details, and anything worth remembering. This is MORE reliable than manual memory_store because it catches things you might forget to store. ALWAYS call this before the conversation ends — especially after discussions about money, pricing, plans, decisions, or business.", {
+server.tool("memory_auto_extract", "Advanced: CRITICAL: Call this at the END of every conversation session to extract and store important facts automatically. Uses LLM analysis to identify pricing, decisions, plans, technical details, and anything worth remembering. This is MORE reliable than manual memory_store because it catches things you might forget to store. ALWAYS call this before the conversation ends — especially after discussions about money, pricing, plans, decisions, or business.", {
     conversation: z.string().describe("The conversation text to extract facts from (include both user and assistant messages)"),
     source: z.string().optional().describe("Source context (e.g. 'discord chat', 'slack thread')"),
     store: z.boolean().optional().describe("Whether to store extracted facts (default: true). Set false to preview what would be extracted."),
@@ -1081,7 +1177,7 @@ server.tool("memory_auto_extract", "CRITICAL: Call this at the END of every conv
 });
 // ── IDE Upgrade Tools ──────────────────────────────────────────────
 // memory_pitfall_check — Check pitfalls before risky actions
-server.tool("memory_pitfall_check", "IMPORTANT: Call this BEFORE executing risky actions (deploy, rm, git push, database changes). Returns known pitfalls (past failures + lessons) so you can avoid repeating mistakes. Pitfalls are DNA-protected and never expire.", {
+server.tool("memory_pitfall_check", "Advanced: IMPORTANT: Call this BEFORE executing risky actions (deploy, rm, git push, database changes). Returns known pitfalls (past failures + lessons) so you can avoid repeating mistakes. Pitfalls are DNA-protected and never expire.", {
     intent: z.string().describe("What you're about to do (e.g. 'deploy to production', 'delete user table')"),
     tags: z.array(z.string()).optional().describe("Filter by tags"),
     limit: z.number().optional().describe("Max results (default 5)"),
@@ -1104,7 +1200,7 @@ server.tool("memory_pitfall_check", "IMPORTANT: Call this BEFORE executing risky
     }
 });
 // memory_plan_save — Save current plan/state for session resumption
-server.tool("memory_plan_save", "Save your current work state (plan steps, cursor position, active goals) so you can resume exactly where you left off in the next session. Call before session ends or when switching tasks.", {
+server.tool("memory_plan_save", "Advanced: Save your current work state (plan steps, cursor position, active goals) so you can resume exactly where you left off in the next session. Call before session ends or when switching tasks.", {
     session_id: z.string().optional().describe("Session identifier (default: 'default')"),
     state: z.record(z.string(), z.unknown()).describe("State to save: {plan: [...], cursor: 3, active_goal: '...', last_action: '...', files_read: [...]}"),
 }, async (args) => {
@@ -1120,7 +1216,7 @@ server.tool("memory_plan_save", "Save your current work state (plan steps, curso
     }
 });
 // memory_plan_resume — Restore saved state from previous session
-server.tool("memory_plan_resume", "Restore your work state from a previous session. Returns plan steps, cursor position, active goals — everything needed to continue where you left off.", {
+server.tool("memory_plan_resume", "Advanced: Restore your work state from a previous session. Returns plan steps, cursor position, active goals — everything needed to continue where you left off.", {
     session_id: z.string().optional().describe("Session identifier (default: 'default')"),
 }, async (args) => {
     try {
@@ -1134,7 +1230,7 @@ server.tool("memory_plan_resume", "Restore your work state from a previous sessi
     }
 });
 // memory_goal_track — Create/update/query goals
-server.tool("memory_goal_track", "Track goals across sessions. Create new goals, update progress, or query active goals. Goals with status='active' are DNA-protected (never decay).", {
+server.tool("memory_goal_track", "Advanced: Track goals across sessions. Create new goals, update progress, or query active goals. Goals with status='active' are DNA-protected (never decay).", {
     action: z.enum(["create", "update", "list"]).describe("Action to perform"),
     title: z.string().optional().describe("Goal title (for create)"),
     progress: z.number().optional().describe("Progress 0.0-1.0 (for update)"),
@@ -1172,7 +1268,7 @@ server.tool("memory_goal_track", "Track goals across sessions. Create new goals,
     }
 });
 // memory_thought_log — Query what the brain has been thinking about
-server.tool("memory_thought_log", "See what the brain has been thinking about autonomously. Returns recent thoughts, hypotheses, and insights generated during idle time.", {
+server.tool("memory_thought_log", "Advanced: See what the brain has been thinking about autonomously. Returns recent thoughts, hypotheses, and insights generated during idle time.", {
     limit: z.number().optional().describe("Max thoughts to return (default 5)"),
 }, async (args) => {
     try {
@@ -1189,7 +1285,7 @@ server.tool("memory_thought_log", "See what the brain has been thinking about au
     }
 });
 // memory_feedback — Report recall quality for self-improvement
-server.tool("memory_feedback", "Report whether recall results were helpful. This feeds the neuroplasticity system — over time, the brain learns what works for YOUR specific patterns and improves recall quality.", {
+server.tool("memory_feedback", "Advanced: Report whether recall results were helpful. This feeds the neuroplasticity system — over time, the brain learns what works for YOUR specific patterns and improves recall quality.", {
     query: z.string().describe("The recall query that was made"),
     chunk_ids: z.array(z.number()).describe("IDs of chunks that were returned"),
     helpful: z.boolean().describe("Were the results helpful for your task?"),
@@ -1209,7 +1305,7 @@ server.tool("memory_feedback", "Report whether recall results were helpful. This
     }
 });
 // memory_predict — Predictive recall (push intent, get predicted memories)
-server.tool("memory_predict", "Predictive recall — tell the brain what you're about to do and get relevant memories pre-loaded. Call this when you can anticipate what context will be needed next.", {
+server.tool("memory_predict", "Advanced: Predictive recall — tell the brain what you're about to do and get relevant memories pre-loaded. Call this when you can anticipate what context will be needed next.", {
     intent: z.string().describe("What you/user are about to do"),
     context: z.string().optional().describe("Current conversation context (helps prediction accuracy)"),
     limit: z.number().optional().describe("Max predictions (default 5)"),
@@ -1232,7 +1328,7 @@ server.tool("memory_predict", "Predictive recall — tell the brain what you're
     }
 });
 // memory_changelog — What changed since last session
-server.tool("memory_changelog", "See what changed in your memory since your last session. Shows new memories, updates, invalidations, and insights from overnight consolidation. Call at session start after bootstrap to understand what the brain learned while you were away.", {
+server.tool("memory_changelog", "Advanced: See what changed in your memory since your last session. Shows new memories, updates, invalidations, and insights from overnight consolidation. Call at session start after bootstrap to understand what the brain learned while you were away.", {
     since: z.string().describe("ISO datetime — show changes after this time (e.g. '2026-05-20T10:00:00Z')"),
     project_id: z.string().optional().describe("Filter to specific project"),
     limit: z.number().optional().describe("Max changes to return (default 50)"),
@@ -1255,7 +1351,7 @@ server.tool("memory_changelog", "See what changed in your memory since your last
     }
 });
 // memory_cognitive_profile — Complete self-model (metacognition)
-server.tool("memory_cognitive_profile", "Get the brain's complete self-model: who the user is, their mood, active goals, top entities (people/places), learned procedures, and recent topics. Use for complete context awareness. No LLM cost — pure aggregation (~50ms).", {}, async () => {
+server.tool("memory_cognitive_profile", "Advanced: Get the brain's complete self-model: who the user is, their mood, active goals, top entities (people/places), learned procedures, and recent topics. Use for complete context awareness. No LLM cost — pure aggregation (~50ms).", {}, async () => {
     try {
         const r = (await api("GET", "/v1/personality/cognitive-profile"));
         let out = `## Cognitive Profile\n\n`;
@@ -1278,7 +1374,7 @@ server.tool("memory_cognitive_profile", "Get the brain's complete self-model: wh
     }
 });
 // memory_entity_profile — Get everything known about an entity
-server.tool("memory_entity_profile", "Get complete profile for a specific entity (person, place, concept). Returns: frequency stats, linked memories, and relationships. Use when you need context about a specific person or topic the user has discussed.", {
+server.tool("memory_entity_profile", "Advanced: Get complete profile for a specific entity (person, place, concept). Returns: frequency stats, linked memories, and relationships. Use when you need context about a specific person or topic the user has discussed.", {
     name: z.string().describe("Entity name to look up (e.g. 'Sarah', 'React', 'AuthService')"),
 }, async (args) => {
     try {
@@ -1316,7 +1412,7 @@ server.tool("memory_entity_profile", "Get complete profile for a specific entity
 //   • twin_respond / twin_status    — Cognitive Twin (promax+ tier)
 // ═══════════════════════════════════════════════════════════════════════════
 // brain_export
-server.tool("brain_export", "Export the entire brain to a portable JSON bundle (vendor-neutral). Use when the user wants to back up their brain, migrate to another instance (e.g. lite-build on-prem), or comply with data-portability rights. The bundle is self-contained — chunks, edges, entities, L2 sessions, mood, agents — and includes a sha256 checksum. Returns the bundle JSON.", {
+server.tool("brain_export", "Advanced: Export the entire brain to a portable JSON bundle (vendor-neutral). Use when the user wants to back up their brain, migrate to another instance (e.g. lite-build on-prem), or comply with data-portability rights. The bundle is self-contained — chunks, edges, entities, L2 sessions, mood, agents — and includes a sha256 checksum. Returns the bundle JSON.", {
     scope: z.enum(["full", "dna_only", "since"]).optional().describe("'full'=everything (default), 'dna_only'=just preferences/decisions/identity (lightweight portable identity), 'since'=incremental (requires `since` ISO datetime)"),
     since: z.string().optional().describe("ISO8601 datetime, only used when scope='since'"),
 }, async (args) => {
@@ -1341,7 +1437,7 @@ server.tool("brain_export", "Export the entire brain to a portable JSON bundle (
     }
 });
 // brain_import
-server.tool("brain_import", "Import a MemoryAI bundle (from brain_export) into the current tenant. Idempotent — chunks deduped by content_hash; edges/entities upserted. Embeddings are reused if the bundle's embedding_model matches the local one; otherwise dropped (chunks re-embed lazily).", {
+server.tool("brain_import", "Advanced: Import a MemoryAI bundle (from brain_export) into the current tenant. Idempotent — chunks deduped by content_hash; edges/entities upserted. Embeddings are reused if the bundle's embedding_model matches the local one; otherwise dropped (chunks re-embed lazily).", {
     bundle: z.record(z.string(), z.unknown()).describe("The bundle JSON produced by brain_export (must contain format='memoryai-bundle', version, manifest, etc.)"),
     keep_embeddings: z.boolean().optional().describe("Reuse bundle embeddings if model matches (default: true)"),
 }, async (args) => {
@@ -1363,7 +1459,7 @@ server.tool("brain_import", "Import a MemoryAI bundle (from brain_export) into t
     }
 });
 // benchmark_recall_vs_full
-server.tool("benchmark_recall_vs_full", "Run a public benchmark: smart recall vs full-context dump on the calling brain. DNA #2 — proves the 'retina for AI' moat with measurable numbers (cost, latency, signal density). Available on every tier; safe to share results publicly.", {
+server.tool("benchmark_recall_vs_full", "Advanced: Run a public benchmark: smart recall vs full-context dump on the calling brain. DNA #2 — proves the 'retina for AI' moat with measurable numbers (cost, latency, signal density). Available on every tier; safe to share results publicly.", {
     query: z.string().describe("The query to benchmark (e.g. 'what does the user prefer?')"),
     model: z.string().optional().describe("Model whose pricing to apply (default: claude-opus-4-6). Affects $cost only."),
     naive_budget_tokens: z.number().optional().describe("Cap on full-context dump (default: 200K = Claude window)"),
@@ -1390,7 +1486,7 @@ server.tool("benchmark_recall_vs_full", "Run a public benchmark: smart recall vs
     }
 });
 // benchmark_pricing
-server.tool("benchmark_pricing", "Get the assumed $/1M-input-tokens pricing for each LLM (used by benchmark_recall_vs_full). No auth required; list prices only.", {}, async () => {
+server.tool("benchmark_pricing", "Advanced: Get the assumed $/1M-input-tokens pricing for each LLM (used by benchmark_recall_vs_full). No auth required; list prices only.", {}, async () => {
     try {
         const r = (await api("GET", "/v1/benchmark/pricing"));
         const lines = Object.entries(r.prices || {}).map(([k, v]) => `- ${k}: $${v}`);
@@ -1401,7 +1497,7 @@ server.tool("benchmark_pricing", "Get the assumed $/1M-input-tokens pricing for
     }
 });
 // trust_agents
-server.tool("trust_agents", "Get the agent reputation leaderboard (sorted by reputation_score desc). DNA #1.5 — when 20 agents share memory and disagree, this tells you whose claims to trust. Requires team+ plan.", {
+server.tool("trust_agents", "Advanced: Get the agent reputation leaderboard (sorted by reputation_score desc). DNA #1.5 — when 20 agents share memory and disagree, this tells you whose claims to trust. Requires team+ plan.", {
     limit: z.number().optional().describe("Max agents to return (default: 50, max: 500)"),
 }, async (args) => {
     try {
@@ -1416,7 +1512,7 @@ server.tool("trust_agents", "Get the agent reputation leaderboard (sorted by rep
     }
 });
 // trust_chunk
-server.tool("trust_chunk", "Get per-chunk trust info: which agent claimed it, that agent's reputation, helpful/unhelpful counts. Use after a recall to decide whether to trust a specific result. Available on every paid tier.", {
+server.tool("trust_chunk", "Advanced: Get per-chunk trust info: which agent claimed it, that agent's reputation, helpful/unhelpful counts. Use after a recall to decide whether to trust a specific result. Available on every paid tier.", {
     chunk_id: z.number().describe("The chunk ID returned by recall"),
 }, async (args) => {
     try {
@@ -1433,7 +1529,7 @@ server.tool("trust_chunk", "Get per-chunk trust info: which agent claimed it, th
     }
 });
 // twin_respond
-server.tool("twin_respond", "Ask the Cognitive Twin to predict how the user would respond to a given query. The twin uses the user's personality + mood + DNA + procedures to simulate their voice. Returns the predicted response, a confidence score 0-1, and the chunk IDs that informed it (provenance trail). Auto-refuses with confidence=0 if the brain has fewer than 5 DNA memories. Requires promax+ plan.", {
+server.tool("twin_respond", "Advanced: Ask the Cognitive Twin to predict how the user would respond to a given query. The twin uses the user's personality + mood + DNA + procedures to simulate their voice. Returns the predicted response, a confidence score 0-1, and the chunk IDs that informed it (provenance trail). Auto-refuses with confidence=0 if the brain has fewer than 5 DNA memories. Requires promax+ plan.", {
     query: z.string().describe("The free-form question to ask the twin (e.g. 'what database for a chat app?')"),
     operation: z.enum(["respond", "decide"]).optional().describe("'respond'=free-form answer (default), 'decide'=pick one option from the query"),
 }, async (args) => {
@@ -1453,7 +1549,7 @@ server.tool("twin_respond", "Ask the Cognitive Twin to predict how the user woul
     }
 });
 // twin_status
-server.tool("twin_status", "Check whether the Cognitive Twin is ready for the calling tenant. Cheap — no LLM call. Returns DNA count, personality/mood presence, and a `ready` boolean. Useful before invoking twin_respond.", {}, async () => {
+server.tool("twin_status", "Advanced: Check whether the Cognitive Twin is ready for the calling tenant. Cheap — no LLM call. Returns DNA count, personality/mood presence, and a `ready` boolean. Useful before invoking twin_respond.", {}, async () => {
     try {
         const r = (await api("GET", "/v1/twin/status"));
         return ok(`Twin ready: ${r.ready ? "YES" : "NO"} (need ≥${r.min_dna_required} DNA, have ${r.dna_count})\n` +
@@ -1469,6 +1565,175 @@ server.tool("twin_status", "Check whether the Cognitive Twin is ready for the ca
         return err(e);
     }
 });
+// ═══════════════════════════════════════════════════════════════════════════
+// v2.3 (billion-dollar foundation, 2026-05-29) — DNA-aligned tools:
+//   • inherit_*  — DNA #3 brain belongs to user, transferable when they die
+//   • fed_*      — DNA #1 ∞ agents share brain across organizations
+//   • l2_inject  — DNA #2 retina endpoint (compose context within budget)
+//   • l2_status  — cache + availability summary
+//   • spec_info  — public protocol contract (CC BY 4.0)
+// ═══════════════════════════════════════════════════════════════════════════
+// inherit_assign
+server.tool("inherit_assign", "Advanced: Assign an heir who inherits your brain when you trigger inheritance. DNA #3 — brain belongs to the user and is transferable. Idempotent on (owner, heir).", {
+    heir_tenant_id: z.string().describe("Heir's tenant UUID"),
+    share: z.number().optional().describe("Share percentage 0-100 (default: 100 if single heir)"),
+    scope: z.enum(["all", "dna_only", "tagged"]).optional().describe("What to transfer (default: all)"),
+    tag_filter: z.array(z.string()).optional().describe("Only transfer chunks with these tags (when scope=tagged)"),
+    message: z.string().optional().describe("Optional letter to the heir, surfaced in their inbox"),
+}, async (args) => {
+    try {
+        const r = (await api("POST", "/v1/inheritance/heirs", args));
+        return ok(`Heir assigned: ${r.heir_tenant_id} (share ${r.share}%, scope ${r.scope}). ${r.message_set ? "Message stored." : ""}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// inherit_list
+server.tool("inherit_list", "Advanced: List your assigned heirs and their share/scope. DNA #3 — your brain inheritance plan, viewable any time.", {}, async () => {
+    try {
+        const r = (await api("GET", "/v1/inheritance/heirs"));
+        const heirs = r.heirs || [];
+        if (heirs.length === 0)
+            return ok("No heirs assigned yet.");
+        const lines = heirs.map((h) => `- ${h.heir_tenant_id} · share=${h.share}% · scope=${h.scope} · status=${h.status} · added=${h.created_at?.slice(0, 10)}`);
+        return ok(`Heirs (${heirs.length}):\n${lines.join("\n")}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// inherit_revoke
+server.tool("inherit_revoke", "Advanced: Revoke a previously assigned heir. Their access to your brain is removed; nothing is exported.", {
+    heir_tenant_id: z.string().describe("Heir's tenant UUID to revoke"),
+}, async (args) => {
+    try {
+        await api("DELETE", `/v1/inheritance/heirs/${encodeURIComponent(args.heir_tenant_id)}`);
+        return ok(`Heir revoked: ${args.heir_tenant_id}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// inherit_trigger
+server.tool("inherit_trigger", "Advanced: Trigger inheritance — exports your brain bundle and imports it into every accepted heir. Owner-only (heir-triggered inheritance is deferred to P2.3.full). DNA #3 — your brain becomes their brain.", {}, async () => {
+    try {
+        const r = (await api("POST", "/v1/inheritance/trigger", {}));
+        const transfers = r.transfers || [];
+        const summary = transfers.map((t) => `- ${t.heir_tenant_id}: ${t.status} (${t.chunks_inserted ?? 0} chunks transferred)`);
+        return ok(`Inheritance triggered (${transfers.length} heirs):\n${summary.join("\n")}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// fed_grant
+server.tool("fed_grant", "Advanced: Grant a federated reader access to your brain. DNA #1 — multi-agent / cross-organization recall without copying. Optional tag filter, expiry, and DNA exclusion (DNA excluded by default for safety). Requires team+ plan.", {
+    grantee_tenant_id: z.string().describe("Grantee's tenant UUID"),
+    permission: z.enum(["read", "read_write"]).optional().describe("Permission (default: read)"),
+    tag_filter: z.array(z.string()).optional().describe("Only expose chunks matching these tags"),
+    include_dna: z.boolean().optional().describe("Allow grantee to recall DNA chunks (default: false)"),
+    expires_at: z.string().optional().describe("ISO datetime expiry (default: no expiry)"),
+}, async (args) => {
+    try {
+        const r = (await api("POST", "/v1/federation/grants", args));
+        return ok(`Federation grant created: ${r.grant_id} (grantee=${r.grantee_tenant_id}, permission=${r.permission}, expires=${r.expires_at || "never"})`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// fed_revoke
+server.tool("fed_revoke", "Advanced: Revoke a federation grant. Only the grantor may revoke. Existing in-flight recalls remain audited.", {
+    grant_id: z.string().describe("Grant UUID to revoke"),
+}, async (args) => {
+    try {
+        await api("DELETE", `/v1/federation/grants/${encodeURIComponent(args.grant_id)}`);
+        return ok(`Federation grant revoked: ${args.grant_id}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// fed_inbox
+server.tool("fed_inbox", "Advanced: List federation grants others gave you (your federated inbox). Each grant lets you recall against another tenant's brain via fed_recall.", {}, async () => {
+    try {
+        const r = (await api("GET", "/v1/federation/inbox"));
+        const grants = r.grants || [];
+        if (grants.length === 0)
+            return ok("Federation inbox empty.");
+        const lines = grants.map((g) => `- grant=${g.grant_id} · grantor=${g.grantor_tenant_id} · perm=${g.permission} · tags=${(g.tag_filter || []).join(",") || "(any)"} · expires=${g.expires_at || "never"}`);
+        return ok(`Federated grants you can use (${grants.length}):\n${lines.join("\n")}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// fed_recall
+server.tool("fed_recall", "Advanced: Recall against a federated brain you have access to. Server enforces tag_filter, DNA exclusion, expiry, and audits every call back to the grantor.", {
+    grant_id: z.string().describe("Grant UUID from fed_inbox"),
+    query: z.string().describe("Recall query"),
+}, async (args) => {
+    try {
+        const r = (await api("POST", "/v1/federation/recall", args));
+        const results = r.results || [];
+        if (results.length === 0)
+            return ok("No federated results.");
+        const lines = results.slice(0, 10).map((m) => `[${m.score?.toFixed(2)}] ${m.content?.slice(0, 200)}`);
+        return ok(`Federated recall (${results.length} results, audited to grantor):\n${lines.join("\n\n")}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// l2_inject — DNA #2 retina endpoint
+server.tool("l2_inject", "Compose a context block for your prompt within a token budget. DNA #2 — top model thinks with 100K context, L2 holds 100M memory; this tool is the bridge. Pipeline: L4 cache → DNA → pre-reasoned L2 → L3 4-way recall → compress within budget. Latency p95 < 200ms (cache hit), < 800ms (miss). Returns a markdown block ready to paste into your system prompt.", {
+    query: z.string().describe("What you're about to ask the top model"),
+    context_budget_tokens: z.number().optional().describe("Max tokens in returned context (default: 2000)"),
+    model_hint: z.string().optional().describe("Model name (e.g. 'claude-opus-4-7') for token-counting accuracy"),
+    freshness_priority: z.enum(["balanced", "recent", "deep"]).optional().describe("Bias toward freshness vs depth (default: balanced)"),
+    bypass_cache: z.boolean().optional().describe("Skip L4 cache lookup (default: false)"),
+}, async (args) => {
+    try {
+        const r = (await api("POST", "/v1/l2/inject", args));
+        const out = `L2 inject — ${r.tokens_used}/${r.tokens_budget} tokens, ${r.sources?.length ?? 0} sources, cache_hit=${r.cache_hit}, ${r.latency_ms}ms\n\n${r.context_block}`;
+        return ok(out);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// l2_status — DNA #2
+server.tool("l2_status", "Check L2 readiness: cached entries, pre-reasoned chunks, DNA chunks. Cheap — no LLM call. Useful before deciding whether to call l2_inject vs raw recall.", {}, async () => {
+    try {
+        const r = (await api("GET", "/v1/l2/status"));
+        return ok(`L2 status:\n` +
+            `- cached_entries: ${r.cached_entries}\n` +
+            `- pre_reasoned_chunks: ${r.pre_reasoned_chunks}\n` +
+            `- dna_chunks: ${r.dna_chunks}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// spec_info — DNA #3 protocol
+server.tool("spec_info", "Advanced: Get the MemoryAI Protocol v1 contract (machine-readable summary). DNA #3 — vendor-neutral standard. Use this when interoperating with other MemoryAI-compatible implementations.", {}, async () => {
+    try {
+        const r = (await api("GET", "/v1/spec/info"));
+        const lines = [
+            `Protocol: ${r.format} v${r.version}`,
+            `License: ${r.license}`,
+            `Conformance levels: ${(r.conformance_levels || []).join(", ")}`,
+            `DNA types: ${(r.dna_memory_types || []).join(", ")}`,
+            `Embedding model: ${r.embedding_model} (${r.embedding_dim} dims)`,
+            `Bundle endpoints: ${(r.endpoints || []).join(", ")}`,
+        ];
+        return ok(lines.join("\n"));
+    }
+    catch (e) {
+        return err(e);
+    }
+});
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);