rag-lite

Project-memory retrieval gate, INDEX scaffolds, and per-agent rule files for AI coding agents. Install once per project; re-run to upgrade.

Why rag-lite

No vector DB. No embeddings. No daemons. No magic. Just markdown your agent already reads.

Most "RAG for code" tools want you to spin up a vector store, run an indexer, embed your docs, and pray retrieval surfaces the right chunk. rag-lite skips all of it. Your project docs are already text. Your agent already reads text. The only thing missing is a discipline that tells the agent when and how to look — that is what rag-lite installs.

• Works with the tools you already use. One command writes rules for Claude Code (CLAUDE.md), Cursor (.cursor/rules/), Gemini CLI (GEMINI.md), and any AGENTS.md-aware agent (Codex, Aider, etc.) — all from the same source of truth. Switch agents mid-project, keep the same memory.
• Plays nice with Superpowers and GSD. Pick --workflow superpowers, gsd, or both. The gate text references the workflow your team actually runs.
• Zero infrastructure. No services to host. No API keys. No background processes. The "retrieval" is your agent reading an INDEX file — the same way a human would.
• You own your docs. rag-lite manages clearly-marked regions. Everything outside the markers is yours, untouched on upgrade.
• Idempotent and CI-safe. Re-run to upgrade. --check and doctor flag drift, missing INDEX rows, and orphaned plans — drop into CI and stop letting docs rot.
• Tiny. One npx command. No lock-in — uninstall = delete the marker blocks.

If your agent keeps forgetting context, hallucinating file paths, or re-discovering the same decisions, the fix is rarely smarter retrieval. It is giving the agent a habit of looking at the index first. rag-lite is that habit, in a box.

Install / run

npx rag-lite-init

Writes (or upgrades) the following in the current directory:

• CLAUDE.md — managed marker block with the retrieval gate.
• AGENTS.md — same gate text for Codex, Aider, and other AGENTS.md-aware agents.
• GEMINI.md — same gate text for Gemini CLI.
• .cursor/rules/rag-lite.mdc — Cursor rule mirror (whole-file, CLI-owned).
• docs/INDEX.md — stable distilled-topic index (scaffolded once).
• docs/<workflow>/INDEX.md — active specs/plans index per workflow (scaffolded once).

Re-running the command upgrades managed regions in place. User content outside marker blocks and INDEX rows is preserved.

Flags

• --workflow superpowers,gsd — pick which workflows the gate references (default: both).
• --agents claude,cursor,agents-md,gemini — pick which target files to write (default: all).
• --root <path> — project root (default: cwd).
• --dry-run — print the plan; write nothing.
• --check — exit 2 if managed regions drifted from the bundled version (CI-friendly).

Subcommands

• npx rag-lite-init upgrade — alias for the default; refreshes managed marker blocks.
• npx rag-lite-init doctor — read-only drift report. Exits 2 if anything is missing or out of date, including spec/plan files not referenced from the workflow INDEX.

How it works

The CLI manages two kinds of regions:

• Marker blocks (<!-- rag-lite:start v=N --> ... <!-- rag-lite:end -->) in CLAUDE.md, AGENTS.md, and GEMINI.md. Content inside is overwritten on upgrade; everything outside is left alone.
• Whole-file ownership of .cursor/rules/rag-lite.mdc. Header comment marks it as managed.
• Scaffold-once for INDEX files: created if missing, never touched again.

Lifecycle (INDEX maintenance, stale-row sweep, graduation flow) is enforced by the gate text the agent reads — no hooks, no daemons. Run doctor periodically to spot missed bookkeeping.

Architecture

Curious how it works under the hood? See docs/ARCHITECTURE.md for ownership models, module layout, the plan/apply contract, and extension points.

License

MIT.