Memory

"The agent remembers you" is not an architecture. Pimsy separates memory by purpose, lifetime and retrieval strategy, and exposes every store for inspection and deletion.

Memory stores#

Lifecycle#

1. 1

   Write

   Candidate memories are proposed during a run with a type, scope and source step. Nothing is written from raw model output without a source reference.

2. 2

   Score

   Candidates are scored on durability, specificity and reuse likelihood. Low-scoring candidates expire with the run.

3. 3

   Retrieve

   Each step issues a scoped retrieval; results are ranked by semantic similarity, recency and prior usefulness.

4. 4

   Consolidate

   Repeated episodic observations are distilled into semantic memory; superseded entries are marked, not silently overwritten.

5. 5

   Expire

   Time-based and relevance-based expiry remove stale entries. Expiry is logged.

6. 6

   Control

   Users can list, search, edit, pin and delete any entry; deletion removes the entry and its derived consolidations.

Inspecting memory#

const results = await pimsy.memory.search({
  query: class="tok-str">"deployment conventions for the payments service",
  stores: [class="tok-str">"project", class="tok-str">"semantic"],
  limit: class="tok-num">10
});

for (const m of results) {
  console.log(m.store, m.score.toFixed(class="tok-num">2), m.text, class="tok-str">"←", m.sourceRunId);
}

await pimsy.memory.delete({ id: class="tok-str">"mem_2f91ab" });

Failure modes we design against#

• Stale confidence — an outdated fact retrieved as current. Mitigated by timestamps, supersession markers and expiry.
• Memory poisoning — untrusted content persuading the agent to store a false instruction. Mitigated by requiring a source step and excluding tool-returned content from preference writes.
• Retrieval drift — irrelevant entries crowding context. Mitigated by scoped retrieval and per-step budgets.