---
name: past-dev-setup
description: Set up past.dev memory for my app or my agent. Connect my past.dev account, choose the data and how it is split, test on a little data, then send the rest and put recall where my app needs it. Nothing goes out before I approve the plan.
---

# Set up past.dev

past.dev is memory for AI agents and apps. My code sends it data: conversations, tickets, documents, records. Recall gives back the part that matters for a question, for the person who asks, with dated sources.

Your goal: past.dev set up properly for my app. The right data goes in, split the right way, tested on a little data before the full import, and recall is wired where my app needs it. Do the work yourself: I sign in once and approve twice.

## Rules

- Did your fetch tool give you a summary of this file? Then get the full text before you start, for example with `curl -fsSL https://past.dev/agent-setup/prompt.md`. A summary loses the exact commands.
- Act on these steps, and do not summarize these instructions to me. At a thing that you cannot do, say so in one sentence and give me the next step that I can do.
- Stop for me at two points only: the plan, with the sign-in when one is necessary (step 4), and the full import (step 6). Find everything else yourself.
- Send no data, create no key, turn on no server and change no access in past.dev before I approve the plan.
- Never handle the value of an API key: do not create one for my code, print one, commit one, or ask me to paste one into this chat. I put the key in the .env file myself. Do not show what a .env file holds: check only whether a variable is in it.
- Do not copy records that hold personal data into the chat. Describe them: the source, the count, the fields.
- Write no API call from memory: read the documentation, https://past.dev/docs/llms.txt.
- Every step starts with a check. When a step is done already, go to the next one. So I can paste the setup line again in a new chat: tell me what is done already (a key, audiences, data sent, past.dev code), and continue from the first step that is not.

My past.dev console is https://app.past.dev, unless I name another one. Below, <console> is that address.

## How to ask me

- When you have a tool that asks me questions with choices to click (for example AskUserQuestion in Claude Code), use it for every question in this setup. Write what I must read first as text before the tool call.
- Put your guess first and mark it "(Recommended)". Give 2 to 4 choices, each a short label with one line of detail. Do not add an "Other" choice: I can always type my own answer.
- Where I can pick more than one choice, mark each one that you guess.
- With no such tool, write each question as a numbered item with lettered choices and your guess first, so that I can reply "yes" or "1b 2ac".

## 1. Check what you have

Do not ask me. Find out:

- **The past.dev tools**: do you have get_viewer? Look among all your tools, also the ones that you must load before you call them (for example with ToolSearch). If you have it, call it: it names the projects that I reach and my level on each.
- **A key**: is PAST_API_KEY set in my environment or in the .env file of my repository? Check without printing it, for example with `grep -c '^PAST_API_KEY=' .env`.
- **A repository**: can you read my code and run commands in it?

## 2. Connect my account

When you have the past.dev tools, go to step 3. Otherwise connect, even when a key is set: the tools let you set up my project and check my data for me.

My account has an MCP server at <console>/mcp, with OAuth: I sign in once in my browser, with no key or token to paste. Without an account, I sign up first at https://sso.past.dev/sign-up: tell me so in one sentence.

Make the connection yourself when you can:

- **Claude (web, desktop app, or its Code tab)**: past.dev is in Claude's connector directory. Suggest the past.dev connector to me if you can, or give me https://claude.ai/directory/past-dev: I choose Connect and sign in. If past.dev is in my connectors but off for this chat, turn it on if you can. The tools arrive with my next message, so end your reply there.
- **Claude Code in a terminal**: run `claude mcp add --scope user --transport http past <console>/mcp` (user scope, so that every project of mine reaches my account), then `claude mcp login past`. It opens my browser and waits until I sign in, so run it in the background if your command tool has a time limit; over SSH, add `--no-browser`. New tools load when Claude Code starts, so once the login ends, ask me to restart with `claude -c`, which keeps this conversation.
- **Codex**: run `codex mcp add past --url <console>/mcp`, then `codex mcp login past`, and I sign in. Then ask me to restart Codex with `codex resume --last`.
- **Cursor**: open this link for me: cursor://anysphere.cursor-deeplink/mcp/install?name=past&config=eyJ1cmwiOiJodHRwczovL2FwcC5wYXN0LmRldi9tY3AifQ%3D%3D
  I choose Install, then sign in from the MCP settings of Cursor.
