@daniel156161/prism 0.2.91 → 0.2.96

package/src/prism-extensions/core/mex-cli.ts

@@ -0,0 +1,217 @@
+import { execFile, spawnSync } from "node:child_process"
+import * as fs from "node:fs"
+import * as path from "node:path"
+import { promisify } from "node:util"
+
+const execFileAsync = promisify(execFile)
+
+export type MexExecRunner = typeof execFileAsync
+export type MexDetail = "minimal" | "standard" | "source"
+export type MexRelation = "who-calls" | "what-calls" | "where-defined"
+export type MexLogType = "decision" | "note" | "risk" | "todo"
+
+export const MEX_DETAIL_LEVELS: MexDetail[] = ["minimal", "standard", "source"]
+export const MEX_RELATIONS: MexRelation[] = ["who-calls", "what-calls", "where-defined"]
+export const MEX_LOG_TYPES: MexLogType[] = ["decision", "note", "risk", "todo"]
+
+export const MEX_SCAFFOLD_DIR = ".mex"
+export const DEFAULT_MEX_TIMEOUT_MS = 60_000
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined
+}
+
+export function mexBinary(env: NodeJS.ProcessEnv = process.env): string {
+  return nonEmptyString(env.PRISM_MEX_BIN) ?? "mex"
+}
+
+/** mex telemetry is opt-out; Prism keeps it off unless explicitly enabled. */
+export function mexEnv(env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  if (env.PRISM_MEX_TELEMETRY === "1") return { ...env }
+  return { ...env, DO_NOT_TRACK: "1", MEX_TELEMETRY: "0" }
+}
+
+export function isMexCliInstalled(env: NodeJS.ProcessEnv = process.env, runSync: typeof spawnSync = spawnSync): boolean {
+  if (env.PRISM_DISABLE_MEX === "1") return false
+  const result = runSync(mexBinary(env), ["--version"], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], env: mexEnv(env), timeout: 5_000 })
+  return result.status === 0 && !!result.stdout?.trim()
+}
+
+export function mexScaffoldDir(cwd: string = process.cwd()): string {
+  return path.join(cwd, MEX_SCAFFOLD_DIR)
+}
+
+export function hasMexScaffold(cwd: string = process.cwd()): boolean {
+  // We treat a `.mex/` directory as a usable scaffold only when it contains
+  // the always-loaded anchor and router instruction files.
+  // This prevents accidentally counting a merely existing home/global `.mex/`
+  // directory that may not actually be a functional scaffold.
+  const dir = mexScaffoldDir(cwd)
+  const agentsFile = path.join(dir, "AGENTS.md")
+  const routerFile = path.join(dir, "ROUTER.md")
+  try {
+    return fs.statSync(dir).isDirectory() && fs.statSync(agentsFile).isFile() && fs.statSync(routerFile).isFile()
+  } catch {
+    return false
+  }
+}
+
+/** Tools only make sense when the CLI exists and the repo is scaffolded (or forced). */
+export function isMexAvailable(env: NodeJS.ProcessEnv = process.env, cwd: string = process.cwd(), runSync: typeof spawnSync = spawnSync): boolean {
+  if (env.PRISM_DISABLE_MEX === "1") return false
+  if (!hasMexScaffold(cwd) && env.PRISM_MEX_FORCE !== "1") return false
+  return isMexCliInstalled(env, runSync)
+}
+
+// --- argument builders (pure, easy to test) --------------------------------
+
+export type MexRetrievalOptions = {
+  detail?: unknown
+  maxNodes?: unknown
+  maxOutputTokens?: unknown
+  maxSourceLines?: unknown
+}
+
+function requiredText(value: unknown, name: string): string {
+  const text = String(value ?? "").trim()
+  if (!text) throw new Error(`${name} is required`)
+  return text
+}
+
+function positiveIntFlag(flag: string, value: unknown): string[] {
+  if (value === undefined || value === null || value === "") return []
+  const parsed = Math.trunc(Number(value))
+  if (!Number.isFinite(parsed) || parsed < 1) throw new Error(`${flag} must be a positive number`)
+  return [flag, String(parsed)]
+}
+
+export function mexDetail(value: unknown, fallback: MexDetail = "minimal"): MexDetail {
+  const detail = String(value ?? fallback).toLowerCase()
+  if (!MEX_DETAIL_LEVELS.includes(detail as MexDetail)) throw new Error(`detail must be one of ${MEX_DETAIL_LEVELS.join(", ")}`)
+  return detail as MexDetail
+}
+
+function retrievalFlags(options: MexRetrievalOptions, fallbackDetail: MexDetail): string[] {
+  return [
+    "--detail",
+    mexDetail(options.detail, fallbackDetail),
+    ...positiveIntFlag("--max-nodes", options.maxNodes),
+    ...positiveIntFlag("--max-output-tokens", options.maxOutputTokens),
+    ...positiveIntFlag("--max-source-lines", options.maxSourceLines),
+  ]
+}
+
+export function buildScopeArgs(task: unknown, options: MexRetrievalOptions & { fingerprint?: unknown } = {}): string[] {
+  return [
+    "graph",
+    "scope",
+    ...retrievalFlags(options, "minimal"),
+    ...(options.fingerprint ? ["--fingerprint"] : []),
+    "--",
+    requiredText(task, "task"),
+  ]
+}
+
+export function buildGetArgs(ids: unknown, options: Pick<MexRetrievalOptions, "maxOutputTokens" | "maxSourceLines"> = {}): string[] {
+  const list = (Array.isArray(ids) ? ids : [ids]).map((id) => String(id ?? "").trim()).filter(Boolean)
+  if (list.length === 0) throw new Error("ids is required")
+  return [
+    "graph",
+    "get",
+    ...positiveIntFlag("--max-source-lines", options.maxSourceLines),
+    ...positiveIntFlag("--max-output-tokens", options.maxOutputTokens),
+    "--",
+    ...list,
+  ]
+}
+
+export function buildQueryArgs(relation: unknown, target: unknown, options: MexRetrievalOptions = {}): string[] {
+  const value = String(relation ?? "").toLowerCase().trim()
+  if (!MEX_RELATIONS.includes(value as MexRelation)) throw new Error(`relation must be one of ${MEX_RELATIONS.join(", ")}`)
+  return ["graph", "query", ...retrievalFlags(options, "minimal"), "--", value, requiredText(target, "target")]
+}
+
+export function buildImpactArgs(target: unknown, options: MexRetrievalOptions & { depth?: unknown } = {}): string[] {
+  return [
+    "impact",
+    "--detail",
+    mexDetail(options.detail, "minimal"),
+    ...positiveIntFlag("--depth", options.depth),
+    ...positiveIntFlag("--max-nodes", options.maxNodes),
+    ...positiveIntFlag("--max-output-tokens", options.maxOutputTokens),
+    ...positiveIntFlag("--max-source-lines", options.maxSourceLines),
+    "--",
+    requiredText(target, "target"),
+  ]
+}
+
+export function buildGraphArgs(options: { json?: unknown; root?: unknown } = {}): string[] {
+  const root = nonEmptyString(options.root)
+  return ["graph", ...(options.json ? ["--json"] : []), ...(root ? ["--root", root] : [])]
+}
+
+export function buildCheckArgs(options: { json?: unknown; quiet?: unknown } = {}): string[] {
+  return ["check", ...(options.json ? ["--json"] : []), ...(options.quiet ? ["--quiet"] : [])]
+}
+
+export function buildTimelineArgs(options: { json?: unknown; since?: unknown; type?: unknown; limit?: unknown } = {}): string[] {
+  const since = nonEmptyString(options.since)
+  const type = nonEmptyString(options.type)?.toLowerCase()
+  if (type && !MEX_LOG_TYPES.includes(type as MexLogType)) throw new Error(`type must be one of ${MEX_LOG_TYPES.join(", ")}`)
+  return [
+    "timeline",
+    ...(options.json ? ["--json"] : []),
+    ...(since ? ["--since", since] : []),
+    ...(type ? ["--type", type] : []),
+    ...positiveIntFlag("--limit", options.limit),
+  ]
+}
+
+export function buildLogArgs(message: unknown, options: { type?: unknown; files?: unknown; source?: unknown; status?: unknown } = {}): string[] {
+  const type = String(options.type ?? "note").toLowerCase()
+  if (!MEX_LOG_TYPES.includes(type as MexLogType)) throw new Error(`type must be one of ${MEX_LOG_TYPES.join(", ")}`)
+  const files = (Array.isArray(options.files) ? options.files : options.files ? [options.files] : []).map((file) => String(file ?? "").trim()).filter(Boolean)
+  const source = nonEmptyString(options.source) ?? "prism-agent"
+  const status = nonEmptyString(options.status)
+  return [
+    "log",
+    "--type",
+    type,
+    ...files.flatMap((file) => ["--file", file]),
+    "--source",
+    source,
+    ...(status ? ["--status", status] : []),
+    "--",
+    requiredText(message, "message"),
+  ]
+}
+
+// --- execution -------------------------------------------------------------
+
+export type MexRunResult = { ok: boolean; exitCode: number; output: string }
+
+export type MexRunOptions = {
+  cwd?: string
+  env?: NodeJS.ProcessEnv
+  timeoutMs?: number
+  maxBuffer?: number
+  runner?: MexExecRunner
+}
+
+export async function runMex(args: string[], options: MexRunOptions = {}): Promise<MexRunResult> {
+  const env = options.env ?? process.env
+  const runner = options.runner ?? execFileAsync
+  try {
+    const { stdout, stderr } = await runner(mexBinary(env), args, {
+      cwd: options.cwd ?? process.cwd(),
+      env: mexEnv(env),
+      timeout: options.timeoutMs ?? DEFAULT_MEX_TIMEOUT_MS,
+      maxBuffer: options.maxBuffer ?? 32 * 1024 * 1024,
+    })
+    const output = [String(stdout ?? ""), String(stderr ?? "")].join("\n").trim()
+    return { ok: true, exitCode: 0, output }
+  } catch (error: any) {
+    const output = [String(error?.stdout ?? ""), String(error?.stderr ?? ""), error?.message ? `ERROR: ${error.message}` : ""].filter((part) => part.trim()).join("\n").trim()
+    return { ok: false, exitCode: Number.isFinite(error?.code) ? Number(error.code) : 1, output: output || `ERROR: mex ${args[0] ?? ""} failed` }
+  }
+}

