# ReadmeDB — Full Reference for AI Agents

> This is the extended reference. The summary version is at https://app.readmedb.com/llms.txt

## What ReadmeDB Is

ReadmeDB is a persistent markdown file store for AI agents. It exposes 16 MCP tools, a REST
API, and a CLI (`rdb`). Agents authenticate with a Bearer API key. Each key is a fully isolated
namespace — files written with one key are not visible to other keys, even within the same account.

## Authentication

All API and MCP requests require:
```
Authorization: Bearer <api-key>
```

API keys look like `rdb_<random>`. Obtain them at https://app.readmedb.com/dashboard.

OAuth 2.0 (PKCE) is also supported for Claude.ai:
- Discovery: `GET https://app.readmedb.com/.well-known/oauth-authorization-server`
- Authorize: `GET https://app.readmedb.com/oauth/authorize`
- Token: `POST https://app.readmedb.com/oauth/token`

On 401, the response includes:
```
WWW-Authenticate: Bearer realm="readmedb", authorization_server="https://app.readmedb.com"
```

## MCP Server

- **Endpoint**: `https://app.readmedb.com/api/mcp`
- **Protocol**: MCP over HTTP (JSON-RPC 2.0, POST or GET)
- **Transport**: WebStandardStreamableHTTP

### MCP Config

```json
{
  "mcpServers": {
    "readmedb": {
      "url": "https://app.readmedb.com/api/mcp",
      "headers": { "Authorization": "Bearer rdb_your_key" }
    }
  }
}
```

### Tool: get_namespace_summary

No parameters. Call once at session start.

Returns:
```json
{
  "fileCount": 12,
  "maxFiles": 50,
  "filesUsedPct": 24,
  "storageBytes": 48392,
  "maxStorageBytes": 5242880,
  "storageUsedPct": 1,
  "storageMB": "0.05",
  "maxMB": "5",
  "plan": "free",
  "recentFiles": [
    { "name": "CLAUDE.md", "updatedAt": 1720000000000, "age": "2h ago" }
  ],
  "recommended_action": "Small namespace — call list_files for a full listing..."
}
```

Always follow `recommended_action`.

### Tool: list_files

Parameters:
- `limit` (integer 1–500, default 100) — max files to return
- `offset` (integer ≥0, default 0) — pagination offset
- `preview_bytes` (integer 1–2000, optional) — include first N bytes of each file inline

Returns:
```json
{
  "files": [
    { "name": "CLAUDE.md", "sizeBytes": 1234, "createdAt": 1720000000000, "updatedAt": 1720000000000, "preview": "# My notes..." }
  ],
  "limit": 100,
  "offset": 0,
  "returned": 1
}
```

### Tool: read_file

Parameters:
- `name` (string, required)
- `start_line` (integer ≥1, optional) — 1-indexed first line
- `end_line` (integer ≥1, optional) — 1-indexed last line (inclusive)

Returns:
```json
{
  "content": "# File content here",
  "sizeBytes": 1234,
  "updatedAt": 1720000000000,
  "totalLines": 42,
  "partial": true,
  "start_line": 1,
  "end_line": 20
}
```

### Tool: read_files

Parameters:
- `names` (string[], max 10, required)

Returns array — each element is either:
```json
{ "name": "file.md", "content": "...", "sizeBytes": 123, "updatedAt": 1720000000000 }
```
or on error:
```json
{ "name": "missing.md", "error": "FILE_NOT_FOUND: ..." }
```

### Tool: write_file

Parameters:
- `name` (string, required)
- `content` (string, required) — max 1 MB
- `if_not_exists` (boolean, default false) — no-op if file already exists

Returns:
```json
{ "ok": true, "name": "file.md", "sizeBytes": 1234, "storage": "0.05/5 MB", "files": "13/50" }
```

### Tool: patch_file

Parameters:
- `name` (string, required)
- `find` (string, required) — literal string to find (not regex)
- `replace` (string, required) — replacement string
- `all` (boolean, default false) — replace all occurrences
- `occurrence_index` (integer ≥0, optional) — 0-based index when `all` is false

