mindkeg-mcp 0.7.1 → 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);
@@ -8135,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);