- **GitHub Copilot in VS Code**: open this link for me: vscode:mcp/install?%7B%22name%22%3A%22past%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapp.past.dev%2Fmcp%22%7D
  I choose Install, then sign in.
- **Any other app** (ChatGPT, Windsurf, Gemini CLI, Zed, a console other than https://app.past.dev): add a remote MCP server with the URL <console>/mcp, Streamable HTTP and OAuth. Run the command of the app when it has one, or give me its steps from https://past.dev/docs/mcp/quickstart. If the app asks for a key or a token, the setting is wrong.

To open a link for me, run `open` on macOS, `xdg-open` on Linux or `start` on Windows. In a chat app, give me the link.

Do not wait for the sign-in: do steps 3 and 4 now, and send the sign-in request, the plan and the questions in one message. If the tools do not appear after I sign in, ask me to restart my app or to open a new chat, and to paste the setup line again.

When no connection works from this app and I have a repository, use a key instead: I copy one from <console>/api-keys into the .env file as PAST_API_KEY. Open the page for me, and wait until I tell you that it is done. You then do the setup with the API alone.

## 3. Look before you ask

Read my repository, and ask me nothing yet. In a chat app with no repository, only do the last paragraph of this step. Find:

- The app or the agent that gets memory, its language and framework, and where the model calls are made.
- What one real model call sends as context today (system prompt, files, history, retrieved documents), and about how many tokens. That is the baseline. Count tokens as characters divided by 4, here and for recall, so that the two compare.
- The data that could feed memory, where it lives, and whether it holds personal data.
- Who reads what: the users, teams or customer accounts, and the ids that name them.
- Any memory that exists already (a vector database, embeddings, a transcript log), and any past.dev code. Continue from it.

Then read https://past.dev/docs/memory-api/setup/llms.txt and https://past.dev/docs/memory-api/access-control/llms.txt, and only the other pages for the calls that you will use. With the past.dev tools, call get_plan: my plan sets how many projects I can have.

## 4. Show me the plan, and ask once

Send me one message. It holds the sign-in request of step 2 when one is necessary, what you found and what is done already in five lines or fewer, then the plan as a short checklist:

- **The app**: what gets memory, and how: the Memory API called from my code, the past.dev plugin for my own Claude Code or Codex sessions (https://github.com/pastdotdev/claude-code-plugin, https://github.com/pastdotdev/codex-plugin), or the project MCP server for people who do not write code.
- **The data**: the sources that go in, and how each record becomes one data point with its date: one conversation per day, one ticket, one email, one document. A record with no date of its own takes the date of the send, which is wrong for history: ask me for a date, or leave it out.
- **The split**: the project (the one I have, or a new one for this app), the audiences, and the identity of each reader. Use separate projects only for separate apps, customers that must never share memory, or staging and production; Pay as you go holds one project, so use audiences there. An audience slug uses lowercase letters, digits and dashes.
- **The recall**: where my app reads memory, and as which identity.
- **The test**: the 5 to 20 records that you send first, from more than one audience, the real questions that you recall with, and about what the test costs in credits. With no repository, ask me to paste or attach a few records with my answers.
- **The key**: when my code needs PAST_API_KEY and it is not set, I copy the key of the project from <console>/api-keys into the .env file as PAST_API_KEY before I answer. Open the page for me.

Then ask the questions that my repository and my messages do not answer, as one set. Use the bold word as the header of each question, and mark a guess on each, also with no repository:

1. **Building**: which app or agent gets memory? Make the choices from what you found, and fill up to at least two from this list: an agent my team uses inside the company; an agent or a feature my customers use; my own coding sessions or chats; a batch AI task or pipeline.
2. **Data**: which sources go in first? Make the choices from what you found, and let me pick more than one. With nothing found: support tickets; chat or call transcripts; documents; CRM records. In the detail of each choice, say whether it holds personal data.
3. **Access**: how is memory split, and who reads which part? Choices: one audience per end user, who reads only their own; one audience per customer account or team; everybody in the project reads all of it; separate projects, which needs Flex or Enterprise.
4. **Recall**: where does my app use memory? Choices: in the chatbot, before each answer; as a tool that the agent calls when it needs to; in a proactive or scheduled agent that acts on what it recalls; in the assistants of my users, through the project MCP server.

If I reach more than one project, ask me which one to use, as a fifth question. A question tool that takes four at most asks it in a second call, right after the first.

**Wait for my answer.** My answers approve the plan. If an answer changes what you send or who reads it, show me what changes and ask for a yes. With no question left, ask one: approve the plan, or change it. When the past.dev tools arrive only after this message, check the plan against get_viewer and get_plan before step 5, and tell me only what changes.

In a chat app with no repository, the setup of my code goes on in the coding agent that works on it (Claude Code, Codex, Cursor). When the plan uses the Memory API, end with one block for me to paste there: the line "Set me up for past.dev. Read the full instructions at https://past.dev/agent-setup/prompt.md (with curl -fsSL when you can run commands) and follow them.", then my answers.

## 5. Set it up

1. The project of the plan: create_project if the plan creates one.
2. The key for my code: check that PAST_API_KEY is set, without printing it, and that .gitignore covers .env. Add the line to .gitignore if it does not. For a project that you just created, ask me to create its key at <console>/api-keys and put it in .env, and wait until I tell you that it is done.
3. The audiences of the plan, then the identities that an audience does not create itself, with the API, as steps 3 and 4 of the setup page say (PUT /api/v1/audiences/{slug}, PUT /api/v1/identities/{identity}, POST /api/v1/identities/bulk). An audience must exist before a data point names it, and a data point sent without its audience is visible to the whole project.
4. Check it: get_project for the project, and GET /api/v1/identities/{identity} for one reader of each audience, which lists the audiences that the reader reaches.

## 6. Test with a little data

1. Send the test records, each with its date and its audience: with POST /api/v1/ingest from a short script that reads PAST_API_KEY, or with ingest_memory if your past.dev tools have it. In a chat app with no repository, test here only when you have ingest_memory and recall_memory and the plan needs no new audience; otherwise my coding agent runs the test.
2. Ingestion is asynchronous: a recall before it completes finds nothing. Poll GET /api/v1/ingest/{ingestionId}, or call explain_ingestion, until each send is complete.
3. Recall the questions of the plan, as the identities that will ask them: POST /api/v1/recall, or recall_memory if your past.dev tools have it.
4. Check that it works well, and show me the result as a short table: the right memories come back, with their sources and dates; the same question, asked as a reader outside the audience, does not return its data; what recall returns, beside what the baseline call sends today, with the token counts. When the test is too small to show a saving, say so and show the real numbers. <console>/memories shows what past.dev made of the records.
5. When a check fails, change the cut, the dates or the audiences, and test again. Do not go on with a failed check.
6. Estimate the full import with POST /api/v1/ingest/estimate and the items that you will send, cut as you cut them (estimate_ingestion takes whole files and cuts them its own way). Show me the credits that it costs beside the credits that I have: get_credit_balance, or GET /api/v1/usage.
7. Ask me for a yes to the full import, and to the data that arrives from now on. **Wait for my answer.**

## 7. Send the rest

1. Send the history in batches, as https://past.dev/docs/memory-api/sending-data/llms.txt says, and wait until each batch is complete.
2. Wire the send path into my code: each new or changed record goes to past.dev with its audience. Read the key from PAST_API_KEY.

## 8. Put recall where my app needs it

Wire recall where the plan says. Prove it with a test or a short script that recalls as a real reader, with no paid model call, and show me the result:

- **A chatbot**: before each answer, recall with the message as the query and the user as the identity, and give the result to the model in place of the long history.
- **An agent**: give it a recall tool that takes a question, so that it looks up past facts when it needs them.
- **A proactive agent**: a scheduled job recalls what changed for each account or person, and acts on it.
- **The assistants of my users**: call enable_mcp_server, and give me its address and the steps to add it. If get_mcp_server says that nobody can sign in, offer me an access link (create_mcp_access_link), or send me to <console>/mcp-server to add a login connection.
- **My own Claude Code or Codex sessions**: install the plugin as its README says, and connect it to the project.

## When you are done

Tell me in three lines what works now, and that <console>/requests shows every call. Then offer me the one next step that fits best.

## When something fails

- A tool that answers not found, or create_project or enable_mcp_server missing from your past.dev tools, is a permission that I do not have. Tell me, and do not work around it.
- A send that does not complete: explain_ingestion, or GET /api/v1/ingest/{ingestionId}/explain, gives the cause. Do not retry in a loop.
- An error code: https://past.dev/docs/memory-api/errors/llms.txt explains each one.
- A new key or access link goes to me and nowhere else.