@infinitedusky/indusk-mcp 1.6.7 → 1.7.3

package/dist/bin/cli.js

@@ -105,6 +105,30 @@ program
     const { checkGates } = await import("./commands/check-gates.js");
     await checkGates(process.cwd(), { file: opts.file, phase: opts.phase });
 });
+const infra = program
+    .command("infra")
+    .description("Manage the indusk-infra container (FalkorDB + Graphiti)");
+infra
+    .command("start")
+    .description("Start the infrastructure container (creates if needed)")
+    .action(async () => {
+    const { infraStart } = await import("./commands/infra.js");
+    await infraStart();
+});
+infra
+    .command("stop")
+    .description("Stop the infrastructure container (preserves data)")
+    .action(async () => {
+    const { infraStop } = await import("./commands/infra.js");
+    await infraStop();
+});
+infra
+    .command("status")
+    .description("Show infrastructure container health and configuration")
+    .action(async () => {
+    const { infraStatus } = await import("./commands/infra.js");
+    await infraStatus();
+});
 program
     .command("serve")
     .description("Start the MCP server (used by Claude Code via .mcp.json)")

package/dist/bin/commands/infra.d.ts

@@ -0,0 +1,3 @@
+export declare function infraStart(): Promise<void>;
+export declare function infraStop(): Promise<void>;
+export declare function infraStatus(): Promise<void>;

package/dist/bin/commands/infra.js

