# ReadmeDB

> Persistent markdown file storage for AI agents, delivered as a hosted MCP server and REST API.

ReadmeDB is a markdown object store for AI agents. Add one MCP config entry and your agents
can read, write, search, patch, and version `.md` files — persistently across Claude Desktop,
Cursor, Windsurf, Codex, and any MCP-compatible host.

Each API key is an isolated file namespace. Files are stored in Postgres and versioned
automatically (up to 10 snapshots per file). Full-text search is powered by Postgres `tsvector`.

## Quick Start

1. Sign up at https://app.readmedb.com/sign-up
2. Generate an API key from https://app.readmedb.com/dashboard
3. Add to your MCP client config:

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

4. Call `get_namespace_summary` to orient yourself, then start reading and writing files.

## MCP Endpoint

- URL: `https://app.readmedb.com/api/mcp`
- Protocol: Model Context Protocol over HTTP (POST + GET, JSON-RPC 2.0)
- Auth: `Authorization: Bearer <api-key>`
- OAuth: `/.well-known/oauth-authorization-server` for Claude.ai auto-discovery

## MCP Tools (16 total)

| Tool | Purpose |
|------|---------|
| `get_namespace_summary` | Session-start orientation: file count, storage, plan, recent files, recommended action |
| `list_files` | List all files ordered by recency; limit/offset pagination; optional preview_bytes |
| `read_file` | Read one file; start_line/end_line for partial reads |
| `read_files` | Bulk read up to 10 files in one call |
| `write_file` | Create or overwrite a file (max 1 MB); if_not_exists flag |
| `patch_file` | Literal find/replace; occurrence_index for targeting specific match |
| `append_to_file` | Append text to the end of a file (creates if absent) |
| `delete_file` | Permanently delete a file and all version history |
| `move_file` | Atomic rename with version history migration |
| `search_files` | Full-text search returning name, sizeBytes, updatedAt, snippet |
| `fetch_docs_for_task` | Search + ranked reads + truncation in one orchestrated call |
| `list_modified_since` | Files changed after a Unix timestamp (ms) |
| `get_file_history` | Version IDs, timestamps, and sizes for a file |
| `get_file_version` | Read a specific historical version by ID |
| `diff_versions` | Unified diff between two versions (or version vs. current) |
| `restore_version` | Make a historical version current (quota-checked, versioned) |

## MCP Resources

- `readmedb://policy/naming` — naming rules, size limits, plan quotas, error codes, recommended workflows

## MCP Prompts

- `onboard_session` — step-by-step session startup instructions

## REST API

Base URL: `https://app.readmedb.com/api/v1`
Auth: `Authorization: Bearer <api-key>`
Full spec: https://app.readmedb.com/api/openapi

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/files` | List all files in namespace |
| POST | `/api/v1/files` | Create a file `{name, content}` |
| GET | `/api/v1/files/{name}` | Read a file |
| PUT | `/api/v1/files/{name}` | Overwrite a file `{content}` |
| DELETE | `/api/v1/files/{name}` | Delete a file |

## CLI

Install: `curl -fsSL https://app.readmedb.com/install.sh | sh`
Docs: https://app.readmedb.com/cli

```
rdb login               # save API key
rdb ls                  # list files
rdb cat <file>          # read file
rdb write <file>        # write file (arg/--file/stdin)
rdb edit <file>         # open in $EDITOR
rdb search <query>      # full-text search
rdb history <file>      # version list
rdb diff <file> <id>    # diff version vs. current
rdb restore <file> <id> # restore version
```

## File Naming Rules

- Allowed: letters, digits, hyphen `-`, underscore `_`, dot `.`, space ` `
- Forbidden: `/` `\` `..` sequences, null bytes
- Max 200 characters
- Examples: `CLAUDE.md`, `memory-2024.md`, `notes v2.txt`

## Error Codes

| Code | Meaning |
|------|---------|
| `INVALID_NAME` | File name violates naming rules |
| `FILE_NOT_FOUND` | No file with that name exists |
| `FILE_EXISTS` | Destination already exists (move without overwrite) |
| `FILE_TOO_LARGE` | Content exceeds 1 MB per-file limit |
| `QUOTA_FILE_LIMIT` | File count limit reached |
| `QUOTA_STORAGE_LIMIT` | Storage byte limit reached |
| `PATCH_NOT_FOUND` | Literal search string not found in file |
| `PATCH_OUT_OF_RANGE` | occurrence_index beyond match count |
| `VERSION_NOT_FOUND` | Version ID not in history |
| `TOO_MANY_FILES` | read_files called with >10 names |
| `RATE_LIMIT_EXCEEDED` | Too many requests — retry after 60s |

## Plans

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

## Recommended Agent Workflow

1. Call `get_namespace_summary` at session start — follow `recommended_action`.
2. Few files (≤10): `list_files` then `read_files` (bulk, up to 10).
3. Many files: `search_files` or `fetch_docs_for_task` with keywords.
4. Large files: `read_file` with `start_line`/`end_line`.
5. Targeted edits: `patch_file` instead of full read + rewrite.
6. Before destructive ops: verify the name with `list_files` first.

## Key Links

- Home: https://app.readmedb.com
- Dashboard: https://app.readmedb.com/dashboard
- CLI docs: https://app.readmedb.com/cli
- Sign up: https://app.readmedb.com/sign-up
- MCP endpoint: https://app.readmedb.com/api/mcp
- OpenAPI spec: https://app.readmedb.com/api/openapi
- AI plugin manifest: https://app.readmedb.com/.well-known/ai-plugin.json
- llms-full.txt: https://app.readmedb.com/llms-full.txt