Kratos Memory

Kratos Memory

Persistent memory across sessions for any AI coding agent. Save what matters, recall it later. Local SQLite, zero network calls, 40ms per command.

Setup Check

Before using any command, verify kratos-memory is installed AND working:

kratos-memory status

If command not found — install it:

npm install -g kratos-memory

If status fails with a native module error (e.g. NODE_MODULE_VERSION mismatch) — reinstall:

npm uninstall -g kratos-memory && npm install -g kratos-memory

If npm is unavailable, use npx (slower but works without install):

npx kratos-memory@latest status

Only proceed once status runs successfully. If it shows project info and memory stats, the setup is healthy.

If running inside Claude Code or Codex, also install the hooks — once per project (requires kratos-memory >= 1.8.0 for Codex, >= 1.7.0 for Claude Code):

kratos-memory hooks status

If they are not installed (or are flagged as legacy format), run:

kratos-memory hooks install

This wires SessionStart (memory auto-injected into every session), PostToolUse/Stop (auto-capture), and a git post-commit hook (every commit saved as a memory) — for Claude Code (.claude/settings.local.json) and Codex (.codex/hooks.json) in one shot. In Codex, run /hooks once afterwards to trust them. After this, memory loads and saves itself — but you must STILL save explicitly per the triggers below, because hooks capture activity, not reasoning.

Two Memory Scopes

Kratos has two memory layers. Use the right one:

Project memory (default) — isolated per project. Architecture decisions, repo-specific patterns, project config, file structures. Only visible when working in that project.

Global memory (--global flag) — shared across ALL projects. Reusable bug fixes, tool gotchas, workflow patterns, general engineering lessons. Visible from any project.

Add --global or -g to any command to use global memory:

kratos-memory save "..." --global     # save to global
kratos-memory search "..." --global   # search global
kratos-memory recent --global         # recent global memories

Session Start — Always Do This

At the beginning of every session, load project context:

kratos-memory context

This is a compact, token-budgeted block: pinned rules first, then decisions and fixes, then recent work (project + global merged). If hooks are installed it is already injected automatically — do not run it twice. For the full report (topics, most-touched files, stale memories worth pruning):

kratos-memory summary

If working on a specific area, search for it:

kratos-memory ask "How does [area] work?"

Use this context to avoid re-asking the user things they already explained in prior sessions.

When to Save — Proactive Triggers

Save immediately when any of these happen. Do not ask permission — just save.

After fixing a bug — save BOTH project and global:

# Project: what was fixed in this repo
kratos-memory save "Fixed [what] — root cause was [why]. Changed [file] to [how]." --tags bug,fix --importance 4 --paths path/to/file.ts

# Global: the reusable lesson (only if the fix applies beyond this project)
kratos-memory save "If you encounter [symptom], the cause is usually [root cause]. Fix: [general solution]." --tags bug,fix --importance 4 --global

After the user explains how something works:

kratos-memory save "[What they explained]" --tags architecture --importance 4 --paths relevant/file.ts

After making a design or architecture decision:

kratos-memory save "Chose [X] over [Y] because [reason]." --tags decision,architecture --importance 5

After discovering infrastructure/deployment details:

kratos-memory save "[Service] hosted on [platform]. [Details]." --tags infrastructure --importance 4

When the user sets a rule ("never do X", "always do Y"):

kratos-memory save "[The rule]" --tags rules --importance 5

Then pin it so it always surfaces first:

kratos-memory pin <id>

After discovering a tool gotcha or workflow pattern (GLOBAL):

kratos-memory save "npm rebuild better-sqlite3 reports success but doesn't build. Use npm run build-release instead." --tags tooling,gotcha --importance 4 --global

After completing significant work:

kratos-memory save "Session: [what was done]. Key changes: [list]. Files: [list]." --tags session --importance 3

Core Commands — Quick Reference

Add --global / -g to any read/write command to use global scope.

For full command reference with all options, see references/api_reference.md.

Saving Best Practices

• Be specific — "Auth uses JWT RS256 with httpOnly refresh tokens" not "we use JWT"
• Include file paths — --paths src/auth.ts helps future agents find the code
• Include the WHY — "Chose X because Y" is more valuable than "Using X"
• Use consistent tags — bug, fix, architecture, decision, security, database, api, frontend, backend, infrastructure, performance, rules
• Scan before saving sensitive text — kratos-memory scan "<text>" detects API keys, passwords, PII
• Pin critical rules — anything that should never be forgotten

When to Save Global vs Project

Save to GLOBAL (`--global`) when:

• The lesson applies to ANY project (not just this one)
• You fixed a bug caused by a tool/library/platform behavior
• You discovered a workflow pattern (e.g., "Codex needs --write flag")
• The user shares a general preference that should apply everywhere

Save to PROJECT (default) when:

• It's about THIS repo's architecture, patterns, or config
• It's about specific files, endpoints, or schemas in this project
• It's a project-specific rule or convention

When stuck on a bug — search both:

