@infinitedusky/indusk-mcp 1.7.0 → 1.7.3

package/dist/bin/commands/init.js

@@ -215,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");
@@ -568,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/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/nextjs/manifest.json

@@ -1,18 +1,6 @@
 {
 	"name": "nextjs",
 	"description": "Next.js 13+ patterns — App Router, server components, caching, performance",
-	"provides": {
-		"skill": true,
-		"health_checks": [
-			{
-				"name": "no-turbopack-in-dev-scripts",
-				"command": "! grep -rl '\\-\\-turbopack' apps/*/package.json 2>/dev/null | head -1 | grep -q ."
-			},
-			{
-				"name": "webpack-aggregate-timeout-configured",
-				"command": "for f in apps/*/next.config.*; do [ -f \"$f\" ] && grep -q 'aggregateTimeout' \"$f\" || { echo \"missing aggregateTimeout: $f\"; exit 1; }; done"
-			}
-		]
-	},
+	"provides": { "skill": true },
 	"detect": { "dependency": "next" }
 }

package/extensions/nextjs/skill.md

@@ -24,26 +24,6 @@ You are working in a Next.js project. Follow these patterns.
 - Dynamic imports (`next/dynamic`) for heavy client components
 - Minimize `"use client"` boundaries — push them as deep in the component tree as possible
 
-## Dev Server — Webpack Only
-
-- **Do not use Turbopack** — its 1ms file watcher debounce on macOS causes crashes when files are written by external tools (MCP servers, code generation, etc.)
-- **Next.js < 16:** plain `next dev` uses webpack by default — just don't add `--turbopack`
-- **Next.js 16+:** Turbopack is the default — use `next dev --webpack` to opt out
-- **Always include `aggregateTimeout: 600`** in webpack watchOptions in `next.config.*`
-
-```ts
-// next.config.ts
-const nextConfig = {
-  webpack: (config) => {
-    config.watchOptions = {
-      ...config.watchOptions,
-      aggregateTimeout: 600,
-    };
-    return config;
-  },
-};
-```
-
 ## Common Gotchas
 
 - `"use client"` doesn't mean the component only renders on the client — it still SSRs. It means it hydrates.

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.7.0",
+	"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.