How MeowKit persists learnings across sessions — the .meowkit/ state root, topic files, capture, pruning.

MeowKit stores engineering learnings under a runtime-neutral .meowkit/ state root — fix patterns, review findings, architecture decisions. Skills read only the topic files relevant to their domain. There is no auto-injection pipeline.

The `.meowkit/` state root

Project state lives at .meowkit/, resolved from the nearest version-control root (or, in a non-git checkout, a directory that already owns both package.json and an existing .meowkit/). It never keys off a provider directory (.claude/, .codex/, .cursor/) — those are install targets, not state-discovery sentinels — so the same state root works whether the project is driven by Claude Code, Codex, or another provider.

Directory	Purpose
`memory/`	Curated stores + topic files described below
`telemetry/`	Session/cost telemetry
`state/`	Locks (`state/migrate.lock`, per-store locks under `state/locks/`) and other runtime state
`cache/`	Disposable derived data
`migrations/`	Migration bookkeeping

Topic files

File	Consumer	Read when
`fixes.json`	`mk:fix`	Bug diagnosis
`review-patterns.md` + `review-patterns.json`	`mk:review`, `mk:plan-creator`	Code review or planning
`architecture-decisions.md` + `architecture-decisions.json`	`mk:plan-creator`, `mk:cook`	Architecture work
`security-notes.md`	`mk:cso`, `mk:review`	Security audit
`cost-log.json`	analyst, `mk:memory`	Cost reporting
`decisions.md`	architect	Long-form ADRs

JSON-first. For the curated stores (fixes, review-patterns, architecture-decisions, security-findings) the .json file is canonical and schema-validated; the Markdown under views/ is a generated, non-authoritative view. mk:fix reads and writes fixes.json only for bug-class patterns. Long-session continuity is handled by the host runtime's native compaction — MeowKit no longer keeps its own conversation summary.

Machine-local by default. .meowkit/memory/* is gitignored — content is developer-specific working state. Only .gitkeep is tracked.

The write contract

Every managed write to a curated store — the mewkit memory capture CLI, a provider capture hook, or a skill/adapter — goes through one validated pipeline instead of hand-rolling file writes:

schema validation (zod) → secret scrub → injection scan → per-store lock → atomic replace (temp-file + rename)

This is the single write authority for .meowkit/memory/. Skills, hooks, and adapters never construct the store path or dedupe/lock logic themselves.

How to capture

There are two write paths. Pick the right one — picking the wrong one means the entry is silently lost.

Path 1 — `mewkit memory capture` (`##prefix:` shortcut)

The human user types messages with a ## prefix. Codex's UserPromptSubmit capture hook is a thin wrapper that pipes the prompt straight to npx mewkit memory capture — the CLI is the single capture authority behind it, so the locking/scrub/scan logic lives in one place instead of being duplicated per provider:

Prefix	Target
`##decision: chose X over Y because…`	`architecture-decisions.json`
`##pattern: DESCRIPTION`	`review-patterns.json`
`##note: TEXT`	`quick-notes.md`

A non-prefixed prompt is a fast no-op (exit 0). See memory capture for direct CLI usage.

The hook does NOT fire on agent or tool output. It is bound to UserPromptSubmit semantics. Agents that need to capture use Path 2 below.

Path 2 — Agent-authored entry via direct `Edit`

When an agent or skill identifies a learning, it calls Edit directly on the appropriate topic file under .meowkit/memory/. There is no hook — the agent scrubs secrets in-content before writing.

The mk:fix skill's Step 6 is the canonical example: read the live JSON schema and add or update a structured entry via Edit.

Session-end capture

The Stop hook auto-appends cost entries to cost-log.json and resolves the active model id from session-state/detected-model.json via resolve-model.sh. Phase 6 (Reflect) runs prose-driven session capture via direct Edit. There is no mewkit memory session-capture CLI subcommand; content extraction needs LLM analysis.

How to read

Skills include a "Load memory" step in their SKILL.md. The agent uses Read to load the relevant topic file at task start. Nothing is injected on subsequent turns.

Validate and regenerate

mewkit memory validate     # Schema-validate the curated stores (--strict to fail on errors)
mewkit memory seed-from-md # Populate JSON stores from Markdown (run once after upgrading)
mewkit memory render-views # Regenerate views/*.md from the canonical JSON
mewkit doctor --state      # Report curated-memory health

The generated views/*.md carry a "generated — do not edit" banner — edit the JSON and re-run render-views. After an upgrade, run seed-from-md once so existing Markdown topic files are migrated into the JSON stores.

Pruning

/mk:memory --prune              # Archive entries older than 90 days
/mk:memory --prune --days 180   # Custom threshold
/mk:memory --prune --dry-run    # Preview without writing

Entries move to lessons-archive.md. Exempt: entries marked severity: critical or severity: security. Prune when a single topic file exceeds 300 lines or all topic files exceed 500 lines.

Separate from Claude Code auto-memory

Claude Code has its own auto-memory at ~/.claude/projects/PROJECT/memory/. It is separate from MeowKit's .meowkit/memory/. Use Claude Code auto-memory for personal habits; use MeowKit memory for project-specific engineering artifacts.

Memory System