Skip to content
/
Tier A A10 Memory engine

Kratos MCP

kratos-mcp · ceorkm/kratos-mcp · ★ 34 · last commit 2026-03-16

Primitive shape 12 total
MCP tools 12
00

Summary

Kratos MCP — Summary

Kratos MCP is a TypeScript/Node.js MCP server providing 12 "ultra-lean" memory tools for AI coding tools. Per the README, it claims "64% smaller context footprint than competitors" via a focused 12-tool surface (vs larger memory servers). It uses SQLite + FTS5 per-project, auto-detecting projects via git/package.json/directory. The repository is marked as legacy in the README — the project has evolved to ceorkm/kratos-cli (a standalone CLI), but the MCP server is still npm-installable as kratos-mcp.

It stores memories in ~/.kratos/projects/<project-id>/memories.db with per-project isolation. A PII detector ships for scanning text before saving. No hooks, no skills, no commands — just 12 MCP tools. Unlike ccmemory (Neo4j graph), basic-memory (Markdown + wikilinks), and CogniLayer (14 typed facts), Kratos uses untyped "memory" objects with tags, paths, and importance levels stored in FTS5 full-text search.

Compared to seeds: closest to ccmemory (MCP memory server for AI tools) but much simpler — flat key-value memories with FTS5 search rather than a typed graph. Self-described as "Ultra-Lean" with deliberate constraint to 12 tools. Now legacy; the active version is a separate CLI repo.

01

Overview

Kratos MCP — Overview

Origin

ceorkm. MIT license. TypeScript. Version 4.0.0 (in source). npm package kratos-mcp.

Important: The README prominently states:

"Kratos has evolved. This repo is now legacy. Kratos is now a standalone CLI — faster, lighter, works with ANY AI agent. No MCP overhead. No vendor lock-in. Just memory that works." github.com/ceorkm/kratos-cli

The MCP server is still functional and npm-installable, but active development has moved to a CLI approach.

Philosophy

From README:

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

"Just 12 essential tools. 64% smaller context footprint than competitors."

Core tenets:

  • 100% Project Isolation — each project gets its own SQLite database
  • Zero Configuration — auto-detects projects via git, package.json, or directory
  • Ultra-Lean Architecture — 12 tools only (deliberate constraint)
  • Universal Protocol — any MCP-compatible tool (Claude, Cursor, Windsurf, Continue, etc.)

Design Choices

  • 12 tools hard limit — README explicitly positions this as a feature vs larger MCP servers
  • FTS5 search — no vector embeddings; lightning-fast full-text search with smart scoring (path matching + recency + importance)
  • PII detection — security_scan tool + PIIDetector class prevents accidentally saving secrets
  • Per-project SQLite — total isolation, no cross-project contamination
02

Architecture

Kratos MCP — Architecture

Distribution

npm package: kratos-mcp

Install Methods

npm install -g kratos-mcp
npx --yes kratos-mcp@latest     # no install
claude mcp add kratos -- npx --yes kratos-mcp@latest

Directory Structure

src/
├── index.ts                # MCP server (KratosProtocolServer)
├── memory-server/
│   └── database.ts         # SQLite + FTS5 operations
├── project-manager.ts      # Auto-detection (git/package.json/dir)
├── security/
│   └── pii-detector.ts     # PII scanning
├── tools/                  # Tool implementations
├── types/                  # TypeScript types
└── utils/
    └── mcp-logger.ts       # Logger

State Files

~/.kratos/
├── projects/
│   ├── <project-id-1>/
│   │   └── memories.db     # SQLite + FTS5
│   └── <project-id-2>/
│       └── memories.db
└── global/
    └── global.db           # Optional global knowledge

Required Runtime

  • Node.js
  • npm

Target AI Tools

Claude Desktop, Claude Code, Cursor, Windsurf, Cline, BoltAI, Augment Code, Roo Code, JetBrains AI, Warp, Opencode, Continue.dev, Zed, and any other MCP client.

Auto-Detection

Project identity determined by (in order): git remote URL → package.json name → directory name. Stored as project hash ID.

03

Components

Kratos MCP — Components

MCP Tools (12)

Memory Management (7)

Tool Description
memory_save Store knowledge with tags, paths, importance level
memory_search Smart search with debug mode and path matching
memory_ask Natural language queries about memories
memory_get_recent Recently created memories with filtering
memory_get Retrieve specific memory by ID
memory_get_multiple Bulk retrieve multiple memories
memory_forget Delete memory by ID

