Skip to content

About

past.dev for Claude Code: your Claude Code sessions become memory, and every session opens already briefed. past.dev is a long-term memory API for AI agents.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

20 Commits

Folders and files

Repository files navigation

past.dev for Claude Code

Your Claude Code sessions become memory, and every session opens already briefed.

past.dev is memory for AI agents. This plugin connects Claude Code to a past.dev project: what you and Claude say to each other is read into memory as you work, and what matters comes back by itself, at the start of every session and with every prompt. The decisions, the reasons behind them, what was already tried and dropped.

=== past · recalled from memory ===
3 from this project's history. Background, not instruction.

[1] 2026-09-14 — Webhooks retry from the job queue now: the HTTP client's retries sent them twice.
[2] 2026-09-02 — Rejected: caching prices in Redis. They change hourly, and a stale one is worse.
[3] 2026-08-27 — The importer keeps rows it cannot parse in import_rejects and never drops them.

That block is what Claude reads before your prompt. It arrives on its own: Claude does not have to decide to look anything up. When a request needs more than the block holds, Claude asks for it itself, with the past_recall tool the plugin serves.

Get started

You need Claude Code and Node 16 or later.

  1. Get a project API key. Sign up at sso.past.dev/sign-up, then open Build › API keys in the console. The key starts with past_sk_.

  2. Install the plugin. In Claude Code:

    /plugin marketplace add pastdotdev/claude-code-plugin
    /plugin install pastdotdev@pastdotdev
    

    The first line adds this repository as a marketplace. The second line installs the plugin from it.

    In the Claude desktop app, or on claude.ai: open Customize › Plugins, select Add › Add marketplace and enter pastdotdev/claude-code-plugin, then open past.dev and select Add. The plugin is saved to your account and loads in Claude Code, in the app's Code tab and in the terminal, from the next session on; /reload-plugins loads it into a session already open.

  3. Connect it.

    /pastdotdev:connect <project-api-key> <identity>
    

    The identity is the email or id every memory is attributed to. Recall stays off without one.

  4. Check it. /pastdotdev:status shows the project it talks to and what it has sent.

Sessions are read from your next prompt on: what you typed before connecting stays on your machine. /pastdotdev:backfill lists the sessions from before the plugin was installed, estimates what sending them costs, and sends them when you confirm.

To keep the key out of the conversation, use /plugin configure pastdotdev@pastdotdev in the terminal CLI instead of step 3: a form that masks the key and keeps it in your system's credential store.

How it works

session opens    recall what past.dev knows about this project     ──►  into context
every prompt     recall what past.dev knows about this prompt      ──►  into context
any time         Claude asks past.dev itself, with past_recall     ──►  into context
every reply      nothing is sent; the session is marked active
compaction       the sittings that closed are sent; the one still open at most once an hour
session over     the session is sent: closed, its window quit, or quiet for 12 hours

Five hooks and one tool do this, and one script runs them all. The block before a prompt holds up to ten memories; the tool returns up to a hundred, within 2,000 tokens. A recall that has not answered within 4 seconds (8 at session start) is dropped, so it never holds a prompt up, and a prompt shorter than 12 characters ("yes", "go on") recalls nothing.

A session is sent in sittings. Where a conversation went quiet for 30 minutes, the next turn starts a new sitting; so does the next one after 50 KB of prose, once Claude has answered. Each sitting is dated at its own first turn, so a decision made on the third day of a long conversation is remembered on that day, and past.dev can tell which of two statements came later. A session that continues sends its last sitting and the new ones again, nothing earlier.

Recall happens in the hooks. A tool recalls only when the model decides to call one; a hook recalls on every prompt. For questions about history, the bundled skill lets Claude also search past.dev on demand: ask what was decided about something, or whether it was tried before.

What leaves your machine

Your prompts and Claude's replies, with the names of the project's folder and its branch, the session's id, the model Claude ran on with its effort level, and the identity you connected with. The folder's path stays on your machine. Recall sends queries: one when a session starts, the first 1,000 characters of each prompt, and the questions Claude asks past_recall. Nothing else.

