🎯 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

🚀 Installation

# Install globally
npm install -g kratos-mcp

# Or run directly with npx (no installation required)
npx kratos-mcp

# Or install as a dependency
npm install kratos-mcp

🎬 Quick Start

1️⃣ Configure Your AI Tool

{
  "mcpServers": {
    "kratos": {
      "command": "npx",
      "args": ["--yes", "kratos-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "kratos": {
      "command": "kratos-mcp",
      "args": []
    }
  }
}

claude mcp add kratos -- npx --yes kratos-mcp@latest

# First install globally
npm install -g kratos-mcp@latest

# Then add to Claude Code
claude mcp add kratos -- kratos-mcp

{
  "mcpServers": {
    "kratos": {
      "command": "npx",
      "args": ["--yes", "kratos-mcp@latest"]
    }
  }
}

{
  "command": "npx",
  "args": ["kratos-mcp"]
}

2️⃣ Start Using Kratos

// 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)

🔒 Security (1 tool)

📁 Project Management (3 tools)

⚙️ System (1 tool)

📊 How It Works

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]

🔬 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

🗂️ Memory Structure

~/.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)

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

// 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

// 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..."

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

# Clone the repo
git clone https://github.com/ceorkm/kratos-mcp.git

# Install dependencies
npm install

# Build
npm run build

# Run in development
npm run dev

📄 License

MIT © 2025 Kratos MCP Contributors

🙏 Acknowledgments

Built on the Model Context Protocol by Anthropic.

Inspired by real-world experience building production apps with AI.