past dev for Dify

past dev is a memory API for AI agents. This plugin gives Dify apps three tools that call the past dev Memory API:

Tool	API call	What it does
Ingest	POST /api/v1/ingest	Sends one data point. past dev turns it into memory.
Recall	POST /api/v1/recall	Reads the memory for one identity, ranked for a query.
Delete data point	DELETE /api/v1/data-points/{sourceId}	Deletes one data point and the memory made from it.

You can use the tools in Workflow, Chatflow and Agent apps.

• Website: https://past.dev
• Quickstart: https://past.dev/docs/memory-api/quickstart
• API reference: https://past.dev/docs/memory-api/api-reference
• Source code: https://github.com/pastdotdev/dify-plugin

Before you start

You need a past dev project API key. The key starts with past_sk_.

1. Sign up at https://sso.past.dev/sign-up, or sign in at https://app.past.dev.
2. In the header, select the project. A key belongs to the project that the header shows.
3. Open API keys and create a key.

Each Ingest and each Recall spends credits on your past dev plan. Delete data point and the connection test spend no credits.

Set up the plugin

1. Install past dev from the Dify Marketplace.
2. In Dify, open Tools, find past dev and click To authorize.
3. In API key, paste your project API key.
4. Keep API host empty or at https://api.past.dev. Change it only if your company runs past dev in its own cloud. The host must use HTTPS.
5. Click Save.

Dify checks the key with GET /api/v1/audiences. This call spends no credits. If past dev refuses the key, Dify shows the error code.

Identity: the app builder sets it, not the model

past dev keeps memory per identity: the id of a person or a customer in your own user records. Recall requires an identity. Ingest creates an identity the first time that it sees it.

The model never chooses the identity. The identity is a tool setting (a form parameter), so only the app builder can set it. A model that could choose the identity could read the memory of another person. Each tool that uses an identity has two settings:

• Identity source
  • Identity field (the default): the tool uses the value in Identity.
  • Dify end-user ID: the tool uses the ID that Dify gives to the person who runs the app. Each end user then has a separate memory. This is the easy choice for an Agent app that many people use.
• Identity: the identity to use when the source is Identity field.
  • In a Workflow or a Chatflow, insert a variable, for example {{#sys.user_id#}} or a user ID from your start node.
  • In an Agent app, the value is fixed for all conversations. Use a fixed value only when the app serves one person or one customer.

Use the tools

Ingest

Setting	API field	Set by	Notes
Content	content	model or workflow	Required. Empty content is refused.
Label	label	model or workflow	Optional short title.
Occurred at	timestamp	model or workflow	Optional ISO 8601 date and time. Empty means now.
Identity source, Identity	identity	builder	See above. Optional for Ingest.
Audience	audience	builder	Optional audience slug. Empty or project means the whole project.
Source ID	id	builder	Optional stable id. Send the same id again to revise the data point.
Metadata	metadata	builder	Optional JSON, returned by Recall with the source.
Idempotency key	idempotencyKey	builder	Optional. Empty means the plugin makes one key for each run.

The tool returns a text message and the JSON response (sourceId, ingestionId, status).

Recall

Setting	API field	Set by	Notes
Query	query	model or workflow	Required. A question in natural language.
Occurred from, Occurred to	occurredFrom, occurredTo	model or workflow	Optional time window, ISO 8601.
Identity source, Identity	identity	builder	Required. See above.
Level	level	builder	Evidence budget: low (default), medium, high, extra-high. Your plan can lower it.
Max tokens	maxTokens	builder	An explicit budget in place of Level. Do not set both.
Limit	limit	builder	1 to 200 documents. Empty means 100.
Sort	sort	builder	relevance (default) or chronological.
Query timestamp	queryTimestamp	builder	Read memory as it was at this time. Empty means now.

The tool returns two outputs:

• text: the ranked documents, each with its date, its kind, its source IDs and the supporting excerpts. A model can read it directly.
• json: the full API response (asOf, usedEvidenceTokens, results).

Delete data point

Setting	API field	Notes
Source ID	sourceId	Required. The source ID as it was sent with Ingest.

The deletion runs in the background. The tool returns the deletion receipt (operationId, ids). A source ID that contains / is sent to POST /api/v1/data-points/delete, which deletes the same data point. Add this tool to an Agent app only if the model must be able to delete data points.

Errors

When past dev refuses a call, the tool fails with the HTTP status, the error code, the message and the request ID, for example past dev returned 402 out-of-credits: ... (request id ...). The message never contains your API key.

• The plugin does not retry a 400 or a 402 (out-of-credits).
• The plugin retries a 429 or a 503 at most two times. It obeys Retry-After when the wait is 10 seconds or less.
• Every call has a 60-second timeout.

Privacy

The plugin sends the tool inputs to past dev and nothing else. Read PRIVACY.md and the past dev privacy policy at https://past.dev/privacy.

Development

The plugin uses Python 3.12 and the Dify plugin SDK.

python3.12 -m venv .venv
.venv/bin/pip install -r requirements.txt pytest
.venv/bin/python -m pytest

The unit tests use a fake HTTP transport. They send nothing to past dev.

To try the plugin in your Dify workspace with remote debugging:

1. Copy .env.example to .env.
2. Fill in the debug host and key from Plugins > Debug in Dify.
3. Run .venv/bin/python -m main.

To check the plugin against the live API, put PAST_API_KEY (and optionally PAST_API_HOST) in your environment, or in a file that you give with --env-file, and run .venv/bin/python scripts/live_check.py. It makes one Ingest, one Recall and one Delete data point, so it spends a small number of credits.

To build the package, install the Dify plugin CLI and run this command from the folder above this one:

dify plugin package ./dify-plugin -o pastdotdev-0.1.0.difypkg

Support

Open an issue at https://github.com/pastdotdev/dify-plugin/issues or write to louis@past.dev.

License

MIT. See LICENSE.