kratos-memory search "the error message"           # check this project first
kratos-memory search "the error message" --global   # then check global lessons

What NOT to Save

• Code that's already in the repo (that's what git is for)
• Temporary debugging notes
• Obvious language/framework knowledge Claude already has
• Duplicate information — search first, update if exists

Keeping Memory Canonical

When a fact changes (new deploy target, new version, corrected decision), do not just save a new memory next to the stale one — replace it:

kratos-memory save "Deploy target is now Fly.io fra" --tags deploy --supersedes <old-id>

The old memory is expired (kept on disk, hidden from all reads). This stops outdated debugging history from outranking current facts.

• Routine edits to global memory (don't save "edited button.tsx" globally)

Kratos Memory — Command Reference

Table of Contents

• Installation
• save
• search
• ask
• recent
• get
• update
• forget
• pin
• summary
• export
• status
• scan
• context
• hooks
• JSON Mode
• Project Isolation
• Tags Convention

Installation

# Global install (recommended — fastest, ~40ms per command)
npm install -g kratos-memory

# Or use npx (no install needed, slower first run)
npx kratos-memory@latest

After global install, use kratos-memory directly. With npx, prefix commands with npx kratos-memory@latest.

To check if installed: kratos-memory --version

Global Memory

All read/write commands support --global / -g to use the global memory store instead of the project-scoped store.

Global memories are shared across ALL projects. Use for reusable lessons, tool gotchas, and workflow patterns.

kratos-memory save "lesson" --global          # save globally
kratos-memory search "query" --global         # search global
kratos-memory recent --global                 # recent global memories
kratos-memory get <id> --global               # get from global
kratos-memory update <id> "text" --global     # update global memory
kratos-memory forget <id> --global            # delete from global
kratos-memory pin <id> --global               # pin in global
kratos-memory export --global                 # export global memories

save

Store a memory with tags, file paths, and importance.

kratos-memory save "<text>" [options]

Importance: 5=critical, 4=important, 3=normal, 2=minor, 1=low

Examples:

kratos-memory save "Auth uses JWT RS256, refresh in httpOnly cookies" --tags auth,security --importance 5 --paths src/auth.ts
kratos-memory save "Fixed crash in search — null check on empty results" --tags bug,fix --importance 4 --paths src/search.ts

search

Find memories by keyword. Returns relevance percentage.

kratos-memory search "<query>" [-l limit] [-t tags] [-d] [--path-match] [-j]

ask

Results are IDF-ranked (rare terms dominate), cut at the score cliff (weakly related results dropped), and tagged with a confidence level (high/medium/low). Default limit is 5.

Natural language question — synthesizes answer from matching memories.

kratos-memory ask "<question>" [-l limit] [-j]

recent

Latest memories, newest first.

kratos-memory recent [-l limit] [--path-prefix <prefix>] [-j]

get

Retrieve one memory by ID.

kratos-memory get <id> [-j]

update

Edit a memory without delete + re-save.

kratos-memory update <id> "<new text>" [-t tags] [-i importance] [-p paths] [-j]

forget

Delete a memory.

kratos-memory forget <id> [-j]

pin

Pin = always surfaces first in search. For critical rules and context.

kratos-memory pin <id>
kratos-memory pin <id> --unpin

summary

Project brief: pinned items, key decisions, topics, recent.

kratos-memory summary [-j]

export

Dump all memories as JSON to stdout.

kratos-memory export > backup.json

status

Dashboard: project, memory count, importance distribution, tags.

kratos-memory status [-j]

scan

Detect secrets and PII before saving.

kratos-memory scan "<text>" [--redact] [-j]

Detects: SSN, credit cards, emails, API keys (sk-, ghp_, AKIA), JWTs, passwords.

context

Compact, token-budgeted memory block for session injection (used by the Claude Code SessionStart hook; also useful manually). Requires kratos-memory >= 1.7.0.

kratos-memory context [options]

Sections: Pinned, Decisions & fixes (importance 4+), Recent, last session summary. Merges project and global scopes. Prints nothing when the project has no memories.

hooks

Install or manage automatic memory enforcement for Claude Code projects. Requires kratos-memory >= 1.7.0.

kratos-memory hooks install     # SessionStart injection + auto-capture + git post-commit
                                # writes Claude Code AND Codex (.codex/hooks.json) hooks
kratos-memory hooks status      # check what is installed (flags legacy-format entries)
kratos-memory hooks uninstall   # remove kratos hooks only; user hooks untouched

Install is idempotent and migrates legacy flat-format entries that Claude Code silently ignores. Codex hooks use the same schema; Codex requires one-time approval via /hooks. The git post-commit hook appends a marker-delimited block and preserves any existing hook script.

JSON Mode

All commands support -j / --json for machine-readable output.

Project Isolation

Each project gets its own SQLite database. Kratos auto-detects projects from its own registry — the first time you run kratos in a directory, it registers that directory as a project. Subdirectories reuse the parent project.

Global memories (--global) are stored separately at ~/.kratos/global/memories.db and are accessible from any project.

Tags Convention