kratos-mcp

  ██╗  ██╗██████╗  █████╗ ████████╗ ██████╗ ███████╗
  ██║ ██╔╝██╔══██╗██╔══██╗╚══██╔══╝██╔═══██╗██╔════╝
  █████╔╝ ██████╔╝███████║   ██║   ██║   ██║███████╗
  ██╔═██╗ ██╔══██╗██╔══██║   ██║   ██║   ██║╚════██║
  ██║  ██╗██║  ██║██║  ██║   ██║   ╚██████╔╝███████║
  ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝    ╚═════╝ ╚══════╝

The God of War remembers everything.

Persistent memory for AI coding agents. CLI-first. Auto-capture. Encrypted. Zero network calls.

Installation · Quick Start · Commands · Plugin · Security

What is Kratos?

AI coding tools forget everything between sessions. You explain your architecture, your patterns, your decisions — and tomorrow, you explain it all again.

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.

Session 1: You build auth with JWT → Kratos remembers
Session 2: "How does auth work?" → Kratos recalls instantly

Installation

npm install -g kratos-mcp

That's it. Kratos auto-detects your project from .git, package.json, Cargo.toml, go.mod, or pyproject.toml.

Quick Start

# Save a memory
kratos save "Auth uses JWT with RS256, refresh tokens in httpOnly cookies" --tags auth,jwt --importance 5

# Search memories
kratos search "authentication"

# Ask in natural language
kratos ask "how does the auth system work?"

# See what Kratos knows
kratos status

Output:

  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

Commands

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

Plugin Mode

Kratos works as a Claude Code plugin for fully automatic memory capture. No manual commands needed — everything happens in the background.

Install as Plugin

claude --plugin-dir ./plugin

What Happens Automatically

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

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.

Plugin Structure

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)

Security

Kratos was built with security as a core feature, not an afterthought.

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

# Scan text before saving
kratos scan "My API key is sk-1234abcd..." --redact

# Output:
# ✗ Secrets detected!
#   ● API Key (secret, confidence: 0.9)
# Redacted: My API key is sk-[REDACTED_SECRET]...

How It Works

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

Performance:

Metric	Value
Memory retrieval	< 10ms
Project switch	< 100ms
Storage per project	~2MB
Search engine	SQLite FTS5 (porter tokenizer)

Data Storage

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

Each project is completely isolated. Different database, different encryption key, different everything.

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:

kratos mcp

Or in your MCP client config:

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

Existing MCP users: run kratos migrate to verify your data works with the CLI. No data copy needed — same database format.

Contributing

git clone https://github.com/ceorkm/kratos-mcp.git
cd kratos-mcp
npm install
npm run build
npm run cli   # Run CLI in dev mode

License

MIT

Built for developers who are tired of repeating themselves.

Report Bug · Request Feature