scoops

Persistent knowledge base for Claude Code. Gives your AI agent memory that survives across sessions.

The Problem

Every new Claude Code session starts with zero context. The agent re-explores your codebase, rediscovers the same dead ends, and forgets every architectural decision you made yesterday.

scoops fixes this. It maintains a living knowledge base about your project — and injects only what's relevant, based on what you're actually working on.

How It Works

You type: "add rate limiting to the auth routes"
                    ↓
        scoops reads your prompt
        matches keywords against .claude/scoops/index.json
        pulls the 3 most relevant knowledge entries
                    ↓
    [Architecture] Auth middleware (src/middleware/auth.ts)
      Verifies JWT from httpOnly cookie
      Gotcha: jose v5 — use SignJWT class, not jwt.sign()

    [Thread] Auth system — IN PROGRESS
      Remaining: token refresh flow, rate limiting on auth routes

    [Decision] Use jose for JWT, not jsonwebtoken
      Why: jsonwebtoken has known CVEs
                    ↓
        Injected into Claude's context automatically
        Agent knows exactly where to start — no re-exploration

Three Claude Code hooks do the work:

• SessionStart — announces what's in memory (~30 tokens)
• UserPromptSubmit — matches your prompt to relevant knowledge (~200 tokens, surgically targeted)
• Stop — enforces a knowledge update if you made code changes

Install

npx scoops init

That's it. Run it in any project.

What Gets Created

.claude/scoops/
  decisions.json      — why things are the way they are
  architecture.json   — how components connect and work
  threads.json        — what's in progress, what's next
  warnings.json       — dead ends and traps to avoid
  index.json          — lightweight tag index for fast retrieval
  hooks/
    session-start.js
    prompt-retriever.js
    stop-gate.js

.claude/
  settings.json       — hook configuration (merged, not overwritten)

All files are committed to git. Teammates get the knowledge base automatically when they clone.

Knowledge Schema

decisions.json

{
  "id": "d_a1b2c3d4",
  "decision": "Use jose for JWT, not jsonwebtoken",
  "why": "jsonwebtoken has known CVEs, jose supports ESM",
  "alternatives_rejected": ["jsonwebtoken"],
  "tags": ["auth", "jwt", "security"],
  "affects": ["src/auth/*"],
  "date": "2026-03-26"
}

architecture.json

{
  "id": "a_e5f6g7h8",
  "component": "Auth middleware",
  "location": "src/middleware/auth.ts",
  "does": "Verifies JWT from httpOnly cookie, attaches user to req",
  "depends_on": ["jose"],
  "depended_by": ["all /api/admin/* routes"],
  "tags": ["auth", "middleware", "jwt"],
  "gotchas": ["jose v5: use SignJWT class, not jwt.sign()"]
}

threads.json

{
  "id": "t_i9j0k1l2",
  "thread": "Auth system",
  "status": "in_progress",
  "done": ["JWT generation", "login route"],
  "remaining": ["token refresh", "rate limiting"],
  "tags": ["auth", "jwt"],
  "blocked_by": null,
  "updated": "2026-03-26"
}

warnings.json

{
  "id": "w_m2n3o4p5",
  "warning": "bcrypt segfaults on M1 Macs in this Node version",
  "context": "Spent 45min debugging — switched to argon2",
  "avoid": "Do not add bcrypt as a dependency",
  "tags": ["auth", "hashing"],
  "date": "2026-03-25"
}

CLI Commands

scoops init                      # Set up in current project
scoops status                    # Check everything is wired up
scoops list                      # View all knowledge entries
scoops list --type decisions     # Filter by type
scoops list --tag auth           # Filter by tag
scoops prune --keep 50           # Keep only last 50 entries
scoops prune --before 2026-01-01 # Remove entries older than date
scoops export --format md        # Export as markdown
scoops export --format json      # Export as JSON

Design Principles

• Zero dependencies — Node.js built-ins only
• Standalone hooks — work even if you uninstall scoops
• Smart retrieval — keyword scoring, not "dump everything"
• Git-tracked — knowledge is version-controlled and team-shared
• Never crashes — all hooks exit 0 on any error

License

MIT