package/src/prism-extensions/core/mex-graph-db.ts

@@ -0,0 +1,76 @@
+import * as fs from "node:fs"
+import * as path from "node:path"
+import { buildGraphArgs, hasMexScaffold, mexScaffoldDir, runMex, type MexRunOptions } from "./mex-cli.js"
+
+/** SQLite code graph mex builds into the scaffold. */
+export const MEX_GRAPH_DB_FILE = "graph.db"
+export const DEFAULT_MEX_GRAPH_BUILD_TIMEOUT_MS = 300_000
+
+/** Actions that read the code graph and therefore need `.mex/graph.db`. */
+export const MEX_GRAPH_ACTIONS = ["scope", "get", "query", "impact"] as const
+
+export type MexGraphEnsureStatus = "present" | "built" | "failed" | "disabled" | "no-scaffold"
+export type MexGraphEnsureResult = { status: MexGraphEnsureStatus; path: string; output?: string }
+export type MexGraphEnsureOptions = MexRunOptions & { force?: boolean }
+
+export function mexGraphDbPath(cwd: string = process.cwd()): string {
+  return path.join(mexScaffoldDir(cwd), MEX_GRAPH_DB_FILE)
+}
+
+export function hasMexGraphDb(cwd: string = process.cwd()): boolean {
+  try {
+    const stats = fs.statSync(mexGraphDbPath(cwd))
+    return stats.isFile() && stats.size > 0
+  } catch {
+    return false
+  }
+}
+
+export function isMexAutoGraphEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.PRISM_DISABLE_MEX_AUTO_GRAPH !== "1"
+}
+
+export function needsMexGraphAction(action: string): boolean {
+  return (MEX_GRAPH_ACTIONS as readonly string[]).includes(action)
+}
+
+/** One build per scaffold at a time, so a session start and a tool call never race. */
+const inflightBuilds = new Map<string, Promise<MexGraphEnsureResult>>()
+
+/**
+ * Builds `.mex/graph.db` when it is missing (or when `force` is set).
+ * Never throws: mex degrades gracefully with GRAPH_UNAVAILABLE if the build fails.
+ */
+export async function ensureMexGraphDb(options: MexGraphEnsureOptions = {}): Promise<MexGraphEnsureResult> {
+  const cwd = options.cwd ?? process.cwd()
+  const env = options.env ?? process.env
+  const dbPath = mexGraphDbPath(cwd)
+  if (!isMexAutoGraphEnabled(env)) return { status: "disabled", path: dbPath }
+  if (!hasMexScaffold(cwd)) return { status: "no-scaffold", path: dbPath }
+  if (!options.force && hasMexGraphDb(cwd)) return { status: "present", path: dbPath }
+
+  const pending = inflightBuilds.get(dbPath)
+  if (pending) return pending
+  const build = buildMexGraphDb(cwd, dbPath, options).finally(() => inflightBuilds.delete(dbPath))
+  inflightBuilds.set(dbPath, build)
+  return build
+}
+
+async function buildMexGraphDb(cwd: string, dbPath: string, options: MexGraphEnsureOptions): Promise<MexGraphEnsureResult> {
+  const result = await runMex(buildGraphArgs({}), {
+    cwd,
+    env: options.env,
+    runner: options.runner,
+    maxBuffer: options.maxBuffer,
+    timeoutMs: options.timeoutMs ?? DEFAULT_MEX_GRAPH_BUILD_TIMEOUT_MS,
+  })
+  const built = result.ok && hasMexGraphDb(cwd)
+  return { status: built ? "built" : "failed", path: dbPath, output: result.output || undefined }
+}
+
+/** Short user-facing line for a build attempt, or undefined when nothing happened. */
+export function describeMexGraphEnsure(result: MexGraphEnsureResult): string | undefined {
+  if (result.status === "built") return `mex code graph built: ${result.path}`
+  if (result.status === "failed") return [`mex code graph build failed: ${result.path}`, result.output].filter(Boolean).join("\n")
+  return undefined
+}

