Pastepile
Durable, versioned memory for AI assistants. Remote memory needs a Pastepile subscription.
Open source Repository Open in the app JSON README (API)
About
Durable, versioned memory for AI assistants. Remote memory needs a Pastepile subscription.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- com.pastepile
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.9.0
- Added
- 2026-08-29 03:01:18
- Updated
- 2026-09-13 03:10:10
- Origin id
com.pastepile/mcp
README
# @pastepile/mcp
The **persistent memory layer for AI coding assistants.** A
[Model Context Protocol](https://modelcontextprotocol.io) server that lets
Claude, Cursor, Windsurf, and any MCP client save knowledge to
[Pastepile](https://pastepile.com) and retrieve it later by a stable URL.
Your assistant saves its own work as it goes, and can find it again next
session. Zero dependencies, so it adds no supply-chain surface of its own.
## The one tool that matters
`pastepile_remember` takes a **session** name the assistant chooses and can
always reproduce from what it can see: a repository path, a conversation id, a
branch name. The first call under a session creates the memory. Every call
after updates that same memory and keeps the previous content as a version. A
call whose content has not changed does nothing at all.
That last property is the whole design. Because an unchanged save is free and
silent, the assistant can save after every meaningful step without being asked
and without filling your account with near-identical copies. And because the
session is a name rather than a slug, nothing has to survive a compacted
conversation.
## Tools
### Memory (session-keyed; a subscription is required from September 8, 2026)
| Tool | What it does |
| -------------------- | -------------------------------------------------------------------- |
| `pastepile_remember` | Create or update a memory by session. Deduplicates. No slug to keep. |
| `pastepile_recall` | Search your own memory by words, tags, and kind. |
| `pastepile_timeline` | One memory's version history plus related memories. |
| `pastepile_restore` | Put an earlier version back without losing the current one. |
**Trial memory is being retired on September 8, 2026.** Until then, without
`PASTEPILE_API_KEY` the memory tools work out of the box: each memory is an
unlisted paste that expires one month after its last save (a save in its final
week renews it for another month, so memory in active use stays alive), the
session index lives on this device (`~/.pastepile`, or `PASTEPILE_STATE_DIR`),
and restore reaches back one save.
The index is local; the memory is not. Each one is a real paste on Pastepile's
servers, and because every save pushed the expiry out, an actively used trial
memory never expired. That is hosted storage with no subscription behind it,
and from September 8, 2026 saving memory without a key answers
`payment_required`.
**Nothing is deleted and reads are unaffected.** Every memory already saved
stays readable at its link, before and after that date, so it can be exported
or saved again under a key. Pasting in the browser at pastepile.com stays free
with no key and no account. What needs a subscription is writing to Pastepile
programmatically, which covers this server and plain curl alike.
**The tools keep working without a key: local demonstration mode.** From that
date, with no `PASTEPILE_API_KEY` set, `pastepile_remember`, `pastepile_recall`,
`pastepile_timeline` and `pastepile_restore` run against a store on your own
machine so you can see the workflow before paying. It is deliberately small and
deliberately not cloud storage:
| | Local demonstration | With a Pro API key |
| --------------------- | ---------------------- | ------------------------------- |
| Where it lives | This machine, one file | Pastepile, your key's namespace |
| Has a link | No | Yes, a stable URL |
| Another machine | No | Yes |
| How many | 3 | No fixed limit |
| Size each | 16 KB | Up to your plan's ceiling |
| Survives this machine | No | Yes |
Every response says so and carries `storage: "local_demo"`, so an assistant
cannot report a demonstration memory as saved. Clear one with
`pastepile_forget` and its `session` name. This is a demonstration, not a free
subscription trial: there is no free trial.
An API key, issued with [Pastepile Pro](https://www.pastepile.com/pricing),
makes memory permanent, searchable from any machine, with full version
history.
### Pastes (slug-keyed, no key required)
| Tool | What it does |
| ---------------------- | ------------------------------------------------------------------- |
| `pastepile_save` | Save text/code and get back a stable `url`, `slug`, and `edit_key`. |
| `pastepile_checkpoint` | Update one paste and preserve its previous revision in history. |
| `pastepile_get` | Retrieve a paste by slug or full Pastepile URL. |
| `pastepile_search` | Search your private memory (with an API key) or the public corpus. |
| `pastepile_list` | List your saved pastes (with an API key) or the public feed. |
| `pastepile_forget` | Permanently delete a paste that your API key saved. |
Sharing a snippet by URL is a different job from keeping memory, so both
families exist. Reach for the memory tools unless you specifically want a
link to hand someone.
**Private memory:** when `PASTEPILE_API_KEY` is set, every paste your
assistant saves is associated with that key, and `pastepile_search` /
`pastepile_list` default to that private namespace (including unlisted
pastes), searching titles, filenames, and contents. Pass `scope: "public"`
to reach the public corpus instead. Without a key, both tools cover the
public corpus only, and nothing is associated. One key can never see
another key's pastes.
**Conversation checkpoints:** `pastepile_checkpoint` updates one paste at the
same stable URL and preserves the content it replaces in Pastepile's existing
version history. With an API key configured, the same key that saved a paste
can checkpoint it in a later session without the one-time `edit_key`. The
server instructions tell assistants to checkpoint after significant context
growth, code generation, debugging or architecture work, and before likely
context compaction, so saving does not depend on you remembering.
**Forgetting:** `pastepile_forget` deletes a paste that the same API key
created, from its slug alone. That matters because the `edit_key` is shown
exactly once, in a transcript that gets compacted away, so it is not the
credential a later session still has. A paste saved with no key, or with a
different key, is untouched by yours; pass its `edit_key` explicitly to delete
that one. Deletion is permanent, and the tool is annotated as destructive so
clients can confirm before running it.
Saved pastes default to **unlisted** (retrievable by URL, never shown in public
listings or search) and **never expire**, so stored knowledge persists. Both are
adjustable per call. End-to-end encrypted, password-protected, and
burn-after-read pastes cannot be read back through the API and are out of scope
for `pastepile_get`.
## Requirements
Node.js 18 or newer (the server uses the built-in global `fetch`). No install
step, no build.
## Configuration
The server is configured entirely by environment variables:
| Variable | Default | Purpose |
| --------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PASTEPILE_API` | `https://www.pastepile.com` | Base URL. Point at a self-hosted or staging deploy. |
| `PASTEPILE_API_KEY` | (none) | Pastepile API key, sent as `X-API-Key`. Makes memory permanent and portable across machines (without it, memory runs as device-local trial memory) and raises rate limits. Keys are created at <https://www.pastepile.com/keys> and come with a Pastepile Pro subscription. Never logged. |
| `PASTEPILE_AUTOSAVE` | `conservative` | How hard the server asks the assistant to save without being told to. `off` removes every unprompted trigger and leaves the tools available on request. `conservative` saves at moments where losing the work would cost real time. `eager` prefers saving to not saving. |
| `PASTEPILE_STATE_DIR` | `~/.pastepile` | Where trial memory keeps its device-local session index (a private file holding sessions and their edit keys). Unused once an API key is configured. |
## Setup
### Claude Code
```bash
claude mcp add pastepile -- npx -y @pastepile/mcp
```
Or add it to `.mcp.json` in your project (shared with your team):
```json
{
"mcpServers": {
"pastepile": {
"command": "npx",
"args": ["-y", "@pastepile/mcp"],
"env": { "PASTEPILE_API_KEY": "your-key-optional" }
}
}
}
```
### Cursor
Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
```json
{
"mcpServers": {
"pastepile": {
"command": "npx",
"args": ["-y", "@pastepile/mcp"],
"env": { "PASTEPILE_API_KEY": "your-key-optional" }
}
}
}
```
### Windsurf
Add to `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"pastepile": {
"command": "npx",
"args": ["-y", "@pastepile/mcp"],
"env": { "PASTEPILE_API_KEY": "your-key-optional" }
}
}
}
```
### Any other MCP client
The server speaks JSON-RPC 2.0 over stdio. Run it with:
```bash
npx -y @pastepile/mcp
```
Point your client at that command. The `env` block is optional; without it the
server talks to `https://pastepile.com` anonymously.
### Remote endpoint (no local process)
Clients that speak MCP's Streamable HTTP transport can skip the local process
and use the hosted endpoint instead. It runs the same dispatcher as this
package, so the tools are identical:
```
https://www.pastepile.com/api/mcp
```
Tool calls on the remote endpoint require an API key
(https://pastepile.com/keys, issued with Pastepile Pro), sent as
`Authorization: Bearer <key>` or `X-API-Key: <key>`. Full setup:
https://pastepile.com/docs/mcp/remote
## Example
Once configured, ask your assistant to use it in plain language:
> "Save this migration plan to Pastepile so we can pick it up tomorrow."
> "Pull up the paste at pastepile.com/p/abc123 and continue where we left off."
> "Checkpoint our current decisions before the context window fills up."
> "Forget that draft you saved earlier, it is wrong."
The assistant calls `pastepile_save`, `pastepile_checkpoint`, `pastepile_get`,
or `pastepile_forget` for you and keeps the returned slug in context.
## How it works
This server is a thin wrapper over the public Pastepile REST API
(`/api/public/pastes`). With an API key it holds no state of its own: every
tool call is one HTTPS request, tagged with a `pastepile-mcp/<version>`
User-Agent. Trial memory (no key) keeps exactly one small local file, the
session index under `PASTEPILE_STATE_DIR`, because without a key there is no
server-side namespace to attach sessions to. Your content goes straight to
Pastepile under the same privacy model as the web app and CLI.
For end-to-end encryption, create the paste in the web app or CLI (the
encryption key never leaves the client) and share the resulting link.
## License
MIT. Part of the [Pastepile](https://pastepile.com) project.