Repo-local memory + workflow contract

Codex Memory Kit

Repo-local memory + workflow rules for Codex. Ship fast without rewriting history.

Stop losing context, stop accidental repo chaos, and stop “helpful” edits to decisions you already made. MemoryKit makes Codex predictable: startup ritual, modes, memory guards, locks, skill discovery, and git hygiene — all stored locally.

Download MemoryKit Read the Docs
  • Local memory bank in .codex/ (versionable, auditable)
  • Modes: design-first, yolo, existing, memory-only
  • Mutation guards + memory locks (no history rewrite)
  • Auto gitignore block to keep noise out
  • Skill + MCP heuristics so tools get used without babysitting
Mode menu screenshot showing design-first highlighted
Mode menu snapshot from first run.
First start: choose a mode
design-first
yolo
existing
memory-only
Motion-first prototypes before implementation. Keep history locked.

The “helpful rewrite” problem

Codex is powerful — and sometimes too eager. Decisions you “finalized” can get rewritten. Constraints can drift. Tool usage can become inconsistent. MemoryKit exists to lock the past, keep the present coherent, and make the future ship faster.

Built for consistent agents

Memory, modes, and mutation guards — all repo-local, all auditable.

Memory Bank (Local)

Everything stored in .codex/ — context, constraints, patterns, glossary.

Modes at Startup

Pick the right workflow: design-first, yolo, existing, or memory-only.

Mutation Guards

Append-only decision + history logs. No silent rewrites.

Memory Scope Locks

Lock files or sections so nothing changes without explicit unlock.

Git Hygiene

Standard .gitignore block keeps artifacts and noise out.

Skills + MCP Heuristics

Codex picks the right skill and uses tools automatically.

How it works

Five steps to make Codex behave like a reliable teammate.

Diagram showing AGENTS.md and brief.md flowing into the start command and initializing .codex memory
  1. Drop .codex/ into your repo
  2. Add AGENTS.md + brief.md at repo root
  3. In Codex, type start
  4. Choose a mode (first run)
  5. Codex builds using memory + skills, logs history

Modes

Different workflows for different project stages.

Diagram showing four modes: design-first, yolo, existing, memory-only

design-first

Build the front end first in HTML prototypes (motion-forward). No backend until UI approval.

yolo

Design-first, then full implementation with tests, docs, and screenshots when ready.

existing

For brownfield repos. Ask once whether to do a design review first.

memory-only

Skip design gates. Use memory + skills for refactors, docs, ops, analysis.

Trustable memory

Decisions and history are append-only. Locks prevent accidental changes. When Codex wants to change something important, it must either add a new decision entry or request an unlock.

Diagram showing mutation guards and memory locks protecting an append-only log

Keep the repo clean

MemoryKit installs a .gitignore block so artifacts and accidental files don’t get tracked. .codex/ remains mostly Markdown + scripts; screenshots and generated assets go into .codex/artifacts/.

Stop babysitting tool use

MemoryKit defines trigger heuristics so Codex selects the right skill for a task. When motion/UI is involved, it should use Chrome MCP for preview/screenshots and Motion MCP for animation behavior and interaction notes.

Spec Kit + Spec YOLO

MemoryKit supports optional Spec Kit integration and Spec YOLO from a single root MASTER_SPEC.md. Root canon stays visible (AGENTS.md + brief.md) with a canonical pointer (CURRENT.md) to the current guide (GUIDE.md). Add component locks and git checkpoints to stop drift as you ship.

Demo / screenshots

Real mock screenshots to show how MemoryKit feels in use.

Terminal-style mode menu on first start with design-first selected
Screenshot: Mode menu on first start
Memory active indicator with lock and yellow status dot
Screenshot: Memory-active indicator
Run summary panel showing yolo run artifacts: tests passed, screenshot saved, README updated
Screenshot: yolo run artifacts screenshot
Pipeline diagram showing design-first, approve UI, build
GIF placeholder: design-first → approve UI → build

Docs

Quick start for getting MemoryKit into your repo.

On this page Install Startup ritual Modes

Install

Copy .codex/, then add AGENTS.md, brief.md, and MASTER_SPEC.md at the repo root.

Startup ritual

Run start, pick a mode, and let MemoryKit scaffold memory and rules.

Modes

Choose design-first, yolo, existing, or memory-only based on repo state.

View Docs See Example Repo

FAQ

Does this store anything in the cloud?

No. MemoryKit is local and repo-based.

Will this prevent Codex from changing decisions?

It prevents silent rewrites. Changes must be logged as new decisions, or require unlocking.

Can it work with existing projects?

Yes. Use existing mode and optionally run a design review.

Why are there modes?

Because new projects and existing repos require different workflows. Modes remove ambiguity.

What if Codex forgets the UI indicator?

Treat that as drift and restore it. The kit’s rules require it.

Download Codex Memory Kit

Repo-local memory + workflow rules for Codex. Ship fast without rewriting history.

Download MemoryKit View Docs