Returns: `"OK: replaced N occurrence(s) in \"file.md\""`

Errors: `PATCH_NOT_FOUND`, `PATCH_OUT_OF_RANGE`

### Tool: append_to_file

Parameters:
- `name` (string, required)
- `content` (string, required)

Inserts a newline separator before appended content if file already exists.
Creates the file if it does not exist.

Returns:
```json
{ "ok": true, "name": "file.md", "sizeBytes": 2000, "lines": 30, "storage": "0.05/5 MB", "files": "12/50" }
```

### Tool: delete_file

Parameters:
- `name` (string, required)

Permanently deletes the file and all version history. Irreversible.

Returns: `"OK: file \"name\" deleted permanently"`

### Tool: move_file

Parameters:
- `from` (string, required)
- `to` (string, required)
- `overwrite` (boolean, default false)

Atomically renames, preserving all version history.

Returns: `"OK: moved \"from\" → \"to\""`

Errors: `FILE_NOT_FOUND`, `FILE_EXISTS`

### Tool: search_files

Parameters:
- `query` (string, required) — keywords (not regex, not glob)

Returns array:
```json
[{ "name": "notes.md", "sizeBytes": 1234, "updatedAt": 1720000000000, "snippet": "...matched context..." }]
```

Results are ordered by relevance. Use instead of list_files + read_files when looking for specific content.

### Tool: fetch_docs_for_task

Parameters:
- `query` (string, required) — keywords describing the task
- `paths_glob` (string, optional) — file name prefix filter (e.g. `"CLAUDE"` matches `"CLAUDE.md"`)
- `max_chars` (integer 100–100000, default 20000) — max total characters to return

Returns:
```json
{
  "query": "meeting notes",
  "totalChars": 4500,
  "truncated": false,
  "results": [
    { "name": "meetings.md", "sizeBytes": 4500, "content": "...", "truncated": false }
  ]
}
```

Use instead of a manual search + read loop.

### Tool: list_modified_since

Parameters:
- `since_ms` (number, required) — Unix timestamp in milliseconds

Returns: `[{ "name": "file.md", "updatedAt": 1720000000000 }]`

### Tool: get_file_history

Parameters:
- `name` (string, required)

Returns (newest first, up to 10 versions):
```json
[{ "id": 42, "savedAt": 1720000000000, "contentLength": 1234 }]
```

### Tool: get_file_version

Parameters:
- `name` (string, required)
- `version_id` (integer, required) — from `get_file_history`

Returns:
```json
{ "versionId": 42, "savedAt": 1720000000000, "sizeBytes": 1234, "content": "..." }
```

### Tool: diff_versions

Parameters:
- `name` (string, required)
- `version_id_a` (integer, required) — "before" snapshot
- `version_id_b` (integer, optional) — "after" snapshot; omit to diff against current
- `context_lines` (integer 0–20, default 3)

Returns:
```json
{
  "file": "notes.md",
  "a": "version 41 (savedAt: 2024-01-01T00:00:00.000Z)",
  "b": "current (updatedAt: 2024-01-02T00:00:00.000Z)",
  "diff": "--- a\n+++ b\n@@ -1,3 +1,3 @@\n ..."
}
```

### Tool: restore_version

Parameters:
- `name` (string, required)
- `version_id` (integer, required) — from `get_file_history`

Quota-checked. The restoration is saved as a new version (undoable).

Returns: `"OK: restored \"name\" to version 42 (saved as new version 43)"`

## MCP Resources

Fetch with `resources/read`:

### `readmedb://policy/naming`

Returns the full policy document including:
- Naming rules and forbidden characters
- Per-file size limit (1 MB)
- Plan quotas (free: 50 files / 5 MB, pro: 500 files / 100 MB)
- All error codes with meanings
- Recommended agent workflows
- Per-tool documentation links

### `readmedb://docs/{tool_name}`

Returns detailed per-tool documentation. Replace `{tool_name}` with any tool name, e.g.:
`readmedb://docs/patch_file`

## MCP Prompts

### `onboard_session`

