Cursor Notepads: Team Knowledge Base for AI Context

What Cursor Notepads Are and Why Teams Need Them

Every time you open a new chat in Cursor, the AI starts cold. It doesn't know your project's naming conventions, your team's architecture decisions, or the three things everyone on your team learned the hard way last quarter. You re-explain the same context over and over — in every chat, for every developer on the team.

Cursor Notepads solve this. They're persistent, reusable context documents you attach to prompts with @notepad-name. One Notepad can hold your entire API design standard. Another can store the database schema decisions that took three weeks to finalize. Instead of pasting the same wall of text into every chat, you reference the Notepad — and the AI gets everything it needs in one token-efficient lookup.

This guide covers how Notepads work, how to structure them for a team, and the patterns that make them genuinely useful versus just organized clutter.

How Cursor Notepads Work

Notepads live in the Cursor sidebar under the Notepads panel. Each one is a markdown document you write once and reference many times.

You reference a Notepad in any Cursor chat or Composer window using the @ mention syntax:

@api-standards refactor this endpoint to match our conventions

Cursor injects the full Notepad content into the AI's context window at the point of that @ reference. The model sees your standards document exactly as written — no summarization, no paraphrasing.

┌─────────────────────────────────────────┐
│  Cursor Chat                            │
│                                         │
│  User: @api-standards refactor this     │
│        endpoint to match conventions    │
│                                         │
│  ↓ Cursor resolves @api-standards       │
│                                         │
│  Context sent to model:                 │
│  [Notepad: api-standards content]       │
│  + [User message]                       │
│  + [Active file / selection]            │
└─────────────────────────────────────────┘

This makes Notepads fundamentally different from .cursorrules. Rules apply globally to every prompt in a project. Notepads are opt-in — you attach them only when relevant. That distinction matters when you have a large team with specialists working in different parts of a codebase.

Structuring a Team Knowledge Base with Notepads

The most useful Notepads follow a single-responsibility principle: one document, one concern. A Notepad that tries to cover "everything about our backend" becomes too long, too ambiguous, and too expensive in tokens.

These are the Notepad types that work well across most engineering teams:

Architecture Decisions

Document the why behind structural choices — not just what the system does, but why it's built that way. The AI generating code against your system needs this context to avoid suggesting architecturally inconsistent solutions.

# Architecture: Service Boundaries

## Decision: Domain-per-service split (adopted 2025-Q3)
Each domain (users, billing, notifications) owns its own database.
Cross-domain reads go through the service API — never direct DB joins.

## Reason
We hit N+1 query debt when the monolith shared a single schema.
Service-level ownership lets teams optimize independently.

## Consequences
- No cross-domain transactions. Use eventual consistency + events.
- Billing owns stripe_customer_id. Never replicate to user service.

## What to avoid
Don't suggest shared DB tables. Don't suggest direct service-to-service DB access.

That last section — "What to avoid" — is the most important part. The model needs explicit negative constraints, not just positive descriptions.

Coding Standards

Keep standards focused on decisions your linter can't catch: naming patterns, error handling philosophy, logging levels, async patterns your team has settled on.

# Coding Standards: TypeScript Backend

## Error handling
Use Result<T, AppError> instead of throwing. Import from `@/lib/result`.
Never swallow errors silently. Always log before returning Err().

## Naming
- Database models: PascalCase, no suffix (User, not UserModel)
- DTOs: PascalCase + suffix (CreateUserDto, UserResponseDto)
- Service methods: verb + noun (createUser, findUserById)

## Async
Prefer async/await. No raw Promise chains except in utility lib.
Always await in try/catch — never .catch() on an awaited promise.

## Logging
Use structured logging via pino. Include requestId on every log.
Log level: info for business events, debug for internals, error for failures.

Database Schema Reference

Paste the current schema — or the relevant portion — into a Notepad. When asking the AI to write queries or migrations, attach this Notepad so it generates against the actual structure, not a hallucinated approximation.

