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

Command	Use
save "<text>" --tags X --importance N	Store a memory
save "<text>" --global	Store a global memory (shared across all projects)
search "<query>"	Find by keyword
search "<query>" --global	Search global memories
ask "<question>"	Natural language query — IDF-ranked, confidence-scored, --why explains ranking
recent	Latest memories
get <id>	Full memory details
update <id> "<text>"	Edit without delete/re-save
forget <id>	Delete
pin <id>	Pin — always surfaces first
summary	Project brief
export	Dump all as JSON
status	Dashboard
scan "<text>"	Check for secrets/PII
context	Compact context block for session injection (--budget <tokens>)
hooks install	One-time per project: session injection + auto-capture + git capture

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)