@@ -0,0 +1,222 @@
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const CONTAINER_NAME = "indusk-infra";
+const IMAGE_NAME = "indusk-infra";
+const VOLUME_NAME = "indusk-data";
+const CONFIG_DIR = join(homedir(), ".indusk");
+const CONFIG_FILE = join(CONFIG_DIR, "config.env");
+function run(cmd, timeout = 10000) {
+    try {
+        return execSync(cmd, {
+            encoding: "utf-8",
+            timeout,
+            stdio: ["ignore", "pipe", "pipe"],
+        }).trim();
+    }
+    catch {
+        return "";
+    }
+}
+function loadConfig() {
+    const config = {};
+    if (!existsSync(CONFIG_FILE))
+        return config;
+    const content = readFileSync(CONFIG_FILE, "utf-8");
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const eq = trimmed.indexOf("=");
+        if (eq === -1)
+            continue;
+        config[trimmed.slice(0, eq)] = trimmed.slice(eq + 1);
+    }
+    return config;
+}
+function ensureConfig() {
+    if (!existsSync(CONFIG_DIR)) {
+        mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+    if (!existsSync(CONFIG_FILE)) {
+        writeFileSync(CONFIG_FILE, [
+            "# InDusk global configuration",
+            "# This file is read by `indusk infra start` to configure the infrastructure container.",
+            "",
+            "# Required for Graphiti (Gemini LLM/embeddings). Get from https://aistudio.google.com/apikey",
+            "GOOGLE_API_KEY=",
+            "",
+            "# Optional: OTel export endpoint (e.g., https://api.region.gcp.dash0.com)",
+            "# OTEL_EXPORTER_OTLP_ENDPOINT=",
+            "# OTEL_EXPORTER_OTLP_HEADERS=",
+            "# OTEL_SERVICE_NAME=indusk-infra",
+            "",
+        ].join("\n"));
+        console.info(`Created ${CONFIG_FILE}`);
+        console.info("");
+        console.info("Add your GOOGLE_API_KEY to this file:");
+        console.info(`  ${CONFIG_FILE}`);
+        console.info("");
+        console.info("Get a key from: https://aistudio.google.com/apikey");
+        console.info("Without it, FalkorDB works but Graphiti will not (graceful degradation).");
+    }
+    return loadConfig();
+}
+function getContainerStatus() {
+    const running = run(`docker ps --filter name=^${CONTAINER_NAME}$ --format '{{.Status}}'`);
+    if (running)
+        return "running";
+    const exists = run(`docker ps -a --filter name=^${CONTAINER_NAME}$ --format '{{.Status}}'`);
+    if (exists)
+        return "stopped";
+    return "missing";
+}
+export async function infraStart() {
+    const status = getContainerStatus();
+    if (status === "running") {
+        console.info(`${CONTAINER_NAME} is already running.`);
+        await infraStatus();
+        return;
+    }
+    if (status === "stopped") {
+        console.info(`Starting ${CONTAINER_NAME}...`);
+        const result = run(`docker start ${CONTAINER_NAME}`);
+        if (result) {
+            console.info("Started.");
+            // Wait for FalkorDB to be ready
+            await waitForReady();
+            await infraStatus();
+        }
+        else {
+            console.error(`Failed to start ${CONTAINER_NAME}.`);
+            process.exitCode = 1;
+        }
+        return;
+    }
+    // Container doesn't exist — check for image, then create
+    const hasImage = run(`docker images -q ${IMAGE_NAME}`);
+    if (!hasImage) {
+        console.error(`Docker image '${IMAGE_NAME}' not found.`);
+        console.error("");
+        console.error("Build it from the infinitedusky repo:");
+        console.error("  docker build -f docker/Dockerfile.infra -t indusk-infra .");
+        console.error("");
+        console.error("Or pull from GHCR (when published):");
+        console.error("  docker pull ghcr.io/infinitedusky/indusk-infra:latest");
+        process.exitCode = 1;
+        return;
+    }
+    // Load config for env vars
+    const config = ensureConfig();
+    const envArgs = [];
+    if (config.GOOGLE_API_KEY) {
+        envArgs.push(`-e GOOGLE_API_KEY=${config.GOOGLE_API_KEY}`);
+    }
+    else {
+        console.warn("Warning: GOOGLE_API_KEY not set in ~/.indusk/config.env — Graphiti will not work.");
+    }
+    if (config.OTEL_EXPORTER_OTLP_ENDPOINT) {
+        envArgs.push(`-e OTEL_EXPORTER_OTLP_ENDPOINT=${config.OTEL_EXPORTER_OTLP_ENDPOINT}`);
+    }
+    if (config.OTEL_EXPORTER_OTLP_HEADERS) {
+        envArgs.push(`-e OTEL_EXPORTER_OTLP_HEADERS=${config.OTEL_EXPORTER_OTLP_HEADERS}`);
+    }
+    if (config.OTEL_SERVICE_NAME) {
+        envArgs.push(`-e OTEL_SERVICE_NAME=${config.OTEL_SERVICE_NAME}`);
+    }
+    console.info(`Creating ${CONTAINER_NAME}...`);
+    const createCmd = [
+        "docker run -d",
+        `--name ${CONTAINER_NAME}`,
+        "-p 6379:6379",
+        "-p 8100:8100",
+        `-v ${VOLUME_NAME}:/data`,
+        "--restart unless-stopped",
+        ...envArgs,
+        IMAGE_NAME,
+    ].join(" ");
+    const result = run(createCmd, 30000);
+    if (result) {
+        console.info("Created.");
+        await waitForReady();
+        await infraStatus();
+    }
+    else {
+        console.error("Failed to create container.");
+        console.error(`Command: ${createCmd}`);
+        process.exitCode = 1;
+    }
+}
+export async function infraStop() {
+    const status = getContainerStatus();
+    if (status === "missing") {
+        console.info(`${CONTAINER_NAME} does not exist.`);
+        return;
+    }
+    if (status === "stopped") {
+        console.info(`${CONTAINER_NAME} is already stopped.`);
+        return;
+    }
+    console.info(`Stopping ${CONTAINER_NAME}...`);
+    const result = run(`docker stop ${CONTAINER_NAME}`, 30000);
+    if (result) {
+        console.info("Stopped. Data preserved in volume.");
+    }
+    else {
+        console.error("Failed to stop container.");
+        process.exitCode = 1;
+    }
+}
+export async function infraStatus() {
+    const status = getContainerStatus();
+    console.info(`Container: ${CONTAINER_NAME}`);
+    console.info(`Status:    ${status}`);
+    if (status !== "running") {
+        if (status === "stopped") {
+            console.info("\nRun `indusk infra start` to start.");
+        }
+        else {
+            console.info("\nRun `indusk infra start` to create and start.");
+        }
+        return;
+    }
+    // FalkorDB health
+    const pong = run("redis-cli -h localhost ping");
+    console.info(`FalkorDB:  ${pong === "PONG" ? "healthy" : "unreachable"}`);
+    // Graph count
+    if (pong === "PONG") {
+        const graphs = run("redis-cli -h localhost GRAPH.LIST");
+        const graphList = graphs ? graphs.split("\n").filter((l) => l.trim()) : [];
+        console.info(`Graphs:    ${graphList.length} (${graphList.join(", ")})`);
+    }
+    // Graphiti health
+    try {
+        const health = run("curl -sf http://localhost:8100/health", 5000);
+        if (health) {
+            console.info("Graphiti:  healthy");
+        }
+        else {
+            console.info("Graphiti:  starting or unreachable");
+        }
+    }
+    catch {
+        console.info("Graphiti:  unreachable");
+    }
+    // Config
+    const config = loadConfig();
+    console.info(`API Key:   ${config.GOOGLE_API_KEY ? "configured" : "not set"}`);
+    console.info(`OTel:      ${config.OTEL_EXPORTER_OTLP_ENDPOINT ? "enabled" : "disabled"}`);
+}
+async function waitForReady() {
+    console.info("Waiting for FalkorDB...");
+    for (let i = 0; i < 10; i++) {
+        const pong = run("redis-cli -h localhost ping");
+        if (pong === "PONG") {
+            console.info("FalkorDB ready.");
+            return;
+        }
+        await new Promise((r) => setTimeout(r, 2000));
+    }
+    console.warn("FalkorDB did not respond within 20s — may still be loading.");
+}

package/dist/bin/commands/init.js

@@ -127,19 +127,79 @@ export async function init(projectRoot, options = {}) {
         }
         catch { }
     }