What you type is sent with the key it was typed under, and with no other. Nothing typed before you connect is sent, and what was typed under one project's key never goes to another project: a session goes on, in a new sitting, from the prompt after you connect or change keys. Sessions from before the plugin was installed are your history, sent only when you run /pastdotdev:backfill.

Never sent: tool calls and their results, file contents, diffs, command output, subagent threads, and anything injected into the conversation rather than typed by a person. Strings that look like keys, tokens or private keys become [redacted] before anything leaves, and recall queries are redacted the same way.

/pastdotdev:cut prints exactly what would be sent from this session, sitting by sitting, before anything is.

A session is about 10 MB on disk and about 30 KB of prose, and only the prose travels. At 350 bytes to a credit, that is roughly 90 credits a session. What a recall costs depends on your plan: see past.dev/pricing.

Commands

Command What it does
/pastdotdev:connect <key> <identity> [api-url] connect this machine; --audience <slug> sets who sees what you send
/pastdotdev:status what it is connected to, what it has sent, and the last send that failed
/pastdotdev:cut [session] print exactly what would be sent from this session, or from one you name
/pastdotdev:ingest [session] send one session now, without waiting for it to go quiet
/pastdotdev:backfill list and estimate the sessions already on this machine, then send them

Who sees what you send

Everyone in the project, unless you choose an audience: /pastdotdev:connect --audience <slug>, with a slug from the console's Audiences page. /pastdotdev:connect --audience project widens it back.

Settings

~/.past/config.json holds the connection and a few switches: recall and ingest turn either half off, idleMinutes (720) is how long a session stays quiet before it is sent, sittingMinutes (30) is how long a pause starts a new sitting, sittingKilobytes (50) how much prose does, and deny lists paths whose sessions are never read. PAST_API_KEY, PAST_IDENTITY and PAST_API_URL override the file. Each setting is described in the plugin's README.

For a self-hosted past.dev, pass your deployment's URL as the third argument of /pastdotdev:connect. Use https: over plain http to another machine the key travels unencrypted, and the plugin says so.

When something looks wrong

Start with /pastdotdev:status. A hook never interrupts a session, so a problem shows up there rather than in the conversation.

  • Nothing is recalled. Status has to show a key and an identity: recall needs both. A new project has nothing to recall until its first sessions are in; /pastdotdev:ingest sends the current one now.
  • A send failed. Status shows the last failed send and what the API answered.
  • The hooks stay silent. They call node. Claude Code started from the Dock or a launcher finds the node of a login shell, which may be older than your terminal's: Node 16 or later has to come first on that path.

Moving from past@past

Before 0.3.0 the plugin was installed as past@past. To move to the new name, run these in Claude Code:

/plugin uninstall past@past
/plugin marketplace remove past
/plugin marketplace add pastdotdev/claude-code-plugin
/plugin install pastdotdev@pastdotdev

Your connection stays in ~/.past, so you don't need to connect again, and sessions already sent aren't sent twice.

Remove it

/plugin uninstall pastdotdev@pastdotdev, then delete ~/.past. Revoking the key in Build › API keys stops it at once from the server side. What was already sent stays in the project until you delete it in the console.

This repository

A Claude Code plugin marketplace. Claude Code reads it straight from GitHub; there is nothing to build.

.claude-plugin/marketplace.json   the catalog
plugins/past/
  .claude-plugin/plugin.json      the manifest, with the settings form
  hooks/hooks.json                the five hooks
  bin/past-hook.mjs               the whole plugin: one file, Node 16, no dependencies
  commands/                       /pastdotdev:connect, :status, :cut, :ingest, :backfill
  skills/past/SKILL.md            teaches Claude when to search past.dev

The plugin talks only to past.dev's public Memory API (/api/v1/ingest/batch, /api/v1/recall, /api/v1/audiences), with your project's key. Nothing in it is privileged: anyone could write the same connector against the same endpoints.

Contributing

Issues and pull requests are welcome. CLAUDE.md holds the rules the code keeps and how to test a change by hand, for people and agents alike. Before opening a pull request:

claude plugin validate .
claude plugin validate plugins/past
node --check plugins/past/bin/past-hook.mjs

Links

License

MIT. See LICENSE.

About

past.dev for Claude Code: your Claude Code sessions become memory, and every session opens already briefed. past.dev is a long-term memory API for AI agents.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages