mindkeg-mcp 0.7.0 → 0.7.2

package/README.md

@@ -29,7 +29,7 @@ Unlike traditional RAG systems that chunk large documents, Mind Keg stores **pre
 - Free-form tags and group linking
 - Three scoping levels: repository-specific, workspace-wide, and global learnings
 - Dual transport: stdio (local) + HTTP+SSE (remote)
-- API key authentication with per-repository access control
+- Auth-free stdio for local use; API key authentication with per-repository access control for HTTP
 - SQLite storage (zero dependencies, zero config)
 - Import/export for backup and migration
 - **Smarter knowledge management**: auto-categorization (KNN voting), conflict detection, smart staleness scoring, access tracking with relevance decay, near-duplicate merging, typed learning relationships
@@ -67,7 +67,7 @@ If you prefer to configure manually, or need HTTP mode:
 npm install -g mindkeg-mcp
 ```
 
-#### Create an API key
+#### Create an API key (only needed for HTTP mode)
 
 ```bash
 mindkeg api-key create --name "My Laptop"
@@ -75,6 +75,8 @@ mindkeg api-key create --name "My Laptop"
 # mk_abc123...
 ```
 
+> API keys are only required for HTTP transport. stdio transport (used by Claude Code, Cursor, Windsurf local setups) is auth-free.
+
 #### Connect your AI agent
 
 Mind Keg works with any MCP-compatible AI coding agent. Choose your setup:
@@ -86,10 +88,7 @@ Mind Keg works with any MCP-compatible AI coding agent. Choose your setup:
   "mcpServers": {
     "mindkeg": {
       "command": "mindkeg",
-      "args": ["serve", "--stdio"],
-      "env": {
-        "MINDKEG_API_KEY": "mk_your_key_here"
-      }
+      "args": ["serve", "--stdio"]
     }
   }
 }
@@ -102,10 +101,7 @@ Mind Keg works with any MCP-compatible AI coding agent. Choose your setup:
   "mcpServers": {
     "mindkeg": {
       "command": "mindkeg",
-      "args": ["serve", "--stdio"],
-      "env": {
-        "MINDKEG_API_KEY": "mk_your_key_here"
-      }
+      "args": ["serve", "--stdio"]
     }
   }
 }
@@ -118,10 +114,7 @@ Mind Keg works with any MCP-compatible AI coding agent. Choose your setup:
   "mcpServers": {
     "mindkeg": {
       "command": "mindkeg",
-      "args": ["serve", "--stdio"],
-      "env": {
-        "MINDKEG_API_KEY": "mk_your_key_here"
-      }
+      "args": ["serve", "--stdio"]
     }
   }
 }
@@ -162,46 +155,28 @@ Copy `templates/AGENTS.md` to the root of any repository where you want agents t
 
 ## MCP Tools
 
-### Learnings
-
-| Tool                 | Description                                          |
-|----------------------|------------------------------------------------------|
-| `get_context`        | Prime an agent session with all relevant learnings — ranked, scoped, and budget-controlled |
-| `store_learning`     | Store a new atomic learning (repo, workspace, or global scope) |
-| `search_learnings`   | Semantic/keyword search for relevant learnings       |
-| `update_learning`    | Update content, category, or tags                    |
-| `deprecate_learning` | Mark a learning as deprecated                        |
-| `flag_stale`         | Flag a learning as potentially outdated               |
-| `delete_learning`    | Permanently delete a learning                        |
-| `merge_learnings`    | Merge near-duplicate learnings into a canonical entry |
-| `relate_learnings`   | Create typed relationships between learnings          |
-| `list_repositories`  | List all repositories with learning counts           |
-| `list_workspaces`    | List all workspaces with learning counts             |
-
-### Agent Memory Entities
-
-Structured entity types for capturing decisions, findings, gotchas, and run summaries — richer than atomic learnings, designed for cross-session agent memory.
-
-| Tool                   | Description                                          |
-|------------------------|------------------------------------------------------|
-| `store_decision`       | Record an architectural or design decision with rationale |
-| `get_decisions`        | Retrieve decisions for a repository, optionally filtered by status |
-| `supersede_decision`   | Mark a decision as superseded by a newer one         |
-| `store_finding`        | Record a bug, issue, or investigation finding         |
-| `get_open_findings`    | Retrieve unresolved findings for a repository         |
-| `resolve_finding`      | Mark a finding as resolved with a resolution summary  |
-| `store_gotcha`         | Record a non-obvious pitfall or gotcha                |
-| `get_gotchas`          | Retrieve gotchas for a repository                     |
-| `get_relevant_context` | Retrieve all entity types relevant to a repository    |
-| `get_run_history`      | Retrieve run summaries for a repository               |
-| `complete_run`         | Record the completion of an agent run with a summary  |
+**8 consolidated tools (primary API):**
+
+| Tool | Description |
+|---|---|
+| `get_context` | Retrieve relevant knowledge — session primer, task-scoped context, or semantic search (replaces `get_context`, `get_relevant_context`, `search_learnings`) |
+| `store` | Save knowledge — learning, decision, finding, or gotcha (replaces `store_learning`, `store_decision`, `store_finding`, `store_gotcha`) |
+| `update` | Modify/manage knowledge — update, deprecate, flag_stale, delete, or merge (replaces `update_learning`, `deprecate_learning`, `flag_stale`, `delete_learning`, `merge_learnings`) |
+| `resolve` | Close out a decision or finding (replaces `supersede_decision`, `resolve_finding`) |
+| `complete_run` | Record a completed work session |
+| `query` | List knowledge by type — decisions, findings, gotchas, or runs (replaces `get_decisions`, `get_open_findings`, `get_gotchas`, `get_run_history`) |
+| `list_scopes` | List repositories and workspaces with counts (replaces `list_repositories`, `list_workspaces`) |
+| `relate_learnings` | Create typed relationships between learnings |
+
+**Backwards-compatible aliases:** All 19 old tool names (`store_learning`, `search_learnings`, `update_learning`, `deprecate_learning`, `flag_stale`, `delete_learning`, `merge_learnings`, `store_decision`, `get_decisions`, `supersede_decision`, `store_finding`, `resolve_finding`, `get_open_findings`, `store_gotcha`, `get_gotchas`, `get_run_history`, `get_relevant_context`, `list_repositories`, `list_workspaces`) are registered as aliases that delegate to the same service methods. They will be removed in the next major version.
 
 ## CLI Commands
 
 ```bash