-    // Add indusk MCP server (no secrets)
+    // Add indusk MCP server — prefer global binary, fall back to npx
+    const hasGlobalIndusk = run("which indusk") || run("where indusk");
+    const induskCommand = hasGlobalIndusk
+        ? "claude mcp add -t stdio -s project -e PROJECT_ROOT=. -- indusk indusk serve"
+        : "claude mcp add -t stdio -s project -e PROJECT_ROOT=. -- indusk npx --yes @infinitedusky/indusk-mcp serve";
     if (!existingServers.has("indusk") || force) {
         try {
-            execSync(`claude mcp add -t stdio -s project -e PROJECT_ROOT=. -- indusk npx --yes @infinitedusky/indusk-mcp serve`, { cwd: projectRoot, stdio: "pipe", timeout: 10000 });
-            console.info("  added: indusk MCP server (via claude mcp add)");
+            execSync(induskCommand, { cwd: projectRoot, stdio: "pipe", timeout: 10000 });
+            console.info(`  added: indusk MCP server (${hasGlobalIndusk ? "global binary" : "via npx"})`);
         }
         catch {
             console.info("  failed: could not add indusk MCP server — run manually:");
-            console.info("    claude mcp add -t stdio -s project -e PROJECT_ROOT=. -- indusk npx --yes @infinitedusky/indusk-mcp serve");
+            console.info(`    ${induskCommand}`);
         }
     }
     else {
-        console.info("  skip: indusk MCP server (already exists)");
+        // Migrate from npx to global binary if available
+        if (hasGlobalIndusk) {
+            try {
+                const mcpConfig = JSON.parse(readFileSync(mcpJsonPath, "utf-8"));
+                const induskArgs = mcpConfig.mcpServers?.indusk?.args;
+                if (induskArgs?.includes("npx")) {
+                    execSync(induskCommand, { cwd: projectRoot, stdio: "pipe", timeout: 10000 });
+                    console.info("  migrated: indusk MCP server (npx → global binary)");
+                }
+                else {
+                    console.info("  skip: indusk MCP server (already exists)");
+                }
+            }
+            catch {
+                console.info("  skip: indusk MCP server (already exists)");
+            }
+        }
+        else {
+            console.info("  skip: indusk MCP server (already exists)");
+        }
+    }
+    // Install CGC if not present
+    const cgcInstalled = run("cgc --version");
+    if (cgcInstalled) {
+        console.info(`  skip: codegraphcontext (${cgcInstalled})`);
+    }
+    else {
+        const hasPipx = run("pipx --version");
+        if (hasPipx) {
+            console.info("  installing: codegraphcontext via pipx...");
+            try {
+                execSync("pipx install codegraphcontext", {
+                    timeout: 60000,
+                    stdio: ["ignore", "pipe", "pipe"],
+                });
+                console.info("  installed: codegraphcontext");
+            }
+            catch {
+                console.info("  failed: could not install codegraphcontext — run manually:");
+                console.info("    pipx install codegraphcontext");
+            }
+        }
+        else {
+            console.info("  skip: codegraphcontext (pipx not found — install pipx first, then: pipx install codegraphcontext)");
+        }
+    }
+    // Migrate CGC config: falkordb.orb.local → localhost (indusk-infra container)
+    if (existingServers.has("codegraphcontext") && !force) {
+        try {
+            const mcpConfig = JSON.parse(readFileSync(mcpJsonPath, "utf-8"));
+            const cgcEnv = mcpConfig.mcpServers?.codegraphcontext?.env;
+            if (cgcEnv?.FALKORDB_HOST === "falkordb.orb.local") {
+                execSync(`claude mcp add -t stdio -s project -e DATABASE_TYPE=falkordb-remote -e FALKORDB_HOST=localhost -e FALKORDB_GRAPH_NAME=${cgcEnv.FALKORDB_GRAPH_NAME || `cgc-${projectName}`} -- codegraphcontext cgc mcp start`, { cwd: projectRoot, stdio: "pipe", timeout: 10000 });
+                console.info("  migrated: codegraphcontext FALKORDB_HOST → localhost (indusk-infra)");
+            }
+        }
+        catch { }
     }
     // Add codegraphcontext MCP server (no secrets)
     if (!existingServers.has("codegraphcontext") || force) {
@@ -155,6 +215,45 @@ export async function init(projectRoot, options = {}) {
     else {
         console.info("  skip: codegraphcontext MCP server (already exists)");
     }
+    // 4b. Check infrastructure container
+    console.info("\n[Infrastructure]");
+    try {
+        const infraStatus = execSync("docker inspect --format='{{.State.Running}}' indusk-infra", {
+            encoding: "utf-8",
+            timeout: 5000,
+            stdio: ["ignore", "pipe", "pipe"],
+        }).trim();
+        if (infraStatus === "true") {
+            console.info("  ok: indusk-infra container is running");
+        }
+        else {
+            console.info("  starting: indusk-infra container...");
+            execSync("docker start indusk-infra", {
+                timeout: 15000,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            console.info("  started: indusk-infra");
+        }
+    }
+    catch {
+        console.info("  skip: indusk-infra container not found");
+        console.info("    To set up infrastructure: indusk infra start");
+    }
+    // 4c. Copy Graphiti extension manifest
+    const graphitiExtDir = join(projectRoot, ".indusk/extensions/graphiti");
+    const graphitiManifest = join(graphitiExtDir, "manifest.json");
+    if (existsSync(graphitiManifest) && !force) {
+        console.info("  skip: graphiti extension (already exists)");
+    }
+    else {
+        mkdirSync(graphitiExtDir, { recursive: true });
+        cpSync(join(packageRoot, "extensions/graphiti/manifest.json"), graphitiManifest);
+        const skillSource = join(packageRoot, "extensions/graphiti/skill.md");
+        if (existsSync(skillSource)) {
+            cpSync(skillSource, join(graphitiExtDir, "skill.md"));
+        }
+        console.info("  create: .indusk/extensions/graphiti/ (manifest + skill)");
+    }
     // 5. Generate .vscode/settings.json
     console.info("\n[Editor]");
     const vscodePath = join(projectRoot, ".vscode/settings.json");
@@ -295,6 +394,41 @@ export async function init(projectRoot, options = {}) {
             console.info("  wire: node --import ./src/instrumentation.ts src/index.ts");
         }
     } // end isInduskMcp else
+    // 7b. Next.js webpack config — ensure --webpack dev script and aggregateTimeout watchOptions
+    if (!isInduskMcp) {
+        const nextConfigs = ["next.config.ts", "next.config.js", "next.config.mjs"].map((f) => join(projectRoot, f));
+        const nextConfigPath = nextConfigs.find((f) => existsSync(f));
+        if (nextConfigPath) {
+            console.info("\n[Next.js Webpack Config]");
+            const configContent = readFileSync(nextConfigPath, "utf-8");
+            if (!configContent.includes("aggregateTimeout")) {
+                console.info(`  warn: ${nextConfigPath.split("/").pop()} is missing aggregateTimeout in webpack watchOptions`);
+                console.info("  add the following to your next.config:");
+                console.info("    webpack: (config) => {");
+                console.info("      config.watchOptions = { ...config.watchOptions, aggregateTimeout: 600 };");
+                console.info("      return config;");
+                console.info("    }");
+            }
+            else {
+                console.info(`  ok: aggregateTimeout configured in ${nextConfigPath.split("/").pop()}`);
+            }
+            // Check dev script for --turbopack
+            const pkgJsonPath = join(projectRoot, "package.json");
+            if (existsSync(pkgJsonPath)) {
+                const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+                const devScript = pkgJson.scripts?.dev || "";
+                if (devScript.includes("--turbopack")) {
+                    console.info("  warn: dev script uses --turbopack — remove it");
+                    console.info("  Turbopack's 1ms file watcher debounce causes crashes with external tool writes on macOS");
+                    console.info("  Next.js <16: plain 'next dev' uses webpack by default");
+                    console.info("  Next.js 16+: use 'next dev --webpack' to opt out of Turbopack");
+                }
+                else {
+                    console.info("  ok: dev script does not use Turbopack");
+                }
+            }
+        }
+    }
     // 8. Install gate enforcement hooks
     console.info("\n[Hooks]");
     const hooksSource = join(packageRoot, "hooks");
@@ -473,7 +607,8 @@ export async function init(projectRoot, options = {}) {
     console.info("\nDone!");
     console.info("\n⚠  Restart Claude Code to load the updated MCP server and skills.");
     console.info("\nNext steps:");
-    console.info("  1. Restart Claude Code");
-    console.info("  2. Edit CLAUDE.md with your project details");
-    console.info("  3. Start planning: /plan your-first-feature");
+    console.info("  1. Set up infrastructure (if not done): indusk infra start");
+    console.info("  2. Restart Claude Code");
+    console.info("  3. Edit CLAUDE.md with your project details");
+    console.info("  4. Start planning: /plan your-first-feature");
 }

package/dist/lib/graphiti-client.d.ts

@@ -0,0 +1,93 @@
+interface AddEpisodeOptions {
+    groupId?: string;
+    source?: string;
+    sourceDescription?: string;
+}
+interface SearchOptions {
+    groupIds?: string[];
+    maxResults?: number;
+}
+interface GraphitiNode {
+    name: string;
+    uuid: string;
+    summary: string;
+    group_id: string;
+    [key: string]: unknown;
+}
+interface GraphitiFact {
+    uuid: string;
+    fact: string;
+    valid_at: string | null;
+    invalid_at: string | null;
+    [key: string]: unknown;
+}
+/**
+ * MCP client wrapper for the Graphiti temporal knowledge graph.
+ *
+ * Connects to the Graphiti MCP server running inside the indusk-infra container.
+ * Lazy connection — connects on first call, not at construction.
+ * Graceful degradation — returns null/empty on connection failure, never throws.
+ */
+export declare class GraphitiClient {
+    private client;
+    private transport;
+    private connected;
+    private connecting;
+    private serverUrl;
+    private projectName;
+    constructor(projectName: string, serverUrl?: string);
+    /**
+     * Lazily connect to the Graphiti MCP server.
+     * Returns true if connected, false if connection failed.
+     * Multiple concurrent calls share the same connection attempt.
+     */
+    connect(): Promise<boolean>;
+    private doConnect;
+    private getClient;
+    /**
+     * Add an episode to the knowledge graph.
+     *
+     * @param name - Short name for the episode (e.g., "auth-refactor decision")
+     * @param body - Episode content to extract entities and facts from
+     * @param options - groupId defaults to project name, source defaults to "text"
+     * @returns Success response or null on failure
+     */
+    addEpisode(name: string, body: string, options?: AddEpisodeOptions): Promise<{
+        success: boolean;
+    } | null>;
+    /**
+     * Search for entity nodes in the knowledge graph.
+     *
+     * @param query - Natural language search query
+     * @param options - groupIds defaults to [projectName, "shared"] for cross-group search
+     * @returns Array of matching nodes, or empty array on failure
+     */
+    searchNodes(query: string, options?: SearchOptions): Promise<GraphitiNode[]>;
+    /**
+     * Search for facts (relationships between entities) in the knowledge graph.
+     *
+     * @param query - Natural language search query
+     * @param options - groupIds defaults to [projectName, "shared"] for cross-group search
+     * @returns Array of matching facts, or empty array on failure
+     */
+    searchFacts(query: string, options?: SearchOptions): Promise<GraphitiFact[]>;
+    /**
+     * Check if the Graphiti server is reachable and healthy.
+     *
+     * @returns Status object or null if unreachable
+     */
+    getStatus(): Promise<{
+        status: string;
+    } | null>;
+    /**
+     * Resolve group IDs for search — always includes "shared" for cross-group search.
+     * If caller provides groupIds, uses those. Otherwise defaults to [projectName, "shared"].
+     * Deduplicates "shared" if already present.
+     */
+    private resolveGroupIds;
+    /**
+     * Disconnect from the Graphiti MCP server.
+     */
+    disconnect(): Promise<void>;
+}
+export {};

package/dist/lib/graphiti-client.js

@@ -0,0 +1,209 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { getInfraConfig } from "./infra-config.js";
+/**
+ * MCP client wrapper for the Graphiti temporal knowledge graph.
+ *
+ * Connects to the Graphiti MCP server running inside the indusk-infra container.
+ * Lazy connection — connects on first call, not at construction.
+ * Graceful degradation — returns null/empty on connection failure, never throws.
+ */
+export class GraphitiClient {
+    client = null;
+    transport = null;
+    connected = false;
+    connecting = null;
+    serverUrl;
+    projectName;
+    constructor(projectName, serverUrl) {
+        this.projectName = projectName;
+        this.serverUrl = serverUrl ?? getInfraConfig().graphiti.url;
+    }
+    /**
+     * Lazily connect to the Graphiti MCP server.
+     * Returns true if connected, false if connection failed.
+     * Multiple concurrent calls share the same connection attempt.
+     */
+    async connect() {
+        if (this.connected)
+            return true;
+        if (this.connecting)
+            return this.connecting;
+        this.connecting = this.doConnect();
+        const result = await this.connecting;
+        this.connecting = null;
+        return result;
+    }
+    async doConnect() {
+        try {
+            // Normalize URL — Graphiti redirects /mcp/ to /mcp
+            const url = this.serverUrl.endsWith("/") ? this.serverUrl.slice(0, -1) : this.serverUrl;
+            this.transport = new StreamableHTTPClientTransport(new URL(url));
+            this.client = new Client({ name: "indusk-mcp", version: "1.0.0" });
+            await this.client.connect(this.transport);
+            this.connected = true;
+            return true;
+        }
+        catch {
+            this.client = null;
+            this.transport = null;
+            this.connected = false;
+            return false;
+        }
+    }
+    getClient() {
+        if (!this.client)
+            throw new Error("Not connected");
+        return this.client;
+    }
+    /**
+     * Add an episode to the knowledge graph.
+     *
+     * @param name - Short name for the episode (e.g., "auth-refactor decision")
+     * @param body - Episode content to extract entities and facts from
+     * @param options - groupId defaults to project name, source defaults to "text"
+     * @returns Success response or null on failure
+     */
+    async addEpisode(name, body, options) {
+        if (!(await this.connect()))
+            return null;
+        try {
+            const result = await this.getClient().callTool({
+                name: "add_memory",
+                arguments: {
+                    name,
+                    episode_body: body,
+                    group_id: options?.groupId ?? this.projectName,
+                    source: options?.source ?? "text",
+                    source_description: options?.sourceDescription ?? "",
+                },
+            });
+            return { success: !result.isError };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Search for entity nodes in the knowledge graph.
+     *
+     * @param query - Natural language search query
+     * @param options - groupIds defaults to [projectName, "shared"] for cross-group search
+     * @returns Array of matching nodes, or empty array on failure
+     */
+    async searchNodes(query, options) {
+        if (!(await this.connect()))
+            return [];
+        const groupIds = this.resolveGroupIds(options?.groupIds);
+        try {
+            const result = await this.getClient().callTool({
+                name: "search_nodes",
+                arguments: {
+                    query,
+                    group_ids: groupIds,
+                    max_nodes: options?.maxResults ?? 10,
+                },
+            });
+            if (result.isError)
+                return [];
+            const content = result.content;
+            const text = content?.[0];
+            if (text?.text) {
+                const parsed = JSON.parse(text.text);
+                return parsed.nodes ?? parsed ?? [];
+            }
+            return [];
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Search for facts (relationships between entities) in the knowledge graph.
+     *
+     * @param query - Natural language search query
+     * @param options - groupIds defaults to [projectName, "shared"] for cross-group search
+     * @returns Array of matching facts, or empty array on failure
+     */
+    async searchFacts(query, options) {
+        if (!(await this.connect()))
+            return [];
+        const groupIds = this.resolveGroupIds(options?.groupIds);
+        try {
+            const result = await this.getClient().callTool({
+                name: "search_memory_facts",
+                arguments: {
+                    query,
+                    group_ids: groupIds,
+                    max_facts: options?.maxResults ?? 10,
+                },
+            });
+            if (result.isError)
+                return [];
+            const content = result.content;
+            const text = content?.[0];
+            if (text?.text) {
+                const parsed = JSON.parse(text.text);
+                return parsed.facts ?? parsed ?? [];
+            }
+            return [];
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Check if the Graphiti server is reachable and healthy.
+     *
+     * @returns Status object or null if unreachable
+     */
+    async getStatus() {
+        if (!(await this.connect()))
+            return null;
+        try {
+            const result = await this.getClient().callTool({
+                name: "get_status",
+                arguments: {},
+            });
+            if (result.isError)
+                return null;
+            const content = result.content;
+            const text = content?.[0];
+            if (text?.text) {
+                return JSON.parse(text.text);
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Resolve group IDs for search — always includes "shared" for cross-group search.
+     * If caller provides groupIds, uses those. Otherwise defaults to [projectName, "shared"].
+     * Deduplicates "shared" if already present.
+     */
+    resolveGroupIds(groupIds) {
+        const ids = groupIds ?? [this.projectName];
+        if (!ids.includes("shared")) {
+            ids.push("shared");
+        }
+        return ids;
+    }
+    /**
+     * Disconnect from the Graphiti MCP server.
+     */
+    async disconnect() {
+        if (this.client) {
+            try {
+                await this.client.close();
+            }
+            catch {
+                // ignore
+            }
+        }
+        this.client = null;
+        this.transport = null;
+        this.connected = false;
+    }
+}

package/dist/lib/infra-config.d.ts

@@ -0,0 +1,10 @@
+export interface InfraConfig {
+    falkordb: {
+        host: string;
+        port: number;
+    };
+    graphiti: {
+        url: string;
+    };
+}
+export declare function getInfraConfig(): InfraConfig;

package/dist/lib/infra-config.js

@@ -0,0 +1,31 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function getInfraConfig() {
+    // Override: hosted endpoint
+    const infraUrl = process.env.INDUSK_INFRA_URL;
+    if (infraUrl) {
+        return {
+            falkordb: { host: infraUrl, port: 6379 },
+            graphiti: { url: `http://${infraUrl}:8100/mcp/` },
+        };
+    }
+    // Read from global config
+    const configFile = join(homedir(), ".indusk", "config.env");
+    if (existsSync(configFile)) {
+        const content = readFileSync(configFile, "utf-8");
+        const hostMatch = content.match(/^INDUSK_INFRA_HOST=(.+)$/m);
+        if (hostMatch) {
+            const host = hostMatch[1].trim();
+            return {
+                falkordb: { host, port: 6379 },
+                graphiti: { url: `http://${host}:8100/mcp/` },
+            };
+        }
+    }
+    // Default: local container
+    return {
+        falkordb: { host: "localhost", port: 6379 },
+        graphiti: { url: "http://localhost:8100/mcp/" },
+    };
+}

package/dist/server/index.js

@@ -1,4 +1,6 @@
-import { resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { registerContextTools } from "../tools/context-tools.js";
@@ -8,11 +10,33 @@ import { registerLessonTools } from "../tools/lesson-tools.js";
 import { registerPlanTools } from "../tools/plan-tools.js";
 import { registerQualityTools } from "../tools/quality-tools.js";
 import { registerSystemTools } from "../tools/system-tools.js";
+function getLocalVersion() {
+    try {
+        const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "../../package.json");
+        return JSON.parse(readFileSync(pkgPath, "utf-8")).version;
+    }
+    catch {
+        return "unknown";
+    }
+}
+function checkForUpdates(currentVersion) {
+    fetch("https://registry.npmjs.org/@infinitedusky/indusk-mcp/latest")
+        .then((res) => res.json())
+        .then((data) => {
+        if (data.version && data.version !== currentVersion) {
+            console.error(`[indusk] Update available: ${currentVersion} → ${data.version}. Run: npm i -g @infinitedusky/indusk-mcp@latest`);
+        }
+    })
+        .catch(() => { });
+}
 export async function startServer() {
     const projectRoot = resolve(process.env.PROJECT_ROOT ?? ".");
+    const version = getLocalVersion();
+    // Non-blocking version check
+    checkForUpdates(version);
     const server = new McpServer({
         name: "indusk",
-        version: "0.1.0",
+        version,
     });
     registerPlanTools(server, projectRoot);
     registerContextTools(server, projectRoot);

package/dist/tools/graph-tools.js

@@ -412,6 +412,37 @@ export function registerGraphTools(server, projectRoot) {
                 });
             }
         }
+        // 5. Check Graphiti health
+        if (steps.every((s) => s.step !== "falkordb-container" || s.status !== "error")) {
+            try {
+                const health = execSync("curl -sf http://localhost:8100/health", {
+                    encoding: "utf-8",
+                    timeout: 5000,
+                    stdio: ["ignore", "pipe", "pipe"],
+                }).trim();
+                if (health.includes("healthy")) {
+                    steps.push({
+                        step: "graphiti-health",
+                        status: "ok",
+                        detail: "Graphiti MCP server healthy",
+                    });
+                }
+                else {
+                    steps.push({
+                        step: "graphiti-health",
+                        status: "error",
+                        detail: "Graphiti responded but not healthy",
+                    });
+                }
+            }
+            catch {
+                steps.push({
+                    step: "graphiti-health",
+                    status: "error",
+                    detail: "Graphiti MCP server not reachable on localhost:8100 — may still be starting (takes ~90s)",
+                });
+            }
+        }
         const hasErrors = steps.some((s) => s.status === "error");
         const hasFixed = steps.some((s) => s.status === "fixed");
         return {

package/extensions/graphiti/manifest.json

@@ -0,0 +1,24 @@
+{
+	"name": "graphiti",
+	"description": "Graphiti temporal knowledge graph — episodic memory, contradiction detection, semantic search via FalkorDB",
+	"provides": {
+		"skill": true,
+		"health_checks": [
+			{
+				"name": "indusk-infra-running",
+				"command": "docker inspect --format='{{.State.Running}}' indusk-infra 2>/dev/null | grep true"
+			},
+			{
+				"name": "graphiti-server-reachable",
+				"command": "curl -sf http://localhost:8100/health > /dev/null 2>&1"
+			},
+			{
+				"name": "falkordb-reachable",
+				"command": "redis-cli -h localhost ping 2>/dev/null | grep PONG"
+			}
+		]
+	},
+	"detect": {
+		"command": "docker inspect --format='{{.State.Running}}' indusk-infra 2>/dev/null | grep true"
+	}
+}

package/extensions/graphiti/skill.md

@@ -0,0 +1,91 @@
+# Graphiti — Temporal Knowledge Graph
+
+Graphiti is an episodic memory system backed by FalkorDB. It extracts entities and facts from text, detects contradictions, and supports semantic search across project-specific and shared knowledge.
+
+## When to Use
+
+- **Episode capture**: After a decision, retro finding, or correction — anything worth remembering across sessions
+- **Search**: Before making assumptions — check what's already known about a topic
+- **Context retrieval**: At session start or when working in an unfamiliar area
+
+## Core Concepts
+
+### Episodes
+An episode is a chunk of text that Graphiti processes into entities and facts. Think of it as "something that happened" — a decision was made, a bug was found, a convention was established.
+
+### Group IDs
+Every episode belongs to a group. Groups isolate knowledge:
+
+| Group | Purpose | Example |
+|-------|---------|---------|
+| `{project-name}` | Project-specific knowledge | `infinitedusky`, `numero` |
+| `shared` | Cross-project conventions | Developer preferences, universal patterns |
+
+When searching, always include both the project group and `shared` to get the full picture. The `GraphitiClient` does this automatically.
+
+### Entities and Facts
+Graphiti extracts:
+- **Entities**: Named things (tools, patterns, files, concepts)
+- **Facts**: Relationships between entities with temporal validity
+
+Facts can be contradicted — if you add "the parser handles three gate types" and later "the parser handles four gate types", Graphiti invalidates the old fact.
+
+## Patterns
+
+### Capturing a Decision
+After an ADR is accepted or a significant choice is made:
+```
+addEpisode("auth-approach-decision", 
+  "We chose JWT with refresh tokens over session cookies because the API serves both web and mobile clients. Session cookies don't work well with React Native.",
+  { groupId: "myproject" })
+```
+
+### Capturing a Correction
+When someone corrects the agent or a mistake is found:
+```
+addEpisode("correction-test-database",
+  "Integration tests must use a real database, not mocks. We got burned when mocked tests passed but the production migration failed.",
+  { groupId: "shared" })
+```
+
+### Searching Before Acting
+Before making assumptions about how something works:
+```
+searchNodes("authentication middleware")
+searchFacts("how does auth work in this project")
+```
+
+### Capturing a Retrospective Finding
+After a plan retrospective surfaces a useful insight:
+```
+addEpisode("retro-gate-enforcement",
+  "Plan gates need hook-based enforcement, not just instructions. The agent skipped gates when they were advisory only. PreToolUse hooks that block phase transitions are the fix.",
+  { groupId: "myproject" })
+```
+
+## What NOT to Capture
+
+- Code structure (CGC handles this)
+- Git history (git log handles this)
+- Ephemeral state (current task, in-progress work)
+- Things already in CLAUDE.md or lessons
+
+Graphiti is for knowledge that has temporal context — decisions that might change, facts that might be contradicted, insights that accumulate over time.
+
+## Infrastructure
+
+Graphiti runs inside the `indusk-infra` container alongside FalkorDB:
+
+```bash
+indusk infra start    # start the container
+indusk infra status   # check health
+indusk infra stop     # stop (preserves data)
+```
+
+Global config (API keys, OTel): `~/.indusk/config.env`
+
+### Graceful Degradation
+If the `indusk-infra` container is down:
+- CGC graph tools still check FalkorDB directly
+- Graphiti client methods return null/empty (never throw)
+- The agent continues working with flat-file context (CLAUDE.md, lessons, skills)

package/extensions/otel/skill.md

@@ -189,19 +189,17 @@ Wrap this in a helper so every log call includes trace context automatically. Wi
 
 ## Error Propagation
 
-Errors must always include trace context. Never swallow silently.
-
-**Important: Span events (`AddEvent`, `RecordException`) are deprecated as of March 2026.** Use log-based events correlated with the active span instead. The log automatically inherits trace context when emitted inside an active span.
+Errors must always include trace context. Never swallow silently:
 
 ```typescript
 try {
   await processSettlement(hand);
 } catch (err) {
-  // 1. Set error status on span
+  // 1. Record on span
+  span.recordException(err);
   span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
   
-  // 2. Log the error — automatically correlated with the active span
-  // This replaces span.recordException(err) which is deprecated
+  // 2. Log with correlation
   logger.error({ err, ...getTraceContext() }, 'settlement failed');
   
   // 3. Re-throw — don't swallow
@@ -213,11 +211,6 @@ Every catch block should either:
 1. Re-throw with context preserved
 2. Log with trace correlation and handle completely
 
-**Migration from span events to logs:**
-- `span.addEvent('name', attrs)` → `logger.info({ ...attrs, ...getTraceContext() }, 'name')`
-- `span.recordException(err)` → `logger.error({ err, ...getTraceContext() }, 'error message')`
-- Span status (`setStatus`) is NOT deprecated — still use it to mark spans as errored
-
 ## Sensitive Data
 
 Never attach these to spans, logs, or metrics:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@infinitedusky/indusk-mcp",
-	"version": "1.6.7",
+	"version": "1.7.3",
 	"description": "InDusk development system — skills, MCP tools, and CLI for structured AI-assisted development",
 	"type": "module",
 	"files": [

package/skills/handoff.md

@@ -46,18 +46,11 @@ Create or overwrite `.claude/handoff.md` with:
 
 ## When to Write a Handoff
 
+- Before ending any session where work was done
 - When the user says "let's stop here", "wrap up", "hand off"
+- When you're about to run out of context
 - `/handoff` explicitly
 
-## When to Suggest a Handoff
-
-Only suggest a handoff in these situations — never ask unprompted otherwise:
-
-- **You are running low on context** and can feel the conversation getting long. Say so plainly: "I'm getting close to context limits — want me to write a handoff?"
-- **A major milestone just completed** (e.g., a full plan phase, a feature landed, a retrospective finished) and there's no obvious next task queued up. Mention it once — if the user keeps going, don't ask again.
-
-Do **not** suggest a handoff after every task, at natural pauses, or as a closing question. The user decides when to stop.
-
 ## Rules
 
 - **Be specific.** "Working on Phase 3" is useless. "Phase 3, item 4: refactored check_health to use extensions. extensions_status MCP tool created. Next: refactor init to remove hardcoded FalkorDB/CGC." is useful.