A cognitive enhancement layer for AI coding assistants. Persistent memory, safety guards, skill workflows, and token optimization — via MCP.
Works with Claude Code, Codex CLI, Cursor, Windsurf, OpenCode, and other MCP-compatible tools.
| Feature | Description |
|---|---|
| Persistent Memory | Cross-session knowledge storage with FTS5 search, spaced repetition, and dream-cycle maintenance |
| Safety Guards | 100+ destructive command patterns blocked (filesystem, SQL, AWS, GCP, Azure, Aliyun, Terraform, K8s) |
| Token Optimization | NTO command rewriter saves 60-90% tokens on common CLI operations |
| Skill Workflows | 20+ skills including /keep:sprint, /keep:loop, /keep:review — structured multi-agent workflows across five engineering layers |
| Multi-Tool Support | Same memory server works across Claude Code, Codex CLI, Cursor, Windsurf, and OpenCode |
| Model Manager | mx switches between 15+ LLM providers for both Claude Code and Codex CLI |
# Clone and install
git clone https://github.com/wayne-pan/keep.git
cd keep
bash scripts/install.sh
# Configure API key
mx set glm <your-api-key> # or: export ANTHROPIC_API_KEY=xxx
# Start using
claude
> /keep:onboard # first-run personalization
> /keep:sprint build a REST API # structured development workflow- OS: Ubuntu/Debian, Arch Linux, Fedora, or macOS (including WSL2)
- Runtime: Python 3.10+, Node.js 18+
- Tools: git, curl, jq
The installer handles all dependencies automatically.
keep/
├── mem/ # Memory MCP Server (Python, SQLite)
│ ├── server.py # FastMCP entry point
│ ├── tools/ # 26 MCP tools
│ ├── storage/ # SQLite persistence (observations, synthesis, entities, links)
│ ├── search/ # FTS5 + recall engine
│ └── dream/ # Memory maintenance cycle (dedup, merge, prune, strengthen)
├── hooks/ # 28 Claude Code hooks (bash)
├── skills/ # 25 skill workflows
├── scripts/ # Installer, model switcher, benchmarks
└── rules/ # Behavioral rules
keep orchestrates AI work across five cumulative layers — each wraps the one below:
| Layer | What it engineers | keep tool |
|---|---|---|
| Prompt | The request sent to the model | Direct interaction |
| Context | What the model sees | Memory MCP, context trimming |
| Harness | Tools, hooks, safety, scaffolding | hooks/, skills/, rules/ |
| Loop | One agent's repeat cycle (discover → verify → persist) | /keep:loop |
| Graph | Coordination between many specialized agents | rules/graph-engineering.md (conceptual — no skill; most tasks never need one) |
A loop is the inside of a graph node. A graph earns its keep only when a single loop can't hold the work — most tasks never need one. See rules/loop-engineering.md and rules/graph-engineering.md.
The memory MCP server provides 26 tools for persistent knowledge management:
- Store:
remember,remember_web,add_observation - Retrieve:
search,recall,timeline,get_observations,related - Maintain:
dream_cycle(dedup/merge/prune/strengthen),feedback,verify - Analyze:
smart_outline,smart_search,smart_unfold - Admin:
stats,dashboard,wakeup,lifecycle_transition
Storage: ~/.claude/mem/memory.db (SQLite) with JSONL durability for crash recovery.
Three-tier hook protection:
| Tier | Action | Examples |
|---|---|---|
| Block | Destructive patterns denied | rm -rf /, aws ec2 terminate-instances, gcloud projects delete, terraform destroy, kubectl delete namespace |
| Block | Secret leak prevention | cat ~/.aws/credentials, gcloud auth print-access-token, env dumps |
| Warn | Potentially risky ops | terraform apply, aws s3 cp, kubectl apply |
Supports: filesystem, git, SQL, AWS (26 patterns), GCP (26), Azure (16), Aliyun (24), Terraform, Docker, Kubernetes, Helm.
Ordered by the main engineering flow (align → build → verify → fix → orchestrate). The orchestration skill (/keep:loop) sits one floor above the harness — it coordinates other skills rather than running tasks directly. Run /keep:route when unsure which applies.
| Skill | Trigger | Purpose |
|---|---|---|
/keep:route |
"which skill", "help me choose" | Router — index every skill, point at the right one |
/keep:grilling |
"grill me", "align before coding" | Pre-coding alignment interview — one question at a time, each with a recommendation |
/keep:to-prd |
"write a PRD", "synthesize prd" | Turn locked plan into a published PRD (no interview) |
/keep:to-issues |
"break into issues", "vertical slices" | Decompose PRD into agent-ready vertical slices |
/keep:triage |
"triage inbox", "sort issues" | Move external-sourced issues through a state machine (raw → done) |
/keep:teach |
"teach me", "walk me through" | Multi-session teaching with spaced repetition; learner profile in memory |
/keep:sprint |
"build a feature", "implement" | Full Research → Plan → Implement → Quality Gate → Review → Test → Ship → Reflect cycle |
/keep:design-interface |
"/keep:design-interface" | Deep module interface design with seam analysis (Design It Twice) |
/keep:tdd |
"/keep:tdd" | Test-driven development workflow (red → green → refactor) |
/keep:review |
"code review", "audit" | Multi-agent cross-validation (bug hunter + security + adversarial + evaluator) |
/keep:deslop |
"/keep:deslop" | Remove code redundancy and over-engineering |
/keep:diagnosing-bugs |
"why is this broken", "debug" | Six-phase debug loop — tight red loop is a hard gate before hypothesising |
/keep:architecture-scan |
"find shallow modules", "ball of mud" | Scan codebase for deepening opportunities, ranked report |
/keep:prototype |
"spike this", "throwaway" | Disposable prototype in worktree — code answers design questions faster than prose |
/keep:handoff |
"pass this off", "wrap up session" | Cross-session handoff doc with suggested next skills |
/keep:analyze |
"analyze artifact" | RLM-style chunk+parallel+merge for large files |
/keep:ubiquitous-language |
"/keep:ubiquitous-language" | Shared vocabulary management (inline + batch modes) |
/keep:browser-use |
"/keep:browser-use" | Headless browser automation with domain knowledge |
/keep:ambient |
"/keep:ambient" | Background context awareness and monitoring |
/keep:skill-forge |
"/keep:skill" | Auto-extract reusable skill templates from experience |
/keep:loop |
"set up a loop", "run unattended" | Loop Engineering — five-move automated loop with evaluator gate |
/keep:harness |
Module changes | Manage keep's own configuration |
/keep:onboard |
"/keep:onboard" | First-run personalization wizard |
/keep:statusline |
"/keep:statusline:setup" | Token/cost/context status bar |
mx (Model Switch) is a unified model switcher for both Claude Code and Codex CLI, supporting 15+ providers:
Claude Code (emits shell exports):
mx glm # GLM 5.2
mx sonnet # Claude Sonnet 4.5
mx opus # Claude Opus 4.5
mx deepseek # Deepseek Chat
mx qwen # Qwen3 Max
mx kimi # KIMI for Coding
mx status # Show current config
# ... and moreCodex CLI (writes config.toml directly):
mx codex glm # GLM 5.2 via OpenAI-compatible endpoint
mx codex deepseek # Deepseek Chat
mx codex qwen # Qwen3 Max
mx codex kimi # KIMI K2 Thinking
# ... and moreConfig file: ~/.mx_config
Full 11-test benchmark comparing harness vs vanilla Claude Code (Opus 4.6):
| Metric | Vanilla | Harness |
|---|---|---|
| Quality | 78/110 | 79/110 |
Safety (safety-block) |
3/10 | 6/10 |
Token optimization (nto-rewrite) |
6/10 | 7/10 |
Run your own:
bash scripts/benchmark.sh # full (11 tests)
bash scripts/benchmark.sh --quick # quick (4 tests)keep works with any MCP-compatible tool:
# Auto-detect and configure during install
bash scripts/install.sh
# Or configure a specific adapter
bash scripts/install.sh --adapter cursor
bash scripts/install.sh --adapter windsurf
bash scripts/install.sh --adapter opencode
bash scripts/install.sh --adapter codex
bash scripts/install.sh --list-adapters # see all supportedThe installer also deploys a full Codex CLI harness automatically: AGENTS.md (instructions), hooks (safety guard, NTO, etc.), config.toml (MCP servers), and hooks.json (hook wiring).
| File | Location | Purpose |
|---|---|---|
| Settings | ~/.claude/settings.json |
Hooks, permissions, MCP servers |
| Memory DB | ~/.claude/mem/memory.db |
SQLite knowledge store |
| mx config | ~/.mx_config |
Model/API key |
| mx accounts | ~/.mx_accounts |
Claude Pro account store |
| Personal rules | ~/.claude/rules/personal.md |
User preferences (via /onboard) |
| Codex config | ~/.codex/config.toml |
Codex CLI model + MCP servers |
| Codex instructions | ~/.codex/AGENTS.md |
Codex behavioral instructions |
See CONTRIBUTING.md for guidelines. Bug reports and pull requests welcome.