-# Quick setup (auto-detects agent, writes config, copies instructions)
+# Global setup (one-time) — writes MCP config, SessionStart hook, runs migrations
 mindkeg init
-mindkeg init --agent cursor
+mindkeg init --agent cursor    # Target a specific agent (default: claude-code)
+mindkeg init --project         # Per-project setup instead of global (optional)
 
 # Database statistics
 mindkeg stats
@@ -253,7 +228,7 @@ mindkeg backfill-integrity  # Compute SHA-256 hashes for legacy learnings
 | `MINDKEG_HOST`                | `127.0.0.1`                  | HTTP server bind address            |
 | `MINDKEG_PORT`                | `52100`                      | HTTP server port                    |
 | `MINDKEG_LOG_LEVEL`           | `info`                       | `debug`, `info`, `warn`, `error`    |
-| `MINDKEG_API_KEY`             | (none)                       | API key for stdio transport         |
+| `MINDKEG_API_KEY`             | (none)                       | API key for HTTP transport (stdio is auth-free) |
 
 ### Embedding providers
 
@@ -480,9 +455,10 @@ src/
   audit/            Structured JSON lines audit logger
   auth/             API key generation + validation middleware
   crypto/           AES-256-GCM field encryption
+  hooks/            Hook script generation (SessionStart auto-retrieval)
   monitoring/       Prometheus metrics + /health endpoint
   security/         Content sanitization, integrity hashing, rate limiter
-  tools/            One file per MCP tool (22 tools) + shared tool-utils
+  tools/            MCP tool handlers (8 consolidated + 19 backwards-compatible aliases)
   services/         LearningService + EmbeddingService + PurgeService + ConflictDetector + StalenessEngine
   storage/          StorageAdapter interface + SQLite impl
   models/           Zod schemas + TypeScript types

package/dist/cli/index.js

