keep

KEEP — Knowledge Engine for Engineering Persistence

A memory layer for agentic, spec-driven software development.

Code evolves; the reasoning behind it usually doesn't get written down. KEEP keeps a small, structured /knowledge directory next to the code — specs, ADRs, tagged operational and architecture notes, and an ideas inbox — and exposes seven slash commands the agent uses to consult and maintain it as the codebase changes. Spec claims are bound to specific code symbols via anchors:; a deterministic drift check fails CI when reality diverges from the spec.

/knowledge
├── docs/
│   ├── specs/          what the system should do (behavioral specs)
│   │                     use tags `runbook` / `architecture` for ops and topology
│   └── decisions/      why it is the way it is (ADRs, flat ADR-NNNN-slug.md)
├── ideas/              half-formed proposals (promoted later via compile)
└── INDEX.md            navigation map — auto-generated, do not edit by hand

Runbooks and architecture live as specs with reserved tags, not separate top-level folders. Execution state belongs in your tracker or agent task lists, not under /knowledge.

Install

Claude Code plugin — adds the skill plus seven real slash commands with autocomplete:

/plugin marketplace add CuriousDolphin/KEEP
/plugin install keep@keep-knowledge

skills.sh — adds only the skill. Works in Claude Code, Cursor, Codex, and other Agent Skills compatible tools:

npx skills add CuriousDolphin/KEEP --skill keep -a claude-code -y

Both paths run the same logic — the skill itself is the source of truth. The plugin install registers /keep-ask, /keep-compile, … as deterministic slash commands; the skills.sh install relies on the skill triggering on either the command name or the equivalent natural language.

Commands

Seven slash commands. One root, one bootstrap, five action verbs.

Step	Surface	Purpose	Writes?
Entry point	/keep	Dashboard. If /knowledge is missing, points the user to /keep-init. Otherwise prints counts + anchor coverage (spec-level and code-level) + adaptive hints.	No
Bootstrap	/keep-init	Scaffold /knowledge, install SPEC-000-keep.md (self-spec), append KEEP snippet to AGENTS.md / CLAUDE.md / .cursorrules. Always asks consent before writing.	Scaffold only
Read	/keep-ask <question>	Synthesize an answer from /knowledge with [id] citations. Say "just list paths" for list-only output.	No
Write	/keep-compile [source] [--dry]	One command, two phases — classify a source, write/update specs+ADRs, propose anchors from concrete values, regenerate INDEX.md. --dry stops after classification. When the source is pre-existing markdown (not a git diff), the agent asks before writing.	Yes (unless --dry)
Enforce	/keep-check-drift [source]	Deterministic — scripts/check_drift.py verifies every anchor in spec frontmatter against current code (Go, Python, TypeScript). Exit 1 blocks merge. CI / pre-commit ready.	No
Capture	/keep-idea <description>	Capture a parked thought under ideas/ with type: idea, status: draft. Searches for prior art first.	Yes
Hygiene	/keep-govern	Stale, duplicated, or contradicting knowledge; oversize files; TODO(KEEP) markers; aging draft ideas. Run weekly at most.	No

Typical flows

• Questions (how, why, where, is it safe): /keep-ask first — not ad-hoc grep. If you only need paths, tell /keep-ask "just list paths".
• First-time adoption: /keep-init. The agent asks consent, scaffolds /knowledge, installs SPEC-000-keep.md, appends the AGENTS.md snippet.
• Pre-existing docs: /keep-compile ./docs/ (folder) or /keep-compile docs/auth/jwt.md (file). The agent asks: cordon (safe default) or migrate-with-verification.
• After meaningful code changes: /keep-compile (single command, classify + propose anchors + write + regen). Add --dry to preview.
• Before merge: /keep-check-drift. Exit 1 blocks merge.
• Parked ideas (not implementing now): /keep-idea "...".
• Hygiene: /keep-govern occasionally (weekly at most).

Examples

First-time adoption

> /keep-init
Asks: "Scaffold /knowledge, install SPEC-000-keep, append AGENTS.md snippet? [y/N]"
On y → creates /knowledge/{docs/{specs,decisions},ideas}, INDEX.md,
       /knowledge/docs/specs/keep/SPEC-000-keep.md, appends AGENTS.md.
       Mentions optional CI/pre-commit setup, does not auto-install.

Handling pre-existing docs

> /keep-compile ./docs/
"./docs/ has 12 markdown files. Two options:
  (a) Cordon the folder — one ADR declares it out of scope.        ← default
  (b) Walk file-by-file — ask per file: migrate, cordon, or skip.
Which do you want?"