Step-by-step session startup guide. Instructs the agent to:
1. Call `get_namespace_summary` and read `recommended_action`
2. Load files appropriately based on count
3. Use `read_files` (bulk) instead of `read_file` in a loop
4. Use `patch_file` for targeted edits

## REST API

Base URL: `https://app.readmedb.com/api/v1`
Auth: `Authorization: Bearer <api-key>`
Content-Type: `application/json`
OpenAPI spec: `https://app.readmedb.com/api/openapi`

### GET /api/v1/files

List all files in the namespace.

Response 200:
```json
{ "files": [{ "name": "file.md", "sizeBytes": 1234, "createdAt": 1720000000000, "updatedAt": 1720000000000 }] }
```

### POST /api/v1/files

Create a new file.

Request body:
```json
{ "name": "file.md", "content": "# Hello" }
```

Response 201: `{ "ok": true }`
Error 402: quota exceeded
Error 413: file too large (>1 MB)

### GET /api/v1/files/{name}

Read a file. URL-encode the file name.

Response 200:
```json
{ "name": "file.md", "content": "# Hello", "sizeBytes": 7, "createdAt": 1720000000000, "updatedAt": 1720000000000 }
```

Error 404: file not found

### PUT /api/v1/files/{name}

Overwrite a file.

Request body: `{ "content": "# Updated" }`

Response 200: `{ "ok": true }`

### DELETE /api/v1/files/{name}

Delete a file and all version history.

Response 200: `{ "ok": true }`
Error 404: file not found

## CLI

Install:
```sh
curl -fsSL https://app.readmedb.com/install.sh | sh
```
Or: `npm install -g rdb` / `pnpm add -g rdb` / `bun install -g rdb`

Full CLI docs: https://app.readmedb.com/cli

### All Commands

```
rdb login [--key rdb_xxx] [--url https://...]   # save API key
rdb logout                                        # clear config
rdb whoami [--json]                               # plan + quota + recent files

rdb ls [--limit N] [--offset N] [--since 2h] [--json]
rdb cat <file> [files...] [--lines 1:50] [--json]
rdb write <file> [content] [--file path] [-n] [--json]
rdb append <file> [content] [--file path] [--json]
rdb edit <file>
rdb rm <file> [-y] [--json]
rdb mv <from> <to> [--force] [--json]

rdb search <query> [--json]
rdb patch <file> <find> <replace> [--all] [--nth N] [--json]

rdb history <file> [--json]
rdb version <file> <id> [--json]
rdb diff <file> <id-a> [id-b] [-C N] [--json]
rdb restore <file> <id> [-y] [--json]
```

Config: `~/.config/rdb/config.json`
Env vars: `READMEDB_API_KEY`, `READMEDB_URL`, `EDITOR`

## Rate Limits

| Plan | Limit |
|------|-------|
| Free | 60 requests/minute |
| Pro | 600 requests/minute |

On limit hit: HTTP 429, `Retry-After: 60` header.
Error code: `RATE_LIMIT_EXCEEDED`

## Plans & Pricing

| Plan | Files | Storage | Rate limit | Price |
|------|-------|---------|------------|-------|
| Free | 50 | 5 MB | 60 req/min | £0 |
| Pro | 500 | 100 MB | 600 req/min | £5/mo |

Upgrade at https://app.readmedb.com/dashboard

## All Links

- Home: https://app.readmedb.com
- Sign up: https://app.readmedb.com/sign-up
- Dashboard: https://app.readmedb.com/dashboard
- CLI docs: https://app.readmedb.com/cli
- MCP endpoint: https://app.readmedb.com/api/mcp
- REST base: https://app.readmedb.com/api/v1
- OpenAPI spec: https://app.readmedb.com/api/openapi
- AI plugin manifest: https://app.readmedb.com/.well-known/ai-plugin.json
- OAuth discovery: https://app.readmedb.com/.well-known/oauth-authorization-server
- llms.txt: https://app.readmedb.com/llms.txt
- llms-full.txt: https://app.readmedb.com/llms-full.txt
- Install script: https://app.readmedb.com/install.sh