package/src/prism-extensions/integrations/ai-memory-system.ts

@@ -276,8 +276,14 @@ export function formatAiMemoryToolCall(toolName: string, args: any, theme: Theme
  * ignores the per-turn query so a broken API does not warn on every prompt.
  */
 function reportBackgroundFailure(ctx: any, label: string, error: unknown): void {
-  const message = `AI Memory ${label} failed: ${error instanceof Error ? error.message : String(error)}`
-  const key = `${label}|${message.split(" | query=")[0]}`
+  const rawErrorMessage = error instanceof Error ? error.message : String(error)
+  // Background injection warnings should not be cluttered with the full
+  // query payload (often long JSON/string). Keep the code message still
+  // useful while making it readable.
+  const errorMessageForUser = rawErrorMessage.replace(/\s\|\squery=.*?(?=\s\|\sfilters=|$)/, "")
+
+  const message = `AI Memory ${label} failed: ${errorMessageForUser}`
+  const key = `${label}|${rawErrorMessage.split(" | query=")[0]}`
   if (reportedBackgroundFailures.has(key)) return
   reportedBackgroundFailures.add(key)
   ctx?.ui?.notify?.(message, "warning")
@@ -632,18 +638,33 @@ export default function aiMemorySystemExtension(pi: ExtensionAPI): void {
   pi.on?.("before_agent_start", async (event: any, ctx: any) => {
     const patch: { systemPrompt?: string; message?: any } = {}
 
+    // Background injection may fail when the local AI Memory HTTP daemon is
+    // down. We try every turn, but we only emit a single warning per turn to
+    // avoid spamming (and we also hide the full query payload).
+    let warnedThisTurn = false
+    const reportOnceThisTurn = (label: string, error: unknown) => {
+      if (warnedThisTurn) return
+      warnedThisTurn = true
+      reportBackgroundFailure(ctx, label, error)
+    }
+
     // Always-loaded durable context (mapped from 00 Kontext) is injected as a
     // system-prompt chunk so it remains in the cached prefix. It is opt-in so a
     // missing local AI Memory daemon does not produce startup/per-turn warnings.
     if (shouldInjectAiMemoryAlwaysContext()) {
       try {
-        const alwaysBlock = buildAlwaysContextMessage(await loadAlwaysContext())?.content?.trim()
+        // If the daemon is reachable again, allow warnings to re-appear on the
+        // next failure (clear the dedupe set on successful injection).
+        const alwaysContent = await loadAlwaysContext()
+        reportedBackgroundFailures.clear()
+
+        const alwaysBlock = buildAlwaysContextMessage(alwaysContent)?.content?.trim()
         if (alwaysBlock) {
           const prev = String(event?.systemPrompt ?? "")
           patch.systemPrompt = `${prev}${prev ? "\n\n" : ""}${alwaysBlock}`
         }
       } catch (error) {
-        reportBackgroundFailure(ctx, "always-context injection", error)
+        reportOnceThisTurn("always-context injection", error)
       }
     }
 
@@ -651,10 +672,13 @@ export default function aiMemorySystemExtension(pi: ExtensionAPI): void {
     const query = String(event?.prompt ?? "").trim()
     if (shouldInjectAiMemoryCandidates() && query) {
       try {
-        const message = buildAiMemoryContextMessage(await loadAiMemoryInjectResults(query))
+        const injectResults = await loadAiMemoryInjectResults(query)
+        reportedBackgroundFailures.clear()
+
+        const message = buildAiMemoryContextMessage(injectResults)
         if (message) patch.message = message
       } catch (error) {
-        reportBackgroundFailure(ctx, "candidate injection", error)
+        reportOnceThisTurn("candidate injection", error)
       }
     }
 

package/src/prism-extensions/integrations/mex-memory.ts

@@ -0,0 +1,264 @@
+import { Type } from "typebox"
+import {
+  buildCheckArgs,
+  buildGetArgs,
+  buildGraphArgs,
+  buildImpactArgs,
+  buildLogArgs,
+  buildQueryArgs,
+  buildScopeArgs,
+  buildTimelineArgs,
+  hasMexScaffold,
+  isMexAvailable,
+  MEX_LOG_TYPES,
+  MEX_RELATIONS,
+  runMex,
+  type MexRunOptions,
+} from "../core/mex-cli.js"
+import {
+  describeMexGraphEnsure,
+  ensureMexGraphDb,
+  hasMexGraphDb,
+  isMexAutoGraphEnabled,
+  needsMexGraphAction,
+  type MexGraphEnsureResult,
+} from "../core/mex-graph-db.js"
+import { textToolResult } from "../tools/toolbox-utils.js"
+import { formatBracketedToolCall, renderSingleLineToolCall, type ThemeLike } from "../ui/tool-call-rendering.js"
+
+type ExtensionAPI = any
+
+const MEX_STATUS_KEY = "mex"
+const MEX_STATUS_LABEL = "🕸 mex"
+const MEX_STATUS_BUILDING_LABEL = "🕸 mex ⟳"
+
+const RETRIEVAL_PARAMS = {
+  detail: Type.Optional(Type.String({ description: "minimal | standard | source. Default minimal." })),
+  maxNodes: Type.Optional(Type.Number({ description: "Maximum nodes to return." })),
+  maxOutputTokens: Type.Optional(Type.Number({ description: "Hard output token ceiling." })),
+  maxSourceLines: Type.Optional(Type.Number({ description: "Per-node source line cap (detail=source)." })),
+}
+
+export function formatMexOutput(action: string, result: { ok: boolean; exitCode: number; output: string }) {
+  const text = result.output || (result.ok ? `mex ${action} produced no output.` : `mex ${action} failed.`)
+  return textToolResult(text, { action, ok: result.ok, exitCode: result.exitCode })
+}
+
+/** Registers the mex code-graph tools. Exported for tests. */
+export function registerMexTools(pi: ExtensionAPI, options: MexRunOptions = {}): string[] {
+  const registered: string[] = []
+  const exec = async (action: string, args: string[]) => {
+    // For code-graph actions we must have a `.mex/` scaffold.
+    // Otherwise `mex` itself may auto-create the scaffold/DB, which we explicitly want to avoid.
+    if (needsMexGraphAction(action)) {
+      const ensured = await ensureMexGraphDb(graphEnsureOptions(options))
+      if (ensured.status === "no-scaffold" || ensured.status === "disabled") {
+        return formatMexOutput(action, {
+          ok: false,
+          exitCode: 1,
+          output: `mex ${action} disabled: missing .mex scaffold (needed for graph.db). Run npx mex-agent setup in the repo root, or disable mex via PRISM_DISABLE_MEX=1.`,
+        })
+      }
+    }
+    return formatMexOutput(action, await runMex(args, options))
+  }
+
+  function register(tool: any): void {
+    registered.push(tool.name)
+    pi.registerTool(tool)
+  }
+
+  register({
+    name: "mex_scope",
+    label: "Mex Scope",
+    description: "Retrieve a compact, task-relevant code neighborhood from the local mex code graph (JSONL: symbols, signatures, relations, node ids).",
+    promptSnippet: "Use mex_scope first for codebase questions to get a compact set of relevant symbols instead of scanning files.",
+    promptGuidelines: [
+      "Describe the task in natural language, e.g. 'trace the authentication flow'.",
+      "Scope matching is word-based, not semantic. If results look weak, rephrase once, then fall back to grep/read.",
+      "Expand promising node ids with mex_get instead of reading whole files.",
+    ],
+    parameters: Type.Object({
+      task: Type.String({ description: "Task description, e.g. 'trace the authentication flow'." }),
+      ...RETRIEVAL_PARAMS,
+      fingerprint: Type.Optional(Type.Boolean({ description: "Attach node fingerprints (grounding workflow)." })),
+    }),
+    async execute(_id: string, params: any) {
+      return exec("scope", buildScopeArgs(params.task, params))
+    },
+    renderCall(args: any, theme: ThemeLike, context: any) {
+      return renderSingleLineToolCall(formatBracketedToolCall("mex scope", args?.task, theme), context)
+    },
+  })
+
+  register({
+    name: "mex_get",
+    label: "Mex Get",
+    description: "Expand source code for specific mex code-graph node ids returned by mex_scope, mex_query, or mex_impact.",
+    promptSnippet: "Expand mex node ids to source instead of reading whole files.",
+    parameters: Type.Object({
+      ids: Type.Array(Type.String({ description: "Node id, e.g. function:a3f8...c21" })),
+      maxSourceLines: Type.Optional(Type.Number({ description: "Per-node source line cap." })),
+      maxOutputTokens: Type.Optional(Type.Number({ description: "Hard output token ceiling." })),
+    }),
+    async execute(_id: string, params: any) {
+      return exec("get", buildGetArgs(params.ids, params))
+    },
+    renderCall(args: any, theme: ThemeLike, context: any) {
+      const ids = Array.isArray(args?.ids) ? args.ids : []
+      return renderSingleLineToolCall(formatBracketedToolCall("mex get", ids.length > 1 ? `${ids[0]} +${ids.length - 1}` : ids[0], theme), context)
+    },
+  })
+
+  register({
+    name: "mex_query",
+    label: "Mex Query",
+    description: `Query structural code relations in the mex graph: ${MEX_RELATIONS.join(", ")}.`,
+    promptSnippet: "Use mex_query for precise structural questions like who calls a function or where a symbol is defined.",
+    parameters: Type.Object({
+      relation: Type.String({ description: MEX_RELATIONS.join(" | ") }),
+      target: Type.String({ description: "Symbol or file name." }),
+      ...RETRIEVAL_PARAMS,
+    }),
+    async execute(_id: string, params: any) {
+      return exec("query", buildQueryArgs(params.relation, params.target, params))
+    },
+    renderCall(args: any, theme: ThemeLike, context: any) {
+      return renderSingleLineToolCall(formatBracketedToolCall("mex query", [args?.relation, args?.target].filter(Boolean).join(" "), theme), context)
+    },
+  })
+
+  register({
+    name: "mex_impact",
+    label: "Mex Impact",
+    description: "Show the transitive code and wiki blast radius for a symbol or file before refactoring.",
+    promptSnippet: "Use mex_impact before refactors to see what a symbol or file change touches.",
+    parameters: Type.Object({
+      target: Type.String({ description: "Symbol name or file path." }),
+      depth: Type.Optional(Type.Number({ description: "Transitive caller depth. Default 2." })),
+      ...RETRIEVAL_PARAMS,
+    }),
+    async execute(_id: string, params: any) {
+      return exec("impact", buildImpactArgs(params.target, params))
+    },
+    renderCall(args: any, theme: ThemeLike, context: any) {
+      return renderSingleLineToolCall(formatBracketedToolCall("mex impact", args?.target, theme), context)
+    },
+  })
+
+  register({
+    name: "mex_log",
+    label: "Mex Log",
+    description: `Append a ${MEX_LOG_TYPES.join("/")} entry to the repo-local mex event log (.mex/events).`,
+    promptSnippet: "Log durable repo decisions, risks, or todos into the mex event log.",
+    promptGuidelines: [
+      "Log decisions only when they are actually settled in this conversation.",
+      "Keep entries short and repo-specific; no secrets, credentials, or private hostnames.",
+    ],
+    parameters: Type.Object({
+      message: Type.String({ description: "Short entry text." }),
+      type: Type.Optional(Type.String({ description: `${MEX_LOG_TYPES.join(" | ")}. Default note.` })),
+      files: Type.Optional(Type.Array(Type.String({ description: "Related file path." }))),
+      status: Type.Optional(Type.String({ description: "Lifecycle status, e.g. decided or implemented." })),
+    }),
+    async execute(_id: string, params: any) {
+      return exec("log", buildLogArgs(params.message, params))
+    },
+    renderCall(args: any, theme: ThemeLike, context: any) {
+      return renderSingleLineToolCall(formatBracketedToolCall(`mex log ${String(args?.type ?? "note")}`, args?.message, theme), context)
+    },
+  })
+
+  return registered
+}
+
+export default function mexMemoryExtension(pi: ExtensionAPI): void {
+  const cwd = process.cwd()
+  if (!isMexAvailable(process.env, cwd)) return
+
+  registerMexTools(pi, { cwd })
+
+  pi.on?.("session_start", (_event: any, ctx: any) => {
+    ctx?.ui?.setStatus?.(MEX_STATUS_KEY, mexStatusLabel(cwd))
+    void autoBuildMissingGraph(cwd, ctx)
+  })
+
+  pi.registerCommand("mex", {
+    description: "Mex code graph: /mex [status] | graph | check | timeline | scope <task>",
+    handler: async (args: string, ctx: any) => {
+      const [sub, ...rest] = (args || "").trim().split(/\s+/)
+      const argument = rest.join(" ").trim()
+      const action = (sub || "status").toLowerCase()
+      try {
+        if (action === "status") {
+          const result = await runMex(buildCheckArgs({ quiet: true }), { cwd })
+          const lines = [
+            `mex scaffold: ${hasMexScaffold(cwd) ? mexPathLabel(cwd) : "missing"}`,
+            `mex graph.db: ${hasMexGraphDb(cwd) ? "present" : isMexAutoGraphEnabled() ? "missing (auto-build on demand)" : "missing (auto-build disabled)"}`,
+            result.output,
+          ]
+          ctx.ui.notify(lines.filter(Boolean).join("\n"), result.ok ? "info" : "warning")
+          return
+        }
+        if (action === "graph") {
+          // Never let `mex graph` create a scaffold/DB in `~/.mex` when we're running outside a repo scaffold.
+          // Don't rebuild when graph.db already exists; just skip to avoid touching ~/.mex.
+          const ensured = await ensureMexGraphDb({ cwd, env: process.env, runner: undefined, timeoutMs: 300_000 })
+          const message = describeMexGraphEnsure(ensured)
+          if (message) ctx.ui.notify(message, ensured.status === "built" ? "info" : "warning")
+          else ctx.ui.notify("mex graph skipped.", ensured.status === "built" ? "info" : "warning")
+          return
+        }
+        if (action === "check") {
+          const result = await runMex(buildCheckArgs({}), { cwd, timeoutMs: 300_000 })
+          ctx.ui.notify(result.output || "No drift output.", result.ok ? "info" : "warning")
+          return
+        }
+        if (action === "timeline") {
+          const result = await runMex(buildTimelineArgs({ limit: 20 }), { cwd })
+          ctx.ui.notify(result.output || "No mex events.", "info")
+          return
+        }
+        if (action === "scope") {
+          if (!argument) return ctx.ui.notify("Usage: /mex scope <task>", "warning")
+          const result = await runMex(buildScopeArgs(argument, {}), { cwd })
+          ctx.ui.notify(result.output || "No scope results.", result.ok ? "info" : "warning")
+          return
+        }
+        ctx.ui.notify("Usage: /mex [status] | graph | check | timeline | scope <task>", "warning")
+      } catch (error) {
+        ctx.ui.notify(`mex command failed:\n${error instanceof Error ? error.message : String(error)}`, "error")
+      }
+    },
+  })
+}
+
+function mexPathLabel(cwd: string): string {
+  return `${cwd.replace(/\/+$/, "")}/.mex`
+}
+
+function graphEnsureOptions(options: MexRunOptions): MexRunOptions {
+  return { cwd: options.cwd, env: options.env, runner: options.runner }
+}
+
+/** Only a scaffold with a usable code graph counts as "mex is working"; otherwise the segment stays hidden. */
+export function mexStatusLabel(cwd: string = process.cwd()): string | undefined {
+  return hasMexScaffold(cwd) && hasMexGraphDb(cwd) ? MEX_STATUS_LABEL : undefined
+}
+
+/** Builds a missing code graph in the background so the first graph tool call is not blocked. */
+async function autoBuildMissingGraph(cwd: string, ctx: any): Promise<MexGraphEnsureResult | undefined> {
+  if (!hasMexScaffold(cwd) || hasMexGraphDb(cwd) || !isMexAutoGraphEnabled()) return undefined
+  ctx?.ui?.setStatus?.(MEX_STATUS_KEY, MEX_STATUS_BUILDING_LABEL)
+  try {
+    const result = await ensureMexGraphDb({ cwd })
+    const message = describeMexGraphEnsure(result)
+    if (message) ctx?.ui?.notify?.(message, result.status === "built" ? "info" : "warning")
+    return result
+  } catch (error) {
+    ctx?.ui?.notify?.(`mex graph build failed:\n${error instanceof Error ? error.message : String(error)}`, "warning")
+    return undefined
+  } finally {
+    ctx?.ui?.setStatus?.(MEX_STATUS_KEY, mexStatusLabel(cwd))
+  }
+}

package/src/prism-extensions/tools/builtin-tools.ts

@@ -2,6 +2,7 @@ import type { ToolboxToolDefinition } from "./toolbox.js"
 import { createDiagnosticToolboxTools } from "./diagnostic-tools.js"
 import { createPrismDiagnosticToolboxTools } from "./prism-diagnostic-tools.js"
 import { createSshConfigTool } from "./ssh-config-tool.js"
+import { createMexToolboxTools } from "./mex-tools.js"
 
 export function defineToolboxTool(definition: ToolboxToolDefinition): ToolboxToolDefinition {
   return { source: "toolbox/builtin", ...definition }
@@ -11,6 +12,7 @@ export const builtinToolboxTools: ToolboxToolDefinition[] = [
   createSshConfigTool(),
   ...createDiagnosticToolboxTools(),
   ...createPrismDiagnosticToolboxTools(),
+  ...createMexToolboxTools(),
 ]
 
 export function createBuiltinToolboxTools(): ToolboxToolDefinition[] {