kratos-mcp 1.6.0 → 4.0.0

package/README.md

@@ -1,8 +1,8 @@
 <div align="center">
-  
+
 # 🏛️ Kratos MCP
 
-### Memory System for AI Coding Tools
+### Ultra-Lean Memory System for AI Coding Tools
 
 [![npm version](https://img.shields.io/npm/v/kratos-mcp.svg)](https://www.npmjs.com/package/kratos-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
@@ -11,7 +11,7 @@
 
 **Never explain your codebase again. Let AI remember everything.**
 
-🌐 **[kratos-mcp.com](https://kratos-mcp.com)** • [Installation](#-installation) • [Quick Start](#-quick-start) • [Features](#-features) • [Documentation](#-documentation) • [Contributing](#-contributing)
+🌐 **[kratos-mcp.com](https://kratos-mcp.com)** • [Installation](#-installation) • [Quick Start](#-quick-start) • [Features](#-features) • [Tools](#-available-tools)
 
 </div>
 
@@ -21,7 +21,7 @@
 
 After building 30+ production apps with AI, we discovered a critical problem: **AI tools forget everything between sessions**. You explain your architecture, your patterns, your decisions—and tomorrow, you explain it all again.
 
-Kratos MCP solves this with the **Four Pillars Framework**—a battle-tested system that gives AI perfect memory of your project.
+Kratos MCP solves this with an **ultra-lean memory system** that gives AI perfect recall of your project—with minimal context overhead.
 
 ## ✨ Features
 
@@ -35,16 +35,16 @@ Each project gets its own SQLite database. No cross-contamination. Ever.
 </td>
 <td width="50%">
 
-### 🎯 **95.8% Context Accuracy**
-Smart retrieval engine that knows exactly what memories matter for your current task.
+### ⚡ **Zero Configuration**
+Auto-detects projects via git, package.json, or directory structure. Just install and code.
 
 </td>
 </tr>
 <tr>
 <td width="50%">
 
-### ⚡ **Zero Configuration**
-Auto-detects projects via git, package.json, or directory structure. Just install and code.
+### 🪶 **Ultra-Lean Architecture**
+Just 12 essential tools. 64% smaller context footprint than competitors.
 
 </td>
 <td width="50%">
@@ -56,57 +56,6 @@ Works with Claude, Cursor, Windsurf, Continue—any MCP-compatible tool.
 </tr>
 </table>
 
-## ⚙️ Configuration
-
-Kratos supports flexible data storage configuration to fit your workflow:
-
-### Data Storage Location
-
-Kratos determines where to store project data using this priority order:
-
-1. **Environment Variable** (highest priority)
-   ```bash
-   export KRATOS_DATA_DIR="/opt/kratos"
-   # or
-   export KRATOS_DATA_DIR="/Users/yourname/custom-kratos"
-   ```
-
-2. **Project-specific Configuration** (`.vscode/settings.json`)
-   ```json
-   {
-     "kratosDataDir": ".kratos",           // Relative to project root
-     "kratosDataDir": "/opt/kratos"        // Or absolute path
-   }
-   ```
-
-3. **Default Location** (fallback)
-   ```
-   ~/.kratos/  (User home directory)
-   ```
-
-### Configuration Examples
-
-**Per-project storage** (as requested in GitHub issue):
-```json
-// .vscode/settings.json
-{
-  "kratosDataDir": ".kratos"
-}
-```
-
-**Team shared location**:
-```bash
-export KRATOS_DATA_DIR="/opt/kratos"
-```
-
-**Custom user directory**:
-```json
-// .vscode/settings.json
-{
-  "kratosDataDir": "~/my-ai-memory"
-}
-```
-
 ## 🚀 Installation
 
 ```bash
@@ -195,333 +144,6 @@ Add to `.cursor/mcp_config.json` in your project root:
 ```
 </details>
 
-<details>
-<summary><b>Windsurf (Codeium)</b></summary>
-
-Add to `~/.windsurf/mcp_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "kratos": {
-      "command": "npx",
-      "args": ["--yes", "kratos-mcp@latest"]
-    }
-  }
-}
-```
-</details>
-
-<details>
-<summary><b>Cline (VSCode Extension)</b></summary>
-
-1. Open VSCode Command Palette (Cmd+Shift+P)
-2. Run "Cline: Edit MCP Settings"
-3. Add server configuration:
-
-```json
-{
-  "kratos": {
-    "command": "npx",
-    "args": ["kratos-mcp"]
-  }
-}
-```
-</details>
-
-<details>
-<summary><b>BoltAI</b></summary>
-
-1. Open BoltAI Settings
-2. Navigate to MCP Servers
-3. Add new server with:
-
-```json
-{
-  "name": "kratos",
-  "command": "npx",
-  "args": ["kratos-mcp"]
-}
-```
-</details>
-
-<details>
-<summary><b>Augment Code</b></summary>
-
-Add to Augment settings under MCP configuration:
-
-```json
-{
-  "mcpServers": {
-    "kratos": {
-      "command": "npx",
-      "args": ["--yes", "kratos-mcp@latest"]
-    }
-  }
-}
-```
-</details>
-
-<details>
-<summary><b>Roo Code (VSCode Extension)</b></summary>
-
-Add to `.roo/config.json`:
-
-```json
-{
-  "mcpServers": {
-    "kratos": {
-      "command": "npx",
-      "args": ["--yes", "kratos-mcp@latest"]
-    }
-  }
-}
-```
-</details>
-
-<details>
-<summary><b>Zencoder</b></summary>
-
-Configure in Zencoder settings:
-
-```json
-{
-  "mcpServers": {
-    "kratos": {
-      "command": "npx",
-      "args": ["--yes", "kratos-mcp@latest"]
-    }
-  }
-}
-```
-</details>
-
-<details>
-<summary><b>Amazon Q Developer</b></summary>
-
-Add to Q Developer settings:
-
-```json
-{
-  "mcpServers": [
-    {
-      "name": "kratos",
-      "command": "npx",
-      "args": ["kratos-mcp"]
-    }
-  ]
-}
-```
-</details>
-
-<details>
-<summary><b>Qodo Gen</b></summary>
-
-Add to Qodo configuration:
-
-```json
-{
-  "mcpServers": {
-    "kratos": {
-      "command": "npx",
-      "args": ["--yes", "kratos-mcp@latest"]
-    }
-  }
-}
-```
-</details>
-
-<details>
-<summary><b>JetBrains AI Assistant</b></summary>
-
-1. Open Settings → Tools → AI Assistant
-2. Add MCP server:
-
-```json
-{
-  "kratos": {
-    "command": "npx",
-    "args": ["kratos-mcp"]
-  }
-}
-```
-</details>
-
-<details>
-<summary><b>Warp Terminal</b></summary>
-
-Add to `~/.warp/mcp_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "kratos": {
-      "command": "npx",
-      "args": ["--yes", "kratos-mcp@latest"]
-    }
-  }
-}
-```
-</details>
-
-<details>
-<summary><b>Opencode</b></summary>
-
-Configure in Opencode settings:
-
-```json
-{
-  "mcpServers": {
-    "kratos": {
-      "command": "npx",
-      "args": ["--yes", "kratos-mcp@latest"]
-    }
-  }
-}
-```
-</details>
-
-<details>
-<summary><b>Copilot Coding Agent</b></summary>
-
-Add to Copilot configuration:
-
-```json
-{
-  "mcpServers": {
-    "kratos": {
-      "command": "npx",
-      "args": ["--yes", "kratos-mcp@latest"]
-    }
-  }
-}
-```
-</details>
-
-<details>
-<summary><b>Kiro</b></summary>
-
-Add to Kiro settings:
-
-```json
-{
-  "mcpServers": {
-    "kratos": {
-      "command": "npx",
-      "args": ["--yes", "kratos-mcp@latest"]
-    }
-  }
-}
-```
-</details>
-
-<details>
-<summary><b>OpenAI Codex</b></summary>
-
-Configure in Codex settings:
-
-```json
-{
-  "mcpServers": {
-    "kratos": {
-      "command": "npx",
-      "args": ["--yes", "kratos-mcp@latest"]
-    }
-  }
-}
-```
-</details>
-
-<details>
-<summary><b>LM Studio</b></summary>
-
-Add to LM Studio MCP configuration:
-
-```json
-{
-  "mcpServers": {
-    "kratos": {
-      "command": "npx",
-      "args": ["--yes", "kratos-mcp@latest"]
-    }
-  }
-}
-```
-</details>
-
-<details>
-<summary><b>Perplexity Desktop</b></summary>
-
-Add to Perplexity settings:
-
-```json
-{
-  "mcpServers": {
-    "kratos": {
-      "command": "npx",
-      "args": ["--yes", "kratos-mcp@latest"]
-    }
-  }
-}
-```
-</details>
-
-<details>
-<summary><b>Continue.dev</b></summary>
-
-Add to `~/.continue/config.json`:
-
-```json
-{
-  "models": [...],
-  "mcpServers": {
-    "kratos": {
-      "command": "npx",
-      "args": ["kratos-mcp"]
-    }
-  }
-}
-```
-</details>
-
-<details>
-<summary><b>Zed</b></summary>
-
-Add to `~/.config/zed/settings.json`:
-
-```json
-{
-  "assistant": {
-    "mcpServers": {
-      "kratos": {
-        "command": "npx",
-        "args": ["kratos-mcp"]
-      }
-    }
-  }
-}
-```
-</details>
-
-<details>
-<summary><b>VS Code (Generic MCP Extensions)</b></summary>
-
-For any MCP-compatible VS Code extension, add to `.vscode/settings.json`:
-
-```json
-{
-  "mcpServers": {
-    "kratos": {
-      "command": "npx",
-      "args": ["--yes", "kratos-mcp@latest"]
-    }
-  }
-}
-```
-</details>
-
-
-
 <details>
 <summary><b>Other MCP Tools</b></summary>
 
@@ -534,6 +156,8 @@ Kratos works with any tool supporting the Model Context Protocol. The general fo
 }
 ```
 
+**Compatible with:** Windsurf, Cline, BoltAI, Augment Code, Roo Code, Zencoder, Amazon Q, Qodo Gen, JetBrains AI, Warp, Opencode, Continue.dev, Zed, and more!
+
 Check your tool's documentation for specific MCP server configuration location.
 
 </details>
@@ -543,120 +167,97 @@ Check your tool's documentation for specific MCP server configuration location.
 ```typescript
 // Your AI now remembers:
 // ✓ Your authentication patterns
-// ✓ Your API structure  
+// ✓ Your API structure
 // ✓ Your component architecture
 // ✓ Your coding standards
 // ✓ Every decision you've made
 ```
 
-## 🏛️ The Four Pillars Framework
-
-Based on real-world experience building 30+ production apps with AI, Kratos implements the Four Pillars of effective AI development:
-
-### 📋 **Pillar 1: PRD (Product Requirements)**
-> "What Matters"
-
-Define not just *what* to build, but *how* AI should build it:
-- Complete page paths and user flows
-- API endpoints and data structures
-- Edge cases and integration points
-- UI/UX references and patterns
-
-### 🎯 **Pillar 2: Prompt Templates**
-> "What to Do"
-
-Reusable task templates that work perfectly with your codebase:
-- Role & stack definition
-- Clear scope constraints
-- File context specifications
-- Verification steps
-
-### 🧠 **Pillar 3: Context Retrieval**
-> "What to Inject"
+## 🛠️ Available Tools
 
-Smart injection of relevant memories based on your current task:
-- Automatic pattern matching
-- Path-based relevance scoring
-- Recency weighting
-- Semantic clustering
+Kratos provides **12 ultra-lean tools** optimized for minimal context consumption:
 
-### 💾 **Pillar 4: Memory Storage**
-> "What to Save"
-
-Permanent knowledge base that grows with your project:
-- Architecture decisions
-- Bug fixes and solutions
-- Feature implementations
-- Performance optimizations
-
-## 🛠️ Core Tools
+### 💾 Memory Management (7 tools)
 
 <table>
 <tr>
 <th>Tool</th>
 <th>Description</th>
-<th>Example</th>
 </tr>
 <tr>
 <td><code>memory_save</code></td>
-<td>Store important project knowledge</td>
-<td>
-
-```javascript
-// Save authentication pattern
-memory_save({
-  title: "JWT Auth Flow",
-  content: "Tokens in httpOnly cookies...",
-  tags: ["auth", "security"]
-})
-```
-
-</td>
+<td>Store important project knowledge with tags, paths, and importance levels</td>
 </tr>
 <tr>
 <td><code>memory_search</code></td>
-<td>Retrieve relevant memories</td>
-<td>
-
-```javascript
-// Get auth-related memories
-memory_search({
-  query: "authentication",
-  k: 5
-})
-```
+<td>Smart semantic search with debug mode and path matching</td>
+</tr>
+<tr>
+<td><code>memory_ask</code></td>
+<td>Natural language queries about your memories</td>
+</tr>
+<tr>
+<td><code>memory_get_recent</code></td>
+<td>Get recently created memories with filtering</td>
+</tr>
+<tr>
+<td><code>memory_get</code></td>
+<td>Retrieve a specific memory by ID</td>
+</tr>
+<tr>
+<td><code>memory_get_multiple</code></td>
+<td>Bulk retrieve multiple memories</td>
+</tr>
+<tr>
+<td><code>memory_forget</code></td>
+<td>Delete a memory by ID</td>
+</tr>
+</table>
 
-</td>
+### 🔒 Security (1 tool)
+
+<table>
+<tr>
+<th>Tool</th>
+<th>Description</th>
 </tr>
 <tr>
-<td><code>prd_update</code></td>
-<td>Define project requirements</td>
-<td>
-
-```javascript
-// Update PRD section
-prd_update({
-  feature: "api_structure",
-  content: "RESTful endpoints..."
-})
-```
+<td><code>security_scan</code></td>
+<td>Scan text for PII and secrets before saving</td>
+</tr>
+</table>
 
-</td>
+### 📁 Project Management (3 tools)
+
+<table>
+<tr>
+<th>Tool</th>
+<th>Description</th>
 </tr>
 <tr>
-<td><code>prompt_build</code></td>
-<td>Create reusable prompts</td>
-<td>
-
-```javascript
-// Build structured prompt
-prompt_build({
-  goal: "Create React component",
-  role: "Senior React Developer"
-})
-```
+<td><code>project_switch</code></td>
+<td>Switch between different projects</td>
+</tr>
+<tr>
+<td><code>project_current</code></td>
+<td>Get current active project info</td>
+</tr>
+<tr>
+<td><code>change_storage_path</code></td>
+<td>Dynamically change storage location with automatic data migration</td>
+</tr>
+</table>
 
-</td>
+### ⚙️ System (1 tool)
+
+<table>
+<tr>
+<th>Tool</th>
+<th>Description</th>
+</tr>
+<tr>
+<td><code>system_status</code></td>
+<td>Get system status and memory statistics</td>
 </tr>
 </table>
 
@@ -666,11 +267,10 @@ prompt_build({
 graph LR
     A[Your Code] --> B[Kratos MCP]
     B --> C{Project Detection}
-    C --> D[Project Database]
+    C --> D[SQLite Database]
     D --> E[Memory Storage]
-    D --> F[Context Broker]
-    F --> G[AI Tool]
-    G --> H[Perfect Context]
+    E --> F[AI Tool]
+    F --> G[Perfect Context]
 ```
 
 ## 🔬 Under the Hood
@@ -679,6 +279,7 @@ graph LR
 - **Smart Scoring**: Path matching + recency + importance
 - **Auto-detection**: Git, package.json, or directory-based
 - **Secure**: All data stays local, no external calls
+- **Lean**: Only 4 core components, minimal memory footprint
 
 ## 📈 Performance
 
@@ -688,8 +289,8 @@ graph LR
 <th>Value</th>
 </tr>
 <tr>
-<td>Context Accuracy</td>
-<td>95.8%</td>
+<td>Context Overhead</td>
+<td>64% smaller than v3</td>
 </tr>
 <tr>
 <td>Memory Retrieval</td>
@@ -708,30 +309,63 @@ graph LR
 ## 🗂️ Memory Structure
 
 ```
-.kratos/
+~/.kratos/                       # Default storage location
 ├── projects/
 │   ├── project-id-1/
-│   │   ├── memories.db      # SQLite database
-│   │   ├── prd.yml          # Product requirements
-│   │   └── prompts/          # Reusable templates
+│   │   └── memories.db          # SQLite database with FTS5
 │   └── project-id-2/
-│       └── ...
-└── config.yml                # Global configuration
+│       └── memories.db
+└── global/
+    └── global.db                # Shared knowledge (optional)
+```
+
+**New in v1.6.1:** Use `change_storage_path` to move data to custom locations like `/opt/kratos` or `.kratos` for per-project storage.
+
+## 💡 Example Usage
+
+```typescript
+// Save a memory
+await memory_save({
+  summary: "JWT auth implementation",
+  text: "We use httpOnly cookies with refresh tokens...",
+  tags: ["auth", "security"],
+  paths: ["src/middleware/auth.ts"],
+  importance: 5
+});
+
+// Search memories
+await memory_search({
+  q: "authentication",
+  k: 5,
+  debug: true  // Get search insights
+});
+
+// Ask natural language questions
+await memory_ask({
+  question: "How does our auth system work?",
+  limit: 10
+});
+
+// Change storage location
+await change_storage_path({
+  newPath: "/opt/kratos",
+  migrate: true,
+  backup: true
+});
 ```
 
 ## 🎮 Live Demo
 
 ```typescript
 // User: "Explain the auth system"
-// 
+//
 // Kratos automatically retrieves:
 // ✓ JWT implementation from 2 weeks ago
-// ✓ Middleware configuration from last month  
+// ✓ Middleware configuration from last month
 // ✓ User model structure from initial setup
-// ✓ Security decisions from PRD
 //
-// AI Response: "Your auth uses JWT with refresh tokens 
-// stored in httpOnly cookies. The middleware validates 
+// AI Response: "Your auth uses JWT with refresh tokens
+// stored in httpOnly cookies. The middleware validates
 // tokens on protected routes at /api/middleware/auth.ts:42..."
 ```
 
@@ -746,6 +380,9 @@ git clone https://github.com/ceorkm/kratos-mcp.git
 # Install dependencies
 npm install
 
+# Build
+npm run build
+
 # Run in development
 npm run dev
 ```
@@ -758,7 +395,7 @@ MIT © 2025 Kratos MCP Contributors
 
 Built on the [Model Context Protocol](https://modelcontextprotocol.io) by Anthropic.
 
-Inspired by the Four Pillars Framework and real-world experience building production apps with AI.
+Inspired by real-world experience building production apps with AI.
 
 ---