kratos-mcp 4.0.0 → 4.1.0

package/README.md

@@ -1,408 +1,256 @@
 <div align="center">
 
-# 🏛️ Kratos MCP
+```
+  ██╗  ██╗██████╗  █████╗ ████████╗ ██████╗ ███████╗
+  ██║ ██╔╝██╔══██╗██╔══██╗╚══██╔══╝██╔═══██╗██╔════╝
+  █████╔╝ ██████╔╝███████║   ██║   ██║   ██║███████╗
+  ██╔═██╗ ██╔══██╗██╔══██║   ██║   ██║   ██║╚════██║
+  ██║  ██╗██║  ██║██║  ██║   ██║   ╚██████╔╝███████║
+  ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝    ╚═════╝ ╚══════╝
+```
 
-### Ultra-Lean Memory System for AI Coding Tools
+### The God of War remembers everything.
 
 [![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)
-[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
 
-**Never explain your codebase again. Let AI remember everything.**
+**Persistent memory for AI coding agents. CLI-first. Auto-capture. Encrypted. Zero network calls.**
 
-🌐 **[kratos-mcp.com](https://kratos-mcp.com)** • [Installation](#-installation) • [Quick Start](#-quick-start) • [Features](#-features) • [Tools](#-available-tools)
+[Installation](#installation) · [Quick Start](#quick-start) · [Commands](#commands) · [Plugin](#plugin-mode) · [Security](#security)
 
 </div>
 
 ---
 
-## 🎯 Why Kratos?
-
-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 an **ultra-lean memory system** that gives AI perfect recall of your project—with minimal context overhead.
-
-## ✨ Features
+## What is Kratos?
 
-<table>
-<tr>
-<td width="50%">
+AI coding tools forget everything between sessions. You explain your architecture, your patterns, your decisions — and tomorrow, you explain it all again.
 
-### 🔒 **100% Project Isolation**
-Each project gets its own SQLite database. No cross-contamination. Ever.
+Kratos gives your AI agent **permanent memory**. It auto-captures what happens during coding sessions and recalls relevant context when you start a new one. No manual work. No setup. Just install and code.
 
-</td>
-<td width="50%">
+```
+Session 1: You build auth with JWT → Kratos remembers
+Session 2: "How does auth work?" → Kratos recalls instantly
+```
 
-### ⚡ **Zero Configuration**
-Auto-detects projects via git, package.json, or directory structure. Just install and code.
+## Installation
 
-</td>
-</tr>
-<tr>
-<td width="50%">
+```bash
+npm install -g kratos-mcp
+```
 
-### 🪶 **Ultra-Lean Architecture**
-Just 12 essential tools. 64% smaller context footprint than competitors.
+That's it. Kratos auto-detects your project from `.git`, `package.json`, `Cargo.toml`, `go.mod`, or `pyproject.toml`.
 
-</td>
-<td width="50%">
+## Quick Start
 
-### 🌍 **Universal Protocol**
-Works with Claude, Cursor, Windsurf, Continue—any MCP-compatible tool.
+```bash
+# Save a memory
+kratos save "Auth uses JWT with RS256, refresh tokens in httpOnly cookies" --tags auth,jwt --importance 5
 
-</td>
-</tr>
-</table>
+# Search memories
+kratos search "authentication"
 
-## 🚀 Installation
+# Ask in natural language
+kratos ask "how does the auth system work?"
 
-```bash
-# Install globally
-npm install -g kratos-mcp
+# See what Kratos knows
+kratos status
+```
 
-# Or run directly with npx (no installation required)
-npx kratos-mcp
+**Output:**
 
-# Or install as a dependency
-npm install kratos-mcp
+```
+  KRATOS — Memory System
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  ACTIVE PROJECT
+  ● my-app
+
+  MEMORY STATS
+    Total:       47
+    Last saved:  3/15/2026, 2:16:21 PM
+    Importance:
+      5 ████████████████████ 12
+      4 █████████████░░░░░░░ 8
+      3 ████████░░░░░░░░░░░░ 5
+      2 ██████░░░░░░░░░░░░░░ 4
+      1 ░░░░░░░░░░░░░░░░░░░░ 0
+
+  TOP TAGS
+    #auth(5)  #database(4)  #api(3)  #frontend(2)
+
+  FEATURES
+    ● FTS5 Full-Text Search
+    ● AES-256-GCM Encryption
+    ● PII/Secret Detection
+    ● Smart Compression
+    ● Auto-Capture Hooks
 ```
 
-## 🎬 Quick Start
+## Commands
 
-### 1️⃣ Configure Your AI Tool
+| Command | Description |
+|---------|-------------|
+| `kratos save <text>` | Save a memory (`--tags`, `--importance 1-5`, `--paths`, `--compress`) |
+| `kratos search <query>` | Full-text search (`--limit`, `--tags`, `--debug`) |
+| `kratos ask <question>` | Natural language query |
+| `kratos recent` | Recent memories (`--limit`) |
+| `kratos get <id>` | Full memory details |
+| `kratos forget <id>` | Delete a memory |
+| `kratos status` | System dashboard |
+| `kratos switch <path>` | Switch project |
+| `kratos scan <text>` | Detect PII/secrets (`--redact`) |
+| `kratos migrate` | Verify existing data for CLI use |
+| `kratos hooks install` | Install auto-capture hooks for Claude Code |
+| `kratos hooks uninstall` | Remove hooks |
 
-<details>
-<summary><b>Claude Desktop</b></summary>
+## Plugin Mode
 
-Add to your Claude Desktop config file:
-- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-- **Linux**: `~/.config/claude/claude_desktop_config.json`
+Kratos works as a **Claude Code plugin** for fully automatic memory capture. No manual commands needed — everything happens in the background.
 
-```json
-{
-  "mcpServers": {
-    "kratos": {
-      "command": "npx",
-      "args": ["--yes", "kratos-mcp@latest"]
-    }
-  }
-}
-```
+### Install as Plugin
 
-Or if you have it installed globally:
-```json
-{
-  "mcpServers": {
-    "kratos": {
-      "command": "kratos-mcp",
-      "args": []
-    }
-  }
-}
+```bash
+claude --plugin-dir ./plugin
 ```
-</details>
 
-<details>
-<summary><b>Claude Code (Anthropic's VSCode Extension)</b></summary>
+### What Happens Automatically
 
-Run this command in your terminal:
+| Event | Action |
+|-------|--------|
+| **Session starts** | Loads recent memories into Claude's context |
+| **You edit a file** | Captures what changed, saves as memory |
+| **You run a command** | Captures the command and result |
+| **Session ends** | Claude summarizes the session (using the host LLM — free, no API key) and saves it |
 
-```bash
-claude mcp add kratos -- npx --yes kratos-mcp@latest
-```
+The plugin uses Claude Code's built-in `type: "prompt"` hook — Claude itself compresses your session memories. No external AI, no Ollama, no API keys, no network calls.
 
-Or for global installation:
+### Plugin Structure
 
-```bash
-# First install globally
-npm install -g kratos-mcp@latest
-
-# Then add to Claude Code
-claude mcp add kratos -- kratos-mcp
+```
+plugin/
+  .claude-plugin/plugin.json      # Manifest
+  hooks/hooks.json                # Lifecycle hooks (PostToolUse, Stop, etc.)
+  skills/kratos-memory/SKILL.md   # Teaches Claude how to use kratos
+  scripts/                        # Hook handlers
+  .mcp.json                       # MCP server (backward compat)
 ```
 
-See [Claude Code MCP docs](https://docs.anthropic.com/claude-code/mcp) for more info.
-</details>
+## Security
 
-<details>
-<summary><b>Cursor</b></summary>
+Kratos was built with security as a core feature, not an afterthought.
 
-Add to `.cursor/mcp_config.json` in your project root:
+| Feature | Detail |
+|---------|--------|
+| **AES-256-GCM Encryption** | Memories encrypted at rest with per-project keys |
+| **PII Detection** | Auto-detects SSN, credit cards, emails, phone numbers, IPs, DOB |
+| **Secret Detection** | Catches API keys, AWS keys, GitHub tokens, JWTs, private keys, passwords |
+| **Project Isolation** | Each project has its own SQLite database — zero cross-contamination |
+| **Zero Network Calls** | Nothing leaves your machine. Ever. No telemetry, no analytics, no cloud. |
+| **Key Rotation** | Rotate encryption keys without data loss |
 
-```json
-{
-  "mcpServers": {
-    "kratos": {
-      "command": "npx",
-      "args": ["--yes", "kratos-mcp@latest"]
-    }
-  }
-}
-```
-</details>
+```bash
+# Scan text before saving
+kratos scan "My API key is sk-1234abcd..." --redact
 
-<details>
-<summary><b>Other MCP Tools</b></summary>
+# Output:
+# ✗ Secrets detected!
+#   ● API Key (secret, confidence: 0.9)
+# Redacted: My API key is sk-[REDACTED_SECRET]...
+```
 
-Kratos works with any tool supporting the Model Context Protocol. The general format is:
+## How It Works
 
-```json
-{
-  "command": "npx",
-  "args": ["kratos-mcp"]
-}
+```
+You code with Claude
+        ↓
+  PostToolUse hook fires (auto)
+        ↓
+  Observation captured + compressed
+        ↓
+  Saved to per-project SQLite + FTS5
+        ↓
+  Next session starts
+        ↓
+  SessionStart hook loads recent context
+        ↓
+  Claude knows what happened last time
 ```
 
-**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.
+**Performance:**
 
-</details>
+| Metric | Value |
+|--------|-------|
+| Memory retrieval | < 10ms |
+| Project switch | < 100ms |
+| Storage per project | ~2MB |
+| Search engine | SQLite FTS5 (porter tokenizer) |
 
-### 2️⃣ Start Using Kratos
+## Data Storage
 
-```typescript
-// Your AI now remembers:
-// ✓ Your authentication patterns
-// ✓ Your API structure
-// ✓ Your component architecture
-// ✓ Your coding standards
-// ✓ Every decision you've made
 ```
-
-## 🛠️ Available Tools
-
-Kratos provides **12 ultra-lean tools** optimized for minimal context consumption:
-
-### 💾 Memory Management (7 tools)
-
-<table>
-<tr>
-<th>Tool</th>
-<th>Description</th>
-</tr>
-<tr>
-<td><code>memory_save</code></td>
-<td>Store important project knowledge with tags, paths, and importance levels</td>
-</tr>
-<tr>
-<td><code>memory_search</code></td>
-<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>
-
-### 🔒 Security (1 tool)
-
-<table>
-<tr>
-<th>Tool</th>
-<th>Description</th>
-</tr>
-<tr>
-<td><code>security_scan</code></td>
-<td>Scan text for PII and secrets before saving</td>
-</tr>
-</table>
-
-### 📁 Project Management (3 tools)
-
-<table>
-<tr>
-<th>Tool</th>
-<th>Description</th>
-</tr>
-<tr>
-<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>
-
-### ⚙️ 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>
-
-## 📊 How It Works
-
-```mermaid
-graph LR
-    A[Your Code] --> B[Kratos MCP]
-    B --> C{Project Detection}
-    C --> D[SQLite Database]
-    D --> E[Memory Storage]
-    E --> F[AI Tool]
-    F --> G[Perfect Context]
+~/.kratos/
+├── projects/
+│   ├── proj_abc123/
+│   │   ├── databases/
+│   │   │   └── memories.db        # SQLite + FTS5
+│   │   ├── sessions/
+│   │   │   └── current.json       # Active session buffer
+│   │   └── project.json           # Project metadata
+│   └── proj_def456/
+│       └── ...
+├── .keys/
+│   └── proj_abc123.key            # AES-256 encryption key
+└── projects.json                  # Project registry
 ```
 
-## 🔬 Under the Hood
-
-- **SQLite + FTS5**: Lightning-fast full-text search
-- **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
-
-<table>
-<tr>
-<th>Metric</th>
-<th>Value</th>
-</tr>
-<tr>
-<td>Context Overhead</td>
-<td>64% smaller than v3</td>
-</tr>
-<tr>
-<td>Memory Retrieval</td>
-<td>&lt; 10ms</td>
-</tr>
-<tr>
-<td>Project Switch</td>
-<td>&lt; 100ms</td>
-</tr>
-<tr>
-<td>Storage Overhead</td>
-<td>~2MB per project</td>
-</tr>
-</table>
-
-## 🗂️ Memory Structure
+Each project is completely isolated. Different database, different encryption key, different everything.
 
-```
-~/.kratos/                       # Default storage location
-├── projects/
-│   ├── project-id-1/
-│   │   └── memories.db          # SQLite database with FTS5
-│   └── project-id-2/
-│       └── memories.db
-└── global/
-    └── global.db                # Shared knowledge (optional)
-```
+## MCP Support (Deprecated)
+
+> **Note:** MCP support is deprecated and will be removed in a future version. The CLI and plugin are the recommended interfaces going forward. MCP consumed too much context per tool call.
+
+If you still need MCP mode:
 
-**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
-});
+```bash
+kratos mcp
 ```
 
-## 🎮 Live Demo
-
-```typescript
-// User: "Explain the auth system"
-//
-// Kratos automatically retrieves:
-// ✓ JWT implementation from 2 weeks ago
-// ✓ Middleware configuration from last month
-// ✓ User model structure from initial setup
-//
-// 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..."
+Or in your MCP client config:
+```json
+{
+  "mcpServers": {
+    "kratos": {
+      "command": "npx",
+      "args": ["kratos-mcp"]
+    }
+  }
+}
 ```
 
-## 🤝 Contributing
+Existing MCP users: run `kratos migrate` to verify your data works with the CLI. No data copy needed — same database format.
 
-We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+## Contributing
 
 ```bash
-# Clone the repo
 git clone https://github.com/ceorkm/kratos-mcp.git
-
-# Install dependencies
+cd kratos-mcp
 npm install
-
-# Build
 npm run build
-
-# Run in development
-npm run dev
+npm run cli   # Run CLI in dev mode
 ```
 
-## 📄 License
-
-MIT © 2025 Kratos MCP Contributors
-
-## 🙏 Acknowledgments
-
-Built on the [Model Context Protocol](https://modelcontextprotocol.io) by Anthropic.
+## License
 
-Inspired by real-world experience building production apps with AI.
+MIT
 
 ---
 
 <div align="center">
 
-**Built for developers who value their time.**
+**Built for developers who are tired of repeating themselves.**
 
-[Report Bug](https://github.com/ceorkm/kratos-mcp/issues) • [Request Feature](https://github.com/ceorkm/kratos-mcp/issues) • [Documentation](https://github.com/ceorkm/kratos-mcp#readme)
+[Report Bug](https://github.com/ceorkm/kratos-mcp/issues) · [Request Feature](https://github.com/ceorkm/kratos-mcp/issues)
 
 </div>

package/bin/kratos-mcp

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 
-// This is the executable wrapper for kratos-mcp
-// It ensures the MCP server runs correctly when installed globally or via npx
+// Kratos Memory — CLI + MCP Server
+// Mode detection:
+//   - CLI mode: when called with subcommands (save, search, etc.)
+//   - MCP mode: when stdin is piped (no TTY) with no args, or via `kratos mcp`
+// This preserves backward compatibility with existing MCP configurations.
 
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
@@ -10,20 +13,19 @@ import { spawn } from 'child_process';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-// Find the actual index.js file
-const indexPath = join(__dirname, '..', 'dist', 'index.js');
+// Route to the CLI entry point (which handles both CLI and MCP mode detection)
+const cliPath = join(__dirname, '..', 'dist', 'cli', 'index.js');
 
-// Spawn node with the actual server file
-const child = spawn(process.execPath, [indexPath], {
+const child = spawn(process.execPath, [cliPath, ...process.argv.slice(2)], {
   stdio: 'inherit',
-  env: { ...process.env, KRATOS_DEBUG: 'false' }
+  env: { ...process.env }
 });
 
 child.on('error', (err) => {
-  console.error('Failed to start Kratos MCP:', err);
+  console.error('Failed to start Kratos:', err);
   process.exit(1);
 });
 
 child.on('exit', (code) => {
   process.exit(code || 0);
-});
+});

package/dist/cli/capture-handler.d.ts

@@ -0,0 +1,13 @@
+import type { CLIContext } from './core.js';
+export declare class CaptureHandler {
+    private ctx;
+    private bufferPath;
+    private compressor;
+    constructor(ctx: CLIContext);
+    handlePostToolUse(data: any): Promise<void>;
+    handleSessionEnd(_data: any): Promise<void>;
+    private appendToBuffer;
+    private loadBuffer;
+    private clearBuffer;
+}
+//# sourceMappingURL=capture-handler.d.ts.map

package/dist/cli/capture-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-handler.d.ts","sourceRoot":"","sources":["../../src/cli/capture-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAqB5C,qBAAa,cAAc;IACzB,OAAO,CAAC,GAAG,CAAa;IACxB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAsB;gBAE5B,GAAG,EAAE,UAAU;IAMrB,iBAAiB,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAgD3C,gBAAgB,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;YA4BnC,cAAc;YAgBd,UAAU;YAWV,WAAW;CAO1B"}