ReadmeDB

A persistent markdown file store for AI agents, accessed via MCP (Model Context Protocol). Agents connect once and can read, write, search, and version files across sessions and platforms.

What it does

• Agents get a personal file namespace scoped to their API key
• Files persist across restarts, machines, and agent types (Claude, Cursor, Codex, Windsurf, etc.)
• 14 MCP tools: bulk read, find/replace, atomic rename, version history, one-call restore, and more
• Quota and rate limiting per plan; Stripe billing for upgrades

Quick start

1. Prerequisites

• Node.js 20+
• pnpm (npm i -g pnpm)
• A Postgres database (local or hosted — Neon free tier works)
• A Clerk account (free tier works)
• A Stripe account (test mode is fine)

2. Clone and install

git clone <your-repo-url>
cd readmedb
pnpm install

3. Set up environment variables

Copy .env.example to .env.local and fill in each value:

cp .env.example .env.local

See Environment variables below for what each one means.

4. Push the database schema

pnpm drizzle-kit push

This creates all tables in your Postgres database.

5. Seed the default plan

Connect to your Postgres database and run:

INSERT INTO plans (id, name, max_files, max_storage_bytes, rate_limit)
VALUES ('free', 'Free', 50, 5242880, 60)
ON CONFLICT (id) DO NOTHING;

6. Configure Clerk webhooks

In your Clerk dashboard → Webhooks → Add endpoint:

• URL: https://your-domain.com/api/webhooks/clerk
• Events: user.created

Copy the signing secret into CLERK_WEBHOOK_SECRET.

7. Configure Stripe webhooks

In your Stripe dashboard → Webhooks → Add endpoint:

• URL: https://your-domain.com/api/webhooks/stripe
• Events: customer.subscription.updated, customer.subscription.deleted

Copy the signing secret into STRIPE_WEBHOOK_SECRET.

8. Start the dev server

pnpm dev

Open http://localhost:3000.

---

Using ReadmeDB as an agent

1. Sign up and create an API key

Go to your ReadmeDB instance → sign in → Dashboard → Generate key. Copy the rdb_... key.

2. Add to your agent's MCP config

{
  "mcpServers": {
    "readmedb": {
      "url": "https://your-domain.com/api/mcp",
      "headers": {
        "Authorization": "Bearer rdb_your_key_here"
      }
    }
  }
}

Claude Code: add to ~/.claude/settings.json under mcpServers
Cursor: add to .cursor/mcp.json in your project
Windsurf: add to ~/.codeium/windsurf/mcp_config.json
Codex: add to your codex.json config

3. Start using tools

At the start of each session, call get_namespace_summary for a quick orientation. Then use whatever tools you need:

Tool	When to use
get_namespace_summary	Session start — file count, storage, 5 recent files
read_files	Load multiple known files at once
read_file	Read a single file
write_file	Create or fully overwrite a file
patch_file	Change a specific substring without rewriting the whole file
append_to_file	Add entries to a log or list
search_files	Find files by keyword with snippet context
list_files	Browse all files
list_modified_since	What changed since your last session
move_file	Rename or reorganise (version history moves with it)
delete_file	Permanently remove a file and all its history
get_file_history	See past snapshots of a file
get_file_version	Read a specific old version
restore_version	Make an old version current again

---

Environment variables

Variable	Required	Description
DATABASE_URL	Yes	Postgres connection string, e.g. postgresql://user:pass@host/db
CLERK_SECRET_KEY	Yes	Clerk server-side secret (starts with sk_)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY	Yes	Clerk client-side key (starts with pk_)
CLERK_WEBHOOK_SECRET	Yes	Clerk webhook signing secret (starts with whsec_)
STRIPE_SECRET_KEY	Yes	Stripe secret key (starts with sk_test_ or sk_live_)
STRIPE_WEBHOOK_SECRET	Yes	Stripe webhook signing secret (starts with whsec_)
NEXT_PUBLIC_STRIPE_PRO_PRICE_ID	Yes	Stripe price ID for the Pro plan (starts with price_)

---

Development commands

pnpm dev                   # start dev server (localhost:3000)
pnpm build                 # production build
pnpm start                 # serve production build
pnpm lint                  # run Biome linter
pnpm format                # auto-format with Biome
pnpm drizzle-kit push      # push schema to DB (no migration files)
pnpm drizzle-kit generate  # generate migration SQL files

---

Deploying

The easiest path is Vercel + Neon:

1. Push to GitHub
2. Import the repo in Vercel
3. Add all environment variables in the Vercel project settings
4. Deploy — Vercel runs pnpm build automatically

Make sure your Clerk and Stripe webhook URLs point to your production domain.