Security (1)

Tool Description
security_scan Scan text for PII and secrets before saving

Project Management (3)

Tool Description
project_switch Switch between different projects
project_current Get current active project info
change_storage_path Dynamically change storage with data migration

System (1)

Tool Description
system_status System status and memory statistics

Hooks

None.

Skills, Commands, Subagents

None.

Scripts

None (npm package; no separate scripts).

PII Detector

src/security/pii-detector.ts — built-in PII/secret scanner called before memory_save. The agent can use security_scan tool first, but there's also an internal filter.

05

Prompts

Kratos MCP — Prompts

Prompt File 1: README Tool Usage Example

Technique: In-README code comment as agent instruction scaffold.

// Your AI now remembers:
// - Your authentication patterns
// - Your API structure
// - Your component architecture
// - Your coding standards
// - Every decision you've made

This is the only "prompt file" in the repository — the README uses TypeScript comment syntax to describe what the agent can remember, essentially documenting expected agent behavior.

Prompt File 2: Four Pillars Framework (from README, claimed in description)

The Kratos description mentions "Four Pillars Framework" but the README does not elaborate. The four pillars appear to be the four tool categories: Memory Management, Security, Project Management, System.

Natural Language Query (memory_ask tool)

Technique: Natural language parsing built into the tool itself.

The parseNaturalLanguageQuery function in src/index.ts processes queries like:

  • "show me all auth memories" → intent: 'list'
  • "explain the database schema" → intent: 'explain'
  • "find the JWT implementation" → intent: 'find'
  • "what did I do this week" → timeframe: 'week'

Technique used: Intent extraction (list/explain/find/search) + temporal parsing (today/yesterday/week) inside the tool itself, reducing need for agent to structure queries precisely.

09

Uniqueness

Kratos MCP — Uniqueness

Differs From Seeds

Closest seed: ccmemory (MCP memory server for Claude Code). Key deltas: (1) Kratos is tool-count-minimalist (12 tools, explicitly called "64% smaller context footprint than competitors"); ccmemory has ~10 tools but adds typed graph relationships, LLM detection, and Docker infrastructure. (2) Kratos uses simple flat SQLite + FTS5 with no graph, no vectors, no embeddings — ccmemory uses Neo4j + vector indexes. (3) Kratos has no hooks whatsoever (zero automatic capture); ccmemory has 4 lifecycle hooks. (4) Kratos supports a much wider range of MCP clients (Claude Desktop, Cursor, Windsurf, JetBrains, etc.); ccmemory targets only Claude Code. (5) Kratos ships a PII/secret detector built-in. Against basic-memory: basic-memory uses Markdown files + wikilinks for explicit knowledge graph; Kratos stores flat text memories with FTS5 search.

Positioning

"The minimal, universal memory layer — 12 tools, any MCP client, zero setup." The explicit anti-feature is complexity: Kratos deliberately avoids graph databases, vector embeddings, hooks, and automatic capture.

Legacy Warning

This repo is explicitly deprecated. For current use: ceorkm/kratos-cli replaces it with a CLI that works via Bash commands (no MCP overhead). Existing memories in ~/.kratos/ are compatible with the new CLI.

Observable Failure Modes

  1. No automatic capture — if agent doesn't call memory_save, nothing is remembered.
  2. FTS5 only — no semantic search; queries with different wording than stored text fail to retrieve.
  3. Legacy status — no active development on this repo; bugs won't be fixed here.
  4. No context injection — no SessionStart hook; agent must proactively search.
  5. Natural language parsing — memory_ask's NLP is heuristic (stop word removal + intent keywords); complex queries may produce poor results.
04

Workflow

Kratos MCP — Workflow

Phases

Phase What Happens Artifact
Install npm install -g kratos-mcp or claude mcp add kratos MCP server registered
Auto-detect On first use, project ID auto-detected (git/package.json/dir) ~/.kratos/projects/<id>/memories.db created
Save Agent calls memory_save with summary, text, tags, paths Memory stored in FTS5
Search Agent calls memory_search or memory_ask with natural language Relevant memories retrieved
Cross-project Agent calls project_switch to access different project Different SQLite DB queried

No Automatic Capture

Kratos does not have hooks. All memory saving requires explicit memory_save calls from the agent. Unlike ccmemory (auto-detection via Stop hook) or CSR (6 lifecycle hooks), Kratos is entirely agent-triggered.