@@ -4298,7 +4298,7 @@ function validateStoreInput(input) {
 function registerConsolidatedStore(server, learningService, entityService, storage, getApiKey, auditLogger) {
   server.tool(
     "store",
-    "Save a piece of knowledge. Types: learning (short insight, max 500 chars), decision (architectural choice with rationale), finding (code review issue), gotcha (non-obvious behavior). Before calling this, ask the user if they want to save it and which scope \u2014 this repo, workspace, or global.",
+    'Save a piece of knowledge when you discover something worth preserving across sessions. Call this proactively when you encounter: a gotcha (non-obvious behavior), an architectural decision with rationale, a code review finding, or a short factual insight (conventions, debugging tips). Always ask the user first \u2014 e.g., "I noticed X, want me to save this to Mind Keg?" \u2014 and confirm scope (this repo / workspace / global) before calling.',
     {
       type: z8.enum(["learning", "decision", "finding", "gotcha"]).describe("Type of knowledge to store."),
       repository: z8.string().optional().nullable().describe("Repository path. Required for decision, finding, gotcha. Optional for learning."),
@@ -4499,7 +4499,7 @@ function validateUpdateInput(input) {
 function registerConsolidatedUpdate(server, learningService, storage, getApiKey, auditLogger) {
   server.tool(
     "update",
-    "Modify or manage existing knowledge. Actions: update (change content/tags), deprecate (mark outdated \u2014 preferred over delete), flag_stale (soft flag when unsure), delete (permanent), merge (consolidate duplicates). Use deprecate when you discover a stored learning is wrong. Use flag_stale when you're unsure.",
+    "Modify or manage existing knowledge. Actions: update (change content/tags), deprecate (mark outdated \u2014 preferred over delete), flag_stale (soft flag when unsure), delete (permanent), merge (consolidate duplicates). When you find a stored learning that contradicts current reality, proactively offer to deprecate or flag it. Use deprecate when certain, flag_stale when unsure.",
     {
       action: z9.enum(["update", "deprecate", "flag_stale", "delete", "merge"]).describe("Action to perform."),
       id: z9.string().uuid().describe("Target learning ID."),
@@ -6327,16 +6327,49 @@ function createNoopAuditLogger() {
 }
 
 // src/server.ts
+var MINDKEG_SERVER_INSTRUCTIONS = `You have access to Mind Keg \u2014 a persistent memory system for knowledge that survives across sessions. Use it to retrieve prior context and proactively preserve new insights.
+
+# When to retrieve
+
+At session start, call \`get_context({ repository: "<current repo path>" })\` to load prior knowledge. If the SessionStart hook already injected context (visible as "Mind Keg Persistent Memory" at the top of the conversation), skip this \u2014 the context is already loaded.
+
+For topic-specific lookups mid-session, call \`get_context({ query: "<topic>", repository: "<path>" })\`.
+
+# When to store (proactively offer)
+
+When you discover something non-obvious during work, pause and offer to save it:
+
+> "I noticed [X]. This looks like a [gotcha/decision/finding]. Want me to save it to Mind Keg?
+>  Scope: this repo, this workspace, or globally?"
+
+Wait for the user's answer before calling \`store\`.
+
+Watch for these patterns specifically:
+
+- **Gotchas** \u2014 non-obvious behaviors, footguns, surprising library quirks \u2192 \`store({ type: "gotcha", ... })\`
+- **Architectural decisions** with rationale \u2192 \`store({ type: "decision", ... })\`
+- **Code review findings** that need tracking across sessions \u2192 \`store({ type: "finding", ... })\`
+- **Short factual insights** (conventions, debugging tips, compact observations) \u2192 \`store({ type: "learning", ... })\`
+
+# Rules
+
+- Always ask before storing. Never store silently.
+- Don't store transient session state, obvious facts, or codebase-specific details that change as code evolves (file paths, function locations). Those belong in project-level memory, not Mind Keg.
+- Prefer \`update({ action: "deprecate" })\` over delete for wrong knowledge \u2014 preserves audit trail.
+- Use \`update({ action: "flag_stale" })\` when you suspect something is outdated but aren't sure.
+- For scope, ask the user; default suggestion: this repo unless the insight clearly applies cross-project.
+- At session end, if you made multiple discoveries, summarize them and offer to save the ones the user wants to keep.`;
 function createMcpServer(deps) {
   const server = new McpServer(
     {
       name: "mindkeg-mcp",
-      version: "0.7.0"
+      version: "0.7.2"
     },
     {
       capabilities: {
         tools: {}
-      }
+      },
+      instructions: MINDKEG_SERVER_INSTRUCTIONS
     }
   );
   const learningService = new LearningService(deps.storage, deps.embedding);
@@ -7055,7 +7088,7 @@ function registerImportCommand(program2) {
 }
 
 // cli/commands/init.ts
-import { existsSync, mkdirSync as mkdirSync3, readFileSync as readFileSync2, writeFileSync as writeFileSync2, copyFileSync } from "fs";
+import { existsSync, mkdirSync as mkdirSync3, readFileSync as readFileSync2, writeFileSync as writeFileSync2, copyFileSync, readdirSync } from "fs";
 import { resolve, join as join2, dirname as dirname3 } from "path";
 import { execSync } from "child_process";
 import { fileURLToPath } from "url";
@@ -7071,7 +7104,7 @@ function generateBashHook() {
 REPO_PATH=$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")
 export MINDKEG_REPO="$REPO_PATH"
 
-node --experimental-sqlite -e "
+OUTPUT=$(node --experimental-sqlite -e "
 (async () => {
   try {
     const os = await import('node:os');
@@ -7092,63 +7125,21 @@ node --experimental-sqlite -e "
 
     if (rows.length === 0) process.exit(0);
 
-    const lines = ['=== Mind Keg: Persistent Memory ===', ''];
+    const lines = ['Mind Keg Persistent Memory (from ~/.mindkeg/brain.db):', ''];
     for (const row of rows) {
       lines.push('- [' + row.category + '] ' + row.content);
     }
-    lines.push('', 'Use get_context for full details or store to save new knowledge.');
+    lines.push('', 'These learnings were loaded from Mind Keg. Use get_context for more details or store to save new knowledge.');
     console.log(lines.join('\\n'));
   } catch (e) {
     // Silent failure \u2014 never block session startup
   }
 })();
-" 2>/dev/null
-
-exit 0
-`;
-}
-function generatePowerShellHook() {
-  return `# Mind Keg \u2014 SessionStart auto-retrieval hook
-# Generated by: npx mindkeg-mcp init
-# Loads persistent memory at the start of every Claude Code session.
-
-try {
-    $repoPath = git rev-parse --show-toplevel 2>$null
-    if (-not $repoPath) { $repoPath = $PWD.Path }
-    $env:MINDKEG_REPO = $repoPath
-
-    node --experimental-sqlite -e "
-(async () => {
-  try {
-    const os = await import('node:os');
-    const path = await import('node:path');
-    const { DatabaseSync } = await import('node:sqlite');
-
-    const dbPath = path.join(os.homedir(), '.mindkeg', 'brain.db');
-    const db = new DatabaseSync(dbPath, { open: true, readOnly: true });
-
-    const repo = process.env.MINDKEG_REPO || '';
-    const workspace = path.dirname(repo) + '/';
-
-    const stmt = db.prepare(
-      'SELECT content, category FROM learnings WHERE status = ? AND (repository = ? OR workspace = ? OR (repository IS NULL AND workspace IS NULL)) ORDER BY updated_at DESC LIMIT 20'
-    );
-    const rows = stmt.all('active', repo, workspace);
+" 2>/dev/null)
 
-    if (rows.length === 0) process.exit(0);
-
-    const lines = ['=== Mind Keg: Persistent Memory ===', ''];
-    for (const row of rows) {
-      lines.push('- [' + row.category + '] ' + row.content);
-    }
-    lines.push('', 'Use get_context for full details or store to save new knowledge.');
-    console.log(lines.join('\\n'));
-  } catch (e) {}
-})();
-" 2>$null
-} catch {
-    # Silent failure
-}
+if [ -n "$OUTPUT" ]; then
+  echo "$OUTPUT"
+fi
 
 exit 0
 `;
@@ -7297,25 +7288,37 @@ function writeGlobalMcpConfig(homeDir, agent) {
   writeFileSync2(configPath, JSON.stringify(existing, null, 2) + "\n", "utf-8");
   return { created: true, path: configPath };
 }
-function writeGlobalHook(homeDir, agent) {
-  const config = AGENT_CONFIGS[agent];
-  if (!config.globalHookDir || !config.globalSettingsFile) return null;
-  const hookDir = join2(homeDir, config.globalHookDir);
-  const isWindows = process.platform === "win32";
-  const hookFileName = isWindows ? "load-mindkeg.ps1" : "load-mindkeg.sh";
+function detectClaudeProfiles(homeDir) {
+  const profiles = [];
+  try {
+    const entries = readdirSync(homeDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory() && entry.name.startsWith(".claude-") && entry.name !== ".claude-worktrees") {
+        const settingsPath = join2(homeDir, entry.name, "settings.json");
+        if (existsSync(settingsPath)) {
+          profiles.push(entry.name);
+        }
+      }
+    }
+  } catch {
+  }
+  return profiles;
+}
+function writeHookToDir(hookDir, settingsPath) {
+  const hookFileName = "load-mindkeg.sh";
   const hookPath = join2(hookDir, hookFileName);
   if (!existsSync(hookDir)) {
     mkdirSync3(hookDir, { recursive: true });
   }
-  const scriptContent = isWindows ? generatePowerShellHook() : generateBashHook();
+  const scriptContent = generateBashHook();
   writeFileSync2(hookPath, scriptContent, "utf-8");
-  if (!isWindows) {
+  if (process.platform !== "win32") {
     try {
       execSync(`chmod +x "${hookPath}"`, { stdio: ["pipe", "pipe", "pipe"] });
     } catch {
     }
   }
-  const settingsPath = join2(homeDir, config.globalSettingsFile);
+  const hookCommand = "bash " + hookPath.replace(/\\/g, "/");
   let settings = {};
   if (existsSync(settingsPath)) {
     try {
@@ -7323,7 +7326,7 @@ function writeGlobalHook(homeDir, agent) {
     } catch {
     }
   }
-  const hookConfig = generateHookConfig(hookPath);
+  const hookConfig = generateHookConfig(hookCommand);
   const existingHooks = settings["hooks"] ?? {};
   const newHooks = hookConfig["hooks"] ?? {};
   const existingSessionStart = existingHooks["SessionStart"] ?? [];
@@ -7340,6 +7343,13 @@ function writeGlobalHook(homeDir, agent) {
   }
   return { created: !alreadyHasMindkeg, path: hookPath };
 }
+function writeGlobalHook(homeDir, agent) {
+  const config = AGENT_CONFIGS[agent];
+  if (!config.globalHookDir || !config.globalSettingsFile) return null;
+  const hookDir = join2(homeDir, config.globalHookDir);
+  const settingsPath = join2(homeDir, config.globalSettingsFile);
+  return writeHookToDir(hookDir, settingsPath);
+}
 function ensureDatabase(homeDir) {
   const dbDir = join2(homeDir, ".mindkeg");
   const dbPath = join2(dbDir, "brain.db");
@@ -7445,6 +7455,17 @@ Mind Keg \u2014 Global Setup for ${AGENT_CONFIGS[agent].label}
     } else {
       console.log(`  - Hook already registered`);
     }
+    const profiles = detectClaudeProfiles(home);
+    for (const profile of profiles) {
+      const profileHookDir = join2(home, profile, "hooks");
+      const profileSettingsFile = join2(home, profile, "settings.json");
+      const profileResult = writeHookToDir(profileHookDir, profileSettingsFile);
+      if (profileResult.created) {
+        console.log(`  \u2713 Wrote ${profileResult.path} (profile: ${profile})`);
+      } else {
+        console.log(`  - Hook already registered in ${profile}`);
+      }
+    }
   }
   console.log("\nDatabase:");
   const dbResult = ensureDatabase(home);
@@ -8147,7 +8168,7 @@ Config location: ${settingsDir}
 }
 
 // cli/index.ts
-program.name("mindkeg").description("Mind Keg MCP \u2014 persistent memory for AI coding agents").version("0.5.0");
+program.name("mindkeg").description("Mind Keg MCP \u2014 persistent memory for AI coding agents").version("0.7.2");
 registerServeCommand(program);
 registerApiKeyCommand(program);
 registerMigrateCommand(program);