Perpetuity ยท first published 5 September 2026 # How it works Perpetuity is a memory for AI agents that sits between the agent and its model. Instead of re-sending the whole conversation on every turn, it sends a short frame of what is relevant right now, retrieved from everything the agent has ever seen. 94.0 LongMemEval-S, 500 questions 92.2 with 82M tokens in one memory 52% less spent over a 120-prompt coding session 1. [1. Base-URL proxy](https://www.neuraweave.ai/perpetuity/how-it-works#proxy) 2. [2. Rendered frame](https://www.neuraweave.ai/perpetuity/how-it-works#frame) 3. [3. Token-clock heat](https://www.neuraweave.ai/perpetuity/how-it-works#heat) 4. [4. Breadth-sized cap](https://www.neuraweave.ai/perpetuity/how-it-works#cap) 5. [5. Recall tools](https://www.neuraweave.ai/perpetuity/how-it-works#recall) 6. [6. Exact scan, pooled memory](https://www.neuraweave.ai/perpetuity/how-it-works#scale) 7. [7. Store guarantees](https://www.neuraweave.ai/perpetuity/how-it-works#store) Part 1 ## Base-URL proxy The harness changes one setting, its base URL, and every request then passes through Perpetuity. Agent harness Perpetuity 1. 1. works out whose conversation this is 2. 2. stores the new message 3. 3. retrieves what matters from everything stored 4. 4. renders it as the frame Model provider The reply streams back the same way, and Perpetuity stores it as well. Full description Perpetuity runs as a proxy at the path of the provider's chat API, so an agent harness adopts it by changing its base URL and nothing else. Every request that comes through gets the same treatment: we work out who is asking and which conversation they are in from the request headers, store the incoming message, retrieve what is relevant from everything that was stored before, render it into text and put it into the request, forward that to the real provider, stream the reply back to the harness, and store the reply as well. Which provider a request is meant for we read from the request itself, from the credential type and the shape of the model name, so one deployment can serve several providers behind one interface. A handful of per-request headers let a harness switch parts of the pipeline off for a single call. Part 2 ## Rendered frame The model sees the stored turns that matter now, quoted verbatim, instead of the whole transcript sent again. Harness request instructions + tools full history, re-sent live turn Model request instructions + tools the frame, verbatim live turn Schematic, not to scale. Everything else stays in memory, and the model can recall it. Full description The model never sees the conversation history as the harness sent it. What it sees instead is a frame made of past turns, quoted verbatim from the store, grouped by conversation with the current one last, labelled with names and times that are resolved when the frame is rendered, and closed by the live question. We then strip the history the harness sent. For a chat client the live question closes the frame as its last rendered turn. For a coding harness such as Claude Code, the live turn and the last few turns stay exactly as the harness sent them, and the frame leaves those turns out. Nothing gets summarized on the way in and nothing is thrown away, so the frame is what the model sees this turn, while the memory is everything it could see. The frame is rendered as alternating user and assistant messages, so the model reads it as a conversation rather than a quoted block. For benchmarks and probes there is also a mode that answers a question without remembering it, where the live question is appended after the frame instead of being captured. Part 3 ## Token-clock heat Memory warms when it is stored or used. It cools only as the agent works, so an idle agent forgets nothing. stored: born hotretrieved: reheatedretrieved againrender line Across: tokens the agent processes, not wall time. An idle agent forgets nothing. Schematic curve. Full description Each stored item carries a small activation state and nothing else about its past: the clock position of its last activation, the peak it reached then, and a decay constant that was fixed when it was created. From those three values we can compute how warm an item is at any later moment, so nothing ever has to be written to cool something down. The clock is not wall time. It advances only when the agent processes content, measured in tokens, which means an idle agent forgets nothing. Creating an item counts as an activation, so it is born hot in the same write that stores it, and retrieval reheats what it selects with a peak shaped by rank, adopting the new state only where it beats the item's current trajectory. The frame is simply whatever is still warm enough to render. Heat decides what the model sees but never enters the relevance score. Recency is not a rule we wrote anywhere. New items are simply hot. Part 4 ## Breadth-sized cap A narrow question gets a small frame and a broad one a larger frame. The live conversation is never cut. Narrow question, one clear match Broad question, matches across many topics - never trimmed (this turn, its retrieval, recent conversation) - budget (from the score spread) - ceiling Full description The frame has a token budget, but the budget is not a fixed number. We derive it per query from how the retrieval scores are spread: a question with one clear best match gets a small budget, and a question whose good matches are spread across many topics, which is what a broad question looks like, gets a larger one, up to a ceiling. The cap is enforced against the text as it is actually rendered, in two passes, and a mandatory set is never trimmed: the current turn, its own retrieval, and the most recent stretch of the conversation. When the cap removed something and the recall tools are on, the model is told how many items were left out and which tools reach them. The statistic that sets the budget only decides how much gets rendered, it never changes which item ranks above which. Part 5 ## Recall tools When the frame is not enough, the model can call its memory tools for more. - Search - Rest of this turn's retrieval - Co-occurrence - Category count - Fact chains - Dates Called mid-reply, run inside the proxy. A result never repeats what the model was already shown this turn. Full description Besides the frame it gets without asking, the model has a small set of memory tools it can call when the frame feels incomplete: search everything stored, see more of this turn's retrieval from below the cap, trace what came up together with a topic before, count every stored instance of a category, browse the chains of related facts it keeps, or look up when something happened. The tools run inside the proxy, in the middle of the streamed reply, and a call's result is appended to that turn's context on top of the frame. Each call only returns what the model has not been shown yet during the turn, so a search never repeats the frame. The loop is bounded, and on its last round the model has to answer. The instructions for the tools ride along with the request only when the tools do, so a harness that turns them off gets a prompt that never mentions them. Part 6 ## Exact scan, pooled memory Every stored item is read on every question, even with 500 users in one memory. 82M tokens in one memory, every item scanned on every question 500 users' histories held at once 92.2 on LongMemEval-S, retrieved from that one memory every stored item, a cheap score a shortlist, the full score the frame No approximate index between the question and the memory. Full description Candidates for the frame come from a scan over every stored item, with no approximate index between the question and the memory. A small memory is scanned straight from the store. A large or pooled one is held as one in-memory copy in the serving process and spread across worker threads with a deterministic merge. Before every scan that copy catches up by reading only what was stored since its last catch-up, which makes a cold process slower on its first request but never wrong. The same scan works over a memory pooled across many users at once. Everyone's items sit in one resident arena and score under one shared frequency statistic, while each asking user keeps their own conversation, heat and exclusions. The pooled score on the benchmarks page was measured exactly this way, with every question retrieved from one memory holding 500 users, and each asking user's own items given priority in the ranking. Past a certain size, a cheaper score over every item picks a shortlist first and the full score ranks the shortlist, so every item is still read on every query. The shortlist grows with the size of the memory. Part 7 ## Store guarantees Every message is stored in full, in one step, and never rewritten. One step A message, its retrieval row, its heat and its counts are written in one transaction. One writer each Every derived structure has exactly one writer. Swaps as data The retrieval dictionary ships as data and switches in one atomic flip. Full description A captured message becomes one or more immutable rows, each paired with exactly one retrieval row, and both are written together with the born-hot activation and the frequency counts in a single transaction, so either everything about a message is stored or nothing is. Every derived structure has one writer. Activation is only ever patched by retrieval, the chain graph and the binding log each have a single writer, and the decay constant is written once at birth and never again. The representation the retrieval rows use comes from a versioned dictionary that ships as data, and swapping it is a data operation rather than a code change: the new table is uploaded dark, every retrieval row is re-derived from the stored tokens while heat and novelty stay untouched, and the switch is one atomic flip. An integrity check recomputes the invariants on demand, and a user's memory can be purged as a unit. Other memory systems ## Comparison Most memory systems sit beside the agent's context, which still fills up. Perpetuity replaces the agent's context. No model runs when it writes or reads. We have measured it at 82M tokens of history. | Memory | Model / write | Model / read | Replaces context | | --- | --- | --- | --- | | LLM-extracted memories | a model call | usually an embedding call | no | | Lexical (files, full-text index) | none | none | no | | Dense vectors | an embedding call | an embedding call | no | | Perpetuity | none | none | yes | The numbers we measured on this architecture are on the [benchmarks page](https://www.neuraweave.ai/perpetuity/benchmarks). ## Perpetuity opens in early access. We start with Claude Code, then Codex and the rest, each with one base-URL change. Join now and you are first in line. We email you when your access is approved. This page as HTML: https://www.neuraweave.ai/perpetuity/how-it-works Perpetuity for agents (availability, and joining early access with the person's consent): https://www.neuraweave.ai/perpetuity/agents.md