kratos-memory

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

The God of War remembers everything.

Persistent memory for AI coding agents. Works with any agent — Claude Code, Codex, Cursor, Cline, or anything that runs Bash.

What is Kratos?

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

Kratos gives your AI agent permanent memory. Every observation is saved and searchable locally. No cloud, no API keys, no vendor lock-in.

> use npx kratos-memory CLI. save what you learn, search when you need context.

Agent runs: npx kratos-memory search "auth"
Agent gets: JWT auth with refresh tokens, 15-min expiry, httpOnly cookies...
Agent runs: npx kratos-memory save "Added rate limiter to /api routes" --tags middleware

Works with any AI coding agent that can execute shell commands.

Install

npx kratos-memory

That's it. No global install needed. Auto-detects your project.

Commands

Command	What it does
npx kratos-memory save <text>	Save a memory (--tags, --importance 1-5, --paths, --supersedes <id>, --json)
npx kratos-memory search <query>	Full-text search with FTS5 (--limit, --tags, --debug, --json)
npx kratos-memory ask <question>	Natural language query — learns your vocabulary, IDF-ranked, confidence-scored (--why, --json)
npx kratos-memory recent	Recent memories (--limit, --json)
npx kratos-memory get <id>	Full memory details (--json)
npx kratos-memory forget <id>	Delete a memory (--json)
npx kratos-memory status	System dashboard (--json)
npx kratos-memory switch <path>	Switch project (--json)
npx kratos-memory scan <text>	Detect PII and secrets (--redact, --json)
npx kratos-memory context	Compact memory block for session injection (--budget, --json)
npx kratos-memory summary	Project report: decisions, topics, most-touched files, prune candidates
npx kratos-memory hooks install	Install hooks (Claude Code + Codex): memory injection, per-prompt recall, auto-capture, git commit capture
npx kratos-memory hooks install --global	Same for Claude Code, but in ~/.claude/settings.json — every project on the machine, zero per-repo setup

Kratos also supports machine-readable output for automation-heavy workflows. Use --json on the core read/write commands when you want agents, scripts, or CI to parse results safely.

How agents use it

Just tell your agent:

Use npx kratos-memory CLI for persistent memory. Run npx kratos-memory --help to see commands. Save important observations. Search before starting work.

Or drop the included AGENTS.md file in your project root — any agent that reads project files will pick it up.

Claude Code

One command, fully automatic, every project on the machine:

npx kratos-memory hooks install --global

Or per-project (also wires Codex + git hooks):

npx kratos-memory hooks install

This wires these hooks:

• SessionStart — kratos context injects pinned memories, decisions, and recent work into every new session. The agent starts already knowing the project.
• UserPromptSubmit — each prompt is searched against project + global memory; clearly relevant memories are injected at the moment they matter. Silent otherwise.
• PostToolUse — file edits are buffered (no per-edit DB writes).
• SessionEnd / PreCompact — one consolidated session summary is saved when the session ends or before context compaction.
• git post-commit — every commit is saved as a memory (message + changed files). Per-project install only.

Hooks call one stable path forever: ~/.kratos/bin/kratos. Kratos rewrites that launcher on every run to point at the current install, so node upgrades, nvm switches, and reinstalls never break the hooks and never require rewriting them.

No prompting, no relying on the model to remember to check memory — the hooks enforce it.

Codex

The same install command also writes .codex/hooks.json with identical lifecycle hooks (SessionStart memory injection, auto-capture, session summary):

npx kratos-memory hooks install

Then run /hooks once inside Codex to trust them — Codex requires explicit approval for project hooks.

Cursor / Cline / Any agent

Same pattern. If it can run Bash, it can use Kratos.

Features

Feature	Detail
FTS5 Search	Full-text search with porter tokenizer, smart fallbacks, <10ms retrieval
Local-only Storage	All data stays on your machine, zero network calls
PII Detection	Auto-detects SSN, credit cards, emails, phones, API keys, AWS keys, JWTs
Project Isolation	Each project gets its own SQLite database — zero cross-contamination
Smart Compression	Rule-based compression, no AI dependency
Auto-Capture Hooks	Optional hooks for Claude Code sessions
Zero Network Calls	Nothing leaves your machine. Ever.

How it works

You tell your agent "use kratos-memory"
        ↓
Agent runs: npx kratos-memory search "relevant context"
        ↓
Agent gets memories from local SQLite + FTS5
        ↓
Agent works with full context
        ↓
Agent runs: npx kratos-memory save "what it learned"
        ↓
Stored locally, searchable forever

Data storage

~/.kratos/
├── projects/
│   ├── proj_abc123/
│   │   ├── databases/
│   │   │   └── memories.db        # SQLite + FTS5
│   │   └── project.json           # Project metadata
│   └── proj_def456/
│       └── ...
└── projects.json                  # Project registry

Each project is completely isolated with its own database.

Security

• PII detection — SSN, credit cards, emails, phones, IPs, DOB
• Secret scanning — API keys, AWS keys, GitHub tokens, JWTs, private keys
• Auto-redaction — captured hook payloads are scanned and redacted before storage
• Zero network calls — nothing ever leaves your machine
• No telemetry, no analytics, no cloud

Coming from Kratos MCP?

This is the successor to kratos-mcp. We moved from MCP to CLI because MCP eats tokens before you ever use it. The CLI is lighter, faster, and works with any agent — not just MCP-compatible ones.

The actual numbers (measured on Claude Code):

	MCP server	CLI
Tool schemas loaded into every session	1,538 tokens (12 tools)	0 tokens
Cost before the first memory is read	1,538 tokens	0 tokens
Invocation	JSON-RPC tool call	one Bash command (~30 tokens)

The MCP version pays ~1.5k tokens of schema overhead in every session of every project, even sessions that never touch memory. At 20 agent sessions a day that's ~31k tokens/day of pure overhead. The CLI pays nothing until the moment it's actually used — and the responses are the same JSON either way.

Your data is already compatible. Both versions use the same ~/.kratos/ storage and SQLite format. Just start using npx kratos-memory and your existing memories are there.

npx kratos-memory status   # see your existing memories
npx kratos-memory recent   # they're all here

Contributing

PRs welcome at github.com/ceorkm/kratos-cli/pulls

License

MIT

Built for developers who are tired of repeating themselves.

Report Bug · Request Feature