# DB Schema: Core Tables (Postgres)

## users
id          uuid        PK
email       text        UNIQUE NOT NULL
created_at  timestamptz NOT NULL DEFAULT now()
deleted_at  timestamptz NULL     -- soft delete

## subscriptions
id          uuid        PK
user_id     uuid        FK → users.id
plan        text        CHECK (plan IN ('free', 'pro', 'team'))
started_at  timestamptz NOT NULL
ended_at    timestamptz NULL

## Notes
- No cascades — handle FK integrity in application layer
- All timestamps in UTC, stored as timestamptz
- Use deleted_at for soft deletes — never hard delete users

Onboarding Context

New team members — and new AI sessions — both benefit from a "here's what this project is" document. This is the Notepad you attach when asking the AI to do something unfamiliar that touches the whole system.

# Project: What This Is

## Summary
B2B SaaS for construction project tracking. 
~40k users, 200 enterprise accounts, multi-tenant Postgres.

## Stack
- API: Hono on Bun, deployed to Fly.io
- DB: Postgres 16 via Neon (serverless)
- Auth: Clerk
- Queue: BullMQ on Redis
- Frontend: Next.js 15, shadcn/ui

## Key constraints
- Multi-tenant: every query MUST filter by organization_id
- No raw SQL in route handlers — use the query builder in @/db/
- Clerk user IDs are the source of truth for identity — never use internal user IDs in external-facing APIs

Referencing Multiple Notepads in One Prompt

You can stack multiple Notepads in a single prompt. This is useful when a task crosses domains:

@db-schema @coding-standards 
Write a repository function that finds all active subscriptions 
expiring in the next 7 days, grouped by plan type.

The model receives both documents as context before your instruction. Keep stacks to 2–3 Notepads maximum. Beyond that, you're likely asking the AI to hold too many constraints at once — better to break the task into smaller steps.

Keeping Notepads Accurate

A Notepad that's out of date is worse than no Notepad. The AI will confidently generate code against your old schema or stale conventions — and the output will look correct until it hits review.

Three practices that help:

Own each Notepad. Assign a team member as the named owner of each document. When the schema changes, that person updates the Notepad before merging the migration.

Date your decisions. Add ## Decision (adopted YYYY-MM) headers to architecture notes. This signals to the AI — and to humans — which decisions are settled versus provisional.

Review Notepads in retrospectives. Once a quarter, spend 15 minutes walking through each Notepad as a team. Ask: is this still true? Is this too detailed? Is there something missing that keeps coming up in chats?

Notepads vs .cursorrules

These two features are often confused. They serve different purposes:

Use .cursorrules for rules that apply to every single AI interaction in the project. Use Notepads for context that's relevant sometimes, but not always. The two work well together — a lean .cursorrules for universal constraints, and Notepads for specialized knowledge you pull in on demand.

Production Considerations

Token budget. Each Notepad you reference consumes tokens. A 500-line schema Notepad costs context window space on every prompt that references it. Keep Notepads focused — split large documents rather than appending indefinitely.

Sensitive data. Don't put production credentials, real customer data, or secrets in Notepads. They sync across the team via Cursor's cloud. Treat Notepad content like you'd treat a comment in a public repo.

Model context limits. If you're using a model with a smaller context window (e.g., a local model via Cursor's local model support), large Notepads can crowd out the actual code you're asking the AI to work with. Test context limits for the models your team uses.

Summary

• Cursor Notepads are persistent markdown documents injected into AI context via @notepad-name
• They solve the "cold start" problem — the AI knows your standards, schema, and decisions without re-explanation
• Structure Notepads around single concerns: architecture decisions, coding standards, schema, onboarding context
• Stack 2–3 Notepads per prompt maximum for cross-domain tasks
• Assign owners and review quarterly — stale Notepads actively mislead the AI
• Use .cursorrules for universal project rules; use Notepads for opt-in domain context

Tested on Cursor 0.47, team plan, using Claude Sonnet 4 and GPT-4o as backend models