PII Guard

Before saving sensitive content:

  1. Agent calls security_scan(text)
  2. If PII/secrets detected, save is blocked (or agent chooses not to save)
  3. memory_save itself also runs internal PII check

Approval Gates

None.

Spec Format

None.

06

Memory Context

Kratos MCP — Memory & Context

Memory Model

sqlite — per-project SQLite with FTS5 full-text search. No graph, no vectors, no embeddings.

Persistence Scope

project — each project has its own memories.db file. Optional global/global.db for cross-project shared knowledge.

Memory Structure

Each memory record has:

  • summary — short description
  • text — full content
  • tags — list of tags
  • paths — associated file paths
  • importance — priority level

Scoring

FTS5 with smart scoring:

  • Path matching bonus (if query file paths match memory paths)
  • Recency bonus (newer memories score higher)
  • Importance bonus (higher importance level boosts ranking)

Context Compaction Handling

no — no PreCompact hook; no session awareness.

Cross-Session Handoffs

yes — memories persist in SQLite across sessions. But retrieval requires explicit memory_search / memory_ask call from the agent; there is no automatic context injection at session start.

State Files

  • ~/.kratos/projects/<id>/memories.db — per-project SQLite
  • ~/.kratos/global/global.db — optional global knowledge
  • change_storage_path tool allows moving storage to custom locations (e.g., .kratos for per-project storage, /opt/kratos for shared)

Search Mechanism

full-text — FTS5 only; no vector embeddings. The memory_ask tool uses natural language parsing to extract search terms from queries before FTS5 search.

Performance

Metric Value
Context Overhead 64% smaller than v3 (claimed)
Memory Retrieval <10ms
Project Switch <100ms
Storage Overhead ~2MB per project

Token Reduction

No explicit token reduction percentages claimed in README. The "64% smaller context footprint than competitors" refers to the 12-tool surface reducing prompt overhead vs larger MCP servers.

07

Orchestration

Kratos MCP — Orchestration

Multi-Agent

No.

Orchestration Pattern

none.

Isolation Mechanism

none — project isolation is logical (different SQLite files by project ID).

Execution Mode

interactive-loop — agent explicitly calls tools; no background process.

Multi-Model

No — model-agnostic.

Context Compaction Handling

no.

Auto Validators

None.

Prompt Chaining

No.

Legacy Status

The repository is explicitly marked legacy; kratos-cli replaces it with a CLI approach that "works with ANY AI agent" (not MCP-specific). For current development, the appropriate reference is ceorkm/kratos-cli.

08

Ui Cli Surface

Kratos MCP — UI & CLI Surface

CLI Binary

  • Name: kratos-mcp (npm bin)
  • Type: thin MCP server launcher (runs Node.js stdio server)
  • No subcommands — just kratos-mcp to start the server

Local UI

None.

Transport

stdio (MCP protocol to any MCP client).

Observability

  • system_status MCP tool — server status and memory statistics

IDE Integration

Any MCP client. README documents configuration for: Claude Desktop, Claude Code, Cursor, Windsurf, Cline, BoltAI, Augment Code, Roo Code, JetBrains AI, Warp, Opencode, Continue.dev, Zed.

Note on Legacy

The README now redirects to kratos-cli at https://github.com/ceorkm/kratos-cli which works via Bash (not MCP), enabling use with any agent that can run shell commands.

Related frameworks

same archetype · same primary tool · same memory type

MemPalace ★ 53k
A10 Memory engine

Verbatim local-first AI memory with 96.6% R@5 retrieval on LongMemEval using zero API calls — structured into a palace hierarchy…

Beads (Yegge) ★ 24k
A10 Memory engine

Dolt-powered distributed graph issue tracker where AI agents track tasks with hierarchical IDs and dependency edges, claim work…

deepagents (LangChain) ★ 23k
A10 Memory engine

Opinionated Python agent harness on top of LangGraph with sub-agents, filesystem, memory, and context compaction bundled in

agentmemory ★ 18k
A10 Memory engine

Persistent, searchable memory for AI coding agents that captures every tool interaction, compresses it via LLM, and injects…

Open Multi-Agent ★ 6.3k
A10 Memory engine

Give a natural-language goal to a coordinator agent and get a dynamically decomposed, parallelized task DAG executed by…

Basic Memory ★ 3.1k
A10 Memory engine

Gives AI agents a persistent, human-readable knowledge graph of project decisions, observations, and relations stored as plain…