kratos-cli: Instructions file for Claude Code

CLAUDE.md

Guidance for working in the kratos-memory (a.k.a. kratos-cli) repository.

What this is

A CLI-first persistent memory store for AI coding agents. Memories are saved to local SQLite databases with FTS5 full-text search — zero network calls, all data stays on disk under ~/.kratos/. Published to npm as kratos-memory; exposed as the kratos / kratos-memory binaries.

The deferred mcp__kratos__* tools available in this environment are a separate MCP wrapper around the same data store — this repo contains no MCP server code (the src/memory-server/ name is historical; it's just the DB layer).

Commands

npm run build      # tsc → dist/
npm run dev        # tsx src/cli/index.ts (run CLI from source)
npm start          # node dist/cli/index.js (run built CLI)
npm test           # builds, then runs node --test against tests/*.test.mjs

Tests (tests/cli.test.mjs) spawn the built CLI in a sandboxed $HOME, so always npm run build before testing. There is no lint step.

npm install runs scripts/ensure-better-sqlite3.mjs (postinstall), which self-heals the better-sqlite3 native binary by rebuilding it if the prebuilt .node file is missing or fails to load.

Architecture

Entry: bin/kratos-cli → loads native-module guard → imports dist/cli/index.js.

• src/cli/index.ts — Commander setup. Every subcommand lazily import()s its handler from src/cli/commands/<name>.ts so startup stays fast. Adding a command = register it here + add a file in commands/.
• src/cli/core.ts — initCLIContext() builds the CLIContext: detects the project, opens the project DB and the global DB. getScopedMemoryDb(ctx, {global}) picks which DB a command writes to. PII detector is loaded lazily.
• src/project-manager.ts — Registry-based project detection. No filesystem marker sniffing: cwd (or its deepest registered ancestor) maps to a project. Metadata lives in ~/.kratos/projects/<id>/project.json with a projects.json cache that rebuilds from disk if corrupted. Override cwd with KRATOS_PROJECT_ROOT.
• src/memory-server/database.ts — MemoryDatabase, the core. SQLite + WAL, a memories table mirrored into an FTS5 virtual table (mem_fts) via triggers. Scoped per-project (~/.kratos/projects/<id>/databases/memories.db) or global (~/.kratos/global/memories.db).
• src/security/pii-detector.ts — pattern + entropy based PII/secret detection and redaction. Backs save (warns) and scan.
• src/compression/ — RuleCompressor (via factory.createCompressor) shortens text on save --compress and in auto-capture summaries.
• src/cli/capture-handler.ts + commands/hooks.ts — opt-in auto-capture. hooks install writes a PostToolUse/Stop hook into .claude/settings.local.json that calls the hidden capture command to buffer session activity into a memory.