kiro-memory 1.1.4 → 1.2.1

package/README.md

@@ -308,6 +308,105 @@ npm run test:context
 npm run test:server
 ```
 
+## Troubleshooting
+
+### `invalid ELF header` (WSL)
+
+```
+Error: .../better_sqlite3.node: invalid ELF header
+```
+
+This happens when the native module was compiled for Windows but you're running inside WSL (Linux). Common cause: npm installed to the Windows filesystem (`/mnt/c/...`) instead of the Linux one.
+
+**Fix:**
+
+```bash
+# Check which node you're using
+which node
+# If it shows /mnt/c/... you're using Windows Node inside WSL
+
+# Install Node.js natively in WSL
+curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
+sudo apt-get install -y nodejs
+
+# Or use nvm (recommended)
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
+nvm install 22
+
+# Verify
+which node  # Should be /home/... or /root/.nvm/...
+
+# Reinstall
+npm install -g kiro-memory
+```
+
+### `npm prefix` pointing to Windows (WSL)
+
+If `npm prefix -g` returns a `/mnt/c/...` path, npm installs global packages on the Windows filesystem, causing native module issues.
+
+**Fix:**
+
+```bash
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+
+# Reinstall
+npm install -g kiro-memory
+```
+
+### Missing build tools (Linux/WSL)
+
+```
+gyp ERR! find Python
+gyp ERR! stack Error: Could not find any Python installation to use
+```
+
+Native modules like `better-sqlite3` need compilation tools.
+
+**Fix:**
+
+```bash
+sudo apt-get update && sudo apt-get install -y build-essential python3
+npm install -g kiro-memory --build-from-source
+```
+
+### `no agent with name kiro-memory found`
+
+The agent configuration was not installed. Run the install command:
+
+```bash
+kiro-memory install
+```
+
+This creates the agent config at `~/.kiro/agents/contextkit.json`. Note: the agent name is `contextkit-memory`, so start Kiro with:
+
+```bash
+kiro-cli --agent contextkit-memory
+```
+
+### Port 3001 already in use
+
+```bash
+# Find what's using the port
+lsof -i :3001
+
+# Kill the process
+kill -9 <PID>
+
+# Or use a different port
+export KIRO_MEMORY_WORKER_PORT=3002
+```
+
+### Quick diagnostics
+
+Run the built-in doctor command to check your environment:
+
+```bash
+kiro-memory doctor
+```
+
 ## Contributing
 
 Contributions are welcome. Please open an issue to discuss proposed changes before submitting a pull request. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiro-memory",
-  "version": "1.1.4",
+  "version": "1.2.1",
   "description": "Persistent cross-session memory for Kiro CLI. Automatically tracks context, observations, and summaries across coding sessions.",
   "keywords": [
     "kiro",

package/plugin/dist/cli/contextkit.js

@@ -900,8 +900,8 @@ var ContextKitSDK = class {
   }
   detectProject() {
     try {
-      const { execSync } = __require("child_process");
-      const gitRoot = execSync("git rev-parse --show-toplevel", {
+      const { execSync: execSync2 } = __require("child_process");
+      const gitRoot = execSync2("git rev-parse --show-toplevel", {
         cwd: process.cwd(),
         encoding: "utf8",
         stdio: ["pipe", "pipe", "ignore"]
@@ -1081,9 +1081,303 @@ function createContextKit(config) {
 }
 
 // src/cli/contextkit.ts
+import { execSync } from "child_process";
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync2, writeFileSync } from "fs";
+import { join as join3, dirname as dirname2 } from "path";
+import { homedir as homedir3, platform, release } from "os";
+import { fileURLToPath as fileURLToPath2 } from "url";
 var args = process.argv.slice(2);
 var command = args[0];
+var __filename = fileURLToPath2(import.meta.url);
+var __dirname2 = dirname2(__filename);
+var DIST_DIR = dirname2(__dirname2);
+var AGENT_TEMPLATE = JSON.stringify({
+  name: "contextkit-memory",
+  description: "Agent with persistent cross-session memory. Uses ContextKit to remember context from previous sessions and automatically save what it learns.",
+  model: "claude-sonnet-4",
+  tools: ["read", "write", "shell", "glob", "grep", "web_search", "web_fetch", "@contextkit"],
+  mcpServers: {
+    contextkit: {
+      command: "node",
+      args: ["__DIST_DIR__/servers/mcp-server.js"]
+    }
+  },
+  hooks: {
+    agentSpawn: [{ command: "node __DIST_DIR__/hooks/agentSpawn.js", timeout_ms: 1e4 }],
+    userPromptSubmit: [{ command: "node __DIST_DIR__/hooks/userPromptSubmit.js", timeout_ms: 5e3 }],
+    postToolUse: [{ command: "node __DIST_DIR__/hooks/postToolUse.js", matcher: "*", timeout_ms: 5e3 }],
+    stop: [{ command: "node __DIST_DIR__/hooks/stop.js", timeout_ms: 1e4 }]
+  },
+  resources: ["file://.kiro/steering/contextkit.md"]
+}, null, 2);
+var STEERING_CONTENT = `# ContextKit - Persistent Memory
+
+You have access to ContextKit, a persistent cross-session memory system.
+
+## Available MCP Tools
+
+### @contextkit/search
+Search previous session memory. Use when:
+- The user mentions past work
+- You need context on previous decisions
+- You want to check if a problem was already addressed
+
+### @contextkit/get_context
+Retrieve recent context for the current project. Use at the start of complex tasks to understand what was done before.
+
+### @contextkit/timeline
+Show chronological context around an observation. Use to understand the sequence of events.
+
+### @contextkit/get_observations
+Retrieve full details of specific observations. Use after \`search\` to drill down.
+
+## Behavior
+
+- Previous session context is automatically injected at startup
+- Your actions (files written, commands run) are tracked automatically
+- A summary is generated at the end of each session
+- No manual saving needed: the system is fully automatic
+`;
+function isWSL() {
+  try {
+    const rel = release().toLowerCase();
+    if (rel.includes("microsoft") || rel.includes("wsl")) return true;
+    if (existsSync3("/proc/version")) {
+      const proc = readFileSync2("/proc/version", "utf8").toLowerCase();
+      return proc.includes("microsoft") || proc.includes("wsl");
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+function commandExists(cmd) {
+  try {
+    execSync(`which ${cmd}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isWindowsPath(p) {
+  return p.startsWith("/mnt/c") || p.startsWith("/mnt/d") || /^[A-Za-z]:[\\\/]/.test(p);
+}
+function runEnvironmentChecks() {
+  const checks = [];
+  const wsl = isWSL();
+  const os = platform();
+  checks.push({
+    name: "Operating system",
+    ok: os === "linux" || os === "darwin",
+    message: os === "linux" ? wsl ? "Linux (WSL)" : "Linux" : os === "darwin" ? "macOS" : `${os} (not officially supported)`
+  });
+  if (wsl) {
+    const nodePath = process.execPath;
+    const nodeOnWindows = isWindowsPath(nodePath);
+    checks.push({
+      name: "WSL: Native Node.js",
+      ok: !nodeOnWindows,
+      message: nodeOnWindows ? `Node.js points to Windows: ${nodePath}` : `Native Linux Node.js: ${nodePath}`,
+      fix: nodeOnWindows ? "Install Node.js inside WSL:\n  curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -\n  sudo apt-get install -y nodejs\n  Or use nvm: https://github.com/nvm-sh/nvm" : void 0
+    });
+    try {
+      const npmPrefix = execSync("npm prefix -g", { encoding: "utf8" }).trim();
+      const prefixOnWindows = isWindowsPath(npmPrefix);
+      checks.push({
+        name: "WSL: npm global prefix",
+        ok: !prefixOnWindows,
+        message: prefixOnWindows ? `npm global prefix points to Windows: ${npmPrefix}` : `npm global prefix: ${npmPrefix}`,
+        fix: prefixOnWindows ? `Fix npm prefix:
+  mkdir -p ~/.npm-global
+  npm config set prefix ~/.npm-global
+  echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
+  source ~/.bashrc
+  Then reinstall: npm install -g kiro-memory` : void 0
+      });
+    } catch {
+      checks.push({
+        name: "WSL: npm global prefix",
+        ok: false,
+        message: "Unable to determine npm prefix"
+      });
+    }
+  }
+  const nodeVersion = parseInt(process.versions.node.split(".")[0]);
+  checks.push({
+    name: "Node.js >= 18",
+    ok: nodeVersion >= 18,
+    message: `Node.js v${process.versions.node}`,
+    fix: nodeVersion < 18 ? "Upgrade Node.js:\n  nvm install 22 && nvm use 22\n  Or visit: https://nodejs.org/" : void 0
+  });
+  let sqliteOk = false;
+  let sqliteMsg = "";
+  try {
+    __require("better-sqlite3");
+    sqliteOk = true;
+    sqliteMsg = "Native module loaded successfully";
+  } catch (err) {
+    sqliteMsg = err.code === "ERR_DLOPEN_FAILED" ? "Incompatible native binary (invalid ELF header \u2014 likely platform mismatch)" : `Error: ${err.message}`;
+  }
+  checks.push({
+    name: "better-sqlite3",
+    ok: sqliteOk,
+    message: sqliteMsg,
+    fix: !sqliteOk ? wsl ? "In WSL, rebuild the native module:\n  npm rebuild better-sqlite3\n  If that fails, reinstall:\n  npm install -g kiro-memory --build-from-source" : "Rebuild the native module:\n  npm rebuild better-sqlite3" : void 0
+  });
+  if (os === "linux") {
+    const hasMake = commandExists("make");
+    const hasGcc = commandExists("g++") || commandExists("gcc");
+    const hasPython = commandExists("python3") || commandExists("python");
+    const allPresent = hasMake && hasGcc && hasPython;
+    const missing = [];
+    if (!hasMake || !hasGcc) missing.push("build-essential");
+    if (!hasPython) missing.push("python3");
+    checks.push({
+      name: "Build tools (native modules)",
+      ok: allPresent,
+      message: allPresent ? "make, g++, python3 available" : `Missing: ${missing.join(", ")}`,
+      fix: !allPresent ? `Install required packages:
+  sudo apt-get update && sudo apt-get install -y ${missing.join(" ")}
+  Then reinstall: npm install -g kiro-memory --build-from-source` : void 0
+    });
+  }
+  return checks;
+}
+function printChecks(checks) {
+  let hasErrors = false;
+  console.log("");
+  for (const check of checks) {
+    const icon = check.ok ? "\x1B[32m\u2713\x1B[0m" : "\x1B[31m\u2717\x1B[0m";
+    console.log(`  ${icon} ${check.name}: ${check.message}`);
+    if (!check.ok && check.fix) {
+      console.log(`    \x1B[33m\u2192 Fix:\x1B[0m`);
+      for (const line of check.fix.split("\n")) {
+        console.log(`      ${line}`);
+      }
+    }
+    if (!check.ok) hasErrors = true;
+  }
+  console.log("");
+  return { hasErrors };
+}
+async function installKiro() {
+  console.log("\n=== Kiro Memory - Installation ===\n");
+  console.log("[1/3] Running environment checks...");
+  const checks = runEnvironmentChecks();
+  const { hasErrors } = printChecks(checks);
+  if (hasErrors) {
+    console.log("\x1B[31mInstallation aborted.\x1B[0m Fix the issues above and retry.");
+    console.log("After fixing, run: kiro-memory install\n");
+    process.exit(1);
+  }
+  const distDir = DIST_DIR;
+  const kiroDir = process.env.KIRO_CONFIG_DIR || join3(homedir3(), ".kiro");
+  const agentsDir = join3(kiroDir, "agents");
+  const settingsDir = join3(kiroDir, "settings");
+  const steeringDir = join3(kiroDir, "steering");
+  const dataDir = process.env.CONTEXTKIT_DATA_DIR || join3(homedir3(), ".contextkit");
+  console.log("[2/3] Installing Kiro configuration...\n");
+  for (const dir of [agentsDir, settingsDir, steeringDir, dataDir]) {
+    mkdirSync3(dir, { recursive: true });
+  }
+  const agentConfig = AGENT_TEMPLATE.replace(/__DIST_DIR__/g, distDir);
+  const agentDestPath = join3(agentsDir, "contextkit.json");
+  writeFileSync(agentDestPath, agentConfig, "utf8");
+  console.log(`  \u2192 Agent config: ${agentDestPath}`);
+  const mcpFilePath = join3(settingsDir, "mcp.json");
+  let mcpConfig = { mcpServers: {} };
+  if (existsSync3(mcpFilePath)) {
+    try {
+      mcpConfig = JSON.parse(readFileSync2(mcpFilePath, "utf8"));
+      if (!mcpConfig.mcpServers) mcpConfig.mcpServers = {};
+    } catch {
+    }
+  }
+  mcpConfig.mcpServers.contextkit = {
+    command: "node",
+    args: [join3(distDir, "servers", "mcp-server.js")]
+  };
+  writeFileSync(mcpFilePath, JSON.stringify(mcpConfig, null, 2), "utf8");
+  console.log(`  \u2192 MCP config:   ${mcpFilePath}`);
+  const steeringDestPath = join3(steeringDir, "contextkit.md");
+  writeFileSync(steeringDestPath, STEERING_CONTENT, "utf8");
+  console.log(`  \u2192 Steering:     ${steeringDestPath}`);
+  console.log(`  \u2192 Data dir:     ${dataDir}`);
+  console.log("\n[3/3] Installation complete!\n");
+  console.log("To use Kiro with persistent memory:");
+  console.log("  kiro-cli --agent contextkit-memory\n");
+  console.log("To create a permanent alias:");
+  console.log(`  echo 'alias kiro="kiro-cli --agent contextkit-memory"' >> ~/.bashrc`);
+  console.log("  source ~/.bashrc\n");
+  console.log("The worker starts automatically when a Kiro session begins.");
+  console.log(`Web dashboard: http://localhost:3001
+`);
+}
+async function runDoctor() {
+  console.log("\n=== Kiro Memory - Diagnostics ===");
+  const checks = runEnvironmentChecks();
+  const kiroDir = process.env.KIRO_CONFIG_DIR || join3(homedir3(), ".kiro");
+  const agentPath = join3(kiroDir, "agents", "contextkit.json");
+  const mcpPath = join3(kiroDir, "settings", "mcp.json");
+  const dataDir = process.env.CONTEXTKIT_DATA_DIR || join3(homedir3(), ".contextkit");
+  checks.push({
+    name: "Kiro agent config",
+    ok: existsSync3(agentPath),
+    message: existsSync3(agentPath) ? agentPath : "Not found",
+    fix: !existsSync3(agentPath) ? "Run: kiro-memory install" : void 0
+  });
+  let mcpOk = false;
+  if (existsSync3(mcpPath)) {
+    try {
+      const mcp = JSON.parse(readFileSync2(mcpPath, "utf8"));
+      mcpOk = !!mcp.mcpServers?.contextkit;
+    } catch {
+    }
+  }
+  checks.push({
+    name: "MCP server configured",
+    ok: mcpOk,
+    message: mcpOk ? "contextkit registered in mcp.json" : "Not configured",
+    fix: !mcpOk ? "Run: kiro-memory install" : void 0
+  });
+  checks.push({
+    name: "Data directory",
+    ok: existsSync3(dataDir),
+    message: existsSync3(dataDir) ? dataDir : "Not created (will be created on first use)"
+  });
+  let workerOk = false;
+  try {
+    const port = process.env.KIRO_MEMORY_WORKER_PORT || "3001";
+    execSync(`curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:${port}/api/health`, {
+      timeout: 2e3,
+      encoding: "utf8"
+    });
+    workerOk = true;
+  } catch {
+  }
+  checks.push({
+    name: "Worker service",
+    ok: true,
+    // Non-blocking: starts automatically with Kiro
+    message: workerOk ? "Running on port 3001" : "Not running (starts automatically with Kiro)"
+  });
+  const { hasErrors } = printChecks(checks);
+  if (hasErrors) {
+    console.log("Some checks failed. Fix the issues listed above.\n");
+    process.exit(1);
+  } else {
+    console.log("All good! Kiro Memory is ready.\n");
+  }
+}
 async function main() {
+  if (command === "install") {
+    await installKiro();
+    return;
+  }
+  if (command === "doctor") {
+    await runDoctor();
+    return;
+  }
   const contextkit = createContextKit();
   try {
     switch (command) {
@@ -1238,7 +1532,11 @@ async function addSummary(contextkit, content) {
 `);
 }
 function showHelp() {
-  console.log(`Usage: contextkit <command> [options]
+  console.log(`Usage: kiro-memory <command> [options]
+
+Setup:
+  install                   Install hooks, MCP server, and agent config into Kiro CLI
+  doctor                    Run environment diagnostics (checks Node, build tools, WSL, etc.)
 
 Commands:
   context, ctx              Show current project context
@@ -1250,10 +1548,11 @@ Commands:
   help                      Show this help message
 
 Examples:
-  contextkit context
-  contextkit search "authentication"
-  contextkit observations 20
-  contextkit add-observation "Bug Fix" "Fixed the login issue"
+  kiro-memory install
+  kiro-memory doctor
+  kiro-memory context
+  kiro-memory search "authentication"
+  kiro-memory observations 20
 `);
 }
 main().catch(console.error);